synthesisui 0.5.0 → 0.7.0

package/README.md

@@ -68,6 +68,29 @@ npx synthesisui@latest doctor
         21  #f1f3fa  → --ds-color-gray-100
 ```
 
+### Overruled
+
+With a system installed it runs a second pass that nothing else can:
+
+```
+── Overruled ─────────────────────────────────────────────────────
+
+  3 places where the code takes a component
+  the system defines, and then overrules it locally.
+
+  components/Hero.tsx
+        12  ds-button · border-radius: 4
+            the recipe binds {radius.md}
+        18  ds-button · padding: px-8
+            the recipe binds {spacing.2xs} {spacing.md}
+```
+
+It only flags a property the recipe **actually binds**. `w-full` beside a
+button is layout; `px-8` is drift, because the recipe already decided the
+padding. A rule reading `var(--ds-…)` back is the opposite of overruling and
+is left alone. This needs the recipes, which are only in the project because
+`add` put them there - a linter has no idea what `ds-button` promised.
+
 The last column is the point: not "you hardcoded a colour", but **the name
 your own system already has for it**. Exact matches only - a tool that guesses
 a near colour invites a silent visual change, and a diagnosis nobody trusts is
@@ -76,8 +99,28 @@ worse than none.
 With no system installed it still finds every hand-written value and counts
 the distinct ones. Runs offline, needs no account, writes nothing.
 
-`--strict` exits 1 when drift is found, for CI. `--all` lists everything
-instead of the loudest files.
+### What your system says
+
+```
+── What your system says about what you use ──────────────────────
+
+  ds-badge  ·  3 places
+      Badges whisper status in periwinkle; danger appears only for money at risk.
+
+  ds-button  ·  3 places
+      One indigo action per view; gold is reserved for moments of ceremony, never buttons.
+      Buttons speak quietly - sentence case, no exclamation.
+```
+
+The usage laws your team wrote, for the components this project actually uses,
+ordered by how much you use them. They are prose, so nothing verifies them -
+the value is putting them in front of whoever is touching the component. No
+other tool is positioned to do it, because no other tool knows these laws
+exist.
+
+`--strict` exits 1 when drift is found, for CI. `--all` lists every finding
+instead of the loudest files. `--laws` shows every law instead of the busiest
+components.
 
 ## What `add` materializes
 

package/dist/commands/doctor.js

@@ -1,5 +1,6 @@
 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 { body, section, snippet } from "../output.js";
@@ -58,7 +59,10 @@ async function* walk(dir) {
         }
     }
 }
-/** Find the installed system: `_synthesisui/ds/<slug>/tokens.css` + `.lock`. */
+/** Find the installed system: `_synthesisui/ds/<slug>/tokens.css` + `.lock`,
+ *  and the recipes `add` put next to them in `design-system.json`. Those
+ *  recipes are why the component pass can exist at all - a linter has no idea
+ *  what `ds-button` promised. */
 async function loadSystem(root) {
     const dsDir = join(root, "_synthesisui", "ds");
     let slugs;
@@ -68,12 +72,13 @@ async function loadSystem(root) {
             .map((e) => e.name);
     }
     catch {
-        return EMPTY_TABLE;
+        return { table: EMPTY_TABLE, recipes: new Map() };
     }
     // 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();
     for (const slug of slugs) {
         const dir = join(dsDir, slug);
         const raw = await readFile(join(dir, ".lock"), "utf8").catch(() => "");
@@ -99,8 +104,22 @@ async function loadSystem(root) {
             }
         }
         css += `\n${real || root}`;
+        const docRaw = mine?.version
+            ? await readFile(join(dir, `v${mine.version}`, "design-system.json"), "utf8").catch(() => "")
+            : "";
+        if (docRaw) {
+            try {
+                for (const [k, v] of bindingsFromDocument(JSON.parse(docRaw))) {
+                    if (!recipes.has(k))
+                        recipes.set(k, v);
+                }
+            }
+            catch {
+                // A document we cannot parse costs the component pass, not the run.
+            }
+        }
     }
-    return buildTable({ css, lock });
+    return { table: buildTable({ css, lock }), recipes };
 }
 const KIND_LABEL = {
     color: "colour",
@@ -113,7 +132,7 @@ function meter(pct, width = 24) {
     const filled = Math.round((pct / 100) * width);
     return `${"█".repeat(filled)}${"░".repeat(width - filled)}`;
 }
-function verdict(d, hasSystem) {
+function verdict(d, hasSystem, overruled) {
     // Nothing found and nothing installed: a utility package, a config folder,
     // the wrong directory. Selling a design system here would be noise.
     if (!hasSystem && d.findings.length === 0) {
@@ -133,12 +152,26 @@ function verdict(d, hasSystem) {
             body("Browse systems at https://www.synthesisui.com/gallery"),
         ];
     }
-    if (d.findings.length === 0) {
+    if (d.findings.length === 0 && overruled === 0) {
         return [
             body("No drift. Every design value in this project comes from the"),
             body("system. That is a rarer sentence than it sounds."),
         ];
     }
+    // A report that accuses a component of being overruled and then closes with
+    // "no drift" is a report nobody believes twice.
+    if (d.findings.length === 0) {
+        return [
+            body("No loose values - everything is a token."),
+            body(overruled === 1
+                ? "But one place takes a component the system defines and"
+                : `But ${overruled} places take a component the system defines and`),
+            body(overruled === 1
+                ? "overrules it locally. Either the recipe should change, or"
+                : "overrule it locally. Either the recipe should change, or"),
+            body("that override should not be there."),
+        ];
+    }
     const lines = [
         body(`${d.named} of ${d.findings.length} already have a name in your system.`),
         body("Those are the cheap ones: swap the literal for the token."),
@@ -150,13 +183,25 @@ function verdict(d, hasSystem) {
 }
 export async function doctor(opts) {
     const root = resolve(opts.dir ?? process.cwd());
-    const table = await loadSystem(root);
+    const { table, recipes } = await loadSystem(root);
     const hasSystem = table.byName.size > 0;
     const reports = [];
+    const overrides = [];
+    const used = new Map();
+    const known = new Set(recipes.keys());
     for await (const file of walk(root)) {
         const src = await readFile(file, "utf8").catch(() => "");
-        if (src)
-            reports.push(scanSource(relative(root, file), src, table));
+        if (!src)
+            continue;
+        const rel = relative(root, file);
+        reports.push(scanSource(rel, src, table));
+        if (recipes.size > 0) {
+            for (const o of findOverrides(src, recipes))
+                overrides.push({ ...o, file: rel });
+            for (const [name, n] of countComponents(src, known)) {
+                used.set(name, (used.get(name) ?? 0) + n);
+            }
+        }
     }
     if (reports.length === 0) {
         console.log(`\nNothing to read in ${root}.\n`);
@@ -167,7 +212,10 @@ export async function doctor(opts) {
     console.log(body(hasSystem
         ? `${table.name ?? table.slug} v${table.version ?? "?"} - ${table.byName.size} tokens, ${d.scanned} files read`
         : `No system installed - ${d.scanned} files read`));
-    if (hasSystem) {
+    // 0 of 0 is not a perfect score, it is an empty measurement - printing a
+    // full bar there would be the report's first lie.
+    const measurable = d.tokenUses + d.findings.length > 0;
+    if (hasSystem && measurable) {
         console.log("");
         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`));
