@releasekit/notes 0.42.0 → 0.42.1

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.
@@ -2,8 +2,8 @@ import {
2
2
  aggregateToRoot,
3
3
  detectMonorepo,
4
4
  writeMonorepoChangelogs
5
- } from "./chunk-OEY4SBEM.js";
6
- import "./chunk-LA3V665B.js";
5
+ } from "./chunk-KQQPQQSS.js";
6
+ import "./chunk-CBMVDKDR.js";
7
7
  export {
8
8
  aggregateToRoot,
9
9
  detectMonorepo,
@@ -9,9 +9,9 @@ import chalk from "chalk";
9
9
  import { minimatch } from "minimatch";
10
10
  import * as path3 from "path";
11
11
  function parseGitHubOwnerRepo(repoUrl) {
12
- const scpMatch = repoUrl.match(/^git@github\.com:([^/]+)\/(.+?)(?:\.git)?$/);
13
- if (scpMatch) {
14
- return { owner: scpMatch[1], repo: scpMatch[2] };
12
+ const [, scpOwner, scpRepo] = repoUrl.match(/^git@github\.com:([^/]+)\/(.+?)(?:\.git)?$/) ?? [];
13
+ if (scpOwner && scpRepo) {
14
+ return { owner: scpOwner, repo: scpRepo };
15
15
  }
16
16
  try {
17
17
  const url = new URL(repoUrl);
@@ -78,6 +78,13 @@ function neutralizeDescriptionRefs(text, appendedRefs, mode, repoUrl) {
78
78
  );
79
79
  return out.trim();
80
80
  }
81
+ function removeDescriptionRefs(text, refs) {
82
+ const remove = new Set(refs.filter((r) => !!r).map((r) => Number(r.replace(/^#/, ""))));
83
+ return text.replace(CODE_SPAN_OR_DESC_REF, (match, _lead, parenNum, bareNum) => {
84
+ const num = parenNum ?? bareNum;
85
+ return num !== void 0 && remove.has(Number(num)) ? "" : match;
86
+ }).trim();
87
+ }
81
88
  var LOG_LEVELS = {
82
89
  error: 0,
83
90
  warn: 1,
@@ -236,7 +243,7 @@ var CODE_TO_EXIT = {
236
243
  NO_COMMIT_MESSAGE: EXIT_CODES.VERSION_ERROR,
237
244
  NO_FILES: EXIT_CODES.VERSION_ERROR,
238
245
  CARGO_LOCK_SYNC_ERROR: EXIT_CODES.VERSION_ERROR,
239
- // @releasekit/publish: a malformed manifest is a config error.
246
+ // @releasekit/publish
240
247
  PIPELINE_STAGE_ERROR: EXIT_CODES.PUBLISH_ERROR,
241
248
  NPM_AUTH_ERROR: EXIT_CODES.PUBLISH_ERROR,
242
249
  NPM_PUBLISH_ERROR: EXIT_CODES.PUBLISH_ERROR,
@@ -246,6 +253,7 @@ var CODE_TO_EXIT = {
246
253
  PUB_PUBLISH_ERROR: EXIT_CODES.PUBLISH_ERROR,
247
254
  FILE_COPY_ERROR: EXIT_CODES.PUBLISH_ERROR,
248
255
  VERIFICATION_FAILED: EXIT_CODES.PUBLISH_ERROR,
256
+ // A malformed manifest is a config error.
249
257
  CARGO_TOML_ERROR: EXIT_CODES.CONFIG_ERROR,
250
258
  PUBSPEC_YAML_ERROR: EXIT_CODES.CONFIG_ERROR,
251
259
  GIT_COMMIT_ERROR: EXIT_CODES.GIT_ERROR,
@@ -468,9 +476,9 @@ function extractLinksFromPRBodies(entries, marker) {
468
476
  seen.add(mdLink.url);
469
477
  links.push(mdLink);
470
478
  }
471
- } else if (/^https?:\/\//.test(rest)) {
472
- const url = rest.split(/\s/)[0];
473
- if (!seen.has(url)) {
479
+ } else {
480
+ const url = /^https?:\/\/\S*/.exec(rest)?.[0];
481
+ if (url && !seen.has(url)) {
474
482
  seen.add(url);
475
483
  links.push({ label: marker.replace(/:$/, ""), url });
476
484
  }
@@ -565,22 +573,27 @@ function renderMarkdown(contexts, options) {
565
573
  }
566
574
  return sections.join("\n");
567
575
  }
568
- function prependVersion(existingPath, context, options) {
569
- let existing = "";
570
- if (fs3.existsSync(existingPath)) {
571
- existing = fs3.readFileSync(existingPath, "utf-8");
572
- const headerEnd = existing.indexOf("\n## ");
573
- if (headerEnd >= 0) {
574
- const header = existing.slice(0, headerEnd);
575
- const body = existing.slice(headerEnd + 1);
576
- const newVersion = formatVersion(context, options);
577
- return `${header}
576
+ function prependVersions(existingPath, contexts, options) {
577
+ const existing = fs3.existsSync(existingPath) ? fs3.readFileSync(existingPath, "utf-8") : "";
578
+ if (existing.trim() === "") {
579
+ return renderMarkdown(contexts, options);
580
+ }
581
+ const sections = contexts.map((context) => formatVersion(context, options)).join("\n");
582
+ if (existing.startsWith("## ")) {
583
+ return `${sections}
584
+ ${existing}`;
585
+ }
586
+ const headerEnd = existing.indexOf("\n## ");
587
+ if (headerEnd === -1) {
588
+ return `${existing.trimEnd()}
578
589
 
579
- ${newVersion}
580
- ${body}`;
581
- }
590
+
591
+ ${sections}`;
582
592
  }
583
- return renderMarkdown([context]);
593
+ return `${existing.slice(0, headerEnd)}
594
+
595
+ ${sections}
596
+ ${existing.slice(headerEnd + 1)}`;
584
597
  }
585
598
  function writeMarkdown(outputPath, contexts, config, dryRun, options) {
586
599
  const content = renderMarkdown(contexts, options);
@@ -598,20 +611,14 @@ function writeMarkdown(outputPath, contexts, config, dryRun, options) {
598
611
  process.stdout.write(content);
599
612
  return;
600
613
  }
601
- if (config.updateStrategy !== "regenerate" && fs3.existsSync(outputPath) && contexts.length === 1) {
602
- const firstContext = contexts[0];
603
- if (firstContext) {
604
- const updated = prependVersion(outputPath, firstContext, options);
605
- fs3.writeFileSync(outputPath, updated, "utf-8");
606
- }
607
- } else {
608
- fs3.writeFileSync(outputPath, content, "utf-8");
609
- }
614
+ const updated = config.updateStrategy === "regenerate" ? content : prependVersions(outputPath, contexts, options);
615
+ fs3.writeFileSync(outputPath, updated, "utf-8");
610
616
  success(`${label} written to ${outputPath}`);
611
617
  }
612
618
 
613
619
  export {
614
620
  parseGitHubOwnerRepo,
621
+ removeDescriptionRefs,
615
622
  setLogLevel,
616
623
  setQuietMode,
617
624
  error,
@@ -626,6 +633,6 @@ export {
626
633
  isPathWithinRoot,
627
634
  formatVersion,
628
635
  renderMarkdown,
629
- prependVersion,
636
+ prependVersions,
630
637
  writeMarkdown
631
638
  };
@@ -1,11 +1,10 @@
1
1
  import {
2
2
  debug,
3
- formatVersion,
4
3
  info,
5
- prependVersion,
4
+ prependVersions,
6
5
  renderMarkdown,
7
6
  success
8
- } from "./chunk-LA3V665B.js";
7
+ } from "./chunk-CBMVDKDR.js";
9
8
 
10
9
  // src/monorepo/aggregator.ts
11
10
  import * as fs from "fs";
@@ -60,22 +59,7 @@ function writeMonorepoChangelogs(contexts, options, config, dryRun, refs = "link
60
59
  const rootPath = path.join(options.rootPath, options.fileName ?? "CHANGELOG.md");
61
60
  const fmtOpts = { includePackageName: true, refs };
62
61
  info(`Writing root changelog to ${rootPath}`);
63
- let rootContent;
64
- if (config.updateStrategy !== "regenerate" && fs.existsSync(rootPath)) {
65
- const newSections = contexts.map((ctx) => formatVersion(ctx, fmtOpts)).join("\n");
66
- const existing = fs.readFileSync(rootPath, "utf-8");
67
- const headerEnd = existing.indexOf("\n## ");
68
- if (headerEnd >= 0) {
69
- rootContent = `${existing.slice(0, headerEnd)}
70
-
71
- ${newSections}
72
- ${existing.slice(headerEnd + 1)}`;
73
- } else {
74
- rootContent = renderMarkdown(contexts, fmtOpts);
75
- }
76
- } else {
77
- rootContent = renderMarkdown(contexts, fmtOpts);
78
- }
62
+ const rootContent = config.updateStrategy === "regenerate" ? renderMarkdown(contexts, fmtOpts) : prependVersions(rootPath, contexts, fmtOpts);
79
63
  if (writeFile(rootPath, rootContent, dryRun)) {
80
64
  files.push(rootPath);
81
65
  }
@@ -89,7 +73,7 @@ ${existing.slice(headerEnd + 1)}`;
89
73
  if (packageDir) {
90
74
  const changelogPath = path.join(packageDir, options.fileName ?? "CHANGELOG.md");
91
75
  info(`Writing changelog for ${packageName} to ${changelogPath}`);
92
- const pkgContent = config.updateStrategy !== "regenerate" && fs.existsSync(changelogPath) ? prependVersion(changelogPath, ctx, { refs }) : renderMarkdown([ctx], { refs });
76
+ const pkgContent = config.updateStrategy === "regenerate" ? renderMarkdown([ctx], { refs }) : prependVersions(changelogPath, [ctx], { refs });
93
77
  if (writeFile(changelogPath, pkgContent, dryRun)) {
94
78
  files.push(changelogPath);
95
79
  }
@@ -7,13 +7,14 @@ import {
7
7
  info,
8
8
  isPathWithinRoot,
9
9
  parseGitHubOwnerRepo,
10
+ removeDescriptionRefs,
10
11
  setLogLevel,
11
12
  setQuietMode,
12
13
  success,
13
14
  unwrapEnvelope,
14
15
  warn,
15
16
  writeMarkdown
16
- } from "./chunk-LA3V665B.js";
17
+ } from "./chunk-CBMVDKDR.js";
17
18
 
18
19
  // ../config/dist/index.js
19
20
  import * as fs from "fs";
@@ -321,10 +322,6 @@ var LLMOptionsSchema = z.object({
321
322
  });
322
323
  var LLMRetryConfigSchema = z.object({
323
324
  maxAttempts: z.number().int().positive().optional().describe("Maximum number of attempts"),
324
- // `.int()` here matches the generated JSON Schema (`type: integer`, `minimum`),
325
- // and closes a pre-generator gap where the Zod runtime accepted floats. Keep
326
- // these in sync with scripts/generate-schema.ts — relaxing one without the
327
- // other re-introduces the divergence.
328
325
  initialDelay: z.number().int().nonnegative().optional().describe("Initial delay in ms"),
329
326
  maxDelay: z.number().int().positive().optional().describe("Maximum delay in ms"),
330
327
  backoffFactor: z.number().positive().optional().describe("Delay multiplier per attempt")
@@ -475,10 +472,12 @@ var StandingPrConfigSchema = z.object({
475
472
  branch: z.string().default("release/next").describe("Branch name for the standing release PR."),
476
473
  title: z.string().optional().describe(
477
474
  // biome-ignore lint/suspicious/noTemplateCurlyInString: documenting placeholder syntax to the user
478
- "PR title template. Variables: ${count} (publishable package count), ${version} (raw version), ${tag} (version with tag prefix). Must start with 'chore: release' to match the default skip pattern on squash merge. Default depends on the versioning strategy: 'chore: release ${tag}' in sync mode, 'chore: release ${count} package(s)' otherwise."
475
+ "PR title template. Variables: ${count} (publishable package count), ${version} (raw version), ${tag} (version with tag prefix). Also the release commit's subject, so it must match a release.ci.skipPatterns entry and carry no CI-skip marker. A title with a CI-skip marker is replaced by 'chore: release preparation'. So is one the skip patterns miss, if they match 'chore: release preparation'. The run warns either way. Default depends on the versioning strategy: 'chore: release ${tag}' in sync mode, 'chore: release ${count} package(s)' otherwise."
479
476
  ),
480
477
  labels: z.array(z.string()).default(["release"]).describe("Labels to apply to the standing release PR."),
481
- deleteBranchOnMerge: z.boolean().default(true).describe("Whether to auto-delete the release branch after the PR is merged."),
478
+ deleteBranchOnMerge: z.boolean().default(true).describe(
479
+ "Whether to auto-delete the release branch after the PR is merged. Publish keeps it if an update has moved it since the merge, or if the merged PR's head commit can't be read."
480
+ ),
482
481
  mergeMethod: z.enum(["merge", "squash", "rebase"]).default("merge").describe("Merge method to use when merging the standing release PR via CLI."),
483
482
  minAge: z.string().optional().describe(
484
483
  "Minimum age of the standing PR before it can be merged. Duration string, e.g. '6h', '30m', '1d'. Gate enforced via the releasekit/standing-pr commit status check; configure it as a required status check in branch protection to block merges."
@@ -491,9 +490,7 @@ var StandingPrConfigSchema = z.object({
491
490
  "Minimum repository permission an actor needs to steer the standing PR \u2014 tick/untick selection checkboxes, flip per-row channel toggles, apply release labels, and (with branch protection) merge. Default: admin."
492
491
  ),
493
492
  allowedActors: z.array(
494
- // A GitHub username (e.g. `octocat`) or a team as `@org/team-slug`. The `@…/…` form needs
495
- // the slash — `@octocat` is neither a username nor a team and would silently match nobody,
496
- // so reject it at config-load time. Round-trips into the JSON Schema as `pattern`.
493
+ // `@octocat` (no slash) is neither a username nor a team and would silently match nobody.
497
494
  z.string().regex(/^(?:[A-Za-z0-9-]+|@[A-Za-z0-9-]+\/[A-Za-z0-9._-]+)$/, {
498
495
  message: 'allowedActors entries must be a GitHub username (e.g. "octocat") or a team as "@org/team-slug" (note the slash).'
499
496
  })
@@ -781,11 +778,7 @@ var LLMError = class extends NotesError {
781
778
  "Check network connectivity",
782
779
  "Try with --no-llm to skip LLM processing"
783
780
  ];
784
- /**
785
- * Whether the underlying failure is transient and worth retrying (timeout / 429 / 5xx / network).
786
- * `false` marks a non-retryable failure (4xx auth/validation) so `withRetry` fails fast instead of
787
- * burning the whole backoff budget. `undefined` means "unclassified" — callers retry by default.
788
- */
781
+ /** `undefined` means "unclassified" - callers retry by default. */
789
782
  retryable;
790
783
  constructor(message, options) {
791
784
  super(message);
@@ -1077,7 +1070,7 @@ var GitHubForge = class {
1077
1070
  }
1078
1071
  async getPullRequest(prNumber) {
1079
1072
  const { data } = await this.octokit.rest.pulls.get({ ...this.base, pull_number: prNumber });
1080
- return { body: data.body ?? "", labels: labelNames(data.labels) };
1073
+ return { body: data.body ?? "", labels: labelNames(data.labels), headSha: data.head?.sha };
1081
1074
  }
1082
1075
  async createPullRequest(pr) {
1083
1076
  const { data } = await this.octokit.rest.pulls.create({ ...this.base, ...pr });
@@ -1349,12 +1342,9 @@ var LLM_DEFAULTS = {
1349
1342
  timeout: 6e4,
1350
1343
  // 16k tokens accommodates large changelogs without hitting most model ceilings.
1351
1344
  maxTokens: 16384,
1352
- // 0.7 balances coherence (low temp) with natural-sounding variation (high temp).
1345
+ // Balances coherence with natural-sounding variation.
1353
1346
  temperature: 0.7,
1354
1347
  concurrency: 5,
1355
- // Max entries per enhance+categorize prompt. Large releases in a single prompt overflow the output
1356
- // ceiling → entry-count validation fails → corrective retries resend a growing transcript. Bounded
1357
- // chunks keep each call within budget and isolate a bad chunk's fallback to that chunk alone.
1358
1348
  enhanceCategorizeChunkSize: 30,
1359
1349
  retry: {
1360
1350
  maxAttempts: 3,
@@ -1362,9 +1352,8 @@ var LLM_DEFAULTS = {
1362
1352
  maxDelay: 3e4,
1363
1353
  backoffFactor: 2
1364
1354
  }
1365
- // No default model: releasekit ships no model ids (they rot — e.g. a provider deprecates one), so
1366
- // `llm.model` is required and validated at config load. The model choice, and keeping it current,
1367
- // is the consumer's.
1355
+ // No default model: model ids rot (providers deprecate them), so `llm.model` is required and validated
1356
+ // at config load.
1368
1357
  };
1369
1358
 
1370
1359
  // src/llm/examples/fetcher.ts
@@ -1454,10 +1443,12 @@ function groupByCategory(llmEntries, entries) {
1454
1443
  if (!entry) {
1455
1444
  continue;
1456
1445
  }
1457
- if (!categoryMap.has(category)) {
1458
- categoryMap.set(category, []);
1446
+ const bucket = categoryMap.get(category);
1447
+ if (bucket) {
1448
+ bucket.push(entry);
1449
+ } else {
1450
+ categoryMap.set(category, [entry]);
1459
1451
  }
1460
- categoryMap.get(category).push(entry);
1461
1452
  }
1462
1453
  const result = [];
1463
1454
  for (const [category, catEntries] of categoryMap) {
@@ -1539,9 +1530,9 @@ function parseReleaseBodyToExample(markdown, version) {
1539
1530
  if (!line) {
1540
1531
  continue;
1541
1532
  }
1542
- const headingMatch = /^#{2,4} (.+)/.exec(line);
1543
- if (headingMatch) {
1544
- currentCategory = headingMatch[1].trim();
1533
+ const heading = /^#{2,4} (.+)/.exec(line)?.[1];
1534
+ if (heading) {
1535
+ currentCategory = heading.trim();
1545
1536
  continue;
1546
1537
  }
1547
1538
  if (line.startsWith("#")) {
@@ -1640,11 +1631,12 @@ async function fetchExamples(options) {
1640
1631
  const nonDraft = allReleases.filter((r) => !r.draft && !r.prerelease);
1641
1632
  const packageScoped = nonDraft.filter((r) => matchesPackageScoped(r.tagName, packageName));
1642
1633
  const matching = (packageScoped.length > 0 ? packageScoped : isMonorepo ? [] : nonDraft.filter((r) => matchesBareVersion(r.tagName))).slice(0, count);
1643
- if (matching.length === 0) {
1634
+ const latest = matching[0];
1635
+ if (!latest) {
1644
1636
  debug(`No matching releases found for ${packageName}`);
1645
1637
  return [];
1646
1638
  }
1647
- const latestTag = matching[0].tagName;
1639
+ const latestTag = latest.tagName;
1648
1640
  const key = cacheKey(owner, repo, packageName);
1649
1641
  const cached = readCache(key, latestTag, count);
1650
1642
  if (cached) {
@@ -1735,10 +1727,6 @@ var BaseLLMProvider = class {
1735
1727
  }
1736
1728
  return Math.min(Math.trunc(timeout), MAX_TIMEOUT_MS);
1737
1729
  }
1738
- /**
1739
- * Runs one request under the idle timeout and normalises its errors to LLMError. An abort is a timeout
1740
- * whatever `request` then threw, because each SDK surfaces an aborted stream differently.
1741
- */
1742
1730
  async withIdleTimeout(label, options, request) {
1743
1731
  const ms = this.getTimeout(options);
1744
1732
  const controller = new AbortController();
@@ -2445,7 +2433,10 @@ async function enhanceEntries(provider, entries, context, concurrency = LLM_DEFA
2445
2433
  batch.map(async (entry) => {
2446
2434
  try {
2447
2435
  const newDescription = await enhanceEntry(provider, entry, context);
2448
- return { ...entry, description: newDescription };
2436
+ return {
2437
+ ...entry,
2438
+ description: removeDescriptionRefs(newDescription, [...entry.issueIds ?? [], entry.prNumber])
2439
+ };
2449
2440
  } catch {
2450
2441
  failures++;
2451
2442
  return entry;
@@ -2467,7 +2458,7 @@ function buildSystemPrompt3(categories, style) {
2467
2458
  categories,
2468
2459
  `Categories: Group into meaningful categories (e.g., "New", "Fixed", "Changed", "Removed").`
2469
2460
  );
2470
- const pairs = categories && categories.length > 0 ? categories.filter((c) => c.scopes?.length).map((c) => ({ name: c.name, scopes: c.scopes })) : [];
2461
+ const pairs = (categories ?? []).flatMap((c) => c.scopes?.length ? [{ name: c.name, scopes: c.scopes }] : []);
2471
2462
  const scopeInstruction = renderScopeInstruction(pairs, " entries");
2472
2463
  return `You are generating release notes for a software project. Given changelog entries, rewrite each as a clear user-friendly description and categorize it.
2473
2464
 
@@ -2530,7 +2521,7 @@ function createEnhanceAndCategorizeValidator(entries, context) {
2530
2521
  }
2531
2522
  return {
2532
2523
  ...original,
2533
- description: llmEntry.description,
2524
+ description: removeDescriptionRefs(llmEntry.description, [...original.issueIds ?? [], original.prNumber]),
2534
2525
  scope: llmEntry.scope ?? void 0,
2535
2526
  breaking: original.breaking || llmEntry.breaking === true,
2536
2527
  leadIn: llmEntry.leadIn ?? void 0
@@ -3148,7 +3139,6 @@ async function processWithLLM(context, llmConfig, examples, packageNames) {
3148
3139
  provider = {
3149
3140
  name: baseProvider.name,
3150
3141
  capabilities: baseProvider.capabilities,
3151
- // Fail fast on non-transient errors (4xx auth/validation); only retry timeout/429/5xx/network.
3152
3142
  complete: (messages, opts) => withRetry(() => baseProvider.complete(messages, { ...configOptions, ...opts }), {
3153
3143
  ...retryOpts,
3154
3144
  shouldRetry: isRetryableLLMError
@@ -3374,7 +3364,7 @@ async function runPipeline(input, config, dryRun, pipelineOptions) {
3374
3364
  const dir = releaseNotesConfig.file.dir;
3375
3365
  info(`Generating release notes \u2192 ${dir}`);
3376
3366
  try {
3377
- const { detectMonorepo } = await import("./aggregator-75QONDAK.js");
3367
+ const { detectMonorepo } = await import("./aggregator-DYYIWNIK.js");
3378
3368
  const nested = detectMonorepo(process.cwd()).isMonorepo || contexts.length > 1;
3379
3369
  const renderContent = (ctx) => {
3380
3370
  if (releaseNotesConfig.templates?.path) {
@@ -3438,7 +3428,7 @@ async function processInput(inputJson, config, dryRun, pipelineOptions) {
3438
3428
  return runPipeline(input, config, dryRun, pipelineOptions);
3439
3429
  }
3440
3430
  async function writeMonorepoFiles(contexts, config, dryRun, fileName, refs) {
3441
- const { detectMonorepo, writeMonorepoChangelogs } = await import("./aggregator-75QONDAK.js");
3431
+ const { detectMonorepo, writeMonorepoChangelogs } = await import("./aggregator-DYYIWNIK.js");
3442
3432
  const cwd = process.cwd();
3443
3433
  const detected = detectMonorepo(cwd);
3444
3434
  if (!detected.isMonorepo) {
package/dist/cli.js CHANGED
@@ -1,10 +1,10 @@
1
1
  #!/usr/bin/env node
2
2
  import {
3
3
  createNotesCommand
4
- } from "./chunk-3X4XBORT.js";
4
+ } from "./chunk-OTH3XXI4.js";
5
5
  import {
6
6
  readPackageVersion
7
- } from "./chunk-LA3V665B.js";
7
+ } from "./chunk-CBMVDKDR.js";
8
8
 
9
9
  // src/cli.ts
10
10
  import * as fs from "fs";
package/dist/index.d.ts CHANGED
@@ -10,20 +10,8 @@ type MonorepoConfig = z.infer<typeof MonorepoConfigSchema>;
10
10
  declare function loadAuth(): Record<string, string>;
11
11
  declare function saveAuth(provider: string, apiKey: string): void;
12
12
 
13
- /**
14
- * Neutralising bare GitHub-autolinked tokens in changelog output. GitHub auto-links a bare `#NNN`
15
- * issue/PR ref (with a hovercard) and treats a bare `@scope/pkg` / `@user` as a mention (a stray
16
- * link that can ping/subscribe a real org or team on every release PR). Both render surfaces — the
17
- * notes Markdown (`CHANGELOG.md`, GitHub release body) and the standing-PR body — share these two
18
- * pure helpers so the treatment stays identical.
19
- */
20
- /** How bare `#NNN` issue/PR refs in a changelog are rendered. */
21
13
  type ChangelogRefsMode = 'strip' | 'escape' | 'link';
22
14
 
23
- /**
24
- * Base error class that all releasekit errors should extend.
25
- * Provides consistent error handling with codes and suggestions.
26
- */
27
15
  declare abstract class ReleaseKitError extends Error {
28
16
  abstract readonly code: string;
29
17
  abstract readonly suggestions: string[];
@@ -33,48 +21,27 @@ declare abstract class ReleaseKitError extends Error {
33
21
  static isReleaseKitError(error: unknown): error is ReleaseKitError;
34
22
  }
35
23
 
36
- /**
37
- * Shared types for the releasekit ecosystem.
38
- *
39
- * These types define the JSON contract between @releasekit/version (producer)
40
- * and @releasekit/notes (consumer). Changes here affect both packages.
41
- */
42
- /**
43
- * A single changelog entry produced by @releasekit/version.
44
- */
45
24
  interface VersionChangelogEntry {
46
25
  type: string;
47
26
  description: string;
48
27
  issueIds?: string[];
49
28
  /**
50
- * The pull request this entry shipped through, taken from the trailing `(#N)` GitHub appends to a
51
- * squash-merge commit subject. It marks which of the {@link issueIds} is the PR (the rest are closed
52
- * issues), so the changelog can render `(PR #N · closes #M)` instead of a flat ref list. The number
53
- * is also kept inside `issueIds` (the full flat list), so a consumer that ignores this field still
54
- * shows the ref. Optional and additive — absent means no identifiable PR (a non-squash commit or an
55
- * old manifest), and renderers fall back to the plain ref list.
29
+ * The PR this entry shipped through, from the trailing `(#N)` GitHub appends to a squash-merge subject. Marks which
30
+ * of the {@link issueIds} is the PR (the rest are closed issues); the number stays in `issueIds` too, so a consumer
31
+ * that ignores this field still shows the ref. Absent when there's no identifiable PR (a non-squash commit or an
32
+ * old manifest).
56
33
  */
57
34
  prNumber?: string;
58
35
  scope?: string;
59
36
  originalType?: string;
60
37
  breaking?: boolean;
61
38
  /**
62
- * True when this entry is a fabricated `Update version to X` placeholder minted by the
63
- * version-groups engine for a lockstep carry — a group member bumped only to stay in sync, with
64
- * no commits of its own. It is not derived from a real commit. The preview formatter treats a
65
- * changelog whose entries are *all* synthetic as "no real changes" and collapses the package into
66
- * the "Also bumped" list instead of rendering a full block of placeholder noise.
67
- *
68
- * Only the groups engine sets it, and only on a clean empty extraction: an independently-released
69
- * package (single/async strategy) or an extraction-error fallback keeps its visible block, since
70
- * neither is a no-change carry. Optional and additive — absent means a real entry, so manifests
71
- * written before this field existed render exactly as before.
39
+ * True when this entry is a fabricated `Update version to X` placeholder minted by the version-groups engine for a
40
+ * lockstep carry - a group member bumped only to stay in sync, with no commits of its own. Not set on an
41
+ * extraction-error fallback, which isn't a no-change carry.
72
42
  */
73
43
  synthetic?: boolean;
74
44
  }
75
- /**
76
- * Changelog data for a single package, as emitted by @releasekit/version --json.
77
- */
78
45
  interface VersionPackageChangelog {
79
46
  packageName: string;
80
47
  version: string;
@@ -83,118 +50,60 @@ interface VersionPackageChangelog {
83
50
  repoUrl: string | null;
84
51
  entries: VersionChangelogEntry[];
85
52
  }
86
- /**
87
- * The resolved action a package's version landed on — purely additive observability, it
88
- * never changes which version resolves. `'graduated'` means a prerelease was promoted to stable and
89
- * any requested bump was ignored; `'bumped'` is the ordinary commit/label-driven bump;
90
- * `'first-release'` is a package with no prior tag. Defined as a string-literal union (core cannot
91
- * import the version package, where the deriving logic lives).
92
- */
53
+ /** `'graduated'`: a prerelease promoted to stable, ignoring any requested bump. `'first-release'`: no prior tag. */
93
54
  type VersionAction = 'first-release' | 'graduated' | 'bumped';
94
- /**
95
- * The release channel a version sits on. Derived per-package and purely from the resolved
96
- * version: `'prerelease'` when the version carries a semver prerelease segment (`…-<preid>.N`), else
97
- * `'stable'`. A standing PR with permanently-mixed maturity carries both at once — some `'stable'`
98
- * packages, some `'prerelease'` — each advancing along its own line.
99
- */
100
55
  type ReleaseChannel = 'stable' | 'prerelease';
101
56
  /**
102
- * The `data` of @releasekit/version's `--json` envelope.
103
- * This is the primary interchange format between version and notes.
57
+ * The `data` of @releasekit/version's `--json` envelope, passed between pipeline stages and persisted in standing-PR
58
+ * manifests. Open PRs carry old manifests, so new fields must be optional and consumers must tolerate their absence.
104
59
  */
105
60
  interface VersionOutput {
106
61
  dryRun: boolean;
107
- /**
108
- * Which versioning strategy produced this output. Lets consumers (preview, standing PR)
109
- * render sync releases as a single versioned unit instead of a package count. Optional
110
- * for backwards compatibility with manifests produced before this field existed.
111
- *
112
- * `'group'` is the version-groups engine (fixed/linked, and the implicit all-packages fixed
113
- * group that `version.sync: true` desugars to). `'sync'` remains for the legacy lockstep
114
- * strategy so existing consumers keep working unchanged.
115
- */
62
+ /** Absent in older manifests. */
116
63
  strategy?: 'sync' | 'single' | 'async' | 'group';
117
64
  updates: VersionPackageUpdate[];
118
65
  changelogs: VersionPackageChangelog[];
119
- /**
120
- * Changelog entries from commits that don't touch any specific package directory
121
- * (CI, infrastructure, shared package changes). Stored separately so they can be
122
- * rendered once rather than duplicated across every per-package changelog.
123
- */
66
+ /** Entries from commits that touch no package directory. */
124
67
  sharedEntries?: VersionChangelogEntry[];
125
68
  commitMessage?: string;
126
- /** Consumer-facing tags from `tagTemplate` (e.g. `v1.2.3`). The publish pipeline pushes
127
- * them and creates a GitHub Release for each. */
69
+ /** Consumer-facing tags from `tagTemplate`. */
128
70
  tags: string[];
129
- /** Internal baseline-marker tags from `baselineTagTemplate` (e.g. `release/v1.2.3`).
130
- * Pushed alongside `tags` but not used to create GitHub Releases — they exist purely
131
- * so future version-bump and changelog calculations can find the previous release on
132
- * the source branch's history when the consumer-facing tag has been force-moved off it. */
71
+ /**
72
+ * Internal baseline-marker tags from `baselineTagTemplate`, pushed alongside `tags` but never given a GitHub
73
+ * Release. They let later runs find the previous release on the source branch when the consumer-facing tag has
74
+ * been force-moved off it.
75
+ */
133
76
  baselineTags?: string[];
134
77
  }
135
- /**
136
- * A package update record in the version output.
137
- */
138
78
  interface VersionPackageUpdate {
139
79
  packageName: string;
140
80
  newVersion: string;
141
81
  /**
142
- * The resolved baseline version this update bumped from — the package's prior release, in the same
143
- * consumer-tag display form the changelog carries ({@link VersionPackageChangelog.previousVersion}).
144
- * Absent for a first release and whenever the baseline was unreachable / fell back to all-history,
145
- * so consumers derive the bump magnitude only when it is present. Optional for backwards
146
- * compatibility: standing-PR manifests written before this field existed omit it (old PRs still
147
- * open), so every consumer must tolerate its absence (render a dash / skip the delta).
82
+ * In the same consumer-tag display form as {@link VersionPackageChangelog.previousVersion}. Absent for a first
83
+ * release, when the baseline was unreachable or fell back to all-history, and in older manifests.
148
84
  */
149
85
  previousVersion?: string;
150
86
  filePath: string;
151
- /** Per-package git tag. Set only when each package has its own tag (async mode or sync+packageSpecificTags). Absent in sync mode with a single shared tag. */
87
+ /** Absent when all packages share one tag. */
152
88
  tag?: string;
153
89
  /**
154
- * True when this update is the workspace-root package.json, bumped only to keep the root
155
- * version in lockstep (sync mode). Root updates are not publishable packages — consumers
156
- * should exclude them from package counts and package lists.
90
+ * The workspace-root package.json, bumped only to keep the root version in lockstep. Not a publishable package, so
91
+ * exclude it from package counts and lists.
157
92
  */
158
93
  isRoot?: boolean;
159
- /**
160
- * Name of the version group this package was released as part of (from `version.groups`, or
161
- * the implicit all-packages group that `version.sync: true` desugars to). Absent for packages
162
- * versioned independently. CI surfaces can use this to treat a fixed group atomically (e.g.
163
- * expand a scope label that matches part of a group to the whole group).
164
- */
165
94
  group?: string;
166
95
  /**
167
- * Role in a `--include-prerequisites` release: `'target'` for an explicitly-selected
168
- * (group-expanded) package that receives the bump/prerelease/stable override, `'prerequisite'`
169
- * for a changed transitive dependency pulled in to keep the targets installable (it keeps its own
170
- * commit-driven bump). Absent on plain releases and for the root lockstep bump — consumers treat
171
- * an absent role as a target.
96
+ * Set in an `--include-prerequisites` release: `'target'` is an explicitly-selected (group-expanded) package that
97
+ * gets the bump/prerelease/stable override; `'prerequisite'` is a changed transitive dependency pulled in to keep
98
+ * the targets installable, which keeps its own commit-driven bump. Absent on plain releases and for the root
99
+ * lockstep bump - treat an absent role as a target.
172
100
  */
173
101
  role?: 'target' | 'prerequisite';
174
- /**
175
- * For a `'prerequisite'` update, the target package(s) it was pulled in for (a shared dependency
176
- * can serve several). Lets CI surfaces render "target → its prerequisites" without re-deriving
177
- * the dependency graph. Absent for targets.
178
- */
179
102
  prerequisiteOf?: string[];
180
- /**
181
- * The resolved version action for this update: `'graduated'` (prerelease → stable, bump
182
- * ignored), `'bumped'` (commit/label-driven), or `'first-release'`. Purely additive observability —
183
- * it never affects which version resolved. Optional for backwards compatibility: standing-PR
184
- * manifests produced before this field existed won't carry it, so every consumer must tolerate
185
- * its absence (render nothing).
186
- */
103
+ /** Absent in older manifests. */
187
104
  action?: VersionAction;
188
- /** Short human-readable reason for {@link action} (e.g. `Graduated 1.0.0-next.1 → 1.0.0 (bump ignored).`). Optional, same back-compat rule as {@link action}. */
189
105
  actionReason?: string;
190
- /**
191
- * The release channel this package's new version sits on: `'prerelease'` when `newVersion`
192
- * carries a semver prerelease segment, else `'stable'`. Derived from the resolved version via
193
- * {@link deriveReleaseChannel}; a mixed standing PR carries both, each package advancing on its own
194
- * line. Purely additive observability — it never affects which version resolves. Optional for
195
- * backwards compatibility: standing-PR manifests written before this field existed omit it, so every
196
- * consumer must tolerate its absence (re-derive from `newVersion`).
197
- */
106
+ /** Absent in older manifests - re-derive it with {@link deriveReleaseChannel}. */
198
107
  channel?: ReleaseChannel;
199
108
  }
200
109
 
@@ -203,11 +112,6 @@ interface RetryOptions {
203
112
  initialDelay?: number;
204
113
  maxDelay?: number;
205
114
  backoffFactor?: number;
206
- /**
207
- * Decide whether a thrown error is worth retrying. `true` (or omitting the predicate) retries;
208
- * `false` stops immediately and rethrows. Lets callers fail fast on non-transient errors
209
- * (e.g. 4xx auth/validation) while still retrying timeout/429/5xx/network failures.
210
- */
211
115
  shouldRetry?: (error: unknown) => boolean;
212
116
  }
213
117
 
@@ -222,7 +126,7 @@ interface ChangelogEntry {
222
126
  description: string;
223
127
  issueIds?: string[];
224
128
  /** The PR this entry shipped through (trailing `(#N)` of a squash-merge subject); marks which of
225
- * {@link issueIds} is the PR vs. a closed issue. Optional — absent means no identifiable PR. */
129
+ * {@link issueIds} is the PR vs. a closed issue. */
226
130
  prNumber?: string;
227
131
  scope?: string;
228
132
  originalType?: string;
@@ -270,8 +174,6 @@ interface TemplateContext {
270
174
  entries: ChangelogEntry[];
271
175
  compareUrl?: string;
272
176
  enhanced?: EnhancedData;
273
- /** True when `previousVersion === null` — the package has no prior release. Templates can branch
274
- * on it to add a first-release intro; the default renderer seeds a placeholder line. */
275
177
  isFirstRelease?: boolean;
276
178
  }
277
179
  interface DocumentContext {
@@ -282,12 +184,10 @@ interface DocumentContext {
282
184
  versions: TemplateContext[];
283
185
  unreleased?: TemplateContext;
284
186
  compareUrls?: Record<string, string>;
285
- /** True when rendered for a single-package inline context (e.g. GitHub release body).
286
- * Templates can use this to suppress document-level headings that are redundant
187
+ /** Templates can use this to suppress document-level headings that are redundant
287
188
  * when the content is embedded in a release that already shows the package/version. */
288
189
  perPackage?: boolean;
289
- /** Which release-notes destination this render targets: `'file'` (an in-repo per-version file)
290
- * or `'release'` (the GitHub release body). Templates can branch on it — e.g. emit docs-site
190
+ /** `'release'` is the GitHub release body. Templates can branch on it - e.g. emit docs-site
291
191
  * YAML frontmatter only for `'file'`, since it would render as literal text in a GitHub release. */
292
192
  output?: 'file' | 'release';
293
193
  }
@@ -381,7 +281,6 @@ interface ChangelogConfig {
381
281
  mode?: LocationMode;
382
282
  file?: string;
383
283
  templates?: TemplateConfig;
384
- /** How bare `#NNN` issue/PR refs render in the changelog. Default `'link'` when unset. */
385
284
  refs?: ChangelogRefsMode;
386
285
  }
387
286
  interface LinksConfig {
@@ -393,20 +292,17 @@ interface LinksConfig {
393
292
  title?: string;
394
293
  }
395
294
  interface ReleaseNotesFileConfig {
396
- /** Directory for the per-version release-notes files (default: release-notes). */
397
295
  dir?: string;
398
296
  }
399
297
  interface FirstReleaseConfig {
400
- /** Placeholder intro line for a package's first release. Supports ${packageName} and ${version}. */
298
+ /** Supports ${packageName} and ${version}. */
401
299
  text?: string;
402
300
  }
403
301
  interface ReleaseNotesConfig {
404
- /** In-repo per-version file output. Omit to keep notes only on the GitHub release body. */
405
302
  file?: ReleaseNotesFileConfig;
406
303
  templates?: TemplateConfig;
407
304
  llm?: LLMConfig;
408
305
  links?: LinksConfig;
409
- /** First-release placeholder intro. Default-on with a factual line; set to false to disable. */
410
306
  firstRelease?: false | FirstReleaseConfig;
411
307
  }
412
308
 
@@ -424,17 +320,12 @@ interface PipelineResult {
424
320
  }
425
321
  interface PipelineOptions {
426
322
  /**
427
- * Skip the LLM pass and the release-notes file write (RELEASE_NOTES.md).
428
- * Per-package CHANGELOG.md is unaffected. Use during standing-PR update so the
323
+ * Skip the LLM pass and the release-notes file write. Use during standing-PR update so the
429
324
  * standing-PR workflow doesn't depend on LLM availability and doesn't pay for
430
325
  * an LLM call on every push to main.
431
326
  */
432
327
  skipReleaseNotes?: boolean;
433
- /**
434
- * Skip the changelog file writes (CHANGELOG.md). LLM + release-notes generation
435
- * are unaffected. Use during publish from manifest to regenerate only the
436
- * release notes against an already-bumped tree.
437
- */
328
+ /** Use during publish from manifest to regenerate only the release notes against an already-bumped tree. */
438
329
  skipChangelogs?: boolean;
439
330
  }
440
331
  declare function runPipeline(input: ChangelogInput, config: Config, dryRun: boolean, pipelineOptions?: PipelineOptions): Promise<PipelineResult>;
@@ -453,11 +344,7 @@ declare class TemplateError extends NotesError {
453
344
  declare class LLMError extends NotesError {
454
345
  readonly code = "LLM_ERROR";
455
346
  readonly suggestions: string[];
456
- /**
457
- * Whether the underlying failure is transient and worth retrying (timeout / 429 / 5xx / network).
458
- * `false` marks a non-retryable failure (4xx auth/validation) so `withRetry` fails fast instead of
459
- * burning the whole backoff budget. `undefined` means "unclassified" — callers retry by default.
460
- */
347
+ /** `undefined` means "unclassified" - callers retry by default. */
461
348
  readonly retryable?: boolean;
462
349
  constructor(message: string, options?: {
463
350
  retryable?: boolean;
@@ -498,15 +385,11 @@ declare function renderJson(contexts: TemplateContext[]): string;
498
385
  declare function writeJson(outputPath: string, contexts: TemplateContext[], dryRun: boolean): void;
499
386
 
500
387
  interface FormatVersionOptions {
501
- /** Include the package name in the version header (e.g. `## [pkg@1.0.0]`). */
502
388
  includePackageName?: boolean;
503
- /** Order to render LLM-categorised sections. Only applies when enhanced.categories is present. */
389
+ /** Order to render LLM-categorised sections. */
504
390
  categoryOrder?: string[];
505
- /** Migration/doc links to render at the end of the release notes section. */
506
391
  links?: LinksConfig;
507
- /** First-release placeholder intro config, or `false` to suppress it. */
508
392
  firstRelease?: FirstReleaseConfig | false;
509
- /** How bare `#NNN` issue/PR refs are rendered (`changelog.refs`; default `'link'`). */
510
393
  refs?: ChangelogRefsMode;
511
394
  }
512
395
  declare function formatVersion(context: TemplateContext, options?: FormatVersionOptions): string;
package/dist/index.js CHANGED
@@ -18,12 +18,12 @@ import {
18
18
  runPipeline,
19
19
  saveAuth,
20
20
  versionOutputToChangelogInput
21
- } from "./chunk-3X4XBORT.js";
21
+ } from "./chunk-OTH3XXI4.js";
22
22
  import {
23
23
  aggregateToRoot,
24
24
  detectMonorepo,
25
25
  writeMonorepoChangelogs
26
- } from "./chunk-OEY4SBEM.js";
26
+ } from "./chunk-KQQPQQSS.js";
27
27
  import {
28
28
  debug,
29
29
  formatVersion,
@@ -31,7 +31,7 @@ import {
31
31
  renderMarkdown,
32
32
  success,
33
33
  writeMarkdown
34
- } from "./chunk-LA3V665B.js";
34
+ } from "./chunk-CBMVDKDR.js";
35
35
 
36
36
  // src/output/json.ts
37
37
  import * as fs from "fs";
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@releasekit/notes",
3
- "version": "0.42.0",
3
+ "version": "0.42.1",
4
4
  "description": "Release notes and changelog generation with LLM-powered enhancement and flexible templating",
5
5
  "type": "module",
6
6
  "module": "./dist/index.js",