Skip to content

Node-based terminal manager for AI coding agents — tmux-backed terminals and parallel agent sessions as draggable nodes on an infinite pan/zoom canvas. macOS, Linux, and a browser Server Edition.

feat(release): group the release notes, link every PR, and let a Highlights file lead

enes5867355a1af7
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 0ef27749f..04120600d 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -268,9 +268,21 @@ jobs:
with:
fetch-depth: 0 # full history + tags — notes diff against the previous release tag
- # Release notes from commit subjects since the previous tag (merges + the version-bump
- # commit filtered out). Written BEFORE the promote below, so the release is complete —
- # assets AND notes — the moment it becomes "latest" (nodeterm.dev/releases renders these).
+ # Release notes, in two layers (issue #841). Written BEFORE the promote below, so the
+ # release is complete — assets AND notes — the moment it becomes "latest".
+ #
+ # Layer 1 scripts/release-notes.mjs asks GitHub's own generator for the PR-resolved
+ # list (PR number, PR title, author) and regroups it into New / Improved /
+ # Fixed, with test/refactor/chore/ci/build collapsed at the bottom — kept, not
+ # deleted. Every entry links its PR, and any issue its title names.
+ # Layer 2 docs/release-notes/<TAG>.md, a hand-written Highlights block reviewed in the
+ # release PR, placed at the top. ABSENT FILE ⇒ THE GROUPED LIST ALONE. No
+ # release is ever blocked waiting for prose, and nobody has to be in the loop.
+ #
+ # DEGRADES, NEVER FAILS: if the generator throws for any reason (gh api down, a body
+ # shape we do not parse, a missing node), the step falls back to EXACTLY the plain
+ # `git log` list this release used to publish. A release that cannot publish because
+ # prose generation broke would be strictly worse than the list we are replacing.
- name: Generate release notes
env:
GH_TOKEN: ${{ github.token }}
@@ -278,12 +290,16 @@ jobs:
tag="${GITHUB_REF_NAME}"
prev=$(git describe --tags --abbrev=0 "${tag}^" 2>/dev/null || true)
if [ -n "$prev" ]; then range="${prev}..${tag}"; else range="${tag}"; fi
- {
- echo "## Changes${prev:+ since ${prev}}"
- git log --no-merges --format='- %s' "$range" | grep -vE '^- chore\(release\)' | head -60
- total=$(git log --no-merges --format='- %s' "$range" | grep -cvE '^- chore\(release\)' || true)
- if [ "${total:-0}" -gt 60 ]; then echo "- …and $((total - 60)) more commits"; fi
- } > notes.md
+ if ! node scripts/release-notes.mjs --tag "$tag" --prev "$prev" \
+ --repo "$GITHUB_REPOSITORY" --out notes.md; then
+ echo "::warning::structured release notes failed; falling back to the plain commit list"
+ {
+ echo "## Changes${prev:+ since ${prev}}"
+ git log --no-merges --format='- %s' "$range" | grep -vE '^- chore\(release\)' | head -60
+ total=$(git log --no-merges --format='- %s' "$range" | grep -cvE '^- chore\(release\)' || true)
+ if [ "${total:-0}" -gt 60 ]; then echo "- …and $((total - 60)) more commits"; fi
+ } > notes.md
+ fi
gh release edit "$tag" --repo "$GITHUB_REPOSITORY" --notes-file notes.md
- name: Promote release to latest
diff --git a/docs/release-notes/README.md b/docs/release-notes/README.md
new file mode 100644
index 000000000..22f02d9fe
--- /dev/null
+++ b/docs/release-notes/README.md
@@ -0,0 +1,75 @@
+# Release notes
+
+Two layers make up what a GitHub Release says. `.github/workflows/release.yml`'s "Generate release
+notes" step assembles them; `scripts/release-notes.mjs` is the generator and
+`scripts/release-notes.test.ts` is its test.
+
+## Layer 1 — the grouped list (automatic, always there)
+
+GitHub's own generator resolves each commit in the range to the PR that merged it, and we regroup
+that list by the conventional-commit type in the **PR title**:
+
+| section | types |
+|---|---|
+| **New** | `feat`, `feature` |
+| **Improved** | `perf`, `ui`, `a11y`, **and anything unmapped** |
+| **Fixed** | `fix`, `bugfix`, `hotfix`, `revert`, `security` |
+| **Internal changes** (collapsed) | `docs`, `test`, `refactor`, `style`, `chore`, `ci`, `build`, `deps` |
+
+`TYPE_SECTIONS` in `scripts/release-notes.mjs` is the one copy of that table. A type nobody mapped —
+or a PR title with no conventional prefix at all — lands in **Improved**, visible, with its title
+intact. Nothing is ever dropped except the previous tag's `chore(release):` version bump.
+
+## Layer 2 — Highlights (optional, written by hand)
+
+Add `docs/release-notes/<tag>.md` — three to five sentences about what actually changed for
+someone using the app — and CI puts it at the top of the notes, under a `## Highlights` heading
+(supply your own heading if you want a different one).
+
+**If the file is absent, the release publishes with the grouped list alone.** That is the rule the
+whole design hangs on: no release may ever be blocked waiting for prose, and the workflow must stay
+able to publish with nobody in the loop. Write it in the release PR, where it is reviewed like any
+other change, or do not write it.
+
+`v0.3.8.md` is the worked example.
+
+## Writing one
+
+- Say what changed **for a user**, not what the diff did. A reader who does not have the code open
+ is the whole audience for this layer; the grouped list below it is already there for the reader
+ who does.
+- Name the thing in the UI where there is one ("Settings → Notch"), so the sentence is checkable.
+- Do not restate the list. Four sentences that pick the three things worth knowing beat twelve that
+ summarise everything.
+- English, like every other string in this repo.
+
+## Things the generator deliberately does not do
+
+- **It does not translate or rewrite a title.** A non-English or out-of-context PR title is
+ published verbatim in its section. A detector that guesses wrong either mangles a real entry or
+ silently loses a user-facing fix, and neither is better than a line that reads oddly. Note that
+ reading PR titles already removes most of this: a commit subject is written for a reviewer with
+ the diff open, a PR title is reviewed.
+- **Nothing becomes a headline by itself.** The only headline is the Highlights block, which is
+ hand-written and reviewed, so a bad title is at worst a bullet.
+- **It does not categorise by GitHub label.** `.github/release.yml` categories key off PR labels,
+ and this repo does not label PRs by type (measured 2026-09-22: of six sampled PRs in the v0.3.8
+ range, only the dependabot one carried any label). A label-driven config would put every entry in
+ one bucket. If the repo starts labelling, that file becomes worth adding.
+
+## Failure
+
+Any failure in the generator — `gh api` down, a body shape it cannot parse, no `node` on the runner
+— falls back to exactly the plain `git log` list releases used to publish, with a `::warning::` in
+the job log. **A release that cannot publish because prose generation broke would be strictly worse
+than the list this replaces.**
+
+## Testing it by hand
+
+```bash
+node scripts/release-notes.mjs --tag v0.3.8 --prev v0.3.7 --repo eneskirca/nodeterm
+```
+
+It reads `docs/release-notes/<tag>.md` from the working directory (`--root` to point elsewhere) and
+prints to stdout unless given `--out`. `--body-file` substitutes a saved `generate-notes` body for
+the API call.
diff --git a/docs/release-notes/v0.3.8.md b/docs/release-notes/v0.3.8.md
new file mode 100644
index 000000000..fef57af96
--- /dev/null
+++ b/docs/release-notes/v0.3.8.md
@@ -0,0 +1,18 @@
+Windows took a real step forward: the session host now ships **inside** the packaged app, so
+terminals there survive a restart instead of quietly becoming plain shells, and a Windows desktop
+can finally pair with the phone over the relay rather than failing at an SSH step that could never
+have worked on it.
+
+Agents gained two abilities, both gated on your confirmation: they can file a GitHub issue for a
+gap they hit, and they can read — or ask to change — a short allowlist of settings. Agent-to-agent
+messaging still ships **off**.
+
+Three things that quietly said something untrue now say the right one. The licence panel no longer
+prints an access token's week-long expiry as your subscription end date; a build with no update
+channel says so instead of reporting "up to date" forever; and Eco checks the agent still owns its
+pane before quitting it, so waking a sleeping session from the phone can no longer type
+`claude --resume` into the wrong shell.
+
+Smaller, but you will see them: the per-node context meter fills in at mount on remote and
+non-Claude nodes rather than staying blank until your next prompt, and the notch HUD capsule can be
+moved — Settings → Notch now carries a side and a vertical offset beside the width.
diff --git a/scripts/release-notes.mjs b/scripts/release-notes.mjs
new file mode 100644
index 000000000..28ed96392
--- /dev/null
+++ b/scripts/release-notes.mjs
@@ -0,0 +1,324 @@
+// Release notes generator — repo tooling, not product code.
+//
+// Replaces the one-line `git log --no-merges --format='- %s'` step that used to write the
+// release body. That line produced a chronological, unlinkable list in which a test tidy-up
+// sat beside a new feature, because `--no-merges` drops exactly the commits that carry the
+// PR number (issue #841).
+//
+// WHAT RESOLVES THE PR NUMBERS: GitHub's own generator
+// (`POST /repos/{owner}/{repo}/releases/generate-notes`). It already maps every commit in the
+// range back to the PR that merged it and prints `* <PR title> by @<author> in <url>`. We do
+// not re-derive that from git — the platform's resolver is better than a second one here,
+// and it has a side benefit worth writing down: it reads the **PR title**, which was reviewed,
+// instead of the commit subject, which was not. Measured on v0.3.6..v0.3.7 — the Spanish
+// commit subject `fix(grok): usar session_summary como título…` never reaches the notes,
+// because PR #784's title is English.
+//
+// WHAT WE DO OURSELVES: the grouping. GitHub's `.github/release.yml` categories key off PR
+// **labels**, and this repo does not label PRs by type (measured 2026-09-22: of six sampled
+// PRs in the v0.3.8 range, only the dependabot one carried any label at all). A label-driven
+// config would put every entry in one bucket, so the type comes from the conventional-commit
+// prefix in the PR title instead, through the single table below.
+//
+// NON-ENGLISH / OUT-OF-CONTEXT SUBJECTS are deliberately NOT special-cased here. This layer
+// publishes what it is given, verbatim, in its mapped section; it never translates, rewrites
+// or drops a line, because a detector that guesses wrong either mangles a real entry or
+// silently loses a user-facing fix. Nothing here can ever become a headline: the only headline
+// is `## Highlights`, which is a hand-written file reviewed in the release PR
+// (docs/release-notes/<tag>.md). Absent file ⇒ the grouped list alone — no release is ever
+// blocked waiting for prose.
+
+import { readFileSync, existsSync, writeFileSync } from 'node:fs'
+import { execFileSync } from 'node:child_process'
+
+/**
+ * Audience sections, in the order they are rendered. Features first, internal work kept but
+ * collapsed — someone auditing a release must still be able to find the test and chore work.
+ */
+export const SECTIONS = [
+ { key: 'new', title: 'New', collapsed: false },
+ { key: 'improved', title: 'Improved', collapsed: false },
+ { key: 'fixed', title: 'Fixed', collapsed: false },
+ { key: 'internal', title: 'Internal changes', collapsed: true }
+]
+
+/**
+ * THE one commit-type → section table. The workflow, the tests and any future reader use this
+ * and nothing else. A type that is not in here does not vanish: see UNMAPPED_SECTION.
+ */
+export const TYPE_SECTIONS = {
+ feat: 'new',
+ feature: 'new',
+ perf: 'improved',
+ ui: 'improved',
+ a11y: 'improved',
+ fix: 'fixed',
+ bugfix: 'fixed',
+ hotfix: 'fixed',
+ revert: 'fixed',
+ security: 'fixed',
+ docs: 'internal',
+ doc: 'internal',
+ test: 'internal',
+ tests: 'internal',
+ refactor: 'internal',
+ style: 'internal',
+ chore: 'internal',
+ ci: 'internal',
+ build: 'internal',
+ deps: 'internal'
+}
+
+/**
+ * Where an entry lands when its type is not in the table — including an entry with no
+ * conventional prefix at all. Visible on purpose: an unmapped type must be read by a human and
+ * either mapped or reworded, and it can only be read if it is on screen.
+ */
+export const UNMAPPED_SECTION = 'improved'
+
+/** The version-bump commit for the PREVIOUS tag lands in every range. It is pure noise. */
+const RELEASE_BUMP_RE = /^chore\(release\)/i
+
+/**
+ * GitHub's release body is capped (125k characters). Past this we drop the collapsed internal
+ * section and say so, rather than letting the API reject the whole body.
+ */
+export const BODY_LIMIT = 110000
+
+const ENTRY_RE = /^[*-]\s+(.*\S)\s+by\s+@([A-Za-z0-9._-]+(?:\[bot\])?)\s+in\s+(https:\/\/\S*?\/pull\/(\d+))\s*$/
+const CONVENTIONAL_RE = /^([A-Za-z]+)(?:\(([^)]*)\))?(!?):\s*(\S.*)$/
+
+/** Section key for a commit type. Unknown / missing type ⇒ UNMAPPED_SECTION. */
+export function sectionForType(type) {
+ if (!type) return UNMAPPED_SECTION
+ return TYPE_SECTIONS[String(type).toLowerCase()] ?? UNMAPPED_SECTION
+}
+
+/**
+ * Split a conventional-commit title. Returns null when the prefix is not a type we know:
+ * "Messaging: the refusal was advising a remedy that cannot work" parses as the shape but
+ * "messaging" is not a type, and stripping that prefix would throw away the only context the
+ * line has. An unrecognised prefix therefore stays part of the subject, verbatim.
+ */
+export function parseConventional(title) {
+ const m = CONVENTIONAL_RE.exec(title)
+ if (!m) return null
+ const type = m[1].toLowerCase()
+ if (!(type in TYPE_SECTIONS)) return null
+ return { type, scope: m[2] || null, breaking: m[3] === '!', subject: m[4] }
+}
+
+/** Parse one `* <title> by @<author> in <pr url>` line from GitHub's generated body. */
+export function parseEntry(line) {
+ const m = ENTRY_RE.exec(line)
+ if (!m) return null
+ return { title: m[1], author: m[2], prUrl: m[3], pr: Number(m[4]) }
+}
+
+export function isReleaseBump(title) {
+ return RELEASE_BUMP_RE.test(title)
+}
+
+/**
+ * Turn bare `#123` references into absolute links. Absolute because these notes are also
+ * rendered outside github.com (nodeterm.dev), where nothing auto-links a bare `#123`.
+ * `/issues/<n>` redirects to `/pull/<n>` when the number is a PR, so a wrong guess about which
+ * kind of number it is costs nothing. A `#123` that is already inside a link is left alone.
+ */
+export function linkifyIssues(text, repo) {
+ if (!repo) return text
+ const parts = String(text).split(/(\[[^\]]*\]\([^)]*\))/g)
+ return parts
+ .map((part, i) =>
+ i % 2 === 1
+ ? part
+ : part.replace(/(^|[^\w/[])#(\d+)\b/g, (_all, lead, n) => `${lead}[#${n}](https://github.com/${repo}/issues/${n})`)
+ )
+ .join('')
+}
+
+function renderAuthor(author) {
+ // `@dependabot[bot]` cannot be the text of a markdown link — the brackets close it early.
+ return author.endsWith('[bot]') ? `@${author}` : `[@${author}](https://github.com/${author})`
+}
+
+/** One rendered bullet. Scope becomes a bold lead-in; the PR is always linked. */
+export function renderEntry(entry, repo) {
+ const parsed = parseConventional(entry.title)
+ const subject = parsed ? parsed.subject : entry.title
+ const scope = parsed?.scope ? `**${parsed.scope}** — ` : ''
+ const breaking = parsed?.breaking ? '**Breaking:** ' : ''
+ const body = `${breaking}${scope}${linkifyIssues(subject, repo)}`
+ return `- ${body} · [#${entry.pr}](${entry.prUrl}) by ${renderAuthor(entry.author)}`
+}
+
+/**
+ * Pull the entries out of GitHub's generated body. Anything that looks like an entry is taken,
+ * whatever heading it sits under, EXCEPT the "New Contributors" block, which GitHub writes in
+ * the same bullet shape and which we keep verbatim at the bottom.
+ */
+export function parseGeneratedBody(body) {
+ const entries = []
+ const newContributors = []
+ const unparsed = []
+ let inContributors = false
+ for (const raw of String(body ?? '').split('\n')) {
+ const line = raw.trimEnd()
+ if (/^#{1,6}\s/.test(line)) {
+ inContributors = /new contributors/i.test(line)
+ continue
+ }
+ if (!/^[*-]\s/.test(line)) continue
+ if (inContributors) {
+ newContributors.push(line.replace(/^[*-]\s+/, '- '))
+ continue
+ }
+ const entry = parseEntry(line)
+ if (entry) entries.push(entry)
+ else unparsed.push(line.replace(/^[*-]\s+/, '- '))
+ }
+ return { entries, newContributors, unparsed }
+}
+
+/** Group parsed entries into the section order above. Release-bump entries are dropped. */
+export function groupEntries(entries) {
+ const groups = Object.fromEntries(SECTIONS.map((s) => [s.key, []]))
+ let dropped = 0
+ for (const entry of entries) {
+ if (isReleaseBump(entry.title)) {
+ dropped += 1
+ continue
+ }
+ const parsed = parseConventional(entry.title)
+ groups[sectionForType(parsed?.type)].push(entry)
+ }
+ return { groups, dropped }
+}
+
+/**
+ * The curated block. The file owns its content; we only add the `## Highlights` heading when
+ * the author did not start with a heading of their own.
+ */
+export function highlightsBlock(text) {
+ const trimmed = String(text ?? '').trim()
+ if (!trimmed) return ''
+ return /^#{1,6}\s/.test(trimmed) ? trimmed : `## Highlights\n\n${trimmed}`
+}
+
+function compareUrl(repo, prev, tag) {
+ return prev ? `https://github.com/${repo}/compare/${prev}...${tag}` : null
+}
+
+/**
+ * Render the whole body. Pure: every input is a value, so the tests exercise exactly what CI
+ * publishes.
+ */
+export function renderNotes({ tag, prev, repo, body, highlights }) {
+ const { entries, newContributors, unparsed } = parseGeneratedBody(body)
+ const { groups } = groupEntries(entries)
+ for (const line of unparsed) groups[UNMAPPED_SECTION].push({ raw: line })
+ const compare = compareUrl(repo, prev, tag)
+
+ const renderSection = (section, { omitInternal }) => {
+ const items = groups[section.key]
+ if (!items.length) return null
+ if (section.collapsed && omitInternal) {
+ const more = compare ? ` See the [full changelog](${compare}) for all of them.` : ''
+ return `_${items.length} internal change${items.length === 1 ? '' : 's'} (tests, refactors, chores, dependency bumps) are omitted here because the notes would exceed GitHub's release-body limit.${more}_`
+ }
+ const lines = items.map((item) => (item.raw ? item.raw : renderEntry(item, repo)))
+ if (!section.collapsed) return `## ${section.title}\n\n${lines.join('\n')}`
+ return [
+ '<details>',
+ `<summary><strong>${section.title}</strong> (${lines.length}) — tests, refactors, chores, dependency bumps</summary>`,
+ '',
+ lines.join('\n'),
+ '',
+ '</details>'
+ ].join('\n')
+ }
+
+ const build = (omitInternal) => {
+ const blocks = []
+ const head = highlightsBlock(highlights)
+ if (head) blocks.push(head)
+ for (const section of SECTIONS) {
+ const rendered = renderSection(section, { omitInternal })
+ if (rendered) blocks.push(rendered)
+ }
+ if (newContributors.length) blocks.push(`## New contributors\n\n${newContributors.join('\n')}`)
+ if (compare) blocks.push(`**Full Changelog**: ${compare}`)
+ return blocks.join('\n\n') + '\n'
+ }
+
+ const full = build(false)
+ if (full.length <= BODY_LIMIT) return full
+ const trimmed = build(true)
+ if (trimmed.length <= BODY_LIMIT) return trimmed
+ const cut = trimmed.slice(0, BODY_LIMIT)
+ const tail = compare ? `\n\n_Truncated to fit GitHub's release-body limit — see the [full changelog](${compare})._\n` : '\n'
+ return cut + tail
+}
+
+// ---------------------------------------------------------------------------------------------
+// CLI. Everything above is pure; everything below is the shell around it.
+// ---------------------------------------------------------------------------------------------
+
+function parseArgs(argv) {
+ const out = {}
+ for (let i = 0; i < argv.length; i += 1) {
+ const arg = argv[i]
+ if (!arg.startsWith('--')) continue
+ const eq = arg.indexOf('=')
+ if (eq !== -1) out[arg.slice(2, eq)] = arg.slice(eq + 1)
+ else if (argv[i + 1] && !argv[i + 1].startsWith('--')) out[arg.slice(2)] = argv[(i += 1)]
+ else out[arg.slice(2)] = 'true'
+ }
+ return out
+}
+
+function generatedBody({ repo, tag, prev }) {
+ const args = ['api', `repos/${repo}/releases/generate-notes`, '-f', `tag_name=${tag}`]
+ if (prev) args.push('-f', `previous_tag_name=${prev}`)
+ args.push('--jq', '.body')
+ return execFileSync('gh', args, { encoding: 'utf8', maxBuffer: 32 * 1024 * 1024 })
+}
+
+export function highlightsPathFor(tag) {
+ return `docs/release-notes/${tag}.md`
+}
+
+function readHighlights(tag, root) {
+ const path = `${root ?? '.'}/${highlightsPathFor(tag)}`
+ try {
+ if (!existsSync(path)) return ''
+ return readFileSync(path, 'utf8')
+ } catch (err) {
+ // Never fatal: an unreadable Highlights file must not hold up a release.
+ console.error(`::warning::could not read ${path}: ${err.message}`)
+ return ''
+ }
+}
+
+function main() {
+ const args = parseArgs(process.argv.slice(2))
+ const tag = args.tag
+ const repo = args.repo
+ if (!tag || !repo) {
+ console.error('usage: release-notes.mjs --tag <tag> --repo <owner/name> [--prev <tag>] [--out <file>] [--body-file <file>]')
+ process.exit(2)
+ }
+ const prev = args.prev && args.prev !== 'true' ? args.prev : ''
+ const body = args['body-file'] ? readFileSync(args['body-file'], 'utf8') : generatedBody({ repo, tag, prev })
+ const notes = renderNotes({
+ tag,
+ prev,
+ repo,
+ body,
+ highlights: readHighlights(tag, args.root)
+ })
+ if (args.out && args.out !== 'true') writeFileSync(args.out, notes)
+ else process.stdout.write(notes)
+}
+
+if (process.argv[1] && process.argv[1].endsWith('release-notes.mjs')) main()
diff --git a/scripts/release-notes.test.ts b/scripts/release-notes.test.ts
new file mode 100644
index 000000000..0216acd9a
--- /dev/null
+++ b/scripts/release-notes.test.ts
@@ -0,0 +1,298 @@
+import { describe, it, expect } from 'vitest'
+import {
+ SECTIONS,
+ TYPE_SECTIONS,
+ UNMAPPED_SECTION,
+ BODY_LIMIT,
+ sectionForType,
+ parseConventional,
+ parseEntry,
+ isReleaseBump,
+ linkifyIssues,
+ renderEntry,
+ parseGeneratedBody,
+ groupEntries,
+ highlightsBlock,
+ highlightsPathFor,
+ renderNotes
+ // @ts-expect-error — plain .mjs repo tooling, deliberately outside the typechecked projects.
+} from './release-notes.mjs'
+
+const REPO = 'eneskirca/nodeterm'
+const pr = (n: number) => `https://github.com/${REPO}/pull/${n}`
+
+// A trimmed copy of a real `POST /releases/generate-notes` body for v0.3.7..v0.3.8. Every case
+// the generator has to get right is in here: a feat, a fix, an internal test PR, a dependabot
+// bump, the PREVIOUS tag's release-bump PR, and two PR titles with no conventional prefix.
+const GENERATED = `## What's Changed
+* feat(notch): let the user place the HUD capsule (side + vertical offset) by @eneskirca in ${pr(796)}
+* chore(release): v0.3.7 by @eneskirca in ${pr(795)}
+* fix(license): never print the token TTL as the subscription end date (#800) by @eneskirca in ${pr(801)}
+* Messaging: the unproven-owner refusal was advising a remedy that cannot work by @eneskirca in ${pr(803)}
+* test(control): settings doc claims pinned to the mechanism by @eneskirca in ${pr(806)}
+* build(deps-dev): bump the dev-dependencies group across 1 directory with 3 updates by @dependabot[bot] in ${pr(697)}
+
+## New Contributors
+* @ezwep made their first contribution in ${pr(579)}
+
+**Full Changelog**: https://github.com/${REPO}/compare/v0.3.7...v0.3.8
+`
+
+const render = (over: Record<string, unknown> = {}) =>
+ renderNotes({ tag: 'v0.3.8', prev: 'v0.3.7', repo: REPO, body: GENERATED, highlights: '', ...over })
+
+describe('type → section table', () => {
+ it('is the ONE mapping, and every value names a real section', () => {
+ const keys = new Set(SECTIONS.map((s: { key: string }) => s.key))
+ for (const [type, section] of Object.entries(TYPE_SECTIONS)) {
+ expect(keys, `${type} maps to an unknown section`).toContain(section)
+ }
+ expect(keys).toContain(UNMAPPED_SECTION)
+ })
+
+ it('puts features first and internal work last', () => {
+ expect(SECTIONS.map((s: { key: string }) => s.key)).toEqual(['new', 'improved', 'fixed', 'internal'])
+ expect(SECTIONS.at(-1).collapsed).toBe(true)
+ expect(SECTIONS.slice(0, -1).every((s: { collapsed: boolean }) => !s.collapsed)).toBe(true)
+ })
+
+ it('routes the audience types the way a reader expects', () => {
+ expect(sectionForType('feat')).toBe('new')
+ expect(sectionForType('perf')).toBe('improved')
+ expect(sectionForType('fix')).toBe('fixed')
+ expect(sectionForType('revert')).toBe('fixed')
+ for (const internal of ['test', 'refactor', 'chore', 'ci', 'build', 'docs']) {
+ expect(sectionForType(internal), internal).toBe('internal')
+ }
+ })
+
+ it('is case-insensitive, because a hand-typed title says Fix as often as fix', () => {
+ expect(sectionForType('FIX')).toBe('fixed')
+ expect(sectionForType('Feat')).toBe('new')
+ })
+
+ // The load-bearing half of "never vanish".
+ it('lands an unmapped type in a VISIBLE section, not in the collapsed one', () => {
+ const section = sectionForType('wip')
+ expect(section).toBe(UNMAPPED_SECTION)
+ const target = SECTIONS.find((s: { key: string }) => s.key === section)
+ expect(target.collapsed).toBe(false)
+ })
+
+ it('treats a missing type the same way', () => {
+ expect(sectionForType(undefined)).toBe(UNMAPPED_SECTION)
+ expect(sectionForType('')).toBe(UNMAPPED_SECTION)
+ })
+})
+
+describe('conventional-commit parsing', () => {
+ it('splits type, scope and subject', () => {
+ expect(parseConventional('feat(notch): place the HUD capsule')).toEqual({
+ type: 'feat',
+ scope: 'notch',
+ breaking: false,
+ subject: 'place the HUD capsule'
+ })
+ })
+
+ it('reads a bang as breaking', () => {
+ expect(parseConventional('feat(api)!: drop the old channel').breaking).toBe(true)
+ })
+
+ it('accepts a type with no scope', () => {
+ expect(parseConventional('docs: rewrite the setup section').scope).toBe(null)
+ })
+
+ // "Messaging: …" parses as the SHAPE of a conventional commit but "messaging" is not a type.
+ // Stripping that prefix would throw away the only context the line has.
+ it('refuses a prefix that is not a known type, so the title stays whole', () => {
+ expect(parseConventional('Messaging: the unproven-owner refusal advises a remedy that cannot work')).toBe(null)
+ const line = renderEntry({ title: 'Messaging: the refusal cannot work', author: 'x', pr: 803, prUrl: pr(803) }, REPO)
+ expect(line).toContain('Messaging: the refusal cannot work')
+ })
+
+ it('is not fooled by a colon later in the subject', () => {
+ expect(parseConventional('the wheel over a banner: whose is it?')).toBe(null)
+ })
+})
+
+describe('entry parsing and links', () => {
+ it('pulls title, author and PR number out of a generated line', () => {
+ expect(parseEntry(`* fix(eco): prove the agent owns the pane by @eneskirca in ${pr(824)}`)).toEqual({
+ title: 'fix(eco): prove the agent owns the pane',
+ author: 'eneskirca',
+ pr: 824,
+ prUrl: pr(824)
+ })
+ })
+
+ it('reads a bot author', () => {
+ expect(parseEntry(`* build(deps): bump by @dependabot[bot] in ${pr(697)}`).author).toBe('dependabot[bot]')
+ })
+
+ it('returns null for a line that is not an entry', () => {
+ expect(parseEntry('**Full Changelog**: https://example.com')).toBe(null)
+ expect(parseEntry('* @ezwep made their first contribution')).toBe(null)
+ })
+
+ it('links the PR on every entry', () => {
+ const line = renderEntry({ title: 'feat(notch): place the capsule', author: 'eneskirca', pr: 796, prUrl: pr(796) }, REPO)
+ expect(line).toContain(`[#796](${pr(796)})`)
+ expect(line).toContain('[@eneskirca](https://github.com/eneskirca)')
+ expect(line).toContain('**notch** —')
+ })
+
+ it('links an issue the subject names, alongside the PR', () => {
+ const line = renderEntry(
+ { title: 'fix(license): never print the token TTL (#800)', author: 'eneskirca', pr: 801, prUrl: pr(801) },
+ REPO
+ )
+ expect(line).toContain(`[#800](https://github.com/${REPO}/issues/800)`)
+ expect(line).toContain(`[#801](${pr(801)})`)
+ })
+
+ it('links every issue shape the repo actually writes', () => {
+ expect(linkifyIssues('(part 1 of #767)', REPO)).toBe(`(part 1 of [#767](https://github.com/${REPO}/issues/767))`)
+ expect(linkifyIssues('route the send (issue #435)', REPO)).toContain('[#435]')
+ expect(linkifyIssues('regression from #789', REPO)).toContain('[#789]')
+ })
+
+ it('leaves a reference that is already a link alone', () => {
+ const already = `see [#800](https://github.com/${REPO}/issues/800)`
+ expect(linkifyIssues(already, REPO)).toBe(already)
+ })
+
+ it('does not turn a colour or a fragment into an issue link', () => {
+ expect(linkifyIssues('the accent is #1e90ff', REPO)).toBe('the accent is #1e90ff')
+ expect(linkifyIssues('see docs/x.md#2 for the rule', REPO)).toBe('see docs/x.md#2 for the rule')
+ })
+
+ it('does not wrap a bot name in a markdown link it would break', () => {
+ const line = renderEntry({ title: 'build(deps): bump', author: 'dependabot[bot]', pr: 697, prUrl: pr(697) }, REPO)
+ expect(line).toContain('@dependabot[bot]')
+ expect(line).not.toContain('[@dependabot[bot]]')
+ })
+})
+
+describe('grouping', () => {
+ it('drops the previous tag’s version-bump PR and nothing else', () => {
+ expect(isReleaseBump('chore(release): v0.3.7')).toBe(true)
+ expect(isReleaseBump('chore(deps): bump vite')).toBe(false)
+ const { entries } = parseGeneratedBody(GENERATED)
+ const { groups, dropped } = groupEntries(entries)
+ expect(dropped).toBe(1)
+ const all = Object.values(groups).flat() as Array<{ pr: number }>
+ expect(all.map((e) => e.pr)).not.toContain(795)
+ expect(all).toHaveLength(entries.length - 1)
+ })
+
+ it('keeps New Contributors out of the entry list', () => {
+ const { entries, newContributors } = parseGeneratedBody(GENERATED)
+ expect(entries.map((e: { pr: number }) => e.pr)).not.toContain(579)
+ expect(newContributors).toEqual([`- @ezwep made their first contribution in ${pr(579)}`])
+ })
+})
+
+describe('rendered notes', () => {
+ it('orders the sections features-first, internal last and collapsed', () => {
+ const out = render()
+ const order = ['## New', '## Improved', '## Fixed', '<details>'].map((h) => out.indexOf(h))
+ expect(order.every((i) => i >= 0)).toBe(true)
+ expect([...order]).toEqual([...order].sort((a, b) => a - b))
+ expect(out).toContain('<summary><strong>Internal changes</strong>')
+ })
+
+ it('collapses internal work but keeps it — it is not deleted', () => {
+ const out = render()
+ const details = out.slice(out.indexOf('<details>'))
+ expect(details).toContain('[#806]')
+ expect(details).toContain('[#697]')
+ // …and the audience sections stay clean of it.
+ expect(out.slice(0, out.indexOf('<details>'))).not.toContain('[#806]')
+ })
+
+ it('puts an unprefixed PR title in a visible section rather than dropping it', () => {
+ const out = render()
+ const visible = out.slice(0, out.indexOf('<details>'))
+ expect(visible).toContain('Messaging: the unproven-owner refusal')
+ })
+
+ it('always ends with the full compare link', () => {
+ expect(render()).toContain(`**Full Changelog**: https://github.com/${REPO}/compare/v0.3.7...v0.3.8`)
+ })
+
+ it('publishes a non-English title verbatim instead of guessing at it', () => {
+ const body = `## What's Changed\n* fix(grok): usar session_summary como título by @xaviguardia in ${pr(784)}\n`
+ const out = render({ body })
+ expect(out).toContain('usar session_summary como título')
+ expect(out).toContain('## Fixed')
+ })
+
+ it('carries New Contributors through', () => {
+ expect(render()).toContain('## New contributors')
+ expect(render()).toContain('@ezwep made their first contribution')
+ })
+
+ it('omits an empty section instead of printing an empty heading', () => {
+ const body = `## What's Changed\n* fix(a): b by @x in ${pr(1)}\n`
+ const out = render({ body })
+ expect(out).toContain('## Fixed')
+ expect(out).not.toContain('## New\n')
+ expect(out).not.toContain('<details>')
+ })
+})
+
+describe('the Highlights layer', () => {
+ it('names the file CI looks for', () => {
+ expect(highlightsPathFor('v0.3.8')).toBe('docs/release-notes/v0.3.8.md')
+ })
+
+ // THE load-bearing rule: no release may ever be blocked waiting for prose.
+ it('renders the grouped list alone when the file is absent', () => {
+ const out = render({ highlights: '' })
+ expect(out).not.toContain('Highlights')
+ expect(out.startsWith('## New')).toBe(true)
+ expect(out).toContain('[#796]')
+ })
+
+ it('treats a whitespace-only file as absent', () => {
+ expect(highlightsBlock(' \n\n ')).toBe('')
+ expect(render({ highlights: '\n \n' }).startsWith('## New')).toBe(true)
+ })
+
+ it('puts the curated block at the very top, above New', () => {
+ const out = render({ highlights: 'Windows can pair with the phone over the relay now.' })
+ expect(out.indexOf('## Highlights')).toBe(0)
+ expect(out.indexOf('## Highlights')).toBeLessThan(out.indexOf('## New'))
+ expect(out).toContain('Windows can pair with the phone over the relay now.')
+ })
+
+ it('does not add a heading when the file already starts with one', () => {
+ const out = render({ highlights: '## What changed for you\n\nA sentence.' })
+ expect(out.startsWith('## What changed for you')).toBe(true)
+ expect(out).not.toContain('## Highlights')
+ })
+})
+
+describe('truncation is never silent', () => {
+ const many = (n: number, type: string) =>
+ Array.from({ length: n }, (_, i) => `* ${type}(scope${i}): ${'a subject that is long enough to matter '.repeat(3)} by @eneskirca in ${pr(1000 + i)}`)
+
+ it('keeps the whole list when it fits', () => {
+ const body = `## What's Changed\n${many(40, 'fix').join('\n')}\n`
+ const out = render({ body })
+ expect(out.length).toBeLessThanOrEqual(BODY_LIMIT)
+ expect(out).toContain('[#1039]')
+ })
+
+ it('when it must cut, it says what was cut and links the full compare view', () => {
+ const body = `## What's Changed\n${many(20, 'feat').join('\n')}\n${many(900, 'chore').join('\n')}\n`
+ const out = render({ body })
+ expect(out.length).toBeLessThanOrEqual(BODY_LIMIT + 200)
+ expect(out).toMatch(/internal changes \(tests, refactors, chores, dependency bumps\) are omitted/)
+ expect(out).toContain(`https://github.com/${REPO}/compare/v0.3.7...v0.3.8`)
+ // The audience sections survive the cut — they are the point of the notes.
+ expect(out).toContain('## New')
+ expect(out).toContain('[#1000]')
+ })
+})
diff --git a/vitest.config.ts b/vitest.config.ts
index 47436de3e..2bb2415a9 100644
--- a/vitest.config.ts
+++ b/vitest.config.ts
@@ -20,7 +20,10 @@ export default defineConfig({
'test/acceptance/**/*.test.ts',
// Opt-in end-to-end tests against a real sshd in Docker. They self-skip unless
// NODETERM_SSH_DOCKER is set, so a machine without Docker still runs a green suite.
- 'test/ssh-docker/**/*.test.ts'
+ 'test/ssh-docker/**/*.test.ts',
+ // Repo tooling that CI depends on (the release-notes generator). Not shipped in any
+ // bundle and not in a tsconfig project, but its pure parts decide what a release says.
+ 'scripts/**/*.test.ts'
],
environment: 'node',
// Issue #629: every run gets a private `TMUX_TMPDIR`, so no test can reach the tmux servers