@releasekit/notes 0.19.2 → 0.20.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/cli.js CHANGED
@@ -1,10 +1,10 @@
1
1
  #!/usr/bin/env node
2
2
  import {
3
3
  createNotesCommand
4
- } from "./chunk-C4MRRHW7.js";
4
+ } from "./chunk-UWUSIQSW.js";
5
5
  import {
6
6
  readPackageVersion
7
- } from "./chunk-77FGMGVD.js";
7
+ } from "./chunk-QCJ545PJ.js";
8
8
 
9
9
  // src/cli.ts
10
10
  import * as fs from "fs";
package/dist/index.js CHANGED
@@ -18,12 +18,12 @@ import {
18
18
  runPipeline,
19
19
  saveAuth,
20
20
  versionOutputToChangelogInput
21
- } from "./chunk-C4MRRHW7.js";
21
+ } from "./chunk-UWUSIQSW.js";
22
22
  import {
23
23
  aggregateToRoot,
24
24
  detectMonorepo,
25
25
  writeMonorepoChangelogs
26
- } from "./chunk-XMSBOPFR.js";
26
+ } from "./chunk-L34QVI62.js";
27
27
  import {
28
28
  debug,
29
29
  formatVersion,
@@ -31,7 +31,7 @@ import {
31
31
  renderMarkdown,
32
32
  success,
33
33
  writeMarkdown
34
- } from "./chunk-77FGMGVD.js";
34
+ } from "./chunk-QCJ545PJ.js";
35
35
 
36
36
  // src/output/json.ts
37
37
  import * as fs from "fs";
@@ -136,7 +136,35 @@ LLM configuration for release notes enhancement. Requires `provider` and `model`
136
136
  }
137
137
  ```
138
138
 
139
- See the full LLM option reference below.
139
+ See the [full LLM option reference](#llm-options-notesreleasenotesllm) below.
140
+
141
+ ### `notes.releaseNotes.links`
142
+
143
+ Appends a links section to each release in the built-in markdown renderer. Only rendered when LLM categorisation is active (`tasks.categorize: true`).
144
+
145
+ | Option | Type | Description |
146
+ |--------|------|-------------|
147
+ | `title` | `string` | Section heading. Default: `"Links"` |
148
+ | `items` | `object[]` | Static links: `{ label: string, url: string }` |
149
+ | `fromPRBodyMarker` | `string` | Scan PR bodies for lines beginning with this marker and extract markdown links or bare URLs |
150
+
151
+ ```json
152
+ {
153
+ "notes": {
154
+ "releaseNotes": {
155
+ "links": {
156
+ "title": "Migration guide",
157
+ "items": [
158
+ { "label": "v2.0 migration", "url": "https://docs.example.com/migrate-v2" }
159
+ ],
160
+ "fromPRBodyMarker": "Migration:"
161
+ }
162
+ }
163
+ }
164
+ }
165
+ ```
166
+
167
+ Links discovered via `fromPRBodyMarker` are de-duplicated against explicit `items` by URL (explicit `items` take precedence).
140
168
 
141
169
  ---
142
170
 
@@ -182,22 +210,33 @@ How existing changelog files are updated when new entries are generated.
182
210
 
183
211
  | Option | Type | Default | Description |
184
212
  |--------|------|---------|-------------|
185
- | `concurrency` | `integer` | `3` | Maximum parallel LLM requests when enhancing entries |
213
+ | `concurrency` | `integer` | `5` | Maximum parallel LLM requests when enhancing entries |
214
+ | `examples` | `integer` | `3` | Past GitHub releases to fetch for few-shot style prompting (`0`–`5`; requires `GITHUB_TOKEN`) |
215
+
216
+ ### Context (`context`)
217
+
218
+ | Option | Type | Default | Description |
219
+ |--------|------|---------|-------------|
220
+ | `context.pullRequests` | `boolean` | `true` | Fetch linked PR bodies from GitHub for extra LLM context. Requires `GITHUB_TOKEN` or `GH_TOKEN`. |
186
221
 
187
222
  ### Model options (`options`)
188
223
 
189
- | Option | Type | Description |
190
- |--------|------|-------------|
191
- | `timeout` | `integer` (ms) | Request timeout |
192
- | `maxTokens` | `integer` | Maximum tokens to generate |
193
- | `temperature` | `number` | Sampling temperature (0–2) |
224
+ | Option | Type | Default | Description |
225
+ |--------|------|---------|-------------|
226
+ | `timeout` | `integer` (ms) | `60000` | Request timeout |
227
+ | `maxTokens` | `integer` | `16384` | Maximum tokens to generate |
228
+ | `temperature` | `number` | `0.7` | Sampling temperature (0–2) |
194
229
 
195
230
  ```json
