beadcyte 0.4.0

package/src/changelog-cli.mjs

@@ -0,0 +1,105 @@
+#!/usr/bin/env node
+// changelog-cli.mjs — the `beadcyte changelog` entry point.
+//
+//   beadcyte changelog            regenerate CHANGELOG.md
+//   beadcyte changelog --check    fail if the committed file is stale
+//   beadcyte changelog --stdout   print instead of writing
+//
+// Runs on import, like cli.mjs and serve.mjs: bin/beadcyte.mjs dispatches with a
+// bare `await import(...)`. The generator itself is in changelog.mjs, which
+// stays free of side effects so a test can import it.
+
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { readFile, writeFile } from "node:fs/promises";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { renderChangelog, CHANGELOG_PATH } from "./changelog.mjs";
+
+const execFileAsync = promisify(execFile);
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
+
+/** Tags with their creation dates, oldest first. Empty when there are none. */
+async function gitTags() {
+  try {
+    const { stdout } = await execFileAsync(
+      "git",
+      [
+        "for-each-ref",
+        "--sort=creatordate",
+        "--format=%(refname:short)|%(creatordate:iso-strict)",
+        "refs/tags",
+      ],
+      { cwd: ROOT },
+    );
+    return stdout
+      .split("\n")
+      .filter(Boolean)
+      .map((line) => {
+        const i = line.indexOf("|");
+        return { name: line.slice(0, i), date: line.slice(i + 1) };
+      });
+  } catch {
+    return []; // not a git repo, or no git — Unreleased is still correct
+  }
+}
+
+async function closedBeads() {
+  const { stdout } = await execFileAsync(
+    "bd",
+    ["list", "--status=closed", "--limit", "0", "--json"],
+    { cwd: ROOT, maxBuffer: 256 * 1024 * 1024 },
+  );
+  const parsed = JSON.parse(stdout);
+  return Array.isArray(parsed) ? parsed : (parsed.issues ?? parsed.beads ?? []);
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+  if (args.includes("--help") || args.includes("-h")) {
+    console.log(`
+Generate CHANGELOG.md from closed beads.
+
+  beadcyte changelog            regenerate CHANGELOG.md at the repo root
+  beadcyte changelog --check    exit 2 if the committed file is out of date
+  beadcyte changelog --stdout   print to stdout instead of writing
+
+An entry appears when a closed bead carries ship evidence. Spikes,
+upstream: bugs, chores and epics are excluded. Releases are cut by git tag.
+`);
+    process.exit(0);
+  }
+
+  const [beads, tags] = await Promise.all([closedBeads(), gitTags()]);
+  const next = renderChangelog(beads, { tags });
+  const entries = (next.match(/^- /gm) ?? []).length;
+
+  if (args.includes("--stdout")) {
+    process.stdout.write(next);
+    return;
+  }
+
+  if (args.includes("--check")) {
+    let current = null;
+    try {
+      current = await readFile(CHANGELOG_PATH, "utf8");
+    } catch {
+      console.error("[beadcyte] CHANGELOG.md is missing; run `beadcyte changelog`");
+      process.exit(2);
+    }
+    if (current !== next) {
+      console.error("[beadcyte] CHANGELOG.md is out of date; run `beadcyte changelog`");
+      process.exit(2);
+    }
+    console.error(`[beadcyte] CHANGELOG.md is current (${entries} entries)`);
+    return;
+  }
+
+  await writeFile(CHANGELOG_PATH, next);
+  console.error(`[beadcyte] wrote CHANGELOG.md (${entries} entries)`);
+}
+
+await main().catch((e) => {
+  console.error(`[beadcyte] changelog failed: ${e.message ?? e}`);
+  process.exit(1);
+});

package/src/changelog.mjs

