synthesisui 0.7.0 → 0.8.1

package/dist/commands/doctor.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
@@ -185,11 +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 = [];
     const used = new Map();
     const known = new Set(recipes.keys());
-    for await (const file of walk(root)) {
+    for await (const file of scopes.length > 0 ? walkAll(scopes) : walk(root)) {
         const src = await readFile(file, "utf8").catch(() => "");
         if (!src)
             continue;
@@ -212,6 +224,21 @@ 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 (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;
@@ -281,8 +308,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`);

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,77 @@ 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.
+ *
+ * `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");
@@ -137,19 +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;
-            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() ?? ""),
-            });
+        // 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)) {
@@ -161,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() ?? ""),
             });
@@ -168,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)
@@ -186,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/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,7 +26,7 @@ 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
+  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
 
@@ -63,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
@@ -120,8 +121,11 @@ 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,

package/package.json

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