@eserstack/codebase 0.0.0-bootstrap.0 → 5.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (175) hide show
  1. package/README.md +302 -0
  2. package/dist/changelog-gen.d.ts +105 -0
  3. package/dist/changelog-gen.js +498 -0
  4. package/dist/changelog-text.d.ts +39 -0
  5. package/dist/changelog-text.js +82 -0
  6. package/dist/cli-support.d.ts +140 -0
  7. package/dist/cli-support.js +244 -0
  8. package/dist/cli-system/app-opts.d.ts +15 -0
  9. package/dist/cli-system/app-opts.js +13 -0
  10. package/dist/cli-system/app.d.ts +29 -0
  11. package/dist/cli-system/app.js +12 -0
  12. package/dist/cli-system/handlers/completions-setup.d.ts +14 -0
  13. package/dist/cli-system/handlers/completions-setup.js +139 -0
  14. package/dist/cli-system/handlers/completions.d.ts +3 -0
  15. package/dist/cli-system/handlers/completions.js +79 -0
  16. package/dist/cli-system/handlers/doctor.d.ts +8 -0
  17. package/dist/cli-system/handlers/doctor.js +146 -0
  18. package/dist/cli-system/handlers/info.d.ts +3 -0
  19. package/dist/cli-system/handlers/info.js +69 -0
  20. package/dist/cli-system/handlers/install.d.ts +8 -0
  21. package/dist/cli-system/handlers/install.js +137 -0
  22. package/dist/cli-system/handlers/mod.d.ts +12 -0
  23. package/dist/cli-system/handlers/mod.js +13 -0
  24. package/dist/cli-system/handlers/uninstall.d.ts +3 -0
  25. package/dist/cli-system/handlers/uninstall.js +60 -0
  26. package/dist/cli-system/handlers/update.d.ts +76 -0
  27. package/dist/cli-system/handlers/update.js +310 -0
  28. package/dist/cli-system/handlers/version-check.d.ts +16 -0
  29. package/dist/cli-system/handlers/version-check.js +176 -0
  30. package/dist/cli-system/handlers/version.d.ts +3 -0
  31. package/dist/cli-system/handlers/version.js +45 -0
  32. package/dist/cli-system/mod.d.ts +19 -0
  33. package/dist/cli-system/mod.js +52 -0
  34. package/dist/commitmsg.d.ts +28 -0
  35. package/dist/commitmsg.js +232 -0
  36. package/dist/directive-analysis.d.ts +75 -0
  37. package/dist/directive-analysis.js +223 -0
  38. package/dist/ffi-client.d.ts +11 -0
  39. package/dist/ffi-client.js +12 -0
  40. package/dist/file-tool.d.ts +96 -0
  41. package/dist/file-tool.js +274 -0
  42. package/dist/file-tools-shared.d.ts +81 -0
  43. package/dist/file-tools-shared.js +276 -0
  44. package/dist/gh-contributors.d.ts +89 -0
  45. package/dist/gh-contributors.js +205 -0
  46. package/dist/gh.d.ts +3 -0
  47. package/dist/gh.js +64 -0
  48. package/dist/git-listing.d.ts +27 -0
  49. package/dist/git-listing.js +69 -0
  50. package/dist/git.d.ts +172 -0
  51. package/dist/git.js +277 -0
  52. package/dist/install.d.ts +34 -0
  53. package/dist/install.js +421 -0
  54. package/dist/main.d.ts +22 -0
  55. package/dist/main.js +14 -0
  56. package/dist/mod.d.ts +25 -0
  57. package/dist/mod.js +8 -0
  58. package/dist/module.d.ts +10 -0
  59. package/dist/module.js +221 -0
  60. package/dist/native-functions.d.ts +1088 -0
  61. package/dist/native-functions.js +2 -0
  62. package/dist/npm-externals.d.ts +27 -0
  63. package/dist/npm-externals.js +34 -0
  64. package/dist/npm-workspace-specifiers.d.ts +6 -0
  65. package/dist/npm-workspace-specifiers.js +45 -0
  66. package/dist/package/loader.d.ts +34 -0
  67. package/dist/package/loader.js +203 -0
  68. package/dist/package/mod.d.ts +36 -0
  69. package/dist/package/mod.js +5 -0
  70. package/dist/package/types.d.ts +142 -0
  71. package/dist/package/types.js +32 -0
  72. package/dist/package/workspace.d.ts +33 -0
  73. package/dist/package/workspace.js +158 -0
  74. package/dist/package/writer.d.ts +52 -0
  75. package/dist/package/writer.js +278 -0
  76. package/dist/package.json +275 -0
  77. package/dist/release-notes.d.ts +90 -0
  78. package/dist/release-notes.js +236 -0
  79. package/dist/release-tag.d.ts +46 -0
  80. package/dist/release-tag.js +95 -0
  81. package/dist/release.d.ts +145 -0
  82. package/dist/release.js +584 -0
  83. package/dist/source-mask.d.ts +3 -0
  84. package/dist/source-mask.js +185 -0
  85. package/dist/validate-bom.d.ts +5 -0
  86. package/dist/validate-bom.js +43 -0
  87. package/dist/validate-case-conflict.d.ts +5 -0
  88. package/dist/validate-case-conflict.js +43 -0
  89. package/dist/validate-circular-deps.d.ts +11 -0
  90. package/dist/validate-circular-deps.js +53 -0
  91. package/dist/validate-code-conventions.d.ts +22 -0
  92. package/dist/validate-code-conventions.js +166 -0
  93. package/dist/validate-commit-msg.d.ts +50 -0
  94. package/dist/validate-commit-msg.js +182 -0
  95. package/dist/validate-docs.d.ts +20 -0
  96. package/dist/validate-docs.js +78 -0
  97. package/dist/validate-eof.d.ts +5 -0
  98. package/dist/validate-eof.js +61 -0
  99. package/dist/validate-error-coverage.d.ts +28 -0
  100. package/dist/validate-error-coverage.js +93 -0
  101. package/dist/validate-export-names.d.ts +17 -0
  102. package/dist/validate-export-names.js +56 -0
  103. package/dist/validate-filenames.d.ts +5 -0
  104. package/dist/validate-filenames.js +151 -0
  105. package/dist/validate-json.d.ts +5 -0
  106. package/dist/validate-json.js +71 -0
  107. package/dist/validate-large-files.d.ts +5 -0
  108. package/dist/validate-large-files.js +41 -0
  109. package/dist/validate-laroux-boundaries.d.ts +19 -0
  110. package/dist/validate-laroux-boundaries.js +59 -0
  111. package/dist/validate-licenses.d.ts +5 -0
  112. package/dist/validate-licenses.js +137 -0
  113. package/dist/validate-line-endings.d.ts +5 -0
  114. package/dist/validate-line-endings.js +47 -0
  115. package/dist/validate-merge-conflict.d.ts +5 -0
  116. package/dist/validate-merge-conflict.js +46 -0
  117. package/dist/validate-mod-exports.d.ts +16 -0
  118. package/dist/validate-mod-exports.js +56 -0
  119. package/dist/validate-naming-and-todos.d.ts +5 -0
  120. package/dist/validate-naming-and-todos.js +70 -0
  121. package/dist/validate-runtime-js-apis.d.ts +5 -0
  122. package/dist/validate-runtime-js-apis.js +78 -0
  123. package/dist/validate-secrets.d.ts +5 -0
  124. package/dist/validate-secrets.js +82 -0
  125. package/dist/validate-self-imports.d.ts +5 -0
  126. package/dist/validate-self-imports.js +78 -0
  127. package/dist/validate-server-loc.d.ts +32 -0
  128. package/dist/validate-server-loc.js +94 -0
  129. package/dist/validate-shebangs.d.ts +5 -0
  130. package/dist/validate-shebangs.js +33 -0
  131. package/dist/validate-stream.d.ts +25 -0
  132. package/dist/validate-stream.js +62 -0
  133. package/dist/validate-submodules.d.ts +5 -0
  134. package/dist/validate-submodules.js +43 -0
  135. package/dist/validate-symlinks.d.ts +5 -0
  136. package/dist/validate-symlinks.js +46 -0
  137. package/dist/validate-toml.d.ts +5 -0
  138. package/dist/validate-toml.js +40 -0
  139. package/dist/validate-trailing-whitespace.d.ts +5 -0
  140. package/dist/validate-trailing-whitespace.js +49 -0
  141. package/dist/validate-yaml.d.ts +5 -0
  142. package/dist/validate-yaml.js +40 -0
  143. package/dist/validation/config.d.ts +17 -0
  144. package/dist/validation/config.js +30 -0
  145. package/dist/validation/mod.d.ts +71 -0
  146. package/dist/validation/mod.js +479 -0
  147. package/dist/validation/registry.d.ts +57 -0
  148. package/dist/validation/registry.js +256 -0
  149. package/dist/validation/types.d.ts +101 -0
  150. package/dist/validation/types.js +2 -0
  151. package/dist/validation/validators/circular-deps.d.ts +7 -0
  152. package/dist/validation/validators/circular-deps.js +31 -0
  153. package/dist/validation/validators/docs.d.ts +7 -0
  154. package/dist/validation/validators/docs.js +38 -0
  155. package/dist/validation/validators/error-coverage.d.ts +2 -0
  156. package/dist/validation/validators/error-coverage.js +46 -0
  157. package/dist/validation/validators/export-names.d.ts +7 -0
  158. package/dist/validation/validators/export-names.js +31 -0
  159. package/dist/validation/validators/laroux-boundaries.d.ts +2 -0
  160. package/dist/validation/validators/laroux-boundaries.js +29 -0
  161. package/dist/validation/validators/mod-exports.d.ts +7 -0
  162. package/dist/validation/validators/mod-exports.js +32 -0
  163. package/dist/validation/validators/mod.d.ts +11 -0
  164. package/dist/validation/validators/mod.js +12 -0
  165. package/dist/validation/validators/server-loc.d.ts +2 -0
  166. package/dist/validation/validators/server-loc.js +48 -0
  167. package/dist/versions.d.ts +166 -0
  168. package/dist/versions.js +349 -0
  169. package/dist/violation-baseline.d.ts +58 -0
  170. package/dist/violation-baseline.js +144 -0
  171. package/dist/walk-stream.d.ts +24 -0
  172. package/dist/walk-stream.js +55 -0
  173. package/dist/workspace-discovery.d.ts +60 -0
  174. package/dist/workspace-discovery.js +130 -0
  175. package/package.json +225 -1
