@releasekit/notes 0.42.0 → 0.43.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
@@ -34,7 +34,7 @@ npm install -g @releasekit/notes
34
34
  pnpm add -g @releasekit/notes
35
35
  ```
36
36
 
37
- > **Note:** ESM only. Requires Node.js 20+.
37
+ > **Note:** ESM only. Requires Node.js 22.12+.
38
38
 
39
39
  ## Quick Start
40
40
 
@@ -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-YNGSEWF6.js";
6
+ import "./chunk-TNTTAFQ4.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
  };
@@ -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-TNTTAFQ4.js";
17
18
 
18
19
  // ../config/dist/index.js
19
20
  import * as fs from "fs";
@@ -83,13 +84,17 @@ var VersionCargoConfigSchema = z.object({
83
84
  enabled: z.boolean().default(true).describe(
84
85
  "Version Cargo.toml manifests. Detected Rust packages are versioned by default; set false to opt out (e.g. a vendored crate, or Rust versioning handled elsewhere)."
85
86
  ),
86
- paths: z.array(z.string()).optional().describe("Directories to search for Cargo.toml files")
87
+ paths: z.array(z.string()).optional().describe(
88
+ "Directories, relative to each package, to bump a Cargo.toml in instead of the package's own directory. Ignored in group mode."
89
+ )
87
90
  });
88
91
  var VersionPubConfigSchema = z.object({
89
92
  enabled: z.boolean().default(true).describe(
90
93
  "Version pubspec.yaml manifests. Detected Dart/Flutter packages are versioned by default; set false to opt out."
91
94
  ),
92
- paths: z.array(z.string()).optional().describe("Directories to search for pubspec.yaml files")
95
+ paths: z.array(z.string()).optional().describe(
96
+ "Directories, relative to each package, to bump a pubspec.yaml in instead of the package's own directory. Ignored in group mode."
97
+ )
93
98
  });
94
99
  var VersionGroupSchema = z.object({
95
100
  packages: z.array(z.string()).min(1).describe(
@@ -321,10 +326,6 @@ var LLMOptionsSchema = z.object({
321
326
  });
322
327
  var LLMRetryConfigSchema = z.object({
323
328
  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
329
  initialDelay: z.number().int().nonnegative().optional().describe("Initial delay in ms"),
329
330
  maxDelay: z.number().int().positive().optional().describe("Maximum delay in ms"),
330
331
  backoffFactor: z.number().positive().optional().describe("Delay multiplier per attempt")
@@ -475,10 +476,12 @@ var StandingPrConfigSchema = z.object({
475
476
  branch: z.string().default("release/next").describe("Branch name for the standing release PR."),
476
477
  title: z.string().optional().describe(
477
478
  // 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."
479
+ "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
480
  ),
480
481
  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."),
482
+ deleteBranchOnMerge: z.boolean().default(true).describe(
483
+ "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."
484
+ ),
482
485
  mergeMethod: z.enum(["merge", "squash", "rebase"]).default("merge").describe("Merge method to use when merging the standing release PR via CLI."),
483
486
  minAge: z.string().optional().describe(
484
487
  "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 +494,7 @@ var StandingPrConfigSchema = z.object({
491
494
  "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
495
  ),
493
496
  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`.
497
+ // `@octocat` (no slash) is neither a username nor a team and would silently match nobody.
497
498
  z.string().regex(/^(?:[A-Za-z0-9-]+|@[A-Za-z0-9-]+\/[A-Za-z0-9._-]+)$/, {
498
499
  message: 'allowedActors entries must be a GitHub username (e.g. "octocat") or a team as "@org/team-slug" (note the slash).'
499
500
  })
