synthesisui 0.6.0 → 0.8.0

package/README.md

@@ -99,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,6 +1,6 @@
 import { readdir, readFile } from "node:fs/promises";
 import { join, relative, resolve } from "node:path";
-import { bindingsFromDocument, findOverrides, } from "../doctor/overrides.js";
+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";
@@ -59,6 +59,17 @@ async function* walk(dir) {
         }
     }
 }
+/** The same walk over several roots, in the order the caller named them. A
+ *  single file passed as a scope is read as itself. */
+async function* walkAll(roots) {
+    for (const r of roots) {
+        if (EXTS.some((x) => r.endsWith(x))) {
+            yield r;
+            continue;
+        }
+        yield* walk(r);
+    }
+}
 /** 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
@@ -132,7 +143,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) {
@@ -152,12 +163,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."),
@@ -171,9 +196,12 @@ 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 scopes = (opts.scopes ?? []).map((s) => resolve(root, s));
     const reports = [];
     const overrides = [];
-    for await (const file of walk(root)) {
+    const used = new Map();
+    const known = new Set(recipes.keys());
+    for await (const file of scopes.length > 0 ? walkAll(scopes) : walk(root)) {
         const src = await readFile(file, "utf8").catch(() => "");
         if (!src)
             continue;
@@ -182,6 +210,9 @@ export async function doctor(opts) {
         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) {
@@ -193,7 +224,25 @@ 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) {
+    if (scopes.length > 0) {
+        console.log(body(`scope: ${opts.scopes?.join(", ")}`));
+    }
+    // What a token could never have held, said out loud. A report that quietly
+    // drops things is only trustworthy until someone notices, and then it is
+    // worth less than one that says too much.
+    const aside = new Map();
+    for (const r of reports) {
+        if (!r.setAside)
+            continue;
+        aside.set(r.setAside.reason, (aside.get(r.setAside.reason) ?? 0) + r.setAside.count);
+    }
+    for (const [reason, count] of aside) {
+        console.log(body(`set aside: ${count} value(s) in ${reason}`));
+    }
+    // 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`));
@@ -271,8 +320,34 @@ export async function doctor(opts) {
             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 || overrides.length > 0))

package/dist/doctor/overrides.js

@@ -46,7 +46,24 @@ export function bindingsOf(recipe) {
     collect(r.variants, false);
     collect(r.states, false);
     collect(r.parts, false);
-    return { props, baseValues };
+    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:
@@ -100,6 +117,28 @@ function enclosingTag(src, at) {
     return null;
 }
 const lineAt = (src, index) => src.slice(0, index).split("\n").length;
+/**
+ * The literal a style property was given, or null when it was given an
+ * expression instead.
+ *
+ * `style={{ width: w }}` passes a variable; `transform: shown ? "a" : "b"`
+ * passes a ternary. Neither is a value the author hardcoded over the recipe,
+ * and reporting them as "the recipe binds 100%" was noise on a real project
+ * (investidorez, 25/07). Only a quoted string or a bare number is an override
+ * anyone can act on.
+ */
+function literalValue(raw) {
+    const v = raw.trim();
+    const quoted = /^(["'])([\s\S]*)\1$/.exec(v);
+    if (quoted) {
+        // a template that interpolates is decided at runtime, not here
+        return quoted[2].includes("${") ? null : quoted[2];
+    }
+    if (v.startsWith("`"))
+        return null;
+    // bare numbers are valid in a JSX style object (padding: 8)
+    return /^-?\d*\.?\d+(px|rem|em|%|vh|vw|ch|s|ms)?$/.test(v) ? v : null;
+}
 export function findOverrides(source, recipes) {
     const out = [];
     const lines = source.split("\n");
@@ -125,10 +164,13 @@ export function findOverrides(source, recipes) {
             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: s[2].trim().replace(/^["']|["']$/g, ""),
+                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() ?? ""),

package/dist/doctor/scan.js

@@ -10,6 +10,17 @@
  * takes eight seconds and needs a build step is a diagnosis nobody runs.
  */
 import { tokenFor } from "./tokens.js";
+/**
+ * `next/og` renders JSX to a PNG on the server. There is no document, so there
+ * is no `var(--ds-*)` to read: every colour in such a file MUST be a literal.
+ * Telling the author to tokenize it is telling them to break the build
+ * (investidorez, 25/07 - two files, nineteen impossible findings).
+ */
+const RENDERS_IMAGE = /from\s+["']next\/og["']|\bnew\s+ImageResponse\b/;
+/** A colour sitting on an SVG paint attribute is artwork - a brand mark, an
+ *  illustration. Google's logo contributed four "fix me" lines to a real
+ *  report; no design system should own those four hexes. */
+const SVG_PAINT = /(?:fill|stroke)\s*[=:]\s*["']?$/;
 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|\/\/|\*|\/\*)/;
@@ -34,10 +45,32 @@ const IDIOM = new Set(["0", "0px", "1px", "9999px", "100%", "50%"]);
 export function scanSource(file, source, table) {
     const findings = [];
     let tokenUses = 0;
+    let aside = 0;
+    if (RENDERS_IMAGE.test(source)) {
+        return {
+            file,
+            findings: [],
+            tokenUses: 0,
+            setAside: {
+                reason: "renders to an image, where CSS variables do not exist",
+                count: (source.match(COLOR) ?? []).length,
+            },
+        };
+    }
+    let svgDepth = 0;
     source.split("\n").forEach((raw, i) => {
         const line = raw.trim();
         const at = i + 1;
         tokenUses += (line.match(TOKEN_USE) ?? []).length;
+        // Depth at the START of this line, carried before the early return so a
+        // blank line inside an <svg> cannot close the region by accident. The
+        // per-match depth is recomputed below, because an icon is often written on
+        // one line - `<svg><path fill="#4285F4"/></svg>` opens and closes around
+        // the value, and a line-level counter reads zero right where it matters.
+        const lineStart = svgDepth;
+        svgDepth = Math.max(0, svgDepth +
+            (line.match(/<svg\b/g) ?? []).length -
+            (line.match(/<\/svg>/g) ?? []).length);
         if (!line || IGNORE_LINE.test(line))
             return;
         // `rgba(${r}, ${g}, ${b}, ${a})` is code computing a colour, not a colour
@@ -60,8 +93,18 @@ export function scanSource(file, source, table) {
                 excerpt: clip(line),
             });
         };
-        for (const m of line.matchAll(COLOR))
+        for (const m of line.matchAll(COLOR)) {
+            const before = line.slice(0, m.index ?? 0);
+            const depthHere = lineStart +
+                (before.match(/<svg\b/g) ?? []).length -
+                (before.match(/<\/svg>/g) ?? []).length;
+            // inside an <svg>, a colour on fill= or stroke= is paint, not surface
+            if (depthHere > 0 && SVG_PAINT.test(before)) {
+                aside++;
+                continue;
+            }
             push("color", m[0]);
+        }
         for (const m of line.matchAll(RADIUS)) {
             const value = `${m[1]}${m[2]}`;
             if (!IDIOM.has(value))
@@ -80,7 +123,14 @@ export function scanSource(file, source, table) {
             push("font", stack);
         }
     });
-    return { file, findings, tokenUses };
+    return {
+        file,
+        findings,
+        tokenUses,
+        ...(aside > 0
+            ? { setAside: { reason: "SVG artwork", count: aside } }
+            : null),
+    };
 }
 export function diagnose(files) {
     const flat = files.flatMap((f) => f.findings.map((x) => ({ ...x, file: f.file })));

package/dist/document-diff.js

@@ -46,7 +46,30 @@ function deepEqual(a, b) {
     }
     return false;
 }
-/** Variant options that existed and disappeared (breaking for the consumer). */
+/**
+ * Did this variant option ever put a declaration on the page? An option like
+ * `{ "tone": { "default": {} } }` compiles to nothing, so nothing in the
+ * consumer's app can depend on it.
+ */
+function declaresAnything(node) {
+    if (node === null || node === undefined)
+        return false;
+    if (typeof node !== "object")
+        return String(node).trim().length > 0;
+    if (Array.isArray(node))
+        return node.some(declaresAnything);
+    return Object.values(node).some(declaresAnything);
+}
+/**
+ * Variant options that existed, disappeared, AND used to render something.
+ *
+ * Vesper v2 → v15 announced ten breaking changes ("input no longer supports
+ * tone", and nine more). Every one of them was `{ tone: { default: {} } }` - an
+ * axis with a single empty option that emitted zero CSS. Removing it could not
+ * break an app, but the brief sent the consumer's agent hunting for `tone=`
+ * props that never existed (investidorez, 25/07). Housekeeping and a breaking
+ * change now read differently, because they are different.
+ */
 function removedVariantOptions(before, after) {
     const out = [];
     const prevVariants = (before.variants ?? {});
@@ -54,11 +77,14 @@ function removedVariantOptions(before, after) {
     for (const [axis, options] of Object.entries(prevVariants)) {
         const nextAxis = nextVariants[axis];
         if (!nextAxis) {
-            out.push(axis);
+            if (declaresAnything(options))
+                out.push(axis);
             continue;
         }
-        for (const option of Object.keys(options)) {
-            if (!(option in nextAxis))
+        for (const [option, decls] of Object.entries(options)) {
+            if (option in nextAxis)
+                continue;
+            if (declaresAnything(decls))
                 out.push(`${axis}="${option}"`);
         }
     }

package/dist/index.js

@@ -26,8 +26,9 @@ 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
+  synthesisui doctor [paths…] [--all]      audit for DRIFT: every design value written by
+                                           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
 
@@ -61,6 +63,7 @@ Examples:
   synthesisui init --target next
   synthesisui init --target next --ds halogen   bootstrap + bring a system in
   synthesisui doctor
+  synthesisui doctor apps/web packages/ui   # scope the read in a monorepo
   synthesisui doctor --strict
   synthesisui list
   synthesisui add halogen
@@ -118,10 +121,14 @@ async function main() {
     const dir = typeof flags.dir === "string" ? flags.dir : undefined;
     switch (command) {
         case "doctor":
+            // positional paths scope the READING (the system is still found from the
+            // root): `doctor apps/web packages/ui` in a monorepo
             await doctor({
                 dir,
+                scopes: args,
                 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.6.0",
+  "version": "0.8.0",
   "description": "Bring SynthesisUI design systems into any project - tokens, typed components, whole pages and an agent-ready CLAUDE.md manifest.",
   "type": "module",
   "bin": {