package/README.md ADDED
@@ -0,0 +1,302 @@
1
+ # 🔧 [@eserstack/codebase](./)
2
+
3
+ > **Note:** JSR is frozen at 4.5.x. From 5.0.0, `@eserstack/codebase` is
4
+ > published on npm under the same name (`pnpm add @eserstack/codebase`); the JSR
5
+ > versions stay available but get no updates.
6
+
7
+ > **eserstack Tool** — [eser/stack on GitHub](https://github.com/eser/stack)
8
+ > **Install:** `pnpm add @eserstack/codebase`
9
+
10
+ `@eserstack/codebase` provides validation tools and project management utilities
11
+ for maintaining code quality. It includes the validation tools listed under
12
+ Available Tools, git hook management, release tooling, and a workflow
13
+ integration layer.
14
+
15
+ ## 🚀 Quick Start
16
+
17
+ ### Install git hooks
18
+
19
+ ```bash
20
+ # Install hooks from .eser/manifest.yml into .git/hooks/
21
+ npx eser codebase install
22
+
23
+ # Show installed hook status
24
+ npx eser codebase status
25
+
26
+ # Remove managed hooks
27
+ npx eser codebase uninstall
28
+ ```
29
+
30
+ ### Run individual tools
31
+
32
+ ```bash
33
+ # Check JSON syntax
34
+ npx eser codebase validate-json
35
+
36
+ # Fix missing trailing newlines
37
+ npx eser codebase validate-eof --fix
38
+
39
+ # Skip paths that match a regular expression; repeat --exclude for more
40
+ npx eser codebase validate-trailing-whitespace --exclude docs/api/ --exclude etc/temp/
41
+
42
+ # Validate commit message format
43
+ npx eser codebase validate-commit-msg --message "feat(core): add feature"
44
+ ```
45
+
46
+ ### Cut a release
47
+
48
+ ```bash
49
+ # Preview: prints old -> new version and whether a changelog entry is due
50
+ npx eser codebase release patch --dry-run
51
+
52
+ # Bump VERSION + every package.json, write the CHANGELOG section, commit
53
+ # "chore(codebase): release v<version>", push, then push the v<version> tag
54
+ npx eser codebase release patch
55
+ ```
56
+
57
+ The tag push is the trigger — CI reacts to `v*.*.*`, never to the commit, and
58
+ never creates tags itself (a tag pushed by a workflow's own `GITHUB_TOKEN`
59
+ dispatches nothing). `rerelease` re-fires the run by recreating the tag at HEAD;
60
+ `unrelease` removes the tag and the GitHub Release. Neither is safe once JSR or
61
+ npm has accepted the version — cut a new patch instead.
62
+
63
+ ## 🛠 Available Tools
64
+
65
+ ### Setup
66
+
67
+ | Command | Description |
68
+ | ----------- | ------------------------------------------- |
69
+ | `install` | Install git hooks from `.eser/manifest.yml` |
70
+ | `uninstall` | Remove managed git hooks |
71
+ | `status` | Show git hook installation status |
72
+
73
+ ### Release
74
+
75
+ | Command | Description |
76
+ | --------------- | -------------------------------------------------------- |
77
+ | `release` | Bump, changelog, commit, push, then push the trigger tag |
78
+ | `rerelease` | Delete and recreate the current version tag at HEAD |
79
+ | `unrelease` | Delete the current version tag and its GitHub Release |
80
+ | `versions` | Bump version across all workspace packages |
81
+ | `changelog-gen` | Generate CHANGELOG entry from commits |
82
+
83
+ ### AI
84
+
85
+ | Command | Description |
86
+ | ----------- | --------------------------------------- |
87
+ | `commitmsg` | Generate a commit message from the diff |
88
+
89
+ ### GitHub
90
+
91
+ | Command | Description |
92
+ | ------------------ | ------------------------------------------------------- |
93
+ | `gh contributors` | Update contributor list in README.md |
94
+ | `gh release-notes` | Sync CHANGELOG to GitHub Releases, a new one as a draft |
95
+ | `gh release-tag` | Create and push the release tag (the release trigger) |
96
+
97
+ ### Validation
98
+
99
+ | Command | Description |
100
+ | ------------------------------ | ---------------------------------------------- |
101
+ | `validate-eof` | Ensure files end with newline |
102
+ | `validate-trailing-whitespace` | Remove trailing whitespace |
103
+ | `validate-bom` | Remove UTF-8 byte order markers |
104
+ | `validate-line-endings` | Normalize line endings to LF |
105
+ | `validate-large-files` | Detect files exceeding size limit |
106
+ | `validate-case-conflict` | Detect case-conflicting filenames |
107
+ | `validate-merge-conflict` | Detect merge conflict markers |
108
+ | `validate-json` | Validate JSON syntax |
109
+ | `validate-toml` | Validate TOML syntax |
110
+ | `validate-yaml` | Validate YAML syntax |
111
+ | `validate-symlinks` | Detect broken symlinks |
112
+ | `validate-shebangs` | Validate shebang consistency |
113
+ | `validate-secrets` | Detect credentials and private keys |
114
+ | `validate-filenames` | Enforce filename conventions |
115
+ | `validate-submodules` | Detect git submodules |
116
+ | `validate-commit-msg` | Validate conventional commit format |
117
+ | `validate-docs` | Validate JSDoc documentation |
118
+ | `validate-circular-deps` | Detect circular dependencies |
119
+ | `validate-export-names` | Validate export naming conventions |
120
+ | `validate-licenses` | Validate license headers |
121
+ | `validate-mod-exports` | Detect modules no package entry point reaches |
122
+ | `validate-server-loc` | Fail when a non-test file exceeds a line cap |
123
+ | `validate-error-coverage` | Check error structs for required fields |
124
+ | `validate-self-imports` | Detect a package importing its own name |
125
+ | `validate-runtime-js-apis` | Detect runtime globals outside `runtime` |
126
+ | `validate-code-conventions` | Enforce namespace imports, `??`, no `export *` |
127
+ | `validate-laroux-boundaries` | Enforce the laroux package import rules |
128
+
129
+ Run any tool with `--help` for options:
130
+
131
+ ```bash
132
+ npx eser codebase validate-filenames --help
133
+ ```
134
+
135
+ ## 📋 Configuration (.eser/manifest.yml)
136
+
137
+ Tools are configured through `.eser/manifest.yml` at the project root. Each tool
138
+ receives its options from the workflow step configuration:
139
+
140
+ ```yaml
141
+ stack:
142
+ - javascript
143
+ - golang
144
+
145
+ workflows:
146
+ - id: default
147
+ on: [precommit, prepush]
148
+ steps:
149
+ # Validation tools with options
150
+ - validate-json:
151
+ exclude:
152
+ - "tsconfig.json"
153
+ - validate-filenames:
154
+ rules:
155
+ - directory: "apps/services/"
156
+ convention: "snake_case"
157
+ - directory: "*"
158
+ convention: "kebab-case"
159
+ exclude:
160
+ - "Makefile"
161
+ - "README.md"
162
+ - validate-secrets:
163
+ allowMissingCredentials: true
164
+ - validate-commit-msg:
165
+ forceScope: true
166
+ allowAsterisk: true
167
+ allowMultipleScopes: true
168
+ types: [ci, chore, docs, feat, fix, perf, refactor, revert, test]
169
+
170
+ # Shell commands for external tools
171
+ - shell:
172
+ name: formatter
173
+ command: oxfmt --check
174
+ fixCommand: oxfmt
175
+ - shell:
176
+ name: go-tests
177
+ command: "go test -race ./..."
178
+ workingDirectory: ./apps/services/
179
+ timeout: 300
180
+ ```
181
+
182
+ ### Baselines
183
+
184
+ `validate-code-conventions` applies its rules to new code while existing code
185
+ is migrated. It records the current violations per file in
186
+ `.eser/baselines/code-conventions.json` (the `baseline` step option points
187
+ elsewhere), and a file fails only when it has more violations than its baseline
188
+ allows. After fixing violations, shrink the baseline:
189
+
190
+ ```bash
191
+ npx eser codebase validate-code-conventions --write-baseline
192
+ ```
193
+
194
+ ## 🔌 API Usage
195
+
196
+ The package root (`@eserstack/codebase`) is the CLI entry point. The library API
197
+ lives under `@eserstack/codebase/mod`:
198
+
199
+ ```typescript
200
+ import * as codebase from "@eserstack/codebase/mod";
201
+
202
+ // Git operations
203
+ const commits = await codebase.getCommitsBetween("v1.0.0", "HEAD");
204
+ const branch = await codebase.getCurrentBranch();
205
+
206
+ // Workspace discovery
207
+ const packages = await codebase.discoverPackages(".");
208
+ ```
209
+
210
+ ```typescript
211
+ import * as validation from "@eserstack/codebase/validation";
212
+
213
+ // Run every validator that applies to the stack in .eser/manifest.yml
214
+ const report = await validation.validate({ root: "." });
215
+
216
+ // Get all registered tools as workflow-compatible objects
217
+ const tools = validation.getWorkflowTools();
218
+
219
+ // Run a specific validator programmatically
220
+ const validator = validation.getValidator("validate-json");
221
+ if (validator !== null) {
222
+ const result = await validator.validate({ root: "." });
223
+ }
224
+ ```
225
+
226
+ ### The shared `system` command tree
227
+
228
+ `cli-system/` owns the operational commands every shipped binary carries —
229
+ `install`, `uninstall`, `update`, `completions`, `version`, `doctor`, `info` —
230
+ built once and parameterised by a `CliApp` so `eser`, `noskills` and `laroux`
231
+ each get a tree describing themselves.
232
+
233
+ ```typescript
234
+ import * as cliSupport from "@eserstack/codebase/cli-support";
235
+ // The binary's own command module and package manifest.
236
+ import * as module from "./module.ts";
237
+ import config from "./package.json" with { type: "json" };
238
+
239
+ const app = cliSupport.attachStandardCommands(
240
+ module.moduleDef.toCommand("noskills", config.version),
241
+ );
242
+ ```
243
+
244
+ It attaches to a binary's ROOT command, never to a Module. That is deliberate:
245
+ `eser` mounts the very same module object the standalone `noskills` binary
246
+ re-roots, so a layer living on the module would appear in both — and
247
+ `eser noskills version` would exist, implying a submodule has a version of its
248
+ own.
249
+
250
+ ## Upgrading from 4.x
251
+
252
+ These changes since 4.5.2 need a change in code, commands or files that use this
253
+ package. The [changelog](https://github.com/eser/stack/blob/main/CHANGELOG.md)
254
+ lists the changes in every package.
255
+
256
+ - `versions()` rejects with `VersionWriteError` (with `targetVersion` and
257
+ `failures`) when a `package.json` could not be written, and
258
+ does not write `VERSION`. It used to resolve and report those packages as
259
+ updated. Catch it, fix the listed files, then rerun with the explicit target:
260
+
261
+ ```bash
262
+ # Before: a failed write still reported success
263
+ eser codebase versions minor
264
+ # After: fix the files in error.failures, then pass error.targetVersion
265
+ eser codebase versions target_version
266
+ ```
267
+
268
+ - Validator help, `gh --help`, the `--write-baseline` result line of
269
+ `validate-code-conventions`, and the output of
270
+ `validate-docs`, `validate-mod-exports`, `validate-export-names`,
271
+ `validate-circular-deps`, `validate-commit-msg`
272
+ and the standalone `commitmsg` entry go through the shared CLI context. When
273
+ stdout is not a TTY, that output is plain text on stderr instead of stdout.
274
+ Capture both streams: `eser codebase validate-docs > report.txt` becomes
275
+ `eser codebase validate-docs > report.txt 2>&1`.
276
+ - For every file-tool validator, an empty `--exclude` value (a trailing
277
+ `--exclude` or `--exclude=`) fails with exit code 1; it used to match every
278
+ path, so nothing was checked. Repeated `--exclude` flags all apply, where only
279
+ the last one did. Pass real patterns and drop extra flags you relied on being
280
+ ignored.
281
+ - `validate-runtime-js-apis` reports every reference to a runtime global other
282
+ than Node's in code (through `globalThis`, an alias or a `typeof` check
283
+ included), and members of Node's global `process`, in test files too;
284
+ only `standards/cross-runtime/` is skipped on its own. Text in comments and
285
+ string literals does not count. The check runs in Go and needs the native
286
+ library. Its message is `direct <runtime> API usage: X; use Y from
287
+ @eserstack/standards/cross-runtime`. It has no baseline any more:
288
+ `--write-baseline`, the `baseline` option and
289
+ `.eser/baselines/runtime-js-apis.json` are gone. Switch to `runtime` from
290
+ `@eserstack/standards/cross-runtime`, or list scripts that run without it by
291
+ design in the step's `exclude`.
292
+ - `validate-package-configs` and the `./validate-package-configs` export are
293
+ removed: with package.json as the only package config there is nothing to
294
+ compare. Drop the step from `.eser/manifest.yml`.
295
+ - The `./lint-plugin` export and its rules (`copyright-header`,
296
+ `no-top-level-arrow-exports`, `prefer-private-fields`) are removed;
297
+ `validate-licenses` still checks license headers.
298
+
299
+ ---
300
+
301
+ 🔗 For further details, visit the
302
+ [eserstack repository](https://github.com/eser/stack).
@@ -0,0 +1,105 @@
1
+ import * as functions from "@eserstack/functions";
2
+ import type * as shellArgs from "@eserstack/shell/args";
3
+ import type * as git from "./git.ts";
4
+ /**
5
+ * A parsed conventional commit.
6
+ */
7
+ export type ConventionalCommit = {
8
+ /** Commit type (feat, fix, refactor, etc.) */
9
+ readonly type: string;
10
+ /** Commit scope (optional, e.g., "auth" in "feat(auth): message") */
11
+ readonly scope: string | undefined;
12
+ /** Commit message (after the colon) */
13
+ readonly message: string;
14
+ /** Original commit hash */
15
+ readonly hash: string;
16
+ };
17
+ /**
18
+ * CHANGELOG section name from Keep a Changelog format.
19
+ */
20
+ export type ChangelogSection = "Added" | "Fixed" | "Changed" | "Removed";
21
+ /**
22
+ * Options for generating a changelog.
23
+ */
24
+ export type GenerateChangelogOptions = {
25
+ /** Root directory containing VERSION and CHANGELOG.md (default: ".") */
26
+ readonly root?: string;
27
+ /** Release version for the heading. Default: next patch after the latest tag. */
28
+ readonly version?: string;
29
+ /** Preview without writing to CHANGELOG.md (default: false) */
30
+ readonly dryRun?: boolean;
31
+ };
32
+ /**
33
+ * Result of generating a changelog.
34
+ */
35
+ export type GenerateChangelogResult = {
36
+ /** The version for this release */
37
+ readonly version: string;
38
+ /** Number of commits processed */
39
+ readonly commitCount: number;
40
+ /** Number of unique entries (after dedup) */
41
+ readonly entryCount: number;
42
+ /** The generated markdown content */
43
+ readonly content: string;
44
+ /** Whether this was a dry run */
45
+ readonly dryRun: boolean;
46
+ };
47
+ /**
48
+ * Parse a single commit subject as a conventional commit.
49
+ * Returns undefined if the subject doesn't match the conventional format.
50
+ */
51
+ export declare const parseConventionalCommit: (subject: string, hash: string) => ConventionalCommit | undefined;
52
+ /**
53
+ * Strip the "take" suffix from a message.
54
+ * "authentication system (take II)." → "authentication system."
55
+ * "authentication system (take 3)" → "authentication system"
56
+ */
57
+ export declare const stripTakeSuffix: (message: string) => string;
58
+ /**
59
+ * Parse an array of git commits into conventional commits.
60
+ * Non-conventional commits are silently skipped.
61
+ */
62
+ export declare const parseConventionalCommits: (commits: ReadonlyArray<git.Commit>) => ConventionalCommit[];
63
+ /**
64
+ * Deduplicate commits by stripping "take" suffixes and keeping only the first
65
+ * occurrence of each unique type+message pair.
66
+ */
67
+ export declare const deduplicateCommits: (commits: ReadonlyArray<ConventionalCommit>) => ConventionalCommit[];
68
+ /**
69
+ * Group commits by CHANGELOG section.
70
+ * Skips commit types that are not user-facing (chore, ci, test).
71
+ */
72
+ export declare const groupBySection: (commits: ReadonlyArray<ConventionalCommit>) => Map<ChangelogSection, ConventionalCommit[]>;
73
+ /**
74
+ * Generate a complete CHANGELOG section from grouped commits.
75
+ */
76
+ export declare const generateChangelogSection: (version: string, commits: ReadonlyArray<ConventionalCommit>) => string;
77
+ /**
78
+ * Writes a version's section into CHANGELOG.md content and moves the notes under
79
+ * `## Unreleased` into it, leaving that heading empty above the section. This is
80
+ * the same layout as InsertIntoChangelog in pkg/ajan/codebasefx, which is what a
81
+ * release runs: {@link generateChangelog} calls the Go generator through the
82
+ * bridge, and a Go test compares the two on the same cases.
83
+ *
84
+ * The section goes below Unreleased, or first when there is no Unreleased. An
85
+ * existing section of the version is replaced in place, and the text in it a
86
+ * person wrote stays.
87
+ *
88
+ * @param version - The version string to check for duplicates (e.g., "4.1.2")
89
+ */
90
+ export declare const insertIntoChangelog: (changelogContent: string, newSection: string, version?: string) => string;
91
+ /**
92
+ * Generate a changelog entry from conventional commits since the last tag and
93
+ * write it to CHANGELOG.md, moving the notes under `## Unreleased` into it. The
94
+ * Go generator does the work, so this needs the native library, and `content`
95
+ * holds the generated entries only. A dry run writes nothing.
96
+ */
97
+ export declare const generateChangelog: (options?: GenerateChangelogOptions) => Promise<GenerateChangelogResult>;
98
+ /** Handler: wraps generateChangelog as a Task via fromPromise. */
99
+ export declare const generateChangelogHandler: functions.handler.Handler<GenerateChangelogOptions, GenerateChangelogResult, Error>;
100
+ /** Runnable CLI trigger for changelog-gen. */
101
+ export declare const handleCli: (event: functions.triggers.CliEvent) => Promise<shellArgs.CliResult<void>>;
102
+ /** Parse the changelog-gen arguments: `--dry-run` (`-n`). */
103
+ export declare const parseCliArgs: (cliArgs?: readonly string[]) => functions.triggers.CliEvent;
104
+ /** CLI entry point. */
105
+ export declare const main: (cliArgs?: readonly string[]) => Promise<shellArgs.CliResult<void>>;