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.

14.5 KB
Raw Blame
// 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.
//
// ONE WAY TO LEAVE A PR OUT: the `no-release-notes` label (EXCLUDE_LABEL). A PR carrying it is
// dropped entirely — not folded into Internal changes, not counted, not linked. It is for work that
// ships switched off and must not be announced before it is switched on; everything else, internal
// work included, stays in the notes. The labelled PRs are looked up per run (`gh api`), and a failed
// lookup fails the generator rather than publishing notes that silently ignored the label.
//
// 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'

/** PRs carrying this label never reach the notes (see the header). */
export const EXCLUDE_LABEL = 'no-release-notes'

/** 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 }
}

/** `entries` without the PRs numbered in `excluded` (an iterable of PR numbers). */
export function dropExcluded(entries, excluded) {
  const skip = new Set([...(excluded ?? [])].map(Number))
  return entries.filter((entry) => !skip.has(entry.pr))
}

/** PR numbers from `gh --jq` output (one per line) or a hand-typed comma list. */
export function parseExcludeList(text) {
  return String(text ?? '')
    .split(/[\s,]+/)
    .filter(Boolean)
    .map(Number)
    .filter((n) => Number.isSafeInteger(n) && n > 0)
}

/** 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, exclude }) {
  const { entries, newContributors, unparsed } = parseGeneratedBody(body)
  const { groups } = groupEntries(dropExcluded(entries, exclude))
  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 })
}

/** The numbers of every PR (open or closed) carrying EXCLUDE_LABEL. Throws when the lookup fails. */
function excludedPrs({ repo }) {
  const out = execFileSync(
    'gh',
    [
      'api',
      '--paginate',
      `repos/${repo}/issues?labels=${EXCLUDE_LABEL}&state=all&per_page=100`,
      '--jq',
      '.[] | select(.pull_request) | .number'
    ],
    { encoding: 'utf8', maxBuffer: 8 * 1024 * 1024 }
  )
  return parseExcludeList(out)
}

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>] [--exclude <pr,pr>]'
    )
    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 })
  // `--exclude` stands in for the label lookup (tests, a hand run against a saved body).
  const exclude = args.exclude !== undefined ? parseExcludeList(args.exclude === 'true' ? '' : args.exclude) : excludedPrs({ repo })
  const notes = renderNotes({
    tag,
    prev,
    repo,
    body,
    highlights: readHighlights(tag, args.root),
    exclude
  })
  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()