synthesisui 0.11.2 → 0.12.0

package/dist/commands/doctor.js

@@ -252,6 +252,14 @@ export async function doctor(opts) {
         r.findings = r.findings.filter((f) => !explained.has(`${r.file}:${f.line}:${f.literal.toLowerCase()}`));
     }
     const d = diagnose(reports);
+    // Nine releases in one evening added a section each, every one justified on
+    // its own, and nobody read the whole. The result was 151 lines carrying about
+    // eight lines of meaning. Detail is now something you ask for.
+    const verbose = opts.verbose === true;
+    const say = (line) => {
+        if (verbose)
+            console.log(line);
+    };
     console.log(section("Doctor"));
     console.log(body(hasSystem
         ? `${table.name ?? table.slug} v${table.version ?? "?"} - ${table.byName.size} tokens, ${d.scanned} files read`
@@ -266,10 +274,18 @@ export async function doctor(opts) {
     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 a of r.setAside) {
+            aside.set(a.reason, (aside.get(a.reason) ?? 0) + a.count);
+        }
+    }
+    const asideTotal = [...aside.values()].reduce((n, v) => n + v, 0);
+    if (verbose) {
+        for (const [reason, count] of aside) {
+            console.log(body(`set aside: ${count} value(s) in ${reason}`));
+        }
     }
-    for (const [reason, count] of aside) {
-        console.log(body(`set aside: ${count} value(s) in ${reason}`));
+    else if (asideTotal > 0) {
+        console.log(body(`set aside ${asideTotal} value(s) a token could never hold (--verbose for why)`));
     }
     // 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.
@@ -280,18 +296,18 @@ export async function doctor(opts) {
         console.log(body(`                ${d.tokenUses} from the system, ${d.findings.length} by hand`));
     }
     if (d.findings.length > 0) {
-        console.log(section("Drift"));
+        say(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]}`));
+            say(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"));
+            say("");
+            say(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"}`;
@@ -301,17 +317,17 @@ export async function doctor(opts) {
                     : near
                         ? `  → nearest is ${near.name} (${near.value})`
                         : "";
-                console.log(`      ${r.literal.padEnd(w)}  ${where}${named}`);
+                say(`      ${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("");
+        const shownFiles = verbose ? files : files.slice(0, 8);
+        say("");
         for (const f of shownFiles) {
-            console.log(body(`${f.file}`));
-            const shown = opts.all ? f.findings : f.findings.slice(0, 3);
+            say(body(`${f.file}`));
+            const shown = verbose ? f.findings : f.findings.slice(0, 3);
             for (const x of shown) {
                 // A dead end with a neighbour is not a dead end. Only for lengths -
                 // "nearly the same blue" is the guess this tool must never make.
@@ -321,15 +337,15 @@ export async function doctor(opts) {
                     : near
                         ? `→ nearest is ${near.name} (${near.value})`
                         : "→ no token holds this value yet";
-                console.log(`      ${String(x.line).padStart(4)}  ${x.literal}  ${named}`);
+                say(`      ${String(x.line).padStart(4)}  ${x.literal}  ${named}`);
             }
             if (f.findings.length > shown.length) {
-                console.log(`            +${f.findings.length - shown.length} more`);
+                say(`            +${f.findings.length - shown.length} more`);
             }
-            console.log("");
+            say("");
         }
         if (files.length > shownFiles.length) {
-            console.log(body(`+${files.length - shownFiles.length} more files. Run with --all to see everything.`));
+            say(body(`+${files.length - shownFiles.length} more files. Run with --all to see everything.`));
         }
     }
     // Every other section asks whether the code obeys the system. This one asks
@@ -339,19 +355,19 @@ export async function doctor(opts) {
     const conflicts = documents.flatMap((doc) => findSelfConflicts(doc));
     const conflictsInUse = conflicts.filter((c) => used.has(c.component));
     if (conflictsInUse.length > 0) {
-        console.log(section("Your system contradicts itself"));
-        console.log(body(conflictsInUse.length === 1
+        say(section("Your system contradicts itself"));
+        say(body(conflictsInUse.length === 1
             ? "One component says one thing in prose and another in its recipe."
             : `${conflictsInUse.length} components say one thing in prose and another in their recipe.`));
-        console.log("");
+        say("");
         for (const c of conflictsInUse) {
-            console.log(body(`ds-${c.component}`));
-            console.log(`          "${c.law}"`);
-            console.log(`          but ${c.where} binds ${c.value}`);
-            console.log("");
+            say(body(`ds-${c.component}`));
+            say(`          "${c.law}"`);
+            say(`          but ${c.where} binds ${c.value}`);
+            say("");
         }
-        console.log(body("Whoever wrote the law and whoever wrote the recipe disagree."));
-        console.log(body("Until they do not, no code here can be correct."));
+        say(body("Whoever wrote the law and whoever wrote the recipe disagree."));
+        say(body("Until they do not, no code here can be correct."));
     }
     // The other way a system fails itself: a recipe that names a SHELF where the
     // system has a ROLE. The value is legitimate, the reference resolves, the CSS
@@ -360,22 +376,24 @@ export async function doctor(opts) {
         .flatMap((doc) => findFrozenBindings(doc))
         .filter((f) => used.has(f.component));
     if (frozen.length > 0) {
-        console.log(section("These will not follow your other scheme"));
-        console.log(body(frozen.length === 1
+        say(section("These will not follow your other scheme"));
+        say(body(frozen.length === 1
             ? "One recipe names a primitive where a role holds the same value."
             : `${frozen.length} recipes name a primitive where a role holds the same value.`));
-        console.log("");
+        say("");
         for (const f of frozen) {
-            console.log(body(`ds-${f.component} · ${f.where}`));
-            console.log(`          binds ${f.wrote}`);
-            console.log(`          {color.semantic.${f.role}} holds that, and becomes ${f.becomes}`);
-            console.log("");
+            say(body(`ds-${f.component} · ${f.where}`));
+            say(`          binds ${f.wrote}`);
+            say(`          {color.semantic.${f.role}} holds that, and becomes ${f.becomes}`);
+            say("");
         }
-        console.log(body("The value resolves and the CSS compiles, so nothing"));
-        console.log(body("complains - the surface just stays put when the scheme"));
-        console.log(body("moves around it."));
+        say(body("The value resolves and the CSS compiles, so nothing"));
+        say(body("complains - the surface just stays put when the scheme"));
+        say(body("moves around it."));
     }
     const frozenAt = new Set(frozen.map((f) => `${f.component}:${f.where.split(" · ").pop()}`));
+    let offSystemCount = 0;
+    let lawKeepingCount = 0;
     if (overrides.length > 0) {
         // An override on a property the component's own law FORBIDS, written as a
         // reset, is not drift - it is the author keeping a promise the recipe
@@ -404,6 +422,7 @@ export async function doctor(opts) {
         };
         const drifting = overrides.filter((o) => lawKept(o) === null);
         const correcting = overrides.length - drifting.length;
+        lawKeepingCount = correcting;
         /**
          * Two very different acts wearing one label. Choosing a DIFFERENT token
          * from the system is a decision inside the vocabulary - the recipe says
@@ -429,18 +448,19 @@ export async function doctor(opts) {
         // REMOVES what the recipe sets, and no token can hold "no transform".
         // Marking it as a raw value asked for something that cannot exist.
         const offSystem = drifting.filter((o) => !onSystem(o) && !isReset(o.wrote)).length;
-        console.log(section("Overruled"));
-        console.log(body(`${drifting.length} place${drifting.length === 1 ? "" : "s"} where the code takes a component`));
-        console.log(body("the system defines, and then overrules it locally."));
-        console.log("");
-        console.log(body(`${offSystem} of them leave the system entirely; the rest pick a different token.`));
+        offSystemCount = offSystem;
+        say(section("Overruled"));
+        say(body(`${drifting.length} place${drifting.length === 1 ? "" : "s"} where the code takes a component`));
+        say(body("the system defines, and then overrules it locally."));
+        say("");
+        say(body(`${offSystem} of them leave the system entirely; the rest pick a different token.`));
         if (correcting > 0) {
-            console.log("");
-            console.log(body(correcting === 1
+            say("");
+            say(body(correcting === 1
                 ? "One more overrules it to KEEP a law the recipe breaks - marked below."
                 : `${correcting} more overrule it to KEEP a law the recipe breaks - marked below.`));
         }
-        console.log("");
+        say("");
         const byFile = new Map();
         for (const o of overrides) {
             const list = byFile.get(o.file);
@@ -449,20 +469,20 @@ export async function doctor(opts) {
             else
                 byFile.set(o.file, [o]);
         }
-        const shown = opts.all ? [...byFile] : [...byFile].slice(0, 6);
+        const shown = verbose ? [...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}`);
+            say(body(file));
+            for (const o of verbose ? list : list.slice(0, 3)) {
+                say(`      ${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}`);
+                    say(`            the recipe binds ${o.recipe}`);
                 else if (o.where)
-                    console.log(`            the recipe binds it ${o.where}`);
+                    say(`            the recipe binds it ${o.where}`);
                 if (lawKept(o) === null && !onSystem(o)) {
-                    console.log(isReset(o.wrote)
+                    say(isReset(o.wrote)
                         ? "            ↑ removes it rather than replacing it"
                         : "            ↑ a raw value, not a token");
                 }
@@ -471,21 +491,21 @@ export async function doctor(opts) {
                 // that as an infraction is the same unfairness as the law case above.
                 if (frozenAt.has(`${o.component}:${o.prop}`) &&
                     /var\(\s*--ds-color-semantic-/.test(o.wrote)) {
-                    console.log("            ✓ the recipe is frozen here; yours names a role");
+                    say("            ✓ the recipe is frozen here; yours names a role");
                 }
                 const kept = lawKept(o);
                 if (kept) {
-                    console.log(`            ✓ but the law says: "${kept}"`);
-                    console.log("              this override keeps it - the recipe does not");
+                    say(`            ✓ but the law says: "${kept}"`);
+                    say("              this override keeps it - the recipe does not");
                 }
             }
-            if (!opts.all && list.length > 3) {
-                console.log(`            +${list.length - 3} more`);
+            if (!verbose && list.length > 3) {
+                say(`            +${list.length - 3} more`);
             }
-            console.log("");
+            say("");
         }
         if (byFile.size > shown.length) {
-            console.log(body(`+${byFile.size - shown.length} more files. Run with --all.`));
+            say(body(`+${byFile.size - shown.length} more files. Run with --all.`));
         }
     }
     // The system's own words, for the components this project actually uses.
@@ -496,28 +516,114 @@ export async function doctor(opts) {
         .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);
+        say(section("What your system says about what you use"));
+        const shownComps = opts.laws || verbose ? 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"}`));
+            const shown = opts.laws || verbose ? laws : laws.slice(0, 2);
+            say(body(`ds-${name}  ·  ${count} place${count === 1 ? "" : "s"}`));
             for (const law of shown)
-                console.log(`      ${law}`);
+                say(`      ${law}`);
             if (laws.length > shown.length) {
-                console.log(`      +${laws.length - shown.length} more`);
+                say(`      +${laws.length - shown.length} more`);
             }
-            console.log("");
+            say("");
         }
         if (inUse.length > shownComps.length) {
-            console.log(body(`+${inUse.length - shownComps.length} more components carry laws. Run with --laws.`));
-            console.log("");
+            say(body(`+${inUse.length - shownComps.length} more components carry laws. Run with --laws.`));
+            say("");
         }
     }
-    console.log(section("What this means"));
+    say(section("What this means"));
     for (const line of verdict(d, hasSystem, overrides.length, conflictsInUse.length))
-        console.log(line);
-    console.log("");
+        say(line);
+    say("");
+    const plan = [];
+    for (const c of conflictsInUse) {
+        plan.push({
+            rank: 0,
+            what: `the ds-${c.component} contradiction`,
+            size: `${used.get(c.component) ?? 0} places`,
+            cheap: false,
+        });
+    }
+    for (const f of frozen) {
+        plan.push({
+            rank: 1,
+            what: `the frozen ds-${f.component} ${f.where.split(" · ").pop()}`,
+            size: `${used.get(f.component) ?? 0} places`,
+            cheap: true,
+        });
+    }
+    if (offSystemCount > 0) {
+        plan.push({
+            rank: 2,
+            what: `the ${offSystemCount} override${offSystemCount === 1 ? "" : "s"} that left the system`,
+            size: `${offSystemCount} place${offSystemCount === 1 ? "" : "s"}`,
+            cheap: false,
+        });
+    }
+    for (const r of d.repeats.filter((x) => x.token).slice(0, 3)) {
+        plan.push({
+            rank: 3,
+            what: `${r.literal} → ${r.token}`,
+            size: `${r.files} file${r.files === 1 ? "" : "s"}`,
+            cheap: true,
+        });
+    }
+    for (const r of d.repeats.filter((x) => !x.token).slice(0, 2)) {
+        const near = nearestToken(table, r.literal);
+        plan.push({
+            rank: 4,
+            what: near
+                ? `${r.literal} - name it, or snap to ${near.name}`
+                : `${r.literal} - the system has no name for it`,
+            size: `${r.files} file${r.files === 1 ? "" : "s"}`,
+            cheap: false,
+        });
+    }
+    plan.sort((a, b) => a.rank - b.rank);
+    if (!verbose && !hasSystem) {
+        // The cold run is the whole pitch: someone with no system, one command, a
+        // number they did not have. The summary must not swallow it - it is the
+        // only path here that has to persuade rather than inform.
+        console.log("");
+        for (const line of verdict(d, false, 0, 0))
+            console.log(line);
+        console.log("");
+    }
+    else if (!verbose) {
+        if (conflictsInUse.length + frozen.length > 0) {
+            console.log("");
+            console.log(body(`${conflictsInUse.length + frozen.length} problem(s) in the SYSTEM - not fixable from this repo`));
+            for (const c of conflictsInUse) {
+                console.log(`      ds-${c.component}    the law forbids ${c.forbids}, the recipe binds it`);
+            }
+            for (const f of frozen) {
+                console.log(`      ds-${f.component}  ${f.where.split(" · ").pop()} frozen at a primitive, will not follow the other scheme`);
+            }
+        }
+        if (d.findings.length > 0 || overrides.length > 0) {
+            console.log("");
+            console.log(body(`${d.findings.length} value(s) by hand · ${d.named} already have a name`));
+            console.log(body(`${overrides.length - lawKeepingCount} override(s) · ${offSystemCount} left the system` +
+                (lawKeepingCount > 0
+                    ? ` · ${lawKeepingCount} more kept a law`
+                    : "")));
+        }
+        if (plan.length > 0) {
+            console.log("");
+            console.log(body("Where to start"));
+            const w = Math.min(52, Math.max(...plan.slice(0, 5).map((j) => j.what.length)));
+            plan.slice(0, 5).forEach((j, i) => {
+                const what = j.what.length > w ? `${j.what.slice(0, w - 1)}…` : j.what.padEnd(w);
+                console.log(`      ${i + 1}. ${what}  ${j.size}${j.cheap ? "  (cheap)" : ""}`);
+            });
+        }
+        console.log("");
+        console.log(body("synthesisui doctor --verbose   every finding, file by file"));
+        console.log("");
+    }
     if (opts.strict) {
         const mine = d.findings.length > 0 || overrides.length > 0;
         // The two system lenses are deliberately NOT in here by default. A team

package/dist/doctor/scan.js

@@ -60,16 +60,21 @@ const IDIOM = new Set(["0", "0px", "1px", "9999px", "100%", "50%"]);
 export function scanSource(file, source, table) {
     const findings = [];
     let tokenUses = 0;
-    let aside = 0;
+    // Reason by reason. Rolling two into "A or B" was the one place the report
+    // still lumped things it had told apart everywhere else.
+    const aside = new Map();
+    const setAside = (reason) => aside.set(reason, (aside.get(reason) ?? 0) + 1);
     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,
-            },
+            setAside: [
+                {
+                    reason: "renders to an image, where CSS variables do not exist",
+                    count: (source.match(COLOR) ?? []).length,
+                },
+            ],
         };
     }
     let svgDepth = 0;
@@ -101,7 +106,7 @@ export function scanSource(file, source, table) {
             if (literal.includes("$") || literal.includes("{"))
                 return;
             if (col >= 0 && inFallback(col)) {
-                aside++;
+                setAside("a token's own fallback");
                 return;
             }
             const key = `${kind}:${literal}`;
@@ -123,7 +128,7 @@ export function scanSource(file, source, table) {
                 (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++;
+                setAside("SVG artwork");
                 continue;
             }
             push("color", m[0], m.index ?? -1);
@@ -150,12 +155,9 @@ export function scanSource(file, source, table) {
         file,
         findings,
         tokenUses,
-        ...(aside > 0
+        ...(aside.size > 0
             ? {
-                setAside: {
-                    reason: "SVG artwork or a token's own fallback",
-                    count: aside,
-                },
+                setAside: [...aside].map(([reason, count]) => ({ reason, count })),
             }
             : null),
     };

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 [paths…] [--all]      audit for DRIFT: every design value written by
+  synthesisui doctor [paths…] [--verbose]  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
 
@@ -54,7 +54,7 @@ Options:
   --force            clean: apply the changes (without it, dry run)
   --strict           doctor: exit 1 when drift is found in THIS repo (for CI)
   --strict-system    doctor: also exit 1 when the system itself is inconsistent
-  --all              doctor: list every finding, not just the loudest files
+  --verbose          doctor: every finding, file by file (default is a summary)
   --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
@@ -129,7 +129,9 @@ async function main() {
                 scopes: args,
                 strict: flags.strict === true || flags["strict-system"] === true,
                 strictSystem: flags["strict-system"] === true,
-                all: flags.all === true,
+                // --all is the old spelling; it keeps working silently so a script
+                // written last week does not break.
+                verbose: flags.verbose === true || flags.all === true,
                 laws: flags.laws === true,
             });
             break;

package/package.json

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