synthesisui 0.4.13 → 0.6.0

package/README.md

@@ -38,6 +38,69 @@ your own in two minutes.
 | `refit <file>` | Send an app component back into your design system |
 | `upgrade <slug>` | Diff your `.lock` against the latest version and migrate |
 | `clean` | Remove materialized files and the managed CLAUDE.md block |
+| `doctor` | Audit the repo for drift: every design value written by hand, and the token your system already has for it |
+
+## `doctor`
+
+Every tool in this space promises output that is brand consistent and free of
+drift. None of them checks. This checks, in the only place it can be true -
+the code that shipped.
+
+```
+npx synthesisui@latest doctor
+```
+
+```
+── Doctor ────────────────────────────────────────────────────────
+
+  Aluna v1 - 91 tokens, 53 files read
+
+  Token coverage  ████████████████████████   98%
+                  2019 from the system, 34 by hand
+
+── Drift ─────────────────────────────────────────────────────────
+
+  26  colour
+   8  spacing
+
+  app/welcome2/_components/signature.tsx
+        19  #8b8bf1  → --ds-color-blue-500
+        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
+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 `add` materializes
 

package/dist/commands/doctor.js

@@ -0,0 +1,280 @@
+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";
+/**
+ * `synthesisui doctor` - the check nobody else ships.
+ *
+ * Every generator in this market now promises "brand consistent, no drift".
+ * Not one of them verifies it. This does, in the only place it can be true:
+ * the code that actually shipped.
+ *
+ * Two audiences, one command:
+ *
+ * - With a system installed, it does the thing that cannot be faked - it names
+ *   the project's OWN token for the value someone hardcoded. "#2563eb, which
+ *   your system calls --ds-color-semantic-info." Nothing generic; the
+ *   diagnosis is in their vocabulary.
+ * - With no system installed, it still finds every hand-written design value
+ *   and counts the distinct ones. That number IS the pitch, and it costs the
+ *   reader nothing to get.
+ *
+ * Runs offline, needs no account, and touches nothing. A tool that asks for a
+ * signup before it tells you anything is a tool nobody runs twice.
+ */
+const EXTS = [".tsx", ".ts", ".jsx", ".js", ".css", ".scss", ".vue", ".svelte"];
+const SKIP = new Set([
+    "node_modules",
+    ".next",
+    ".git",
+    "dist",
+    "build",
+    "out",
+    "coverage",
+    ".turbo",
+    ".vercel",
+    // Our own installed artifacts are the answer, not the problem.
+    "_synthesisui",
+]);
+async function* walk(dir) {
+    // `readdir`'s overloads infer a Buffer-named Dirent without an explicit
+    // encoding; naming it keeps `e.name` a string.
+    const entries = await readdir(dir, {
+        withFileTypes: true,
+        encoding: "utf8",
+    }).catch(() => []);
+    for (const e of entries) {
+        if (e.name.startsWith(".") && e.name !== ".")
+            continue;
+        const full = join(dir, e.name);
+        if (e.isDirectory()) {
+            if (SKIP.has(e.name))
+                continue;
+            yield* walk(full);
+        }
+        else if (EXTS.some((x) => e.name.endsWith(x))) {
+            yield full;
+        }
+    }
+}
+/** 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;
+    try {
+        slugs = (await readdir(dsDir, { withFileTypes: true }))
+            .filter((e) => e.isDirectory())
+            .map((e) => e.name);
+    }
+    catch {
+        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(() => "");
+        let mine = null;
+        try {
+            mine = raw ? JSON.parse(raw) : null;
+        }
+        catch {
+            mine = null;
+        }
+        lock ??= mine;
+        // The file at the root is a POINTER - `@import "./v1/tokens.css"` - so the
+        // pinned folder is where the declarations actually live. Read that first,
+        // and fall back to following whatever the root imports, for a project that
+        // pinned by hand.
+        const root = await readFile(join(dir, "tokens.css"), "utf8").catch(() => "");
+        let real = mine?.version
+            ? await readFile(join(dir, `v${mine.version}`, "tokens.css"), "utf8").catch(() => "")
+            : "";
+        if (!real) {
+            for (const m of root.matchAll(/@import\s+["']([^"']+)["']/g)) {
+                real += `\n${await readFile(join(dir, m[1]), "utf8").catch(() => "")}`;
+            }
+        }
+        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 { table: buildTable({ css, lock }), recipes };
+}
+const KIND_LABEL = {
+    color: "colour",
+    radius: "radius",
+    spacing: "spacing",
+    font: "type",
+};
+/** A bar you can read at a glance, in a font that is always monospace. */
+function meter(pct, width = 24) {
+    const filled = Math.round((pct / 100) * width);
+    return `${"█".repeat(filled)}${"░".repeat(width - filled)}`;
+}
+function verdict(d, hasSystem) {
+    // 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) {
+        return [
+            body("No design values are written by hand here, and no system is"),
+            body("installed. Nothing to fix, and nothing to compare against."),
+        ];
+    }
+    if (!hasSystem) {
+        const distinct = new Set(d.findings.map((f) => f.literal.toLowerCase()));
+        return [
+            body(`${distinct.size} distinct design values are written by hand here.`),
+            body("No design system is installed, so none of them has a name yet."),
+            "",
+            body("Give them one:"),
+            snippet(["npx synthesisui@latest init --ds <slug>"]),
+            body("Browse systems at https://www.synthesisui.com/gallery"),
+        ];
+    }
+    if (d.findings.length === 0) {
+        return [
+            body("No drift. Every design value in this project comes from the"),
+            body("system. That is a rarer sentence than it sounds."),
+        ];
+    }
+    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."),
+    ];
+    if (d.findings.length > d.named) {
+        lines.push("", body(`The other ${d.findings.length - d.named} are decisions your system has not made yet.`), body("Either they belong in it, or they should not be in the code."));
+    }
+    return lines;
+}
+export async function doctor(opts) {
+    const root = resolve(opts.dir ?? process.cwd());
+    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)
+            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`);
+        return;
+    }
+    const d = diagnose(reports);
+    console.log(section("Doctor"));
+    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) {
+        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`));
+    }
+    if (d.findings.length > 0) {
+        console.log(section("Drift"));
+        const order = ["color", "radius", "spacing", "font"].filter((k) => d.counts[k] > 0);
+        for (const kind of order) {
+            console.log(body(`${d.counts[kind]}  ${KIND_LABEL[kind]}`));
+        }
+        // What a person actually acts on first: the value repeated everywhere.
+        // One decision here retires dozens of sites, and a list sorted by file
+        // never tells you that.
+        const repeats = d.repeats.slice(0, 5);
+        if (repeats.length > 0) {
+            console.log("");
+            console.log(body("Most repeated"));
+            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}` : "";
+                console.log(`      ${r.literal.padEnd(w)}  ${where}${named}`);
+            }
+        }
+        // Loudest files first: drift concentrates, and the fix is usually one
+        // shared component rather than two hundred call sites.
+        const files = [...d.files].sort((a, b) => b.findings.length - a.findings.length);
+        const shownFiles = opts.all ? files : files.slice(0, 8);
+        console.log("");
+        for (const f of shownFiles) {
+            console.log(body(`${f.file}`));
+            const shown = opts.all ? f.findings : f.findings.slice(0, 3);
+            for (const x of shown) {
+                const named = x.token
+                    ? `→ ${x.token}`
+                    : "→ no token holds this value yet";
+                console.log(`      ${String(x.line).padStart(4)}  ${x.literal}  ${named}`);
+            }
+            if (f.findings.length > shown.length) {
+                console.log(`            +${f.findings.length - shown.length} more`);
+            }
+            console.log("");
+        }
+        if (files.length > shownFiles.length) {
+            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 || 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/dist/doctor/scan.js

@@ -0,0 +1,134 @@
+/**
+ * DOCTOR · finding the drift.
+ *
+ * Drift is the market's own word - every generator now promises "brand
+ * consistent, no drift" and not one of them checks. This is the check: a
+ * literal design value written by hand where the project's system already has
+ * a name for it.
+ *
+ * Text in, findings out. No filesystem, no AST, no network - a diagnosis that
+ * takes eight seconds and needs a build step is a diagnosis nobody runs.
+ */
+import { tokenFor } from "./tokens.js";
+const clip = (s) => (s.length > 84 ? `${s.slice(0, 81)}...` : s);
+/** Lines we must not read as authorship: imports, and our own installed CSS. */
+const IGNORE_LINE = /^\s*(import|@import|\/\/|\*|\/\*)/;
+/**
+ * Colour literals, in the two dialects a component file actually mixes:
+ * plain CSS values and Tailwind arbitrary values (`bg-[#2563eb]`).
+ * `#` inside a URL fragment or an id selector is excluded by requiring a full
+ * 3/6/8 digit run terminated by a non-hex character.
+ */
+const COLOR = /#[0-9a-fA-F]{8}\b|#[0-9a-fA-F]{6}\b|#[0-9a-fA-F]{3}\b|rgba?\([^)]*\)|hsla?\([^)]*\)/g;
+/** `rounded-[14px]`, `border-radius: 14px`. Zero and full pills are idiom,
+ *  not drift - nobody tokenizes `0` or `9999px`. */
+const RADIUS = /(?:border-radius\s*:\s*|rounded(?:-[a-z]+)?-\[)(-?\d*\.?\d+)(px|rem|em)/g;
+/** Arbitrary spacing: `p-[18px]`, `gap-[7px]`, `margin: 18px`. */
+const SPACING = /(?:\b[pmg](?:[trblxy])?-\[|gap-\[|(?:padding|margin|gap)\s*:\s*)(-?\d*\.?\d+)(px|rem)/g;
+/** A font stack written by hand rather than taken from the type scale. */
+const FONT = /font-family\s*:\s*([^;}\n]+)/g;
+/** Uses of the system. Coverage is meaningless without them. */
+const TOKEN_USE = /var\(\s*--ds-[a-z0-9-]+/gi;
+/** Under this, a radius or spacing value is idiom rather than a decision. */
+const IDIOM = new Set(["0", "0px", "1px", "9999px", "100%", "50%"]);
+export function scanSource(file, source, table) {
+    const findings = [];
+    let tokenUses = 0;
+    source.split("\n").forEach((raw, i) => {
+        const line = raw.trim();
+        const at = i + 1;
+        tokenUses += (line.match(TOKEN_USE) ?? []).length;
+        if (!line || IGNORE_LINE.test(line))
+            return;
+        // `rgba(${r}, ${g}, ${b}, ${a})` is code computing a colour, not a colour
+        // written by hand - flagging it would be telling someone to tokenize a
+        // variable. And the same literal twice in one declaration (a two-stop
+        // shadow) is one decision, so it is reported once.
+        const seen = new Set();
+        const push = (kind, literal) => {
+            if (literal.includes("$") || literal.includes("{"))
+                return;
+            const key = `${kind}:${literal}`;
+            if (seen.has(key))
+                return;
+            seen.add(key);
+            findings.push({
+                kind,
+                line: at,
+                literal,
+                token: tokenFor(table, literal),
+                excerpt: clip(line),
+            });
+        };
+        for (const m of line.matchAll(COLOR))
+            push("color", m[0]);
+        for (const m of line.matchAll(RADIUS)) {
+            const value = `${m[1]}${m[2]}`;
+            if (!IDIOM.has(value))
+                push("radius", value);
+        }
+        for (const m of line.matchAll(SPACING)) {
+            const value = `${m[1]}${m[2]}`;
+            if (!IDIOM.has(value))
+                push("spacing", value);
+        }
+        for (const m of line.matchAll(FONT)) {
+            const stack = m[1].trim();
+            // A stack already reading from the system is the point, not a problem.
+            if (stack.startsWith("var("))
+                continue;
+            push("font", stack);
+        }
+    });
+    return { file, findings, tokenUses };
+}
+export function diagnose(files) {
+    const flat = files.flatMap((f) => f.findings.map((x) => ({ ...x, file: f.file })));
+    const counts = {
+        color: 0,
+        radius: 0,
+        spacing: 0,
+        font: 0,
+    };
+    for (const f of flat)
+        counts[f.kind] += 1;
+    const tokenUses = files.reduce((n, f) => n + f.tokenUses, 0);
+    const total = tokenUses + flat.length;
+    const byLiteral = new Map();
+    for (const f of flat) {
+        const key = `${f.kind}:${f.literal.toLowerCase()}`;
+        const hit = byLiteral.get(key);
+        if (hit) {
+            hit.count += 1;
+            hit.files.add(f.file);
+        }
+        else {
+            byLiteral.set(key, {
+                kind: f.kind,
+                token: f.token,
+                count: 1,
+                files: new Set([f.file]),
+            });
+        }
+    }
+    const repeats = [...byLiteral.entries()]
+        .map(([key, v]) => ({
+        literal: key.slice(key.indexOf(":") + 1),
+        kind: v.kind,
+        token: v.token,
+        count: v.count,
+        files: v.files.size,
+    }))
+        .filter((r) => r.count > 1)
+        .sort((a, b) => b.count - a.count);
+    return {
+        files: files.filter((f) => f.findings.length > 0),
+        findings: flat,
+        counts,
+        named: flat.filter((f) => f.token).length,
+        tokenUses,
+        coverage: total === 0 ? 100 : Math.round((tokenUses / total) * 100),
+        scanned: files.length,
+        repeats,
+    };
+}

package/dist/doctor/tokens.js

@@ -0,0 +1,92 @@
+/**
+ * DOCTOR · the installed system, read back out of the project.
+ *
+ * `add` writes `_synthesisui/ds/<slug>/tokens.css` and a `.lock` naming the
+ * pinned version. Doctor reads them so it can do the thing nothing else in
+ * this market does: not merely flag a hardcoded value, but say what the
+ * project's OWN system already calls it.
+ *
+ *   #2563eb  →  --ds-color-semantic-info
+ *
+ * Pure and dependency-free on purpose: every function here takes text and
+ * returns data, so the whole diagnosis is testable without a filesystem.
+ */
+export const EMPTY_TABLE = {
+    name: null,
+    slug: null,
+    version: null,
+    byName: new Map(),
+    byValue: new Map(),
+};
+/** Lowercase, collapse whitespace, expand #abc to #aabbcc - so `#FFF`,
+ *  `#ffffff` and `# fff` all land on one key. */
+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 rgb = /^rgba?\(([^)]+)\)$/.exec(v);
+    if (rgb) {
+        const parts = rgb[1].split(/[\s,/]+/).filter(Boolean);
+        return `rgb(${parts.join(" ")})`;
+    }
+    return v;
+}
+/**
+ * Pull `--ds-*: value;` declarations out of a stylesheet.
+ *
+ * A regex rather than a CSS parser: tokens.css is emitted by us, one
+ * declaration per line, and a dependency-free CLI that starts instantly is
+ * worth more here than tolerating stylesheets we did not write.
+ */
+export function parseTokens(css) {
+    const out = new Map();
+    for (const m of css.matchAll(/(--ds-[a-z0-9-]+)\s*:\s*([^;}]+)[;}]/gi)) {
+        const name = m[1].toLowerCase();
+        const value = m[2].trim();
+        // A token pointing at another token is an alias, not a literal we can
+        // match a hardcoded colour against.
+        if (value.startsWith("var("))
+            continue;
+        if (!out.has(name))
+            out.set(name, value);
+    }
+    return out;
+}
+export function buildTable(input) {
+    const byName = parseTokens(input.css);
+    const byValue = new Map();
+    for (const [name, value] of byName) {
+        const key = normalizeValue(value);
+        const list = byValue.get(key);
+        if (list)
+            list.push(name);
+        else
+            byValue.set(key, [name]);
+    }
+    return {
+        name: input.lock?.name ?? null,
+        slug: input.lock?.slug ?? null,
+        version: input.lock?.version ?? null,
+        byName,
+        byValue,
+    };
+}
+/**
+ * The token that already holds this literal, if the project has one.
+ *
+ * Exact match only. A "nearest colour" guess would be the single most
+ * dangerous thing this tool could do: telling somebody their `#2563ec` is
+ * "basically" `--ds-color-semantic-info` invites a silent visual change, and
+ * a diagnosis nobody can trust is worse than no diagnosis. Near misses are
+ * reported as drift, not as a fix.
+ */
+export function tokenFor(table, literal) {
+    const hit = table.byValue.get(normalizeValue(literal));
+    if (!hit || hit.length === 0)
+        return null;
+    // Semantic roles name intent; primitives name a shelf. Prefer intent.
+    const semantic = hit.find((n) => n.includes("-semantic-"));
+    return semantic ?? hit[0];
+}

