codegraph/scripts/prepare-release.mjs

#!/usr/bin/env node
/**
 * Promote `## [Unreleased]` content into `## [<version>]` in CHANGELOG.md
 * so the release.yml workflow's `extract-release-notes.mjs <version>` call
 * picks up everything that landed since the last release.
 *
 * **Why this exists:** the release workflow used to do a literal
 * `extract-release-notes.mjs <version>` lookup with an `[Unreleased]`
 * fallback. The fallback only triggers if the `[<version>]` block
 * doesn't exist at all — and in practice maintainers sometimes had a
 * sparse `[<version>]` block pre-populated (e.g. one early fix
 * documented before the rest of the work landed). The workflow then
 * extracted that sparse block, ignoring the much larger `[Unreleased]`
 * section above it — so the published release notes were missing most
 * of what shipped. See v0.9.5 for the canonical post-mortem.
 *
 * **What it does**, idempotently:
 *
 *   Case A — `[<version>]` does not exist yet:
 *     Rename the `[Unreleased]` header to `[<version>] - <YYYY-MM-DD>`
 *     and add a fresh empty `## [Unreleased]` block above it. This is
 *     the common case.
 *
 *   Case B — `[<version>]` exists AND `[Unreleased]` has content:
 *     Merge `[Unreleased]`'s sub-sections (### Added / ### Fixed /
 *     ### Changed / ### Removed / ### Deprecated / ### Security) into
 *     the corresponding sub-sections of `[<version>]`. Unmatched
 *     sub-sections are appended to `[<version>]`. The `[Unreleased]`
 *     block is then emptied.
 *
 *   Case C — `[Unreleased]` has no content:
 *     No-op. Exit 0. Re-runs of the workflow are safe.
 *
 * **Where the date comes from:** for Case A, `<YYYY-MM-DD>` is the
 * UTC date at run time. Matches the existing CHANGELOG convention.
 *
 * **Usage:**
 *
 *   node scripts/prepare-release.mjs                # reads version from package.json
 *   node scripts/prepare-release.mjs 1.2.3          # explicit version
 *
 * **Output:**
 *
 *   Writes CHANGELOG.md in place. Prints a summary line to stdout
 *   like `prepare-release: 0.9.5 — promoted 6 Unreleased entries`.
 *   Exits non-zero on parse failures.
 */

import { readFileSync, writeFileSync } from 'node:fs';
import { resolve } from 'node:path';

const CHANGELOG_PATH = resolve(process.cwd(), 'CHANGELOG.md');

function readPackageVersion() {
  const pkg = JSON.parse(readFileSync(resolve(process.cwd(), 'package.json'), 'utf8'));
  if (!pkg.version) throw new Error('package.json has no "version" field');
  return pkg.version;
}

function todayUtcIsoDate() {
  // YYYY-MM-DD in UTC. Matches the CHANGELOG's existing convention
  // (the existing dated entries don't disclose a timezone, but UTC is
  // stable across runners and is what the workflow's runner produces
  // by default anyway).
  return new Date().toISOString().slice(0, 10);
}

/**
 * Split the CHANGELOG into a header preface + an ordered list of
 * version blocks `{ header, body[] }`, preserving line content
 * verbatim so we can re-join without surprises.
 */
function parseChangelog(text) {
  const lines = text.split('\n');
  const versionHeaderRe = /^## \[([^\]]+)\](?:\s+-\s+(.+))?\s*$/;
  const preface = [];
  const blocks = []; // { header: string, name: string, body: string[] }
  let cur = null;
  for (const line of lines) {
    const m = line.match(versionHeaderRe);
    if (m) {
      if (cur) blocks.push(cur);
      cur = { header: line, name: m[1], date: m[2] ?? null, body: [] };
    } else if (cur) {
      cur.body.push(line);
    } else {
      preface.push(line);
    }
  }
  if (cur) blocks.push(cur);
  return { preface, blocks };
}

function joinChangelog({ preface, blocks }) {
  const parts = [preface.join('\n')];
  for (const b of blocks) {
    // Reconstruct: header + body. The block body INCLUDES the blank
    // line after the header (it was captured verbatim).
    parts.push([b.header, ...b.body].join('\n'));
  }
  return parts.join('\n');
}

/**
 * Split a block body into ordered sub-sections keyed by their
 * `### Heading`. Lines before the first `### Heading` go in
 * `leading`. Preserves the original (line-array) body inside each
 * sub-section so we can splice cleanly when merging.
 */
function splitSubsections(body) {
  const subsectionRe = /^### (\w+)\s*$/;
  const leading = [];
  const subs = []; // { heading: 'Added' | 'Fixed' | …, headerLine: string, body: string[] }
  let cur = null;
  for (const line of body) {
    const m = line.match(subsectionRe);
    if (m) {
      if (cur) subs.push(cur);
      cur = { heading: m[1], headerLine: line, body: [] };
    } else if (cur) {
      cur.body.push(line);
    } else {
      leading.push(line);
    }
  }
  if (cur) subs.push(cur);
  return { leading, subs };
}

function rebuildBody({ leading, subs }) {
  const parts = [];
  if (leading.length) parts.push(leading.join('\n'));
  for (const s of subs) {
    parts.push([s.headerLine, ...s.body].join('\n'));
  }
  return parts.join('\n').split('\n');
}

