@releasekit/notes 0.2.0-next.9 → 0.2.0

package/dist/cli.cjs

@@ -354,6 +354,83 @@ var OpenAICompatibleProvider = class extends BaseLLMProvider {
 
 // src/llm/tasks/categorize.ts
 var import_core3 = require("@releasekit/core");
+
+// src/llm/prompts.ts
+function resolvePrompt(taskName, defaultPrompt, promptsConfig) {
+  if (!promptsConfig) return defaultPrompt;
+  const fullTemplate = promptsConfig.templates?.[taskName];
+  if (fullTemplate) return fullTemplate;
+  const additionalInstructions = promptsConfig.instructions?.[taskName];
+  if (additionalInstructions) {
+    const insertionPoint = defaultPrompt.lastIndexOf("Output only valid JSON");
+    if (insertionPoint !== -1) {
+      return `${defaultPrompt.slice(0, insertionPoint)}Additional instructions:
+${additionalInstructions}
+
+${defaultPrompt.slice(insertionPoint)}`;
+    }
+    return `${defaultPrompt}
+
+Additional instructions:
+${additionalInstructions}`;
+  }
+  return defaultPrompt;
+}
+
+// src/llm/scopes.ts
+function getAllowedScopesFromCategories(categories) {
+  const scopeMap = /* @__PURE__ */ new Map();
+  for (const cat of categories) {
+    if (cat.scopes && cat.scopes.length > 0) {
+      scopeMap.set(cat.name, cat.scopes);
+    }
+  }
+  return scopeMap;
+}
+function resolveAllowedScopes(scopeConfig, categories, packageNames) {
+  if (!scopeConfig || scopeConfig.mode === "unrestricted") return null;
+  if (scopeConfig.mode === "none") return [];
+  if (scopeConfig.mode === "packages") return packageNames ?? [];
+  if (scopeConfig.mode === "restricted") {
+    const explicit = scopeConfig.rules?.allowed ?? [];
+    const all = new Set(explicit);
+    if (categories) {
+      const fromCategories = getAllowedScopesFromCategories(categories);
+      for (const scopes of fromCategories.values()) {
+        for (const s of scopes) all.add(s);
+      }
+    }
+    return [...all];
+  }
+  return null;
+}
+function validateScope(scope, allowedScopes, rules) {
+  if (!scope || allowedScopes === null) return scope;
+  if (allowedScopes.length === 0) return void 0;
+  const caseSensitive = rules?.caseSensitive ?? false;
+  const normalise = (s) => caseSensitive ? s : s.toLowerCase();
+  const isAllowed = allowedScopes.some((a) => normalise(a) === normalise(scope));
+  if (isAllowed) return scope;
+  switch (rules?.invalidScopeAction ?? "remove") {
+    case "keep":
+      return scope;
+    case "fallback":
+      return rules?.fallbackScope;
+    case "remove":
+    default:
+      return void 0;
+  }
+}
+function validateEntryScopes(entries, scopeConfig, categories) {
+  const allowedScopes = resolveAllowedScopes(scopeConfig, categories);
+  if (allowedScopes === null) return entries;
+  return entries.map((entry) => ({
+    ...entry,
+    scope: validateScope(entry.scope, allowedScopes, scopeConfig?.rules)
+  }));
+}
+
+// src/llm/tasks/categorize.ts
 var DEFAULT_CATEGORIZE_PROMPT = `You are categorizing changelog entries for a software release.
 
 Given the following entries, group them into meaningful categories (e.g., "Core", "UI", "API", "Performance", "Bug Fixes", "Documentation").
@@ -365,20 +442,21 @@ Entries:
 
 Output only valid JSON, nothing else:`;
 function buildCustomCategorizePrompt(categories) {
-  const categoryList = categories.map((c) => `- "${c.name}": ${c.description}`).join("\n");
-  const developerCategory = categories.find((c) => c.name === "Developer");
+  const categoryList = categories.map((c) => {
+    const scopeInfo = c.scopes?.length ? ` Allowed scopes: ${c.scopes.join(", ")}.` : "";
+    return `- "${c.name}": ${c.description}${scopeInfo}`;
+  }).join("\n");
+  const scopeMap = getAllowedScopesFromCategories(categories);
   let scopeInstructions = "";
-  if (developerCategory) {
-    const scopeMatch = developerCategory.description.match(/from:\s*([^.]+)/);
-    if (scopeMatch?.[1]) {
-      const scopes = scopeMatch[1].split(",").map((s) => s.trim()).filter(Boolean);
-      if (scopes.length > 0) {
-        scopeInstructions = `
-
-For the "Developer" category, you MUST assign a scope from this exact list: ${scopes.join(", ")}.
-`;
-      }
+  if (scopeMap.size > 0) {
+    const entries = [];
+    for (const [catName, scopes] of scopeMap) {
+      entries.push(`For "${catName}", assign a scope from: ${scopes.join(", ")}.`);
     }
+    scopeInstructions = `
+
+${entries.join("\n")}
+Only use scopes from these predefined lists. If an entry does not fit any scope, set scope to null.`;
   }
   return `You are categorizing changelog entries for a software release.
 
@@ -386,9 +464,10 @@ Given the following entries, group them into the specified categories. Only use
 
 Categories:
 ${categoryList}${scopeInstructions}
+
 Output a JSON object with two fields:
 - "categories": an object where keys are category names and values are arrays of entry indices (0-based)
-- "scopes": an object where keys are entry indices (as strings) and values are scope labels
+- "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.
 
 Entries:
 {{entries}}
@@ -399,9 +478,11 @@ async function categorizeEntries(provider, entries, context) {
   if (entries.length === 0) {
     return [];
   }
-  const entriesText = entries.map((e, i) => `${i}. [${e.type}]${e.scope ? ` (${e.scope})` : ""}: ${e.description}`).join("\n");
+  const entriesCopy = entries.map((e) => ({ ...e, scope: void 0 }));
+  const entriesText = entriesCopy.map((e, i) => `${i}. [${e.type}]: ${e.description}`).join("\n");
   const hasCustomCategories = context.categories && context.categories.length > 0;
-  const promptTemplate = hasCustomCategories ? buildCustomCategorizePrompt(context.categories) : DEFAULT_CATEGORIZE_PROMPT;
+  const defaultPrompt = hasCustomCategories ? buildCustomCategorizePrompt(context.categories) : DEFAULT_CATEGORIZE_PROMPT;
+  const promptTemplate = resolvePrompt("categorize", defaultPrompt, context.prompts);
   const prompt = promptTemplate.replace("{{entries}}", entriesText);
   try {
     const response = await provider.complete(prompt);
@@ -413,13 +494,14 @@ async function categorizeEntries(provider, entries, context) {
       const scopeMap = parsed.scopes || {};
       for (const [indexStr, scope] of Object.entries(scopeMap)) {
         const idx = Number.parseInt(indexStr, 10);
-        if (entries[idx] && scope) {
-          entries[idx] = { ...entries[idx], scope };
+        if (entriesCopy[idx] && scope && scope.trim()) {
+          entriesCopy[idx] = { ...entriesCopy[idx], scope: scope.trim() };
         }
       }
+      const validatedEntries = validateEntryScopes(entriesCopy, context.scopes, context.categories);
       for (const [category, rawIndices] of Object.entries(categoryMap)) {
         const indices = Array.isArray(rawIndices) ? rawIndices : [];
-        const categoryEntries = indices.map((i) => entries[i]).filter((e) => e !== void 0);
+        const categoryEntries = indices.map((i) => validatedEntries[i]).filter((e) => e !== void 0);
         if (categoryEntries.length > 0) {
           result.push({ category, entries: categoryEntries });
         }
@@ -428,7 +510,7 @@ async function categorizeEntries(provider, entries, context) {
       const categoryMap = parsed;
       for (const [category, rawIndices] of Object.entries(categoryMap)) {
         const indices = Array.isArray(rawIndices) ? rawIndices : [];
-        const categoryEntries = indices.map((i) => entries[i]).filter((e) => e !== void 0);
+        const categoryEntries = indices.map((i) => entriesCopy[i]).filter((e) => e !== void 0);
         if (categoryEntries.length > 0) {
           result.push({ category, entries: categoryEntries });
         }
@@ -439,12 +521,12 @@ async function categorizeEntries(provider, entries, context) {
     (0, import_core3.warn)(
       `LLM categorization failed, falling back to General: ${error2 instanceof Error ? error2.message : String(error2)}`
     );
-    return [{ category: "General", entries }];
+    return [{ category: "General", entries: entriesCopy }];
   }
 }
 
 // src/llm/tasks/enhance.ts
-var ENHANCE_PROMPT = `You are improving changelog entries for a software project.
+var DEFAULT_ENHANCE_PROMPT = `You are improving changelog entries for a software project.
 Given a technical commit message, rewrite it as a clear, user-friendly changelog entry.
 
 Rules:
@@ -460,9 +542,10 @@ Type: {{type}}
 Description: {{description}}
 
 Rewritten description (only output the new description, nothing else):`;
-async function enhanceEntry(provider, entry, _context) {
-  const styleText = _context.style ? `- ${_context.style}` : '- Use present tense ("Add feature" not "Added feature")';
-  const prompt = ENHANCE_PROMPT.replace("{{style}}", styleText).replace("{{type}}", entry.type).replace("{{#if scope}}Scope: {{scope}}{{/if}}", entry.scope ? `Scope: ${entry.scope}` : "").replace("{{description}}", entry.description);
+async function enhanceEntry(provider, entry, context) {
+  const styleText = context.style ? `- ${context.style}` : '- Use present tense ("Add feature" not "Added feature")';
+  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);
+  const prompt = resolvePrompt("enhance", defaultPrompt, context.prompts);
   const response = await provider.complete(prompt);
   return response.trim();
 }
@@ -518,7 +601,23 @@ function buildPrompt(entries, categories, style) {
   const entriesText = entries.map((e, i) => `${i}. [${e.type}]${e.scope ? ` (${e.scope})` : ""}: ${e.description}`).join("\n");
   const styleText = style || 'Use present tense ("Add feature" not "Added feature"). Be concise.';
   const categorySection = categories ? `Categories (use ONLY these):
-${categories.map((c) => `- "${c.name}": ${c.description}`).join("\n")}` : `Categories: Group into meaningful categories (e.g., "New", "Fixed", "Changed", "Removed").`;
+${categories.map((c) => {
+    const scopeInfo = c.scopes?.length ? ` Allowed scopes: ${c.scopes.join(", ")}.` : "";
+    return `- "${c.name}": ${c.description}${scopeInfo}`;
+  }).join("\n")}` : `Categories: Group into meaningful categories (e.g., "New", "Fixed", "Changed", "Removed").`;
+  let scopeInstruction = "";
+  if (categories) {
+    const scopeMap = getAllowedScopesFromCategories(categories);
+    if (scopeMap.size > 0) {
+      const parts = [];
+      for (const [catName, scopes] of scopeMap) {
+        parts.push(`For "${catName}" entries, assign a scope from: ${scopes.join(", ")}.`);
+      }
+      scopeInstruction = `
+${parts.join("\n")}
+Only use scopes from these predefined lists. Set scope to null if no scope applies.`;
+    }
+  }
   return `You are generating release notes for a software project. Given the following changelog entries, do two things:
 
 1. **Rewrite** each entry as a clear, user-friendly description
@@ -529,9 +628,7 @@ Style guidelines:
 - Be concise (1 short sentence per entry)
 - Focus on what changed, not implementation details
 
-${categorySection}
-
-${categories ? 'For entries in categories involving internal/developer changes, set a "scope" field with a short subcategory label (e.g., "CI", "Dependencies", "Testing").' : ""}
+${categorySection}${scopeInstruction}
 
 Entries:
 ${entriesText}
@@ -548,7 +645,8 @@ async function enhanceAndCategorize(provider, entries, context) {
   const retryOpts = LLM_DEFAULTS.retry;
   try {
     return await withRetry(async () => {
-      const prompt = buildPrompt(entries, context.categories, context.style);
+      const defaultPrompt = buildPrompt(entries, context.categories, context.style);
+      const prompt = resolvePrompt("enhanceAndCategorize", defaultPrompt, context.prompts);
       const response = await provider.complete(prompt);
       const cleaned = response.replace(/^```(?:json)?\n?/, "").replace(/\n?```$/, "").trim();
       const parsed = JSON.parse(cleaned);
@@ -564,22 +662,23 @@ async function enhanceAndCategorize(provider, entries, context) {
           scope: result.scope || original.scope
         };
       });
+      const validatedEntries = validateEntryScopes(enhancedEntries, context.scopes, context.categories);
       const categoryMap = /* @__PURE__ */ new Map();
       for (let i = 0; i < parsed.entries.length; i++) {
         const result = parsed.entries[i];
         const category = result?.category || "General";
-        const entry = enhancedEntries[i];
+        const entry = validatedEntries[i];
         if (!entry) continue;
         if (!categoryMap.has(category)) {
           categoryMap.set(category, []);
         }
-        categoryMap.get(category).push(entry);
+        categoryMap.get(category)?.push(entry);
       }
       const categories = [];
       for (const [category, catEntries] of categoryMap) {
         categories.push({ category, entries: catEntries });
       }
-      return { enhancedEntries, categories };
+      return { enhancedEntries: validatedEntries, categories };
     }, retryOpts);
   } catch (error2) {
     (0, import_core4.warn)(
@@ -593,7 +692,7 @@ async function enhanceAndCategorize(provider, entries, context) {
 }
 
 // src/llm/tasks/release-notes.ts
-var RELEASE_NOTES_PROMPT = `You are writing release notes for a software project.
+var DEFAULT_RELEASE_NOTES_PROMPT = `You are writing release notes for a software project.
 
 Create engaging, user-friendly release notes for the following changes.
 
@@ -626,16 +725,17 @@ No notable changes in this release.`;
     if (e.breaking) line += " **BREAKING**";
     return line;
   }).join("\n");
-  const prompt = RELEASE_NOTES_PROMPT.replace("{{version}}", context.version ?? "v1.0.0").replace(
+  const defaultPrompt = DEFAULT_RELEASE_NOTES_PROMPT.replace("{{version}}", context.version ?? "v1.0.0").replace(
     "{{#if previousVersion}}Previous version: {{previousVersion}}{{/if}}",
     context.previousVersion ? `Previous version: ${context.previousVersion}` : ""
   ).replace("{{date}}", context.date ?? (/* @__PURE__ */ new Date()).toISOString().split("T")[0] ?? "").replace("{{entries}}", entriesText);
+  const prompt = resolvePrompt("releaseNotes", defaultPrompt, context.prompts);
   const response = await provider.complete(prompt);
   return response.trim();
 }
 
 // src/llm/tasks/summarize.ts
-var SUMMARIZE_PROMPT = `You are creating a summary of changes for a software release.
+var DEFAULT_SUMMARIZE_PROMPT = `You are creating a summary of changes for a software release.
 
 Given the following changelog entries, create a brief summary (2-3 sentences) that captures the main themes of this release.
 
@@ -643,12 +743,13 @@ Entries:
 {{entries}}
 
 Summary (only output the summary, nothing else):`;
-async function summarizeEntries(provider, entries, _context) {
+async function summarizeEntries(provider, entries, context) {
   if (entries.length === 0) {
     return "";
   }
   const entriesText = entries.map((e) => `- [${e.type}]${e.scope ? ` (${e.scope})` : ""}: ${e.description}`).join("\n");
-  const prompt = SUMMARIZE_PROMPT.replace("{{entries}}", entriesText);
+  const defaultPrompt = DEFAULT_SUMMARIZE_PROMPT.replace("{{entries}}", entriesText);
+  const prompt = resolvePrompt("summarize", defaultPrompt, context.prompts);
   const response = await provider.complete(prompt);
   return response.trim();
 }
@@ -796,9 +897,10 @@ ${body}`;
 function writeMarkdown(outputPath, contexts, config, dryRun) {
   const content = renderMarkdown(contexts);
   if (dryRun) {
-    (0, import_core5.info)("--- Changelog Preview ---");
-    console.log(content);
-    (0, import_core5.info)("--- End Preview ---");
+    (0, import_core5.info)(`Would write changelog to ${outputPath}`);
+    (0, import_core5.debug)("--- Changelog Preview ---");
+    (0, import_core5.debug)(content);
+    (0, import_core5.debug)("--- End Preview ---");
     return;
   }
   const dir = path.dirname(outputPath);
@@ -957,9 +1059,10 @@ function renderJson(contexts) {
 function writeJson(outputPath, contexts, dryRun) {
   const content = renderJson(contexts);
   if (dryRun) {
-    (0, import_core7.info)("--- JSON Output Preview ---");
-    console.log(content);
-    (0, import_core7.info)("--- End Preview ---");
+    (0, import_core7.info)(`Would write JSON output to ${outputPath}`);
+    (0, import_core7.debug)("--- JSON Output Preview ---");
+    (0, import_core7.debug)(content);
+    (0, import_core7.debug)("--- End Preview ---");
     return;
   }
   const dir = path2.dirname(outputPath);
@@ -1226,17 +1329,27 @@ function renderTemplate(templatePath, context, engine) {
 
 // src/core/pipeline.ts
 var import_meta = {};
-function generateCompareUrl(repoUrl, from, to) {
+function generateCompareUrl(repoUrl, from, to, packageName) {
+  const isPackageSpecific = from.includes("@") && packageName && from.includes(packageName);
+  let fromVersion;
+  let toVersion;
+  if (isPackageSpecific) {
+    fromVersion = from;
+    toVersion = `${packageName}@${to.startsWith("v") ? "" : "v"}${to}`;
+  } else {
+    fromVersion = from.replace(/^v/, "");
+    toVersion = to.replace(/^v/, "");
+  }
   if (/gitlab\.com/i.test(repoUrl)) {
-    return `${repoUrl}/-/compare/${from}...${to}`;
+    return `${repoUrl}/-/compare/${fromVersion}...${toVersion}`;
   }
   if (/bitbucket\.org/i.test(repoUrl)) {
-    return `${repoUrl}/branches/compare/${from}..${to}`;
+    return `${repoUrl}/branches/compare/${fromVersion}..${toVersion}`;
   }
-  return `${repoUrl}/compare/${from}...${to}`;
+  return `${repoUrl}/compare/${fromVersion}...${toVersion}`;
 }
 function createTemplateContext(pkg) {
-  const compareUrl = pkg.repoUrl && pkg.previousVersion ? generateCompareUrl(pkg.repoUrl, pkg.previousVersion, pkg.version) : void 0;
+  const compareUrl = pkg.repoUrl && pkg.previousVersion ? generateCompareUrl(pkg.repoUrl, pkg.previousVersion, pkg.version, pkg.packageName) : void 0;
   return {
     packageName: pkg.packageName,
     version: pkg.version,
@@ -1274,7 +1387,9 @@ async function processWithLLM(context, config) {
     previousVersion: context.previousVersion ?? void 0,
     date: context.date,
     categories: config.llm.categories,
-    style: config.llm.style
+    style: config.llm.style,
+    scopes: config.llm.scopes,
+    prompts: config.llm.prompts
   };
   const enhanced = {
     entries: context.entries
@@ -1338,7 +1453,6 @@ async function processWithLLM(context, config) {
     }
     return {
       ...context,
-      entries: enhanced.entries,
       enhanced
     };
   } catch (error2) {
@@ -1371,9 +1485,10 @@ async function generateWithTemplate(contexts, config, outputPath, dryRun) {
   );
   const result = renderTemplate(templatePath, documentContext, config.templates?.engine);
   if (dryRun) {
-    (0, import_core8.info)("--- Changelog Preview ---");
-    console.log(result.content);
-    (0, import_core8.info)("--- End Preview ---");
+    (0, import_core8.info)(`Would write templated output to ${outputPath}`);
+    (0, import_core8.debug)("--- Changelog Preview ---");
+    (0, import_core8.debug)(result.content);
+    (0, import_core8.debug)("--- End Preview ---");
     return;
   }
   if (outputPath === "-") {
@@ -1399,8 +1514,10 @@ async function runPipeline(input, config, dryRun) {
     switch (output.format) {
       case "markdown": {
         const file = output.file ?? "CHANGELOG.md";
-        if (config.templates?.path || output.options?.template) {
-          await generateWithTemplate(contexts, config, file, dryRun);
+        const effectiveTemplateConfig = output.templates ?? config.templates;
+        if (effectiveTemplateConfig?.path || output.options?.template) {
+          const configWithTemplate = { ...config, templates: effectiveTemplateConfig };
+          await generateWithTemplate(contexts, configWithTemplate, file, dryRun);
         } else {
           writeMarkdown(file, contexts, config, dryRun);
         }
@@ -1460,8 +1577,8 @@ function splitByPackage(contexts) {
 // src/monorepo/aggregator.ts
 function writeFile(outputPath, content, dryRun) {
   if (dryRun) {
-    (0, import_core9.info)(`[DRY RUN] Would write to ${outputPath}`);
-    console.log(content);
+    (0, import_core9.info)(`Would write to ${outputPath}`);
+    (0, import_core9.debug)(content);
     return;
   }
   const dir = path7.dirname(outputPath);

package/dist/cli.js

@@ -11,7 +11,7 @@ import {
   runPipeline,
   saveAuth,
   writeMonorepoChangelogs
-} from "./chunk-BLWJTLRD.js";
+} from "./chunk-DGZ6TM5J.js";
 
 // src/cli.ts
 import * as fs from "fs";