ai-release-notes 0.1.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/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,26 +183,34 @@ 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
  }
203
208
  const outputIndexConfigs = loadedConfig.outputIndex
204
209
  ? (Array.isArray(loadedConfig.outputIndex) ? loadedConfig.outputIndex : [loadedConfig.outputIndex])
205
210
  : [];
211
+ // An index template is written in the language the release is generated
212
+ // in, so prompt.languages already answers this.
213
+ const primaryLanguage = generatedResult.localized[0]?.language ?? "en";
206
214
  const outputIndexTargets = outputIndexConfigs.flatMap((outputIndex, groupId) => outputIndex.saveTo.includes("{lang}")
207
215
  ? generatedResult.localized.map((release) => ({
208
216
  path: (0, path_1.resolve)(getOutputPath(outputIndex.saveTo, opts.env, release.language, opts.from, opts.to)),
@@ -210,14 +218,16 @@ program
210
218
  language: release.language,
211
219
  format: outputIndex.format,
212
220
  templatePath: outputIndex.template,
213
- templateLanguage: outputIndex.templateLanguage,
221
+ entryTemplatePath: outputIndex.entryTemplate,
222
+ templateLanguage: primaryLanguage,
214
223
  }))
215
224
  : [{
216
225
  path: (0, path_1.resolve)(getOutputPath(outputIndex.saveTo, opts.env, undefined, opts.from, opts.to)),
217
226
  groupId,
218
227
  format: outputIndex.format,
219
228
  templatePath: outputIndex.template,
220
- templateLanguage: outputIndex.templateLanguage,
229
+ entryTemplatePath: outputIndex.entryTemplate,
230
+ templateLanguage: primaryLanguage,
221
231
  }]);
222
232
  if (outputIndexTargets.some((index) => outputTargets.some((target) => (0, path_1.resolve)(target.path) === index.path))) {
223
233
  throw new Error("outputIndex.saveTo must be different from every output.saveTo path");
@@ -254,16 +264,18 @@ program
254
264
  const content = target.format === "html" && target.html
255
265
  ? target.html
256
266
  : target.markdown;
257
- 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);
258
268
  if (saved === "skipped") {
259
269
  console.log(chalk_1.default.yellow("ℹ️ Release " + fromVersion + " → " + toVersion + " is already in " + outputPath));
260
270
  }
271
+ else if (saved === "replaced") {
272
+ console.log(chalk_1.default.green("💾 Replaced " + outputPath));
273
+ }
261
274
  else {
262
275
  console.log(chalk_1.default.green("💾 Saved to " + outputPath));
263
276
  }
264
277
  }
