synthesisui 0.16.18 → 0.16.20

package/dist/commands/doctor.js

@@ -1,6 +1,8 @@
 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";
@@ -521,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.
@@ -633,6 +675,32 @@ export async function doctor(opts) {
         say(body("Whoever wrote the law and whoever wrote the recipe disagree."));
         say(body("Until they do not, no code here can be correct."));
     }
+    /**
+     * THE FAILURE THAT SURVIVES A PERFECT SCORE.
+     *
+     * Coverage asks whether the vocabulary was used. It cannot ask whether the
+     * system says ONE thing, because every component here can reference the right
+     * token and still answer the same question differently. Measured on 28/07 in
+     * a system this tool had just graded 100%: the input shows focus by moving its
+     * border, the button by drawing an outline.
+     *
+     * Reported quietly and only against a clear house style. Hover is legitimately
+     * different per component, and a checker that flagged variety would be
+     * uninstalled the same day it shipped.
+     */
+    const divergences = findDivergences(documents);
+    if (divergences.length > 0) {
+        say(section("The system answers the same question two ways"));
+        for (const d of divergences) {
+            say(body(`${d.concern}: ${d.houseCount} components use ${d.house.join(" + ")}.`));
+            for (const o of d.outliers) {
+                say(`      ${o.component} uses ${o.props.join(" + ")} instead`);
+            }
+            say("");
+        }
+        say(body("Every one of these uses your tokens, so coverage says nothing"));
+        say(body("about them. A person meets the difference on screen."));
+    }
     // The other way a system fails itself: a recipe that names a SHELF where the
     // system has a ROLE. The value is legitimate, the reference resolves, the CSS
     // compiles - and the binding sits still while everything around it flips.

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/coherence.js

@@ -0,0 +1,117 @@
+/**
+ * DOES THE SYSTEM AGREE WITH ITSELF?
+ *
+ * Token coverage answers a different question than everybody assumes. It asks
+ * whether the vocabulary was used. It cannot ask whether the system says one
+ * thing, because every component can reference the correct token and still
+ * express the same idea in a different way.
+ *
+ * Measured on 28/07, in a system this tool had just graded at 100%: the input
+ * shows focus by moving its border, the button by drawing an outline. Same
+ * token, same toolbar, two answers to one question. Every deterministic
+ * assertion we had passed, and a person looking at the screen sees a system
+ * that has not decided what focus looks like.
+ *
+ * WHY IT LIVES IN CODE AND NOT IN THE DESIGN TOOL. A designer in the Design
+ * Systems Slack built a lint plugin that does this inside Figma. Asked whether
+ * it can compare across components rather than one at a time: "it can check one
+ * at a time or all, but this crashes figma most of the time". A plugin walks a
+ * document graph inside a sandbox; this reads recipes off disk, and the whole
+ * catalogue costs a few milliseconds. The check is feasible on this side and not
+ * on that one.
+ *
+ * WHAT MAKES IT HONEST RATHER THAN NOISY. Variety is not drift. Hover is
+ * legitimately different per component - a row tints, a link recolours, a chip
+ * moves its border - and a checker that flagged all of it would be uninstalled
+ * the same day. So it reports a MINORITY against a DOMINANT majority and says
+ * nothing at all when the catalogue has no majority to disagree with.
+ *
+ * Measured against the shipped catalogue, that rule reports the two real ones
+ * and neither of the false ones:
+ *
+ *   focus       9 use outline, 3 use border-color   → reported (75% dominant)
+ *   disabled   12 dim and change the cursor, 1 only dims → reported (92%)
+ *   hover       5 shapes across 11, none dominant  → silent
+ *   active      1 and 1                            → silent
+ */
+/**
+ * State names that answer the SAME question, folded together.
+ *
+ * Without this the check finds nothing here, because each name is unanimous on
+ * its own: `focusVisible` is nine-for-nine outline, `focus` is three-for-three
+ * border. The disagreement only exists once you know they are the same concern,
+ * which is exactly why it survived every per-name check anyone could write.
+ */
+const CONCERNS = {
+    focus: "focus",
+    focusvisible: "focus",
+    focuswithin: "focus",
+    active: "pressed",
+    pressed: "pressed",
+    checked: "selected",
+    selected: "selected",
+    disabled: "disabled",
+    hover: "hover",
+};
+/** Below this share, the catalogue has no house style to disagree with, and
+ *  every "outlier" is just the variety the concern is supposed to have. */
+const DOMINANT = 0.7;
+function collect(documents) {
+    const byConcern = new Map();
+    const visit = (label, node) => {
+        for (const [state, block] of Object.entries(node.states ?? {})) {
+            const concern = CONCERNS[state.toLowerCase()];
+            // An unrecognised state is not folded into anything. Guessing that two
+            // names mean the same thing is how a checker starts inventing findings.
+            if (!concern)
+                continue;
+            const props = Object.keys(block ?? {}).sort();
+            if (props.length === 0)
+                continue;
+            const list = byConcern.get(concern) ?? [];
+            list.push({ component: label, props });
+            byConcern.set(concern, list);
+        }
+    };
+    for (const raw of documents) {
+        const doc = raw;
+        for (const [name, recipe] of Object.entries(doc.components ?? {})) {
+            visit(name, recipe);
+            for (const [part, block] of Object.entries(recipe.parts ?? {})) {
+                visit(`${name}.${part}`, block);
+            }
+        }
+    }
+    return byConcern;
+}
+/** Every concern the system answers more than one way, with a clear majority. */
+export function findDivergences(documents) {
+    const out = [];
+    for (const [concern, entries] of collect(documents)) {
+        // One component cannot disagree with itself, and two cannot form a house
+        // style - the smallest catalogue this can speak about is three.
+        if (entries.length < 3)
+            continue;
+        const shapes = new Map();
+        for (const e of entries) {
+            const key = e.props.join("+");
+            shapes.set(key, [...(shapes.get(key) ?? []), e]);
+        }
+        if (shapes.size < 2)
+            continue;
+        const ranked = [...shapes.entries()].sort((a, b) => b[1].length - a[1].length);
+        const [houseKey, houseList] = ranked[0];
+        if (houseList.length / entries.length < DOMINANT)
+            continue;
+        out.push({
+            concern,
+            house: houseKey.split("+"),
+            houseCount: houseList.length,
+            outliers: ranked
+                .slice(1)
+                .flatMap(([, list]) => list)
+                .sort((a, b) => a.component.localeCompare(b.component)),
+        });
+    }
+    return out.sort((a, b) => b.outliers.length - a.outliers.length);
+}

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.18",
+  "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": {