gcf-aif-ext 0.2.7 → 0.3.0

package/lib/design-check.js

@@ -0,0 +1,580 @@
+// Design check (GCF-PRD §11.9): the mechanical checks over gcf/design/, each with a severity.
+// `block` refuses a commit (the pre-commit hook runs this); `report` is a reading of where
+// the design stands — an unfinished unit is the normal state of a design, not a violation.
+import { readFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { bodyIssues, parseBlocks, itemsOf, readRecords } from 'cnlp-kit';
+import {
+  SLUG_RE,
+  UNIT_TYPES,
+  CARD_TYPES,
+  AGENT_SLOTS,
+  listOf,
+  loadDocProfile,
+  slotValues,
+  provenanceOf,
+  isTbd,
+} from './design.js';
+import { buildLedger } from './ledger.js';
+import { sourceBodies } from './anchors.js';
+
+// Units a number may carry. A project adds its own in the `units:` block of glossary.md.
+// Bare `px` is absent on purpose: its size depends on the screen density.
+export const UNITS = [
+  ...['s', 'ms', 'min', 'h', '%', 'fps', 'KB', 'MB', 'GB', 'deg', 'm'],
+  ...['cell', 'cells', 'tile', 'tiles', 'css-px'],
+];
+// A unit is one token, or `<noun> per <event>` for a rate (`2..4 coins per level`).
+const ENVELOPE_RE = /^-?\d+(?:\.\d+)?\.\.-?\d+(?:\.\d+)? (\S+)(?: per \S+)?$/;
+// `in` takes only a set or a hard range: "respawn in 5 s" is a duration in prose, not a limit.
+const COMPARISON_RE = new RegExp(
+  '(?:^|\\s)(?:(?:=|<=|>=|<|>)\\s+-?\\d[\\d.]*' + //       an operator and a value,
+    '|in\\s+(?:\\{[^}]*\\}|-?\\d[\\d.]*\\.\\.-?\\d[\\d.]*))' + // or `in` a set or a range
+    '(?:\\s+(\\S+)(?: per \\S+)?)?$', //                      and its unit, closing the line
+);
+const ENVELOPE_BLOCKS = ['feel', 'sources', 'sinks'];
+const FLAGS = ['src-changed', 'orphan', 'impl?'];
+const REQUIRED_HEADER = ['type', 'route', 'system', 'milestone', 'pillars', 'depends', 'source'];
+const ws = (t) => String(t).replace(/\s+/g, ' ').trim();
+const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
+/**
+ * @typedef {object} Issue
+ * @property {string} check    M1..M14
+ * @property {string} severity  'block' refuses a commit, 'report' is a reading
+ * @property {string} file     gcf-relative
+ * @property {number} line
+ * @property {string | null} id
+ * @property {string} message
+ */
+
+/**
+ * Text a check may judge: quoted and backticked spans are data, paths and ids are names.
+ * `allSlugs` drops every hyphen slug (the glossary check: `tile-tray` is an id, not prose);
+ * otherwise only an id carrying a digit goes (`q-003`), so a unit like `css-px` stays.
+ */
+const judged = (v, allSlugs = false) =>
+  String(v)
+    .replace(/"[^"]*"|`[^`]*`/g, ' ')
+    .replace(/\S*\/\S*/g, ' ')
+    .replace(/\b[a-z][a-z0-9]*(?:-[a-z0-9]+)+\b/g, (s) => (allSlugs || /\d/.test(s) ? ' ' : s))
+    .replace(/\s*\[until:[^\]]*\]\s*$/, '');
+
+/** M5: a digit is legal as an envelope (feel, a resource rate) or as a closing comparison. */
+export function numberProblem(block, value, units = UNITS) {
+  const v = judged(value).trim();
+  if (!/\d/.test(v)) return null;
+  const env = v.match(ENVELOPE_RE);
+  if (env) {
+    if (!ENVELOPE_BLOCKS.includes(block)) return 'an envelope is legal only in feel and in a rate';
+
+    return units.includes(env[1]) ? null : `unit "${env[1]}" is not in the closed list`;
+  }
+
+  // A comparison closing the line covers its own number only: "lasts 0.25 s, cooldown = 1 s"
+  // still carries a number in prose before the operator.
+  const cmp = v.match(COMPARISON_RE);
+  const rest = cmp ? v.slice(0, cmp.index) : v;
+  if (cmp && cmp[1] && !units.includes(cmp[1])) return `unit "${cmp[1]}" is not in the list`;
+  if (!/\d/.test(namesOut(rest))) return null;
+
+  return 'a number outside an envelope and a closing comparison: write it as one, or in words';
+}
+
+// A token where letters and digits are glued is a name when it starts with a letter (Vector3,
+// Rigidbody2D) or is a dimension (3D) or a size label (1x2). A number glued to anything else
+// stays a quantity (100px, 500HP, 60fps, 2x, 3rd), and so does a multiplier (x2).
+const NAME_TOKEN = /\b(?=[A-Za-z0-9]*[A-Za-z])(?=[A-Za-z0-9]*\d)[A-Za-z0-9]+\b/g;
+const isName = (t) => (/^[A-Za-z]/.test(t) && !/^x\d+$/i.test(t)) || /^\d+(?:D|x\d+)$/i.test(t);
+const namesOut = (v) => v.replace(NAME_TOKEN, (t) => (isName(t) ? ' ' : t));
+
+/**
+ * True when a line's numbers are all one exact comparison closing it — legal in any block. The
+ * linter's own unit list is wider, so a unit outside the M5 list is the linter's to judge.
+ */
+export const closingComparison = (line) => {
+  const v = judged(line).trim();
+  const cmp = v.match(COMPARISON_RE);
+
+  return Boolean(cmp) && !/\d/.test(namesOut(v.slice(0, cmp?.index ?? 0)));
+};
+
+/** A whole-word, case-insensitive match that also works for Cyrillic (`\b` is ASCII-only). */
+const wordRe = (w) => new RegExp(`(?<![\\p{L}\\p{N}_])${escapeRe(w)}(?![\\p{L}\\p{N}_])`, 'iu');
+
+async function readIf(file) {
+  return existsSync(file) ? readFile(file, 'utf8') : null;
+}
+
+/** Items of one top-level `key:` block of a document: raw item lines. */
+function itemsIn(text, key) {
+  if (text === null) return [];
+  const { lines, sections } = parseBlocks(text);
+  const at = sections.find((s) => s.key === key);
+
+  return at ? itemsOf(lines, at.line) : [];
+}
+
+const recordsIn = (text, key) => readRecords(itemsIn(text, key)).records.map((r) => r.values);
+
+/** `blocks:` of open-questions.md: every reference, and the D1 ones per blocked id. */
+export function questionBlocks(text) {
+  /** @type {Map<string, string[]>} */
+  const d1 = new Map();
+  const refs = [];
+  for (const rec of String(text ?? '').split(/\n(?=- id:)/)) {
+    const qid = rec.match(/^- id:\s*(\S+)/)?.[1];
+    const ids = listOf(rec.match(/^\s+blocks:\s*(.+)$/m)?.[1] ?? '');
+    if (!qid || ids === 'TBD' || !ids.length) continue;
+    refs.push({ qid, ids });
+    if (!/^\s+class:\s*D1\b/m.test(rec)) continue;
+    for (const id of ids) d1.set(id, [...(d1.get(id) ?? []), qid]);
+  }
+
+  return { d1, refs };
+}
+
+/** Everything outside a unit that its references resolve against. */
+async function loadContext(root) {
+  const glossary = await readIf(path.join(root, 'glossary.md'));
+  const game = await readIf(path.join(root, 'game.md'));
+  const pillars = await readIf(path.join(root, 'PILLARS.md'));
+  const forbidden = recordsIn(glossary, 'terms').flatMap((t) => {
+    const not = listOf(t.not ?? '');
+
+    return not === 'TBD' ? [] : not;
+  });
+
+  return {
+    milestones: game === null ? null : recordsIn(game, 'milestones').map((m) => m.name),
+    pillarIds: recordsIn(pillars, 'pillars')
+      .map((p) => p.id)
+      .filter(Boolean),
+    forbidden: forbidden.map((w) => ({ word: w, re: wordRe(w) })),
+    units: [
+      ...UNITS,
+      ...itemsIn(glossary, 'units').map((i) => i.text.replace(/^- /, '').split(':')[0].trim()),
+    ],
+    questions: questionBlocks(await readIf(path.join(root, 'open-questions.md'))),
+    sources: await sourceBodies(path.join(root, 'source')),
+  };
+}
+
+/** Header rules: each returns `[check, message]` or null for one field of a unit's header. */
+const HEADER_RULES = {
+  type: (v) => (UNIT_TYPES.includes(v) ? null : ['M1', `type must be ${UNIT_TYPES.join(' | ')}`]),
+  route: (v, u) => {
+    const m = v.match(/^(soft|hard) \(.+\)$/);
+    if (!m) return ['M1', 'route must read "soft|hard (<why, one line>)"'];
+    const soft = CARD_TYPES.includes(u.header.type);
+    if ((m[1] === 'soft') === soft || !UNIT_TYPES.includes(u.header.type)) return null;
+
+    return [
+      'M1',
+      `a ${u.header.type} is ${soft ? 'soft' : 'hard'}: only mechanic and resource get a card`,
+    ];
+  },
+  system: (v, u) => {
+    const list = listOf(v);
+    if (list === 'TBD' || !list.length || !list.every((s) => SLUG_RE.test(s)))
+      return ['M1', 'system must list >=1 subsystem slugs'];
+
+    return list[0] === u.system
+      ? null
+      : ['M1', `the first system must be ${u.system}, the file it lives in`];
+  },
+  milestone: (v, u, ctx) => {
+    if (v === 'TBD' || v === 'later') return null;
+    if (!SLUG_RE.test(v)) return ['M1', 'milestone must be a milestone name, later or TBD'];
+
+    return ctx.milestones === null || ctx.milestones.includes(v)
+      ? null
+      : ['M2', `milestone ${v} is not a milestone of game.md`];
+  },
+  pillars: (v, u, ctx) => {
+    const list = listOf(v);
+    if (list === 'TBD') return null;
+    const missing = list.filter((p) => !ctx.pillarIds.includes(p));
+
+    return missing.length ? ['M2', `pillar ${missing.join(', ')} has no id in PILLARS.md`] : null;
+  },
+  depends: (v, u, ctx, ledger) => {
+    const list = listOf(v);
+    if (list === 'TBD') return ['M1', 'depends lists ids or reads none'];
+    const unknown = list.filter((d) => d === u.id || !ledger.known(d));
+
+    return unknown.length ? ['M2', `depends on unknown ${unknown.join(', ')}`] : null;
+  },
+  source: (v) =>
+    /^(GDD#[A-Za-z0-9_-]+|manual)$/.test(v)
+      ? null
+      : ['M1', 'source must be GDD#<anchor> or manual'],
+  flags: (v) => {
+    const list = listOf(v);
+
+    return list !== 'TBD' && list.every((f) => FLAGS.includes(f))
+      ? null
+      : ['M1', `flags are ${FLAGS.join(', ')}`];
+  },
+};
+
+/** M1/M2 over a unit's header. */
+function headerIssues(u, ctx, ledger) {
+  const out = [];
+  if (!SLUG_RE.test(u.id)) out.push(['M1', u.line, 'the id must be a lowercase hyphen slug']);
+  for (const key of REQUIRED_HEADER) {
+    if (!(key in u.header)) out.push(['M1', u.line, `missing header field ${key}:`]);
+  }
+
+  for (const [key, value] of Object.entries(u.header)) {
+    const res = HEADER_RULES[key]?.(value, u, ctx, ledger);
+    if (res) out.push([res[0], u.headerLines[key], `${key}: ${res[1]}`]);
+  }
+
+  return out;
+}
+
+// Blocks the card stage writes: a unit in design/ has not reached them yet.
+const CARD_STAGE = ['contract', 'interactions'];
+
+/**
+ * M1 over a body: the profile of its type, with `key: TBD` accepted on any block. In design/
+ * (`stage` 'design') the card-stage blocks are not owed yet.
+ */
+async function bodyProblems(body, type, stage = 'card') {
+  const profile = await loadDocProfile(`unit-${type}`);
+  const tbdLines = new Set(
+    parseBlocks(body)
+      .sections.filter((s) => s.value === 'TBD')
+      .map((s) => s.line),
+  );
+  const owed = (m) =>
+    stage === 'design' && CARD_STAGE.some((k) => m === `missing required block "${k}:"`);
+  const issues = bodyIssues(body, profile).filter(
+    (i) =>
+      !owed(i.message) &&
+      !(tbdLines.has(i.line) && i.message.includes('carries a value on the key line')),
+  );
+
+  return { profile, issues };
+}
+
+/** M4 and M5 over the values of a unit. */
+function valueIssues(values, ctx) {
+  const out = [];
+  for (const v of values) {
+    const text = judged(v.value, true);
+    const hit = ctx.forbidden.find((f) => f.re.test(text));
+    if (hit) out.push(['M4', v.line, `"${hit.word}" is a forbidden synonym in glossary.md`]);
+    // `contract` names code — paths and types like Rigidbody2D — not quantities.
+    const num = v.block === 'contract' ? null : numberProblem(v.block, v.value, ctx.units);
+    if (num) out.push(['M5', v.line, `${num}: ${v.value}`]);
+  }
+
+  return out;
+}
+
+/** One provenance record: its own form, and its quote verbatim in the section it names. */
+function recordProblem(r, ctx) {
+  if (r.src || r.quote) {
+    if (!r.src || !r.quote) return 'src and quote go together';
+    const bodies = ctx.sources.get(r.src);
+    if (!bodies) return `${r.src} is not an anchor of gcf/source/`;
+
+    return bodies.some((b) => b.includes(ws(r.quote)))
+      ? null
+      : `quote is not verbatim in ${r.src}: "${r.quote}"`;
+  }
+
+  if (r.answer) return /^(q-\d+|manual)$/.test(r.answer) ? null : 'answer is q-NNN or manual';
+  if (r.assumed) return /^q-\d+$/.test(r.assumed) ? null : 'assumed is q-NNN';
+
+  return 'a record carries src + quote, answer, or assumed';
+}
+
+/** Slots with content a GDD-sourced unit must back by a provenance record. */
+function uncovered(values, records) {
+  const covers = (block, name) =>
+    records.some(
+      (r) =>
+        r.slot === block ||
+        (name ? r.slot === `${block}.${name}` : r.slot?.startsWith(`${block}.`)),
+    );
+  const need = new Map();
+  for (const v of values.filter((x) => !isTbd(x.value) && !AGENT_SLOTS.includes(x.block))) {
+    const slot = v.name ? `${v.block}.${v.name}` : v.block;
+    if (!need.has(slot) && !covers(v.block, v.name)) need.set(slot, v.line);
+  }
+
+  return [...need];
+}
+
+/**
+ * A problem that comes from the GDD moving under a record — the quote changed, the anchor went —
+ * rather than from the record itself. A flagged unit and a card report it instead of blocking:
+ * a re-import must not lock every commit until each record is rewritten.
+ */
+export const isDrift = (problem) =>
+  /^(quote is not verbatim|GDD#\S+ is not an anchor)/.test(problem ?? '');
+
+/** M9: provenance records are well formed, quotes verbatim, every GDD-sourced slot backed. */
+function provenanceIssues(u, values, ctx) {
+  const records = provenanceOf(u.body);
+  const flags = listOf(u.header.flags ?? '');
+  const flagged = flags !== 'TBD' && flags.some((f) => ['src-changed', 'orphan'].includes(f));
+  const out = [];
+  for (const r of records) {
+    const problem = recordProblem(r, ctx);
+    const sev = flagged && isDrift(problem) ? 'report' : 'block';
+    if (problem) out.push(['M9', r.line, problem, sev]);
+  }
+
+  if (!String(u.header.source ?? '').startsWith('GDD#')) return out;
+  for (const [slot, line] of uncovered(values, records)) {
+    out.push(['M9', line, `${slot} has content and no provenance record`]);
+  }
+
+  return out;
+}
+
+/** Every check over one unit; issue lines are lines of the design file. */
+async function checkUnit(u, ctx, ledger) {
+  /** @type {Issue[]} */
+  const issues = [];
+  const add = (check, line, message, severity = 'block') =>
+    issues.push({ check, severity, file: u.file, line, id: u.id, message });
+  const atBody = (line) => (line ? u.bodyLine + line - 1 : u.line);
+  for (const [c, line, m] of headerIssues(u, ctx, ledger)) add(c, line, m);
+  if (!UNIT_TYPES.includes(u.header.type)) return { issues, values: [] };
+
+  const { profile, issues: shape } = await bodyProblems(u.body, u.header.type, 'design');
+  for (const i of shape) add('M1', atBody(i.line), i.message);
+  const values = slotValues(u.body, profile);
+  for (const [c, line, m] of valueIssues(values, ctx)) add(c, atBody(line), m);
+  for (const [c, line, m, sev] of provenanceIssues(u, values, ctx)) add(c, atBody(line), m, sev);
+
+  return { issues, values };
+}
+
+/** M1 and M5 over a singleton document (game.md, glossary.md), `key: TBD` accepted. */
+async function checkDoc(root, name, ctx) {
+  const text = await readIf(path.join(root, `${name}.md`));
+  if (text === null) return [];
+  const profile = await loadDocProfile(name);
+  const tbdLines = new Set(
+    parseBlocks(text)
+      .sections.filter((s) => s.value === 'TBD')
+      .map((s) => s.line),
+  );
+  const shape = bodyIssues(text, profile).filter(
+    (i) => !(tbdLines.has(i.line) && i.message.includes('carries a value on the key line')),
+  );
+  const nums = slotValues(text, profile).flatMap((v) => {
+    const p = numberProblem(v.block, v.value, ctx.units);
+
+    return p ? [{ line: v.line, message: `${p}: ${v.value}`, check: 'M5' }] : [];
+  });
+
+  return [...shape.map((i) => ({ ...i, check: 'M1' })), ...nums].map((i) => ({
+    check: i.check,
+    severity: 'block',
+    file: `${name}.md`,
+    line: i.line,
+    id: null,
+    message: i.message,
+  }));
+}
+
+/** Each design file opens with the subsystem's `purpose:` (`TBD` until someone writes it). */
+function preambleIssues(design) {
+  return design
+    .filter((d) => !parseBlocks(d.preamble).sections.some((s) => s.key === 'purpose'))
+    .map((d) => ({
+      check: 'M1',
+      severity: 'block',
+      file: d.file,
+      line: 1,
+      id: null,
+      message: `${d.file} opens with "purpose:" — why the subsystem exists, or TBD`,
+    }));
+}
+
+/**
+ * A card is a unit in work: the same profile, plus what the card stage owes — no TBD left,
+ * `contract` and `interactions` written. Its frontmatter is validated by the schema separately.
+ */
+async function checkCard(card, ctx) {
+  /** @type {Issue[]} */
+  const issues = [];
+  const file = `cards/${card.name}`;
+  const raw = await readFile(card.file, 'utf8');
+  const offset = raw.split('\n').length - card.body.split('\n').length;
+  const add = (check, line, message, severity = 'block') =>
+    issues.push({ check, severity, file, line: line + offset, id: card.data.id, message });
+  if (!CARD_TYPES.includes(card.data.type)) return issues;
+
+  const { profile, issues: shape } = await bodyProblems(card.body, card.data.type);
+  for (const i of shape) add('M1', i.line, i.message);
+  const values = slotValues(card.body, profile);
+  for (const v of values.filter((x) => isTbd(x.value)))
+    add('M1', v.line, `a card carries no TBD: ${v.block}`);
+  for (const [c, line, m] of valueIssues(values, ctx)) add(c, line, m);
+  for (const r of provenanceOf(card.body)) {
+    const problem = recordProblem(r, ctx);
+    // A card's quotes go stale when the GDD moves on: that is a D1 for the human, not a gate.
+    if (problem) add('M9', r.line, problem, isDrift(problem) ? 'report' : 'block');
+  }
+
+  return issues;
+}
+
+/** M12: one live place per id, and no silent return from a terminal state. */
+function ledgerIssues(ledger) {
+  /** @type {Issue[]} */
+  const out = [];
+  for (const id of ledger.ids()) {
+    const { live, terminal } = ledger.where(id);
+    const file = live[0]?.file ?? 'history.md';
+    const add = (message) =>
+      out.push({ check: 'M12', severity: 'block', file, line: 1, id, message });
+    if (live.length > 1)
+      add(`${id} lives in ${live.length} places: ${live.map((p) => p.file).join(', ')}`);
+    if (live.length && terminal.length && !reopens(ledger, id)) {
+      add(
+        `${id} is ${terminal.join(' and ')} already: a live copy needs "reopens: <why>" ` +
+          '(an undone move: take its line out of history.md or graveyard.md)',
+      );
+    }
+  }
+
+  return out;
+}
+
+function reopens(ledger, id) {
+  const unit = ledger.design.flatMap((d) => d.units).find((u) => u.id === id);
+  const card = ledger.cards.find((c) => c.data.id === id);
+
+  return Boolean(unit?.header.reopens || card?.data.reopens);
+}
+
+/** M14: backlog.md is the order of the units in design/, each exactly once. */
+function backlogIssues(text, unitIds) {
+  /** @type {Issue[]} */
+  const out = [];
+  if (text === null) return out;
+  const add = (line, id, message) =>
+    out.push({ check: 'M14', severity: 'block', file: 'backlog.md', line, id, message });
+  const seen = new Set();
+  text.split('\n').forEach((l, i) => {
+    const id = l.match(/^- (\S+)/)?.[1];
+    if (!id) return;
+    if (seen.has(id)) add(i + 1, id, `${id} is listed twice`);
+    else if (!unitIds.has(id)) add(i + 1, id, `${id} is not a unit of gcf/design/`);
+    seen.add(id);
+  });
+  for (const id of unitIds)
+    if (!seen.has(id)) add(1, id, `${id} is missing from the backlog order`);
+
+  return out;
+}
+
+/** M2 over open-questions.md: every `blocks:` names a known id. */
+function questionIssues(ctx, ledger) {
+  return ctx.questions.refs.flatMap(({ qid, ids }) =>
+    ids
+      .filter((id) => !ledger.known(id))
+      .map((id) => ({
+        check: 'M2',
+        severity: 'block',
+        file: 'open-questions.md',
+        line: 1,
+        id: qid,
+        message: `${qid} blocks unknown ${id}`,
+      })),
+  );
+}
+
+/** Tallies per key: units, ready units, slot values, TBD values. */
+function tally(units, key) {
+  /** @type {Record<string, {units: number, ready: number, values: number, tbd: number}>} */
+  const out = {};
+  for (const u of units) {
+    const t = (out[u[key]] ??= { units: 0, ready: 0, values: 0, tbd: 0 });
+    t.units++;
+    t.ready += u.ready ? 1 : 0;
+    t.values += u.values;
+    t.tbd += u.tbd;
+  }
+
+  return out;
+}
+
+/** M7: which pillars the units serve, which serve none, which units serve no pillar. */
+function pillarReport(units, ctx) {
+  const refs = Object.fromEntries(ctx.pillarIds.map((p) => [p, 0]));
+  for (const u of units.filter((x) => x.pillars !== 'TBD')) {
+    for (const p of u.pillars) refs[p] = (refs[p] ?? 0) + 1;
+  }
+
+  return {
+    refs,
+    unreferenced: Object.keys(refs).filter((p) => refs[p] === 0),
+    // `pillars: TBD` is waiting for the pillars interview, not a unit without a reason.
+    without: units
+      .filter((u) => CARD_TYPES.includes(u.type) && u.pillars !== 'TBD' && !u.pillars.length)
+      .map((u) => u.id),
+  };
+}
+
+/**
+ * Run every design check over a project. `blocking` counts the issues that refuse a commit;
+ * the rest of the report (completeness, readiness, pillars) is a reading, not a gate.
+ */
+export async function designCheck(projectDir) {
+  const root = path.join(path.resolve(projectDir), 'gcf');
+  const ledger = await buildLedger(projectDir);
+  const ctx = await loadContext(root);
+  /** @type {Issue[]} */
+  const issues = [];
+  const units = [];
+  for (const u of ledger.design.flatMap((d) => d.units)) {
+    const { issues: own, values } = await checkUnit(u, ctx, ledger);
+    issues.push(...own);
+    const tbd = values.filter((v) => isTbd(v.value)).length;
+    const blockedBy = ctx.questions.d1.get(u.id) ?? [];
+    const pillars = listOf(u.header.pillars ?? '');
+    units.push({
+      id: u.id,
+      file: u.file,
+      system: u.system,
+      type: u.header.type ?? null,
+      milestone: u.header.milestone ?? 'TBD',
+      pillars,
+      values: values.length,
+      tbd,
+      blocked_by: blockedBy,
+      ready: tbd === 0 && !blockedBy.length && !own.some((i) => i.severity === 'block'),
+    });
+  }
+
+  for (const c of ledger.cards) issues.push(...(await checkCard(c, ctx)));
+  for (const doc of ['game', 'glossary']) issues.push(...(await checkDoc(root, doc, ctx)));
+  issues.push(...preambleIssues(ledger.design));
+  issues.push(...ledgerIssues(ledger), ...questionIssues(ctx, ledger));
+  if (ledger.design.length) {
+    const backlog = await readIf(path.join(root, 'backlog.md'));
+    issues.push(...backlogIssues(backlog, new Set(units.map((u) => u.id))));
+  }
+
+  return {
+    blocking: issues.filter((i) => i.severity === 'block').length,
+    issues,
+    units,
+    systems: tally(units, 'system'),
+    milestones: tally(units, 'milestone'),
+    pillars: pillarReport(units, ctx),
+  };
+}
+
+export { judged, uncovered };