package/dist/index.js

@@ -3,6 +3,7 @@ import { add } from "./commands/add.js";
 import { advise } from "./commands/advise.js";
 import { clean } from "./commands/clean.js";
 import { component } from "./commands/component.js";
+import { doctor } from "./commands/doctor.js";
 import { generate } from "./commands/generate.js";
 import { init } from "./commands/init.js";
 import { list } from "./commands/list.js";
@@ -25,6 +26,8 @@ Usage - deterministic, FREE:
   synthesisui upgrade <slug>               update an installed DS + regenerate your components + migration brief
   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
 
 Usage - AI, USES CREDITS (login required):
   synthesisui generate "<desc>"            AI-create a NEW component your DS doesn't have (token-only recipe)
@@ -48,6 +51,8 @@ Options:
   --instruction <s>  refit: extra guidance for the adaptation
   --dry              refit: adapt and print, but save nothing
   --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
   --out <path>       output path for the generated template (default: <pagesDir>/<file>)
   -h, --help         this help
 
@@ -55,6 +60,8 @@ Examples:
   synthesisui login
   synthesisui init --target next
   synthesisui init --target next --ds halogen   bootstrap + bring a system in
+  synthesisui doctor
+  synthesisui doctor --strict
   synthesisui list
   synthesisui add halogen
   synthesisui add halogen --version 3
