synthesisui 0.10.1 → 0.11.1

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
@@ -487,6 +510,23 @@ export async function doctor(opts) {
     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))
-        process.exitCode = 1;
+    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
+        // that installed someone else's system cannot fix its self-contradiction
+        // by editing this repo, and failing their build for it punishes the wrong
+        // person. It still prints, so a CI log carries it upstream. Anyone who
+        // authors their own system wants the opposite, and asks for it.
+        const theirs = conflictsInUse.length + frozen.length;
+        if (opts.strictSystem && theirs > 0) {
+            console.log(body(`--strict-system: ${theirs} problem(s) in the system itself. Failing.`));
+            process.exitCode = 1;
+        }
+        else if (theirs > 0) {
+            console.log(body(`${theirs} problem(s) above are in the system, not this repo - not failing.`));
+            console.log(body("Run with --strict-system if the system is yours."));
+        }
+        if (mine)
+            process.exitCode = 1;
+    }
 }

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/index.js

@@ -52,7 +52,8 @@ Options:
   --instruction <s>  refit: extra guidance for the adaptation
   --dry              refit: adapt and print, but save nothing
   --force            clean: apply the changes (without it, dry run)
-  --strict           doctor: exit 1 when drift is found (for CI)
+  --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
   --laws             doctor: show every usage law, not just the busiest components
   --out <path>       output path for the generated template (default: <pagesDir>/<file>)
@@ -126,7 +127,8 @@ async function main() {
             await doctor({
                 dir,
                 scopes: args,
-                strict: flags.strict === true,
+                strict: flags.strict === true || flags["strict-system"] === true,
+                strictSystem: flags["strict-system"] === true,
                 all: flags.all === true,
                 laws: flags.laws === true,
             });

package/package.json

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