synthesisui 0.5.0 → 0.6.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

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, 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",
@@ -150,13 +169,20 @@ 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 = [];
     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 });
+        }
     }
     if (reports.length === 0) {
         console.log(`\nNothing to read in ${root}.\n`);
@@ -215,10 +241,40 @@ 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.`));
+        }
+    }
     console.log(section("What this means"));
     for (const line of verdict(d, hasSystem))
         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,189 @@
+/**
+ * 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);
+    return { props, baseValues };
+}
+/**
+ * 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/package.json

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