synthesisui 0.8.1 → 0.9.1

package/dist/commands/doctor.js

@@ -2,7 +2,8 @@ import { readdir, readFile } from "node:fs/promises";
 import { join, relative, resolve } from "node:path";
 import { bindingsFromDocument, countComponents, findOverrides, } from "../doctor/overrides.js";
 import { diagnose, scanSource, } from "../doctor/scan.js";
-import { buildTable, EMPTY_TABLE } from "../doctor/tokens.js";
+import { findSelfConflicts, forbiddenProps, isReset, propMatchesLabel, } from "../doctor/self-conflict.js";
+import { buildTable, EMPTY_TABLE, nearestToken, } from "../doctor/tokens.js";
 import { body, section, snippet } from "../output.js";
 /**
  * `synthesisui doctor` - the check nobody else ships.
@@ -83,13 +84,14 @@ async function loadSystem(root) {
             .map((e) => e.name);
     }
     catch {
-        return { table: EMPTY_TABLE, recipes: new Map() };
+        return { table: EMPTY_TABLE, recipes: new Map(), documents: [] };
     }
     // Several systems can live side by side; every token is prefixed --ds-, so
     // reading them all is both correct and what the running app actually sees.
     let css = "";
     let lock = null;
     const recipes = new Map();
+    const documents = [];
     for (const slug of slugs) {
         const dir = join(dsDir, slug);
         const raw = await readFile(join(dir, ".lock"), "utf8").catch(() => "");
@@ -120,7 +122,9 @@ async function loadSystem(root) {
             : "";
         if (docRaw) {
             try {
-                for (const [k, v] of bindingsFromDocument(JSON.parse(docRaw))) {
+                const parsed = JSON.parse(docRaw);
+                documents.push(parsed);
+                for (const [k, v] of bindingsFromDocument(parsed)) {
                     if (!recipes.has(k))
                         recipes.set(k, v);
                 }
@@ -130,7 +134,7 @@ async function loadSystem(root) {
             }
         }
     }
-    return { table: buildTable({ css, lock }), recipes };
+    return { table: buildTable({ css, lock }), recipes, documents };
 }
 const KIND_LABEL = {
     color: "colour",
@@ -194,7 +198,7 @@ function verdict(d, hasSystem, overruled) {
 }
 export async function doctor(opts) {
     const root = resolve(opts.dir ?? process.cwd());
-    const { table, recipes } = await loadSystem(root);
+    const { table, recipes, documents } = await loadSystem(root);
     const hasSystem = table.byName.size > 0;
     const scopes = (opts.scopes ?? []).map((s) => resolve(root, s));
     const reports = [];
@@ -219,6 +223,15 @@ export async function doctor(opts) {
         console.log(`\nNothing to read in ${root}.\n`);
         return;
     }
+    // The same line said twice, two different ways: `#fff` on an avatar came
+    // back under Drift as "no token holds this value yet" AND under Overruled as
+    // "the recipe binds {color.navy.50}". The override is strictly the better
+    // sentence - it names the component and what it promised - so the generic
+    // one steps aside (investidorez, 25/07).
+    const explained = new Set(overrides.map((o) => `${o.file}:${o.line}:${o.wrote.toLowerCase()}`));
+    for (const r of reports) {
+        r.findings = r.findings.filter((f) => !explained.has(`${r.file}:${f.line}:${f.literal.toLowerCase()}`));
+    }
     const d = diagnose(reports);
     console.log(section("Doctor"));
     console.log(body(hasSystem
@@ -263,7 +276,12 @@ export async function doctor(opts) {
             const w = Math.max(...repeats.map((r) => r.literal.length));
             for (const r of repeats) {
                 const where = `${r.count}\u00d7 in ${r.files} file${r.files === 1 ? "" : "s"}`;
-                const named = r.token ? `  → ${r.token}` : "";
+                const near = r.token ? null : nearestToken(table, r.literal);
+                const named = r.token
+                    ? `  → ${r.token}`
+                    : near
+                        ? `  → nearest is ${near.name} (${near.value})`
+                        : "";
                 console.log(`      ${r.literal.padEnd(w)}  ${where}${named}`);
             }
         }
@@ -276,9 +294,14 @@ export async function doctor(opts) {
             console.log(body(`${f.file}`));
             const shown = opts.all ? f.findings : f.findings.slice(0, 3);
             for (const x of shown) {
+                // A dead end with a neighbour is not a dead end. Only for lengths -
+                // "nearly the same blue" is the guess this tool must never make.
+                const near = x.token ? null : nearestToken(table, x.literal);
                 const named = x.token
                     ? `→ ${x.token}`
-                    : "→ no token holds this value yet";
+                    : near
+                        ? `→ nearest is ${near.name} (${near.value})`
+                        : "→ no token holds this value yet";
                 console.log(`      ${String(x.line).padStart(4)}  ${x.literal}  ${named}`);
             }
             if (f.findings.length > shown.length) {
@@ -290,10 +313,64 @@ export async function doctor(opts) {
             console.log(body(`+${files.length - shownFiles.length} more files. Run with --all to see everything.`));
         }
     }
+    // Every other section asks whether the code obeys the system. This one asks
+    // whether the system obeys itself, and it is only here because the tool once
+    // reported a consumer for overruling a recipe while they were obeying the
+    // law written on that same component.
+    const conflicts = documents.flatMap((doc) => findSelfConflicts(doc));
+    const conflictsInUse = conflicts.filter((c) => used.has(c.component));
+    if (conflictsInUse.length > 0) {
+        console.log(section("Your system contradicts itself"));
+        console.log(body(conflictsInUse.length === 1
+            ? "One component says one thing in prose and another in its recipe."
+            : `${conflictsInUse.length} components say one thing in prose and another in their recipe.`));
+        console.log("");
+        for (const c of conflictsInUse) {
+            console.log(body(`ds-${c.component}`));
+            console.log(`          "${c.law}"`);
+            console.log(`          but ${c.where} binds ${c.value}`);
+            console.log("");
+        }
+        console.log(body("Whoever wrote the law and whoever wrote the recipe disagree."));
+        console.log(body("Until they do not, no code here can be correct."));
+    }
     if (overrides.length > 0) {
+        // An override on a property the component's own law FORBIDS, written as a
+        // reset, is not drift - it is the author keeping a promise the recipe
+        // broke. Counting it against them was the report being unfair to the only
+        // person in the loop who read the law (investidorez, 25/07).
+        const forbidden = new Map();
+        for (const doc of documents) {
+            for (const [comp, props] of forbiddenProps(doc)) {
+                const merged = forbidden.get(comp) ?? new Map();
+                for (const [label, law] of props)
+                    merged.set(label, law);
+                forbidden.set(comp, merged);
+            }
+        }
+        const lawKept = (o) => {
+            if (!isReset(o.wrote))
+                return null;
+            const props = forbidden.get(o.component);
+            if (!props)
+                return null;
+            for (const [label, law] of props) {
+                if (propMatchesLabel(o.prop, label))
+                    return law;
+            }
+            return null;
+        };
+        const drifting = overrides.filter((o) => lawKept(o) === null);
+        const correcting = overrides.length - drifting.length;
         console.log(section("Overruled"));
-        console.log(body(`${overrides.length} place${overrides.length === 1 ? "" : "s"} where the code takes a component`));
+        console.log(body(`${drifting.length} place${drifting.length === 1 ? "" : "s"} where the code takes a component`));
         console.log(body("the system defines, and then overrules it locally."));
+        if (correcting > 0) {
+            console.log("");
+            console.log(body(correcting === 1
+                ? "One more overrules it to KEEP a law the recipe breaks - marked below."
+                : `${correcting} more overrule it to KEEP a law the recipe breaks - marked below.`));
+        }
         console.log("");
         const byFile = new Map();
         for (const o of overrides) {
@@ -315,6 +392,11 @@ export async function doctor(opts) {
                     console.log(`            the recipe binds ${o.recipe}`);
                 else if (o.where)
                     console.log(`            the recipe binds it ${o.where}`);
+                const kept = lawKept(o);
+                if (kept) {
+                    console.log(`            ✓ but the law says: "${kept}"`);
+                    console.log("              this override keeps it - the recipe does not");
+                }
             }
             if (!opts.all && list.length > 3) {
                 console.log(`            +${list.length - 3} more`);

package/dist/doctor/self-conflict.js

@@ -0,0 +1,175 @@
+/**
+ * DOCTOR · the system against itself.
+ *
+ * Every other check asks whether the CODE obeys the system. This one asks
+ * whether the system obeys ITSELF - whether a component's recipe contradicts
+ * the law written on that same component.
+ *
+ * It exists because of a real report. Vesper says of its card:
+ *
+ *   "Cards are ledger pages: hairline borders, dusk surfaces, no drop shadows."
+ *
+ * and its recipe binds `boxShadow: {shadow.md}` on hover. A consumer wrote
+ * `box-shadow: none` over it, with a comment explaining why - and the doctor
+ * reported THEM as the one overruling the system. They were obeying the prose
+ * and contradicting the machine, and nothing in the tool could see it
+ * (investidorez, 25/07).
+ *
+ * Prose is not verifiable in general, and this does not try. It reads one
+ * narrow shape - a law that FORBIDS something the recipe then binds - and says
+ * nothing at all when it is unsure. A false accusation here is worse than
+ * silence, because the thing being accused is the system's own author.
+ */
+/** A property the recipe can bind, and the words a law uses to forbid it. */
+const FORBIDDABLE = [
+    { prop: /^box-shadow$/, words: ["shadow", "shadows"], label: "box-shadow" },
+    { prop: /^border(-width)?$/, words: ["border", "borders"], label: "border" },
+    {
+        prop: /^border-radius$/,
+        words: ["radius", "rounding", "rounded corners"],
+        label: "border-radius",
+    },
+    {
+        prop: /^text-transform$/,
+        words: ["uppercase", "all caps", "caps"],
+        label: "text-transform",
+    },
+    {
+        prop: /^background(-image)?$/,
+        words: ["gradient", "gradients"],
+        label: "gradient",
+    },
+    {
+        prop: /^(transform|animation)$/,
+        words: ["animation", "animations", "movement", "motion"],
+        label: "motion",
+    },
+    {
+        prop: /^letter-spacing$/,
+        words: ["tracking", "letter-spacing"],
+        label: "letter-spacing",
+    },
+];
+/**
+ * The negations a designer actually writes. Anchored to the word so "no drop
+ * shadows" hits and "no more than one shadow" does not - that is a rule about
+ * quantity, and this lens does not count.
+ */
+const NEGATIONS = ["no", "never", "without", "avoid"];
+const isSet = (v) => {
+    const t = v.trim().toLowerCase();
+    return (t !== "" && t !== "none" && t !== "0" && t !== "unset" && t !== "initial");
+};
+/**
+ * Does this law forbid `label`? True only when a negation sits within a few
+ * words of the term - "no drop shadows" yes, "shadows are allowed when nothing
+ * else separates two surfaces" no.
+ */
+const QUANTITY = /\b(more|less|fewer|than|most|one|two|three|\d)\b/;
+function forbids(law, words) {
+    const text = law.toLowerCase();
+    for (const word of words) {
+        for (const neg of NEGATIONS) {
+            const re = new RegExp(`\\b${neg}\\b([^.;,]{0,24}?)\\b${word}\\b`);
+            const m = re.exec(text);
+            // "never MORE THAN ONE shadow" is a rule about how many, not a ban. This
+            // lens does not count, so it says nothing.
+            if (m && !QUANTITY.test(m[1]))
+                return word;
+        }
+    }
+    return null;
+}
+/** Walk a recipe block, yielding every property it actually sets. */
+function* declarations(node, where) {
+    if (!node || typeof node !== "object")
+        return;
+    for (const [k, v] of Object.entries(node)) {
+        if (typeof v === "string" || typeof v === "number") {
+            const prop = k.replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase();
+            yield { prop, value: String(v), where };
+        }
+        else if (v && typeof v === "object") {
+            yield* declarations(v, where);
+        }
+    }
+}
+/**
+ * Per component, the properties its own laws forbid and the law that does it.
+ *
+ * The report needs this separately from the conflicts: an override on a
+ * forbidden property is not drift, it is the author keeping a promise the
+ * recipe broke. Listing them together was accusing the person who was right.
+ */
+export function forbiddenProps(document) {
+    const out = new Map();
+    const doc = (document ?? {});
+    const components = (doc.components ?? {});
+    for (const [name, raw] of Object.entries(components)) {
+        const recipe = (raw ?? {});
+        const laws = Array.isArray(recipe.usage)
+            ? recipe.usage.filter((x) => typeof x === "string")
+            : [];
+        for (const law of laws) {
+            for (const rule of FORBIDDABLE) {
+                if (!forbids(law, rule.words))
+                    continue;
+                const byProp = out.get(name) ?? new Map();
+                byProp.set(rule.label, law);
+                out.set(name, byProp);
+            }
+        }
+    }
+    return out;
+}
+/** Is this property one the law names, given how the rule matches? */
+export function propMatchesLabel(prop, label) {
+    const rule = FORBIDDABLE.find((r) => r.label === label);
+    return rule ? rule.prop.test(prop) : false;
+}
+/** A value that removes rather than sets - the law being kept. */
+export function isReset(value) {
+    return !isSet(value);
+}
+/**
+ * Every place a component's recipe does what its own law forbids.
+ */
+export function findSelfConflicts(document) {
+    const out = [];
+    const doc = (document ?? {});
+    const components = (doc.components ?? {});
+    for (const [name, raw] of Object.entries(components)) {
+        const recipe = (raw ?? {});
+        const laws = Array.isArray(recipe.usage)
+            ? recipe.usage.filter((x) => typeof x === "string")
+            : [];
+        if (laws.length === 0)
+            continue;
+        const decls = [
+            ...declarations(recipe.base, "base"),
+            ...declarations(recipe.states, "a state"),
+            ...declarations(recipe.variants, "a variant"),
+            ...declarations(recipe.parts, "a part"),
+        ];
+        for (const law of laws) {
+            for (const rule of FORBIDDABLE) {
+                const word = forbids(law, rule.words);
+                if (!word)
+                    continue;
+                for (const d of decls) {
+                    if (!rule.prop.test(d.prop) || !isSet(d.value))
+                        continue;
+                    out.push({
+                        component: name,
+                        law,
+                        forbids: word,
+                        where: `${d.where} · ${d.prop}`,
+                        value: d.value,
+                    });
+                    break; // one report per law per property family
+                }
+            }
+        }
+    }
+    return out;
+}