196
231
  {
197
- "llm": {
198
- "provider": "openai",
199
- "model": "gpt-4o",
200
- "options": { "temperature": 0.3, "maxTokens": 1000 }
232
+ "notes": {
233
+ "releaseNotes": {
234
+ "llm": {
235
+ "provider": "openai",
236
+ "model": "gpt-4o",
237
+ "options": { "temperature": 0.3, "maxTokens": 1000 }
238
+ }
239
+ }
201
240
  }
202
241
  }
203
242
  ```
@@ -208,12 +247,22 @@ How existing changelog files are updated when new entries are generated.
208
247
  |------|------|-------------|
209
248
  | `enhance` | `boolean` | Rewrite each entry description to be clearer and more user-facing |
210
249
  | `summarize` | `boolean` | Generate a one-paragraph summary of the release |
211
- | `categorize` | `boolean` | Group entries into user-friendly categories (Features, Fixes, …) |
250
+ | `categorize` | `boolean` | Group entries into semantic categories (default set: Breaking, New, Changed, Fixed, Developer) |
212
251
  | `releaseNotes` | `boolean` | Generate full prose release notes suitable for a GitHub release body |
213
252
 
214
253
  ### Categories (`categories`)
215
254
 
216
- Provide hints to the `categorize` task for how to group entries.
255
+ Controls how the `categorize` task groups entries. When not set, the following defaults are used:
256
+
257
+ | Name | Description |
258
+ |------|-------------|
259
+ | `Breaking` | Breaking changes that require user action to upgrade |
260
+ | `New` | New features and capabilities |
261
+ | `Changed` | Changes to existing functionality |
262
+ | `Fixed` | Bug fixes |
263
+ | `Developer` | Internal changes: CI, tooling, dependencies, refactoring |
264
+
265
+ Override with a custom list:
217
266
 
218
267
  ```json
219
268
  {
@@ -236,9 +285,62 @@ Each category object:
236
285
  | `description` | yes | Hint sent to the LLM to guide grouping |
237
286
  | `scopes` | no | Commit scopes that always map to this category |
238
287
 
288
+ ### Category order (`categoryOrder`)
289
+
290
+ Controls the order in which LLM-categorised sections are rendered. Categories not listed appear after the listed ones. The `Breaking` category is always pinned first even if omitted from this list.
291
+
292
+ **Type:** `string[]`
293
+ **Default:** none (LLM-returned order is preserved)
294
+
295
+ ```json
296
+ {
297
+ "llm": {
298
+ "categoryOrder": ["Breaking", "New", "Fixed", "Changed", "Developer"]
299
+ }
300
+ }
301
+ ```
302
+
303
+ ### Scope validation (`scopes`)
304
+
305
+ Controls how the LLM assigns scopes to entries. Invalid scopes trigger a corrective retry; after all retries are exhausted the scope is cleared rather than causing a failure.
306
+
307
+ **`scopes.mode`**
308
+
309
+ | Value | Behaviour |
310
+ |-------|-----------|
311
+ | `unrestricted` | LLM assigns any scope it chooses (default) |
312
+ | `none` | Scopes are disabled; all assigned scopes are cleared |
313
+ | `restricted` | Only scopes in `rules.allowed` are permitted |
314
+ | `packages` | Scopes must match package names (monorepo only) |
315
+
316
+ **`scopes.rules`**
317
+
318
+ | Option | Type | Default | Description |
319
+ |--------|------|---------|-------------|
320
+ | `allowed` | `string[]` | — | Allowed scope values when mode is `restricted` |
321
+ | `caseSensitive` | `boolean` | `false` | Whether scope matching is case-sensitive |
322
+
323
+ ```json
324
+ {
325
+ "llm": {
326
+ "scopes": {
327
+ "mode": "restricted",
328
+ "rules": { "allowed": ["api", "ui", "core"] }
329
+ }
330
+ }
331
+ }
332
+ ```
333
+
239
334
  ### Style (`style`)
240
335
 
241
- A brief style instruction appended to every LLM prompt.
336
+ A style instruction appended to every LLM prompt.
337
+
338
+ Default:
339
+ ```
340
+ Write in past tense ("Added feature", not "Add feature"). Be concise and user-focused. Lead with the impact, not the implementation detail.
341
+ ```
342
+
343
+ Override to change tone:
242
344
 
243
345
  ```json
244
346
  {
@@ -253,24 +355,39 @@ A brief style instruction appended to every LLM prompt.
253
355
  | Option | Type | Default | Description |
254
356
  |--------|------|---------|-------------|
255
357
  | `maxAttempts` | `integer` | `3` | Maximum retries on failure |
256
- | `initialDelay` | `integer` (ms) | `500` | Delay before first retry |
257
- | `maxDelay` | `integer` (ms) | `10000` | Maximum delay between retries |
358
+ | `initialDelay` | `integer` (ms) | `1000` | Delay before first retry |
359
+ | `maxDelay` | `integer` (ms) | `30000` | Maximum delay between retries |
258
360
  | `backoffFactor` | `number` | `2` | Exponential backoff multiplier |
259
361
 
260
362
  ### Prompt overrides (`prompts`)
261
363
 
262
- Override the built-in prompt instructions or templates for any task. The key is the task name (`enhance`, `categorize`, `summarize`, `releaseNotes`).
364
+ `prompts.instructions` appends extra text to the built-in system prompt for a task. The structured output contract is preserved, so this is safe to use with all tasks.
365
+
366
+ Available keys:
367
+
368
+ | Key | Applies to |
369
+ |-----|-----------|
370
+ | `enhance` | Standalone `enhance` task (when `categorize` is disabled) |
371
+ | `categorize` | Standalone `categorize` task (when `enhance` is disabled) |
372
+ | `enhanceAndCategorize` | Combined task (when both `enhance` and `categorize` are enabled) |
373
+ | `summarize` | `summarize` task |
374
+ | `releaseNotes` | `releaseNotes` task |
263
375
 
264
376
  ```json
265
377
  {
266
- "llm": {
267
- "prompts": {
268
- "instructions": {
269
- "enhance": "Rewrite the description from a developer's perspective, keeping it technical."
378
+ "notes": {
379
+ "releaseNotes": {
380
+ "llm": {
381
+ "prompts": {
382
+ "instructions": {
383
+ "enhance": "Write from the perspective of an end user, not a developer.",
384
+ "releaseNotes": "Start with a one-sentence executive summary."
385
+ }
386
+ }
270
387
  }
271
388
  }
272
389
  }
273
390
  }
274
391
  ```
275
392
 
276
- See the [LLM providers guide](./llm-providers.md) for examples.
393
+ See the [LLM providers guide](./llm-providers.md) for more examples.
@@ -32,6 +32,8 @@ Alternatively, set the provider's environment variable (`OPENAI_API_KEY`, `ANTHR
32
32
 
33
33
  ## Provider Setup
34
34
 
35
+ Model names change frequently — check your provider's documentation for the current model IDs. As a general guide: **mini/haiku-tier models** are fast and cheap, suitable for most changelog enhancement; **standard/sonnet-tier models** produce higher-quality output and are worth the extra cost for public-facing release notes.
36
+
35
37
  ### OpenAI
36
38
 
37
39
  ```json
@@ -50,7 +52,7 @@ Alternatively, set the provider's environment variable (`OPENAI_API_KEY`, `ANTHR
50
52
 
51
53
  Set `OPENAI_API_KEY` or run `releasekit-notes auth openai`.
52
54
 
53
- Recommended models: `gpt-4o-mini` (fast, cheap), `gpt-4o` (higher quality).
55
+ See the [OpenAI models documentation](https://platform.openai.com/docs/models) for current model IDs.
54
56
 
55
57
  ### Anthropic
56
58
 
@@ -70,7 +72,7 @@ Recommended models: `gpt-4o-mini` (fast, cheap), `gpt-4o` (higher quality).
70
72
 
71
73
  Set `ANTHROPIC_API_KEY` or run `releasekit-notes auth anthropic`.
72
74
 
73
- Recommended models: `claude-haiku-4-5` (fast), `claude-sonnet-4-5` (balanced).
75
+ See the [Anthropic models documentation](https://docs.anthropic.com/en/docs/about-claude/models) for current model IDs.
74
76
 
75
77
  ### Ollama (local)
76
78
 
@@ -95,7 +97,7 @@ ollama pull llama3.2
95
97
  }
96
98
  ```
97
99
 
98
- Ollama defaults to `http://localhost:11434`. Override with `baseURL` if needed.
100
+ Ollama defaults to `http://localhost:11434`. Override with `baseURL` if needed. See the [Ollama model library](https://ollama.com/library) for available models.
99
101
 
100
102
  ### OpenAI-Compatible Endpoint
101
103
 
@@ -107,7 +109,7 @@ For self-hosted or third-party OpenAI-compatible APIs (LM Studio, vLLM, Azure Op
107
109
  "releaseNotes": {
108
110
  "llm": {
109
111
  "provider": "openai-compatible",
110
- "model": "mistral-7b-instruct",
112
+ "model": "your-model-name",
111
113
  "baseURL": "http://localhost:1234/v1",
112
114
  "tasks": { "enhance": true }
113
115
  }
@@ -116,7 +118,7 @@ For self-hosted or third-party OpenAI-compatible APIs (LM Studio, vLLM, Azure Op
116
118
  }
117
119
  ```
118
120
 
119
- Set `baseURL` to the endpoint's base path. If the endpoint requires authentication, set `apiKey` in the config or store it with `releasekit-notes auth openai-compatible`.
121
+ Set `baseURL` to the endpoint's base path and `model` to the model ID accepted by that endpoint. If authentication is required, set `apiKey` in the config or store it with `releasekit-notes auth openai-compatible`.
120
122
 
121
123
  ---
122
124
 
@@ -129,18 +131,20 @@ Tasks are configured under `llm.tasks`. Multiple tasks can be enabled simultaneo
129
131
  Rewrites each changelog entry description to be clearer and more user-facing.
130
132
 
131
133
  **Input:** `"fix: npe in auth middleware when token is null"`
132
- **Output:** `"Fixed a crash that could occur during authentication when no token was present"`
134
+ **Output:** `"Fix crash during authentication when no token is provided"`
133
135
 
134
136
  ```json
135
137
  { "tasks": { "enhance": true } }
136
138
  ```
137
139
 
138
- Entry descriptions are processed in parallel (default concurrency: 3). Adjust with `concurrency`:
140
+ Entry descriptions are processed in parallel (default concurrency: `5`). Adjust with `concurrency`:
139
141
 
140
142
  ```json
141
- { "concurrency": 5 }
143
+ { "concurrency": 3 }
142
144
  ```
143
145
 
146
+ When `enhance` and `categorize` are both enabled, the pipeline runs a single combined `enhanceAndCategorize` call — see [Combined enhance + categorize](#combined-enhance--categorize). The combined call also generates `leadIn` phrases, scope assignments, and breaking flags. These drive scope grouping, breaking change re-routing, and `**leadIn**: description` formatting in the built-in renderer — none of which are available when running `enhance` alone. Routine fixes and bumps receive no `leadIn`.
147
+
144
148
  ### `summarize`
145
149
 
146
150
  Generates a one-paragraph summary of the entire release, added to the template context as `enhanced.summary`.
@@ -157,7 +161,17 @@ Groups entries into user-friendly categories rather than conventional commit typ
157
161
  { "tasks": { "categorize": true } }
158
162
  ```
159
163
 
160
- Provide category hints for better grouping:
164
+ **Default categories** (used when `categories` is not configured):
165
+
166
+ | Name | Description |
167
+ |------|-------------|
168
+ | `Breaking` | Breaking changes that require user action to upgrade |
169
+ | `New` | New features and capabilities |
170
+ | `Changed` | Changes to existing functionality |
171
+ | `Fixed` | Bug fixes |
172
+ | `Developer` | Internal changes: CI, tooling, dependencies, refactoring |
173
+
174
+ Provide a custom list to override the defaults:
161
175
 
162
176
  ```json
163
177
  {
@@ -170,6 +184,12 @@ Provide category hints for better grouping:
170
184
  }
171
185
  ```
172
186
 
187
+ Control the render order of categories with `categoryOrder`. The `Breaking` category is always pinned first even if omitted:
188
+
189
+ ```json
190
+ { "categoryOrder": ["Breaking", "New", "Fixed", "Changed", "Developer"] }
191
+ ```
192
+
173
193
  ### `releaseNotes`
174
194
 
175
195
  Generates complete prose release notes for the version — suitable for a GitHub release body. Available in the pipeline result as `releaseNotes` and used automatically when `publish.githubRelease.body` is set to `"releaseNotes"`.
@@ -180,45 +200,57 @@ Generates complete prose release notes for the version — suitable for a GitHub
180
200
 
181
201
  You do not need `mode` or `file` configured for this task — the generated text is passed through the pipeline even without file output.
182
202
 
203
+ ### Links section
204
+
205
+ When LLM categorisation is active, you can configure the built-in renderer to append a links section (migration guides, changelogs, etc.) to each release. This is configured on `notes.releaseNotes.links`, not inside `llm`. See [notes.releaseNotes.links](./configuration.md#notesreleasenoteslinks) in the configuration reference.
206
+
183
207
  ---
184
208
 
185
- ## Prompt Customisation
209
+ ## Combined enhance + categorize
186
210
 
187
- Override the built-in prompt instructions or templates for any task. Keys are task names.
211
+ When both `enhance: true` and `categorize: true` are set, the pipeline makes a **single LLM call** (`enhanceAndCategorize`) that rewrites descriptions, assigns categories, generates `leadIn` phrases, identifies scopes, and flags breaking changes — all in one pass. This is more efficient than two sequential calls and is the recommended configuration when using both tasks.
188
212
 
189
- ### Custom instructions
213
+ ```json
214
+ { "tasks": { "enhance": true, "categorize": true } }
215
+ ```
190
216
 
191
- Append extra instructions to the built-in prompt:
217
+ To customise the prompt for the combined call, use the `enhanceAndCategorize` key in `prompts.instructions`. The standalone `enhance` key applies only when `categorize` is disabled:
192
218
 
193
219
  ```json
194
220
  {
195
221
  "llm": {
196
222
  "prompts": {
197
223
  "instructions": {
198
- "enhance": "Write in a friendly tone for non-technical users. Keep entries under 15 words.",
199
- "releaseNotes": "Start with a one-sentence headline, then group changes by theme."
224
+ "enhanceAndCategorize": "Prefer 'New' over 'Changed' for additive changes.",
225
+ "enhance": "Applied only when categorize is not enabled."
200
226
  }
201
227
  }
202
228
  }
203
229
  }
204
230
  ```
205
231
 
206
- ### Full prompt template override
232
+ ---
233
+
234
+ ## Prompt Customisation
207
235
 
208
- Replace the entire prompt for a task. The string is sent to the LLM verbatim — no placeholder substitution is applied.
236
+ `prompts.instructions` appends extra text to the built-in system prompt for a task. The structured output contract is preserved, so this is safe to use with all tasks.
209
237
 
210
238
  ```json
211
239
  {
212
240
  "llm": {
213
241
  "prompts": {
214
- "templates": {
215
- "enhance": "You are a technical writer. Rewrite the changelog entry below as a single, concise sentence in plain English. Return only the rewritten text, nothing else."
242
+ "instructions": {
243
+ "enhance": "Write in a friendly tone for non-technical users. Keep entries under 15 words.",
244
+ "enhanceAndCategorize": "Prefer 'New' over 'Changed' for purely additive changes.",
245
+ "releaseNotes": "Start with a one-sentence headline, then group changes by theme."
216
246
  }
217
247
  }
218
248
  }
219
249
  }
220
250
  ```
221
251
 
252
+ If you need fully custom output formatting, use the [templates system](./templates.md) instead — it operates on the pipeline result after all LLM tasks have run.
253
+
222
254
  ---
223
255
 
224
256
  ## CLI Flags
@@ -233,6 +265,8 @@ releasekit-notes \
233
265
  --input version-output.json
234
266
  ```
235
267
 
268
+ > **Task name format:** CLI flags use kebab-case (`release-notes`), while the config file uses camelCase (`releaseNotes`). The mapping is: `enhance` → `enhance`, `categorize` → `categorize`, `summarize` → `summarize`, `releaseNotes` → `release-notes`.
269
+
236
270
  Use `--no-llm` to disable LLM processing even when it is configured:
237
271
 
238
272
  ```bash