@thebattlearena/corner 0.9.1-beta.70 → 0.10.0

package/ring/scripts/bout-stats.mjs

@@ -0,0 +1,360 @@
+#!/usr/bin/env node
+// The numbers of a bout for the final edition of its chronicle: what the lines are made of, the
+// rhythm of the commits (by day, by hour, by conventional type) and the referee's book (decisions,
+// rebounds, findings, contracts, fouls, round-bells). Read-only: git in the wrestler's worktree and
+// the bout dir. The pure parts are exported and tested; the CLI prints JSON or, with --html, the
+// "El cierre en números" block ready for the chronicle template. Zero-dependency.
+//
+//   node bout-stats.mjs <pr> [--tz <Area/City>] [--repo <owner/name>] [--html] [--lang es|en]
+//                            [--moments <json|file>]
+//
+// --moments takes an array of { at, title, tag } (tag: one of the chronicle's event types); the
+// skill picks them from the play-by-play JSON. Every time comes from the records, never invented.
+import { execFileSync } from 'node:child_process';
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { basename, join } from 'node:path';
+
+import { renderStats } from './bout-stats-render.mjs';
+import {
+  classifyDecision,
+  foulTarget,
+  parseDecisionLine,
+  parseReboundLine,
+} from './chronicle.mjs';
+import {
+  boutDir,
+  isMain,
+  projectDir,
+  readState,
+  repoSlug,
+  slugFromRemote,
+} from './config.mjs';
+import { counts, readLedger } from './findings.mjs';
+
+const LOCKFILES = [
+  'package-lock.json',
+  'yarn.lock',
+  'pnpm-lock.yaml',
+  'bun.lockb',
+  'npm-shrinkwrap.json',
+  'Cargo.lock',
+  'go.sum',
+  'poetry.lock',
+  'Pipfile.lock',
+  'Gemfile.lock',
+  'composer.lock',
+];
+const TEST_PATH = /(^|\/)(__tests__|__mocks__|__fixtures__|tests?|spec)\//;
+const TEST_FILE =
+  /\.(test|spec|e2e-spec)\.[cm]?[jt]sx?$|_test\.(go|py)$|(^|\/)test_[^/]+\.py$/;
+const CODE_FILE =
+  /\.([cm]?[jt]sx?|py|go|rb|java|kt|kts|swift|rs|cs|php|vue|svelte|scala|ex|exs|dart|m|mm|c|cc|cpp|h|hpp|sql)$/;
+
+/** Which part of the bout a changed path belongs to: tests, lockfile, code or other. PURE. */
+export function lineBucket(path) {
+  const file = String(path);
+  if (LOCKFILES.includes(basename(file))) return 'lockfile';
+  if (TEST_PATH.test(file) || TEST_FILE.test(file)) return 'tests';
+  if (CODE_FILE.test(file)) return 'code';
+  return 'other';
+}
+
+/**
+ * Totals of `git diff --numstat` output, split by bucket. A binary file ("-" counts) counts as a
+ * file with no lines. A rename (`a => b`, `{a => b}`) is bucketed by its new path. PURE.
+ */
+export function numstatTotals(text) {
+  const empty = () => ({ added: 0, deleted: 0, files: 0 });
+  const buckets = {
+    code: empty(),
+    tests: empty(),
+    lockfile: empty(),
+    other: empty(),
+  };
+  const total = empty();
+  for (const line of String(text).split('\n').filter(Boolean)) {
+    const [added, deleted, ...rest] = line.split('\t');
+    const path = rest
+      .join('\t')
+      .replace(/\{[^{}]* => ([^{}]*)\}/g, '$1')
+      .replace(/^.* => /, '');
+    const bucket = buckets[lineBucket(path)];
+    const plus = Number(added) || 0;
+    const minus = Number(deleted) || 0;
+    for (const target of [bucket, total]) {
+      target.added += plus;
+      target.deleted += minus;
+      target.files += 1;
+    }
+  }
+  return { ...total, buckets };
+}
+
+const TYPE_ORDER = [
+  'feat',
+  'fix',
+  'refactor',
+  'test',
+  'docs',
+  'perf',
+  'style',
+  'build',
+  'ci',
+  'chore',
+];
+
+/** The conventional type of a commit subject (`feat(mobile): …` → feat), or "other". PURE. */
+export function commitType(subject) {
+  const type = /^([a-z]+)(\([^)]*\))?!?:/i
+    .exec(String(subject).trim())?.[1]
+    ?.toLowerCase();
+  return TYPE_ORDER.includes(type) ? type : 'other';
+}
+
+const dayKey = (at, timeZone) =>
+  new Intl.DateTimeFormat('en-CA', {
+    timeZone,
+    year: 'numeric',
+    month: '2-digit',
+    day: '2-digit',
+  }).format(new Date(at));
+const hourOf = (at, timeZone) =>
+  Number(
+    new Intl.DateTimeFormat('en-GB', {
+      timeZone,
+      hour: '2-digit',
+      hour12: false,
+    })
+      .format(new Date(at))
+      .replace('24', '00'),
+  );
+
+/** Days between two YYYY-MM-DD keys, both included, so a quiet day still shows as zero. PURE. */
+function daysBetween(first, last) {
+  const days = [];
+  for (
+    let at = Date.parse(`${first}T12:00:00Z`);
+    at <= Date.parse(`${last}T12:00:00Z`);
+    at += 86_400_000
+  )
+    days.push(new Date(at).toISOString().slice(0, 10));
+  return days;
+}
+
+/**
+ * The rhythm of `git log --format=%cI%x09%s` lines in a time zone: commits per local day (quiet
+ * days included), per local hour (24 slots) and per conventional type (fixed order, "other" last).
+ * PURE.
+ */
+export function commitRhythm(log, timeZone) {
+  const commits = String(log)
+    .split('\n')
+    .filter(Boolean)
+    .map((line) => {
+      const [at, ...subject] = line.split('\t');
+      return { at, subject: subject.join('\t') };
+    })
+    .filter((commit) => !Number.isNaN(Date.parse(commit.at)));
+  const byHour = Array.from({ length: 24 }, () => 0);
+  const perDay = new Map();
+  const perType = new Map();
+  for (const commit of commits) {
+    byHour[hourOf(commit.at, timeZone)] += 1;
+    const day = dayKey(commit.at, timeZone);
+    perDay.set(day, (perDay.get(day) ?? 0) + 1);
+    const type = commitType(commit.subject);
+    perType.set(type, (perType.get(type) ?? 0) + 1);
+  }
+  const keys = [...perDay.keys()].sort();
+  const byDay = keys.length
+    ? daysBetween(keys[0], keys.at(-1)).map((day) => ({
+        day,
+        n: perDay.get(day) ?? 0,
+      }))
+    : [];
+  const byType = [...TYPE_ORDER, 'other']
+    .filter((type) => perType.has(type))
+    .map((type) => ({ type, n: perType.get(type) }));
+  return { total: commits.length, byDay, byHour, byType };
+}
+
+/**
+ * The referee's book from the ledgers: decisions (distinct ids, the judge's among them), contracts
+ * the judge approved, fouls, rebounds (closed and open), first and last recorded time. PURE.
+ */
+export function ledgerCounts(decisionsText, reboundsText) {
+  const decisions = String(decisionsText)
+    .split('\n')
+    .map(parseDecisionLine)
+    .filter((entry) => entry?.id);
+  const rebounds = String(reboundsText)
+    .split('\n')
+    .map(parseReboundLine)
+    .filter(Boolean);
+  const ids = (list) => new Set(list.map((entry) => entry.id)).size;
+  const fouls = decisions.filter(
+    (entry) => classifyDecision(entry) === 'falta',
+  );
+  // As applyFoulReferences in the chronicle: a line marking an earlier decision of the ledger
+  // counts as that decision's foul, so two marks of the same D<n> are one foul.
+  const logged = new Set(decisions.map((entry) => entry.id));
+  const foulOf = (entry) => {
+    const target = foulTarget(entry.text);
+    return target && target !== entry.id && logged.has(target)
+      ? target
+      : entry.id;
+  };
+  // ISO times with different offsets do not sort as strings: sort by the instant.
+  const times = [...decisions, ...rebounds]
+    .map((entry) => entry.at)
+    .filter((at) => at && !Number.isNaN(Date.parse(at)))
+    .sort((a, b) => Date.parse(a) - Date.parse(b));
+  return {
+    decisions: ids(decisions.filter((entry) => /^D\d+$/.test(entry.id))),
+    judgeDecisions: ids(
+      decisions.filter((entry) => classifyDecision(entry) === 'juez'),
+    ),
+    contracts: ids(
+      decisions.filter((entry) => /contract approved/i.test(entry.text)),
+    ),
+    fouls: new Set(fouls.map(foulOf)).size,
+    rebounds: {
+      total: rebounds.length,
+      closed: rebounds.filter((entry) => entry.closed).length,
+    },
+    first: times[0] ?? null,
+    last: times.at(-1) ?? null,
+  };
+}
+
+/** Round numbers from the bout dir's `round-<n>-<slug>.md` files (one per round-bell). PURE. */
+export function roundBells(files) {
+  return new Set(
+    files.map((file) => /^round-(\d+)-/.exec(file)?.[1]).filter(Boolean),
+  ).size;
+}
+
+/** "134 h 54" between two ISO times. PURE. */
+export function durationLabel(first, last) {
+  if (!first || !last) return null;
+  const minutes = Math.max(
+    0,
+    Math.floor((Date.parse(last) - Date.parse(first)) / 60_000),
+  );
+  return `${Math.floor(minutes / 60)} h ${String(minutes % 60).padStart(2, '0')}`;
+}
+
+/** Moments for the highlight reel: { at, title, tag } sorted by time, the time checked. PURE. */
+export function readMoments(items) {
+  if (!Array.isArray(items))
+    throw new Error('--moments: expected a JSON array');
+  return items
+    .map((item) => {
+      if (Number.isNaN(Date.parse(item?.at)))
+        throw new Error(`--moments: "${item?.title}" has no valid time`);
+      return {
+        at: item.at,
+        title: String(item.title ?? ''),
+        tag: String(item.tag ?? 'campana'),
+      };
+    })
+    .sort((a, b) => Date.parse(a.at) - Date.parse(b.at));
+}
+
+const run = (args, cwd) =>
+  execFileSync('git', ['-C', cwd, ...args], {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+    maxBuffer: 64 * 1024 * 1024,
+  });
+
+/** Everything above for one bout, read from git and its dir. */
+export function collectStats(dir, timeZone) {
+  const state = readState(dir);
+  const read = (name) =>
+    existsSync(join(dir, name)) ? readFileSync(join(dir, name), 'utf8') : '';
+  const notes = [];
+  const book = ledgerCounts(read('decisions.md'), read('rebounds.md'));
+  const worktreeOk = Boolean(state.worktree && existsSync(state.worktree));
+  if (!worktreeOk)
+    notes.push(
+      `git: the wrestler's worktree ${state.worktree} is gone; lines and commits are missing`,
+    );
+  const base = `origin/${state.base}`;
+  const lines = worktreeOk
+    ? numstatTotals(
+        run(['diff', '--numstat', `${base}...HEAD`], state.worktree),
+      )
+    : null;
+  const rhythm = worktreeOk
+    ? commitRhythm(
+        run(
+          ['log', '--no-merges', '--format=%cI%x09%s', `${base}..HEAD`],
+          state.worktree,
+        ),
+        timeZone,
+      )
+    : null;
+  return {
+    pr: state.pr ?? null,
+    timezone: timeZone,
+    head: worktreeOk
+      ? run(['rev-parse', '--short=9', 'HEAD'], state.worktree).trim()
+      : null,
+    duration: {
+      first: book.first,
+      last: book.last,
+      label: durationLabel(book.first, book.last),
+    },
+    lines,
+    rhythm,
+    book: {
+      ...book,
+      findings: counts(readLedger(dir)),
+      roundBells: roundBells(readdirSync(dir)),
+    },
+    notes,
+  };
+}
+
+function option(argv, name) {
+  const index = argv.indexOf(`--${name}`);
+  return index === -1 ? null : argv[index + 1];
+}
+
+function main([pr, ...argv]) {
+  if (!pr)
+    throw new Error(
+      'usage: bout-stats.mjs <pr> [--tz <zone>] [--repo <owner/name>] [--html] [--lang es|en] [--moments <json|file>]',
+    );
+  const repo = option(argv, 'repo');
+  const timeZone =
+    option(argv, 'tz') ?? Intl.DateTimeFormat().resolvedOptions().timeZone;
+  const dir = boutDir(repo ? slugFromRemote(repo) : repoSlug(projectDir()), pr);
+  if (!existsSync(join(dir, 'state.json')))
+    throw new Error(`no bout for #${pr} in ${dir}`);
+  const stats = collectStats(dir, timeZone);
+  if (!argv.includes('--html')) return JSON.stringify(stats, null, 2);
+  const momentsValue = option(argv, 'moments');
+  const moments = momentsValue
+    ? readMoments(
+        JSON.parse(
+          /^\s*\[/.test(momentsValue)
+            ? momentsValue
+            : readFileSync(momentsValue, 'utf8'),
+        ),
+      )
+    : [];
+  return renderStats(stats, { lang: option(argv, 'lang') ?? 'es', moments });
+}
+
+if (isMain(import.meta.url)) {
+  try {
+    console.log(main(process.argv.slice(2)));
+  } catch (error) {
+    console.error(
+      `bout-stats: ${String(error.stderr || error.message).trim()}`,
+    );
+    process.exit(1);
+  }
+}

package/ring/scripts/config.mjs

@@ -712,7 +712,7 @@ function listDirs(dir) {
 
 /** The bout records the chronicle narrates; play-by-play.html and state.json are not records. */
 const CHRONICLED =
-  /^(decisions|rebounds|title-defense|judges-card)\.md$|^round-.*\.md$/;
+  /^(decisions|rebounds|title-defense|judges-card)\.md$|^round-.*\.md$|^(interview|verdicts|plan)\.jsonl$|^plan-tecnico\.md$/;
 
 /**
  * Is the bout's play-by-play behind its records? Only once it has a link (`playByPlayUrl`): a

package/ring/scripts/contract-endpoints.mjs

@@ -0,0 +1,163 @@
+// «Endpoints del contrato» for the chronicle's weigh-in: what the judge has to see to sign the API
+// contract, inside the one Artifact page and without a server. The plugin is zero-dependency and
+// cannot parse YAML in Node, so this side only gathers the spec files (every file a changed spec
+// root reaches through `$ref`, as the base has it and as the worktree proposes it, the same
+// proposal contract-preview.mjs serves) and writes them into the page as JSON; the page parses and
+// renders them in the browser (templates/endpoints-view.js, js-yaml from the CDN), operation by
+// operation, with the schemas expanded. Regenerating replaces the block, never duplicates it.
+import { execFileSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { loadConfig, readState } from './config.mjs';
+import { globToRegExp } from './contract.mjs';
+import { isSpecRoot, reachable, specRoots } from './contract-preview.mjs';
+
+const show = (worktree, ref, path) => {
+  try {
+    return execFileSync('git', ['-C', worktree, 'show', `${ref}:${path}`], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+      maxBuffer: 64 * 1024 * 1024,
+    });
+  } catch {
+    return null;
+  }
+};
+
+const refExists = (worktree, ref) => {
+  try {
+    execFileSync('git', ['-C', worktree, 'rev-parse', '--verify', '-q', ref], {
+      stdio: 'ignore',
+    });
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+/**
+ * The spec roots whose reachable files differ between `read.base` and `read.head`, each with those
+ * files: `{ path: { base, head } }`, a side null when the file does not exist there and `head`
+ * omitted (`same: true`) when it did not change, so an untouched fragment travels once. PURE apart
+ * from `read`.
+ */
+export function specSources(roots, read) {
+  return roots
+    .map((root) => {
+      const paths = new Set([
+        ...reachable([root], read.head),
+        ...reachable([root], read.base),
+      ]);
+      const files = Object.fromEntries(
+        [...paths].sort().map((path) => {
+          const base = read.base(path);
+          const head = read.head(path);
+          return [path, base === head ? { base, same: true } : { base, head }];
+        }),
+      );
+      const changed = Object.values(files).some((file) => !file.same);
+      return changed ? { root, files } : null;
+    })
+    .filter(Boolean);
+}
+
+/**
+ * The spec roots the PR deletes: files gone from the worktree that the config's `apiSpec` names
+ * and that were an OpenAPI root at the base. `specRoots` only sees the worktree, so without these
+ * a deleted root never reaches the judge. PURE apart from `baseHead`.
+ */
+export function deletedSpecRoots(deleted, apiSpec, baseHead) {
+  const named = (path) =>
+    apiSpec.some((entry) => {
+      const spec = entry.replace(/^\.\//, '');
+      return /[*?]/.test(spec) ? globToRegExp(spec).test(path) : spec === path;
+    });
+  return deleted.filter(
+    (path) => named(path) && isSpecRoot(path, baseHead(path) ?? ''),
+  );
+}
+
+/** The bout's changed spec roots against its stack base, read from its worktree. */
+export function collectContractSources(boutDir) {
+  const state = readState(boutDir);
+  const { worktree, base } = state;
+  if (!worktree || !existsSync(worktree))
+    throw new Error(`the worktree of #${state.pr} is gone (${worktree})`);
+  const ref = refExists(worktree, `origin/${base}`) ? `origin/${base}` : base;
+  const { config } = loadConfig(worktree);
+  const head = (path) => {
+    const file = join(worktree, path);
+    return existsSync(file) ? readFileSync(file, 'utf8') : null;
+  };
+  const atBase = (path) => show(worktree, ref, path);
+  const deleted = execFileSync(
+    'git',
+    [
+      '-C',
+      worktree,
+      'diff',
+      '--name-only',
+      '--no-renames',
+      '--diff-filter=D',
+      ref,
+    ],
+    { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] },
+  )
+    .split('\n')
+    .filter(Boolean);
+  const roots = [
+    ...new Set([
+      ...specRoots(worktree, config),
+      ...deletedSpecRoots(deleted, config.apiSpec, (path) =>
+        atBase(path)?.slice(0, 2048),
+      ),
+    ]),
+  ];
+  return {
+    pr: state.pr,
+    base: ref,
+    roots: specSources(roots, { head, base: atBase }),
+  };
+}
+
+/** JSON safe inside a `<script>` element. PURE. */
+const LINE_SEPARATOR = String.fromCharCode(0x2028);
+const PARAGRAPH_SEPARATOR = String.fromCharCode(0x2029);
+export const scriptJson = (value) =>
+  JSON.stringify(value)
+    .replace(/</g, '\\u003c')
+    .split(LINE_SEPARATOR)
+    .join('\\u2028')
+    .split(PARAGRAPH_SEPARATOR)
+    .join('\\u2029');
+
+/**
+ * The block that goes after `<!-- ring:api-contract #<pr> -->`: the container the page renders
+ * into, a line for a reader without scripts, and the sources as JSON. PURE.
+ */
+export function endpointsBlock(sources) {
+  const roots = sources.roots.map((entry) => entry.root).join(', ');
+  const fallback = sources.roots.length
+    ? `Los endpoints del contrato se dibujan al abrir la página (${roots} contra ${sources.base}).`
+    : `Ningún spec cambia contra ${sources.base}.`;
+  return [
+    `<div class="endpoints" data-ring-spec="${sources.pr}"><p class="endpoints-wait">${fallback}</p></div>`,
+    `<script type="application/json" id="ring-spec-${sources.pr}">${scriptJson(sources)}</script>`,
+  ].join('\n');
+}
+
+/**
+ * The fingerprint of the spec files a page embeds for this bout (SHA-256 of the JSON exactly as
+ * written into the page, which the page hashes too), or null when they cannot be read.
+ */
+export function contractSourcesHash(boutDir) {
+  try {
+    return createHash('sha256')
+      .update(scriptJson(collectContractSources(boutDir)))
+      .digest('hex');
+  } catch {
+    return null;
+  }
+}

package/ring/scripts/contract-preview.mjs

@@ -17,6 +17,8 @@
 // When a database model changes, the referee draws the change as an entity-relationship diagram
 // (references/db-diagram.md) in <bout dir>/db-diagram.html; the page shows it above the model
 // diff, which folds into a "Code diff" disclosure, and warns when a model file changed after it.
+// The endpoints get theirs the same way (references/api-diagram.md, <bout dir>/api-diagram.html):
+// shown above "What changes", whose diff folds under it, and stale when a spec file changed after.
 //
 // The diff runs in two places from one module (spec-diff.mjs): the page parses both specs (YAML
 // via js-yaml) and computes operations, schemas and error responses; the server computes the same
@@ -129,7 +131,7 @@ function worktreeFiles(worktree) {
 }
 
 /** The spec roots the config names: its plain paths, and the OpenAPI roots its globs match. */
-function specRoots(worktree, config) {
+export function specRoots(worktree, config) {
   const files = worktreeFiles(worktree);
   const head = (path) => {
     try {
@@ -241,6 +243,9 @@ function dbDiff(worktree, ref, config) {
 /** The referee's diagram of the model change, drawn per references/db-diagram.md. */
 export const DIAGRAM_FILE = 'db-diagram.html';
 
+/** The referee's diagram of the endpoints, drawn per references/api-diagram.md. */
+export const API_DIAGRAM_FILE = 'api-diagram.html';
+
 /**
  * When a changed model file was last written, in ms: its mtime, or for a deleted file the time of
  * the commit that deleted it. A deletion not committed yet has no date: `Infinity`, so it always
@@ -263,12 +268,12 @@ function writtenAt(worktree, path) {
 }
 
 /**
- * The diagram of the model change, or `null` when the referee has not drawn one: `stale` lists the
- * changed model files written (or deleted) after it, so the judge knows it may not match the diff
- * below.
+ * A diagram of the change (the models by default, or `API_DIAGRAM_FILE`), or `null` when the
+ * referee has not drawn it: `stale` lists the changed files written (or deleted) after it, so the
+ * judge knows it may not match the diff below.
  */
-export function diagramState(dir, worktree, files) {
-  const diagram = join(dir, DIAGRAM_FILE);
+export function diagramState(dir, worktree, files, file = DIAGRAM_FILE) {
+  const diagram = join(dir, file);
   if (!existsSync(diagram)) return null;
   const drawnAt = statSync(diagram).mtimeMs;
   const stale = files
@@ -319,7 +324,7 @@ export function page(specs, first = 0) {
   pre { overflow-x: auto; border: 1px solid var(--line); border-radius: 6px; padding: 8px; font-size: 12px; }
   pre span { display: block; white-space: pre; }
   #swagger { background: #fff; border-radius: 6px; }
-  #diagram { width: 100%; min-height: 320px; border: 1px solid var(--line); border-radius: 6px; background: #fff; }
+  .diagram { width: 100%; min-height: 320px; border: 1px solid var(--line); border-radius: 6px; background: #fff; }
   .warn { background: var(--chg); border-radius: 6px; padding: 8px; }
   details { margin-top: 12px; } summary { cursor: pointer; }
 </style></head>
@@ -364,7 +369,14 @@ export function page(specs, first = 0) {
     html += list('Spec files changed', specFiles.files.map((f) => f.status + '  ' + f.path), '') +
       (specFiles.diff ? '<details><summary>Spec text diff</summary><pre>' + specLines + '</pre></details>' : '');
   }
-  document.getElementById('changes').innerHTML = html || 'No API changes against the base.';
+  const apiStale = data.apiDiagram && data.apiDiagram.stale.length
+    ? '<p class="warn">Changed after the diagram was drawn: ' + esc(data.apiDiagram.stale.join(', ')) + '. Ask the referee to redraw it.</p>'
+    : '';
+  const changes = html || 'No API changes against the base.';
+  document.getElementById('changes').innerHTML = data.apiDiagram
+    ? apiStale + '<iframe class="diagram" src="/api-diagram" sandbox="allow-same-origin" title="Endpoints of the contract"></iframe>' +
+      '<details><summary>Code diff</summary>' + changes + '</details>'
+    : changes;
   const db = data.db;
   const lines = db.diff.split('\\n').map((l) => '<span class="' + (l.startsWith('+') ? 'add' : l.startsWith('-') ? 'del' : '') + '">' + esc(l) + '</span>').join('');
   const code = list('Files', db.files.map((f) => f.status + '  ' + f.path), '') +
@@ -374,13 +386,13 @@ export function page(specs, first = 0) {
     ? '<p class="warn">Changed after the diagram was drawn: ' + esc(db.diagram.stale.join(', ')) + '. Ask the referee to redraw it.</p>'
     : '';
   const drawn = db.diagram
-    ? stale + '<iframe id="diagram" src="/db-diagram" sandbox="allow-same-origin" title="Database model change"></iframe>' +
+    ? stale + '<iframe class="diagram" src="/db-diagram" sandbox="allow-same-origin" title="Database model change"></iframe>' +
       '<details><summary>Code diff</summary>' + code + '</details>'
     : code;
   const dbBox = document.getElementById('db');
   dbBox.innerHTML = db.files.length ? drawn : 'No database-model changes against the base.';
-  const frame = document.getElementById('diagram');
-  if (frame) frame.addEventListener('load', () => { frame.style.height = frame.contentDocument.documentElement.scrollHeight + 'px'; });
+  for (const frame of document.querySelectorAll('iframe.diagram'))
+    frame.addEventListener('load', () => { frame.style.height = frame.contentDocument.documentElement.scrollHeight + 'px'; });
 </script>
 </body></html>`;
 }
@@ -447,8 +459,11 @@ export function handler({ dir, worktree, base, config }) {
           : send(200, contentType(path), text);
       }
       if (url.pathname === '/favicon.ico') return send(204, 'text/plain', '');
-      if (url.pathname === '/db-diagram') {
-        const diagram = join(dir, DIAGRAM_FILE);
+      if (url.pathname === '/db-diagram' || url.pathname === '/api-diagram') {
+        const diagram = join(
+          dir,
+          url.pathname === '/db-diagram' ? DIAGRAM_FILE : API_DIAGRAM_FILE,
+        );
         return existsSync(diagram)
           ? send(200, 'text/html; charset=utf-8', readFileSync(diagram))
           : send(404, 'text/plain', 'not found');
@@ -467,6 +482,7 @@ export function handler({ dir, worktree, base, config }) {
           : send(200, contentType(spec), text);
       }
       if (url.pathname === '/diff.json') {
+        const specFiles = specFilesDiff(worktree, ref, config);
         const body = {
           spec,
           specs,
@@ -476,7 +492,11 @@ export function handler({ dir, worktree, base, config }) {
             ? serverSpecDiff(spec, atBase(spec), proposed(spec))
             : null,
           db: withDiagram(dbDiff(worktree, ref, config)),
-          specFiles: specFilesDiff(worktree, ref, config),
+          specFiles,
+          // Like the database's: no diagram without a spec change, so an old one never shows.
+          apiDiagram: specFiles.files.length
+            ? diagramState(dir, worktree, specFiles.files, API_DIAGRAM_FILE)
+            : null,
         };
         return send(
           200,