@@ -215,10 +263,66 @@ export async function doctor(opts) {
             console.log(body(`+${files.length - shownFiles.length} more files. Run with --all to see everything.`));
         }
     }
+    if (overrides.length > 0) {
+        console.log(section("Overruled"));
+        console.log(body(`${overrides.length} place${overrides.length === 1 ? "" : "s"} where the code takes a component`));
+        console.log(body("the system defines, and then overrules it locally."));
+        console.log("");
+        const byFile = new Map();
+        for (const o of overrides) {
+            const list = byFile.get(o.file);
+            if (list)
+                list.push(o);
+            else
+                byFile.set(o.file, [o]);
+        }
+        const shown = opts.all ? [...byFile] : [...byFile].slice(0, 6);
+        for (const [file, list] of shown) {
+            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}`);
+                if (o.recipe)
+                    console.log(`            the recipe binds ${o.recipe}`);
+            }
+            if (!opts.all && list.length > 3) {
+                console.log(`            +${list.length - 3} more`);
+            }
+            console.log("");
+        }
+        if (byFile.size > shown.length) {
+            console.log(body(`+${byFile.size - shown.length} more files. Run with --all.`));
+        }
+    }
+    // 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
+    // do because no other tool knows these laws exist.
+    const inUse = [...used.entries()]
+        .filter(([name]) => (recipes.get(name)?.usage.length ?? 0) > 0)
+        .sort((a, b) => b[1] - a[1]);
+    if (inUse.length > 0) {
+        console.log(section("What your system says about what you use"));
+        const shownComps = opts.laws || opts.all ? inUse : inUse.slice(0, 4);
+        for (const [name, count] of shownComps) {
+            const laws = recipes.get(name)?.usage ?? [];
+            const shown = opts.laws || opts.all ? laws : laws.slice(0, 2);
+            console.log(body(`ds-${name}  ·  ${count} place${count === 1 ? "" : "s"}`));
+            for (const law of shown)
+                console.log(`      ${law}`);
+            if (laws.length > shown.length) {
+                console.log(`      +${laws.length - shown.length} more`);
+            }
+            console.log("");
+        }
+        if (inUse.length > shownComps.length) {
+            console.log(body(`+${inUse.length - shownComps.length} more components carry laws. Run with --laws.`));
+            console.log("");
+        }
+    }
     console.log(section("What this means"));
-    for (const line of verdict(d, hasSystem))
+    for (const line of verdict(d, hasSystem, overrides.length))
         console.log(line);
     console.log("");
-    if (opts.strict && d.findings.length > 0)
+    if (opts.strict && (d.findings.length > 0 || overrides.length > 0))
         process.exitCode = 1;
 }

package/dist/doctor/overrides.js

@@ -0,0 +1,206 @@
+/**
+ * DOCTOR · drift ON a component the project is already using.
+ *
+ * The generic pass finds a hardcoded value anywhere. This finds the sharper
+ * thing: a place where the code takes a component the system defines and then
+ * overrules the system locally.
+ *
+ *   <button className="ds-button" style={{ borderRadius: 4 }}>
+ *   → the recipe already binds border-radius to {radius.md}
+ *
+ * This is the check nothing else can run, and the reason is structural: it
+ * needs the recipes, and the recipes are only in the project because `add`
+ * put them there (`_synthesisui/ds/<slug>/v<n>/design-system.json`). A linter
+ * has no idea what `ds-button` promised.
+ *
+ * It only ever flags a property the recipe ACTUALLY binds. `w-full` next to a
+ * button is layout, not drift; `p-4` is drift, because the recipe already
+ * decided the padding.
+ */
+const kebab = (s) => s.replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase();
+/**
+ * Every property a recipe touches - base, variants, states and parts. A
+ * variant binding counts: if `intent=primary` sets the background, then
+ * writing a background by hand overrules the system just as surely.
+ */
+export function bindingsOf(recipe) {
+    const props = new Set();
+    const baseValues = new Map();
+    const collect = (block, isBase) => {
+        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);
+                props.add(p);
+                if (isBase)
+                    baseValues.set(p, String(v));
+            }
+            else if (v && typeof v === "object") {
+                collect(v, false);
+            }
+        }
+    };
+    const r = (recipe ?? {});
+    collect(r.base, true);
+    collect(r.variants, false);
+    collect(r.states, false);
+    collect(r.parts, false);
+    const usage = Array.isArray(r.usage)
+        ? r.usage.filter((x) => typeof x === "string")
+        : [];
+    return { props, baseValues, usage };
+}
+/**
+ * How many places each known component is used. An inventory nobody has today:
+ * a design system's own report can say "ds-button, 14 places" because it knows
+ * which names are components rather than guessing at class strings.
+ */
+export function countComponents(source, known) {
+    const out = new Map();
+    for (const m of source.matchAll(DS_IN_CLASS)) {
+        if (!known.has(m[1]))
+            continue;
+        out.set(m[1], (out.get(m[1]) ?? 0) + 1);
+    }
+    return out;
+}
+/**
+ * Tailwind utilities that plainly set a CSS property. Deliberately short:
+ * every entry here can produce an accusation, so anything ambiguous is left
+ * out. Being quiet and right beats being loud.
+ */
+const UTILITY = [
+    [
+        /^rounded(-(?:sm|md|lg|xl|2xl|3xl|full|none))?$|^rounded-\[/,
+        "border-radius",
+    ],
+    [/^p-|^px-|^py-|^pt-|^pr-|^pb-|^pl-/, "padding"],
+    [/^gap-/, "gap"],
+    [/^bg-\[|^bg-(?!clip|blend|origin|repeat|fixed|local|scroll)/, "background"],
+    [/^shadow(-|$)/, "box-shadow"],
+    [
+        /^font-(?:thin|light|normal|medium|semibold|bold|extrabold|black)$/,
+        "font-weight",
+    ],
+    [/^(?:text|font)-\[/, "font-size"],
+    [/^tracking-/, "letter-spacing"],
+    [/^border-\[|^border-\d/, "border-width"],
+];
+function utilityProp(cls) {
+    for (const [re, prop] of UTILITY)
+        if (re.test(cls))
+            return prop;
+    return null;
+}
+const DS_IN_CLASS = /\bds-([a-z][a-z0-9-]*)\b/g;
+const clip = (s) => (s.length > 84 ? `${s.slice(0, 81)}...` : s);
+/**
+ * The tag around an offset. JSX puts `className` and `style` on separate
+ * lines constantly, so a line-scoped check would miss the common case; a
+ * bounded scan to the enclosing `<…>` is both simple and accurate.
+ */
+function enclosingTag(src, at) {
+    const open = src.lastIndexOf("<", at);
+    if (open === -1)
+        return null;
+    let depth = 0;
+    for (let i = open; i < src.length && i < open + 4000; i++) {
+        const c = src[i];
+        if (c === "{")
+            depth++;
+        else if (c === "}")
+            depth--;
+        else if (c === ">" && depth <= 0)
+            return { text: src.slice(open, i), start: open };
+    }
+    return null;
+}
+const lineAt = (src, index) => src.slice(0, index).split("\n").length;
+export function findOverrides(source, recipes) {
+    const out = [];
+    const lines = source.split("\n");
+    const seen = new Set();
+    const record = (o) => {
+        const key = `${o.component}:${o.prop}:${o.line}`;
+        if (seen.has(key))
+            return;
+        seen.add(key);
+        out.push(o);
+    };
+    // ── JSX: a ds-* class and a local style on the same element ───────────────
+    for (const m of source.matchAll(DS_IN_CLASS)) {
+        const name = m[1];
+        const bind = recipes.get(name);
+        if (!bind)
+            continue;
+        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;
+            record({
+                component: name,
+                prop,
+                wrote: s[2].trim().replace(/^["']|["']$/g, ""),
+                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() ?? ""),
+            });
+        }
+        // utility classes sitting beside the ds-* class
+        for (const cls of tag.text.matchAll(/[\w:[\]#().%/-]+/g)) {
+            const prop = utilityProp(cls[0]);
+            if (!prop || !bind.props.has(prop))
+                continue;
+            record({
+                component: name,
+                prop,
+                wrote: cls[0],
+                recipe: bind.baseValues.get(prop) ?? null,
+                line: lineAt(source, tag.start + (cls.index ?? 0)),
+                excerpt: clip(lines[lineAt(source, tag.start + (cls.index ?? 0)) - 1]?.trim() ?? ""),
+            });
+        }
+    }
+    // ── CSS: a rule whose selector reaches a ds-* component ───────────────────
+    for (const rule of source.matchAll(/([^{}]+)\{([^{}]*)\}/g)) {
+        const selector = rule[1];
+        const hit = /\.ds-([a-z][a-z0-9-]*)\b/.exec(selector);
+        const bind = hit ? recipes.get(hit[1]) : undefined;
+        if (!hit || !bind)
+            continue;
+        for (const decl of rule[2].matchAll(/([a-z-]+)\s*:\s*([^;]+)/g)) {
+            const prop = decl[1].trim();
+            if (!bind.props.has(prop))
+                continue;
+            // Reading the system back is the opposite of overruling it.
+            if (decl[2].includes("var(--ds-"))
+                continue;
+            const at = (rule.index ?? 0) + rule[1].length + (decl.index ?? 0);
+            record({
+                component: hit[1],
+                prop,
+                wrote: decl[2].trim(),
+                recipe: bind.baseValues.get(prop) ?? null,
+                line: lineAt(source, at),
+                excerpt: clip(lines[lineAt(source, at) - 1]?.trim() ?? ""),
+            });
+        }
+    }
+    return out.sort((a, b) => a.line - b.line);
+}
+/** Recipes from an installed `design-system.json`, as bindings. */
+export function bindingsFromDocument(doc) {
+    const out = new Map();
+    const comps = doc?.components;
+    if (!comps)
+        return out;
+    for (const [name, recipe] of Object.entries(comps)) {
+        out.set(name, bindingsOf(recipe));
+    }
+    return out;
+}

package/dist/index.js

@@ -27,7 +27,8 @@ Usage - deterministic, FREE:
   synthesisui use <slug> "<intent>"        print a ready-to-paste agent prompt to build/modify on-system
   synthesisui clean [--force]              strip create-next-app boilerplate (dry run without --force)
   synthesisui doctor [--strict] [--all]    audit this repo for DRIFT: every design value written by
-                                           hand, and the token your system already has for it
+                                           hand, the token your system already has for it, and the
+                                           laws your system carries for what you use
 
 Usage - AI, USES CREDITS (login required):
   synthesisui generate "<desc>"            AI-create a NEW component your DS doesn't have (token-only recipe)
@@ -53,6 +54,7 @@ Options:
   --force            clean: apply the changes (without it, dry run)
   --strict           doctor: exit 1 when drift is found (for CI)
   --all              doctor: list every finding, not just the loudest files
+  --laws             doctor: show every usage law, not just the busiest components
   --out <path>       output path for the generated template (default: <pagesDir>/<file>)
   -h, --help         this help
 
@@ -122,6 +124,7 @@ async function main() {
                 dir,
                 strict: flags.strict === true,
                 all: flags.all === true,
+                laws: flags.laws === true,
             });
             break;
         case "list":

package/package.json

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