synthesisui 0.7.0 → 0.8.0

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;

package/dist/doctor/overrides.js

@@ -117,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");
@@ -142,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,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.0",
   "description": "Bring SynthesisUI design systems into any project - tokens, typed components, whole pages and an agent-ready CLAUDE.md manifest.",
   "type": "module",
   "bin": {