Skip to content

Commit ec8ca75

Browse files
virgofxvirgofx
authored
feat: enhance wiki generation with new constants and clean directory (#90)
- Added quality gate badge to README for better visibility. - Introduced additional constants for wiki title replacements to ensure slashes and hyphens are displayed correctly. - Implemented `removeDirectoryContents` in file-utils to clear the directory before generating wiki content, ensuring 100% of the files are present. - Refactored wiki.ts: 1. Split wiki generation and commit/push into distinct functions. 2. Removed unnecessary wiki_subdirectory (e.g., generated) folder. 3. Ensured comprehensive generation of the wiki files. Fixes #80
1 parent 56c354e commit ec8ca75

File tree

5 files changed

+285
-76
lines changed

5 files changed

+285
-76
lines changed

‎README.md‎

Lines changed: 20 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -8,11 +8,13 @@ documentation.</b></sup>
88
![CI](https://github.com/techpivot/terraform-module-releaser/actions/workflows/ci.yml/badge.svg?event=pull_request)
99
[![Lint](https://github.com/techpivot/terraform-module-releaser/actions/workflows/lint.yml/badge.svg)][3]
1010
[![CodeQL](https://github.com/techpivot/terraform-module-releaser/actions/workflows/codeql-analysis.yml/badge.svg)][4]
11+
[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=techpivot_terraform-module-releaser&metric=alert_status)][5]
1112

1213
[1]: https://github.com/techpivot/terraform-module-releaser/releases/latest
1314
[2]: https://github.com/marketplace/actions/terraform-module-releaser
1415
[3]: https://github.com/techpivot/terraform-module-releaser/actions/workflows/lint.yml
1516
[4]: https://github.com/techpivot/terraform-module-releaser/actions/workflows/codeql-analysis.yml
17+
[5]: https://sonarcloud.io/summary/new_code?id=techpivot_terraform-module-releaser
1618

1719
Simplify the management of Terraform modules in your monorepo with this **GitHub Action**, designed to automate
1820
module-specific versioning and releases. By streamlining the Terraform module release process, this action allows you to
@@ -115,6 +117,11 @@ jobs:
115117
uses: techpivot/terraform-module-releaser@v1
116118
```
117119
120+
This configuration provides an out-of-the-box solution that should work for most projects, as the defaults are
121+
reasonably configured.
122+
123+
If you need to customize additional parameters, please refer to [Input Parameters](#input-parameters) section below.
124+
118125
## Permissions
119126
120127
Before executing the GitHub Actions workflow, ensure that you have the necessary permissions set for accessing pull
@@ -161,19 +168,19 @@ resources.
161168
While the out-of-the-box defaults are suitable for most use cases, you can further customize the action's behavior by
162169
configuring the following optional input parameters as needed.
163170

164-
| Input | Description | Default |
165-
| -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- |
166-
| `major-keywords` | Keywords in commit messages that indicate a major release | `major change,breaking change` |
167-
| `minor-keywords` | Keywords in commit messages that indicate a minor release | `feat,feature` |
168-
| `patch-keywords` | Keywords in commit messages that indicate a patch release | `fix,chore,docs` |
169-
| `default-first-tag` | Specifies the default tag version | `v1.0.0` |
170-
| `terraform-docs-version` | Specifies the terraform-docs version used to generate documentation for the wiki | `v0.19.0` |
171-
| `delete-legacy-tags` | Specifies a boolean that determines whether tags and releases from Terraform modules that have been deleted should be automatically removed | `true` |
172-
| `disable-wiki` | Whether to disable wiki generation for Terraform modules | `false` |
173-
| `wiki-sidebar-changelog-max` | An integer that specifies how many changelog entries are displayed in the sidebar per module | `5` |
174-
| `disable-branding` | Controls whether a small branding link to the action's repository is added to PR comments. Recommended to leave enabled to support OSS. | `false` |
175-
| `module-change-exclude-patterns` | A comma-separated list of file patterns to exclude from triggering version changes in Terraform modules. Patterns follow glob syntax (e.g., ".gitignore,_.md") and are relative to each Terraform module directory. Files matching these patterns will not affect version changes. **WARNING**: Avoid excluding '_.tf' files, as they are essential for module detection and versioning processes. | `".gitignore,*.md,*.tftest.hcl,tests/**"` |
176-
| `module-asset-exclude-patterns` | A comma-separated list of file patterns to exclude when bundling a Terraform module for tag/release. Patterns follow glob syntax (e.g., "tests/\*\*") and are relative to each Terraform module directory. Files matching these patterns will be excluded from the bundled output. | `".gitignore,*.md,*.tftest.hcl,tests/**"` |
171+
| Input | Description | Default |
172+
| -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------- |
173+
| `major-keywords` | Keywords in commit messages that indicate a major release | `major change,breaking change` |
174+
| `minor-keywords` | Keywords in commit messages that indicate a minor release | `feat,feature` |
175+
| `patch-keywords` | Keywords in commit messages that indicate a patch release | `fix,chore,docs` |
176+
| `default-first-tag` | Specifies the default tag version | `v1.0.0` |
177+
| `terraform-docs-version` | Specifies the terraform-docs version used to generate documentation for the wiki | `v0.19.0` |
178+
| `delete-legacy-tags` | Specifies a boolean that determines whether tags and releases from Terraform modules that have been deleted should be automatically removed | `true` |
179+
| `disable-wiki` | Whether to disable wiki generation for Terraform modules | `false` |
180+
| `wiki-sidebar-changelog-max` | An integer that specifies how many changelog entries are displayed in the sidebar per module | `5` |
181+
| `disable-branding` | Controls whether a small branding link to the action's repository is added to PR comments. Recommended to leave enabled to support OSS. | `false` |
182+
| `module-change-exclude-patterns` | A comma-separated list of file patterns to exclude from triggering version changes in Terraform modules. Patterns follow glob syntax (e.g., `.gitignore,_.md`) and are relative to each Terraform module directory. Files matching these patterns will not affect version changes. **WARNING**: Avoid excluding '`_.tf`' files, as they are essential for module detection and versioning processes. | `.gitignore, *.md, *.tftest.hcl, tests/**` |
183+
| `module-asset-exclude-patterns` | A comma-separated list of file patterns to exclude when bundling a Terraform module for tag/release. Patterns follow glob syntax (e.g., `tests/\*\*`) and are relative to each Terraform module directory. Files matching these patterns will be excluded from the bundled output. | `".gitignore, *.md, *.tftest.hcl, tests/**"` |
177184

178185
### Example Usage with Inputs
179186

‎src/constants.ts‎

Lines changed: 41 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -4,8 +4,45 @@ export const GITHUB_ACTIONS_BOT_EMAIL = '41898282+github-actions[bot]@users.nore
44
export const PR_SUMMARY_MARKER = '<!-- techpivot/terraform-module-releaser — pr-summary-marker -->';
55
export const PR_RELEASE_MARKER = '<!-- techpivot/terraform-module-releaser — release-marker -->';
66

7-
export const BRANDING_COMMENT =
8-
'<h4 align="center"><sub align="middle">Powered by <img src="https://raw.githubusercontent.com/techpivot/terraform-module-releaser/refs/heads/main/assets/github-mark-top-padding.png" height="16" width="12" align="top" /> <a href="https://github.com/techpivot/terraform-module-releaser">techpivot/terraform-module-releaser</a></sub></h4>';
7+
export const PROJECT_URL = 'https://github.com/techpivot/terraform-module-releaser';
98

10-
export const BRANDING_WIKI =
11-
'<h4 align="center">Powered by <img src="https://raw.githubusercontent.com/techpivot/terraform-module-releaser/refs/heads/main/assets/github-mark-12x14.png" height="14" width="12" align="top" /> <a href="https://github.com/techpivot/terraform-module-releaser">techpivot/terraform-module-releaser</a></h4>';
9+
export const BRANDING_COMMENT = `<h4 align="center"><sub align="middle">Powered by <img src="https://raw.githubusercontent.com/techpivot/terraform-module-releaser/refs/heads/main/assets/github-mark-top-padding.png" height="16" width="12" align="top" /> <a href="${PROJECT_URL}">techpivot/terraform-module-releaser</a></sub></h4>`;
10+
11+
export const BRANDING_WIKI = `<h4 align="center">Powered by <img src="https://raw.githubusercontent.com/techpivot/terraform-module-releaser/refs/heads/main/assets/github-mark-12x14.png" height="14" width="12" align="top" /> <a href="${PROJECT_URL}">techpivot/terraform-module-releaser</a></h4>`;
12+
13+
/**
14+
* WIKI_TITLE_REPLACEMENTS - This object maps specific characters in wiki titles to visually
15+
* similar Unicode alternatives to handle GitHub Wiki limitations related to directory structure,
16+
* uniqueness, and consistent character visibility.
17+
*
18+
* ### GitHub Wiki Issues Addressed:
19+
*
20+
* - **Slash (`/`) Handling**:
21+
* GitHub Wiki does not interpret forward slashes (`/`) as part of a directory structure in titles.
22+
* When a title includes a slash, GitHub Wiki only recognizes the last segment (basename) for
23+
* navigation, leading to potential conflicts if multiple pages share the same basename but
24+
* reside in different contexts. By replacing `/` with a visually similar division slash (`∕`),
25+
* this mapping helps preserve the intended path within the title, avoiding structure-related conflicts.
26+
*
27+
* - **Hyphen (`-`) Behavior**:
28+
* If GitHub encounters a hyphen (`-`) in a title, it will automatically replace it with a figure dash (`‒`).
29+
* Additionally, GitHub may move the file to the root directory, overriding any intended subdirectory placement.
30+
* This behavior can lead to confusion and disorganization within the wiki. To maintain consistent naming
31+
* conventions and avoid unintended movements of files, the hyphen is replaced with a figure dash in titles
32+
* to ensure proper display and organization.
33+
*
34+
* ### Key-Value Pairs:
35+
* - Each **key** represents an original character in the title that may be problematic in GitHub Wiki.
36+
* - Each **value** is a Unicode replacement character chosen to visually resemble the original while
37+
* avoiding structural or display conflicts.
38+
*
39+
* ### Current Mappings:
40+
* - `'/'` → `'∕'` (U+2215 Division Slash): Replaces forward slashes in titles to prevent directory
41+
* conflicts.
42+
* - `'-'` → `'‒'` (U+2012 Figure Dash): Replaces hyphen with figure dash for better display and to avoid
43+
* GitHub's auto-movement to the root directory.
44+
*/
45+
export const WIKI_TITLE_REPLACEMENTS: { [key: string]: string } = {
46+
'/': '∕', // Replace forward slash with a visually similar division slash (U+2215)
47+
'-': '‒', // Replace hyphen with figure dash (U+2012) for better display and to avoid GitHub's auto-movement
48+
};

‎src/file-util.ts‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -52,3 +52,53 @@ export function copyModuleContents(directory: string, tmpDir: string, baseDirect
5252
}
5353
}
5454
}
55+
56+
/**
57+
* Removes all contents of a specified directory except for specified items to preserve.
58+
*
59+
* @param directory - The path of the directory to clear.
60+
* @param exceptions - An array of filenames or directory names to preserve within the directory.
61+
*
62+
* This function removes all files and subdirectories within the specified directory while
63+
* retaining any items listed in the `exceptions` array. The names in `exceptions` should be
64+
* relative to the `directory` (e.g., `['.git', 'README.md']`), referring to items within the
65+
* directory you want to keep.
66+
*
67+
* ### Example Usage:
68+
*
69+
* Suppose you have a directory structure:
70+
* ```
71+
* /example-directory/
72+
* ├── .git/
73+
* ├── config.json
74+
* ├── temp/
75+
* └── README.md
76+
* ```
77+
*
78+
* Using `removeDirectoryContents('/example-directory', ['.git', 'README.md'])` will:
79+
* - Remove `config.json` and the `temp` folder.
80+
* - Preserve the `.git` directory and `README.md` file within `/example-directory`.
81+
*
82+
* **Note:**
83+
* - Items in `exceptions` are matched only by their names relative to the given `directory`.
84+
* - If the `.git` directory or `README.md` file were in a nested subdirectory within `/example-directory`,
85+
* you would need to adjust the `exceptions` parameter accordingly to reflect the correct relative path.
86+
*
87+
* @example
88+
* removeDirectoryContents('/home/user/project', ['.git', 'important-file.txt']);
89+
* // This would remove all contents inside `/home/user/project`, except for the `.git` directory
90+
* // and the `important-file.txt` file.
91+
*/
92+
export function removeDirectoryContents(directory: string, exceptions: string[] = []): void {
93+
if (fs.existsSync(directory)) {
94+
for (const item of fs.readdirSync(directory)) {
95+
const itemPath = path.join(directory, item);
96+
97+
// Skip removal for items listed in the exceptions array
98+
if (!exceptions.includes(item)) {
99+
fs.rmSync(itemPath, { recursive: true, force: true });
100+
}
101+
}
102+
info(`Removed contents of directory [${directory}], preserving items: ${exceptions.join(', ')}`);
103+
}
104+
}

0 commit comments

Comments
 (0)