ai-release-notes 0.2.0 → 0.3.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.
- package/README.md +85 -6
- package/dist/bin/cli.js +150 -191
- package/dist/bin/cli.js.map +1 -1
- package/dist/config.d.ts.map +1 -1
- package/dist/config.js +3 -0
- package/dist/config.js.map +1 -1
- package/dist/generator.js +1 -1
- package/dist/generator.js.map +1 -1
- package/dist/git.d.ts +9 -0
- package/dist/git.d.ts.map +1 -1
- package/dist/git.js +14 -1
- package/dist/git.js.map +1 -1
- package/dist/prompts/builder.d.ts.map +1 -1
- package/dist/prompts/builder.js +8 -1
- package/dist/prompts/builder.js.map +1 -1
- package/dist/release.d.ts +73 -5
- package/dist/release.d.ts.map +1 -1
- package/dist/release.js +184 -87
- package/dist/release.js.map +1 -1
- package/dist/types.d.ts +5 -0
- package/dist/types.d.ts.map +1 -1
- package/dist/types.js +2 -0
- package/dist/types.js.map +1 -1
- package/package.json +1 -1
- package/prompts/release-notes-instructions.md +2 -0
- package/templates/default-release-note.html +66 -5
- package/templates/default-release-summary-entry.html +5 -0
- package/templates/default-release-summary-entry.md +5 -0
- package/templates/default-release-summary.html +7 -3
- package/templates/default-release-summary.md +1 -0
package/README.md
CHANGED
|
@@ -160,19 +160,91 @@ The main parts are simple:
|
|
|
160
160
|
See [Instructions](#instructions).
|
|
161
161
|
- `output` lists the Markdown and/or HTML release files to create. Use
|
|
162
162
|
`{env}`, `{lang}`, `{from}`, and `{to}` in their names. Missing `--from` and
|
|
163
|
-
`--to` become `start` and `end`.
|
|
163
|
+
`--to` become `start` and `end`. A name carrying `{from}` or `{to}` belongs
|
|
164
|
+
to a single release, so regenerating it rewrites that file. A name without
|
|
165
|
+
either is shared by every release, and each new one is added to it.
|
|
164
166
|
- `outputIndex` is optional. It maintains a release summary with links to
|
|
165
167
|
every release file. It may be one destination or a list, for example one
|
|
166
168
|
Markdown and one HTML summary. Add `{lang}` when each language needs its own
|
|
167
|
-
summary.
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
169
|
+
summary. `entryTemplate` sets the shape of one listed release; see
|
|
170
|
+
[Index entries](#index-entries). Index templates can place links between those
|
|
171
|
+
summaries with `{{languages}}` (or `{{langages}}`). That slot is spent the
|
|
172
|
+
first time an index is written: afterwards the switcher is found by the markup
|
|
173
|
+
it was rendered as, so a generated page carries a switcher rather than a
|
|
174
|
+
marker of ours. A single language shows no switcher at all. The switcher
|
|
175
|
+
merges languages from the current prompt with localized index files already
|
|
176
|
+
present on disk. An index template is assumed to be written in the first
|
|
177
|
+
`prompt.languages` entry, and an index in any other language is translated.
|
|
172
178
|
|
|
173
179
|
Custom instruction and summary templates are optional. The generated config
|
|
174
180
|
keeps their lines commented until you need them.
|
|
175
181
|
|
|
182
|
+
### Index entries
|
|
183
|
+
|
|
184
|
+
One listed release is one template: markup with `{{slot}}` placeholders, and
|
|
185
|
+
nothing else. The bundled one lives in
|
|
186
|
+
`templates/default-release-summary-entry.md` and `.html`:
|
|
187
|
+
|
|
188
|
+
```html
|
|
189
|
+
<section class="release-entry">
|
|
190
|
+
<h2>Release {{toVersion}}</h2>
|
|
191
|
+
<p><em>{{environment}} · {{date}} · Changes since {{fromVersion}}</em></p>
|
|
192
|
+
<p><a href="{{href}}">Read release notes</a></p>
|
|
193
|
+
</section>
|
|
194
|
+
```
|
|
195
|
+
|
|
196
|
+
The slots are `{{environment}}`, `{{date}}`, `{{fromVersion}}`, `{{toVersion}}`
|
|
197
|
+
and `{{href}}`. Everything else is yours to write. Point `entryTemplate` at your
|
|
198
|
+
own file to replace it:
|
|
199
|
+
|
|
200
|
+
```yaml
|
|
201
|
+
outputIndex:
|
|
202
|
+
- format: html
|
|
203
|
+
saveTo: ./releases/{env}/{lang}/index.html
|
|
204
|
+
template: ./templates/summary.html
|
|
205
|
+
entryTemplate: ./templates/entry.html
|
|
206
|
+
```
|
|
207
|
+
|
|
208
|
+
The entry template is read from its file on every run and translated together
|
|
209
|
+
with the summary template, so an index never carries a copy of it: editing the
|
|
210
|
+
file is what changes the shape.
|
|
211
|
+
|
|
212
|
+
Each entry stores what the index knows about its release — environment,
|
|
213
|
+
versions, date, link — in a comment marker, and the whole list is rendered again
|
|
214
|
+
on every run. Edit the entry template, or switch the index to another language,
|
|
215
|
+
and the entire history is relabelled at the next release. The list is bounded by
|
|
216
|
+
`<!-- ai-release-notes:releases -->` and `<!-- ai-release-notes:/releases -->`;
|
|
217
|
+
everything outside those two lines belongs to the summary template.
|
|
218
|
+
|
|
219
|
+
An entry that carries no record is kept word for word, below the rendered ones,
|
|
220
|
+
since there is nothing to render it from.
|
|
221
|
+
|
|
222
|
+
### The release page
|
|
223
|
+
|
|
224
|
+
An HTML release note is rendered inside `templates/default-release-note.html`,
|
|
225
|
+
and that file owns every word of the page: its `<title>`, its footer, and its
|
|
226
|
+
styles are the template's own. `--template` (or `output[].template`) points at a
|
|
227
|
+
file of yours instead. These slots are filled, and anything else is left as
|
|
228
|
+
written:
|
|
229
|
+
|
|
230
|
+
| Slot | Value |
|
|
231
|
+
|------|-------|
|
|
232
|
+
| `{{content}}` | The release note itself |
|
|
233
|
+
| `{{projectName}}` | `projectName` from the config |
|
|
234
|
+
| `{{fromVersion}}` / `{{toVersion}}` | The version range |
|
|
235
|
+
| `{{environment}}` | `--env` |
|
|
236
|
+
| `{{date}}` | The resolved release date |
|
|
237
|
+
| `{{version}}` | The `ai-release-notes` version |
|
|
238
|
+
|
|
239
|
+
A page title is a sentence, so it is written in the template's `<title>` rather
|
|
240
|
+
than assembled from the versions: there is no `{{title}}` slot.
|
|
241
|
+
|
|
242
|
+
### The first release
|
|
243
|
+
|
|
244
|
+
`--from start` — the default — reads the whole history, so there is no previous
|
|
245
|
+
version to compare against. The release note says `First release` where a
|
|
246
|
+
comparison would go, and the file name still uses `start` for `{from}`.
|
|
247
|
+
|
|
176
248
|
For the exact configuration and comments, see the annotated
|
|
177
249
|
[example `.ai-release-notes.yml`](examples/.ai-release-notes.yml). The
|
|
178
250
|
[examples guide](examples/README.md) then walks through a first run, writing
|
|
@@ -286,6 +358,13 @@ console.log(result.markdown);
|
|
|
286
358
|
console.log(result.html);
|
|
287
359
|
```
|
|
288
360
|
|
|
361
|
+
`markdownToHtml(markdown, options?)` wraps Markdown in the bundled release-note
|
|
362
|
+
template, which supplies the page title and footer:
|
|
363
|
+
|
|
364
|
+
```typescript
|
|
365
|
+
markdownToHtml(markdown, { trustedHtml: true });
|
|
366
|
+
```
|
|
367
|
+
|
|
289
368
|
---
|
|
290
369
|
|
|
291
370
|
## CI/CD Integration
|
package/dist/bin/cli.js
CHANGED
|
@@ -107,7 +107,7 @@ program
|
|
|
107
107
|
.command("generate")
|
|
108
108
|
.alias("gen")
|
|
109
109
|
.description("Generate release notes from git tags")
|
|
110
|
-
.option("--from <version>",
|
|
110
|
+
.option("--from <version>", `Previous version tag, or "${git_js_1.FIRST_RELEASE}" for the full history`, git_js_1.FIRST_RELEASE)
|
|
111
111
|
.option("--to <version>", "Current version tag (e.g. v1.1.0)")
|
|
112
112
|
.requiredOption("--env <environment>", "Environment: PROD, STAGING, DEV...")
|
|
113
113
|
.option("--release-date <value>", 'Release date: "now", "tag", or an ISO date (default: now)')
|
|
@@ -169,12 +169,12 @@ program
|
|
|
169
169
|
}
|
|
170
170
|
// Determine output path
|
|
171
171
|
let outputTargets = !opts.stdout && opts.output
|
|
172
|
-
? [{ path: opts.output, markdown: generatedResult.markdown, html: generatedResult.html, format: opts.format }]
|
|
172
|
+
? [{ path: opts.output, markdown: generatedResult.markdown, html: generatedResult.html, format: opts.format, ownedByRelease: true }]
|
|
173
173
|
: [];
|
|
174
174
|
if (!opts.stdout && outputTargets.length === 0 && opts.outputDir) {
|
|
175
175
|
const ext = opts.format === "html" ? "html" : "md";
|
|
176
176
|
const filename = `RELEASE_NOTES_${toVersion.replace(/^v/, "")}.${ext}`;
|
|
177
|
-
outputTargets = [{ path: (0, path_1.join)((0, path_1.resolve)(opts.outputDir), filename), markdown: generatedResult.markdown, html: generatedResult.html, format: opts.format }];
|
|
177
|
+
outputTargets = [{ path: (0, path_1.join)((0, path_1.resolve)(opts.outputDir), filename), markdown: generatedResult.markdown, html: generatedResult.html, format: opts.format, ownedByRelease: true }];
|
|
178
178
|
}
|
|
179
179
|
if (!opts.stdout && outputTargets.length === 0) {
|
|
180
180
|
if (loadedConfig.output) {
|
|
@@ -183,20 +183,25 @@ program
|
|
|
183
183
|
if (!output.saveTo)
|
|
184
184
|
return [];
|
|
185
185
|
const saveTo = Array.isArray(output.saveTo) ? output.saveTo : [output.saveTo];
|
|
186
|
-
return saveTo.flatMap((path) =>
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
}))
|
|
194
|
-
: [{
|
|
195
|
-
path: getOutputPath(path, opts.env, undefined, opts.from, opts.to),
|
|
196
|
-
markdown: generatedResult.markdown,
|
|
197
|
-
html: generatedResult.html,
|
|
186
|
+
return saveTo.flatMap((path) => {
|
|
187
|
+
const ownedByRelease = isReleaseSpecificPath(path);
|
|
188
|
+
return path.includes("{lang}")
|
|
189
|
+
? generatedResult.localized.map((release) => ({
|
|
190
|
+
path: getOutputPath(path, opts.env, release.language, opts.from, opts.to),
|
|
191
|
+
markdown: release.markdown,
|
|
192
|
+
html: release.html,
|
|
198
193
|
format: output.format,
|
|
199
|
-
|
|
194
|
+
language: release.language,
|
|
195
|
+
ownedByRelease,
|
|
196
|
+
}))
|
|
197
|
+
: [{
|
|
198
|
+
path: getOutputPath(path, opts.env, undefined, opts.from, opts.to),
|
|
199
|
+
markdown: generatedResult.markdown,
|
|
200
|
+
html: generatedResult.html,
|
|
201
|
+
format: output.format,
|
|
202
|
+
ownedByRelease,
|
|
203
|
+
}];
|
|
204
|
+
});
|
|
200
205
|
});
|
|
201
206
|
}
|
|
202
207
|
}
|
|
@@ -213,6 +218,7 @@ program
|
|
|
213
218
|
language: release.language,
|
|
214
219
|
format: outputIndex.format,
|
|
215
220
|
templatePath: outputIndex.template,
|
|
221
|
+
entryTemplatePath: outputIndex.entryTemplate,
|
|
216
222
|
templateLanguage: primaryLanguage,
|
|
217
223
|
}))
|
|
218
224
|
: [{
|
|
@@ -220,6 +226,7 @@ program
|
|
|
220
226
|
groupId,
|
|
221
227
|
format: outputIndex.format,
|
|
222
228
|
templatePath: outputIndex.template,
|
|
229
|
+
entryTemplatePath: outputIndex.entryTemplate,
|
|
223
230
|
templateLanguage: primaryLanguage,
|
|
224
231
|
}]);
|
|
225
232
|
if (outputIndexTargets.some((index) => outputTargets.some((target) => (0, path_1.resolve)(target.path) === index.path))) {
|
|
@@ -257,16 +264,18 @@ program
|
|
|
257
264
|
const content = target.format === "html" && target.html
|
|
258
265
|
? target.html
|
|
259
266
|
: target.markdown;
|
|
260
|
-
const saved = await saveReleaseNotes((0, path_1.resolve)(outputPath), content, target.markdown);
|
|
267
|
+
const saved = await saveReleaseNotes((0, path_1.resolve)(outputPath), content, target.markdown, target.ownedByRelease === true);
|
|
261
268
|
if (saved === "skipped") {
|
|
262
269
|
console.log(chalk_1.default.yellow("ℹ️ Release " + fromVersion + " → " + toVersion + " is already in " + outputPath));
|
|
263
270
|
}
|
|
271
|
+
else if (saved === "replaced") {
|
|
272
|
+
console.log(chalk_1.default.green("💾 Replaced " + outputPath));
|
|
273
|
+
}
|
|
264
274
|
else {
|
|
265
275
|
console.log(chalk_1.default.green("💾 Saved to " + outputPath));
|
|
266
276
|
}
|
|
267
277
|
}
|
|
268
278
|
if (outputIndexTargets.length > 0 && outputTargets.length > 0) {
|
|
269
|
-
const translatedCopyCache = new Map();
|
|
270
279
|
for (const index of outputIndexTargets) {
|
|
271
280
|
await (0, promises_1.mkdir)((0, path_1.dirname)(index.path), { recursive: true });
|
|
272
281
|
const releasePaths = getReleasePathsForIndex(index, outputTargets);
|
|
@@ -275,6 +284,7 @@ program
|
|
|
275
284
|
outputPath: index.path,
|
|
276
285
|
format: index.format,
|
|
277
286
|
templatePath: index.templatePath,
|
|
287
|
+
entryTemplatePath: index.entryTemplatePath,
|
|
278
288
|
translateTemplate: !opts.dryRun && shouldTranslateTemplate(index.templateLanguage, index.language)
|
|
279
289
|
? async (template) => {
|
|
280
290
|
const translated = await translateOutputIndexTemplate(template, index.language, generatedResult.metadata.provider, loadedConfig.providers[generatedResult.metadata.provider]);
|
|
@@ -282,21 +292,6 @@ program
|
|
|
282
292
|
return translated.text;
|
|
283
293
|
}
|
|
284
294
|
: undefined,
|
|
285
|
-
translateCopy: !opts.dryRun && shouldTranslateOutputIndexCopy(index.language)
|
|
286
|
-
? () => {
|
|
287
|
-
const language = index.language;
|
|
288
|
-
const key = languageCode(language);
|
|
289
|
-
let translated = translatedCopyCache.get(key);
|
|
290
|
-
if (!translated) {
|
|
291
|
-
translated = translateOutputIndexCopy(language, generatedResult.metadata.provider, loadedConfig.providers[generatedResult.metadata.provider]).then(({ copy, usage }) => {
|
|
292
|
-
addTemplateUsage(generatedResult.metadata.usage, usage);
|
|
293
|
-
return copy;
|
|
294
|
-
});
|
|
295
|
-
translatedCopyCache.set(key, translated);
|
|
296
|
-
}
|
|
297
|
-
return translated;
|
|
298
|
-
}
|
|
299
|
-
: undefined,
|
|
300
295
|
projectName: loadedConfig.projectName,
|
|
301
296
|
environment: opts.env,
|
|
302
297
|
language: index.language,
|
|
@@ -321,8 +316,8 @@ program
|
|
|
321
316
|
if (!hasLanguageSwitcher &&
|
|
322
317
|
!existingIndex.templatePath &&
|
|
323
318
|
languageLinks.length > 1 &&
|
|
324
|
-
existing.includes(RELEASES_MARKER)) {
|
|
325
|
-
updated = existing.replace(RELEASES_MARKER, `${languageSwitcher}\n\n${RELEASES_MARKER}`);
|
|
319
|
+
existing.includes(release_js_1.RELEASES_MARKER)) {
|
|
320
|
+
updated = existing.replace(release_js_1.RELEASES_MARKER, `${languageSwitcher}\n\n${release_js_1.RELEASES_MARKER}`);
|
|
326
321
|
}
|
|
327
322
|
if (updated !== existing) {
|
|
328
323
|
await (0, promises_1.writeFile)(existingIndex.path, updated, "utf-8");
|
|
@@ -377,9 +372,19 @@ function getOutputPath(saveTo, environment, language, fromVersion, toVersion) {
|
|
|
377
372
|
return saveTo
|
|
378
373
|
.replaceAll("{env}", normalizedEnvironment)
|
|
379
374
|
.replaceAll("{lang}", normalizedLanguage || "{lang}")
|
|
380
|
-
.replaceAll("{from}", fromVersion ||
|
|
375
|
+
.replaceAll("{from}", fromVersion || git_js_1.FIRST_RELEASE)
|
|
381
376
|
.replaceAll("{to}", toVersion || "end");
|
|
382
377
|
}
|
|
378
|
+
/**
|
|
379
|
+
* Whether a `saveTo` pattern resolves to a different file for every release.
|
|
380
|
+
*
|
|
381
|
+
* With a version placeholder each release gets its own file and owns it. Without
|
|
382
|
+
* one, every release resolves to the same path, which is how a cumulative
|
|
383
|
+
* changelog is configured, and there the releases stack up instead.
|
|
384
|
+
*/
|
|
385
|
+
function isReleaseSpecificPath(saveTo) {
|
|
386
|
+
return saveTo.includes("{from}") || saveTo.includes("{to}");
|
|
387
|
+
}
|
|
383
388
|
function getReleasePathsForIndex(index, outputTargets) {
|
|
384
389
|
const languageTargets = outputTargets.filter((target) => !index.language || !target.language || target.language === index.language);
|
|
385
390
|
const preferredFormat = index.format;
|
|
@@ -401,44 +406,51 @@ function getOutputIndexLanguageLinks(index, targets) {
|
|
|
401
406
|
active: candidate.path.toLowerCase() === index.path.toLowerCase(),
|
|
402
407
|
}));
|
|
403
408
|
}
|
|
404
|
-
const RELEASES_MARKER = "<!-- ai-release-notes:releases -->";
|
|
405
|
-
const RELEASES_END_MARKER = "<!-- ai-release-notes:/releases -->";
|
|
406
409
|
async function createOrUpdateOutputIndex(params) {
|
|
407
|
-
const copy = params.translateCopy
|
|
408
|
-
? await params.translateCopy()
|
|
409
|
-
: getOutputIndexCopy(params.language);
|
|
410
|
-
const localizedDate = localizeIndexDate(params.date, params.language);
|
|
411
|
-
const releaseId = [params.environment, params.fromVersion, params.toVersion]
|
|
412
|
-
.map((value) => encodeURIComponent(value))
|
|
413
|
-
.join("_");
|
|
414
|
-
const releaseEntry = buildOutputIndexEntry(params, releaseId, copy, localizedDate);
|
|
415
|
-
const indexTitle = `${params.projectName ? params.projectName + " · " : ""}${copy.releaseNotes}`;
|
|
416
|
-
const intro = copy.intro(params.environment);
|
|
417
410
|
const languageSwitcher = (0, release_js_1.renderOutputIndexLanguageSwitcher)(params.format, params.languageLinks);
|
|
411
|
+
const record = {
|
|
412
|
+
environment: params.environment,
|
|
413
|
+
fromVersion: params.fromVersion,
|
|
414
|
+
toVersion: params.toVersion,
|
|
415
|
+
date: params.date,
|
|
416
|
+
href: toRelativeLink(params.outputPath, params.releasePaths[0]),
|
|
417
|
+
};
|
|
418
|
+
const renderReleases = (records, entryTemplate) => (0, release_js_1.renderOutputIndexReleases)({
|
|
419
|
+
records,
|
|
420
|
+
entryTemplate,
|
|
421
|
+
format: params.format,
|
|
422
|
+
localizeDate: (date) => localizeIndexDate(date, params.language),
|
|
423
|
+
});
|
|
418
424
|
if ((0, fs_1.existsSync)(params.outputPath)) {
|
|
419
425
|
const existing = await (0, promises_1.readFile)(params.outputPath, "utf-8");
|
|
420
|
-
|
|
421
|
-
|
|
422
|
-
|
|
423
|
-
const
|
|
424
|
-
|
|
426
|
+
// An index written before the releases were bounded ends its list at the
|
|
427
|
+
// first thing that follows it, so give it that boundary before reading the
|
|
428
|
+
// list back out.
|
|
429
|
+
const normalizedExisting = ensureOutputIndexReleaseBoundary(params.format === "html" ? unwrapHtmlDocumentCodeFence(existing) : existing, params.format);
|
|
430
|
+
// The entry template is read from its file on every run, so an index never
|
|
431
|
+
// has to carry a copy of it: editing the file is what changes the shape.
|
|
432
|
+
const { entryTemplate } = await loadOutputIndexEntryTemplate(params);
|
|
433
|
+
// Every release the index knows is rendered again from its record, so a
|
|
434
|
+
// template or a language that changed reaches the whole history, not just
|
|
435
|
+
// the release being added.
|
|
436
|
+
const region = (0, release_js_1.readOutputIndexReleasesRegion)(normalizedExisting);
|
|
437
|
+
const records = (0, release_js_1.upsertOutputIndexReleaseRecord)((0, release_js_1.readOutputIndexReleaseRecords)(region), record);
|
|
438
|
+
const legacyEntries = (0, release_js_1.readLegacyOutputIndexEntries)(region, records.map(release_js_1.outputIndexReleaseId));
|
|
439
|
+
const updated = (0, release_js_1.replaceOutputIndexReleases)(normalizedExisting, [renderReleases(records, entryTemplate), ...legacyEntries].filter(Boolean).join("\n"));
|
|
425
440
|
const hasLanguageSwitcher = (0, release_js_1.hasOutputIndexLanguageSwitcher)(updated);
|
|
426
441
|
const withLanguageSwitcher = (0, release_js_1.applyOutputIndexLanguageSwitcher)(updated, languageSwitcher);
|
|
427
442
|
if (!params.templatePath && params.languageLinks.length > 1 && !hasLanguageSwitcher) {
|
|
428
|
-
return updated.replace(RELEASES_MARKER, `${languageSwitcher}\n\n${RELEASES_MARKER}`);
|
|
443
|
+
return updated.replace(release_js_1.RELEASES_MARKER, `${languageSwitcher}\n\n${release_js_1.RELEASES_MARKER}`);
|
|
429
444
|
}
|
|
430
445
|
return withLanguageSwitcher;
|
|
431
446
|
}
|
|
432
|
-
const template = await
|
|
433
|
-
const
|
|
434
|
-
? await params.translateTemplate(template)
|
|
435
|
-
: template;
|
|
436
|
-
const rendered = renderOutputIndexTemplate(localizedTemplate, {
|
|
447
|
+
const { template, entryTemplate } = await loadOutputIndexEntryTemplate(params);
|
|
448
|
+
const rendered = renderOutputIndexTemplate(template, {
|
|
437
449
|
projectName: params.projectName || "Project",
|
|
438
450
|
environment: params.environment,
|
|
439
451
|
language: params.language || "",
|
|
440
|
-
date:
|
|
441
|
-
releases:
|
|
452
|
+
date: localizeIndexDate(params.date, params.language),
|
|
453
|
+
releases: renderReleases([record], entryTemplate),
|
|
442
454
|
languages: languageSwitcher,
|
|
443
455
|
version: CLI_VERSION,
|
|
444
456
|
}, params.format);
|
|
@@ -451,32 +463,53 @@ async function createOrUpdateOutputIndex(params) {
|
|
|
451
463
|
// never gets that trust.
|
|
452
464
|
const html = isHtmlTemplate
|
|
453
465
|
? rendered
|
|
454
|
-
: (0, release_js_1.markdownToHtml)(rendered,
|
|
466
|
+
: (0, release_js_1.markdownToHtml)(rendered, { trustedHtml: true });
|
|
455
467
|
return html;
|
|
456
468
|
}
|
|
457
|
-
|
|
458
|
-
|
|
459
|
-
|
|
460
|
-
|
|
461
|
-
|
|
462
|
-
|
|
463
|
-
|
|
464
|
-
|
|
465
|
-
|
|
466
|
-
|
|
467
|
-
|
|
468
|
-
|
|
469
|
-
|
|
469
|
+
/**
|
|
470
|
+
* Joins the summary and the entry template on their way to the translator.
|
|
471
|
+
*
|
|
472
|
+
* It exists for the length of one call: it is never written to a template nor
|
|
473
|
+
* to a generated index.
|
|
474
|
+
*/
|
|
475
|
+
const ENTRY_TEMPLATE_SEPARATOR = "__AI_RELEASE_NOTES_PART__";
|
|
476
|
+
/**
|
|
477
|
+
* The summary template to render, and the entry shape to list releases with.
|
|
478
|
+
*
|
|
479
|
+
* The entry shape is not configurable, so it never comes from the summary
|
|
480
|
+
* template. Both are translated in one pass, then split apart again: only the
|
|
481
|
+
* summary is rendered, and the entry shape is stored in the index.
|
|
482
|
+
*/
|
|
483
|
+
async function loadOutputIndexEntryTemplate(params) {
|
|
484
|
+
const summary = await loadOutputIndexTemplate(params.templatePath, params.format);
|
|
485
|
+
const entryFile = await loadEntryTemplate(params.entryTemplatePath, params.format);
|
|
486
|
+
const joined = `${summary}\n${ENTRY_TEMPLATE_SEPARATOR}\n${entryFile}`;
|
|
487
|
+
const localized = params.translateTemplate
|
|
488
|
+
? await params.translateTemplate(joined)
|
|
489
|
+
: joined;
|
|
490
|
+
// A translation that lost the separator cannot be split back apart. The
|
|
491
|
+
// summary stays usable; the entry falls back to the file that was sent.
|
|
492
|
+
const separator = localized.lastIndexOf(ENTRY_TEMPLATE_SEPARATOR);
|
|
493
|
+
return {
|
|
494
|
+
template: (separator < 0 ? localized : localized.slice(0, separator)).trimEnd(),
|
|
495
|
+
entryTemplate: separator < 0
|
|
496
|
+
? entryFile.trim()
|
|
497
|
+
: localized.slice(separator + ENTRY_TEMPLATE_SEPARATOR.length).trim(),
|
|
498
|
+
};
|
|
499
|
+
}
|
|
500
|
+
async function loadEntryTemplate(entryTemplatePath, format) {
|
|
501
|
+
if (!entryTemplatePath) {
|
|
502
|
+
return loadBundledTemplate("default-release-summary-entry", format);
|
|
503
|
+
}
|
|
504
|
+
const resolvedPath = (0, path_1.resolve)(entryTemplatePath);
|
|
505
|
+
if (!(0, fs_1.existsSync)(resolvedPath)) {
|
|
506
|
+
throw new Error(`Output index entry template not found: ${resolvedPath}`);
|
|
470
507
|
}
|
|
471
|
-
|
|
472
|
-
.map((path) => `[${copy.readReleaseNotes} →](${toRelativeLink(params.outputPath, path)})`)
|
|
473
|
-
.join("\n");
|
|
474
|
-
return `${marker}\n## ${title}\n\n_${metadata}_\n\n${links}`;
|
|
508
|
+
return (0, promises_1.readFile)(resolvedPath, "utf-8");
|
|
475
509
|
}
|
|
476
510
|
async function loadOutputIndexTemplate(templatePath, format) {
|
|
477
511
|
if (!templatePath) {
|
|
478
|
-
|
|
479
|
-
return (0, promises_1.readFile)((0, path_1.resolve)(__dirname, `../../templates/default-release-summary.${extension}`), "utf-8");
|
|
512
|
+
return loadBundledTemplate("default-release-summary", format);
|
|
480
513
|
}
|
|
481
514
|
const resolvedTemplatePath = (0, path_1.resolve)(templatePath);
|
|
482
515
|
if (!(0, fs_1.existsSync)(resolvedTemplatePath)) {
|
|
@@ -484,6 +517,10 @@ async function loadOutputIndexTemplate(templatePath, format) {
|
|
|
484
517
|
}
|
|
485
518
|
return (0, promises_1.readFile)(resolvedTemplatePath, "utf-8");
|
|
486
519
|
}
|
|
520
|
+
function loadBundledTemplate(name, format) {
|
|
521
|
+
const extension = format === "html" ? "html" : "md";
|
|
522
|
+
return (0, promises_1.readFile)((0, path_1.resolve)(__dirname, `../../templates/${name}.${extension}`), "utf-8");
|
|
523
|
+
}
|
|
487
524
|
function renderOutputIndexTemplate(template, values, format = "markdown") {
|
|
488
525
|
// A project name and an environment reach an HTML index straight from config
|
|
489
526
|
// and the command line, so they are escaped like every other value there.
|
|
@@ -493,62 +530,10 @@ function renderOutputIndexTemplate(template, values, format = "markdown") {
|
|
|
493
530
|
.replaceAll("{{environment}}", value(values.environment))
|
|
494
531
|
.replaceAll("{{language}}", value(values.language))
|
|
495
532
|
.replaceAll("{{date}}", value(values.date))
|
|
496
|
-
.replaceAll("{{releases}}", `${values.releases}\n${RELEASES_END_MARKER}`)
|
|
533
|
+
.replaceAll("{{releases}}", `${values.releases}\n${release_js_1.RELEASES_END_MARKER}`)
|
|
497
534
|
.replaceAll("{{version}}", value(values.version));
|
|
498
535
|
return (0, release_js_1.applyOutputIndexLanguageSwitcher)(rendered, values.languages);
|
|
499
536
|
}
|
|
500
|
-
function localizeExistingIndexEntries(content, format, copy) {
|
|
501
|
-
if (format === "markdown") {
|
|
502
|
-
return content
|
|
503
|
-
.replace(/(<!-- ai-release-notes:release [^>]+ -->\n## )(?:Release|Versión|Version)\s+/g, (_match, prefix) => `${prefix}${copy.release} `)
|
|
504
|
-
.replace(/(^_[^\n]*? · [^\n]*? · )(?:Changes since|Cambios desde|Changements depuis)\s+/gm, (_match, prefix) => `${prefix}${copy.changesSince} `)
|
|
505
|
-
.replace(/\[(?:Read release notes|Ver notas de la versión|Voir les notes de version) →\]/g, `[${copy.readReleaseNotes} →]`);
|
|
506
|
-
}
|
|
507
|
-
return content
|
|
508
|
-
.replace(/(<section class="release-entry">\n<h2>)(?:Release|Versión|Version)\s+/g, (_match, prefix) => `${prefix}${escapeHtml(copy.release)} `)
|
|
509
|
-
.replace(/(<p class="release-meta">.*? · .*? · )(?:Changes since|Cambios desde|Changements depuis)\s+/g, (_match, prefix) => `${prefix}${escapeHtml(copy.changesSince)} `)
|
|
510
|
-
.replace(/(<a href="[^"]+">)(?:Read release notes|Ver notas de la versión|Voir les notes de version)(?= <span aria-hidden="true">→<\/span><\/a>)/g, (_match, prefix) => `${prefix}${escapeHtml(copy.readReleaseNotes)}`)
|
|
511
|
-
.replace(/<p class="release-meta">(?!<em>)([\s\S]*?)<\/p>/g, (_match, metadata) => `<p class="release-meta"><em>${metadata}</em></p>`);
|
|
512
|
-
}
|
|
513
|
-
function localizeExistingIndexChrome(content, format, indexTitle, intro) {
|
|
514
|
-
if (format === "markdown") {
|
|
515
|
-
return content
|
|
516
|
-
.replace(/^# .*?(?:release notes|release index)\s*$/im, `# ${indexTitle}`)
|
|
517
|
-
.replace(/^A concise release history for .*?\. The newest release is listed first\.\s*$/im, intro);
|
|
518
|
-
}
|
|
519
|
-
return content
|
|
520
|
-
.replace(/<title>.*?(?:release notes|release index)<\/title>/i, `<title>${escapeHtml(indexTitle)}</title>`)
|
|
521
|
-
.replace(/<h1>.*?(?:release notes|release index)<\/h1>/i, `<h1>${escapeHtml(indexTitle)}</h1>`)
|
|
522
|
-
.replace(/<p class="intro">A concise release history for .*?\. The newest release is listed first\.<\/p>/i, `<p class="intro">${escapeHtml(intro)}</p>`);
|
|
523
|
-
}
|
|
524
|
-
function getOutputIndexCopy(language) {
|
|
525
|
-
const code = language ? languageCode(language) : undefined;
|
|
526
|
-
if (code === "es") {
|
|
527
|
-
return {
|
|
528
|
-
release: "Versión",
|
|
529
|
-
releaseNotes: "Notas de la versión",
|
|
530
|
-
intro: (environment) => `Un historial conciso de versiones para ${environment}. Las más recientes aparecen primero.`,
|
|
531
|
-
changesSince: "Cambios desde",
|
|
532
|
-
readReleaseNotes: "Ver notas de la versión",
|
|
533
|
-
};
|
|
534
|
-
}
|
|
535
|
-
if (code === "fr") {
|
|
536
|
-
return {
|
|
537
|
-
release: "Version",
|
|
538
|
-
releaseNotes: "Notes de version",
|
|
539
|
-
intro: (environment) => `Un historique concis des versions pour ${environment}. Les plus récentes apparaissent en premier.`,
|
|
540
|
-
changesSince: "Changements depuis",
|
|
541
|
-
readReleaseNotes: "Voir les notes de version",
|
|
542
|
-
};
|
|
543
|
-
}
|
|
544
|
-
return {
|
|
545
|
-
release: "Release",
|
|
546
|
-
releaseNotes: "Release notes",
|
|
547
|
-
intro: (environment) => `A concise release history for ${environment}. The newest release is listed first.`,
|
|
548
|
-
changesSince: "Changes since",
|
|
549
|
-
readReleaseNotes: "Read release notes",
|
|
550
|
-
};
|
|
551
|
-
}
|
|
552
537
|
function localizeIndexDate(date, language) {
|
|
553
538
|
if (!language)
|
|
554
539
|
return date;
|
|
@@ -566,59 +551,17 @@ function shouldTranslateTemplate(templateLanguage, outputLanguage) {
|
|
|
566
551
|
return false;
|
|
567
552
|
return languageCode(templateLanguage) !== languageCode(outputLanguage);
|
|
568
553
|
}
|
|
569
|
-
function shouldTranslateOutputIndexCopy(language) {
|
|
570
|
-
return Boolean(language && languageCode(language) !== "en");
|
|
571
|
-
}
|
|
572
|
-
async function translateOutputIndexCopy(language, providerName, providerConfig) {
|
|
573
|
-
const result = await (0, llm_js_1.callLLM)(providerName, providerConfig, "You translate the labels used in a release-summary index. Return only valid JSON with these string keys: " +
|
|
574
|
-
"release, releaseNotes, intro, changesSince, readReleaseNotes. " +
|
|
575
|
-
"The intro value must preserve {{environment}} exactly. Do not include Markdown, HTML, or explanations.", `Target language: ${language}\n\nEnglish source:\n` +
|
|
576
|
-
JSON.stringify({
|
|
577
|
-
release: "Release",
|
|
578
|
-
releaseNotes: "Release notes",
|
|
579
|
-
intro: "A concise release history for {{environment}}. The newest release is listed first.",
|
|
580
|
-
changesSince: "Changes since",
|
|
581
|
-
readReleaseNotes: "Read release notes",
|
|
582
|
-
}));
|
|
583
|
-
const rawJson = result.text.trim().replace(/^```(?:json)?\s*/i, "").replace(/\s*```$/, "");
|
|
584
|
-
let translated;
|
|
585
|
-
try {
|
|
586
|
-
translated = JSON.parse(rawJson);
|
|
587
|
-
}
|
|
588
|
-
catch {
|
|
589
|
-
throw new Error("Could not parse translated output-index labels as JSON");
|
|
590
|
-
}
|
|
591
|
-
if (!isOutputIndexCopyTranslation(translated)) {
|
|
592
|
-
throw new Error("Translated output-index labels are incomplete");
|
|
593
|
-
}
|
|
594
|
-
return {
|
|
595
|
-
copy: {
|
|
596
|
-
release: translated.release,
|
|
597
|
-
releaseNotes: translated.releaseNotes,
|
|
598
|
-
intro: (environment) => translated.intro.replaceAll("{{environment}}", environment),
|
|
599
|
-
changesSince: translated.changesSince,
|
|
600
|
-
readReleaseNotes: translated.readReleaseNotes,
|
|
601
|
-
},
|
|
602
|
-
usage: result.usage,
|
|
603
|
-
};
|
|
604
|
-
}
|
|
605
|
-
function isOutputIndexCopyTranslation(value) {
|
|
606
|
-
if (!value || typeof value !== "object")
|
|
607
|
-
return false;
|
|
608
|
-
const candidate = value;
|
|
609
|
-
return ["release", "releaseNotes", "intro", "changesSince", "readReleaseNotes"]
|
|
610
|
-
.every((key) => typeof candidate[key] === "string" && candidate[key].trim().length > 0)
|
|
611
|
-
&& typeof candidate.intro === "string"
|
|
612
|
-
&& candidate.intro.includes("{{environment}}");
|
|
613
|
-
}
|
|
614
554
|
async function translateOutputIndexTemplate(template, language, providerName, providerConfig) {
|
|
615
555
|
const protectedTemplate = protectTemplateTokens(template);
|
|
616
556
|
const result = await (0, llm_js_1.callLLM)(providerName, providerConfig, "You translate release-summary templates. Return only the translated template. " +
|
|
617
557
|
"Translate every human-readable sentence into the requested language, but preserve all HTML, CSS, Markdown syntax, URLs, and protected tokens exactly.", `Target language: ${language}\n\nTemplate:\n${protectedTemplate.template}`);
|
|
618
558
|
const translated = unwrapHtmlDocumentCodeFence(restoreTemplateTokens(result.text, protectedTemplate.tokens));
|
|
619
|
-
if (!translated.includes(RELEASES_MARKER) || !translated.includes("{{releases}}")) {
|
|
559
|
+
if (!translated.includes(release_js_1.RELEASES_MARKER) || !translated.includes("{{releases}}")) {
|
|
620
560
|
throw new Error("Translated output-index template did not preserve the required releases marker or {{releases}} token");
|
|
621
561
|
}
|
|
562
|
+
if (template.includes(ENTRY_TEMPLATE_SEPARATOR) && !translated.includes(ENTRY_TEMPLATE_SEPARATOR)) {
|
|
563
|
+
throw new Error("Translated output-index template did not preserve its entry template");
|
|
564
|
+
}
|
|
622
565
|
return { text: translated, usage: result.usage };
|
|
623
566
|
}
|
|
624
567
|
/** Models occasionally wrap an HTML template in a Markdown code fence. */
|
|
@@ -632,7 +575,10 @@ function unwrapHtmlDocumentCodeFence(content) {
|
|
|
632
575
|
}
|
|
633
576
|
function protectTemplateTokens(template) {
|
|
634
577
|
const values = [
|
|
635
|
-
RELEASES_MARKER,
|
|
578
|
+
release_js_1.RELEASES_MARKER,
|
|
579
|
+
// The entry template travels with the summary. Its labels are meant to be
|
|
580
|
+
// translated; what separates and names its parts is not.
|
|
581
|
+
ENTRY_TEMPLATE_SEPARATOR,
|
|
636
582
|
"{{projectName}}",
|
|
637
583
|
"{{environment}}",
|
|
638
584
|
"{{language}}",
|
|
@@ -641,6 +587,11 @@ function protectTemplateTokens(template) {
|
|
|
641
587
|
"{{date}}",
|
|
642
588
|
"{{releases}}",
|
|
643
589
|
"{{version}}",
|
|
590
|
+
"{{fromVersion}}",
|
|
591
|
+
"{{toVersion}}",
|
|
592
|
+
"{{fromToComparison}}",
|
|
593
|
+
"{{links}}",
|
|
594
|
+
"{{href}}",
|
|
644
595
|
];
|
|
645
596
|
const tokens = values.map((value, index) => [value, `__AI_RELEASE_TEMPLATE_TOKEN_${index}__`]);
|
|
646
597
|
return {
|
|
@@ -661,19 +612,19 @@ function languageCode(language) {
|
|
|
661
612
|
return language.toLowerCase().split(/[-_]/, 1)[0];
|
|
662
613
|
}
|
|
663
614
|
function ensureOutputIndexReleaseBoundary(content, format) {
|
|
664
|
-
if (!content.includes(RELEASES_MARKER) || content.includes(RELEASES_END_MARKER)) {
|
|
615
|
+
if (!content.includes(release_js_1.RELEASES_MARKER) || content.includes(release_js_1.RELEASES_END_MARKER)) {
|
|
665
616
|
return content;
|
|
666
617
|
}
|
|
667
|
-
const releasesStart = content.indexOf(RELEASES_MARKER) + RELEASES_MARKER.length;
|
|
668
|
-
const
|
|
669
|
-
|
|
670
|
-
|
|
671
|
-
|
|
672
|
-
|
|
618
|
+
const releasesStart = content.indexOf(release_js_1.RELEASES_MARKER) + release_js_1.RELEASES_MARKER.length;
|
|
619
|
+
const boundary = [
|
|
620
|
+
format === "html"
|
|
621
|
+
? content.indexOf("</main>", releasesStart)
|
|
622
|
+
: content.indexOf("\n---\n", releasesStart),
|
|
623
|
+
].filter((index) => index >= 0)[0];
|
|
673
624
|
if (boundary === undefined) {
|
|
674
|
-
return `${content.trimEnd()}\n${RELEASES_END_MARKER}\n`;
|
|
625
|
+
return `${content.trimEnd()}\n${release_js_1.RELEASES_END_MARKER}\n`;
|
|
675
626
|
}
|
|
676
|
-
return `${content.slice(0, boundary).trimEnd()}\n${RELEASES_END_MARKER}\n${content.slice(boundary).replace(/^\n/, "")}`;
|
|
627
|
+
return `${content.slice(0, boundary).trimEnd()}\n${release_js_1.RELEASES_END_MARKER}\n${content.slice(boundary).replace(/^\n/, "")}`;
|
|
677
628
|
}
|
|
678
629
|
function toRelativeLink(fromPath, toPath) {
|
|
679
630
|
return (0, path_1.relative)((0, path_1.dirname)(fromPath), toPath)
|
|
@@ -695,7 +646,15 @@ function formatNumber(value) {
|
|
|
695
646
|
function formatDuration(durationMs) {
|
|
696
647
|
return `${(durationMs / 1000).toFixed(1)}s`;
|
|
697
648
|
}
|
|
698
|
-
async function saveReleaseNotes(outputPath, content, markdown) {
|
|
649
|
+
async function saveReleaseNotes(outputPath, content, markdown, ownedByRelease) {
|
|
650
|
+
// A file that belongs to a single release always holds that release as it
|
|
651
|
+
// was last generated: regenerating rewrites it, so re-running the same
|
|
652
|
+
// command twice can never leave two copies behind.
|
|
653
|
+
if (ownedByRelease) {
|
|
654
|
+
const replaced = (0, fs_1.existsSync)(outputPath);
|
|
655
|
+
await (0, promises_1.writeFile)(outputPath, outputPath.endsWith(".html") ? content : content.trim() + "\n", "utf-8");
|
|
656
|
+
return replaced ? "replaced" : "saved";
|
|
657
|
+
}
|
|
699
658
|
const existing = (0, fs_1.existsSync)(outputPath) ? await (0, promises_1.readFile)(outputPath, "utf-8") : "";
|
|
700
659
|
// Probe the form that was actually written: a Markdown heading line never
|
|
701
660
|
// appears in rendered HTML, so comparing one against the other reports every
|