@milehimikey/em 1.8.1 → 1.9.0

package/dist/cli/status.js

@@ -0,0 +1,536 @@
+// SPDX-License-Identifier: MIT
+// `em status` (MIL-163): one deterministic command that answers "what state is the system in"
+// over one or more models — the surface a reader currently has to assemble by hand from the
+// README's Slices table, a conformance report, and `.event-modeling.md`. Pure aggregation over
+// exports the rest of `em` already computes; nothing here re-derives a fact another module owns:
+//
+//  - lifecycle status / driftSignal come from the same doc join `em export`/`em coverage` use
+//    (catalog/docJoin.ts's resolveSliceDocJoin, catalog/driftSignal.ts's classification).
+//  - open Open Questions counts come from the same slice-doc parse `em coverage`'s scope check
+//    already reads (catalog/sliceDoc.ts's openQuestionsTotal/openQuestionsUnchecked).
+//  - invariant coverage totals come from `em coverage`'s own report builder (./coverage.ts),
+//    summed across every input model rather than re-implemented.
+//  - last-conformance + commits-behind-HEAD reuses stateFile.ts's parser and the same injectable
+//    GitRunner convention conform-scope.ts/diff-inputs.ts use, so every git failure branch stays
+//    unit-testable without a real repository.
+//  - slice-PRs-behind-HEAD (MIL-164) reuses conform-scope.ts's own machinery outright —
+//    `changedPathsSince` + `buildConformScope` — rather than re-deriving the
+//    implementedIn-to-changed-path match rule a second time. The standalone surface for this
+//    freshness clause alone (no full model rollup needed) is `em freshness` (freshness.ts).
+//
+// Deterministic core: no LLM calls, no wall-clock timestamps in the output, byte-stable for the
+// same inputs. Text/markdown/badge are formatting layers over one aggregated StatusReport; the
+// JSON document (emit/statusJson.ts) is a versioned envelope around the exact same object.
+import { basename, dirname, resolve } from "node:path";
+import { resolveSliceDocJoin } from "../catalog/docJoin.js";
+import { readSliceDoc } from "../catalog/readSliceDoc.js";
+import { realGit } from "./diff-inputs.js";
+import { loadStateFile, parseState } from "./stateFile.js";
+import { changedPathsSince, buildConformScope } from "./conformScope.js";
+/** The 4 canonical slice-doc lifecycle statuses (docs/slice-doc-schema.md) — the same enum
+ *  `em catalog`'s header coloring and `em render`'s status legend already recognize. */
+export const CANONICAL_STATUSES = ["draft", "reviewed", "ready-to-implement", "implemented"];
+export function classifyStatusBucket(found, reason, status) {
+    if (!found)
+        return "no-doc";
+    if (reason === "frontmatter-invalid")
+        return "frontmatter-invalid";
+    if (status !== null && CANONICAL_STATUSES.includes(status))
+        return status;
+    return "unknown";
+}
+/**
+ * Resolve every slice's status-rollup facts for one already-compiled model. `baseDir` is the
+ * `.em` file's directory, same doc-resolution convention every other doc-aware command uses.
+ * Open Questions counts are read from the slice's OWN bound doc (re-deriving the key from
+ * `doc.path`, not assuming it's this slice's own — MIL-121 cross-binding can resolve to a
+ * different slice's doc, same re-derivation `em coverage`/`--slice-ready` use) rather than a
+ * second independent parse.
+ */
+export function resolveSliceStatusFacts(file, model, refs, baseDir) {
+    const diagnostics = [];
+    const facts = model.slices.map((slice, i) => {
+        const key = refs.sliceKeys[i];
+        const { doc, diagnostics: docDiags } = resolveSliceDocJoin(slice, key, baseDir, (id) => refs.refById.get(id));
+        diagnostics.push(...docDiags);
+        let docPath = null;
+        let openQuestionsTotal = 0;
+        let openQuestionsUnchecked = 0;
+        if (doc.found) {
+            const boundKey = doc.path.replace(/^slices\//, "").replace(/\.md$/, "");
+            docPath = resolve(baseDir, doc.path);
+            const parsed = readSliceDoc(baseDir, boundKey);
+            if (parsed) {
+                openQuestionsTotal = parsed.openQuestionsTotal;
+                openQuestionsUnchecked = parsed.openQuestionsUnchecked;
+            }
+        }
+        return {
+            file,
+            key,
+            docFound: doc.found,
+            docReason: doc.reason,
+            docPath,
+            rawStatus: doc.status,
+            implementedIn: doc.implementedIn,
+            owner: doc.owner,
+            bucket: classifyStatusBucket(doc.found, doc.reason, doc.status),
+            driftSignal: doc.driftSignal,
+            openQuestionsTotal,
+            openQuestionsUnchecked,
+        };
+    });
+    return { facts, diagnostics };
+}
+/** Open `issue "text"` markers in a model — the same predicate `em validate --list-issues`
+ *  counts, here reduced to a bare count for the rollup. */
+export function countOpenIssues(model) {
+    return model.elements.filter((el) => el.issue).length;
+}
+/**
+ * `git rev-list --count <revision>..HEAD` in `repo` (any directory inside it, not necessarily
+ * its root — same "anchor dir, resolve toplevel" convention `conformScope.ts`'s
+ * `changedPathsSince` uses). The git runner is injectable so every failure branch is
+ * unit-testable without a real repository.
+ */
+export function commitsBehindHead(repo, revision, runGit = realGit) {
+    const toplevel = runGit(["-C", repo, "rev-parse", "--show-toplevel"]);
+    if (toplevel.status !== 0) {
+        return { ok: false, message: `em status: ${repo} is not a git repository` };
+    }
+    const repoRoot = toplevel.stdout.trim();
+    const result = runGit(["-C", repoRoot, "rev-list", "--count", `${revision}..HEAD`]);
+    if (result.status !== 0) {
+        return {
+            ok: false,
+            message: `em status: git rev-list failed: ${(result.stderr || "").trim() || `unknown revision "${revision}"`}`,
+        };
+    }
+    const count = parseInt(result.stdout.trim(), 10);
+    if (Number.isNaN(count)) {
+        return { ok: false, message: `em status: unexpected git rev-list output for revision "${revision}"` };
+    }
+    return { ok: true, count };
+}
+/**
+ * `M` in "N commits and M slice-PRs behind HEAD" (MIL-164) — how many slices whose doc's
+ * `implementedIn:` names a path this model's target repo changed since `revision`. Reuses the
+ * exact `em conform-scope` machinery for one model at a time: `changedPathsSince` (the same
+ * `git diff --name-only <revision>..HEAD` walk, same injectable `GitRunner`) to get the changed
+ * paths, then `buildConformScope`'s own `implementedIn`-prefix matching (never fuzzy, never a
+ * second guess) to turn them into a candidate-slice count. `full` is always `false` here — this
+ * is only ever called once `lastConformance` is known non-null (see `resolveConformanceEntry`
+ * below), so there is always a revision to diff against.
+ */
+export function resolveSlicePRsBehindHead(repo, revision, slices, runGit = realGit) {
+    const changed = changedPathsSince(repo, revision, runGit);
+    if (!changed.ok)
+        return { ok: false, message: changed.message };
+    // `date`/`report` are irrelevant to matching (buildConformScope only echoes them back in its
+    // own `lastConformance` field, which this function discards) — only `revision` drives the
+    // implementedIn-to-changed-path match below.
+    const scope = buildConformScope(slices, { date: "", revision, report: "" }, changed.paths, false);
+    return { ok: true, count: scope.candidateSlices.length };
+}
+/**
+ * Resolve one model's conformance entry: read its sibling state file (if any — not every model
+ * has reached the `conform` phase, so a missing state file is routine, not an error), then
+ * compute commits-behind-HEAD and slice-PRs-behind-HEAD (MIL-164) when `Last conformance:` is
+ * set. `repoOverride` is `--repo`; omitted, each model's own directory is used as the repo to
+ * walk (the common single-repo project case — see `repo` field doc above). `sliceDocFacts` is
+ * THIS model's own slice facts (`key`/`status`/`implementedIn`) — the caller's responsibility to
+ * scope correctly per file, since `resolveSlicePRsBehindHead` matches against exactly this
+ * model's slices, not some other input model's.
+ *
+ * A state file is shared by every `.em` file in its directory (`.event-modeling.md` has no
+ * per-model namespacing), but its `Model file:` bullet names exactly ONE of them — so a sibling
+ * file it does NOT describe (the common case: a `conform-scope --seed-asis` scratch copy like
+ * `checkout-asis.em` sitting next to `checkout.em`) must not inherit `checkout.em`'s conformance
+ * record just because it lives in the same directory. When `Model file:` is set and doesn't match
+ * `basename(file)`, the record is reported as unattributed (via `error`, the same non-fatal
+ * channel a git failure uses) rather than silently misattributed.
+ */
+export function resolveConformanceEntry(file, repoOverride, sliceDocFacts, runGit = realGit) {
+    const modelDir = dirname(file);
+    const repo = repoOverride ?? modelDir;
+    const loaded = loadStateFile(modelDir);
+    if (!loaded.ok) {
+        return { file, modelDir, hasStateFile: false, lastConformance: null, repo, commitsBehindHead: null, slicePRsBehindHead: null, error: null };
+    }
+    const parsed = parseState(loaded.text);
+    if (!parsed.ok) {
+        return {
+            file,
+            modelDir,
+            hasStateFile: true,
+            lastConformance: null,
+            repo,
+            commitsBehindHead: null,
+            slicePRsBehindHead: null,
+            error: `state file: ${parsed.message}`,
+        };
+    }
+    if (parsed.state.modelPath && parsed.state.modelPath !== basename(file)) {
+        return {
+            file,
+            modelDir,
+            hasStateFile: true,
+            lastConformance: null,
+            repo,
+            commitsBehindHead: null,
+            slicePRsBehindHead: null,
+            error: `state file describes "${parsed.state.modelPath}", not "${basename(file)}" — not attributing its conformance record`,
+        };
+    }
+    if (!parsed.state.lastConformance) {
+        return { file, modelDir, hasStateFile: true, lastConformance: null, repo, commitsBehindHead: null, slicePRsBehindHead: null, error: null };
+    }
+    const { date, revision } = parsed.state.lastConformance;
+    const commitsResult = commitsBehindHead(repo, revision, runGit);
+    if (!commitsResult.ok) {
+        return {
+            file,
+            modelDir,
+            hasStateFile: true,
+            lastConformance: { date, revision },
+            repo,
+            commitsBehindHead: null,
+            slicePRsBehindHead: null,
+            error: commitsResult.message,
+        };
+    }
+    const slicePRsResult = resolveSlicePRsBehindHead(repo, revision, sliceDocFacts, runGit);
+    if (!slicePRsResult.ok) {
+        return {
+            file,
+            modelDir,
+            hasStateFile: true,
+            lastConformance: { date, revision },
+            repo,
+            commitsBehindHead: commitsResult.count,
+            slicePRsBehindHead: null,
+            error: slicePRsResult.message,
+        };
+    }
+    return {
+        file,
+        modelDir,
+        hasStateFile: true,
+        lastConformance: { date, revision },
+        repo,
+        commitsBehindHead: commitsResult.count,
+        slicePRsBehindHead: slicePRsResult.count,
+        error: null,
+    };
+}
+/** Aggregate everything `em status` reports into one `StatusReport` — pure, no I/O. Callers
+ *  (the CLI action, the MCP tool) resolve every input first (compile each model, join every
+ *  slice's doc, scan the test tree once, resolve conformance) and hand the results here. */
+export function buildStatusReport(files, sliceFacts, openIssuesCount, invariants, conformance, diagnostics) {
+    const byStatus = { draft: 0, reviewed: 0, readyToImplement: 0, implemented: 0, noDoc: 0, frontmatterInvalid: 0, unknown: 0 };
+    const drift = {
+        inSync: 0,
+        neverImplemented: 0,
+        unpropagatedDelta: 0,
+        implementedWithoutLink: 0,
+        notApplicable: 0,
+        frontmatterInvalid: 0,
+    };
+    let openQuestionsTotal = 0;
+    let openQuestionsUnchecked = 0;
+    // MIL-121 `covers:` cross-binding lets several slices resolve to the SAME doc file — a doc's
+    // own Open Questions belong to the doc, not to each slice covered by it, so a shared doc is
+    // only counted once regardless of how many slices are bound to it (keyed by resolved absolute
+    // path, since two different input models' `slices/` dirs could otherwise collide on the same
+    // relative path string without actually being the same file).
+    const countedDocPaths = new Set();
+    for (const f of sliceFacts) {
+        switch (f.bucket) {
+            case "draft":
+                byStatus.draft++;
+                break;
+            case "reviewed":
+                byStatus.reviewed++;
+                break;
+            case "ready-to-implement":
+                byStatus.readyToImplement++;
+                break;
+            case "implemented":
+                byStatus.implemented++;
+                break;
+            case "no-doc":
+                byStatus.noDoc++;
+                break;
+            case "frontmatter-invalid":
+                byStatus.frontmatterInvalid++;
+                break;
+            case "unknown":
+                byStatus.unknown++;
+                break;
+        }
+        switch (f.driftSignal) {
+            case "in-sync":
+                drift.inSync++;
+                break;
+            case "never-implemented":
+                drift.neverImplemented++;
+                break;
+            case "unpropagated-delta":
+                drift.unpropagatedDelta++;
+                break;
+            case "implemented-without-link":
+                drift.implementedWithoutLink++;
+                break;
+            case null:
+                if (f.docReason === "frontmatter-invalid")
+                    drift.frontmatterInvalid++;
+                else
+                    drift.notApplicable++;
+                break;
+        }
+        const alreadyCounted = f.docPath !== null && countedDocPaths.has(f.docPath);
+        if (f.docPath !== null)
+            countedDocPaths.add(f.docPath);
+        if (!alreadyCounted) {
+            openQuestionsTotal += f.openQuestionsTotal;
+            openQuestionsUnchecked += f.openQuestionsUnchecked;
+        }
+    }
+    return {
+        files,
+        slices: { total: sliceFacts.length, byStatus },
+        driftSignal: drift,
+        invariants,
+        issues: { openIssues: openIssuesCount, openQuestionsTotal, openQuestionsUnchecked },
+        conformance,
+        diagnostics,
+        owners: sliceFacts.map((f) => ({ file: f.file, key: f.key, owner: f.owner })),
+    };
+}
+/** Sum per-model `CoverageReport`s (see `./coverage.ts`) into one `StatusInvariantTotals` —
+ *  `em status` doesn't need the per-slice/per-ID detail `em coverage --json` carries, just the
+ *  totals, across however many models `--tests <dir>` was scanned against. */
+export function aggregateInvariantTotals(testsDir, reports) {
+    let total = 0;
+    let uncovered = 0;
+    for (const r of reports) {
+        total += r.totalInvariants;
+        uncovered += r.uncoveredCount;
+    }
+    return { testsDir, total, cited: total - uncovered, uncovered };
+}
+// ---- Text / markdown / badge formatting ----
+function pluralize(n, word) {
+    return `${n} ${word}${n === 1 ? "" : "s"}`;
+}
+/** "N commits and M slice-PRs behind HEAD" (MIL-164's freshness clause), handling either count
+ *  being independently unknown — defensive against a hand-built `ConformanceEntry` (tests) even
+ *  though on the real `resolveConformanceEntry` path the two counts are only ever null together
+ *  (both fail whenever `error` is set, which callers check first — see that function's doc). */
+function formatBehindHead(entry) {
+    const commits = entry.commitsBehindHead;
+    const slicePRs = entry.slicePRsBehindHead;
+    if (commits === null && slicePRs === null)
+        return "commits and slice-PRs behind HEAD unknown";
+    if (commits === null)
+        return `commits behind HEAD unknown, ${pluralize(slicePRs, "slice-PR")} behind HEAD`;
+    if (slicePRs === null)
+        return `${pluralize(commits, "commit")} behind HEAD, slice-PRs behind HEAD unknown`;
+    return `${pluralize(commits, "commit")} and ${pluralize(slicePRs, "slice-PR")} behind HEAD`;
+}
+/** Exported for `em freshness` (freshness.ts, MIL-164) — the standalone surface for exactly
+ *  this one clause, without pulling in the rest of `em status`'s rollup. */
+export function formatConformancePart(entry) {
+    if (entry.error)
+        return `conformance unknown (${entry.error})`;
+    if (!entry.hasStateFile)
+        return "no state file";
+    if (!entry.lastConformance)
+        return "never conformed";
+    return `last conformed ${entry.lastConformance.revision} — ${formatBehindHead(entry)}`;
+}
+/** Same facts as `formatConformancePart`, without the leading "last conformed"/"conformance
+ *  unknown" prose — for a markdown table cell that already carries a "Last conformed" row
+ *  label, so the value itself shouldn't repeat it. */
+function formatConformanceValue(entry) {
+    if (entry.error)
+        return `unknown (${entry.error})`;
+    if (!entry.hasStateFile)
+        return "no state file";
+    if (!entry.lastConformance)
+        return "never conformed";
+    return `\`${entry.lastConformance.revision}\` — ${formatBehindHead(entry)}`;
+}
+/** The one-line rollup: `"8/8 implemented · 20/20 invariants covered · 0 open issues · last
+ *  conformed <rev>, N commits behind HEAD"` (MIL-163's acceptance line). For multiple input
+ *  models, the conformance clause reports the FIRST file's entry — a single-file invocation is
+ *  the common case this line is written for; the full per-model breakdown is always in
+ *  `formatStatusDetail`/the JSON document regardless of file count. */
+export function formatStatusSummary(report) {
+    const { implemented } = report.slices.byStatus;
+    const total = report.slices.total;
+    const invPart = report.invariants
+        ? `${report.invariants.cited}/${report.invariants.total} invariants covered`
+        : "invariants not checked (pass --tests <dir>)";
+    const issuesPart = pluralize(report.issues.openIssues, "open issue");
+    const oqPart = report.issues.openQuestionsUnchecked > 0 ? `, ${pluralize(report.issues.openQuestionsUnchecked, "unchecked open question")}` : "";
+    const conformancePart = formatConformancePart(report.conformance[0]);
+    return `${implemented}/${total} implemented · ${invPart} · ${issuesPart}${oqPart} · ${conformancePart}`;
+}
+/** The detail block below the summary line: one line per rollup dimension, plus one line per
+ *  model's conformance entry. */
+export function formatStatusDetail(report) {
+    const { byStatus } = report.slices;
+    const lines = [];
+    lines.push(`slices: ${report.slices.total} total — ${byStatus.implemented} implemented, ${byStatus.readyToImplement} ready-to-implement, ` +
+        `${byStatus.reviewed} reviewed, ${byStatus.draft} draft, ${byStatus.noDoc} no doc, ${byStatus.frontmatterInvalid} frontmatter invalid, ` +
+        `${byStatus.unknown} unknown status`);
+    const d = report.driftSignal;
+    lines.push(`driftSignal: ${d.inSync} in-sync, ${d.neverImplemented} never-implemented, ${d.unpropagatedDelta} unpropagated-delta, ` +
+        `${d.implementedWithoutLink} implemented-without-link, ${d.notApplicable} n/a (no doc), ${d.frontmatterInvalid} n/a (frontmatter invalid)`);
+    lines.push(report.invariants
+        ? `invariants: ${report.invariants.cited}/${report.invariants.total} covered (${report.invariants.uncovered} uncovered) — ${report.invariants.testsDir}`
+        : "invariants: not checked — pass --tests <dir> to enable");
+    lines.push(`issues: ${pluralize(report.issues.openIssues, "open issue")}, ` +
+        `${report.issues.openQuestionsUnchecked}/${report.issues.openQuestionsTotal} open question(s) unchecked`);
+    const multi = report.conformance.length > 1;
+    for (const entry of report.conformance) {
+        const label = multi ? `conformance (${entry.file}): ` : "conformance: ";
+        lines.push(`${label}${formatConformancePart(entry)}`);
+    }
+    if (report.diagnostics.length > 0) {
+        lines.push(`doc issues: ${pluralize(report.diagnostics.length, "warning")} — see diagnostics (${report.diagnostics.map((d) => d.code).join(", ")})`);
+    }
+    return lines.join("\n");
+}
+/** Full text report: the summary line, a blank line, then the detail block — same
+ *  "rollup line, then detail" shape `em diff`'s text report uses. */
+export function formatStatusText(report) {
+    return `${formatStatusSummary(report)}\n\n${formatStatusDetail(report)}`;
+}
+/** Escape characters that would break a markdown table cell: `|` (the column separator) and
+ *  newlines — plus backslashes, escaped FIRST. Escaping `|` alone would let a pre-existing `\`
+ *  in the source text (a Windows path in `entry.file`, or free text inside a conformance
+ *  `error` string) combine with the newly-inserted `\` (e.g. a literal `\|`) and un-escape the
+ *  pipe again once Markdown unescapes the backslash sequence — a CodeQL
+ *  `js/incomplete-sanitization` finding (PR #116 review). Same convention `em slice index`'s
+ *  own `escapeCell` (sliceIndex.ts) already uses for exactly this reason. Applied to both the
+ *  key and value columns: the multi-model `Last conformed (${entry.file})` row embeds
+ *  `entry.file`, which is CLI-argument/glob-controlled, not just the value column. */
+function escapeCell(s) {
+    return s.replace(/\\/g, "\\\\").replace(/\|/g, "\\|").replace(/\r?\n/g, " ");
+}
+/** A markdown block suited for pasting into a README (MIL-163's `--md`) — a small table,
+ *  same spirit as `em slice index`'s GENERATED Slices table, but not marker-managed: `--md`
+ *  just prints the block, leaving where/whether to embed it to the caller. */
+export function formatStatusMarkdown(report) {
+    const { byStatus } = report.slices;
+    const rows = [
+        ["Slices", `${byStatus.implemented}/${report.slices.total} implemented (${byStatus.readyToImplement} ready-to-implement, ${byStatus.reviewed} reviewed, ${byStatus.draft} draft)`],
+        ["Invariants", report.invariants ? `${report.invariants.cited}/${report.invariants.total} covered` : "not checked"],
+        ["Open issues", `${report.issues.openIssues}`],
+        ["Open questions", `${report.issues.openQuestionsUnchecked} unchecked`],
+    ];
+    if (report.conformance.length <= 1) {
+        const entry = report.conformance[0];
+        rows.push(["Last conformed", formatConformanceValue(entry)]);
+    }
+    else {
+        for (const entry of report.conformance) {
+            rows.push([`Last conformed (${entry.file})`, formatConformanceValue(entry)]);
+        }
+    }
+    const header = "| Metric | Value |\n|---|---|";
+    const body = rows.map(([k, v]) => `| ${escapeCell(k)} | ${escapeCell(v)} |`).join("\n");
+    return `${header}\n${body}`;
+}
+// ---- SVG badge ----
+function escapeXml(s) {
+    return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+}
+/** Deterministic, dependency-free text-width estimate for a shields.io-style flat badge: a
+ *  fixed average character advance (no font metrics table, no rendering) so the same message
+ *  always measures to the same width — good enough for a legible badge, not a claim of
+ *  pixel-perfect parity with shields.io's own Verdana metrics. */
+function textWidth(s) {
+    return Math.ceil(s.length * 6.5) + 10;
+}
+/** Render one flat-style SVG badge — two colored rects (label, message) plus centered text,
+ *  no external fonts/images/scripts, so it renders identically anywhere an SVG does. */
+export function renderBadgeSvg(label, message, color) {
+    const labelWidth = textWidth(label);
+    const messageWidth = textWidth(message);
+    const totalWidth = labelWidth + messageWidth;
+    const labelX = labelWidth / 2;
+    const messageX = labelWidth + messageWidth / 2;
+    const ariaLabel = escapeXml(`${label}: ${message}`);
+    return (`<svg xmlns="http://www.w3.org/2000/svg" width="${totalWidth}" height="20" role="img" aria-label="${ariaLabel}">\n` +
+        `  <title>${ariaLabel}</title>\n` +
+        `  <linearGradient id="s" x2="0" y2="100%">\n` +
+        `    <stop offset="0" stop-color="#bbb" stop-opacity=".1"/>\n` +
+        `    <stop offset="1" stop-opacity=".1"/>\n` +
+        `  </linearGradient>\n` +
+        `  <clipPath id="r">\n` +
+        `    <rect width="${totalWidth}" height="20" rx="3" fill="#fff"/>\n` +
+        `  </clipPath>\n` +
+        `  <g clip-path="url(#r)">\n` +
+        `    <rect width="${labelWidth}" height="20" fill="#555"/>\n` +
+        `    <rect x="${labelWidth}" width="${messageWidth}" height="20" fill="${color}"/>\n` +
+        `    <rect width="${totalWidth}" height="20" fill="url(#s)"/>\n` +
+        `  </g>\n` +
+        `  <g fill="#fff" text-anchor="middle" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" font-size="11">\n` +
+        `    <text x="${labelX}" y="14">${escapeXml(label)}</text>\n` +
+        `    <text x="${messageX}" y="14">${escapeXml(message)}</text>\n` +
+        `  </g>\n` +
+        `</svg>`);
+}
+/** Badge message: a compact version of the summary line's first two/three clauses — a
+ *  badge has no room for the full conformance clause. */
+function badgeMessage(report) {
+    const { implemented } = report.slices.byStatus;
+    const total = report.slices.total;
+    const parts = [`${implemented}/${total} implemented`];
+    if (report.invariants)
+        parts.push(`${report.invariants.cited}/${report.invariants.total} invariants`);
+    parts.push(pluralize(report.issues.openIssues, "issue"));
+    return parts.join(" · ");
+}
+/** Badge color contract (documented here AND in docs/cli.md — keep both in sync):
+ *
+ *  - **red** `#e05d44` — a genuine problem: an open issue, an uncovered invariant, a
+ *    `frontmatter-invalid` doc, or `implemented-without-link` drift (a doc claiming
+ *    `implemented` with nothing linking to it).
+ *  - **yellow** `#dfb317` — things are merely in flight, OR conformance couldn't be verified:
+ *    not every slice implemented yet, an unchecked Open Question, any model with
+ *    `commitsBehindHead > 0` or `slicePRsBehindHead > 0` (MIL-164), or — MIL-163 review — any
+ *    conformance entry carrying a non-null `error` (an unresolvable revision, an unparseable
+ *    state file, a `--repo` that isn't a git repo, or a state file describing a different
+ *    model). An unverifiable conformance state must never be indistinguishable from a verified,
+ *    current one — `commitsBehindHead: null`/`slicePRsBehindHead: null` from an `error` is NOT
+ *    the same fact as "0 behind", so neither can be allowed to coalesce to 0 and read as healthy.
+ *  - **green** `#4c1` — otherwise. Deliberately NOT keyed on "every slice implemented" alone —
+ *    most projects spend most of their life not fully implemented, and that's not a problem a
+ *    badge should flag. A model with NO conformance history yet (`hasStateFile: false`, or
+ *    `Last conformance: never` — both `error: null`) is a legitimate, unremarkable state too
+ *    ("hasn't reached the conform phase", not "broken") and stays eligible for green — only an
+ *    actual `error` demotes a conformance entry out of green.
+ */
+function badgeColor(report) {
+    const hasProblem = report.issues.openIssues > 0 ||
+        (report.invariants !== null && report.invariants.uncovered > 0) ||
+        report.driftSignal.implementedWithoutLink > 0 ||
+        report.driftSignal.frontmatterInvalid > 0;
+    if (hasProblem)
+        return "#e05d44"; // red
+    const inFlight = report.slices.byStatus.implemented < report.slices.total ||
+        report.issues.openQuestionsUnchecked > 0 ||
+        report.conformance.some((c) => (c.commitsBehindHead ?? 0) > 0 || (c.slicePRsBehindHead ?? 0) > 0 || c.error !== null);
+    if (inFlight)
+        return "#dfb317"; // yellow
+    return "#4c1"; // green
+}
+/** Build the `em status --badge` SVG document. */
+export function buildStatusBadge(report) {
+    return renderBadgeSvg("em status", badgeMessage(report), badgeColor(report));
+}
+//# sourceMappingURL=status.js.map

package/dist/cli/status.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"status.js","sourceRoot":"","sources":["../../src/cli/status.ts"],"names":[],"mappings":"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"}

