@eserstack/codebase 0.0.0-stage → 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 +301 -2
  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 +222 -3
@@ -0,0 +1,275 @@
1
+ {
2
+ "name": "@eserstack/codebase",
3
+ "version": "5.0.0",
4
+ "type": "module",
5
+ "repository": {
6
+ "type": "git",
7
+ "url": "https://github.com/eser/stack",
8
+ "directory": "pkg/@eserstack/codebase"
9
+ },
10
+ "files": [
11
+ "dist/**/*.js",
12
+ "dist/**/*.d.ts",
13
+ "dist/**/*.json"
14
+ ],
15
+ "exports": {
16
+ ".": "./main.ts",
17
+ "./mod": "./mod.ts",
18
+ "./module": "./module.ts",
19
+ "./directive-analysis": "./directive-analysis.ts",
20
+ "./git": "./git.ts",
21
+ "./native-functions": "./native-functions.ts",
22
+ "./package": "./package/mod.ts",
23
+ "./validation": "./validation/mod.ts",
24
+ "./workspace-discovery": "./workspace-discovery.ts",
25
+ "./validate-circular-deps": "./validate-circular-deps.ts",
26
+ "./validate-mod-exports": "./validate-mod-exports.ts",
27
+ "./validate-export-names": "./validate-export-names.ts",
28
+ "./validate-docs": "./validate-docs.ts",
29
+ "./validate-licenses": "./validate-licenses.ts",
30
+ "./npm-externals": "./npm-externals.ts",
31
+ "./npm-workspace-specifiers": "./npm-workspace-specifiers.ts",
32
+ "./versions": "./versions.ts",
33
+ "./gh": "./gh.ts",
34
+ "./gh-contributors": "./gh-contributors.ts",
35
+ "./release-tag": "./release-tag.ts",
36
+ "./release-notes": "./release-notes.ts",
37
+ "./changelog-gen": "./changelog-gen.ts",
38
+ "./commitmsg": "./commitmsg.ts",
39
+ "./release": "./release.ts",
40
+ "./cli-support": "./cli-support.ts",
41
+ "./file-tool": "./file-tool.ts",
42
+ "./file-tools-shared": "./file-tools-shared.ts",
43
+ "./walk-stream": "./walk-stream.ts",
44
+ "./validate-stream": "./validate-stream.ts",
45
+ "./validate-eof": "./validate-eof.ts",
46
+ "./validate-trailing-whitespace": "./validate-trailing-whitespace.ts",
47
+ "./validate-bom": "./validate-bom.ts",
48
+ "./validate-line-endings": "./validate-line-endings.ts",
49
+ "./validate-large-files": "./validate-large-files.ts",
50
+ "./validate-case-conflict": "./validate-case-conflict.ts",
51
+ "./validate-merge-conflict": "./validate-merge-conflict.ts",
52
+ "./validate-json": "./validate-json.ts",
53
+ "./validate-toml": "./validate-toml.ts",
54
+ "./validate-yaml": "./validate-yaml.ts",
55
+ "./validate-symlinks": "./validate-symlinks.ts",
56
+ "./validate-shebangs": "./validate-shebangs.ts",
57
+ "./validate-secrets": "./validate-secrets.ts",
58
+ "./validate-filenames": "./validate-filenames.ts",
59
+ "./validate-submodules": "./validate-submodules.ts",
60
+ "./validate-commit-msg": "./validate-commit-msg.ts",
61
+ "./install": "./install.ts"
62
+ },
63
+ "publishConfig": {
64
+ "exports": {
65
+ ".": {
66
+ "types": "./dist/main.d.ts",
67
+ "import": "./dist/main.js"
68
+ },
69
+ "./mod": {
70
+ "types": "./dist/mod.d.ts",
71
+ "import": "./dist/mod.js"
72
+ },
73
+ "./module": {
74
+ "types": "./dist/module.d.ts",
75
+ "import": "./dist/module.js"
76
+ },
77
+ "./directive-analysis": {
78
+ "types": "./dist/directive-analysis.d.ts",
79
+ "import": "./dist/directive-analysis.js"
80
+ },
81
+ "./git": {
82
+ "types": "./dist/git.d.ts",
83
+ "import": "./dist/git.js"
84
+ },
85
+ "./native-functions": {
86
+ "types": "./dist/native-functions.d.ts",
87
+ "import": "./dist/native-functions.js"
88
+ },
89
+ "./package": {
90
+ "types": "./dist/package/mod.d.ts",
91
+ "import": "./dist/package/mod.js"
92
+ },
93
+ "./validation": {
94
+ "types": "./dist/validation/mod.d.ts",
95
+ "import": "./dist/validation/mod.js"
96
+ },
97
+ "./workspace-discovery": {
98
+ "types": "./dist/workspace-discovery.d.ts",
99
+ "import": "./dist/workspace-discovery.js"
100
+ },
101
+ "./validate-circular-deps": {
102
+ "types": "./dist/validate-circular-deps.d.ts",
103
+ "import": "./dist/validate-circular-deps.js"
104
+ },
105
+ "./validate-mod-exports": {
106
+ "types": "./dist/validate-mod-exports.d.ts",
107
+ "import": "./dist/validate-mod-exports.js"
108
+ },
109
+ "./validate-export-names": {
110
+ "types": "./dist/validate-export-names.d.ts",
111
+ "import": "./dist/validate-export-names.js"
112
+ },
113
+ "./validate-docs": {
114
+ "types": "./dist/validate-docs.d.ts",
115
+ "import": "./dist/validate-docs.js"
116
+ },
117
+ "./validate-licenses": {
118
+ "types": "./dist/validate-licenses.d.ts",
119
+ "import": "./dist/validate-licenses.js"
120
+ },
121
+ "./npm-externals": {
122
+ "types": "./dist/npm-externals.d.ts",
123
+ "import": "./dist/npm-externals.js"
124
+ },
125
+ "./npm-workspace-specifiers": {
126
+ "types": "./dist/npm-workspace-specifiers.d.ts",
127
+ "import": "./dist/npm-workspace-specifiers.js"
128
+ },
129
+ "./versions": {
130
+ "types": "./dist/versions.d.ts",
131
+ "import": "./dist/versions.js"
132
+ },
133
+ "./gh": {
134
+ "types": "./dist/gh.d.ts",
135
+ "import": "./dist/gh.js"
136
+ },
137
+ "./gh-contributors": {
138
+ "types": "./dist/gh-contributors.d.ts",
139
+ "import": "./dist/gh-contributors.js"
140
+ },
141
+ "./release-tag": {
142
+ "types": "./dist/release-tag.d.ts",
143
+ "import": "./dist/release-tag.js"
144
+ },
145
+ "./release-notes": {
146
+ "types": "./dist/release-notes.d.ts",
147
+ "import": "./dist/release-notes.js"
148
+ },
149
+ "./changelog-gen": {
150
+ "types": "./dist/changelog-gen.d.ts",
151
+ "import": "./dist/changelog-gen.js"
152
+ },
153
+ "./commitmsg": {
154
+ "types": "./dist/commitmsg.d.ts",
155
+ "import": "./dist/commitmsg.js"
156
+ },
157
+ "./release": {
158
+ "types": "./dist/release.d.ts",
159
+ "import": "./dist/release.js"
160
+ },
161
+ "./cli-support": {
162
+ "types": "./dist/cli-support.d.ts",
163
+ "import": "./dist/cli-support.js"
164
+ },
165
+ "./file-tool": {
166
+ "types": "./dist/file-tool.d.ts",
167
+ "import": "./dist/file-tool.js"
168
+ },
169
+ "./file-tools-shared": {
170
+ "types": "./dist/file-tools-shared.d.ts",
171
+ "import": "./dist/file-tools-shared.js"
172
+ },
173
+ "./walk-stream": {
174
+ "types": "./dist/walk-stream.d.ts",
175
+ "import": "./dist/walk-stream.js"
176
+ },
177
+ "./validate-stream": {
178
+ "types": "./dist/validate-stream.d.ts",
179
+ "import": "./dist/validate-stream.js"
180
+ },
181
+ "./validate-eof": {
182
+ "types": "./dist/validate-eof.d.ts",
183
+ "import": "./dist/validate-eof.js"
184
+ },
185
+ "./validate-trailing-whitespace": {
186
+ "types": "./dist/validate-trailing-whitespace.d.ts",
187
+ "import": "./dist/validate-trailing-whitespace.js"
188
+ },
189
+ "./validate-bom": {
190
+ "types": "./dist/validate-bom.d.ts",
191
+ "import": "./dist/validate-bom.js"
192
+ },
193
+ "./validate-line-endings": {
194
+ "types": "./dist/validate-line-endings.d.ts",
195
+ "import": "./dist/validate-line-endings.js"
196
+ },
197
+ "./validate-large-files": {
198
+ "types": "./dist/validate-large-files.d.ts",
199
+ "import": "./dist/validate-large-files.js"
200
+ },
201
+ "./validate-case-conflict": {
202
+ "types": "./dist/validate-case-conflict.d.ts",
203
+ "import": "./dist/validate-case-conflict.js"
204
+ },
205
+ "./validate-merge-conflict": {
206
+ "types": "./dist/validate-merge-conflict.d.ts",
207
+ "import": "./dist/validate-merge-conflict.js"
208
+ },
209
+ "./validate-json": {
210
+ "types": "./dist/validate-json.d.ts",
211
+ "import": "./dist/validate-json.js"
212
+ },
213
+ "./validate-toml": {
214
+ "types": "./dist/validate-toml.d.ts",
215
+ "import": "./dist/validate-toml.js"
216
+ },
217
+ "./validate-yaml": {
218
+ "types": "./dist/validate-yaml.d.ts",
219
+ "import": "./dist/validate-yaml.js"
220
+ },
221
+ "./validate-symlinks": {
222
+ "types": "./dist/validate-symlinks.d.ts",
223
+ "import": "./dist/validate-symlinks.js"
224
+ },
225
+ "./validate-shebangs": {
226
+ "types": "./dist/validate-shebangs.d.ts",
227
+ "import": "./dist/validate-shebangs.js"
228
+ },
229
+ "./validate-secrets": {
230
+ "types": "./dist/validate-secrets.d.ts",
231
+ "import": "./dist/validate-secrets.js"
232
+ },
233
+ "./validate-filenames": {
234
+ "types": "./dist/validate-filenames.d.ts",
235
+ "import": "./dist/validate-filenames.js"
236
+ },
237
+ "./validate-submodules": {
238
+ "types": "./dist/validate-submodules.d.ts",
239
+ "import": "./dist/validate-submodules.js"
240
+ },
241
+ "./validate-commit-msg": {
242
+ "types": "./dist/validate-commit-msg.d.ts",
243
+ "import": "./dist/validate-commit-msg.js"
244
+ },
245
+ "./install": {
246
+ "types": "./dist/install.d.ts",
247
+ "import": "./dist/install.js"
248
+ }
249
+ }
250
+ },
251
+ "scripts": {
252
+ "build": "node ../../../etc/scripts/build-library.ts"
253
+ },
254
+ "dependencies": {
255
+ "@eserstack/ai": "workspace:*",
256
+ "@eserstack/ajan": "workspace:*",
257
+ "@eserstack/config": "workspace:*",
258
+ "@eserstack/fp": "workspace:*",
259
+ "@eserstack/functions": "workspace:*",
260
+ "@eserstack/primitives": "workspace:*",
261
+ "@eserstack/shell": "workspace:*",
262
+ "@eserstack/standards": "workspace:*",
263
+ "@eserstack/streams": "workspace:*",
264
+ "@eserstack/workflows": "workspace:*",
265
+ "jsonc-parser": "^3.3.1",
266
+ "semver": "^7.8.6",
267
+ "smol-toml": "^1.9.1",
268
+ "yaml": "^2.9.1"
269
+ },
270
+ "devDependencies": {
271
+ "@eserstack/logging": "workspace:*",
272
+ "@eserstack/test-kit": "workspace:*",
273
+ "@types/semver": "^7.8.0"
274
+ }
275
+ }
@@ -0,0 +1,90 @@
1
+ import * as functions from "@eserstack/functions";
2
+ import type * as shellArgs from "@eserstack/shell/args";
3
+ import type { ChangelogEntry } from "./changelog-text.ts";
4
+ export { type ChangelogEntry, normalizeTag, parseChangelogText, } from "./changelog-text.ts";
5
+ /**
6
+ * Options for parsing a changelog file.
7
+ */
8
+ export type ParseChangelogOptions = {
9
+ /** Path to CHANGELOG.md relative to root (default: "CHANGELOG.md") */
10
+ readonly changelogPath?: string;
11
+ /** Root directory (default: ".") */
12
+ readonly root?: string;
13
+ };
14
+ /**
15
+ * Result of parsing a changelog file.
16
+ */
17
+ export type ParseChangelogResult = {
18
+ /** All changelog entries, most recent first */
19
+ readonly entries: ReadonlyArray<ChangelogEntry>;
20
+ };
21
+ /**
22
+ * Options for syncing release notes to GitHub.
23
+ */
24
+ export type SyncReleaseNotesOptions = {
25
+ /** GitHub repository slug (e.g., "owner/repo") */
26
+ readonly repo: string;
27
+ /** Target tag (e.g., "v4.0.43"). If omitted, uses latest changelog entry */
28
+ readonly tag?: string;
29
+ /** Create the release as a draft if it doesn't exist (default: false) */
30
+ readonly createIfMissing?: boolean;
31
+ /** Path to CHANGELOG.md relative to root (default: "CHANGELOG.md") */
32
+ readonly changelogPath?: string;
33
+ /** Root directory (default: ".") */
34
+ readonly root?: string;
35
+ /** Release title template. Use {tag} placeholder. (default: "eserstack {tag}") */
36
+ readonly releaseTitle?: string;
37
+ };
38
+ /**
39
+ * Result of syncing release notes.
40
+ */
41
+ export type SyncReleaseNotesResult = {
42
+ /** The tag that was synced */
43
+ readonly tag: string;
44
+ /** The changelog entry that was used */
45
+ readonly entry: ChangelogEntry;
46
+ /** Action taken */
47
+ readonly action: "created" | "updated" | "skipped";
48
+ };
49
+ /**
50
+ * Reads and parses a CHANGELOG.md file into structured entries.
51
+ *
52
+ * @param options - Options for the operation
53
+ * @returns Result with changelog entries
54
+ */
55
+ export declare const parseChangelog: (options?: ParseChangelogOptions) => Promise<ParseChangelogResult>;
56
+ /**
57
+ * Runs one `gh` command with the given arguments. It resolves when gh exits 0
58
+ * and rejects with the command's error otherwise, gh's stderr included.
59
+ */
60
+ export type GhRunner = (args: ReadonlyArray<string>) => Promise<void>;
61
+ /**
62
+ * Checks whether a GitHub Release exists for a given tag.
63
+ *
64
+ * @param tag - The tag to check (e.g., "v4.0.43")
65
+ * @param repo - The repository slug (e.g., "owner/repo")
66
+ * @param gh - Runs gh (default: the gh on PATH)
67
+ * @returns true if the release exists
68
+ */
69
+ export declare const hasGitHubRelease: (tag: string, repo: string, gh?: GhRunner) => Promise<boolean>;
70
+ /**
71
+ * Syncs a changelog entry to a GitHub Release.
72
+ *
73
+ * Finds the changelog entry matching the target tag, then edits the notes of
74
+ * the corresponding GitHub Release, draft or published, or creates it as a
75
+ * draft when `createIfMissing` is set. An edit changes the notes only, never
76
+ * the draft state; publishing the draft is left to the release run.
77
+ *
78
+ * @param options - Options for the operation
79
+ * @param gh - Runs gh (default: the gh on PATH)
80
+ * @returns Result describing what action was taken
81
+ */
82
+ export declare const syncReleaseNotes: (options: SyncReleaseNotesOptions, gh?: GhRunner) => Promise<SyncReleaseNotesResult>;
83
+ /** Handler: wraps syncReleaseNotes as a Task via fromPromise. */
84
+ export declare const syncReleaseNotesHandler: functions.handler.Handler<SyncReleaseNotesOptions, SyncReleaseNotesResult, Error>;
85
+ /** Runnable CLI trigger for release-notes. */
86
+ export declare const handleCli: (event: functions.triggers.CliEvent) => Promise<shellArgs.CliResult<void>>;
87
+ /** Parse the release-notes arguments: `--repo`, `--tag`, `--create-if-missing`. */
88
+ export declare const parseCliArgs: (cliArgs?: readonly string[]) => functions.triggers.CliEvent;
89
+ /** CLI entry point for dispatcher compatibility. */
90
+ export declare const main: (cliArgs?: readonly string[]) => Promise<shellArgs.CliResult<void>>;
@@ -0,0 +1,236 @@
1
+ // Copyright 2023-present Eser Ozvataf and other contributors. All rights reserved. Apache-2.0 license.
2
+ /**
3
+ * Changelog parsing and GitHub Release synchronization.
4
+ *
5
+ * Can be used as a library or as a standalone script.
6
+ *
7
+ * Library usage:
8
+ * ```typescript
9
+ * import * as releaseNotes from "@eserstack/codebase/release-notes";
10
+ *
11
+ * // Parse changelog
12
+ * const { entries } = await releaseNotes.parseChangelog({ root: "." });
13
+ * console.log(entries[0].version, entries[0].notes);
14
+ *
15
+ * // Sync to GitHub Release
16
+ * const result = await releaseNotes.syncReleaseNotes({
17
+ * repo: "owner/repo",
18
+ * tag: "v4.0.43",
19
+ * createIfMissing: true,
20
+ * });
21
+ * console.log(result.action); // "created" (as a draft) | "updated" | "skipped"
22
+ * ```
23
+ *
24
+ * CLI usage:
25
+ * node ./release-notes.ts --repo owner/repo [--tag v1.0.0] [--create-if-missing]
26
+ *
27
+ * @module
28
+ */
29
+ import * as primitives from "@eserstack/primitives";
30
+ import * as standards from "@eserstack/standards";
31
+ import * as functions from "@eserstack/functions";
32
+ import * as shell from "@eserstack/shell";
33
+ import * as tui from "@eserstack/shell/tui";
34
+ import * as cliSupport from "./cli-support.js";
35
+ import * as changelogText from "./changelog-text.js";
36
+ export { normalizeTag, parseChangelogText, } from "./changelog-text.js";
37
+ /**
38
+ * Reads and parses a CHANGELOG.md file into structured entries.
39
+ *
40
+ * @param options - Options for the operation
41
+ * @returns Result with changelog entries
42
+ */
43
+ export const parseChangelog = async (options = {}) => {
44
+ const { changelogPath = "CHANGELOG.md", root = "." } = options;
45
+ const fullPath = standards.crossRuntime.runtime.path.resolve(root, changelogPath);
46
+ const text = await standards.crossRuntime.runtime.fs.readTextFile(fullPath);
47
+ const entries = changelogText.parseChangelogText(text);
48
+ return { entries };
49
+ };
50
+ /** The gh on PATH, its output captured. */
51
+ const runGh = async (args) => {
52
+ await new shell.exec.CommandBuilder("gh", [...args]).spawn();
53
+ };
54
+ /**
55
+ * Checks whether a GitHub Release exists for a given tag.
56
+ *
57
+ * @param tag - The tag to check (e.g., "v4.0.43")
58
+ * @param repo - The repository slug (e.g., "owner/repo")
59
+ * @param gh - Runs gh (default: the gh on PATH)
60
+ * @returns true if the release exists
61
+ */
62
+ export const hasGitHubRelease = async (tag, repo, gh = runGh) => {
63
+ try {
64
+ await gh(["release", "view", tag, "--repo", repo]);
65
+ return true;
66
+ }
67
+ catch {
68
+ return false;
69
+ }
70
+ };
71
+ /**
72
+ * Syncs a changelog entry to a GitHub Release.
73
+ *
74
+ * Finds the changelog entry matching the target tag, then edits the notes of
75
+ * the corresponding GitHub Release, draft or published, or creates it as a
76
+ * draft when `createIfMissing` is set. An edit changes the notes only, never
77
+ * the draft state; publishing the draft is left to the release run.
78
+ *
79
+ * @param options - Options for the operation
80
+ * @param gh - Runs gh (default: the gh on PATH)
81
+ * @returns Result describing what action was taken
82
+ */
83
+ export const syncReleaseNotes = async (options, gh = runGh) => {
84
+ const { repo, createIfMissing = false, changelogPath = "CHANGELOG.md", root = ".", releaseTitle = "eserstack {tag}", } = options;
85
+ const { entries } = await parseChangelog({ changelogPath, root });
86
+ if (entries.length === 0) {
87
+ throw new Error("No release headings found in CHANGELOG.md.");
88
+ }
89
+ const targetTag = options.tag !== undefined
90
+ ? changelogText.normalizeTag(options.tag)
91
+ : entries[0].tag;
92
+ const entry = entries.find((e) => e.tag === targetTag);
93
+ if (entry === undefined) {
94
+ throw new Error(`No matching changelog section found for ${targetTag}.`);
95
+ }
96
+ // Write notes to a temp file for gh CLI
97
+ const tempDir = await standards.crossRuntime.runtime.fs.makeTempDir({
98
+ prefix: "eserstack-release-",
99
+ });
100
+ const notesPath = standards.crossRuntime.runtime.path.join(tempDir, `${targetTag}-notes.md`);
101
+ await standards.crossRuntime.runtime.fs.writeTextFile(notesPath, entry.notes);
102
+ try {
103
+ const exists = await hasGitHubRelease(targetTag, repo, gh);
104
+ if (exists) {
105
+ try {
106
+ await gh([
107
+ "release",
108
+ "edit",
109
+ targetTag,
110
+ "--repo",
111
+ repo,
112
+ "--notes-file",
113
+ notesPath,
114
+ ]);
115
+ }
116
+ catch (editErr) {
117
+ throw new Error(`gh release edit ${targetTag} failed.${cliSupport.commandFailureDetail(editErr)}`, { cause: editErr });
118
+ }
119
+ return { tag: targetTag, entry, action: "updated" };
120
+ }
121
+ if (!createIfMissing) {
122
+ return { tag: targetTag, entry, action: "skipped" };
123
+ }
124
+ const title = releaseTitle.replaceAll("{tag}", targetTag);
125
+ // A draft, like the Go SyncReleaseNotes and build.yml's release-notes job
126
+ // create: the release run publishes it once its archives are attached, so
127
+ // releases/latest never names a release without them. gh finds a draft by
128
+ // its tag, so the view and edit above reach it on a later sync.
129
+ try {
130
+ await gh([
131
+ "release",
132
+ "create",
133
+ targetTag,
134
+ "--repo",
135
+ repo,
136
+ "--title",
137
+ title,
138
+ "--draft",
139
+ "--notes-file",
140
+ notesPath,
141
+ ]);
142
+ return { tag: targetTag, entry, action: "created" };
143
+ }
144
+ catch (createErr) {
145
+ // Falling back to `edit` is only right when someone else created the
146
+ // release between the check and the create. For any other failure the
147
+ // edit fails too ("release not found"), and reporting THAT error hides
148
+ // the one that matters. Re-check before choosing, and carry gh's own
149
+ // stderr — it is the only place the real reason lives.
150
+ if (!(await hasGitHubRelease(targetTag, repo, gh))) {
151
+ throw new Error(`gh release create ${targetTag} failed.${cliSupport.commandFailureDetail(createErr)}`, { cause: createErr });
152
+ }
153
+ await gh([
154
+ "release",
155
+ "edit",
156
+ targetTag,
157
+ "--repo",
158
+ repo,
159
+ "--notes-file",
160
+ notesPath,
161
+ ]);
162
+ return { tag: targetTag, entry, action: "updated" };
163
+ }
164
+ }
165
+ finally {
166
+ await standards.crossRuntime.runtime.fs.remove(tempDir, {
167
+ recursive: true,
168
+ });
169
+ }
170
+ };
171
+ // --- Handler ---
172
+ /** Handler: wraps syncReleaseNotes as a Task via fromPromise. */
173
+ export const syncReleaseNotesHandler = (input) => functions.task.fromPromise(() => syncReleaseNotes(input));
174
+ // --- CLI Adapter ---
175
+ /** Adapter: functions.triggers.CliEvent → SyncReleaseNotesOptions (extracts --repo, --tag, --create-if-missing flags). */
176
+ const cliAdapter = (event) => {
177
+ const repo = event.flags["repo"] ??
178
+ standards.crossRuntime.runtime.env.get("GITHUB_REPOSITORY") ??
179
+ "";
180
+ if (repo === "") {
181
+ return primitives.results.fail(functions.handler.adaptError("Missing repository. Pass --repo or set GITHUB_REPOSITORY."));
182
+ }
183
+ return primitives.results.ok({
184
+ repo,
185
+ tag: event.flags["tag"] ?? undefined,
186
+ createIfMissing: event.flags["create-if-missing"] === true,
187
+ });
188
+ };
189
+ // --- CLI ResponseMapper ---
190
+ /** ResponseMapper: formats SyncReleaseNotesResult for CLI output. */
191
+ const cliResponseMapper = (result) => {
192
+ const { ctx } = cliSupport.getCliContext();
193
+ if (primitives.results.isFail(result)) {
194
+ const err = result.error;
195
+ const message = err instanceof Error
196
+ ? err.message
197
+ : (err.message ?? String(err));
198
+ tui.log.error(ctx, message);
199
+ return primitives.results.fail({ exitCode: 1 });
200
+ }
201
+ const { value } = result;
202
+ switch (value.action) {
203
+ case "created":
204
+ tui.log.success(ctx, `Created draft release ${value.tag} with changelog notes.`);
205
+ break;
206
+ case "updated":
207
+ tui.log.success(ctx, `Updated release notes for ${value.tag}.`);
208
+ break;
209
+ case "skipped":
210
+ tui.log.warn(ctx, `Release ${value.tag} not found. Skipping (pass --create-if-missing to create a draft).`);
211
+ break;
212
+ }
213
+ return primitives.results.ok(undefined);
214
+ };
215
+ // --- CLI Trigger ---
216
+ /** Runnable CLI trigger for release-notes. */
217
+ export const handleCli = functions.handler.createTrigger({
218
+ handler: syncReleaseNotesHandler,
219
+ adaptInput: cliAdapter,
220
+ adaptOutput: cliResponseMapper,
221
+ });
222
+ /** Parse the release-notes arguments: `--repo`, `--tag`, `--create-if-missing`. */
223
+ export const parseCliArgs = (cliArgs) => cliSupport.parseCliEvent("release-notes", cliArgs, {
224
+ repo: { type: "string" },
225
+ tag: { type: "string" },
226
+ "create-if-missing": { type: "boolean" },
227
+ help: { type: "boolean", short: "h" },
228
+ });
229
+ /** CLI entry point for dispatcher compatibility. */
230
+ export const main = async (cliArgs) => await handleCli(parseCliArgs(cliArgs));
231
+ if (import.meta.main) {
232
+ // Entry point: the await only runs when this file is executed directly.
233
+ // oxlint-disable-next-line node/no-top-level-await
234
+ const result = await main(standards.crossRuntime.runtime.process.args);
235
+ cliSupport.runCliMain(result, cliSupport.getCliContext().output);
236
+ }
@@ -0,0 +1,46 @@
1
+ import * as functions from "@eserstack/functions";
2
+ import type * as shellArgs from "@eserstack/shell/args";
3
+ /**
4
+ * Options for pushing a release tag.
5
+ */
6
+ export type PushReleaseTagOptions = {
7
+ /** Root directory containing the VERSION file (default: ".") */
8
+ readonly root?: string;
9
+ /** Git remote to push to (default: "origin") */
10
+ readonly remote?: string;
11
+ /** Tag prefix (default: "v") */
12
+ readonly tagPrefix?: string;
13
+ /** Tag message template. Use {tag} and {version} placeholders. (default: "Release {tag}") */
14
+ readonly messageTemplate?: string;
15
+ /** Preview without creating/pushing (default: false) */
16
+ readonly dryRun?: boolean;
17
+ };
18
+ /**
19
+ * Result of pushing a release tag.
20
+ */
21
+ export type PushReleaseTagResult = {
22
+ /** The version read from VERSION file */
23
+ readonly version: string;
24
+ /** The full tag name (e.g., "v4.0.43") */
25
+ readonly tag: string;
26
+ /** The remote the tag was pushed to */
27
+ readonly remote: string;
28
+ /** Whether this was a dry run */
29
+ readonly dryRun: boolean;
30
+ };
31
+ /**
32
+ * Reads the VERSION file, creates an annotated git tag, and pushes it.
33
+ *
34
+ * @param options - Options for the operation
35
+ * @returns Result describing the tag that was created
36
+ * @throws If the VERSION file is missing or contains an invalid version
37
+ */
38
+ export declare const pushReleaseTag: (options?: PushReleaseTagOptions) => Promise<PushReleaseTagResult>;
39
+ /** Handler: wraps pushReleaseTag as a Task via fromPromise. */
40
+ export declare const pushReleaseTagHandler: functions.handler.Handler<PushReleaseTagOptions, PushReleaseTagResult, Error>;
41
+ /** Runnable CLI trigger for release-tag. */
42
+ export declare const handleCli: (event: functions.triggers.CliEvent) => Promise<shellArgs.CliResult<void>>;
43
+ /** Parse the release-tag arguments: `--dry-run` (`-n`). */
44
+ export declare const parseCliArgs: (cliArgs?: readonly string[]) => functions.triggers.CliEvent;
45
+ /** CLI entry point for dispatcher compatibility. */
46
+ export declare const main: (cliArgs?: readonly string[]) => Promise<shellArgs.CliResult<void>>;