265
278
  if (outputIndexTargets.length > 0 && outputTargets.length > 0) {
266
- const translatedCopyCache = new Map();
267
279
  for (const index of outputIndexTargets) {
268
280
  await (0, promises_1.mkdir)((0, path_1.dirname)(index.path), { recursive: true });
269
281
  const releasePaths = getReleasePathsForIndex(index, outputTargets);
@@ -272,6 +284,7 @@ program
272
284
  outputPath: index.path,
273
285
  format: index.format,
274
286
  templatePath: index.templatePath,
287
+ entryTemplatePath: index.entryTemplatePath,
275
288
  translateTemplate: !opts.dryRun && shouldTranslateTemplate(index.templateLanguage, index.language)
276
289
  ? async (template) => {
277
290
  const translated = await translateOutputIndexTemplate(template, index.language, generatedResult.metadata.provider, loadedConfig.providers[generatedResult.metadata.provider]);
@@ -279,21 +292,6 @@ program
279
292
  return translated.text;
280
293
  }
281
294
  : undefined,
282
- translateCopy: !opts.dryRun && shouldTranslateOutputIndexCopy(index.language)
283
- ? () => {
284
- const language = index.language;
285
- const key = languageCode(language);
286
- let translated = translatedCopyCache.get(key);
287
- if (!translated) {
288
- translated = translateOutputIndexCopy(language, generatedResult.metadata.provider, loadedConfig.providers[generatedResult.metadata.provider]).then(({ copy, usage }) => {
289
- addTemplateUsage(generatedResult.metadata.usage, usage);
290
- return copy;
291
- });
292
- translatedCopyCache.set(key, translated);
293
- }
294
- return translated;
295
- }
296
- : undefined,
297
295
  projectName: loadedConfig.projectName,
298
296
  environment: opts.env,
299
297
  language: index.language,
@@ -318,8 +316,8 @@ program
318
316
  if (!hasLanguageSwitcher &&
319
317
  !existingIndex.templatePath &&
320
318
  languageLinks.length > 1 &&
321
- existing.includes(RELEASES_MARKER)) {
322
- 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}`);
323
321
  }
324
322
  if (updated !== existing) {
325
323
  await (0, promises_1.writeFile)(existingIndex.path, updated, "utf-8");
@@ -374,9 +372,19 @@ function getOutputPath(saveTo, environment, language, fromVersion, toVersion) {
374
372
  return saveTo
375
373
  .replaceAll("{env}", normalizedEnvironment)
376
374
  .replaceAll("{lang}", normalizedLanguage || "{lang}")
377
- .replaceAll("{from}", fromVersion || "start")
375
+ .replaceAll("{from}", fromVersion || git_js_1.FIRST_RELEASE)
378
376
  .replaceAll("{to}", toVersion || "end");
379
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
+ }
380
388
  function getReleasePathsForIndex(index, outputTargets) {
381
389
  const languageTargets = outputTargets.filter((target) => !index.language || !target.language || target.language === index.language);
382
390
  const preferredFormat = index.format;
@@ -398,44 +406,51 @@ function getOutputIndexLanguageLinks(index, targets) {
398
406
  active: candidate.path.toLowerCase() === index.path.toLowerCase(),
399
407
  }));
400
408
  }
401
- const RELEASES_MARKER = "<!-- ai-release-notes:releases -->";
402
- const RELEASES_END_MARKER = "<!-- ai-release-notes:/releases -->";
403
409
  async function createOrUpdateOutputIndex(params) {
404
- const copy = params.translateCopy
405
- ? await params.translateCopy()
406
- : getOutputIndexCopy(params.language);
407
- const localizedDate = localizeIndexDate(params.date, params.language);
408
- const releaseId = [params.environment, params.fromVersion, params.toVersion]
409
- .map((value) => encodeURIComponent(value))
410
- .join("_");
411
- const releaseEntry = buildOutputIndexEntry(params, releaseId, copy, localizedDate);
412
- const indexTitle = `${params.projectName ? params.projectName + " · " : ""}${copy.releaseNotes}`;
413
- const intro = copy.intro(params.environment);
414
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
+ });
415
424
  if ((0, fs_1.existsSync)(params.outputPath)) {
416
425
  const existing = await (0, promises_1.readFile)(params.outputPath, "utf-8");
417
- const normalizedExisting = params.format === "html"
418
- ? unwrapHtmlDocumentCodeFence(existing)
419
- : existing;
420
- const boundedExisting = ensureOutputIndexReleaseBoundary(normalizedExisting, params.format);
421
- 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"));
422
440
  const hasLanguageSwitcher = (0, release_js_1.hasOutputIndexLanguageSwitcher)(updated);
423
441
  const withLanguageSwitcher = (0, release_js_1.applyOutputIndexLanguageSwitcher)(updated, languageSwitcher);
424
442
  if (!params.templatePath && params.languageLinks.length > 1 && !hasLanguageSwitcher) {
425
- 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}`);
426
444
  }
427
445
  return withLanguageSwitcher;
428
446
  }
