synthesisui 0.9.0 → 0.10.0

package/dist/commands/doctor.js

@@ -2,7 +2,7 @@ import { readdir, readFile } from "node:fs/promises";
 import { join, relative, resolve } from "node:path";
 import { bindingsFromDocument, countComponents, findOverrides, } from "../doctor/overrides.js";
 import { diagnose, scanSource, } from "../doctor/scan.js";
-import { findSelfConflicts } from "../doctor/self-conflict.js";
+import { findSelfConflicts, forbiddenProps, isReset, propMatchesLabel, } from "../doctor/self-conflict.js";
 import { buildTable, EMPTY_TABLE, nearestToken, } from "../doctor/tokens.js";
 import { body, section, snippet } from "../output.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."),
     ];
@@ -313,11 +331,89 @@ export async function doctor(opts) {
             console.log(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
+    // whether the system obeys itself, and it is only here because the tool once
+    // reported a consumer for overruling a recipe while they were obeying the
+    // law written on that same component.
+    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
+            ? "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("");
+        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("");
+        }
+        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."));
+    }
     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
+        // broke. Counting it against them was the report being unfair to the only
+        // person in the loop who read the law (investidorez, 25/07).
+        const forbidden = new Map();
+        for (const doc of documents) {
+            for (const [comp, props] of forbiddenProps(doc)) {
+                const merged = forbidden.get(comp) ?? new Map();
+                for (const [label, law] of props)
+                    merged.set(label, law);
+                forbidden.set(comp, merged);
+            }
+        }
+        const lawKept = (o) => {
+            if (!isReset(o.wrote))
+                return null;
+            const props = forbidden.get(o.component);
+            if (!props)
+                return null;
+            for (const [label, law] of props) {
+                if (propMatchesLabel(o.prop, label))
+                    return law;
+            }
+            return null;
+        };
+        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;
+        };
+        const offSystem = drifting.filter((o) => !onSystem(o)).length;
         console.log(section("Overruled"));
-        console.log(body(`${overrides.length} place${overrides.length === 1 ? "" : "s"} where the code takes a component`));
+        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
+                ? "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("");
         const byFile = new Map();
         for (const o of overrides) {
             const list = byFile.get(o.file);
@@ -338,6 +434,14 @@ 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");
+                }
+                const kept = lawKept(o);
+                if (kept) {
+                    console.log(`            ✓ but the law says: "${kept}"`);
+                    console.log("              this override keeps it - the recipe does not");
+                }
             }
             if (!opts.all && list.length > 3) {
                 console.log(`            +${list.length - 3} more`);
@@ -351,27 +455,6 @@ export async function doctor(opts) {
     // The system's own words, for the components this project actually uses.
     // Prose, so nothing verifies it - the value is putting it in front of
     // whoever is touching the component, which no other tool is positioned to
-    // Every other section asks whether the code obeys the system. This one asks
-    // whether the system obeys itself, and it is only here because the tool once
-    // reported a consumer for overruling a recipe while they were obeying the
-    // law written on that same component.
-    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
-            ? "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("");
-        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("");
-        }
-        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."));
-    }
     // do because no other tool knows these laws exist.
     const inUse = [...used.entries()]
         .filter(([name]) => (recipes.get(name)?.usage.length ?? 0) > 0)
@@ -396,7 +479,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/self-conflict.js

@@ -94,6 +94,43 @@ function* declarations(node, where) {
         }
     }
 }
+/**
+ * Per component, the properties its own laws forbid and the law that does it.
+ *
+ * The report needs this separately from the conflicts: an override on a
+ * forbidden property is not drift, it is the author keeping a promise the
+ * recipe broke. Listing them together was accusing the person who was right.
+ */
+export function forbiddenProps(document) {
+    const out = new Map();
+    const doc = (document ?? {});
+    const components = (doc.components ?? {});
+    for (const [name, raw] of Object.entries(components)) {
+        const recipe = (raw ?? {});
+        const laws = Array.isArray(recipe.usage)
+            ? recipe.usage.filter((x) => typeof x === "string")
+            : [];
+        for (const law of laws) {
+            for (const rule of FORBIDDABLE) {
+                if (!forbids(law, rule.words))
+                    continue;
+                const byProp = out.get(name) ?? new Map();
+                byProp.set(rule.label, law);
+                out.set(name, byProp);
+            }
+        }
+    }
+    return out;
+}
+/** Is this property one the law names, given how the rule matches? */
+export function propMatchesLabel(prop, label) {
+    const rule = FORBIDDABLE.find((r) => r.label === label);
+    return rule ? rule.prop.test(prop) : false;
+}
+/** A value that removes rather than sets - the law being kept. */
+export function isReset(value) {
+    return !isSet(value);
+}
 /**
  * Every place a component's recipe does what its own law forbids.
  */

package/package.json

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