package/dist/cli/usageLog.d.ts

@@ -0,0 +1,75 @@
+import { PatchResult } from "./stateFile.js";
+/** The Usage log's phase vocabulary (docs/usage-data.md#what-s-captured-and-where): the state
+ *  file's own `Current phase:` enum (`stateFile.ts`'s `PHASES`) plus `watch` — a live-viewing
+ *  activity a session can touch without ever being a `Current phase:` value itself (see
+ *  `stateFile.ts`'s own comment on why `watch` is deliberately excluded there). Order here is
+ *  the canonical sort order `log-usage` writes phases in, matching docs/usage-data.md's own
+ *  listing order. */
+export declare const USAGE_PHASES: readonly ["discover", "extract", "model", "slice", "implement", "conform", "review", "validate", "watch"];
+export type UsagePhase = (typeof USAGE_PHASES)[number];
+export declare function isUsagePhase(value: string): value is UsagePhase;
+/** Dedupe and sort a `--phases` list into `USAGE_PHASES`' own canonical order (matching
+ *  docs/usage-data.md's own listing order) rather than input order or alphabetical — so two
+ *  sessions naming the same phases in a different order always log an identical line. */
+export declare function sortUsagePhases(phases: readonly string[]): string[];
+/** Format one Usage log bullet line — the ONE place this exact shape is generated, so
+ *  `log-usage`'s writer and any future caller never drift from `usage-report`'s parser. */
+export declare function formatUsageLogLine(date: string, phases: readonly string[], categories: readonly string[]): string;
+/**
+ * Append one Usage log bullet to `text`'s "## Usage log" section — after whatever's already
+ * there (the guidance comment, and/or prior bullets), never editing or reordering existing
+ * content. `phases`/`categories` are trusted already-deduped, already-sorted, non-empty arrays
+ * (the CLI layer owns that — see `sortByCanonicalOrder`/dedup below); `categories` is `["none"]`
+ * when nothing fired. Fails (without writing anything) if the file has no "## Usage log"
+ * heading at all — same "refuse rather than guess where it goes" discipline
+ * `stateFile.ts`'s `applyBulletUpdates` uses for a missing mechanical bullet.
+ */
+export declare function appendUsageLogEntry(text: string, date: string, phases: readonly string[], categories: readonly string[]): PatchResult;
+/** One canonically-formatted Usage log entry, parsed back into its two fields. */
+export interface UsageLogEntry {
+    date: string;
+    phases: string[];
+    categories: string[];
+}
+/**
+ * Parse every `- YYYY-MM-DD: phases: ... — validate: ...` bullet out of `text`'s "## Usage log"
+ * section. A line that starts with `- ` inside the section but doesn't match the canonical shape
+ * (hand-edited, or written before `log-usage` existed) is returned in `malformed` verbatim
+ * rather than silently skipped or force-fit — `usage-report` surfaces these so a stale/foreign
+ * format is visible, not invisibly under-counted. Lines that are just the guidance comment (or
+ * blank) are ignored entirely — only an actual `- ` bullet attempt counts as malformed.
+ */
+export declare function parseUsageLogSection(text: string): {
+    entries: UsageLogEntry[];
+    malformed: string[];
+};
+/** Every `.event-modeling.md` under `root`, recursively, as paths relative to `root` — sorted,
+ *  POSIX forward slashes (see `walkDir`). Prunes VCS/dependency directories a repo-wide sweep
+ *  should never descend into. */
+export declare function findStateFiles(root: string): string[];
+export interface CountEntry {
+    key: string;
+    count: number;
+}
+export interface UsageReport {
+    root: string;
+    files: string[];
+    sessions: number;
+    phaseCounts: CountEntry[];
+    /** Excludes `"none"` — same as docs/usage-data.md's own aggregation recipe (`grep -v
+     *  '^none$'`): a session with nothing to report isn't a category worth tallying. */
+    categoryCounts: CountEntry[];
+    unparseableLines: Array<{
+        file: string;
+        line: string;
+    }>;
+}
+/** Aggregate every input file's Usage log into one report — pure, no I/O; the CLI layer resolves
+ *  `entries` first (`findStateFiles` + a plain read per file). `root` is carried through only
+ *  for the report's own labeling, never used to re-derive `files`. */
+export declare function aggregateUsageReport(root: string, entries: Array<{
+    file: string;
+    text: string;
+}>): UsageReport;
+/** Text report: a one-line summary, then a phase tally and a category tally, each empty-aware. */
+export declare function formatUsageReportText(report: UsageReport): string;