429
- const template = await loadOutputIndexTemplate(params.templatePath, params.format);
430
- const localizedTemplate = params.translateTemplate
431
- ? await params.translateTemplate(template)
432
- : template;
433
- const rendered = renderOutputIndexTemplate(localizedTemplate, {
447
+ const { template, entryTemplate } = await loadOutputIndexEntryTemplate(params);
448
+ const rendered = renderOutputIndexTemplate(template, {
434
449
  projectName: params.projectName || "Project",
435
450
  environment: params.environment,
436
451
  language: params.language || "",
437
- date: localizedDate,
438
- releases: releaseEntry,
452
+ date: localizeIndexDate(params.date, params.language),
453
+ releases: renderReleases([record], entryTemplate),
439
454
  languages: languageSwitcher,
440
455
  version: CLI_VERSION,
441
456
  }, params.format);
@@ -448,32 +463,53 @@ async function createOrUpdateOutputIndex(params) {
448
463
  // never gets that trust.
449
464
  const html = isHtmlTemplate
450
465
  ? rendered
451
- : (0, release_js_1.markdownToHtml)(rendered, "Release index", "", { trustedHtml: true });
466
+ : (0, release_js_1.markdownToHtml)(rendered, { trustedHtml: true });
452
467
  return html;
453
468
  }
454
- function buildOutputIndexEntry(params, releaseId, copy, localizedDate) {
455
- const releasePaths = [...new Set(params.releasePaths)];
456
- const marker = `<!-- ai-release-notes:release ${releaseId} -->`;
457
- const title = `${copy.release} ${params.toVersion}`;
458
- const metadata = `${params.environment} · ${localizedDate} · ${copy.changesSince} ${params.fromVersion}`;
459
- if (params.format === "html") {
460
- const links = releasePaths
461
- .map((path) => {
462
- const href = escapeHtml(toRelativeLink(params.outputPath, path));
463
- return `<a href="${href}">${escapeHtml(copy.readReleaseNotes)} <span aria-hidden="true">→</span></a>`;
464
- })
465
- .join("\n");
466
- 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}`);
467
507
  }
468
- const links = releasePaths
469
- .map((path) => `[${copy.readReleaseNotes} →](${toRelativeLink(params.outputPath, path)})`)
470
- .join("\n");
471
- return `${marker}\n## ${title}\n\n_${metadata}_\n\n${links}`;
508
+ return (0, promises_1.readFile)(resolvedPath, "utf-8");
472
509
  }
473
510
  async function loadOutputIndexTemplate(templatePath, format) {
474
511
  if (!templatePath) {
475
- const extension = format === "html" ? "html" : "md";
476
- return (0, promises_1.readFile)((0, path_1.resolve)(__dirname, `../../templates/default-release-summary.${extension}`), "utf-8");
512
+ return loadBundledTemplate("default-release-summary", format);
477
513
  }
478
514
  const resolvedTemplatePath = (0, path_1.resolve)(templatePath);
479
515
  if (!(0, fs_1.existsSync)(resolvedTemplatePath)) {
@@ -481,6 +517,10 @@ async function loadOutputIndexTemplate(templatePath, format) {
481
517
  }
482
518
  return (0, promises_1.readFile)(resolvedTemplatePath, "utf-8");
483
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
+ }
484
524
  function renderOutputIndexTemplate(template, values, format = "markdown") {
485
525
  // A project name and an environment reach an HTML index straight from config
486
526
  // and the command line, so they are escaped like every other value there.
@@ -490,62 +530,10 @@ function renderOutputIndexTemplate(template, values, format = "markdown") {
490
530
  .replaceAll("{{environment}}", value(values.environment))
491
531
  .replaceAll("{{language}}", value(values.language))
492
532
  .replaceAll("{{date}}", value(values.date))
493
- .replaceAll("{{releases}}", `${values.releases}\n${RELEASES_END_MARKER}`)
533
+ .replaceAll("{{releases}}", `${values.releases}\n${release_js_1.RELEASES_END_MARKER}`)
494
534
  .replaceAll("{{version}}", value(values.version));
495
535
  return (0, release_js_1.applyOutputIndexLanguageSwitcher)(rendered, values.languages);
496
536
  }
497
- function localizeExistingIndexEntries(content, format, copy) {
498
- if (format === "markdown") {
499
- return content
500
- .replace(/(<!-- ai-release-notes:release [^>]+ -->\n## )(?:Release|Versión|Version)\s+/g, (_match, prefix) => `${prefix}${copy.release} `)
501
- .replace(/(^_[^\n]*? · [^\n]*? · )(?:Changes since|Cambios desde|Changements depuis)\s+/gm, (_match, prefix) => `${prefix}${copy.changesSince} `)
502
- .replace(/\[(?:Read release notes|Ver notas de la versión|Voir les notes de version) →\]/g, `[${copy.readReleaseNotes} →]`);
503
- }
504
- return content
505
- .replace(/(<section class="release-entry">\n<h2>)(?:Release|Versión|Version)\s+/g, (_match, prefix) => `${prefix}${escapeHtml(copy.release)} `)
506
- .replace(/(<p class="release-meta">.*? · .*? · )(?:Changes since|Cambios desde|Changements depuis)\s+/g, (_match, prefix) => `${prefix}${escapeHtml(copy.changesSince)} `)
507
- .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)}`)
508
- .replace(/<p class="release-meta">(?!<em>)([\s\S]*?)<\/p>/g, (_match, metadata) => `<p class="release-meta"><em>${metadata}</em></p>`);
509
- }
510
- function localizeExistingIndexChrome(content, format, indexTitle, intro) {
511
- if (format === "markdown") {
512
- return content
513
- .replace(/^# .*?(?:release notes|release index)\s*$/im, `# ${indexTitle}`)
514
- .replace(/^A concise release history for .*?\. The newest release is listed first\.\s*$/im, intro);
515
- }
516
- return content
517
- .replace(/<title>.*?(?:release notes|release index)<\/title>/i, `<title>${escapeHtml(indexTitle)}</title>`)
518
- .replace(/<h1>.*?(?:release notes|release index)<\/h1>/i, `<h1>${escapeHtml(indexTitle)}</h1>`)
519
- .replace(/<p class="intro">A concise release history for .*?\. The newest release is listed first\.<\/p>/i, `<p class="intro">${escapeHtml(intro)}</p>`);
520
- }
521
- function getOutputIndexCopy(language) {
522
- const code = language ? languageCode(language) : undefined;
523
- if (code === "es") {
524
- return {
525
- release: "Versión",
526
- releaseNotes: "Notas de la versión",
527
- intro: (environment) => `Un historial conciso de versiones para ${environment}. Las más recientes aparecen primero.`,
528
- changesSince: "Cambios desde",
529
- readReleaseNotes: "Ver notas de la versión",
530
- };
531
- }
532
- if (code === "fr") {
533
- return {
534
- release: "Version",
535
- releaseNotes: "Notes de version",
536
- intro: (environment) => `Un historique concis des versions pour ${environment}. Les plus récentes apparaissent en premier.`,
537
- changesSince: "Changements depuis",
538
- readReleaseNotes: "Voir les notes de version",
539
- };
540
- }
541
- return {
542
- release: "Release",
543
- releaseNotes: "Release notes",
544
- intro: (environment) => `A concise release history for ${environment}. The newest release is listed first.`,
545
- changesSince: "Changes since",
546
- readReleaseNotes: "Read release notes",
547
- };
548
- }
549
537
  function localizeIndexDate(date, language) {
550
538
  if (!language)
551
539
  return date;
@@ -563,59 +551,17 @@ function shouldTranslateTemplate(templateLanguage, outputLanguage) {
563
551
  return false;
564
552
  return languageCode(templateLanguage) !== languageCode(outputLanguage);
565
553
  }
566
- function shouldTranslateOutputIndexCopy(language) {
567
- return Boolean(language && languageCode(language) !== "en");
568
- }
569
- async function translateOutputIndexCopy(language, providerName, providerConfig) {
570
- 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: " +
571
- "release, releaseNotes, intro, changesSince, readReleaseNotes. " +
572
- "The intro value must preserve {{environment}} exactly. Do not include Markdown, HTML, or explanations.", `Target language: ${language}\n\nEnglish source:\n` +
573
- JSON.stringify({
574
- release: "Release",
575
- releaseNotes: "Release notes",
576
- intro: "A concise release history for {{environment}}. The newest release is listed first.",
577
- changesSince: "Changes since",
578
- readReleaseNotes: "Read release notes",
579
- }));
580
- const rawJson = result.text.trim().replace(/^```(?:json)?\s*/i, "").replace(/\s*```$/, "");
581
- let translated;
582
- try {
583
- translated = JSON.parse(rawJson);
584
- }
585
- catch {
586
- throw new Error("Could not parse translated output-index labels as JSON");
587
- }
588
- if (!isOutputIndexCopyTranslation(translated)) {
589
- throw new Error("Translated output-index labels are incomplete");
590
- }
591
- return {
592
- copy: {
593
- release: translated.release,
594
- releaseNotes: translated.releaseNotes,
595
- intro: (environment) => translated.intro.replaceAll("{{environment}}", environment),
596
- changesSince: translated.changesSince,
597
- readReleaseNotes: translated.readReleaseNotes,
598
- },
599
- usage: result.usage,
600
- };
601
- }
602
- function isOutputIndexCopyTranslation(value) {
603
- if (!value || typeof value !== "object")
604
- return false;
605
- const candidate = value;
606
- return ["release", "releaseNotes", "intro", "changesSince", "readReleaseNotes"]
607
- .every((key) => typeof candidate[key] === "string" && candidate[key].trim().length > 0)
608
- && typeof candidate.intro === "string"
609
- && candidate.intro.includes("{{environment}}");
610
- }
611
554
  async function translateOutputIndexTemplate(template, language, providerName, providerConfig) {
612
555
  const protectedTemplate = protectTemplateTokens(template);
613
556
  const result = await (0, llm_js_1.callLLM)(providerName, providerConfig, "You translate release-summary templates. Return only the translated template. " +
614
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}`);
615
558
  const translated = unwrapHtmlDocumentCodeFence(restoreTemplateTokens(result.text, protectedTemplate.tokens));
616
- if (!translated.includes(RELEASES_MARKER) || !translated.includes("{{releases}}")) {
559
+ if (!translated.includes(release_js_1.RELEASES_MARKER) || !translated.includes("{{releases}}")) {
617
560
  throw new Error("Translated output-index template did not preserve the required releases marker or {{releases}} token");
618
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
+ }
619
565
  return { text: translated, usage: result.usage };
620
566
  }
621
567
  /** Models occasionally wrap an HTML template in a Markdown code fence. */
@@ -629,7 +575,10 @@ function unwrapHtmlDocumentCodeFence(content) {
629
575
  }
630
576
  function protectTemplateTokens(template) {
631
577
  const values = [
632
- 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,
633
582
  "{{projectName}}",
634
583
  "{{environment}}",
635
584
  "{{language}}",
@@ -638,6 +587,11 @@ function protectTemplateTokens(template) {
638
587
  "{{date}}",
639
588
  "{{releases}}",
640
589
  "{{version}}",
590
+ "{{fromVersion}}",
591
+ "{{toVersion}}",
592
+ "{{fromToComparison}}",
593
+ "{{links}}",
594
+ "{{href}}",
641
595
  ];
642
596
  const tokens = values.map((value, index) => [value, `__AI_RELEASE_TEMPLATE_TOKEN_${index}__`]);
643
597
  return {
@@ -658,19 +612,19 @@ function languageCode(language) {
658
612
  return language.toLowerCase().split(/[-_]/, 1)[0];
659
613
  }
660
614
  function ensureOutputIndexReleaseBoundary(content, format) {
661
- 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)) {
662
616
  return content;
663
617
  }
664
- const releasesStart = content.indexOf(RELEASES_MARKER) + RELEASES_MARKER.length;
665
- const candidates = [content.indexOf("<!-- ai-release-notes:languages -->", releasesStart)];
666
- candidates.push(format === "html"
667
- ? content.indexOf("</main>", releasesStart)
668
- : content.indexOf("\n---\n", releasesStart));
669
- 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];
670
624
  if (boundary === undefined) {
671
- return `${content.trimEnd()}\n${RELEASES_END_MARKER}\n`;
625
+ return `${content.trimEnd()}\n${release_js_1.RELEASES_END_MARKER}\n`;
672
626
  }
673
- 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/, "")}`;
674
628
  }
675
629
  function toRelativeLink(fromPath, toPath) {
676
630
  return (0, path_1.relative)((0, path_1.dirname)(fromPath), toPath)
@@ -692,10 +646,21 @@ function formatNumber(value) {
692
646
  function formatDuration(durationMs) {
693
647
  return `${(durationMs / 1000).toFixed(1)}s`;
694
648
  }
695
- async function saveReleaseNotes(outputPath, content, markdown) {
696
- const header = markdown.split("\n", 1)[0];
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
+ }
697
658
  const existing = (0, fs_1.existsSync)(outputPath) ? await (0, promises_1.readFile)(outputPath, "utf-8") : "";
698
- if (existing.includes(header))
659
+ // Probe the form that was actually written: a Markdown heading line never
660
+ // appears in rendered HTML, so comparing one against the other reports every
661
+ // regeneration as new and appends a second copy of the same release.
662
+ const header = releaseIdentityProbe(outputPath, content, markdown);
663
+ if (header && existing.includes(header))
699
664
  return "skipped";
700
665
  const merged = outputPath.endsWith(".html")
701
666
  ? appendHtmlRelease(existing, content)
@@ -705,6 +670,22 @@ async function saveReleaseNotes(outputPath, content, markdown) {
705
670
  await (0, promises_1.writeFile)(outputPath, merged, "utf-8");
706
671
  return "saved";
707
672
  }
673
+ /**
674
+ * The line that identifies a release inside the file being written.
675
+ *
676
+ * For HTML that is the rendered title heading; for Markdown, the first line.
677
+ * Returns an empty string when neither is available, which saves rather than
678
+ * risks discarding a release as a false duplicate.
679
+ */
680
+ function releaseIdentityProbe(outputPath, content, markdown) {
681
+ if (!outputPath.endsWith(".html"))
682
+ return markdown.split("\n", 1)[0];
683
+ const heading = /<h([12])>[\s\S]*?<\/h\1>/.exec(content);
684
+ if (heading)
685
+ return heading[0];
686
+ const title = /<title>[\s\S]*?<\/title>/.exec(content);
687
+ return title ? title[0] : "";
688
+ }
708
689
  function appendHtmlRelease(existing, content) {
709
690
  if (!existing.trim())
710
691
  return content;