@releasekit/notes 0.19.3 → 0.21.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.
@@ -10,7 +10,7 @@ import {
10
10
  success,
11
11
  warn,
12
12
  writeMarkdown
13
- } from "./chunk-77FGMGVD.js";
13
+ } from "./chunk-QCJ545PJ.js";
14
14
 
15
15
  // ../config/dist/index.js
16
16
  import * as fs from "fs";
@@ -257,8 +257,7 @@ var LLMPromptOverridesSchema = z.object({
257
257
  releaseNotes: z.string().optional()
258
258
  });
259
259
  var LLMPromptsConfigSchema = z.object({
260
- instructions: LLMPromptOverridesSchema.optional(),
261
- templates: LLMPromptOverridesSchema.optional()
260
+ instructions: LLMPromptOverridesSchema.optional()
262
261
  });
263
262
  var LLMConfigSchema = z.object({
264
263
  provider: z.string(),
@@ -269,16 +268,34 @@ var LLMConfigSchema = z.object({
269
268
  concurrency: z.number().int().positive().optional(),
270
269
  retry: LLMRetryConfigSchema.optional(),
271
270
  tasks: LLMTasksConfigSchema.optional(),
272
- categories: z.array(LLMCategorySchema).optional(),
273
- style: z.string().optional(),
271
+ categories: z.array(LLMCategorySchema).default(() => [
272
+ { name: "Breaking", description: "Breaking changes that require user action to upgrade" },
273
+ { name: "New", description: "New features and capabilities" },
274
+ { name: "Changed", description: "Changes to existing functionality" },
275
+ { name: "Fixed", description: "Bug fixes" },
276
+ { name: "Developer", description: "Internal changes: CI, tooling, dependencies, refactoring" }
277
+ ]),
278
+ style: z.string().default(
279
+ 'Write in past tense ("Added feature", not "Add feature"). Be concise and user-focused. Lead with the impact, not the implementation detail.'
280
+ ),
274
281
  scopes: ScopeConfigSchema.optional(),
275
- prompts: LLMPromptsConfigSchema.optional()
282
+ prompts: LLMPromptsConfigSchema.optional(),
283
+ examples: z.number().int().min(0).max(5).default(3),
284
+ context: z.object({
285
+ pullRequests: z.boolean().default(true)
286
+ }).default({ pullRequests: true }),
287
+ categoryOrder: z.array(z.string()).optional()
276
288
  });
277
289
  var ReleaseNotesConfigSchema = z.object({
278
290
  mode: LocationModeSchema.optional(),
279
291
  file: z.string().optional(),
280
292
  templates: TemplateConfigSchema.optional(),
281
- llm: LLMConfigSchema.optional()
293
+ llm: LLMConfigSchema.optional(),
294
+ links: z.object({
295
+ items: z.array(z.object({ label: z.string(), url: z.string().url() })).optional(),
296
+ fromPRBodyMarker: z.string().optional(),
297
+ title: z.string().optional()
298
+ }).optional()
282
299
  });
283
300
  var NotesInputConfigSchema = z.object({
284
301
  source: z.string().optional(),
@@ -290,9 +307,11 @@ var NotesConfigSchema = z.object({
290
307
  updateStrategy: z.enum(["prepend", "regenerate"]).optional()
291
308
  });
292
309
  var CILabelsConfigSchema = z.object({
293
- stable: z.string().default("release:stable"),
294
- prerelease: z.string().default("release:prerelease"),
310
+ stable: z.string().default("channel:stable"),
311
+ prerelease: z.string().default("channel:prerelease"),
295
312
  skip: z.string().default("release:skip"),
313
+ /** Bypass the standing PR for one merge — triggers a direct release. Standing-pr mode only. */
314
+ immediate: z.string().default("release:immediate"),
296
315
  major: z.string().default("bump:major"),
297
316
  minor: z.string().default("bump:minor"),
298
317
  patch: z.string().default("bump:patch")
@@ -307,8 +326,6 @@ var StandingPrConfigSchema = z.object({
307
326
  labels: z.array(z.string()).default(["release"]),
308
327
  /** Whether to auto-delete the release branch after PR merge. Default: true */
309
328
  deleteBranchOnMerge: z.boolean().default(true),
310
- /** Allow teams to edit the release notes section in the PR body before publishing. Default: false */
311
- editableNotes: z.boolean().default(false),
312
329
  /** Merge method to use when merging the standing release PR. Default: 'merge' */
313
330
  mergeMethod: z.enum(["merge", "squash", "rebase"]).default("merge"),
314
331
  /** 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 status check. */
@@ -317,7 +334,7 @@ var StandingPrConfigSchema = z.object({
317
334
  minPackages: z.number().int().positive().optional()
318
335
  });
319
336
  var CIConfigSchema = z.object({
320
- releaseStrategy: z.enum(["manual", "direct", "standing-pr", "scheduled"]).default("direct"),
337
+ releaseStrategy: z.enum(["manual", "direct", "standing-pr"]).default("direct"),
321
338
  releaseTrigger: z.enum(["commit", "label"]).default("label"),
322
339
  prPreview: z.boolean().default(true),
323
340
  autoRelease: z.boolean().default(false),
@@ -330,9 +347,10 @@ var CIConfigSchema = z.object({
330
347
  skipPatterns: z.array(z.string()).default(["chore: release "]),
331
348
  minChanges: z.number().int().positive().default(1),
332
349
  labels: CILabelsConfigSchema.default({
333
- stable: "release:stable",
334
- prerelease: "release:prerelease",
350
+ stable: "channel:stable",
351
+ prerelease: "channel:prerelease",
335
352
  skip: "release:skip",
353
+ immediate: "release:immediate",
336
354
  major: "bump:major",
337
355
  minor: "bump:minor",
338
356
  patch: "bump:patch"
@@ -607,13 +625,103 @@ function getDefaultConfig() {
607
625
  }
608
626
 
609
627
  // src/core/pipeline.ts
610
- import * as fs9 from "fs";
611
- import * as path8 from "path";
628
+ import * as fs10 from "fs";
629
+ import * as path9 from "path";
630
+
631
+ // src/llm/context/prFetcher.ts
632
+ import { RequestError } from "@octokit/request-error";
633
+ import { Octokit } from "@octokit/rest";
634
+ var BODY_CAP = 2048;
635
+ function stripHtmlComments(input) {
636
+ let result = "";
637
+ let i = 0;
638
+ while (i < input.length) {
639
+ if (input.startsWith("<!--", i)) {
640
+ const end = input.indexOf("-->", i + 4);
641
+ i = end === -1 ? input.length : end + 3;
642
+ } else {
643
+ result += input[i++];
644
+ }
645
+ }
646
+ return result;
647
+ }
648
+ function stripDetailsTags(input) {
649
+ let result = "";
650
+ let i = 0;
651
+ let depth = 0;
652
+ const lower = input.toLowerCase();
653
+ while (i < input.length) {
654
+ if (lower.startsWith("<details", i)) {
655
+ depth++;
656
+ const tagEnd = lower.indexOf(">", i);
657
+ i = tagEnd === -1 ? input.length : tagEnd + 1;
658
+ } else if (lower.startsWith("</details>", i)) {
659
+ if (depth > 0) depth--;
660
+ i += 10;
661
+ } else {
662
+ if (depth === 0) result += input[i];
663
+ i++;
664
+ }
665
+ }
666
+ return result;
667
+ }
668
+ function sanitiseBody(raw) {
669
+ return stripDetailsTags(stripHtmlComments(raw)).replace(/!\[.*?\]\(.*?\)/g, "").replace(/\n{3,}/g, "\n\n").trim();
670
+ }
671
+ function truncateBody(body) {
672
+ if (body.length <= BODY_CAP) return body;
673
+ const headingPos = body.lastIndexOf("\n#", BODY_CAP);
674
+ const cutAt = headingPos > BODY_CAP / 2 ? headingPos : BODY_CAP;
675
+ return `${body.slice(0, cutAt).trimEnd()}
676
+ \u2026`;
677
+ }
678
+ var FETCH_CONCURRENCY = 5;
679
+ async function fetchPullRequestContext(owner, repo, issueNumbers, token, cache) {
680
+ const octokit = new Octokit({ auth: token });
681
+ const needed = issueNumbers.filter((n) => !cache.has(n));
682
+ for (let i = 0; i < needed.length; i += FETCH_CONCURRENCY) {
683
+ const batch = needed.slice(i, i + FETCH_CONCURRENCY);
684
+ await Promise.all(
685
+ batch.map(async (number) => {
686
+ try {
687
+ const { data } = await octokit.rest.issues.get({ owner, repo, issue_number: number });
688
+ if (!data.pull_request) {
689
+ cache.set(number, null);
690
+ return;
691
+ }
692
+ const raw = data.body ?? "";
693
+ const body = truncateBody(sanitiseBody(raw));
694
+ cache.set(number, { number, title: data.title, body });
695
+ } catch (error2) {
696
+ if (error2 instanceof RequestError) {
697
+ if (error2.status === 401 || error2.status === 403) {
698
+ warn(`GitHub API auth error fetching PR #${number} (${error2.status}): check GITHUB_TOKEN permissions`);
699
+ } else if (error2.status === 404) {
700
+ cache.set(number, null);
701
+ } else {
702
+ debug(`Failed to fetch PR #${number}: ${error2.message}`);
703
+ }
704
+ } else {
705
+ debug(`Failed to fetch PR #${number}: ${error2 instanceof Error ? error2.message : String(error2)}`);
706
+ }
707
+ }
708
+ })
709
+ );
710
+ }
711
+ }
712
+ function parseIssueNumbers(issueIds) {
713
+ return issueIds.map((id) => parseInt(id.replace(/^#/, ""), 10)).filter((n) => !Number.isNaN(n) && n > 0);
714
+ }
715
+ function resolveGitHubToken() {
716
+ return process.env.GITHUB_TOKEN || process.env.GH_TOKEN || void 0;
717
+ }
612
718
 
613
719
  // src/llm/defaults.ts
614
720
  var LLM_DEFAULTS = {
615
721
  timeout: 6e4,
722
+ // 16k tokens accommodates large changelogs without hitting most model ceilings.
616
723
  maxTokens: 16384,
724
+ // 0.7 balances coherence (low temp) with natural-sounding variation (high temp).
617
725
  temperature: 0.7,
618
726
  concurrency: 5,
619
727
  retry: {
@@ -630,6 +738,150 @@ var LLM_DEFAULTS = {
630
738
  }
631
739
  };
632
740
 
741
+ // src/llm/examples/fetcher.ts
742
+ import { createHash } from "crypto";
743
+ import * as fs5 from "fs";
744
+ import * as os2 from "os";
745
+ import * as path5 from "path";
746
+ import { RequestError as RequestError2 } from "@octokit/request-error";
747
+ import { Octokit as Octokit2 } from "@octokit/rest";
748
+
749
+ // src/llm/examples/parser.ts
750
+ var LEAD_IN_RE = /^\*\*([^*]+)\*\*:\s*/;
751
+ var BULLET_RE = /^[-*]\s+/;
752
+ function parseReleaseBodyToExample(markdown, version) {
753
+ const lines = markdown.split("\n");
754
+ const entries = [];
755
+ let currentCategory = "General";
756
+ for (const raw of lines) {
757
+ const line = raw.trim();
758
+ if (!line) continue;
759
+ const headingMatch = /^#{2,4} (.+)/.exec(line);
760
+ if (headingMatch) {
761
+ currentCategory = headingMatch[1].trim();
762
+ continue;
763
+ }
764
+ if (line.startsWith("#")) continue;
765
+ if (BULLET_RE.test(line)) {
766
+ const text = line.replace(BULLET_RE, "");
767
+ const leadInMatch = LEAD_IN_RE.exec(text);
768
+ const entry = {
769
+ description: leadInMatch ? text.slice(leadInMatch[0].length) : text,
770
+ category: currentCategory
771
+ };
772
+ if (leadInMatch) entry.leadIn = leadInMatch[1];
773
+ if (/\*\*BREAKING\*\*/i.test(text)) entry.breaking = true;
774
+ entries.push(entry);
775
+ }
776
+ }
777
+ if (entries.length === 0) return null;
778
+ return { version, entries };
779
+ }
780
+ function renderExamplesBlock(examples) {
781
+ if (examples.length === 0) return "";
782
+ const blocks = examples.map((ex) => {
783
+ const entryLines = ex.entries.map((e) => {
784
+ const leadIn = e.leadIn ? `**${e.leadIn}**: ` : "";
785
+ const scope = e.scope ? ` (${e.scope})` : "";
786
+ const breaking = e.breaking ? " **BREAKING**" : "";
787
+ return ` - [${e.category}]${scope}: ${leadIn}${e.description}${breaking}`;
788
+ }).join("\n");
789
+ return `<example version="${ex.version}">
790
+ ${entryLines}
791
+ </example>`;
792
+ });
793
+ return `
794
+ Examples from prior releases (use these as style references):
795
+ ${blocks.join("\n")}
796
+ `;
797
+ }
798
+
799
+ // src/llm/examples/fetcher.ts
800
+ function cacheDir() {
801
+ return path5.join(os2.tmpdir(), "releasekit", "examples");
802
+ }
803
+ function cacheKey(owner, repo, packageName) {
804
+ const safe = packageName.replace(/[^a-zA-Z0-9-]/g, "_");
805
+ const hash = createHash("sha256").update(packageName).digest("hex").slice(0, 8);
806
+ return path5.join(cacheDir(), owner, repo, `${safe}_${hash}.json`);
807
+ }
808
+ function readCache(key, latestTag, count) {
809
+ try {
810
+ const raw = fs5.readFileSync(key, "utf-8");
811
+ const entry = JSON.parse(raw);
812
+ if (entry.latestTag !== latestTag || entry.count < count) return null;
813
+ return entry.examples;
814
+ } catch {
815
+ return null;
816
+ }
817
+ }
818
+ function writeCache(key, latestTag, count, examples) {
819
+ try {
820
+ fs5.mkdirSync(path5.dirname(key), { recursive: true });
821
+ fs5.writeFileSync(key, JSON.stringify({ latestTag, count, examples }), "utf-8");
822
+ } catch {
823
+ }
824
+ }
825
+ function matchesPackageScoped(tagName, packageName) {
826
+ const escaped = packageName.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
827
+ return new RegExp(`^${escaped}@`).test(tagName);
828
+ }
829
+ function matchesBareVersion(tagName) {
830
+ return /^v?\d/.test(tagName);
831
+ }
832
+ async function fetchExamples(options) {
833
+ const { owner, repo, packageName, count, githubToken, isMonorepo } = options;
834
+ if (count === 0) return [];
835
+ const token = githubToken ?? process.env.GITHUB_TOKEN ?? process.env.GH_TOKEN;
836
+ if (!token) {
837
+ debug("No GitHub token available \u2014 skipping examples fetch");
838
+ return [];
839
+ }
840
+ const octokit = new Octokit2({ auth: token });
841
+ try {
842
+ const allReleases = [];
843
+ for (let page = 1; page <= 3; page++) {
844
+ const { data } = await octokit.rest.repos.listReleases({ owner, repo, per_page: 100, page });
845
+ allReleases.push(...data);
846
+ const totalScoped = allReleases.filter(
847
+ (r) => !r.draft && !r.prerelease && matchesPackageScoped(r.tag_name, packageName)
848
+ ).length;
849
+ if (totalScoped >= count || data.length < 100) break;
850
+ }
851
+ const nonDraft = allReleases.filter((r) => !r.draft && !r.prerelease);
852
+ const packageScoped = nonDraft.filter((r) => matchesPackageScoped(r.tag_name, packageName));
853
+ const matching = (packageScoped.length > 0 ? packageScoped : isMonorepo ? [] : nonDraft.filter((r) => matchesBareVersion(r.tag_name))).slice(0, count);
854
+ if (matching.length === 0) {
855
+ debug(`No matching releases found for ${packageName}`);
856
+ return [];
857
+ }
858
+ const latestTag = matching[0].tag_name;
859
+ const key = cacheKey(owner, repo, packageName);
860
+ const cached = readCache(key, latestTag, count);
861
+ if (cached) {
862
+ debug(`Using cached examples for ${packageName} (tag: ${latestTag})`);
863
+ return cached.slice(0, count);
864
+ }
865
+ const examples = [];
866
+ for (const release of matching) {
867
+ if (!release.body) continue;
868
+ const version = release.tag_name.replace(/^.*@/, "").replace(/^v/, "");
869
+ const example = parseReleaseBodyToExample(release.body, version);
870
+ if (example) examples.push(example);
871
+ }
872
+ if (examples.length > 0) writeCache(key, latestTag, count, examples);
873
+ debug(`Fetched ${examples.length} examples for ${packageName}`);
874
+ return examples;
875
+ } catch (error2) {
876
+ if (error2 instanceof RequestError2 && (error2.status === 401 || error2.status === 403)) {
877
+ warn(`GitHub API auth error (${error2.status}) \u2014 skipping examples fetch; check GITHUB_TOKEN permissions`);
878
+ } else {
879
+ debug(`Failed to fetch examples: ${error2 instanceof Error ? error2.message : String(error2)}`);
880
+ }
881
+ return [];
882
+ }
883
+ }
884
+
633
885
  // src/llm/anthropic.ts
634
886
  import Anthropic from "@anthropic-ai/sdk";
635
887
 
@@ -646,9 +898,24 @@ var BaseLLMProvider = class {
646
898
  }
647
899
  };
648
900
 
901
+ // src/llm/messages.ts
902
+ function debugLogMessages(providerName, messages) {
903
+ if (process.env.RELEASEKIT_DEBUG !== "1") return;
904
+ console.error(`[RELEASEKIT_DEBUG] ${providerName} messages (${messages.length}):`);
905
+ for (const msg of messages) {
906
+ const preview = msg.content.length > 300 ? `${msg.content.slice(0, 300)}\u2026` : msg.content;
907
+ console.error(` [${msg.role}]: ${preview}`);
908
+ }
909
+ }
910
+
649
911
  // src/llm/anthropic.ts
650
912
  var AnthropicProvider = class extends BaseLLMProvider {
651
913
  name = "anthropic";
914
+ capabilities = {
915
+ systemRole: true,
916
+ structuredOutputs: true,
917
+ toolUse: true
918
+ };
652
919
  client;
653
920
  model;
654
921
  constructor(config = {}) {
@@ -660,18 +927,45 @@ var AnthropicProvider = class extends BaseLLMProvider {
660
927
  this.client = new Anthropic({ apiKey });
661
928
  this.model = config.model ?? LLM_DEFAULTS.models.anthropic;
662
929
  }
663
- async complete(prompt, options) {
930
+ async complete(messages, options) {
931
+ debugLogMessages(this.name, messages);
932
+ const systemMsg = messages.find((m) => m.role === "system");
933
+ const nonSystemMessages = messages.filter((m) => m.role !== "system").map((m) => ({ role: m.role, content: m.content }));
664
934
  try {
935
+ if (options?.schema) {
936
+ const toolName = options.toolName ?? "emit_release_notes";
937
+ const response2 = await this.client.messages.create({
938
+ model: this.model,
939
+ max_tokens: this.getMaxTokens(options),
940
+ system: systemMsg?.content,
941
+ tools: [
942
+ {
943
+ name: toolName,
944
+ description: "Emit structured release notes data as JSON",
945
+ input_schema: options.schema
946
+ }
947
+ ],
948
+ tool_choice: { type: "tool", name: toolName },
949
+ messages: nonSystemMessages
950
+ });
951
+ const toolBlock = response2.content.find((b) => b.type === "tool_use");
952
+ if (toolBlock?.type === "tool_use") {
953
+ const structured = toolBlock.input;
954
+ return { content: JSON.stringify(structured), structured };
955
+ }
956
+ throw new LLMError("Expected tool_use block in Anthropic response");
957
+ }
665
958
  const response = await this.client.messages.create({
666
959
  model: this.model,
667
960
  max_tokens: this.getMaxTokens(options),
668
- messages: [{ role: "user", content: prompt }]
961
+ system: systemMsg?.content,
962
+ messages: nonSystemMessages
669
963
  });
670
964
  const firstBlock = response.content[0];
671
965
  if (!firstBlock || firstBlock.type !== "text") {
672
966
  throw new LLMError("Unexpected response format from Anthropic");
673
967
  }
674
- return firstBlock.text;
968
+ return { content: firstBlock.text };
675
969
  } catch (error2) {
676
970
  if (error2 instanceof LLMError) throw error2;
677
971
  throw new LLMError(`Anthropic API error: ${error2 instanceof Error ? error2.message : String(error2)}`);
@@ -682,6 +976,11 @@ var AnthropicProvider = class extends BaseLLMProvider {
682
976
  // src/llm/ollama.ts
683
977
  var OllamaProvider = class extends BaseLLMProvider {
684
978
  name = "ollama";
979
+ capabilities = {
980
+ systemRole: true,
981
+ structuredOutputs: true,
982
+ toolUse: false
983
+ };
685
984
  baseURL;
686
985
  model;
687
986
  apiKey;
@@ -691,16 +990,20 @@ var OllamaProvider = class extends BaseLLMProvider {
691
990
  this.model = config.model ?? process.env.OLLAMA_MODEL ?? LLM_DEFAULTS.models.ollama;
692
991
  this.apiKey = config.apiKey ?? process.env.OLLAMA_API_KEY;
693
992
  }
694
- async complete(prompt, options) {
993
+ async complete(messages, options) {
994
+ debugLogMessages(this.name, messages);
695
995
  const requestBody = {
696
996
  model: this.model,
697
- messages: [{ role: "user", content: prompt }],
997
+ messages: messages.map((m) => ({ role: m.role, content: m.content })),
698
998
  stream: false,
699
999
  options: {
700
1000
  num_predict: this.getMaxTokens(options),
701
1001
  temperature: this.getTemperature(options)
702
1002
  }
703
1003
  };
1004
+ if (options?.schema) {
1005
+ requestBody.format = options.schema;
1006
+ }
704
1007
  try {
705
1008
  const headers = {
706
1009
  "Content-Type": "application/json"
@@ -729,7 +1032,17 @@ var OllamaProvider = class extends BaseLLMProvider {
729
1032
  if (!data.message?.content) {
730
1033
  throw new LLMError("Empty response from Ollama");
731
1034
  }
732
- return data.message.content;
1035
+ const content = data.message.content;
1036
+ if (options?.schema) {
1037
+ try {
1038
+ const structured = JSON.parse(content);
1039
+ return { content, structured };
1040
+ } catch (e) {
1041
+ debug(`Ollama: failed to parse structured response: ${e instanceof Error ? e.message : String(e)}`);
1042
+ return { content };
1043
+ }
1044
+ }
1045
+ return { content };
733
1046
  } catch (error2) {
734
1047
  if (error2 instanceof LLMError) throw error2;
735
1048
  throw new LLMError(`Ollama error: ${error2 instanceof Error ? error2.message : String(error2)}`);
@@ -741,6 +1054,11 @@ var OllamaProvider = class extends BaseLLMProvider {
741
1054
  import OpenAI from "openai";
742
1055
  var OpenAIProvider = class extends BaseLLMProvider {
743
1056
  name = "openai";
1057
+ capabilities = {
1058
+ systemRole: true,
1059
+ structuredOutputs: true,
1060
+ toolUse: false
1061
+ };
744
1062
  client;
745
1063
  model;
746
1064
  constructor(config = {}) {
@@ -755,19 +1073,43 @@ var OpenAIProvider = class extends BaseLLMProvider {
755
1073
  });
756
1074
  this.model = config.model ?? LLM_DEFAULTS.models.openai;
757
1075
  }
758
- async complete(prompt, options) {
1076
+ async complete(messages, options) {
1077
+ debugLogMessages(this.name, messages);
759
1078
  try {
760
- const response = await this.client.chat.completions.create({
1079
+ const openaiMessages = messages.map((m) => ({ role: m.role, content: m.content }));
1080
+ const requestParams = {
761
1081
  model: this.model,
762
- messages: [{ role: "user", content: prompt }],
1082
+ messages: openaiMessages,
763
1083
  max_tokens: this.getMaxTokens(options),
764
- temperature: this.getTemperature(options)
765
- });
1084
+ temperature: this.getTemperature(options),
1085
+ stream: false,
1086
+ ...options?.schema && {
1087
+ response_format: {
1088
+ type: "json_schema",
1089
+ json_schema: {
1090
+ name: options.toolName ?? "release_notes",
1091
+ // eslint-disable-next-line @typescript-eslint/no-explicit-any
1092
+ schema: options.schema,
1093
+ strict: true
1094
+ }
1095
+ }
1096
+ }
1097
+ };
1098
+ const response = await this.client.chat.completions.create(requestParams);
766
1099
  const content = response.choices[0]?.message?.content;
767
1100
  if (!content) {
768
1101
  throw new LLMError("Empty response from OpenAI");
769
1102
  }
770
- return content;
1103
+ if (options?.schema) {
1104
+ try {
1105
+ const structured = JSON.parse(content);
1106
+ return { content, structured };
1107
+ } catch (e) {
1108
+ debug(`OpenAI: failed to parse structured response: ${e instanceof Error ? e.message : String(e)}`);
1109
+ return { content };
1110
+ }
1111
+ }
1112
+ return { content };
771
1113
  } catch (error2) {
772
1114
  if (error2 instanceof LLMError) throw error2;
773
1115
  throw new LLMError(`OpenAI API error: ${error2 instanceof Error ? error2.message : String(error2)}`);
@@ -779,6 +1121,11 @@ var OpenAIProvider = class extends BaseLLMProvider {
779
1121
  import OpenAI2 from "openai";
780
1122
  var OpenAICompatibleProvider = class extends BaseLLMProvider {
781
1123
  name = "openai-compatible";
1124
+ capabilities = {
1125
+ systemRole: true,
1126
+ structuredOutputs: false,
1127
+ toolUse: false
1128
+ };
782
1129
  client;
783
1130
  model;
784
1131
  constructor(config) {
@@ -790,19 +1137,23 @@ var OpenAICompatibleProvider = class extends BaseLLMProvider {
790
1137
  });
791
1138
  this.model = config.model ?? LLM_DEFAULTS.models["openai-compatible"];
792
1139
  }
793
- async complete(prompt, options) {
1140
+ async complete(messages, options) {
1141
+ debugLogMessages(this.name, messages);
794
1142
  try {
795
- const response = await this.client.chat.completions.create({
1143
+ const openaiMessages = messages.map((m) => ({ role: m.role, content: m.content }));
1144
+ const requestParams = {
796
1145
  model: this.model,
797
- messages: [{ role: "user", content: prompt }],
1146
+ messages: openaiMessages,
798
1147
  max_tokens: this.getMaxTokens(options),
799
- temperature: this.getTemperature(options)
800
- });
1148
+ temperature: this.getTemperature(options),
1149
+ stream: false
1150
+ };
1151
+ const response = await this.client.chat.completions.create(requestParams);
801
1152
  const content = response.choices[0]?.message?.content;
802
1153
  if (!content) {
803
1154
  throw new LLMError("Empty response from LLM");
804
1155
  }
805
- return content;
1156
+ return { content };
806
1157
  } catch (error2) {
807
1158
  if (error2 instanceof LLMError) throw error2;
808
1159
  throw new LLMError(`LLM API error: ${error2 instanceof Error ? error2.message : String(error2)}`);
@@ -820,26 +1171,112 @@ function extractJsonFromResponse(response) {
820
1171
  return stripped;
821
1172
  }
822
1173
 
823
- // src/llm/prompts.ts
824
- function resolvePrompt(taskName, defaultPrompt, promptsConfig) {
825
- if (!promptsConfig) return defaultPrompt;
826
- const fullTemplate = promptsConfig.templates?.[taskName];
827
- if (fullTemplate) return fullTemplate;
828
- const additionalInstructions = promptsConfig.instructions?.[taskName];
829
- if (additionalInstructions) {
830
- const insertionPoint = defaultPrompt.lastIndexOf("Output only valid JSON");
831
- if (insertionPoint !== -1) {
832
- return `${defaultPrompt.slice(0, insertionPoint)}Additional instructions:
833
- ${additionalInstructions}
834
-
835
- ${defaultPrompt.slice(insertionPoint)}`;
1174
+ // src/llm/correctiveRetry.ts
1175
+ async function withCorrectiveRetry(call, validate, buildCorrectionMessages3, initialMessages, maxCorrectiveAttempts = 2) {
1176
+ let messages = initialMessages;
1177
+ let lastError = "";
1178
+ for (let attempt = 0; attempt <= maxCorrectiveAttempts; attempt++) {
1179
+ const result = await call(messages, attempt === 0);
1180
+ const validation = validate(result);
1181
+ if (validation.valid) return validation.value;
1182
+ lastError = validation.error;
1183
+ if (attempt < maxCorrectiveAttempts) {
1184
+ const badContent = typeof result.structured !== "undefined" ? JSON.stringify(result.structured) : result.content;
1185
+ messages = [
1186
+ ...messages,
1187
+ { role: "assistant", content: badContent },
1188
+ ...buildCorrectionMessages3(badContent, validation.error)
1189
+ ];
836
1190
  }
837
- return `${defaultPrompt}
1191
+ }
1192
+ throw new LLMError(`Structured output validation failed after ${maxCorrectiveAttempts + 1} attempts: ${lastError}`);
1193
+ }
1194
+
1195
+ // src/llm/prompts.ts
1196
+ function resolveSystemPrompt(taskName, defaultSystemPrompt, promptsConfig) {
1197
+ const instructions = promptsConfig?.instructions?.[taskName];
1198
+ if (instructions) {
1199
+ return `${defaultSystemPrompt}
838
1200
 
839
1201
  Additional instructions:
840
- ${additionalInstructions}`;
1202
+ ${instructions}`;
841
1203
  }
842
- return defaultPrompt;
1204
+ return defaultSystemPrompt;
1205
+ }
1206
+
1207
+ // src/llm/schemas.ts
1208
+ import { z as z3 } from "zod";
1209
+ var EntryOutputSchema = z3.object({
1210
+ description: z3.string(),
1211
+ category: z3.string(),
1212
+ scope: z3.string().nullable(),
1213
+ breaking: z3.boolean().nullable(),
1214
+ leadIn: z3.string().nullable()
1215
+ });
1216
+ var EnhanceAndCategorizeOutputSchema = z3.object({
1217
+ entries: z3.array(EntryOutputSchema)
1218
+ });
1219
+ var CategorizeEntryOutputSchema = z3.object({
1220
+ category: z3.string(),
1221
+ scope: z3.string().nullable()
1222
+ });
1223
+ var CategorizeOutputSchema = z3.object({
1224
+ entries: z3.array(CategorizeEntryOutputSchema)
1225
+ });
1226
+ function nullableString() {
1227
+ return { anyOf: [{ type: "string" }, { type: "null" }] };
1228
+ }
1229
+ function nullableBoolean() {
1230
+ return { anyOf: [{ type: "boolean" }, { type: "null" }] };
1231
+ }
1232
+ function buildEnhanceAndCategorizeSchema(categories) {
1233
+ const categoryNames = categories.map((c) => c.name);
1234
+ const categoryField = categoryNames.length > 0 ? { type: "string", enum: categoryNames } : { type: "string" };
1235
+ return {
1236
+ type: "object",
1237
+ properties: {
1238
+ entries: {
1239
+ type: "array",
1240
+ items: {
1241
+ type: "object",
1242
+ properties: {
1243
+ description: { type: "string" },
1244
+ category: categoryField,
1245
+ scope: nullableString(),
1246
+ breaking: nullableBoolean(),
1247
+ leadIn: nullableString()
1248
+ },
1249
+ required: ["description", "category", "scope", "breaking", "leadIn"],
1250
+ additionalProperties: false
1251
+ }
1252
+ }
1253
+ },
1254
+ required: ["entries"],
1255
+ additionalProperties: false
1256
+ };
1257
+ }
1258
+ function buildCategorizeSchema(categories) {
1259
+ const categoryNames = categories.map((c) => c.name);
1260
+ const categoryField = categoryNames.length > 0 ? { type: "string", enum: categoryNames } : { type: "string" };
1261
+ return {
1262
+ type: "object",
1263
+ properties: {
1264
+ entries: {
1265
+ type: "array",
1266
+ items: {
1267
+ type: "object",
1268
+ properties: {
1269
+ category: categoryField,
1270
+ scope: nullableString()
1271
+ },
1272
+ required: ["category", "scope"],
1273
+ additionalProperties: false
1274
+ }
1275
+ }
1276
+ },
1277
+ required: ["entries"],
1278
+ additionalProperties: false
1279
+ };
843
1280
  }
844
1281
 
845
1282
  // src/llm/scopes.ts
@@ -869,127 +1306,194 @@ function resolveAllowedScopes(scopeConfig, categories, packageNames) {
869
1306
  }
870
1307
  return null;
871
1308
  }
872
- function validateScope(scope, allowedScopes, rules) {
1309
+ function validateScope(scope, allowedScopes, caseSensitive = false) {
873
1310
  if (!scope || allowedScopes === null) return scope;
874
1311
  if (allowedScopes.length === 0) return void 0;
875
- const caseSensitive = rules?.caseSensitive ?? false;
876
1312
  const normalise = (s) => caseSensitive ? s : s.toLowerCase();
877
1313
  const isAllowed = allowedScopes.some((a) => normalise(a) === normalise(scope));
878
- if (isAllowed) return scope;
879
- switch (rules?.invalidScopeAction ?? "remove") {
880
- case "keep":
881
- return scope;
882
- case "fallback":
883
- return rules?.fallbackScope;
884
- default:
885
- return void 0;
886
- }
1314
+ return isAllowed ? scope : void 0;
887
1315
  }
888
1316
  function validateEntryScopes(entries, scopeConfig, categories) {
889
1317
  const allowedScopes = resolveAllowedScopes(scopeConfig, categories);
890
- if (allowedScopes === null) return entries;
891
- return entries.map((entry) => ({
892
- ...entry,
893
- scope: validateScope(entry.scope, allowedScopes, scopeConfig?.rules)
894
- }));
1318
+ if (allowedScopes === null) return { valid: true, entries, errors: [] };
1319
+ const caseSensitive = scopeConfig?.rules?.caseSensitive ?? false;
1320
+ const action = scopeConfig?.rules?.invalidScopeAction ?? "remove";
1321
+ const fallback = scopeConfig?.rules?.fallbackScope;
1322
+ const errors = [];
1323
+ if (action === "fallback" && fallback !== void 0 && validateScope(fallback, allowedScopes, caseSensitive) === void 0) {
1324
+ warn(
1325
+ `scopes.rules.fallbackScope "${fallback}" is not in the allowed scope list (${allowedScopes.length ? allowedScopes.join(", ") : "<empty>"}); substituted scopes will violate the allow-list. Add "${fallback}" to the allow list or change invalidScopeAction.`
1326
+ );
1327
+ }
1328
+ const validatedEntries = entries.map((entry, index) => {
1329
+ const cleaned = validateScope(entry.scope, allowedScopes, caseSensitive);
1330
+ if (entry.scope && cleaned === void 0) {
1331
+ errors.push({
1332
+ entryIndex: index,
1333
+ providedScope: entry.scope,
1334
+ allowedScopes
1335
+ });
1336
+ const replacement = action === "keep" ? entry.scope : action === "fallback" ? fallback : void 0;
1337
+ return { ...entry, scope: replacement };
1338
+ }
1339
+ return entry.scope !== cleaned ? { ...entry, scope: cleaned } : entry;
1340
+ });
1341
+ return { valid: true, entries: validatedEntries, errors };
895
1342
  }
896
1343
 
897
- // src/llm/tasks/categorize.ts
898
- var DEFAULT_CATEGORIZE_PROMPT = `You are categorizing changelog entries for a software release.
899
-
900
- Given the following entries, group them into meaningful categories (e.g., "Core", "UI", "API", "Performance", "Bug Fixes", "Documentation").
901
-
902
- Output a JSON object where keys are category names and values are arrays of entry indices (0-based).
903
-
904
- Entries:
905
- {{entries}}
1344
+ // src/llm/tasks/shared.ts
1345
+ function escAttr(s) {
1346
+ return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/"/g, "&quot;");
1347
+ }
1348
+ function escBody(s) {
1349
+ return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
1350
+ }
1351
+ function renderPRBlocks(entry) {
1352
+ if (!entry.context?.prs.length) return "";
1353
+ return entry.context.prs.map(
1354
+ (pr) => `<pr number="${pr.number}" title="${escAttr(pr.title)}">${pr.body ? `
1355
+ ${escBody(pr.body)}
1356
+ ` : ""}</pr>`
1357
+ ).join("\n");
1358
+ }
1359
+ function groupByCategory(llmEntries, entries) {
1360
+ const categoryMap = /* @__PURE__ */ new Map();
1361
+ for (let i = 0; i < llmEntries.length; i++) {
1362
+ const category = llmEntries[i]?.category ?? "Unknown";
1363
+ const entry = entries[i];
1364
+ if (!entry) continue;
1365
+ if (!categoryMap.has(category)) categoryMap.set(category, []);
1366
+ categoryMap.get(category).push(entry);
1367
+ }
1368
+ const result = [];
1369
+ for (const [category, catEntries] of categoryMap) {
1370
+ result.push({ category, entries: catEntries });
1371
+ }
1372
+ return result;
1373
+ }
906
1374
 
907
- Output only valid JSON, nothing else:`;
908
- function buildCustomCategorizePrompt(categories) {
909
- const categoryList = categories.map((c) => {
1375
+ // src/llm/tasks/categorize.ts
1376
+ function buildSystemPrompt(categories) {
1377
+ const categorySection = categories && categories.length > 0 ? `Categories (use ONLY these exact names):
1378
+ ${categories.map((c) => {
910
1379
  const scopeInfo = c.scopes?.length ? ` Allowed scopes: ${c.scopes.join(", ")}.` : "";
911
1380
  return `- "${c.name}": ${c.description}${scopeInfo}`;
912
- }).join("\n");
913
- const scopeMap = getAllowedScopesFromCategories(categories);
914
- let scopeInstructions = "";
915
- if (scopeMap.size > 0) {
916
- const entries = [];
917
- for (const [catName, scopes] of scopeMap) {
918
- entries.push(`For "${catName}", assign a scope from: ${scopes.join(", ")}.`);
919
- }
920
- scopeInstructions = `
921
-
922
- ${entries.join("\n")}
923
- Only use scopes from these predefined lists. If an entry does not fit any scope, set scope to null.`;
1381
+ }).join("\n")}` : `Categories: Group into meaningful categories (e.g., "Core", "UI", "API", "Performance", "Bug Fixes", "Documentation").`;
1382
+ let scopeInstruction = "";
1383
+ if (categories && categories.length > 0) {
1384
+ const scopeMap = getAllowedScopesFromCategories(categories);
1385
+ if (scopeMap.size > 0) {
1386
+ const parts = [];
1387
+ for (const [catName, scopes] of scopeMap) {
1388
+ parts.push(`For "${catName}", use a scope from: ${scopes.join(", ")}.`);
1389
+ }
1390
+ scopeInstruction = `
1391
+ ${parts.join("\n")}
1392
+ Only use scopes from these predefined lists. Set scope to null if no scope applies.`;
1393
+ }
924
1394
  }
925
1395
  return `You are categorizing changelog entries for a software release.
926
1396
 
927
- Given the following entries, group them into the specified categories. Only use the categories listed below in this exact order:
928
-
929
- Categories:
930
- ${categoryList}${scopeInstructions}
931
-
932
- Output a JSON object with two fields:
933
- - "categories": an object where keys are category names and values are arrays of entry indices (0-based)
934
- - "scopes": an object where keys are entry indices (as strings) and values are scope labels. Only include entries that have a valid scope from the predefined list.
1397
+ ${categorySection}${scopeInstruction}
935
1398
 
936
- Entries:
937
- {{entries}}
1399
+ Output a JSON object with an "entries" array. Each element (same order as input) must have:
1400
+ - "category": category name from the list above
1401
+ - "scope": subcategory label or null`;
1402
+ }
1403
+ function buildUserPrompt(entries) {
1404
+ const text = entries.map((e, i) => `${i}. [${e.type}]: ${e.description}`).join("\n");
1405
+ return `Entries:
1406
+ ${text}`;
1407
+ }
1408
+ function buildCorrectionMessages(_badContent, error2) {
1409
+ return [
1410
+ {
1411
+ role: "user",
1412
+ content: `Your previous response had an error: ${error2}
938
1413
 
939
- Output only valid JSON, nothing else:`;
1414
+ Please fix the issue and output only valid JSON matching the required schema.`
1415
+ }
1416
+ ];
1417
+ }
1418
+ function makeValidator(entries, context) {
1419
+ const cleanEntries = entries.map((e) => ({ ...e, scope: void 0 }));
1420
+ return (result) => {
1421
+ let parsed;
1422
+ try {
1423
+ parsed = typeof result.structured !== "undefined" ? result.structured : JSON.parse(extractJsonFromResponse(result.content));
1424
+ } catch (e) {
1425
+ return { valid: false, error: `Invalid JSON: ${e instanceof Error ? e.message : String(e)}` };
1426
+ }
1427
+ const zodResult = CategorizeOutputSchema.safeParse(parsed);
1428
+ if (!zodResult.success) {
1429
+ return { valid: false, error: `Schema error: ${zodResult.error.message}` };
1430
+ }
1431
+ if (zodResult.data.entries.length !== entries.length) {
1432
+ return {
1433
+ valid: false,
1434
+ error: `Expected ${entries.length} entries, got ${zodResult.data.entries.length}`
1435
+ };
1436
+ }
1437
+ const categoryNames = context.categories?.map((c) => c.name);
1438
+ if (categoryNames?.length) {
1439
+ const invalid = zodResult.data.entries.filter((e) => !categoryNames.includes(e.category)).map((e) => e.category);
1440
+ if (invalid.length > 0) {
1441
+ const unique = [...new Set(invalid)];
1442
+ return {
1443
+ valid: false,
1444
+ error: `Unknown categories: ${unique.join(", ")}. Valid categories: ${categoryNames.join(", ")}`
1445
+ };
1446
+ }
1447
+ }
1448
+ const withScopes = cleanEntries.map((entry, i) => {
1449
+ const llmEntry = zodResult.data.entries[i];
1450
+ const scope = llmEntry?.scope ?? void 0;
1451
+ return scope ? { ...entry, scope } : entry;
1452
+ });
1453
+ const scopeResult = validateEntryScopes(withScopes, context.scopes, context.categories);
1454
+ if (scopeResult.errors.length > 0) {
1455
+ const offenders = [...new Set(scopeResult.errors.map((e) => e.providedScope))];
1456
+ warn(
1457
+ `LLM returned ${scopeResult.errors.length} entries with disallowed scopes (${offenders.join(", ")}); resolved per invalidScopeAction.`
1458
+ );
1459
+ }
1460
+ return { valid: true, value: groupByCategory(zodResult.data.entries, scopeResult.entries) };
1461
+ };
940
1462
  }
941
1463
  async function categorizeEntries(provider, entries, context) {
942
1464
  if (entries.length === 0) {
943
1465
  return [];
944
1466
  }
945
- const entriesCopy = entries.map((e) => ({ ...e, scope: void 0 }));
946
- const entriesText = entriesCopy.map((e, i) => `${i}. [${e.type}]: ${e.description}`).join("\n");
947
- const hasCustomCategories = context.categories && context.categories.length > 0;
948
- const defaultPrompt = hasCustomCategories ? buildCustomCategorizePrompt(context.categories) : DEFAULT_CATEGORIZE_PROMPT;
949
- const promptTemplate = resolvePrompt("categorize", defaultPrompt, context.prompts);
950
- const prompt = promptTemplate.replace("{{entries}}", entriesText);
1467
+ const systemPrompt = resolveSystemPrompt("categorize", buildSystemPrompt(context.categories), context.prompts);
1468
+ const initialMessages = [
1469
+ { role: "system", content: systemPrompt },
1470
+ { role: "user", content: buildUserPrompt(entries) }
1471
+ ];
1472
+ const schema = buildCategorizeSchema(context.categories ?? []);
1473
+ const validate = makeValidator(entries, context);
951
1474
  try {
952
- const response = await provider.complete(prompt);
953
- const parsed = JSON.parse(extractJsonFromResponse(response));
954
- const result = [];
955
- if (hasCustomCategories && parsed.categories) {
956
- const categoryMap = parsed.categories;
957
- const scopeMap = parsed.scopes || {};
958
- for (const [indexStr, scope] of Object.entries(scopeMap)) {
959
- const idx = Number.parseInt(indexStr, 10);
960
- if (entriesCopy[idx] && scope?.trim()) {
961
- entriesCopy[idx] = { ...entriesCopy[idx], scope: scope.trim() };
962
- }
963
- }
964
- const validatedEntries = validateEntryScopes(entriesCopy, context.scopes, context.categories);
965
- for (const [category, rawIndices] of Object.entries(categoryMap)) {
966
- const indices = Array.isArray(rawIndices) ? rawIndices : [];
967
- const categoryEntries = indices.map((i) => validatedEntries[i]).filter((e) => e !== void 0);
968
- if (categoryEntries.length > 0) {
969
- result.push({ category, entries: categoryEntries });
970
- }
971
- }
972
- } else {
973
- const categoryMap = parsed;
974
- for (const [category, rawIndices] of Object.entries(categoryMap)) {
975
- const indices = Array.isArray(rawIndices) ? rawIndices : [];
976
- const categoryEntries = indices.map((i) => entriesCopy[i]).filter((e) => e !== void 0);
977
- if (categoryEntries.length > 0) {
978
- result.push({ category, entries: categoryEntries });
979
- }
980
- }
981
- }
982
- return result;
983
- } catch (error2) {
984
- warn(
985
- `LLM categorization failed, falling back to General: ${error2 instanceof Error ? error2.message : String(error2)}`
1475
+ return await withCorrectiveRetry(
1476
+ (messages, isFirstAttempt) => provider.complete(
1477
+ messages,
1478
+ isFirstAttempt && provider.capabilities.structuredOutputs ? { schema, toolName: "categorize_entries" } : void 0
1479
+ ),
1480
+ validate,
1481
+ buildCorrectionMessages,
1482
+ initialMessages
986
1483
  );
987
- return [{ category: "General", entries: entriesCopy }];
1484
+ } catch (error2) {
1485
+ if (error2 instanceof LLMError) {
1486
+ warn(`categorizeEntries failed after all attempts: ${error2.message}. Returning entries under General.`);
1487
+ return [{ category: "General", entries: entries.map((e) => ({ ...e, scope: void 0 })) }];
1488
+ }
1489
+ throw error2;
988
1490
  }
989
1491
  }
990
1492
 
991
1493
  // src/llm/tasks/enhance.ts
992
- var DEFAULT_ENHANCE_PROMPT = `You are improving changelog entries for a software project.
1494
+ function buildSystemPrompt2(style) {
1495
+ const styleText = style ? `- ${style}` : '- Use past tense ("Added feature" not "Add feature")';
1496
+ return `You are improving changelog entries for a software project.
993
1497
  Given a technical commit message, rewrite it as a clear, user-friendly changelog entry.
994
1498
 
995
1499
  Rules:
@@ -997,20 +1501,26 @@ Rules:
997
1501
  - Focus on user impact, not implementation details
998
1502
  - Don't use technical jargon unless necessary
999
1503
  - Preserve the scope if mentioned (e.g., "core:", "api:")
1000
- {{style}}
1001
-
1002
- Original entry:
1003
- Type: {{type}}
1004
- {{#if scope}}Scope: {{scope}}{{/if}}
1005
- Description: {{description}}
1504
+ ${styleText}
1006
1505
 
1007
- Rewritten description (only output the new description, nothing else):`;
1506
+ Output only the rewritten description, nothing else.`;
1507
+ }
1508
+ function buildUserPrompt2(entry) {
1509
+ const lines = [`Type: ${entry.type}`];
1510
+ if (entry.scope) lines.push(`Scope: ${entry.scope}`);
1511
+ lines.push(`Description: ${entry.description}`);
1512
+ const prBlocks = renderPRBlocks(entry);
1513
+ if (prBlocks) lines.push(prBlocks);
1514
+ return lines.join("\n");
1515
+ }
1008
1516
  async function enhanceEntry(provider, entry, context) {
1009
- const styleText = context.style ? `- ${context.style}` : '- Use present tense ("Add feature" not "Added feature")';
1010
- const defaultPrompt = DEFAULT_ENHANCE_PROMPT.replace("{{style}}", styleText).replace("{{type}}", entry.type).replace("{{#if scope}}Scope: {{scope}}{{/if}}", entry.scope ? `Scope: ${entry.scope}` : "").replace("{{description}}", entry.description);
1011
- const prompt = resolvePrompt("enhance", defaultPrompt, context.prompts);
1012
- const response = await provider.complete(prompt);
1013
- return response.trim();
1517
+ const systemPrompt = resolveSystemPrompt("enhance", buildSystemPrompt2(context.style), context.prompts);
1518
+ const messages = [
1519
+ { role: "system", content: systemPrompt },
1520
+ { role: "user", content: buildUserPrompt2(entry) }
1521
+ ];
1522
+ const result = await provider.complete(messages);
1523
+ return result.content.trim();
1014
1524
  }
1015
1525
  async function enhanceEntries(provider, entries, context, concurrency = LLM_DEFAULTS.concurrency) {
1016
1526
  const results = [];
@@ -1031,57 +1541,25 @@ async function enhanceEntries(provider, entries, context, concurrency = LLM_DEFA
1031
1541
  return results;
1032
1542
  }
1033
1543
 
1034
- // src/utils/retry.ts
1035
- function sleep(ms) {
1036
- return new Promise((resolve2) => setTimeout(resolve2, ms));
1037
- }
1038
- async function withRetry(fn, options = {}) {
1039
- const maxAttempts = options.maxAttempts ?? 3;
1040
- const initialDelay = options.initialDelay ?? 1e3;
1041
- const maxDelay = options.maxDelay ?? 3e4;
1042
- const backoffFactor = options.backoffFactor ?? 2;
1043
- let lastError;
1044
- for (let attempt = 0; attempt < maxAttempts; attempt++) {
1045
- try {
1046
- return await fn();
1047
- } catch (error2) {
1048
- lastError = error2;
1049
- if (attempt < maxAttempts - 1) {
1050
- const base = Math.min(initialDelay * backoffFactor ** attempt, maxDelay);
1051
- const jitter = base * 0.2 * (Math.random() * 2 - 1);
1052
- await sleep(Math.max(0, base + jitter));
1053
- }
1054
- }
1055
- }
1056
- throw lastError;
1057
- }
1058
-
1059
1544
  // src/llm/tasks/enhance-and-categorize.ts
1060
- function buildPrompt(entries, categories, style) {
1061
- const entriesText = entries.map((e, i) => `${i}. [${e.type}]${e.scope ? ` (${e.scope})` : ""}: ${e.description}`).join("\n");
1062
- const styleText = style || 'Use present tense ("Add feature" not "Added feature"). Be concise.';
1063
- const categorySection = categories ? `Categories (use ONLY these):
1545
+ function buildSystemPrompt3(categories, style) {
1546
+ const styleText = style || 'Use past tense ("Added feature" not "Add feature"). Be concise.';
1547
+ const categorySection = categories && categories.length > 0 ? `Categories (use ONLY these exact names):
1064
1548
  ${categories.map((c) => {
1065
1549
  const scopeInfo = c.scopes?.length ? ` Allowed scopes: ${c.scopes.join(", ")}.` : "";
1066
1550
  return `- "${c.name}": ${c.description}${scopeInfo}`;
1067
1551
  }).join("\n")}` : `Categories: Group into meaningful categories (e.g., "New", "Fixed", "Changed", "Removed").`;
1068
1552
  let scopeInstruction = "";
1069
- if (categories) {
1070
- const scopeMap = getAllowedScopesFromCategories(categories);
1071
- if (scopeMap.size > 0) {
1072
- const parts = [];
1073
- for (const [catName, scopes] of scopeMap) {
1074
- parts.push(`For "${catName}" entries, assign a scope from: ${scopes.join(", ")}.`);
1075
- }
1553
+ if (categories && categories.length > 0) {
1554
+ const withScopes = categories.filter((c) => c.scopes?.length);
1555
+ if (withScopes.length > 0) {
1556
+ const parts = withScopes.map((c) => `For "${c.name}" entries, use a scope from: ${c.scopes?.join(", ")}.`);
1076
1557
  scopeInstruction = `
1077
1558
  ${parts.join("\n")}
1078
1559
  Only use scopes from these predefined lists. Set scope to null if no scope applies.`;
1079
1560
  }
1080
1561
  }
1081
- return `You are generating release notes for a software project. Given the following changelog entries, do two things:
1082
-
1083
- 1. **Rewrite** each entry as a clear, user-friendly description
1084
- 2. **Categorize** each entry into the appropriate category
1562
+ return `You are generating release notes for a software project. Given changelog entries, rewrite each as a clear user-friendly description and categorize it.
1085
1563
 
1086
1564
  Style guidelines:
1087
1565
  - ${styleText}
@@ -1090,70 +1568,130 @@ Style guidelines:
1090
1568
 
1091
1569
  ${categorySection}${scopeInstruction}
1092
1570
 
1093
- Entries:
1094
- ${entriesText}
1571
+ leadIn guidelines:
1572
+ - Set leadIn ONLY when an entry introduces a named API, feature, or concept worth scanning for (e.g. "Deeplink testing", "browser.electron.triggerDeeplink()")
1573
+ - Leave leadIn null for routine fixes, dependency bumps, small tweaks, and refactors
1095
1574
 
1096
- Output a JSON object with:
1097
- - "entries": array of objects, one per input entry (same order), each with: { "description": "rewritten text", "category": "CategoryName", "scope": "optional subcategory label or null" }
1575
+ Output a JSON object with an "entries" array. Each element (same order as input) must have:
1576
+ - "description": rewritten user-friendly text
1577
+ - "category": category name (from the list above)
1578
+ - "scope": subcategory label or null
1579
+ - "breaking": true if this is a breaking change, false or null otherwise
1580
+ - "leadIn": short noun phrase for scanning (e.g. "Streaming API") or null`;
1581
+ }
1582
+ function buildUserPrompt3(entries) {
1583
+ const entriesText = entries.map((e, i) => {
1584
+ const prBlocks = renderPRBlocks(e);
1585
+ const header = `${i}. [${e.type}]${e.scope ? ` (${e.scope})` : ""}: ${e.description}`;
1586
+ return prBlocks ? `${header}
1587
+ ${prBlocks}` : header;
1588
+ }).join("\n");
1589
+ return `Entries:
1590
+ ${entriesText}`;
1591
+ }
1592
+ function buildCorrectionMessages2(_badContent, error2) {
1593
+ return [
1594
+ {
1595
+ role: "user",
1596
+ content: `Your previous response had an error: ${error2}
1098
1597
 
1099
- Output only valid JSON, nothing else:`;
1598
+ Please fix the issue and output only valid JSON matching the required schema.`
1599
+ }
1600
+ ];
1601
+ }
1602
+ function makeValidator2(entries, context) {
1603
+ return (result) => {
1604
+ let parsed;
1605
+ try {
1606
+ parsed = typeof result.structured !== "undefined" ? result.structured : JSON.parse(extractJsonFromResponse(result.content));
1607
+ } catch (e) {
1608
+ return { valid: false, error: `Invalid JSON: ${e instanceof Error ? e.message : String(e)}` };
1609
+ }
1610
+ const zodResult = EnhanceAndCategorizeOutputSchema.safeParse(parsed);
1611
+ if (!zodResult.success) {
1612
+ return { valid: false, error: `Schema error: ${zodResult.error.message}` };
1613
+ }
1614
+ if (zodResult.data.entries.length !== entries.length) {
1615
+ return {
1616
+ valid: false,
1617
+ error: `Expected ${entries.length} entries, got ${zodResult.data.entries.length}`
1618
+ };
1619
+ }
1620
+ const categoryNames = context.categories?.map((c) => c.name);
1621
+ if (categoryNames?.length) {
1622
+ const invalid = zodResult.data.entries.filter((e) => !categoryNames.includes(e.category)).map((e) => e.category);
1623
+ if (invalid.length > 0) {
1624
+ const unique = [...new Set(invalid)];
1625
+ return {
1626
+ valid: false,
1627
+ error: `Unknown categories: ${unique.join(", ")}. Valid categories: ${categoryNames.join(", ")}`
1628
+ };
1629
+ }
1630
+ }
1631
+ const enhancedEntries = entries.map((original, i) => {
1632
+ const llmEntry = zodResult.data.entries[i];
1633
+ if (!llmEntry) return original;
1634
+ return {
1635
+ ...original,
1636
+ description: llmEntry.description,
1637
+ scope: llmEntry.scope ?? void 0,
1638
+ breaking: llmEntry.breaking ?? original.breaking,
1639
+ leadIn: llmEntry.leadIn ?? void 0
1640
+ };
1641
+ });
1642
+ const scopeResult = validateEntryScopes(enhancedEntries, context.scopes, context.categories);
1643
+ if (scopeResult.errors.length > 0) {
1644
+ const offenders = [...new Set(scopeResult.errors.map((e) => e.providedScope))];
1645
+ warn(
1646
+ `LLM returned ${scopeResult.errors.length} entries with disallowed scopes (${offenders.join(", ")}); resolved per invalidScopeAction.`
1647
+ );
1648
+ }
1649
+ const categories = groupByCategory(zodResult.data.entries, scopeResult.entries);
1650
+ return {
1651
+ valid: true,
1652
+ value: { enhancedEntries: scopeResult.entries, categories }
1653
+ };
1654
+ };
1100
1655
  }
1101
1656
  async function enhanceAndCategorize(provider, entries, context) {
1102
1657
  if (entries.length === 0) {
1103
1658
  return { enhancedEntries: [], categories: [] };
1104
1659
  }
1105
- const retryOpts = LLM_DEFAULTS.retry;
1660
+ const basePrompt = buildSystemPrompt3(context.categories, context.style);
1661
+ const examplesBlock = renderExamplesBlock(context.examples ?? []);
1662
+ const systemPrompt = resolveSystemPrompt(
1663
+ "enhanceAndCategorize",
1664
+ examplesBlock ? `${basePrompt}${examplesBlock}` : basePrompt,
1665
+ context.prompts
1666
+ );
1667
+ const initialMessages = [
1668
+ { role: "system", content: systemPrompt },
1669
+ { role: "user", content: buildUserPrompt3(entries) }
1670
+ ];
1671
+ const schema = buildEnhanceAndCategorizeSchema(context.categories ?? []);
1672
+ const validate = makeValidator2(entries, context);
1106
1673
  try {
1107
- return await withRetry(async () => {
1108
- const defaultPrompt = buildPrompt(entries, context.categories, context.style);
1109
- const prompt = resolvePrompt("enhanceAndCategorize", defaultPrompt, context.prompts);
1110
- const response = await provider.complete(prompt);
1111
- const parsed = JSON.parse(extractJsonFromResponse(response));
1112
- if (!Array.isArray(parsed.entries)) {
1113
- throw new Error('Response missing "entries" array');
1114
- }
1115
- const enhancedEntries = entries.map((original, i) => {
1116
- const result = parsed.entries[i];
1117
- if (!result) return original;
1118
- return {
1119
- ...original,
1120
- description: result.description || original.description,
1121
- scope: result.scope || original.scope
1122
- };
1123
- });
1124
- const validatedEntries = validateEntryScopes(enhancedEntries, context.scopes, context.categories);
1125
- const categoryMap = /* @__PURE__ */ new Map();
1126
- for (let i = 0; i < parsed.entries.length; i++) {
1127
- const result = parsed.entries[i];
1128
- const category = result?.category || "General";
1129
- const entry = validatedEntries[i];
1130
- if (!entry) continue;
1131
- if (!categoryMap.has(category)) {
1132
- categoryMap.set(category, []);
1133
- }
1134
- categoryMap.get(category)?.push(entry);
1135
- }
1136
- const categories = [];
1137
- for (const [category, catEntries] of categoryMap) {
1138
- categories.push({ category, entries: catEntries });
1139
- }
1140
- return { enhancedEntries: validatedEntries, categories };
1141
- }, retryOpts);
1142
- } catch (error2) {
1143
- warn(
1144
- `Combined enhance+categorize failed after ${retryOpts.maxAttempts} attempts: ${error2 instanceof Error ? error2.message : String(error2)}`
1674
+ return await withCorrectiveRetry(
1675
+ (messages, isFirstAttempt) => provider.complete(
1676
+ messages,
1677
+ isFirstAttempt && provider.capabilities.structuredOutputs ? { schema, toolName: "emit_release_notes" } : void 0
1678
+ ),
1679
+ validate,
1680
+ buildCorrectionMessages2,
1681
+ initialMessages
1145
1682
  );
1146
- return {
1147
- enhancedEntries: entries,
1148
- categories: [{ category: "General", entries }]
1149
- };
1683
+ } catch (error2) {
1684
+ if (error2 instanceof LLMError) {
1685
+ warn(`enhanceAndCategorize failed after all attempts: ${error2.message}. Returning entries ungrouped.`);
1686
+ const stripped = entries.map((e) => ({ ...e, scope: void 0, leadIn: void 0 }));
1687
+ return { enhancedEntries: stripped, categories: [{ category: "General", entries: stripped }] };
1688
+ }
1689
+ throw error2;
1150
1690
  }
1151
1691
  }
1152
1692
 
1153
1693
  // src/llm/tasks/release-notes.ts
1154
- var DEFAULT_RELEASE_NOTES_PROMPT = `You are writing release notes for a software project.
1155
-
1156
- Create engaging, user-friendly release notes for the following changes.
1694
+ var DEFAULT_SYSTEM_PROMPT = `You are writing release notes for a software project.
1157
1695
 
1158
1696
  Rules:
1159
1697
  - Start with a brief introduction (1-2 sentences)
@@ -1163,54 +1701,68 @@ Rules:
1163
1701
  - End with a brief conclusion or call to action
1164
1702
  - Use markdown formatting
1165
1703
 
1166
- Version: {{version}}
1167
- {{#if previousVersion}}Previous version: {{previousVersion}}{{/if}}
1168
- Date: {{date}}
1704
+ Output only the markdown content.`;
1705
+ function buildUserPrompt4(entries, context) {
1706
+ const version = context.version ?? "v1.0.0";
1707
+ const date = context.date ?? (/* @__PURE__ */ new Date()).toISOString().split("T")[0] ?? "";
1708
+ const prevLine = context.previousVersion ? `Previous version: ${context.previousVersion}
1709
+ ` : "";
1710
+ const entriesText = entries.map((e) => {
1711
+ let line = `- [${e.type}]`;
1712
+ if (e.scope) line += ` (${e.scope})`;
1713
+ line += `: ${e.description}`;
1714
+ if (e.breaking) line += " **BREAKING**";
1715
+ const prBlocks = renderPRBlocks(e);
1716
+ if (prBlocks) line += `
1717
+ ${prBlocks}`;
1718
+ return line;
1719
+ }).join("\n");
1720
+ return `Version: ${version}
1721
+ ${prevLine}Date: ${date}
1169
1722
 
1170
1723
  Changes:
1171
- {{entries}}
1172
-
1173
- Release notes (output only the markdown content):`;
1724
+ ${entriesText}`;
1725
+ }
1174
1726
  async function generateReleaseNotes(provider, entries, context) {
1175
1727
  if (entries.length === 0) {
1176
1728
  return `## Release ${context.version ?? "v1.0.0"}
1177
1729
 
1178
1730
  No notable changes in this release.`;
1179
1731
  }
1180
- const entriesText = entries.map((e) => {
1181
- let line = `- [${e.type}]`;
1182
- if (e.scope) line += ` (${e.scope})`;
1183
- line += `: ${e.description}`;
1184
- if (e.breaking) line += " **BREAKING**";
1185
- return line;
1186
- }).join("\n");
1187
- const defaultPrompt = DEFAULT_RELEASE_NOTES_PROMPT.replace("{{version}}", context.version ?? "v1.0.0").replace(
1188
- "{{#if previousVersion}}Previous version: {{previousVersion}}{{/if}}",
1189
- context.previousVersion ? `Previous version: ${context.previousVersion}` : ""
1190
- ).replace("{{date}}", context.date ?? (/* @__PURE__ */ new Date()).toISOString().split("T")[0] ?? "").replace("{{entries}}", entriesText);
1191
- const prompt = resolvePrompt("releaseNotes", defaultPrompt, context.prompts);
1192
- const response = await provider.complete(prompt);
1193
- return response.trim();
1732
+ const examplesBlock = renderExamplesBlock(context.examples ?? []);
1733
+ const systemPrompt = resolveSystemPrompt(
1734
+ "releaseNotes",
1735
+ examplesBlock ? `${DEFAULT_SYSTEM_PROMPT}${examplesBlock}` : DEFAULT_SYSTEM_PROMPT,
1736
+ context.prompts
1737
+ );
1738
+ const messages = [
1739
+ { role: "system", content: systemPrompt },
1740
+ { role: "user", content: buildUserPrompt4(entries, context) }
1741
+ ];
1742
+ const result = await provider.complete(messages);
1743
+ return result.content.trim();
1194
1744
  }
1195
1745
 
1196
1746
  // src/llm/tasks/summarize.ts
1197
- var DEFAULT_SUMMARIZE_PROMPT = `You are creating a summary of changes for a software release.
1198
-
1199
- Given the following changelog entries, create a brief summary (2-3 sentences) that captures the main themes of this release.
1200
-
1201
- Entries:
1202
- {{entries}}
1203
-
1204
- Summary (only output the summary, nothing else):`;
1747
+ var DEFAULT_SYSTEM_PROMPT2 = `You are creating a summary of changes for a software release.
1748
+ Create a brief summary (2-3 sentences) that captures the main themes of this release.
1749
+ Output only the summary text, nothing else.`;
1750
+ function buildUserPrompt5(entries) {
1751
+ const text = entries.map((e) => `- [${e.type}]${e.scope ? ` (${e.scope})` : ""}: ${e.description}`).join("\n");
1752
+ return `Entries:
1753
+ ${text}`;
1754
+ }
1205
1755
  async function summarizeEntries(provider, entries, context) {
1206
1756
  if (entries.length === 0) {
1207
1757
  return "";
1208
1758
  }
1209
- const entriesText = entries.map((e) => `- [${e.type}]${e.scope ? ` (${e.scope})` : ""}: ${e.description}`).join("\n");
1210
- const defaultPrompt = DEFAULT_SUMMARIZE_PROMPT.replace("{{entries}}", entriesText);
1211
- const prompt = resolvePrompt("summarize", defaultPrompt, context.prompts);
1212
- const response = await provider.complete(prompt);
1213
- return response.trim();
1759
+ const systemPrompt = resolveSystemPrompt("summarize", DEFAULT_SYSTEM_PROMPT2, context.prompts);
1760
+ const messages = [
1761
+ { role: "system", content: systemPrompt },
1762
+ { role: "user", content: buildUserPrompt5(entries) }
1763
+ ];
1764
+ const result = await provider.complete(messages);
1765
+ return result.content.trim();
1214
1766
  }
1215
1767
 
1216
1768
  // src/llm/index.ts
@@ -1251,7 +1803,7 @@ function createProvider(config) {
1251
1803
  }
1252
1804
 
1253
1805
  // src/templates/ejs.ts
1254
- import * as fs5 from "fs";
1806
+ import * as fs6 from "fs";
1255
1807
  import ejs from "ejs";
1256
1808
  function renderEjs(template, context) {
1257
1809
  try {
@@ -1261,16 +1813,16 @@ function renderEjs(template, context) {
1261
1813
  }
1262
1814
  }
1263
1815
  function renderEjsFile(filePath, context) {
1264
- if (!fs5.existsSync(filePath)) {
1816
+ if (!fs6.existsSync(filePath)) {
1265
1817
  throw new TemplateError(`Template file not found: ${filePath}`);
1266
1818
  }
1267
- const template = fs5.readFileSync(filePath, "utf-8");
1819
+ const template = fs6.readFileSync(filePath, "utf-8");
1268
1820
  return renderEjs(template, context);
1269
1821
  }
1270
1822
 
1271
1823
  // src/templates/handlebars.ts
1272
- import * as fs6 from "fs";
1273
- import * as path5 from "path";
1824
+ import * as fs7 from "fs";
1825
+ import * as path6 from "path";
1274
1826
  import Handlebars from "handlebars";
1275
1827
  function registerHandlebarsHelpers() {
1276
1828
  Handlebars.registerHelper("capitalize", (str) => {
@@ -1296,28 +1848,28 @@ function renderHandlebars(template, context) {
1296
1848
  }
1297
1849
  }
1298
1850
  function renderHandlebarsFile(filePath, context) {
1299
- if (!fs6.existsSync(filePath)) {
1851
+ if (!fs7.existsSync(filePath)) {
1300
1852
  throw new TemplateError(`Template file not found: ${filePath}`);
1301
1853
  }
1302
- const template = fs6.readFileSync(filePath, "utf-8");
1854
+ const template = fs7.readFileSync(filePath, "utf-8");
1303
1855
  return renderHandlebars(template, context);
1304
1856
  }
1305
1857
  function renderHandlebarsComposable(templateDir, context) {
1306
1858
  registerHandlebarsHelpers();
1307
- const versionPath = path5.join(templateDir, "version.hbs");
1308
- const entryPath = path5.join(templateDir, "entry.hbs");
1309
- const documentPath = path5.join(templateDir, "document.hbs");
1310
- if (!fs6.existsSync(documentPath)) {
1859
+ const versionPath = path6.join(templateDir, "version.hbs");
1860
+ const entryPath = path6.join(templateDir, "entry.hbs");
1861
+ const documentPath = path6.join(templateDir, "document.hbs");
1862
+ if (!fs7.existsSync(documentPath)) {
1311
1863
  throw new TemplateError(`Document template not found: ${documentPath}`);
1312
1864
  }
1313
- if (fs6.existsSync(versionPath)) {
1314
- Handlebars.registerPartial("version", fs6.readFileSync(versionPath, "utf-8"));
1865
+ if (fs7.existsSync(versionPath)) {
1866
+ Handlebars.registerPartial("version", fs7.readFileSync(versionPath, "utf-8"));
1315
1867
  }
1316
- if (fs6.existsSync(entryPath)) {
1317
- Handlebars.registerPartial("entry", fs6.readFileSync(entryPath, "utf-8"));
1868
+ if (fs7.existsSync(entryPath)) {
1869
+ Handlebars.registerPartial("entry", fs7.readFileSync(entryPath, "utf-8"));
1318
1870
  }
1319
1871
  try {
1320
- const compiled = Handlebars.compile(fs6.readFileSync(documentPath, "utf-8"));
1872
+ const compiled = Handlebars.compile(fs7.readFileSync(documentPath, "utf-8"));
1321
1873
  return compiled(context);
1322
1874
  } catch (error2) {
1323
1875
  throw new TemplateError(`Handlebars render error: ${error2 instanceof Error ? error2.message : String(error2)}`);
@@ -1325,8 +1877,8 @@ function renderHandlebarsComposable(templateDir, context) {
1325
1877
  }
1326
1878
 
1327
1879
  // src/templates/liquid.ts
1328
- import * as fs7 from "fs";
1329
- import * as path6 from "path";
1880
+ import * as fs8 from "fs";
1881
+ import * as path7 from "path";
1330
1882
  import { Liquid } from "liquidjs";
1331
1883
  function createLiquidEngine(root) {
1332
1884
  return new Liquid({
@@ -1344,15 +1896,15 @@ function renderLiquid(template, context) {
1344
1896
  }
1345
1897
  }
1346
1898
  function renderLiquidFile(filePath, context) {
1347
- if (!fs7.existsSync(filePath)) {
1899
+ if (!fs8.existsSync(filePath)) {
1348
1900
  throw new TemplateError(`Template file not found: ${filePath}`);
1349
1901
  }
1350
- const template = fs7.readFileSync(filePath, "utf-8");
1902
+ const template = fs8.readFileSync(filePath, "utf-8");
1351
1903
  return renderLiquid(template, context);
1352
1904
  }
1353
1905
  function renderLiquidComposable(templateDir, context) {
1354
- const documentPath = path6.join(templateDir, "document.liquid");
1355
- if (!fs7.existsSync(documentPath)) {
1906
+ const documentPath = path7.join(templateDir, "document.liquid");
1907
+ if (!fs8.existsSync(documentPath)) {
1356
1908
  throw new TemplateError(`Document template not found: ${documentPath}`);
1357
1909
  }
1358
1910
  const engine = createLiquidEngine(templateDir);
@@ -1364,10 +1916,10 @@ function renderLiquidComposable(templateDir, context) {
1364
1916
  }
1365
1917
 
1366
1918
  // src/templates/loader.ts
1367
- import * as fs8 from "fs";
1368
- import * as path7 from "path";
1919
+ import * as fs9 from "fs";
1920
+ import * as path8 from "path";
1369
1921
  function getEngineFromFile(filePath) {
1370
- const ext = path7.extname(filePath).toLowerCase();
1922
+ const ext = path8.extname(filePath).toLowerCase();
1371
1923
  switch (ext) {
1372
1924
  case ".liquid":
1373
1925
  return "liquid";
@@ -1401,10 +1953,10 @@ function getRenderFileFn(engine) {
1401
1953
  }
1402
1954
  }
1403
1955
  function detectTemplateMode(templatePath) {
1404
- if (!fs8.existsSync(templatePath)) {
1956
+ if (!fs9.existsSync(templatePath)) {
1405
1957
  throw new TemplateError(`Template path not found: ${templatePath}`);
1406
1958
  }
1407
- const stat = fs8.statSync(templatePath);
1959
+ const stat = fs9.statSync(templatePath);
1408
1960
  if (stat.isFile()) {
1409
1961
  return "single";
1410
1962
  }
@@ -1422,7 +1974,7 @@ function renderSingleFile(templatePath, context, engine) {
1422
1974
  };
1423
1975
  }
1424
1976
  function renderComposable(templateDir, context, engine) {
1425
- const files = fs8.readdirSync(templateDir);
1977
+ const files = fs9.readdirSync(templateDir);
1426
1978
  const engineMap = {
1427
1979
  liquid: { document: "document.liquid", version: "version.liquid", entry: "entry.liquid" },
1428
1980
  handlebars: { document: "document.hbs", version: "version.hbs", entry: "entry.hbs" },
@@ -1445,15 +1997,15 @@ function renderComposable(templateDir, context, engine) {
1445
1997
  return { content: renderHandlebarsComposable(templateDir, context), engine: resolvedEngine };
1446
1998
  }
1447
1999
  const expectedFiles = engineMap[resolvedEngine];
1448
- const documentPath = path7.join(templateDir, expectedFiles.document);
1449
- if (!fs8.existsSync(documentPath)) {
2000
+ const documentPath = path8.join(templateDir, expectedFiles.document);
2001
+ if (!fs9.existsSync(documentPath)) {
1450
2002
  throw new TemplateError(`Document template not found: ${expectedFiles.document}`);
1451
2003
  }
1452
- const versionPath = path7.join(templateDir, expectedFiles.version);
1453
- const entryPath = path7.join(templateDir, expectedFiles.entry);
2004
+ const versionPath = path8.join(templateDir, expectedFiles.version);
2005
+ const entryPath = path8.join(templateDir, expectedFiles.entry);
1454
2006
  const render = getRenderFn(resolvedEngine);
1455
- const entryTemplate = fs8.existsSync(entryPath) ? fs8.readFileSync(entryPath, "utf-8") : null;
1456
- const versionTemplate = fs8.existsSync(versionPath) ? fs8.readFileSync(versionPath, "utf-8") : null;
2007
+ const entryTemplate = fs9.existsSync(entryPath) ? fs9.readFileSync(entryPath, "utf-8") : null;
2008
+ const versionTemplate = fs9.existsSync(versionPath) ? fs9.readFileSync(versionPath, "utf-8") : null;
1457
2009
  if (entryTemplate && versionTemplate) {
1458
2010
  const versionsWithEntries = context.versions.map((versionCtx) => {
1459
2011
  const entries = versionCtx.entries.map((entry) => {
@@ -1464,7 +2016,7 @@ function renderComposable(templateDir, context, engine) {
1464
2016
  });
1465
2017
  const docContext = { ...context, renderedVersions: versionsWithEntries };
1466
2018
  return {
1467
- content: render(fs8.readFileSync(documentPath, "utf-8"), docContext),
2019
+ content: render(fs9.readFileSync(documentPath, "utf-8"), docContext),
1468
2020
  engine: resolvedEngine
1469
2021
  };
1470
2022
  }
@@ -1504,7 +2056,44 @@ function renderTemplate(templatePath, context, engine) {
1504
2056
  return renderComposable(templatePath, context, engine);
1505
2057
  }
1506
2058
 
2059
+ // src/utils/retry.ts
2060
+ function sleep(ms) {
2061
+ return new Promise((resolve2) => setTimeout(resolve2, ms));
2062
+ }
2063
+ async function withRetry(fn, options = {}) {
2064
+ const maxAttempts = options.maxAttempts ?? 3;
2065
+ const initialDelay = options.initialDelay ?? 1e3;
2066
+ const maxDelay = options.maxDelay ?? 3e4;
2067
+ const backoffFactor = options.backoffFactor ?? 2;
2068
+ let lastError;
2069
+ for (let attempt = 0; attempt < maxAttempts; attempt++) {
2070
+ try {
2071
+ return await fn();
2072
+ } catch (error2) {
2073
+ lastError = error2;
2074
+ if (attempt < maxAttempts - 1) {
2075
+ const base = Math.min(initialDelay * backoffFactor ** attempt, maxDelay);
2076
+ const jitter = base * 0.2 * (Math.random() * 2 - 1);
2077
+ await sleep(Math.max(0, base + jitter));
2078
+ }
2079
+ }
2080
+ }
2081
+ throw lastError;
2082
+ }
2083
+
1507
2084
  // src/core/pipeline.ts
2085
+ function parseOwnerRepo(repoUrl) {
2086
+ const scpMatch = repoUrl.match(/^git@github\.com:([^/]+)\/(.+?)(?:\.git)?$/);
2087
+ if (scpMatch) return { owner: scpMatch[1], repo: scpMatch[2] };
2088
+ try {
2089
+ const url = new URL(repoUrl);
2090
+ if (url.hostname !== "github.com") return null;
2091
+ const parts = url.pathname.replace(/^\//, "").replace(/\.git$/, "").split("/");
2092
+ if (parts.length >= 2) return { owner: parts[0], repo: parts[1] };
2093
+ } catch {
2094
+ }
2095
+ return null;
2096
+ }
1508
2097
  function findCompoundTagSepPos(tag) {
1509
2098
  let pos = tag.lastIndexOf("-");
1510
2099
  while (pos > 0) {
@@ -1590,7 +2179,7 @@ function createDocumentContext(contexts, repoUrl) {
1590
2179
  compareUrls: Object.keys(compareUrls).length > 0 ? compareUrls : void 0
1591
2180
  };
1592
2181
  }
1593
- async function processWithLLM(context, llmConfig) {
2182
+ async function processWithLLM(context, llmConfig, examples) {
1594
2183
  const tasks = llmConfig.tasks ?? {};
1595
2184
  const llmContext = {
1596
2185
  packageName: context.packageName,
@@ -1600,7 +2189,8 @@ async function processWithLLM(context, llmConfig) {
1600
2189
  categories: llmConfig.categories,
1601
2190
  style: llmConfig.style,
1602
2191
  scopes: llmConfig.scopes,
1603
- prompts: llmConfig.prompts
2192
+ prompts: llmConfig.prompts,
2193
+ examples
1604
2194
  };
1605
2195
  const enhanced = {
1606
2196
  entries: context.entries
@@ -1615,7 +2205,8 @@ async function processWithLLM(context, llmConfig) {
1615
2205
  const configOptions = llmConfig.options;
1616
2206
  const provider = {
1617
2207
  name: rawProvider.name,
1618
- complete: (prompt, opts) => withRetry(() => rawProvider.complete(prompt, { ...configOptions, ...opts }), retryOpts)
2208
+ capabilities: rawProvider.capabilities,
2209
+ complete: (messages, opts) => withRetry(() => rawProvider.complete(messages, { ...configOptions, ...opts }), retryOpts)
1619
2210
  };
1620
2211
  const activeTasks = Object.entries(tasks).filter(([, enabled]) => enabled).map(([name]) => name);
1621
2212
  info(`Running LLM tasks: ${activeTasks.join(", ")}`);
@@ -1663,7 +2254,7 @@ async function processWithLLM(context, llmConfig) {
1663
2254
  };
1664
2255
  } catch (error2) {
1665
2256
  warn(`LLM processing failed: ${error2 instanceof Error ? error2.message : String(error2)}`);
1666
- warn("Falling back to raw entries");
2257
+ warn("Falling back to non-LLM changelog rendering. Check your LLM config or set RELEASEKIT_DEBUG=1 for details.");
1667
2258
  return context;
1668
2259
  }
1669
2260
  }
@@ -1671,17 +2262,17 @@ function getBuiltinTemplatePath(style) {
1671
2262
  let packageRoot;
1672
2263
  try {
1673
2264
  const currentUrl = import.meta.url;
1674
- packageRoot = path8.dirname(new URL(currentUrl).pathname);
1675
- packageRoot = path8.join(packageRoot, "..", "..");
2265
+ packageRoot = path9.dirname(new URL(currentUrl).pathname);
2266
+ packageRoot = path9.join(packageRoot, "..", "..");
1676
2267
  } catch {
1677
2268
  packageRoot = __dirname;
1678
2269
  }
1679
- return path8.join(packageRoot, "templates", style);
2270
+ return path9.join(packageRoot, "templates", style);
1680
2271
  }
1681
2272
  async function generateWithTemplate(contexts, templatesConfig, outputPath, repoUrl, dryRun) {
1682
2273
  let templatePath;
1683
2274
  if (templatesConfig?.path) {
1684
- templatePath = path8.resolve(templatesConfig.path);
2275
+ templatePath = path9.resolve(templatesConfig.path);
1685
2276
  } else {
1686
2277
  templatePath = getBuiltinTemplatePath("keep-a-changelog");
1687
2278
  }
@@ -1696,29 +2287,80 @@ async function generateWithTemplate(contexts, templatesConfig, outputPath, repoU
1696
2287
  process.stdout.write(result.content);
1697
2288
  return;
1698
2289
  }
1699
- const dir = path8.dirname(outputPath);
1700
- if (!fs9.existsSync(dir)) {
1701
- fs9.mkdirSync(dir, { recursive: true });
2290
+ const dir = path9.dirname(outputPath);
2291
+ if (!fs10.existsSync(dir)) {
2292
+ fs10.mkdirSync(dir, { recursive: true });
1702
2293
  }
1703
- fs9.writeFileSync(outputPath, result.content, "utf-8");
2294
+ fs10.writeFileSync(outputPath, result.content, "utf-8");
1704
2295
  const label = /changelog/i.test(outputPath) ? "Changelog" : "Release notes";
1705
2296
  success(`${label} written to ${outputPath} (using ${result.engine} template)`);
1706
2297
  }
1707
- async function runPipeline(input, config, dryRun) {
2298
+ async function runPipeline(input, config, dryRun, pipelineOptions) {
1708
2299
  debug(`Processing ${input.packages.length} package(s)`);
1709
2300
  let contexts = input.packages.map(createTemplateContext);
1710
2301
  const changelogConfig = config.changelog === false ? false : { mode: "root", ...config.changelog ?? {} };
1711
2302
  const releaseNotesConfig = config.releaseNotes === false || config.releaseNotes === void 0 ? void 0 : config.releaseNotes.mode !== void 0 || config.releaseNotes.file !== void 0 ? { mode: "root", ...config.releaseNotes } : config.releaseNotes;
1712
2303
  const llmConfig = releaseNotesConfig?.llm;
1713
- if (llmConfig && !process.env.CHANGELOG_NO_LLM) {
2304
+ if (llmConfig && !process.env.CHANGELOG_NO_LLM && !pipelineOptions?.skipReleaseNotes) {
1714
2305
  info("Processing with LLM enhancement");
1715
- contexts = await Promise.all(contexts.map((ctx) => processWithLLM(ctx, llmConfig)));
2306
+ const examplesCount = llmConfig.examples ?? 3;
2307
+ const repoUrl = contexts[0]?.repoUrl ?? input.metadata?.repoUrl;
2308
+ const ownerRepo = repoUrl ? parseOwnerRepo(repoUrl) : null;
2309
+ const examplesByPackage = /* @__PURE__ */ new Map();
2310
+ if (examplesCount > 0 && ownerRepo) {
2311
+ await Promise.all(
2312
+ contexts.map(async (ctx) => {
2313
+ const examples = await fetchExamples({
2314
+ owner: ownerRepo.owner,
2315
+ repo: ownerRepo.repo,
2316
+ packageName: ctx.packageName,
2317
+ count: examplesCount,
2318
+ isMonorepo: contexts.length > 1
2319
+ });
2320
+ examplesByPackage.set(ctx.packageName, examples);
2321
+ if (examples.length > 0) {
2322
+ debug(`Loaded ${examples.length} example(s) for ${ctx.packageName}`);
2323
+ }
2324
+ })
2325
+ );
2326
+ }
2327
+ const prCache = /* @__PURE__ */ new Map();
2328
+ const pullRequestsEnabled = llmConfig.context?.pullRequests !== false;
2329
+ if (pullRequestsEnabled && ownerRepo) {
2330
+ const allIssueNumbers = [
2331
+ ...new Set(contexts.flatMap((ctx) => ctx.entries.flatMap((e) => parseIssueNumbers(e.issueIds ?? []))))
2332
+ ];
2333
+ if (allIssueNumbers.length > 0) {
2334
+ const token = resolveGitHubToken();
2335
+ if (!token) {
2336
+ warn("No GitHub token available \u2014 skipping PR context fetch (set GITHUB_TOKEN to enable)");
2337
+ } else {
2338
+ debug(`Fetching PR context for ${allIssueNumbers.length} issue(s)`);
2339
+ await fetchPullRequestContext(ownerRepo.owner, ownerRepo.repo, allIssueNumbers, token, prCache);
2340
+ debug(`Loaded PR context for ${prCache.size} issue(s)`);
2341
+ }
2342
+ }
2343
+ }
2344
+ if (prCache.size > 0) {
2345
+ contexts = contexts.map((ctx) => ({
2346
+ ...ctx,
2347
+ entries: ctx.entries.map((entry) => {
2348
+ const prs = parseIssueNumbers(entry.issueIds ?? []).map((n) => prCache.get(n)).filter((pr) => pr != null);
2349
+ return prs.length > 0 ? { ...entry, context: { prs } } : entry;
2350
+ })
2351
+ }));
2352
+ }
2353
+ contexts = await Promise.all(
2354
+ contexts.map((ctx) => processWithLLM(ctx, llmConfig, examplesByPackage.get(ctx.packageName) ?? []))
2355
+ );
1716
2356
  }
1717
2357
  const files = [];
1718
2358
  const fmtOpts = {
1719
- includePackageName: contexts.length > 1 || contexts.some((c) => c.packageName.includes("/"))
2359
+ includePackageName: contexts.length > 1 || contexts.some((c) => c.packageName.includes("/")),
2360
+ categoryOrder: llmConfig?.categoryOrder,
2361
+ links: releaseNotesConfig?.links
1720
2362
  };
1721
- if (changelogConfig !== false && changelogConfig.mode) {
2363
+ if (!pipelineOptions?.skipChangelogs && changelogConfig !== false && changelogConfig.mode) {
1722
2364
  const fileName = changelogConfig.file ?? "CHANGELOG.md";
1723
2365
  const mode = changelogConfig.mode;
1724
2366
  info(`Generating changelog \u2192 ${fileName}`);
@@ -1745,7 +2387,7 @@ async function runPipeline(input, config, dryRun) {
1745
2387
  warn(`Failed to write changelog: ${error2 instanceof Error ? error2.message : String(error2)}`);
1746
2388
  }
1747
2389
  }
1748
- if (releaseNotesConfig?.mode) {
2390
+ if (!pipelineOptions?.skipReleaseNotes && releaseNotesConfig?.mode) {
1749
2391
  const fileName = releaseNotesConfig.file ?? "RELEASE_NOTES.md";
1750
2392
  const mode = releaseNotesConfig.mode;
1751
2393
  info(`Generating release notes \u2192 ${fileName}`);
@@ -1781,12 +2423,15 @@ async function runPipeline(input, config, dryRun) {
1781
2423
  const releaseNotesResult = {};
1782
2424
  for (const ctx of contexts) {
1783
2425
  packageNotes[ctx.packageName] = formatVersion(ctx);
2426
+ if (pipelineOptions?.skipReleaseNotes) {
2427
+ continue;
2428
+ }
1784
2429
  if (ctx.enhanced?.releaseNotes) {
1785
2430
  releaseNotesResult[ctx.packageName] = ctx.enhanced.releaseNotes;
1786
2431
  } else if (releaseNotesConfig) {
1787
2432
  if (releaseNotesConfig.templates?.path) {
1788
2433
  try {
1789
- const templatePath = path8.resolve(releaseNotesConfig.templates.path);
2434
+ const templatePath = path9.resolve(releaseNotesConfig.templates.path);
1790
2435
  const docCtx = { ...createDocumentContext([ctx], void 0), perPackage: true };
1791
2436
  const rendered = renderTemplate(
1792
2437
  templatePath,
@@ -1814,12 +2459,12 @@ async function runPipeline(input, config, dryRun) {
1814
2459
  releaseNotes: Object.keys(releaseNotesResult).length > 0 ? releaseNotesResult : void 0
1815
2460
  };
1816
2461
  }
1817
- async function processInput(inputJson, config, dryRun) {
2462
+ async function processInput(inputJson, config, dryRun, pipelineOptions) {
1818
2463
  const input = parseVersionOutput(inputJson);
1819
- return runPipeline(input, config, dryRun);
2464
+ return runPipeline(input, config, dryRun, pipelineOptions);
1820
2465
  }
1821
2466
  async function writeMonorepoFiles(contexts, config, dryRun, fileName) {
1822
- const { detectMonorepo, writeMonorepoChangelogs } = await import("./aggregator-CGD3KEVU.js");
2467
+ const { detectMonorepo, writeMonorepoChangelogs } = await import("./aggregator-GXJXPM7O.js");
1823
2468
  const cwd = process.cwd();
1824
2469
  const detected = detectMonorepo(cwd);
1825
2470
  if (!detected.isMonorepo) return [];
@@ -1838,7 +2483,7 @@ async function writeMonorepoFiles(contexts, config, dryRun, fileName) {
1838
2483
  }
1839
2484
 
1840
2485
  // src/command.ts
1841
- import * as fs10 from "fs";
2486
+ import * as fs11 from "fs";
1842
2487
  import * as readline from "readline";
1843
2488
  import { Command } from "commander";
1844
2489
  function createNotesCommand() {
@@ -1941,7 +2586,7 @@ function createNotesCommand() {
1941
2586
  }
1942
2587
  let inputJson;
1943
2588
  if (options.input) {
1944
- inputJson = fs10.readFileSync(options.input, "utf-8");
2589
+ inputJson = fs11.readFileSync(options.input, "utf-8");
1945
2590
  } else {
1946
2591
  inputJson = await readStdin();
1947
2592
  }