synthesisui 0.8.0 → 0.9.0

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 } 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) {
@@ -308,8 +331,13 @@ export async function doctor(opts) {
             console.log(body(file));
             for (const o of opts.all ? list : list.slice(0, 3)) {
                 console.log(`      ${String(o.line).padStart(4)}  ds-${o.component} · ${o.prop}: ${o.wrote}`);
+                // Always say what is being overruled. A finding that cannot name it is
+                // indistinguishable from a bug in the reader's eyes, and one of these
+                // (`.ds-card:hover { transform: none }`) was a real, deliberate call.
                 if (o.recipe)
                     console.log(`            the recipe binds ${o.recipe}`);
+                else if (o.where)
+                    console.log(`            the recipe binds it ${o.where}`);
             }
             if (!opts.all && list.length > 3) {
                 console.log(`            +${list.length - 3} more`);
@@ -323,6 +351,27 @@ export async function doctor(opts) {
     // The system's own words, for the components this project actually uses.
     // Prose, so nothing verifies it - the value is putting it in front of
     // whoever is touching the component, which no other tool is positioned to
+    // 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."));
+    }
     // do because no other tool knows these laws exist.
     const inUse = [...used.entries()]
         .filter(([name]) => (recipes.get(name)?.usage.length ?? 0) > 0)

package/dist/doctor/overrides.js

@@ -46,10 +46,37 @@ export function bindingsOf(recipe) {
     collect(r.variants, false);
     collect(r.states, false);
     collect(r.parts, false);
+    // Where a non-base property lives, so the report can name it. Base wins: if
+    // base binds it too, that value is the one worth showing.
+    const boundIn = new Map();
+    const note = (block, label) => {
+        if (!block || typeof block !== "object")
+            return;
+        for (const [k, v] of Object.entries(block)) {
+            if (typeof v === "string" || typeof v === "number") {
+                const p = kebab(k);
+                if (!baseValues.has(p) && !boundIn.has(p))
+                    boundIn.set(p, `${label}: ${v}`);
+            }
+            else if (v && typeof v === "object") {
+                note(v, label);
+            }
+        }
+    };
+    for (const [state, block] of Object.entries((r.states ?? {}))) {
+        note(block, `on ${state}`);
+    }
+    for (const [axis, opts] of Object.entries((r.variants ?? {}))) {
+        if (!opts || typeof opts !== "object")
+            continue;
+        for (const [opt, block] of Object.entries(opts)) {
+            note(block, `on ${axis}="${opt}"`);
+        }
+    }
     const usage = Array.isArray(r.usage)
         ? r.usage.filter((x) => typeof x === "string")
         : [];
-    return { props, baseValues, usage };
+    return { props, baseValues, boundIn, usage };
 }
 /**
  * How many places each known component is used. An inventory nobody has today:
@@ -117,6 +144,55 @@ function enclosingTag(src, at) {
     return null;
 }
 const lineAt = (src, index) => src.slice(0, index).split("\n").length;
+/**
+ * Whatever the `style` prop was given, with where it starts. The expression
+ * container, not `{{` specifically: a real component writes
+ * `style={showImg ? undefined : { color: "#fff" }}`, and requiring the double
+ * brace dropped that finding on the floor. Brace matching rather than a regex,
+ * because the value nests.
+ */
+function styleRegions(tag) {
+    const out = [];
+    const open = /style\s*=\s*\{/g;
+    let m = open.exec(tag);
+    while (m !== null) {
+        const start = m.index + m[0].length;
+        let depth = 1; // the container brace just consumed
+        let end = start;
+        for (; end < tag.length; end++) {
+            if (tag[end] === "{")
+                depth++;
+            else if (tag[end] === "}" && --depth === 0)
+                break;
+        }
+        // Only the OBJECT LITERALS inside the container. Scanning the container
+        // whole let a one-line ternary eat the declaration: in
+        // `style={on ? undefined : { padding: "7px" }}` the colon after `undefined`
+        // reads as a property separator and swallows the padding behind it.
+        const container = tag.slice(start, end);
+        let d = 0;
+        let objStart = -1;
+        for (let i = 0; i < container.length; i++) {
+            if (container[i] === "{") {
+                if (d === 0)
+                    objStart = i + 1;
+                d++;
+            }
+            else if (container[i] === "}" && d > 0 && --d === 0) {
+                out.push({
+                    text: container.slice(objStart, i),
+                    offset: start + objStart,
+                });
+            }
+        }
+        // `style={{ … }}` - the container IS the object
+        if (objStart === -1)
+            out.push({ text: container, offset: start });
+        open.lastIndex = end;
+        m = open.exec(tag);
+    }
+    return out;
+}
 /**
  * The literal a style property was given, or null when it was given an
  * expression instead.
@@ -159,22 +235,29 @@ export function findOverrides(source, recipes) {
         const tag = enclosingTag(source, m.index ?? 0);
         if (!tag)
             continue;
-        // inline style={{ borderRadius: 4 }}
-        for (const s of tag.text.matchAll(/([a-zA-Z-]+)\s*:\s*("[^"]*"|'[^']*'|[^,}\n]+)/g)) {
-            const prop = kebab(s[1]);
-            if (!bind.props.has(prop))
-                continue;
-            const wrote = literalValue(s[2]);
-            if (wrote === null)
-                continue;
-            record({
-                component: name,
-                prop,
-                wrote,
-                recipe: bind.baseValues.get(prop) ?? null,
-                line: lineAt(source, tag.start + (s.index ?? 0)),
-                excerpt: clip(lines[lineAt(source, tag.start + (s.index ?? 0)) - 1]?.trim() ?? ""),
-            });
+        // inline style={{ borderRadius: 4 }} - and ONLY that. Reading the whole tag
+        // meant reading every object prop on it, so Framer Motion's
+        // `animate={{ opacity: 1 }}` came back as "ds-card overrules opacity"
+        // (investidorez, 25/07). An animation is not a design decision.
+        for (const region of styleRegions(tag.text)) {
+            for (const s of region.text.matchAll(/([a-zA-Z-]+)\s*:\s*("[^"]*"|'[^']*'|[^,}\n]+)/g)) {
+                const prop = kebab(s[1]);
+                if (!bind.props.has(prop))
+                    continue;
+                const wrote = literalValue(s[2]);
+                if (wrote === null)
+                    continue;
+                const at = tag.start + region.offset + (s.index ?? 0);
+                record({
+                    component: name,
+                    prop,
+                    wrote,
+                    recipe: bind.baseValues.get(prop) ?? null,
+                    where: bind.boundIn.get(prop) ?? null,
+                    line: lineAt(source, at),
+                    excerpt: clip(lines[lineAt(source, at) - 1]?.trim() ?? ""),
+                });
+            }
         }
         // utility classes sitting beside the ds-* class
         for (const cls of tag.text.matchAll(/[\w:[\]#().%/-]+/g)) {
@@ -186,6 +269,7 @@ export function findOverrides(source, recipes) {
                 prop,
                 wrote: cls[0],
                 recipe: bind.baseValues.get(prop) ?? null,
+                where: bind.boundIn.get(prop) ?? null,
                 line: lineAt(source, tag.start + (cls.index ?? 0)),
                 excerpt: clip(lines[lineAt(source, tag.start + (cls.index ?? 0)) - 1]?.trim() ?? ""),
             });
@@ -193,7 +277,10 @@ export function findOverrides(source, recipes) {
     }
     // ── CSS: a rule whose selector reaches a ds-* component ───────────────────
     for (const rule of source.matchAll(/([^{}]+)\{([^{}]*)\}/g)) {
-        const selector = rule[1];
+        // A CSS comment is not a selector. `/* botões (.ds-button) … */` above an
+        // unrelated rule made the doctor attribute that rule to ds-button - it was
+        // reading prose as structure (investidorez, 25/07).
+        const selector = rule[1].replace(/\/\*[\s\S]*?\*\//g, "");
         const hit = /\.ds-([a-z][a-z0-9-]*)\b/.exec(selector);
         const bind = hit ? recipes.get(hit[1]) : undefined;
         if (!hit || !bind)
@@ -211,6 +298,7 @@ export function findOverrides(source, recipes) {
                 prop,
                 wrote: decl[2].trim(),
                 recipe: bind.baseValues.get(prop) ?? null,
+                where: bind.boundIn.get(prop) ?? null,
                 line: lineAt(source, at),
                 excerpt: clip(lines[lineAt(source, at) - 1]?.trim() ?? ""),
             });

package/dist/doctor/self-conflict.js

@@ -0,0 +1,138 @@
+/**
+ * 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);
+        }
+    }
+}
+/**
+ * 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.0",
+  "version": "0.9.0",
   "description": "Bring SynthesisUI design systems into any project - tokens, typed components, whole pages and an agent-ready CLAUDE.md manifest.",
   "type": "module",
   "bin": {