synthesisui 0.16.19 → 0.16.20

package/dist/commands/doctor.js

@@ -2,6 +2,7 @@ import { readdir, readFile } from "node:fs/promises";
 import { join, relative, resolve } from "node:path";
 import { findDivergences } from "../doctor/coherence.js";
 import { findFrozenBindings } from "../doctor/frozen.js";
+import { appendEvent, readEvents, summarize } from "../doctor/ledger.js";
 import { bindingsFromDocument, countComponents, findOverrides, } from "../doctor/overrides.js";
 import { diagnose, scanSource, siblingTokens, } from "../doctor/scan.js";
 import { findSelfConflicts, forbiddenProps, isReset, propMatchesLabel, } from "../doctor/self-conflict.js";
@@ -522,6 +523,46 @@ export async function doctor(opts) {
         console.log(body(`Token coverage  ${meter(d.coverage)}  ${String(d.coverage).padStart(3)}%`));
         console.log(body(`                ${d.tokenUses} from the system, ${d.findings.length} by hand${d.phantomUses > 0 ? `, ${d.phantomUses} naming nothing` : ""}`));
     }
+    /**
+     * THE RECORD - the layer that remembers, printed where the moment is shown.
+     *
+     * A snapshot is appended only for FULL runs: a scoped run measures a corner,
+     * and a corner's coverage on the project's trend line would read as the
+     * project getting better or worse when somebody just pointed the tool at a
+     * different folder.
+     *
+     * Every line printed here is something no single run can know: whether a
+     * finding was acted on (its file checked clean afterwards - the fix is a
+     * write, so it logged itself), and which way coverage is moving. That is the
+     * question a design-system lead asks before paying for anything, and until
+     * today the honest answer was that nobody knew.
+     */
+    if (hasSystem && measurable && scopes.length === 0) {
+        await appendEvent(root, {
+            kind: "doctor",
+            at: new Date().toISOString(),
+            coverage: d.coverage,
+        });
+    }
+    if (hasSystem && scopes.length === 0) {
+        const record = summarize(await readEvents(root));
+        if (record.checks >= 2) {
+            console.log("");
+            console.log(section("The record"));
+            const acted = record.resolved > 0
+                ? ` ${record.resolved} ${record.resolved === 1 ? "was" : "were"} fixed in a later write.`
+                : "";
+            console.log(body(`${record.checks} checks logged.${acted}${record.open.length === 0 && record.resolved > 0
+                ? " Nothing is still open."
+                : ""}`));
+            for (const o of record.open.slice(0, 5)) {
+                console.log(body(`  still open: ${o.file}  (${o.named} named, ${o.phantoms} phantom)`));
+            }
+            if (record.coverage && record.coverage.from !== record.coverage.to) {
+                console.log(body(`  coverage ${record.coverage.from}% → ${record.coverage.to}% since the first run.`));
+            }
+        }
+    }
     /**
      * Its own section, above drift, because it is a worse problem wearing a
      * better disguise.

package/dist/commands/hook.js

@@ -1,5 +1,6 @@
 import { readFile, writeFile } from "node:fs/promises";
 import { join, relative, resolve } from "node:path";
+import { appendEvent } from "../doctor/ledger.js";
 import { diagnose, scanSource } from "../doctor/scan.js";
 import { loadSystem } from "./doctor.js";
 const pass = () => ({ continue: true });
@@ -57,6 +58,18 @@ async function report(root, filePath) {
     const d = diagnose([scanSource(rel, src, table)]);
     const named = d.findings.filter((f) => f.token);
     const phantoms = d.files.flatMap((f) => f.phantoms ?? []);
+    // Every check leaves one line in the ledger - INCLUDING the clean ones,
+    // because a fix is itself a write, so the clean re-check of a file that was
+    // just flagged is the evidence the agent read the report and acted. Without
+    // the clean lines the record could only ever say "found", never "fixed",
+    // which is the half we could not answer when asked (28/07).
+    await appendEvent(root, {
+        kind: "hook",
+        at: new Date().toISOString(),
+        file: rel,
+        named: named.length,
+        phantoms: phantoms.length,
+    });
     // Unnamed drift alone is deliberately NOT worth interrupting for. There is
     // no token to move to, so the only honest advice is "ask a person" - and
     // saying that after every edit trains the reader to skip the block.

package/dist/doctor/ledger.js

@@ -0,0 +1,105 @@
+import { appendFile, readFile, stat, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+/**
+ * THE LAYER THAT REMEMBERS - governance that cannot answer "is it getting
+ * better?" is a sequence of moments, not a system.
+ *
+ * The stack up to here acts and forgets. The hook checks every write and
+ * reports into the agent's context, and we had no idea whether the agent acted
+ * on it - the owner admitted exactly that, in public, to the person who asked
+ * (28/07). The doctor measures a moment and prints it. Nothing anywhere could
+ * answer the one question a design-system lead actually asks before paying for
+ * a tool: is my team's drift going up or down?
+ *
+ * THE TRICK THAT MAKES THIS CHEAP. The hook already runs on every write, and a
+ * FIX is also a write. So if every check appends one line here, the loop closes
+ * by itself: a finding at 10:02 followed by a clean check of the same file at
+ * 10:04 IS the evidence the agent read the report and acted. Nobody logs
+ * "fixed"; the fix logs itself.
+ *
+ * LOCAL BY DESIGN. One JSONL per project, inside `_synthesisui/`, next to the
+ * system it describes. Nothing leaves the machine - "we send telemetry to our
+ * server" is how a tool that installs an editor hook loses the room. Committing
+ * it is the project's choice: do, and the ledger becomes the team's shared
+ * memory; don't, and it is a personal instrument. Both are legitimate.
+ *
+ * Append-only, one JSON object per line, unknown lines skipped on read - the
+ * same contract every log file that survives a decade has.
+ */
+export const LEDGER_FILE = "ledger.jsonl";
+const ledgerPath = (root) => join(root, "_synthesisui", LEDGER_FILE);
+/** Keep the file from growing forever: past ~1MB, keep the newest half. A
+ *  trend needs recent history, not an archive. */
+const MAX_BYTES = 1_000_000;
+export async function appendEvent(root, event) {
+    const path = ledgerPath(root);
+    try {
+        await appendFile(path, `${JSON.stringify(event)}\n`, "utf8");
+        const size = (await stat(path)).size;
+        if (size > MAX_BYTES) {
+            const lines = (await readFile(path, "utf8")).split("\n").filter(Boolean);
+            await writeFile(path, `${lines.slice(Math.floor(lines.length / 2)).join("\n")}\n`, "utf8");
+        }
+    }
+    catch {
+        // The record must never cost the check. A ledger that can break the hook
+        // is a ledger that gets the hook uninstalled.
+    }
+}
+export async function readEvents(root) {
+    const raw = await readFile(ledgerPath(root), "utf8").catch(() => "");
+    if (!raw)
+        return [];
+    const out = [];
+    for (const line of raw.split("\n")) {
+        if (!line.trim())
+            continue;
+        try {
+            const e = JSON.parse(line);
+            if (e && (e.kind === "hook" || e.kind === "doctor") && e.at)
+                out.push(e);
+        }
+        catch {
+            // A corrupt line loses itself, not the file.
+        }
+    }
+    return out;
+}
+export function summarize(events) {
+    const hooks = events.filter((e) => e.kind === "hook" && e.file);
+    const byFile = new Map();
+    for (const e of hooks) {
+        const key = e.file;
+        byFile.set(key, [...(byFile.get(key) ?? []), e]);
+    }
+    let resolved = 0;
+    const open = [];
+    for (const [file, list] of byFile) {
+        let dirty = false;
+        for (const e of list) {
+            const bad = (e.named ?? 0) + (e.phantoms ?? 0) > 0;
+            if (bad && !dirty)
+                dirty = true;
+            else if (!bad && dirty) {
+                dirty = false;
+                resolved++;
+            }
+        }
+        if (dirty) {
+            const last = list[list.length - 1];
+            open.push({
+                file,
+                named: last.named ?? 0,
+                phantoms: last.phantoms ?? 0,
+            });
+        }
+    }
+    const snaps = events.filter((e) => e.kind === "doctor" && typeof e.coverage === "number");
+    const coverage = snaps.length >= 2
+        ? {
+            from: snaps[0].coverage,
+            to: snaps[snaps.length - 1].coverage,
+        }
+        : null;
+    return { checks: hooks.length, resolved, open, coverage };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "synthesisui",
-  "version": "0.16.19",
+  "version": "0.16.20",
   "description": "Bring SynthesisUI design systems into any project - tokens, typed components, whole pages and an agent-ready CLAUDE.md manifest.",
   "type": "module",
   "bin": {