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 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. Index templates can place links between those summaries with
168
- `{{languages}}` (or `{{langages}}`). The switcher merges languages from the
169
- current prompt with localized index files already present on disk. An index
170
- template is assumed to be written in the first `prompt.languages` entry, and
171
- an index in any other language is translated.
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>", 'Previous version tag, or "start" for the full history', "start")
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) => path.includes("{lang}")
187
- ? generatedResult.localized.map((release) => ({
188
- path: getOutputPath(path, opts.env, release.language, opts.from, opts.to),
189
- markdown: release.markdown,
190
- html: release.html,
191
- format: output.format,
192
- language: release.language,
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 || "start")
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
- const normalizedExisting = params.format === "html"
421
- ? unwrapHtmlDocumentCodeFence(existing)
422
- : existing;
423
- const boundedExisting = ensureOutputIndexReleaseBoundary(normalizedExisting, params.format);
424
- const updated = (0, release_js_1.insertOrUpdateOutputIndexReleaseEntry)(localizeExistingIndexEntries(localizeExistingIndexChrome(boundedExisting, params.format, indexTitle, intro), params.format, copy), releaseEntry, releaseId);
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 loadOutputIndexTemplate(params.templatePath, params.format);
433
- const localizedTemplate = params.translateTemplate
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: localizedDate,
441
- releases: releaseEntry,
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, "Release index", "", { trustedHtml: true });
466
+ : (0, release_js_1.markdownToHtml)(rendered, { trustedHtml: true });
455
467
  return html;
456
468
  }
457
- function buildOutputIndexEntry(params, releaseId, copy, localizedDate) {
458
- const releasePaths = [...new Set(params.releasePaths)];
459
- const marker = `<!-- ai-release-notes:release ${releaseId} -->`;
460
- const title = `${copy.release} ${params.toVersion}`;
461
- const metadata = `${params.environment} · ${localizedDate} · ${copy.changesSince} ${params.fromVersion}`;
462
- if (params.format === "html") {
463
- const links = releasePaths
464
- .map((path) => {
465
- const href = escapeHtml(toRelativeLink(params.outputPath, path));
466
- return `<a href="${href}">${escapeHtml(copy.readReleaseNotes)} <span aria-hidden="true">→</span></a>`;
467
- })
468
- .join("\n");
469
- return `${marker}\n<section class="release-entry">\n<h2>${escapeHtml(title)}</h2>\n<p class="release-meta"><em>${escapeHtml(metadata)}</em></p>\n<p class="release-link">${links}</p>\n</section>`;
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
- const links = releasePaths
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
- const extension = format === "html" ? "html" : "md";
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 candidates = [content.indexOf("<!-- ai-release-notes:languages -->", releasesStart)];
669
- candidates.push(format === "html"
670
- ? content.indexOf("</main>", releasesStart)
671
- : content.indexOf("\n---\n", releasesStart));
672
- const boundary = candidates.filter((index) => index >= 0).sort((a, b) => a - b)[0];
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