package/dist/doctor/tokens.js

@@ -18,17 +18,49 @@ export const EMPTY_TABLE = {
     byName: new Map(),
     byValue: new Map(),
 };
-/** Lowercase, collapse whitespace, expand #abc to #aabbcc - so `#FFF`,
- *  `#ffffff` and `# fff` all land on one key. */
+const hex2 = (n) => Math.max(0, Math.min(255, Math.round(n)))
+    .toString(16)
+    .padStart(2, "0");
+/**
+ * One key per colour, whatever dialect it was written in.
+ *
+ * Every colour lands on 8-digit hex, so `#FFF`, `#ffffff`, `rgb(255 255 255)`
+ * and `rgba(255,255,255,1)` are one value - and a translucent literal finds a
+ * translucent token: Vesper's scrim is authored `#09090bb3`, and an author
+ * writing `rgba(9, 9, 11, 0.7)` was being told no token held it.
+ *
+ * Anything that is not a colour passes through lowercased and collapsed.
+ */
 export function normalizeValue(raw) {
     const v = raw.trim().toLowerCase().replace(/\s+/g, " ");
-    const short = /^#([0-9a-f])([0-9a-f])([0-9a-f])$/.exec(v);
-    if (short)
-        return `#${short[1]}${short[1]}${short[2]}${short[2]}${short[3]}${short[3]}`;
-    // rgb(37 99 235) and rgb(37, 99, 235) are the same colour written twice.
+    const short = /^#([0-9a-f])([0-9a-f])([0-9a-f])([0-9a-f])?$/.exec(v);
+    if (short) {
+        const d = (c) => c + c;
+        return `#${d(short[1])}${d(short[2])}${d(short[3])}${short[4] ? d(short[4]) : "ff"}`;
+    }
+    const long = /^#([0-9a-f]{6})([0-9a-f]{2})?$/.exec(v);
+    if (long)
+        return `#${long[1]}${long[2] ?? "ff"}`;
     const rgb = /^rgba?\(([^)]+)\)$/.exec(v);
     if (rgb) {
         const parts = rgb[1].split(/[\s,/]+/).filter(Boolean);
+        if (parts.length >= 3 &&
+            parts.slice(0, 3).every((p) => /^[\d.]+%?$/.test(p))) {
+            const ch = parts
+                .slice(0, 3)
+                .map((p) => p.endsWith("%") ? (Number.parseFloat(p) / 100) * 255 : Number(p));
+            const rawA = parts[3];
+            const a = rawA === undefined
+                ? 1
+                : rawA.endsWith("%")
+                    ? Number.parseFloat(rawA) / 100
+                    : Number(rawA);
+            if (ch.every((c) => Number.isFinite(c)) && Number.isFinite(a)) {
+                return `#${ch.map(hex2).join("")}${hex2(a * 255)}`;
+            }
+        }
+        // a colour we cannot read (a variable inside, a colour space) still gets a
+        // stable key, just not a comparable one
         return `rgb(${parts.join(" ")})`;
     }
     return v;