@@ -533,14 +534,14 @@ var CIConfigSchema = z.object({
533
534
  z.boolean(),
534
535
  z.object({
535
536
  enabled: z.boolean().default(true).describe("Whether PR preview comments are posted."),
536
- refreshAfterRelease: z.boolean().default(false).describe(
537
- 'After a release completes, replay the preview comment on still-open feeder PRs so their "what would release" estimate is not left stale against the moved baseline. Cosmetic and best-effort \u2014 a failure here never fails the release. Driven automatically in-process after a successful release (both the direct and standing-PR publish paths); the standalone `refresh-after-release` command also performs it for setups that run it as a separate step.'
537
+ markStaleAfterRelease: z.boolean().default(false).describe(
538
+ "After a standing-PR publish, or a `releasekit release` that pushes the release branch, mark the preview on open PRs into that branch as stale until the PR's next push or label change. `releasekit publish` on its own doesn't. Best-effort: a failure never fails the release."
538
539
  )
539
540
  })
540
541
  ]).default(true).transform(
541
- (v) => typeof v === "boolean" ? { enabled: v, refreshAfterRelease: false } : { enabled: v.enabled ?? true, refreshAfterRelease: v.refreshAfterRelease ?? false }
542
+ (v) => typeof v === "boolean" ? { enabled: v, markStaleAfterRelease: false } : { enabled: v.enabled ?? true, markStaleAfterRelease: v.markStaleAfterRelease ?? false }
542
543
  ).describe(
543
- "PR preview comments showing what would be released if the PR is merged. `true`/`false` toggles them; the object form additionally enables `refreshAfterRelease` to refresh feeder-PR previews after a release."
544
+ "PR preview comments showing what would be released if the PR is merged. `true`/`false` toggles them; the object form additionally enables `markStaleAfterRelease` to mark feeder-PR previews stale after a release."
544
545
  ),
545
546
  labels: CILabelsConfigSchema.default({
546
547
  graduate: "release:graduate",
@@ -713,6 +714,11 @@ function assertNoRemovedTopLevelFields(config) {
713
714
  `ci no longer supports ${removed.join(", ")}. autoRelease was removed (it had no effect); skipPatterns and minChanges live under release.ci (release.ci.skipPatterns / release.ci.minChanges).`
714
715
  );
715
716
  }
717
+ if (isRecord(config.ci.prPreview) && "refreshAfterRelease" in config.ci.prPreview) {
718
+ throw new ConfigError(
719
+ "ci.prPreview.refreshAfterRelease was renamed to markStaleAfterRelease. It now marks open PRs' previews stale after a release instead of recomputing them."
720
+ );
721
+ }
716
722
  }
717
723
  if (isRecord(config.monorepo) && "mainPackage" in config.monorepo) {
718
724
  throw new ConfigError("monorepo.mainPackage was removed \u2014 use version.mainPackage instead.");
@@ -765,6 +771,10 @@ var InputParseError = class extends NotesError {
765
771
  "Use --input-source to specify format"
766
772
  ];
767
773
  };
774
+ var InputValidationError = class extends NotesError {
775
+ code = "INPUT_VALIDATION_ERROR";
776
+ suggestions = ["Pass `releasekit version --json` output unchanged"];
777
+ };
768
778
  var TemplateError = class extends NotesError {
769
779
  code = "TEMPLATE_ERROR";
770
780
  suggestions = [
@@ -781,11 +791,7 @@ var LLMError = class extends NotesError {
781
791
  "Check network connectivity",
782
792
  "Try with --no-llm to skip LLM processing"
783
793
  ];
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
- */
794
+ /** `undefined` means "unclassified" - callers retry by default. */
789
795
  retryable;
790
796
  constructor(message, options) {
791
797
  super(message);
@@ -816,6 +822,7 @@ function getExitCode(error2) {
816
822
  case "CONFIG_ERROR":
817
823
  return EXIT_CODES.CONFIG_ERROR;
818
824
  case "INPUT_PARSE_ERROR":
825
+ case "INPUT_VALIDATION_ERROR":
819
826
  return EXIT_CODES.INPUT_ERROR;
820
827
  case "TEMPLATE_ERROR":
821
828
  return EXIT_CODES.TEMPLATE_ERROR;
@@ -830,6 +837,44 @@ function getExitCode(error2) {
830
837
 
831
838
  // src/input/version-output.ts
832
839
  import * as fs5 from "fs";
840
+
841
+ // ../core/dist/version-output-schema.js
842
+ import { z as z3 } from "zod";
843
+ var VersionChangelogEntrySchema = z3.looseObject({
844
+ type: z3.string(),
845
+ description: z3.string(),
846
+ issueIds: z3.array(z3.string()).optional(),
847
+ prNumber: z3.string().optional(),
848
+ scope: z3.string().optional(),
849
+ originalType: z3.string().optional(),
850
+ breaking: z3.boolean().optional()
851
+ });
852
+ var VersionPackageChangelogSchema = z3.looseObject({
853
+ packageName: z3.string(),
854
+ version: z3.string(),
855
+ previousVersion: z3.string().nullable(),
856
+ revisionRange: z3.string(),
857
+ repoUrl: z3.string().nullable(),
858
+ entries: z3.array(VersionChangelogEntrySchema)
859
+ });
860
+ var VersionPackageUpdateSchema = z3.looseObject({
861
+ packageName: z3.string(),
862
+ newVersion: z3.string(),
863
+ filePath: z3.string(),
864
+ files: z3.array(z3.string()).optional(),
865
+ tag: z3.string().optional()
866
+ });
867
+ var VersionOutputSchema = z3.looseObject({
868
+ dryRun: z3.boolean(),
869
+ updates: z3.array(VersionPackageUpdateSchema),
870
+ changelogs: z3.array(VersionPackageChangelogSchema),
871
+ commitMessage: z3.string().optional(),
872
+ tags: z3.array(z3.string()),
873
+ baselineTags: z3.array(z3.string()).optional()
874
+ });
875
+
876
+ // src/input/version-output.ts
877
+ var NotesVersionOutputSchema = VersionOutputSchema.pick({ changelogs: true });
833
878
  function normalizeEntryType(type) {
834
879
  const typeMap = {
835
880
  added: "added",
@@ -889,7 +934,13 @@ function parseVersionOutput(json) {
889
934
  } catch (error2) {
890
935
  throw new InputParseError(error2 instanceof Error ? error2.message : String(error2));
891
936
  }
892
- return versionOutputToChangelogInput(data);
937
+ const result = NotesVersionOutputSchema.safeParse(data);
938
+ if (!result.success) {
939
+ const issues = result.error.issues.map((issue) => `${issue.path.join(".") || "(root)"}: ${issue.message}`).join("\n");
940
+ throw new InputValidationError(`Version output failed schema validation:
941
+ ${issues}`);
942
+ }
943
+ return versionOutputToChangelogInput(result.data);
893
944
  }
894
945
  function parseVersionOutputFile(filePath) {
895
946
  const content = fs5.readFileSync(filePath, "utf-8");
@@ -992,7 +1043,6 @@ function isBotComment(comment) {
992
1043
  }
993
1044
  var REPO_PERMISSIONS = ["admin", "maintain", "write", "triage", "read", "none"];
994
1045
  var MAX_RELEASE_PAGES = 3;
995
- var MAX_OPEN_PR_PAGES = 5;
996
1046
  function labelNames(labels) {
997
1047
  return (labels ?? []).map((label) => typeof label === "string" ? label : label.name ?? "");
998
1048
  }
@@ -1046,25 +1096,27 @@ var GitHubForge = class {
1046
1096
  });
1047
1097
  return data.map((pr) => ({ number: pr.number, mergedAt: pr.merged_at }));
1048
1098
  }
1049
- async listOpenPullRequests() {
1099
+ async listOpenPullRequests(base, limit) {
1050
1100
  const prs = [];
1051
- for (let page = 1; page <= MAX_OPEN_PR_PAGES; page++) {
1101
+ const perPage = Math.min(limit, 100);
1102
+ for (let page = 1; prs.length < limit; page++) {
1052
1103
  const { data } = await this.octokit.rest.pulls.list({
1053
1104
  ...this.base,
1054
1105
  state: "open",
1106
+ base,
1055
1107
  sort: "updated",
1056
1108
  direction: "desc",
1057
- per_page: 100,
1109
+ per_page: perPage,
1058
1110
  page
1059
1111
  });
1060
1112
  for (const pr of data) {
1061
- prs.push({ number: pr.number, headRef: pr.head.ref, draft: pr.draft ?? false, baseSha: pr.base.sha });
1113
+ prs.push({ number: pr.number, headRef: pr.head.ref, baseRef: pr.base.ref });
1062
1114
  }
1063
- if (data.length < 100) {
1115
+ if (data.length < perPage) {
1064
1116
  break;
1065
1117
  }
1066
1118
  }
1067
- return prs;
1119
+ return prs.slice(0, limit);
1068
1120
  }
1069
1121
  async getIssue(issueNumber) {
1070
1122
  const { data } = await this.octokit.rest.issues.get({ ...this.base, issue_number: issueNumber });
@@ -1077,7 +1129,7 @@ var GitHubForge = class {
1077
1129
  }
1078
1130
  async getPullRequest(prNumber) {
1079
1131
  const { data } = await this.octokit.rest.pulls.get({ ...this.base, pull_number: prNumber });
1080
- return { body: data.body ?? "", labels: labelNames(data.labels) };
1132
+ return { body: data.body ?? "", labels: labelNames(data.labels), headSha: data.head?.sha, baseRef: data.base?.ref };
1081
1133
  }
1082
1134
  async createPullRequest(pr) {
1083
1135
  const { data } = await this.octokit.rest.pulls.create({ ...this.base, ...pr });
@@ -1349,12 +1401,9 @@ var LLM_DEFAULTS = {
1349
1401
  timeout: 6e4,
1350
1402
  // 16k tokens accommodates large changelogs without hitting most model ceilings.
1351
1403
  maxTokens: 16384,
1352
- // 0.7 balances coherence (low temp) with natural-sounding variation (high temp).
1404
+ // Balances coherence with natural-sounding variation.
1353
1405
  temperature: 0.7,
1354
1406
  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
1407
  enhanceCategorizeChunkSize: 30,
1359
1408
  retry: {
1360
1409
  maxAttempts: 3,
@@ -1362,9 +1411,8 @@ var LLM_DEFAULTS = {
1362
1411
  maxDelay: 3e4,
1363
1412
  backoffFactor: 2
1364
1413
  }
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.
1414
+ // No default model: model ids rot (providers deprecate them), so `llm.model` is required and validated
1415
+ // at config load.
1368
1416
  };
1369
1417
 
1370
1418
  // src/llm/examples/fetcher.ts
@@ -1454,10 +1502,12 @@ function groupByCategory(llmEntries, entries) {
1454
1502
  if (!entry) {
1455
1503
  continue;
1456
1504
  }
1457
- if (!categoryMap.has(category)) {
1458
- categoryMap.set(category, []);
1505
+ const bucket = categoryMap.get(category);
1506
+ if (bucket) {
1507
+ bucket.push(entry);
1508
+ } else {
1509
+ categoryMap.set(category, [entry]);
1459
1510
  }
1460
- categoryMap.get(category).push(entry);
1461
1511
  }
1462
1512
  const result = [];
1463
1513
  for (const [category, catEntries] of categoryMap) {
@@ -1539,9 +1589,9 @@ function parseReleaseBodyToExample(markdown, version) {
1539
1589
  if (!line) {
1540
1590
  continue;
1541
1591
  }
1542
- const headingMatch = /^#{2,4} (.+)/.exec(line);
1543
- if (headingMatch) {
1544
- currentCategory = headingMatch[1].trim();
1592
+ const heading = /^#{2,4} (.+)/.exec(line)?.[1];
1593
+ if (heading) {
1594
+ currentCategory = heading.trim();
1545
1595
  continue;
1546
1596
  }
1547
1597
  if (line.startsWith("#")) {
@@ -1640,11 +1690,12 @@ async function fetchExamples(options) {
1640
1690
  const nonDraft = allReleases.filter((r) => !r.draft && !r.prerelease);
1641
1691
  const packageScoped = nonDraft.filter((r) => matchesPackageScoped(r.tagName, packageName));
1642
1692
  const matching = (packageScoped.length > 0 ? packageScoped : isMonorepo ? [] : nonDraft.filter((r) => matchesBareVersion(r.tagName))).slice(0, count);
1643
- if (matching.length === 0) {
1693
+ const latest = matching[0];
1694
+ if (!latest) {
1644
1695
  debug(`No matching releases found for ${packageName}`);
1645
1696
  return [];
1646
1697
  }
1647
- const latestTag = matching[0].tagName;
1698
+ const latestTag = latest.tagName;
1648
1699
  const key = cacheKey(owner, repo, packageName);
1649
1700
  const cached = readCache(key, latestTag, count);
1650
1701
  if (cached) {
@@ -1735,10 +1786,6 @@ var BaseLLMProvider = class {
1735
1786
  }
1736
1787
  return Math.min(Math.trunc(timeout), MAX_TIMEOUT_MS);
1737
1788
  }
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
1789
  async withIdleTimeout(label, options, request) {
1743
1790
  const ms = this.getTimeout(options);
1744
1791
  const controller = new AbortController();
@@ -2160,23 +2207,23 @@ ${instructions}`;
2160
2207
  }
2161
2208
 
2162
2209
  // src/llm/schemas.ts
2163
- import { z as z3 } from "zod";
2164
- var EntryOutputSchema = z3.object({
2165
- description: z3.string(),
2166
- category: z3.string(),
2167
- scope: z3.string().nullable(),
2168
- breaking: z3.boolean().nullable(),
2169
- leadIn: z3.string().nullable()
2210
+ import { z as z4 } from "zod";
2211
+ var EntryOutputSchema = z4.object({
2212
+ description: z4.string(),
2213
+ category: z4.string(),
2214
+ scope: z4.string().nullable(),
2215
+ breaking: z4.boolean().nullable(),
2216
+ leadIn: z4.string().nullable()
2170
2217
  });
2171
- var EnhanceAndCategorizeOutputSchema = z3.object({
2172
- entries: z3.array(EntryOutputSchema)
2218
+ var EnhanceAndCategorizeOutputSchema = z4.object({
2219
+ entries: z4.array(EntryOutputSchema)
2173
2220
  });
2174
- var CategorizeEntryOutputSchema = z3.object({
2175
- category: z3.string(),
2176
- scope: z3.string().nullable()
2221
+ var CategorizeEntryOutputSchema = z4.object({
2222
+ category: z4.string(),
2223
+ scope: z4.string().nullable()
2177
2224
  });
2178
- var CategorizeOutputSchema = z3.object({
2179
- entries: z3.array(CategorizeEntryOutputSchema)
2225
+ var CategorizeOutputSchema = z4.object({
2226
+ entries: z4.array(CategorizeEntryOutputSchema)
2180
2227
  });
2181
2228
  function nullableString() {
2182
2229
  return { anyOf: [{ type: "string" }, { type: "null" }] };
@@ -2445,7 +2492,10 @@ async function enhanceEntries(provider, entries, context, concurrency = LLM_DEFA
2445
2492
  batch.map(async (entry) => {
2446
2493
  try {
2447
2494
  const newDescription = await enhanceEntry(provider, entry, context);
2448
- return { ...entry, description: newDescription };
2495
+ return {
2496
+ ...entry,
2497
+ description: removeDescriptionRefs(newDescription, [...entry.issueIds ?? [], entry.prNumber])
2498
+ };
2449
2499
  } catch {
2450
2500
  failures++;
2451
2501
  return entry;
@@ -2467,7 +2517,7 @@ function buildSystemPrompt3(categories, style) {
2467
2517
  categories,
2468
2518
  `Categories: Group into meaningful categories (e.g., "New", "Fixed", "Changed", "Removed").`
2469
2519
  );
2470
- const pairs = categories && categories.length > 0 ? categories.filter((c) => c.scopes?.length).map((c) => ({ name: c.name, scopes: c.scopes })) : [];
2520
+ const pairs = (categories ?? []).flatMap((c) => c.scopes?.length ? [{ name: c.name, scopes: c.scopes }] : []);
2471
2521
  const scopeInstruction = renderScopeInstruction(pairs, " entries");
2472
2522
  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
2523
 
@@ -2530,7 +2580,7 @@ function createEnhanceAndCategorizeValidator(entries, context) {
2530
2580
  }
2531
2581
  return {
2532
2582
  ...original,
2533
- description: llmEntry.description,
2583
+ description: removeDescriptionRefs(llmEntry.description, [...original.issueIds ?? [], original.prNumber]),
2534
2584
  scope: llmEntry.scope ?? void 0,
2535
2585
  breaking: original.breaking || llmEntry.breaking === true,
2536
2586
  leadIn: llmEntry.leadIn ?? void 0
@@ -3148,7 +3198,6 @@ async function processWithLLM(context, llmConfig, examples, packageNames) {
3148
3198
  provider = {
3149
3199
  name: baseProvider.name,
3150
3200
  capabilities: baseProvider.capabilities,
3151
- // Fail fast on non-transient errors (4xx auth/validation); only retry timeout/429/5xx/network.
3152
3201
  complete: (messages, opts) => withRetry(() => baseProvider.complete(messages, { ...configOptions, ...opts }), {
3153
3202
  ...retryOpts,
3154
3203
  shouldRetry: isRetryableLLMError
@@ -3374,7 +3423,7 @@ async function runPipeline(input, config, dryRun, pipelineOptions) {
3374
3423
  const dir = releaseNotesConfig.file.dir;
3375
3424
  info(`Generating release notes \u2192 ${dir}`);
3376
3425
  try {
3377
- const { detectMonorepo } = await import("./aggregator-75QONDAK.js");
3426
+ const { detectMonorepo } = await import("./aggregator-FLRONORL.js");
3378
3427
  const nested = detectMonorepo(process.cwd()).isMonorepo || contexts.length > 1;
3379
3428
  const renderContent = (ctx) => {
3380
3429
  if (releaseNotesConfig.templates?.path) {
@@ -3438,7 +3487,7 @@ async function processInput(inputJson, config, dryRun, pipelineOptions) {
3438
3487
  return runPipeline(input, config, dryRun, pipelineOptions);
3439
3488
  }
3440
3489
  async function writeMonorepoFiles(contexts, config, dryRun, fileName, refs) {
3441
- const { detectMonorepo, writeMonorepoChangelogs } = await import("./aggregator-75QONDAK.js");
3490
+ const { detectMonorepo, writeMonorepoChangelogs } = await import("./aggregator-FLRONORL.js");
3442
3491
  const cwd = process.cwd();
3443
3492
  const detected = detectMonorepo(cwd);
3444
3493
  if (!detected.isMonorepo) {
@@ -3667,6 +3716,7 @@ export {
3667
3716
  saveAuth,
3668
3717
  NotesError,
3669
3718
  InputParseError,
3719
+ InputValidationError,
3670
3720
  TemplateError,
3671
3721
  LLMError,
3672
3722
  GitHubError,
@@ -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-TNTTAFQ4.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
  }
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-U5JUUEEQ.js";
5
5
  import {
6
6
  readPackageVersion
7
- } from "./chunk-LA3V665B.js";
7
+ } from "./chunk-TNTTAFQ4.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,62 @@ 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
+ /** Every manifest bumped in this directory, `filePath` included. Absent in older manifests. */
88
+ files?: string[];
89
+ /** Absent when all packages share one tag. */
152
90
  tag?: string;
153
91
  /**
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.
92
+ * The workspace-root package.json, bumped only to keep the root version in lockstep. Not a publishable package, so
93
+ * exclude it from package counts and lists.
157
94
  */
158
95
  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
96
  group?: string;
166
97
  /**
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.
98
+ * Set in an `--include-prerequisites` release: `'target'` is an explicitly-selected (group-expanded) package that
99
+ * gets the bump/prerelease/stable override; `'prerequisite'` is a changed transitive dependency pulled in to keep
100
+ * the targets installable, which keeps its own commit-driven bump. Absent on plain releases and for the root
101
+ * lockstep bump - treat an absent role as a target.
172
102
  */
173
103
  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
104
  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
- */
105
+ /** Absent in older manifests. */
187
106
  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
107
  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
- */
108
+ /** Absent in older manifests - re-derive it with {@link deriveReleaseChannel}. */
198
109
  channel?: ReleaseChannel;
199
110
  }
200
111
 
@@ -203,11 +114,6 @@ interface RetryOptions {
203
114
  initialDelay?: number;
204
115
  maxDelay?: number;
205
116
  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
117
  shouldRetry?: (error: unknown) => boolean;
212
118
  }
213
119
 
@@ -222,7 +128,7 @@ interface ChangelogEntry {
222
128
  description: string;
223
129
  issueIds?: string[];
224
130
  /** 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. */
131
+ * {@link issueIds} is the PR vs. a closed issue. */
226
132
  prNumber?: string;
227
133
  scope?: string;
228
134
  originalType?: string;
@@ -270,8 +176,6 @@ interface TemplateContext {
270
176
  entries: ChangelogEntry[];
271
177
  compareUrl?: string;
272
178
  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
179
  isFirstRelease?: boolean;
276
180
  }
277
181
  interface DocumentContext {
@@ -282,12 +186,10 @@ interface DocumentContext {
282
186
  versions: TemplateContext[];
283
187
  unreleased?: TemplateContext;
284
188
  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
189
+ /** Templates can use this to suppress document-level headings that are redundant
287
190
  * when the content is embedded in a release that already shows the package/version. */
288
191
  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
192
+ /** `'release'` is the GitHub release body. Templates can branch on it - e.g. emit docs-site
291
193
  * YAML frontmatter only for `'file'`, since it would render as literal text in a GitHub release. */
292
194
  output?: 'file' | 'release';
293
195
  }
@@ -381,7 +283,6 @@ interface ChangelogConfig {
381
283
  mode?: LocationMode;
382
284
  file?: string;
383
285
  templates?: TemplateConfig;
384
- /** How bare `#NNN` issue/PR refs render in the changelog. Default `'link'` when unset. */
385
286
  refs?: ChangelogRefsMode;
386
287
  }
387
288
  interface LinksConfig {
@@ -393,20 +294,17 @@ interface LinksConfig {
393
294
  title?: string;
394
295
  }
395
296
  interface ReleaseNotesFileConfig {
396
- /** Directory for the per-version release-notes files (default: release-notes). */
397
297
  dir?: string;
398
298
  }
399
299
  interface FirstReleaseConfig {
400
- /** Placeholder intro line for a package's first release. Supports ${packageName} and ${version}. */
300
+ /** Supports ${packageName} and ${version}. */
401
301
  text?: string;
402
302
  }
403
303
  interface ReleaseNotesConfig {
404
- /** In-repo per-version file output. Omit to keep notes only on the GitHub release body. */
405
304
  file?: ReleaseNotesFileConfig;
406
305
  templates?: TemplateConfig;
407
306
  llm?: LLMConfig;
408
307
  links?: LinksConfig;
409
- /** First-release placeholder intro. Default-on with a factual line; set to false to disable. */
410
308
  firstRelease?: false | FirstReleaseConfig;
411
309
  }
412
310
 
@@ -424,17 +322,12 @@ interface PipelineResult {
424
322
  }
425
323
  interface PipelineOptions {
426
324
  /**
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
325
+ * Skip the LLM pass and the release-notes file write. Use during standing-PR update so the
429
326
  * standing-PR workflow doesn't depend on LLM availability and doesn't pay for
430
327
  * an LLM call on every push to main.
431
328
  */
432
329
  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
- */
330
+ /** Use during publish from manifest to regenerate only the release notes against an already-bumped tree. */
438
331
  skipChangelogs?: boolean;
439
332
  }
440
333
  declare function runPipeline(input: ChangelogInput, config: Config, dryRun: boolean, pipelineOptions?: PipelineOptions): Promise<PipelineResult>;
@@ -446,6 +339,10 @@ declare class InputParseError extends NotesError {
446
339
  readonly code = "INPUT_PARSE_ERROR";
447
340
  readonly suggestions: string[];
448
341
  }
342
+ declare class InputValidationError extends NotesError {
343
+ readonly code = "INPUT_VALIDATION_ERROR";
344
+ readonly suggestions: string[];
345
+ }
449
346
  declare class TemplateError extends NotesError {
450
347
  readonly code = "TEMPLATE_ERROR";
451
348
  readonly suggestions: string[];
@@ -453,11 +350,7 @@ declare class TemplateError extends NotesError {
453
350
  declare class LLMError extends NotesError {
454
351
  readonly code = "LLM_ERROR";
455
352
  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
- */
353
+ /** `undefined` means "unclassified" - callers retry by default. */
461
354
  readonly retryable?: boolean;
462
355
  constructor(message: string, options?: {
463
356
  retryable?: boolean;
@@ -474,7 +367,7 @@ declare class ConfigError extends NotesError {
474
367
  }
475
368
  declare function getExitCode(error: NotesError): number;
476
369
 
477
- declare function versionOutputToChangelogInput(data: VersionOutput): ChangelogInput;
370
+ declare function versionOutputToChangelogInput(data: Pick<VersionOutput, 'changelogs'>): ChangelogInput;
478
371
  declare function parseVersionOutput(json: string): ChangelogInput;
479
372
  declare function parseVersionOutputFile(filePath: string): ChangelogInput;
480
373
  declare function parseVersionOutputStdin(): Promise<ChangelogInput>;
@@ -498,20 +391,16 @@ declare function renderJson(contexts: TemplateContext[]): string;
498
391
  declare function writeJson(outputPath: string, contexts: TemplateContext[], dryRun: boolean): void;
499
392
 
500
393
  interface FormatVersionOptions {
501
- /** Include the package name in the version header (e.g. `## [pkg@1.0.0]`). */
502
394
  includePackageName?: boolean;
503
- /** Order to render LLM-categorised sections. Only applies when enhanced.categories is present. */
395
+ /** Order to render LLM-categorised sections. */
504
396
  categoryOrder?: string[];
505
- /** Migration/doc links to render at the end of the release notes section. */
506
397
  links?: LinksConfig;
507
- /** First-release placeholder intro config, or `false` to suppress it. */
508
398
  firstRelease?: FirstReleaseConfig | false;
509
- /** How bare `#NNN` issue/PR refs are rendered (`changelog.refs`; default `'link'`). */
510
399
  refs?: ChangelogRefsMode;
511
400
  }
512
401
  declare function formatVersion(context: TemplateContext, options?: FormatVersionOptions): string;
513
402
  declare function renderMarkdown(contexts: TemplateContext[], options?: FormatVersionOptions): string;
514
403
  declare function writeMarkdown(outputPath: string, contexts: TemplateContext[], config: Config, dryRun: boolean, options?: FormatVersionOptions): void;
515
404
 
516
- export { ConfigError, GitHubError, InputParseError, LLMError, NotesError, TemplateError, aggregateToRoot, createTemplateContext, detectMonorepo, formatVersion, getDefaultConfig, getExitCode, loadAuth, loadConfig, parseVersionOutput, parseVersionOutputFile, parseVersionOutputStdin, processInput, renderJson, renderMarkdown, runPipeline, saveAuth, versionOutputToChangelogInput, writeJson, writeMarkdown, writeMonorepoChangelogs };
405
+ export { ConfigError, GitHubError, InputParseError, InputValidationError, LLMError, NotesError, TemplateError, aggregateToRoot, createTemplateContext, detectMonorepo, formatVersion, getDefaultConfig, getExitCode, loadAuth, loadConfig, parseVersionOutput, parseVersionOutputFile, parseVersionOutputStdin, processInput, renderJson, renderMarkdown, runPipeline, saveAuth, versionOutputToChangelogInput, writeJson, writeMarkdown, writeMonorepoChangelogs };
517
406
  export type { ChangelogConfig, ChangelogEntry, ChangelogInput, ChangelogType, CompleteOptions, Config, DocumentContext, EnhancedCategory, EnhancedData, FirstReleaseConfig, InputSource, JSONSchema, LLMCategory, LLMConfig, LLMOptions, LLMPromptOverrides, LLMPromptsConfig, LinksConfig, LocationMode, PRContext, PackageChangelog, PipelineOptions, PipelineResult, ReleaseNotesConfig, ReleaseNotesFileConfig, RetryOptions, ScopeConfig, ScopeRules, TemplateConfig, TemplateContext, TemplateEngine, UpdateStrategy };
package/dist/index.js CHANGED
@@ -2,6 +2,7 @@ import {
2
2
  ConfigError,
3
3
  GitHubError,
4
4
  InputParseError,
5
+ InputValidationError,
5
6
  LLMError,
6
7
  NotesError,
7
8
  TemplateError,
@@ -18,12 +19,12 @@ import {
18
19
  runPipeline,
19
20
  saveAuth,
20
21
  versionOutputToChangelogInput
21
- } from "./chunk-3X4XBORT.js";
22
+ } from "./chunk-U5JUUEEQ.js";
22
23
  import {
23
24
  aggregateToRoot,
24
25
  detectMonorepo,
25
26
  writeMonorepoChangelogs
26
- } from "./chunk-OEY4SBEM.js";
27
+ } from "./chunk-YNGSEWF6.js";
27
28
  import {
28
29
  debug,
29
30
  formatVersion,
@@ -31,7 +32,7 @@ import {
31
32
  renderMarkdown,
32
33
  success,
33
34
  writeMarkdown
34
- } from "./chunk-LA3V665B.js";
35
+ } from "./chunk-TNTTAFQ4.js";
35
36
 
36
37
  // src/output/json.ts
37
38
  import * as fs from "fs";
@@ -72,6 +73,7 @@ export {
72
73
  ConfigError,
73
74
  GitHubError,
74
75
  InputParseError,
76
+ InputValidationError,
75
77
  LLMError,
76
78
  NotesError,
77
79
  TemplateError,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@releasekit/notes",
3
- "version": "0.42.0",
3
+ "version": "0.43.0",
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",