@@ -0,0 +1,196 @@
+// changelog.mjs — CHANGELOG.md as a projection of the tracker.
+//
+// The pure half: beads in, markdown out. `changelog-cli.mjs` is the
+// `beadcyte changelog` entry point and owns the shelling out and the file I/O.
+//
+// Split for a reason worth recording. `beadcyte` subcommands are side-effect entry
+// modules — bin/beadcyte.mjs runs them with a bare `await import(...)`, the way
+// cli.mjs and serve.mjs already work — so a module that both exports pure
+// functions AND runs a CLI on import cannot be imported by a test without
+// shelling out to `bd`. Guarding on `process.argv[1]` looked like the answer
+// and was not: under the dispatcher argv[1] is `bin/beadcyte.mjs`, so the guard was
+// false and `beadcyte changelog` exited 0 having done nothing at all.
+//
+// The data is already there and already good: every close in this project
+// carries a reason written at ship time. Hand-maintaining a changelog
+// alongside that would mean writing every ship note twice and having the two
+// disagree within a fortnight. So this file is generated and the tracker
+// stays the source of truth (bp-67g.34).
+//
+// ## What counts as a ship
+//
+// `isShipped()` from ship.mjs — the same predicate velocity, the estimator
+// and the trend use. A close with no ship evidence is admin cleanup, and a
+// changelog is exactly where that must not appear. This matters more than it
+// sounds: an earlier draft tested `metadata.ship.mr_url` directly, a sixth
+// copy of a rule that had already been consolidated, and silently emitted an
+// EMPTY changelog on a repo whose 15 real ships are attested by commit SHA
+// rather than by merge request.
+//
+// ## Where a release boundary comes from
+//
+// Git tags, and nothing else. A bead belongs to the earliest tag created at
+// or after it closed; a bead closed after the last tag is Unreleased.
+//
+// The alternative — preserving hand-edited released sections and
+// regenerating only Unreleased — was rejected because it makes `--check`
+// meaningless: a file that is only partly generated cannot be compared
+// against a generated one. Tags make the whole file a pure function of the
+// repository, which is what lets a stale committed copy be caught.
+//
+// Until the first tag exists everything is Unreleased, which is honest for a
+// project that has never cut a release.
+
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { isShipped } from "./ship.mjs";
+
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
+
+/** Where the file lives. Root, not src/ — it is for a reader of the repo. */
+export const CHANGELOG_PATH = join(ROOT, "CHANGELOG.md");
+
+/**
+ * Titles that are about the work rather than the product.
+ *
+ * Deliberately a title prefix and an issue type rather than a label: this
+ * repo has 15 shipped beads and not one carries a label, so a label-only
+ * rule would exclude nothing. Labels are honoured as well for repos that do
+ * use them.
+ */
+const SKIP_TITLE = /^\s*(spike|upstream)\s*:/i;
+const SKIP_TYPES = new Set(["chore", "epic"]);
+const SKIP_LABELS = new Set(["changelog:skip", "spike", "upstream"]);
+
+/** Keep a Changelog's own section names, since the header claims that format. */
+const SECTIONS = ["Added", "Fixed", "Changed"];
+
+function sectionFor(type) {
+  if (type === "feature") return "Added";
+  if (type === "bug") return "Fixed";
+  return "Changed";
+}
+
+/**
+ * Does this bead belong in a changelog?
+ *
+ * A changelog is for the reader, not the tracker. A spike is a question
+ * someone answered, an `upstream:` bead is a bug filed against a dependency,
+ * and a chore is housekeeping — none of them are things a user of this tool
+ * received.
+ *
+ * @param {{ status?: string, issue_type?: string, title?: string,
+ *           labels?: string[], metadata?: unknown }} bead
+ */
+export function isChangelogWorthy(bead) {
+  if (bead?.status !== "closed") return false;
+  if (!isShipped(bead)) return false;
+  if (SKIP_TYPES.has(bead.issue_type)) return false;
+  if (SKIP_TITLE.test(bead.title ?? "")) return false;
+  for (const l of bead.labels ?? []) if (SKIP_LABELS.has(l)) return false;
+  return true;
+}
+
+/**
+ * Group shipped beads into releases.
+ *
+ * @param {Array<object>} beads
+ * @param {Array<{name: string, date: string}>} tags  any order; sorted here
+ * @returns {Array<{version: string | null, date: string | null,
+ *                  sections: Record<string, string[]>}>}
+ *   Newest first, Unreleased leading when it has anything.
+ */
+export function groupIntoReleases(beads, tags = []) {
+  // Instants, not strings: git hands over creatordate with the local offset
+  // ("…T21:51:33-05:00") while bd closes are UTC ("…T22:30:00Z"), and as
+  // strings the former reads as EARLIER though it is five hours later. That
+  // put beads closed the afternoon of a release under Unreleased.
+  const at = (iso) => Date.parse(iso);
+  const sorted = [...tags].sort((a, b) => at(a.date) - at(b.date));
+  const UNRELEASED = "\0unreleased"; // cannot collide with a tag name
+  const buckets = new Map();
+  buckets.set(UNRELEASED, { version: null, date: null, beads: [] });
+  for (const t of sorted) {
+    buckets.set(t.name, { version: t.name, date: t.date.slice(0, 10), beads: [] });
+  }
+
+  for (const b of beads.filter(isChangelogWorthy)) {
+    const closed = b.closed_at ?? "";
+    // Earliest tag created at or after this close.
+    const tag = sorted.find((t) => at(t.date) >= at(closed));
+    buckets.get(tag ? tag.name : UNRELEASED).beads.push(b);
+  }
+
+  // Newest first, and stated rather than emergent: Unreleased leads, then
+  // tags newest-to-oldest. Relying on Map insertion order plus a reverse()
+  // put Unreleased LAST, because it is inserted before the tags are.
+  const ordered = [
+    buckets.get(UNRELEASED),
+    ...[...sorted].reverse().map((t) => buckets.get(t.name)),
+  ];
+
+  const out = [];
+  for (const bucket of ordered) {
+    // An empty Unreleased is dropped; an empty tagged release is kept,
+    // because "we cut 0.3.0 and nothing shipped in it" is a real fact.
+    if (bucket.beads.length === 0 && bucket.version === null) continue;
+    const sections = {};
+    for (const s of SECTIONS) sections[s] = [];
+    // Newest close first inside a release, so the most recent work reads
+    // first — the order a person scanning a release actually wants.
+    const newestFirst = [...bucket.beads].sort((x, y) =>
+      (y.closed_at ?? "").localeCompare(x.closed_at ?? ""),
+    );
+    for (const b of newestFirst) {
+      sections[sectionFor(b.issue_type)].push(`- ${b.title} (\`${b.id}\`)`);
+    }
+    out.push({ version: bucket.version, date: bucket.date, sections });
+  }
+  return out;
+}
+
+/**
+ * Render the whole file.
+ *
+ * The header states both rules — what counts as a ship and what is left out
+ * — because a reader cannot otherwise tell the difference between "nothing
+ * shipped" and "this file does not list that kind of thing".
+ */
+export function renderChangelog(beads, { tags = [] } = {}) {
+  const releases = groupIntoReleases(beads, tags);
+  let out = `# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+**This file is generated — do not edit it.** Run \`beadcyte changelog\` to
+regenerate, and \`beadcyte changelog --check\` to verify it is current. The tracker
+is the source of truth; this is a projection of it.
+
+An entry appears here when a closed bead carries ship evidence
+(\`metadata.ship.mr_url\` or \`metadata.ship.commit\`), so administrative
+closes do not. Spikes, \`upstream:\` bugs filed against dependencies, chores
+and epics are left out: they are about the work rather than about what you
+received. Releases are cut by git tag — anything closed since the last tag is
+Unreleased.
+`;
+
+  if (releases.length === 0) {
+    return `${out}\n## [Unreleased]\n\nNothing recorded as shipped yet.\n`;
+  }
+
+  for (const r of releases) {
+    out += r.version ? `\n## [${r.version}] - ${r.date}\n` : `\n## [Unreleased]\n`;
+    if (!SECTIONS.some((s) => r.sections[s].length)) {
+      out += `\nNothing recorded as shipped yet.\n`;
+      continue;
+    }
+    for (const s of SECTIONS) {
+      if (!r.sections[s].length) continue;
+      out += `\n### ${s}\n\n${r.sections[s].join("\n")}\n`;
+    }
+  }
+  return out;
+}