@@ -82,6 +114,42 @@ export function buildTable(input) {
  * a diagnosis nobody can trust is worse than no diagnosis. Near misses are
  * reported as drift, not as a fix.
  */
+/**
+ * The token nearest a length the system has no exact name for.
+ *
+ * `60px` appeared three times across three files on a real project, and the
+ * report could only say "no token holds this value yet" - a dead end. The
+ * nearest step is `--ds-spacing-2xl` at 64px: four pixels away, and almost
+ * certainly what the author meant. Naming it turns a dead end into a decision.
+ *
+ * Deliberately narrow: same unit, within 25% or 8px, and never for a colour -
+ * "nearly the same blue" is exactly the guess this tool must not make.
+ */
+export function nearestToken(table, literal) {
+    const m = /^(-?\d*\.?\d+)(px|rem)$/.exec(literal.trim().toLowerCase());
+    if (!m)
+        return null;
+    const n = Number(m[1]);
+    const unit = m[2];
+    if (!Number.isFinite(n) || n === 0)
+        return null;
+    let best = null;
+    for (const [name, raw] of table.byName) {
+        const t = /^(-?\d*\.?\d+)(px|rem)$/.exec(raw.trim().toLowerCase());
+        if (!t || t[2] !== unit)
+            continue;
+        const v = Number(t[1]);
+        if (!Number.isFinite(v) || v === n)
+            continue;
+        const delta = Math.abs(v - n);
+        if (best === null || delta < best.delta)
+            best = { name, value: raw, delta };
+    }
+    if (!best)
+        return null;
+    const limit = unit === "rem" ? Math.max(n * 0.25, 0.5) : Math.max(n * 0.25, 8);
+    return best.delta <= limit ? best : null;
+}
 export function tokenFor(table, literal) {
     const hit = table.byValue.get(normalizeValue(literal));
     if (!hit || hit.length === 0)

package/package.json

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