@@ -110,6 +117,13 @@ async function main() {
     const registry = typeof flags.registry === "string" ? flags.registry : undefined;
     const dir = typeof flags.dir === "string" ? flags.dir : undefined;
     switch (command) {
+        case "doctor":
+            await doctor({
+                dir,
+                strict: flags.strict === true,
+                all: flags.all === true,
+            });
+            break;
         case "list":
             await list({ registry });
             break;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "synthesisui",
-  "version": "0.4.13",
+  "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": {
@@ -31,7 +31,8 @@
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "dev": "tsx src/index.ts",
-    "prepublishOnly": "npm run build"
+    "prepublishOnly": "npm run build",
+    "test": "vitest run"
   },
   "license": "MIT"
 }

package/dist/commands/page.js

@@ -1,42 +0,0 @@
-import { mkdir, writeFile } from "node:fs/promises";
-import { dirname, join } from "node:path";
-import { readProjectConfig, resolveRegistry } from "../config.js";
-import { fetchPage } from "../registry.js";
-/**
- * Materializes a whole page from a DS template into the project (hybrid
- * codegen-first): the server codegens deterministic files, we write them, and
- * the agent refines them in place. The page uses the DS's `.ds-*` classes +
- * path classes; the co-located CSS (Next target) carries the responsive media
- * queries + the CSS-only hamburger, so it re-vests once `tokens.css` is in.
- */
-export async function page(slug, template, opts) {
-    const base = resolveRegistry(opts.registry);
-    const root = opts.dir ?? process.cwd();
-    const config = await readProjectConfig(root);
-    const target = opts.target === "general" || opts.target === "next"
-        ? opts.target
-        : config.target;
-    console.log(`→ generating "${template}" from "${slug}" (${target}) …`);
-    const generated = await fetchPage(base, slug, template, target, opts.version);
-    // --out targets the page (1st file); sibling files (e.g. the CSS) land in the
-    // same directory. Without --out, everything goes under <pagesDir>.
-    const [pageFile, ...siblings] = generated.files;
-    const pageRel = opts.out ?? join(config.pagesDir, pageFile.filename);
-    const pageDir = dirname(join(root, pageRel));
-    await mkdir(pageDir, { recursive: true });
-    await writeFile(join(root, pageRel), pageFile.code, "utf8");
-    console.log(`✓ wrote ${pageRel}  (${slug} v${generated.version})`);
-    for (const f of siblings) {
-        const rel = opts.out
-            ? join(dirname(pageRel), f.filename)
-            : join(config.pagesDir, f.filename);
-        await writeFile(join(root, rel), f.code, "utf8");
-        console.log(`✓ wrote ${rel}`);
-    }
-    console.log("");
-    console.log("Next steps:");
-    console.log(`  • ensure the DS is installed: synthesisui add ${slug} (provides tokens.css)`);
-    console.log(`  • @import "_synthesisui/ds/${slug}/tokens.css" in your global CSS`);
-    console.log("  • refine the file: wire real data, split into components, swap placeholders");
-    console.log(`  • keep the data-ds="${slug}" wrapper and the ds-* / layout classes (stays on-system)`);
-}