synthesisui 0.10.0 → 0.11.0

package/dist/commands/doctor.js

@@ -1,5 +1,6 @@
 import { readdir, readFile } from "node:fs/promises";
 import { join, relative, resolve } from "node:path";
+import { findFrozenBindings } from "../doctor/frozen.js";
 import { bindingsFromDocument, countComponents, findOverrides, } from "../doctor/overrides.js";
 import { diagnose, scanSource, } from "../doctor/scan.js";
 import { findSelfConflicts, forbiddenProps, isReset, propMatchesLabel, } from "../doctor/self-conflict.js";
@@ -352,6 +353,28 @@ export async function doctor(opts) {
         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."));
     }
+    // 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
+    // compiles - and the binding sits still while everything around it flips.
+    const frozen = documents
+        .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
+            ? "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("");
+        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("");
+        }
+        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."));
+    }
     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
@@ -401,7 +424,10 @@ export async function doctor(opts) {
             }
             return false;
         };
-        const offSystem = drifting.filter((o) => !onSystem(o)).length;
+        // 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."));
@@ -434,8 +460,10 @@ 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 (!onSystem(o) && lawKept(o) === null) {
-                    console.log("            ↑ a raw value, not a token");
+                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) {

package/dist/doctor/frozen.js

@@ -0,0 +1,104 @@
+/**
+ * DOCTOR · bindings that will not follow the scheme.
+ *
+ * A system with two schemes keeps the flip in ONE place: the semantic layer.
+ * `surface` points at navy-800 in dark and navy-50 in light, and every recipe
+ * that binds `{color.semantic.surface}` flips for free.
+ *
+ * A recipe that reaches past the role and names the shelf - `{color.navy.800}` -
+ * is frozen. It looks identical in the authored scheme and wrong in the other
+ * one, and nothing in the pipeline says so: the value is a legitimate token,
+ * the reference resolves, the CSS compiles.
+ *
+ * Vesper does this in five places. Its chip binds `{color.navy.800}` for a
+ * background where `semantic.surface` holds the same value and becomes navy-50
+ * in light mode - so the chip stays dark on a light page (found by reading the
+ * doctor's own output on a real project, investidorez, 25/07).
+ *
+ * This is a correctness check, not a style one. It fires only when the role
+ * actually differs between the two schemes; a role that is the same in both
+ * costs nothing to spell either way, and this stays quiet about it.
+ */
+const PRIMITIVE = /^\{color\.([a-z0-9]+)\.([a-z0-9]+)\}$/i;
+const BACKGROUND = /^background(-color)?$/;
+const kebab = (s) => s.replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase();
+function* colorBindings(node, where) {
+    if (!node || typeof node !== "object")
+        return;
+    for (const [k, v] of Object.entries(node)) {
+        if (typeof v === "string") {
+            // Backgrounds only. A FOREGROUND bound to a primitive is usually right:
+            // white on an indigo button must stay white, because the fill it sits on
+            // does not flip either. Deciding that needs the sibling fill and the
+            // author's intent, so this lens does not try - a wrong accusation here
+            // would have someone invert readable text.
+            if (BACKGROUND.test(kebab(k)) && PRIMITIVE.test(v))
+                yield { prop: kebab(k), value: v, where };
+        }
+        else if (v && typeof v === "object") {
+            yield* colorBindings(v, where);
+        }
+    }
+}
+export function findFrozenBindings(document) {
+    const doc = (document ?? {});
+    const foundations = (doc.foundations ?? {});
+    const color = (foundations.color ?? {});
+    const semantic = (color.semantic ?? {});
+    const alt = (color.semanticAlt ?? {});
+    // Only roles that actually MOVE between schemes. A role spelled the same in
+    // both is not a correctness problem, and this lens does not do taste.
+    //
+    // Several roles can hold one primitive (Vesper's navy-700 is raised, overlay
+    // AND border). Surfaces are preferred, because this only ever reports a
+    // background - naming "border" for a background reads like a bug in the tool.
+    const RANK = ["surface", "raised", "canvas", "overlay", "border"];
+    const roleOf = new Map();
+    for (const [role, ref] of Object.entries(semantic)) {
+        const other = alt[role];
+        if (typeof ref !== "string" || typeof other !== "string")
+            continue;
+        if (other === ref)
+            continue;
+        const m = PRIMITIVE.exec(ref);
+        if (!m)
+            continue;
+        const key = `${m[1]}.${m[2]}`.toLowerCase();
+        const held = roleOf.get(key);
+        const better = !held ||
+            (RANK.indexOf(role) !== -1 &&
+                (RANK.indexOf(held.role) === -1 ||
+                    RANK.indexOf(role) < RANK.indexOf(held.role)));
+        if (better)
+            roleOf.set(key, { role, becomes: other });
+    }
+    if (roleOf.size === 0)
+        return [];
+    const out = [];
+    const components = (doc.components ?? {});
+    for (const [name, raw] of Object.entries(components)) {
+        const recipe = (raw ?? {});
+        const found = [
+            ...colorBindings(recipe.base, "base"),
+            ...colorBindings(recipe.states, "a state"),
+            ...colorBindings(recipe.variants, "a variant"),
+            ...colorBindings(recipe.parts, "a part"),
+        ];
+        for (const b of found) {
+            const m = PRIMITIVE.exec(b.value);
+            if (!m)
+                continue;
+            const hit = roleOf.get(`${m[1]}.${m[2]}`.toLowerCase());
+            if (!hit)
+                continue;
+            out.push({
+                component: name,
+                where: `${b.where} · ${b.prop}`,
+                wrote: b.value,
+                role: hit.role,
+                becomes: hit.becomes,
+            });
+        }
+    }
+    return out;
+}

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.10.0",
+  "version": "0.11.0",
   "description": "Bring SynthesisUI design systems into any project - tokens, typed components, whole pages and an agent-ready CLAUDE.md manifest.",
   "type": "module",
   "bin": {