synthesisui 0.9.1 → 0.10.1

package/dist/commands/doctor.js

@@ -147,11 +147,25 @@ function meter(pct, width = 24) {
     const filled = Math.round((pct / 100) * width);
     return `${"█".repeat(filled)}${"░".repeat(width - filled)}`;
 }
-function verdict(d, hasSystem, overruled) {
+function verdict(d, hasSystem, overruled, conflicts) {
+    // A system at war with itself outranks every other number here. The closing
+    // line is the one people quote, and it used to end on "6 of 14 have a name"
+    // while the page above it said the recipe contradicts its own law.
+    const head = conflicts > 0
+        ? [
+            body(conflicts === 1
+                ? "First, above everything: your system contradicts itself in one place."
+                : `First, above everything: your system contradicts itself in ${conflicts} places.`),
+            body("A law says one thing and the recipe under it does another, and"),
+            body("no code can be correct against a rule that disagrees with itself."),
+            "",
+        ]
+        : [];
     // 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 [
+            ...head,
             body("No design values are written by hand here, and no system is"),
             body("installed. Nothing to fix, and nothing to compare against."),
         ];
@@ -159,6 +173,7 @@ function verdict(d, hasSystem, overruled) {
     if (!hasSystem) {
         const distinct = new Set(d.findings.map((f) => f.literal.toLowerCase()));
         return [
+            ...head,
             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."),
             "",
@@ -169,6 +184,7 @@ function verdict(d, hasSystem, overruled) {
     }
     if (d.findings.length === 0 && overruled === 0) {
         return [
+            ...head,
             body("No drift. Every design value in this project comes from the"),
             body("system. That is a rarer sentence than it sounds."),
         ];
@@ -177,6 +193,7 @@ function verdict(d, hasSystem, overruled) {
     // "no drift" is a report nobody believes twice.
     if (d.findings.length === 0) {
         return [
+            ...head,
             body("No loose values - everything is a token."),
             body(overruled === 1
                 ? "But one place takes a component the system defines and"
@@ -188,6 +205,7 @@ function verdict(d, hasSystem, overruled) {
         ];
     }
     const lines = [
+        ...head,
         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."),
     ];
@@ -362,9 +380,36 @@ export async function doctor(opts) {
         };
         const drifting = overrides.filter((o) => lawKept(o) === null);
         const correcting = overrides.length - drifting.length;
+        /**
+         * Two very different acts wearing one label. Choosing a DIFFERENT token
+         * from the system is a decision inside the vocabulary - the recipe says
+         * surface, the author wanted raised, and both are the system's words.
+         * Writing `#fff` leaves the system entirely. Reporting them identically
+         * buried the ones that matter (investidorez, 25/07).
+         */
+        const onSystem = (o) => {
+            if (o.wrote.includes("var(--ds-"))
+                return true;
+            // a utility whose step exists in the scale - `gap-2xs` when the project
+            // has --ds-spacing-2xs - is the scale being used, just at another step
+            const step = /-([a-z0-9]+)$/.exec(o.wrote);
+            if (!step || o.wrote.includes("["))
+                return false;
+            for (const name of table.byName.keys()) {
+                if (name.endsWith(`-${step[1]}`))
+                    return true;
+            }
+            return false;
+        };
+        // Three acts, not two. `transform: none` does not leave the system - it
+        // 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.`));
         if (correcting > 0) {
             console.log("");
             console.log(body(correcting === 1
@@ -392,6 +437,11 @@ export async function doctor(opts) {
                     console.log(`            the recipe binds ${o.recipe}`);
                 else if (o.where)
                     console.log(`            the recipe binds it ${o.where}`);
+                if (lawKept(o) === null && !onSystem(o)) {
+                    console.log(isReset(o.wrote)
+                        ? "            ↑ removes it rather than replacing it"
+                        : "            ↑ a raw value, not a token");
+                }
                 const kept = lawKept(o);
                 if (kept) {
                     console.log(`            ✓ but the law says: "${kept}"`);
@@ -434,7 +484,7 @@ export async function doctor(opts) {
         }
     }
     console.log(section("What this means"));
-    for (const line of verdict(d, hasSystem, overrides.length))
+    for (const line of verdict(d, hasSystem, overrides.length, conflictsInUse.length))
         console.log(line);
     console.log("");
     if (opts.strict && (d.findings.length > 0 || overrides.length > 0))

package/dist/doctor/scan.js

@@ -40,6 +40,21 @@ const SPACING = /(?:\b[pmg](?:[trblxy])?-\[|gap-\[|(?:padding|margin|gap)\s*:\s*
 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;
+/**
+ * `var(--ds-color-semantic-primary, #5266eb)` - the literal is the TOKEN'S OWN
+ * fallback, written for safety, and reporting it as drift told an author to
+ * tokenize something they had already tokenized (investidorez, 25/07). The
+ * spans below are the fallback arguments on a line.
+ */
+const VAR_FALLBACK = /var\(\s*--ds-[a-z0-9-]+\s*,([^()]*)\)/gi;
+function fallbackSpans(line) {
+    const out = [];
+    for (const m of line.matchAll(VAR_FALLBACK)) {
+        const start = (m.index ?? 0) + m[0].indexOf(",") + 1;
+        out.push([start, start + m[1].length]);
+    }
+    return out;
+}
 /** 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) {
@@ -77,10 +92,18 @@ export function scanSource(file, source, table) {
         // 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 spans = fallbackSpans(line);
+        const inFallback = (at) => spans.some(([a, b]) => at >= a && at <= b);
         const seen = new Set();
-        const push = (kind, literal) => {
+        // NOT named `at`: that is the line number in this scope, and shadowing it
+        // put column positions into the report as line numbers.
+        const push = (kind, literal, col = -1) => {
             if (literal.includes("$") || literal.includes("{"))
                 return;
+            if (col >= 0 && inFallback(col)) {
+                aside++;
+                return;
+            }
             const key = `${kind}:${literal}`;
             if (seen.has(key))
                 return;
@@ -103,17 +126,17 @@ export function scanSource(file, source, table) {
                 aside++;
                 continue;
             }
-            push("color", m[0]);
+            push("color", m[0], m.index ?? -1);
         }
         for (const m of line.matchAll(RADIUS)) {
             const value = `${m[1]}${m[2]}`;
             if (!IDIOM.has(value))
-                push("radius", value);
+                push("radius", value, m.index ?? -1);
         }
         for (const m of line.matchAll(SPACING)) {
             const value = `${m[1]}${m[2]}`;
             if (!IDIOM.has(value))
-                push("spacing", value);
+                push("spacing", value, m.index ?? -1);
         }
         for (const m of line.matchAll(FONT)) {
             const stack = m[1].trim();
@@ -128,7 +151,12 @@ export function scanSource(file, source, table) {
         findings,
         tokenUses,
         ...(aside > 0
-            ? { setAside: { reason: "SVG artwork", count: aside } }
+            ? {
+                setAside: {
+                    reason: "SVG artwork or a token's own fallback",
+                    count: aside,
+                },
+            }
             : null),
     };
 }

package/package.json

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