/**
 * Return true when the block has any meaningful entries (a bullet line
 * starting with `-`, `*`, or a digit) — vs. being empty / just
 * whitespace / just sub-section headers with nothing under them.
 */
function blockHasContent(body) {
  for (const line of body) {
    if (/^\s*([-*]|\d+\.)\s+/.test(line)) return true;
  }
  return false;
}

/**
 * Trim trailing blank lines from an array of lines, then return.
 * Keeps the output tidy when merging.
 */
function trimTrailingBlank(arr) {
  let i = arr.length;
  while (i > 0 && /^\s*$/.test(arr[i - 1])) i--;
  return arr.slice(0, i);
}

function main() {
  const versionArg = process.argv[2];
  const version = versionArg || readPackageVersion();

  const text = readFileSync(CHANGELOG_PATH, 'utf8');
  const parsed = parseChangelog(text);

  const unrelIdx = parsed.blocks.findIndex((b) => b.name === 'Unreleased');
  const verIdx = parsed.blocks.findIndex((b) => b.name === version);

  if (unrelIdx === -1) {
    console.log(`prepare-release: no [Unreleased] block — nothing to do`);
    return;
  }

  const unrel = parsed.blocks[unrelIdx];
  if (!blockHasContent(unrel.body)) {
    console.log(`prepare-release: [Unreleased] is empty — nothing to do`);
    return;
  }

  if (verIdx === -1) {
    // Case A — promote Unreleased → [version].
    const today = todayUtcIsoDate();
    const promoted = {
      header: `## [${version}] - ${today}`,
      name: version,
      date: today,
      body: trimTrailingBlank(unrel.body).concat(['']), // single trailing blank
    };
    const emptied = {
      header: `## [Unreleased]`,
      name: 'Unreleased',
      date: null,
      body: ['', ''], // two blank lines for the next round of entries
    };
    parsed.blocks.splice(unrelIdx, 1, emptied, promoted);
    const next = joinChangelog(parsed);
    writeFileSync(CHANGELOG_PATH, appendLinkRef(next, version));
    console.log(`prepare-release: ${version} — renamed [Unreleased] to [${version}] - ${today}`);
    return;
  }

  // Case B — merge Unreleased sub-sections into the existing
  // [version] sub-sections. New sub-section headings encountered in
  // Unreleased that don't exist in [version] get appended.
  const ver = parsed.blocks[verIdx];
  const unrelSubs = splitSubsections(unrel.body);
  const verSubs = splitSubsections(ver.body);

  let merged = 0;
  for (const us of unrelSubs.subs) {
    const target = verSubs.subs.find((s) => s.heading === us.heading);
    const usBody = trimTrailingBlank(us.body);
    if (usBody.length === 0) continue;
    if (target) {
      // Append Unreleased's entries to the end of the version's matching
      // sub-section, keeping their original ordering. Insert a separating
      // blank line if the existing sub-section doesn't already end in one.
      const existing = trimTrailingBlank(target.body);
      const sep = existing.length && !/^\s*$/.test(existing[existing.length - 1]) ? [''] : [];
      target.body = existing.concat(sep, usBody, ['']);
    } else {
      // Append the whole sub-section to the end.
      verSubs.subs.push({
        heading: us.heading,
        headerLine: us.headerLine,
        body: usBody.concat(['']),
      });
    }
    merged += usBody.filter((l) => /^\s*([-*]|\d+\.)\s+/.test(l)).length;
  }

  ver.body = rebuildBody(verSubs);
  // Empty out Unreleased.
  unrel.body = ['', ''];

  const merged_text = joinChangelog(parsed);
  writeFileSync(CHANGELOG_PATH, appendLinkRef(merged_text, version));
  console.log(`prepare-release: ${version} — merged ${merged} Unreleased entries into existing [${version}] block`);
}

/**
 * Append a `[X.Y.Z]: https://github.com/colbymchenry/codegraph/releases/tag/vX.Y.Z`
 * link reference at the end of the file IF one doesn't already exist. The
 * link ref is what makes `## [X.Y.Z]` heading text auto-link to its tag in
 * GitHub's renderer; without it the heading still renders, just unlinked.
 *
 * Idempotent. The existing CHANGELOG mixes link refs scattered through the
 * file and a sorted block at the bottom — we just append at the very end,
 * which CommonMark accepts regardless.
 */
function appendLinkRef(text, version) {
  const refLine = `[${version}]: https://github.com/colbymchenry/codegraph/releases/tag/v${version}`;
  // Already there? Look for a line that EQUALS this (anywhere in the file)
  // to keep idempotency robust against the scattered-vs-block layout.
  const lines = text.split('\n');
  if (lines.some((l) => l.trim() === refLine)) return text;
  // Append, separated by a blank line from the prior content. Preserve a
  // single trailing newline at EOF.
  const trailingNewline = text.endsWith('\n') ? '' : '\n';
  return text + trailingNewline + refLine + '\n';
}

try {
  main();
} catch (err) {
  console.error(`prepare-release: ${err?.message ?? err}`);
  process.exit(1);
}