synthesisui 0.16.49 → 0.16.51

package/dist/commands/doctor.js

@@ -1,6 +1,8 @@
 import { readdir, readFile } from "node:fs/promises";
 import { join, relative, resolve } from "node:path";
 import { findDivergences } from "../doctor/coherence.js";
+import { emptyTally, internalSpecifiers, scanComponentsInto, tallyToInventory, } from "../doctor/components-scan.js";
+import { checkContracts } from "../doctor/contract-check.js";
 import { findFrozenBindings } from "../doctor/frozen.js";
 import { appendEvent, readEvents, summarize } from "../doctor/ledger.js";
 import { bindingsFromDocument, countComponents, findOverrides, } from "../doctor/overrides.js";
@@ -29,6 +31,8 @@ import { body, paint, section, snippet } from "../output.js";
  * Runs offline, needs no account, and touches nothing. A tool that asks for a
  * signup before it tells you anything is a tool nobody runs twice.
  */
+/** Files that compose components to SHOW them, not to ship them. */
+const IS_ASIDE = /(\.(spec|test|stories)\.[a-z]+$|__tests__\/|(^|\/)\.storybook\/)/;
 const EXTS = [".tsx", ".ts", ".jsx", ".js", ".css", ".scss", ".vue", ".svelte"];
 const SKIP = new Set([
     "node_modules",
@@ -404,6 +408,8 @@ export async function doctor(opts) {
      */
     const wiring = await readWiring(root, table.slug);
     const skippedProjects = [];
+    const tally = emptyTally();
+    const internalSpecs = await internalSpecifiers(root);
     for await (const file of scopes.length > 0
         ? walkAll(scopes)
         : walk(root, skippedProjects)) {
@@ -412,6 +418,13 @@ export async function doctor(opts) {
             continue;
         const rel = relative(root, file);
         reports.push(scanSource(rel, src, table));
+        // Composition, alongside values: the contract check needs to know which
+        // elements this file writes and with what options. Stories and tests are
+        // excluded for the reason they are excluded everywhere else - they compose
+        // components to SHOW them.
+        if (documents.length > 0 && !IS_ASIDE.test(rel)) {
+            scanComponentsInto(tally, rel, src, internalSpecs);
+        }
         if (recipes.size > 0) {
             for (const o of findOverrides(src, recipes))
                 overrides.push({ ...o, file: rel });
@@ -433,6 +446,7 @@ export async function doctor(opts) {
     for (const r of reports) {
         r.findings = r.findings.filter((f) => !explained.has(`${r.file}:${f.line}:${f.literal.toLowerCase()}`));
     }
+    const breaches = checkContracts(tallyToInventory(tally, 400), documents);
     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
@@ -1081,6 +1095,35 @@ export async function doctor(opts) {
                         : "")));
             }
         }
+        /**
+         * A CONTRACT BROKEN, which is the first thing this command has ever said
+         * about composition rather than about values.
+         *
+         * A colour outside the palette has always been drift. This is the same
+         * sentence about a component: `<WidgetCard variant="danger">` on a
+         * component whose contract offers `neutral` and `ocean`. No linter and no
+         * type can say it, because the answer lives in the design system.
+         */
+        if (breaches.length > 0) {
+            // Grouped by element AND axis: grouping by element alone printed
+            // `variant="danger" | "huge"` and then offered the options for variant,
+            // when `huge` was a size. One line per axis or the line lies.
+            const byAxis = new Map();
+            for (const b of breaches) {
+                const k = `${b.element}\u0000${b.axis}`;
+                byAxis.set(k, [...(byAxis.get(k) ?? []), b]);
+            }
+            console.log("");
+            console.log(body(`${paint.strong(String(breaches.length))} use${breaches.length === 1 ? "" : "s"} outside the contract`));
+            for (const list of [...byAxis.values()].slice(0, 5)) {
+                const first = list[0];
+                const values = [...new Set(list.map((b) => b.used))];
+                console.log(body(`    <${first.element} ${first.axis}="${values.join('" | "')}"> ${paint.faint(`- your ds-${first.recipe} offers ${first.offered.join(", ")}`)}`));
+            }
+            if (byAxis.size > 5) {
+                console.log(body(paint.faint(`    (${byAxis.size - 5} more)`)));
+            }
+        }
         if (plan.length > 0) {
             console.log("");
             console.log(body("Where to start"));

package/dist/commands/import.js

@@ -2,8 +2,8 @@ import { mkdir, readdir, readFile, writeFile } from "node:fs/promises";
 import { basename, join, relative } from "node:path";
 import { readToken, resolveRegistry } from "../config.js";
 import { isNearDuplicate } from "../doctor/color-distance.js";
-import { emptyTally, scanComponentsInto, tallyToInventory, } from "../doctor/components-scan.js";
-import { crosswalk } from "../doctor/crosswalk.js";
+import { emptyTally, internalSpecifiers, scanComponentsInto, tallyToInventory, } from "../doctor/components-scan.js";
+import { crosswalk, observedRules } from "../doctor/crosswalk.js";
 import { diagnose, scanSource } from "../doctor/scan.js";
 import { parseSchemeBlocks } from "../doctor/scheme-blocks.js";
 import { buildTable } from "../doctor/tokens.js";
@@ -126,57 +126,6 @@ async function resolveDeps(root) {
     }
     return deps;
 }
-/**
- * Specifier prefixes this workspace owns: the aliases its tsconfig declares and
- * the names of its sibling packages. Everything else that is not relative comes
- * from node_modules.
- */
-async function internalSpecifiers(root) {
-    const out = new Set();
-    for (let up = 0, dir = root; up < 4; up++) {
-        for (const f of ["tsconfig.json", "tsconfig.base.json"]) {
-            const raw = await readFile(join(dir, f), "utf8").catch(() => null);
-            if (!raw)
-                continue;
-            try {
-                // tsconfig allows comments and trailing commas; a census must not die
-                // on either, and the keys are all we want.
-                for (const m of raw.matchAll(/"([^"]+)\/?\*?"\s*:\s*\[/g)) {
-                    const key = m[1].replace(/\/\*$/, "").replace(/\*$/, "");
-                    if (key && !key.startsWith("."))
-                        out.add(key.replace(/\/$/, ""));
-                }
-            }
-            catch {
-                // unreadable config costs the aliases, not the run
-            }
-        }
-        for (const group of ["packages", "libs", "apps"]) {
-            for (const e of await readdir(join(dir, group), {
-                withFileTypes: true,
-            }).catch(() => [])) {
-                if (!e.isDirectory())
-                    continue;
-                const raw = await readFile(join(dir, group, e.name, "package.json"), "utf8").catch(() => null);
-                if (!raw)
-                    continue;
-                try {
-                    const name = JSON.parse(raw).name;
-                    if (typeof name === "string" && name)
-                        out.add(name);
-                }
-                catch {
-                    // same
-                }
-            }
-        }
-        const parent = join(dir, "..");
-        if (parent === dir)
-            break;
-        dir = parent;
-    }
-    return [...out];
-}
 async function detectStack(root) {
     const stack = [];
     const has = async (f) => (await readFile(join(root, f), "utf8").catch(() => null)) !== null;
@@ -344,9 +293,14 @@ export async function takeCensus(root) {
         r.component.name,
         { bucket: r.bucket, canonical: r.canonical, because: r.because },
     ]));
+    const laws = new Map();
+    for (const r of observedRules(inventory)) {
+        laws.set(r.component, [...(laws.get(r.component) ?? []), r.text]);
+    }
     const components = inventory.map((c) => ({
         ...c,
         ...(verdicts.get(c.name) ?? {}),
+        ...(laws.has(c.name) ? { laws: laws.get(c.name) } : {}),
     }));
     const pkgRaw = await readFile(join(root, "package.json"), "utf8").catch(() => null);
     let name = null;
@@ -453,6 +407,29 @@ function printComponents(c) {
         console.log(body(paint.faint(`(${mine.length - 12} more of yours)`)));
     }
     printCrosswalk(mine);
+    printObserved(mine);
+}
+/**
+ * Laws their code already obeys, printed with the evidence that found them.
+ *
+ * Not applied and not sent as decisions - they ride along on the contract as
+ * `usage`, which is where a law about one component belongs and what the GUIDE
+ * and the build script already read.
+ */
+function printObserved(mine) {
+    const rules = observedRules(mine);
+    if (rules.length === 0)
+        return;
+    console.log("");
+    console.log(section("Laws your code already obeys"));
+    console.log(body(paint.faint("A prop with one value across many files is not a choice being made - it is a rule nobody wrote down.")));
+    console.log("");
+    for (const r of rules.slice(0, 8)) {
+        console.log(body(`  ${paint.strong(r.component)} ${paint.dim(r.text.replace(/^Always /, "always "))}`));
+    }
+    if (rules.length > 8) {
+        console.log(body(paint.faint(`  (${rules.length - 8} more)`)));
+    }
 }
 /**
  * The crosswalk, printed and nothing else.

package/dist/doctor/components-scan.js

@@ -1,24 +1,5 @@
-/**
- * WHAT COMPONENTS A PROJECT ACTUALLY USES, and with which props.
- *
- * The census reads vocabulary - colours, radii, spacing, fonts - and is blind
- * to components. So a component library imported cleanly (dono, 30/07) arrived
- * with thirteen colour ramps and not one of its eight atoms, and the system
- * came out looking like ours instead of theirs.
- *
- * This is the same kind of arithmetic pointed at a different question: which
- * elements does this code compose, how often, in how many files, and which
- * literal values do their props take. No semantics, no judgement, no guessing
- * what a component MEANS - that comparison happens later and with a person in
- * the loop.
- *
- * A SCANNER, NOT A PARSER, and honest about it. The CLI ships no AST, so this
- * reads JSX the way the drift scanner reads colours: by shape. It therefore
- * sees what is written literally and misses what is computed
- * (`<Comp {...props} />` contributes a use and no prop values), which is the
- * right failure - a census that guessed at spread props would be inventing
- * usage nobody wrote.
- */
+import { readdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
 /**
  * Opens a JSX element whose name is capitalised - which is React's own rule for
  * "this is a component, not an html tag".
@@ -125,6 +106,7 @@ internal = []) {
                 count: 0,
                 files: new Set(),
                 props: new Map(),
+                propFiles: new Map(),
                 ...(owner ? { from: owner } : {}),
             };
             tally.set(name, hit);
@@ -141,6 +123,9 @@ internal = []) {
             const bucket = hit.props.get(prop) ?? new Map();
             bucket.set(value, (bucket.get(value) ?? 0) + 1);
             hit.props.set(prop, bucket);
+            const seenIn = hit.propFiles.get(prop) ?? new Set();
+            seenIn.add(file);
+            hit.propFiles.set(prop, seenIn);
         }
         // Bare booleans, minus anything already read as a valued prop.
         // Strip the WHOLE pair, name included: stripping only the value left
@@ -157,6 +142,9 @@ internal = []) {
             const bucket = hit.props.get(prop) ?? new Map();
             bucket.set("true", (bucket.get("true") ?? 0) + 1);
             hit.props.set(prop, bucket);
+            const seenIn = hit.propFiles.get(prop) ?? new Set();
+            seenIn.add(file);
+            hit.propFiles.set(prop, seenIn);
         }
     }
 }
@@ -168,6 +156,7 @@ export function tallyToInventory(tally, max = 80) {
         ...(v.from ? { from: v.from } : {}),
         count: v.count,
         files: v.files.size,
+        propFiles: Object.fromEntries([...v.propFiles.entries()].map(([p, files]) => [p, files.size])),
         props: Object.fromEntries([...v.props.entries()].map(([p, values]) => [
             p,
             [...values.entries()]
@@ -178,3 +167,54 @@ export function tallyToInventory(tally, max = 80) {
         .sort((a, b) => b.files - a.files || b.count - a.count)
         .slice(0, max);
 }
+/**
+ * Specifier prefixes this workspace owns: the aliases its tsconfig declares and
+ * the names of its sibling packages. Everything else that is not relative comes
+ * from node_modules.
+ */
+export async function internalSpecifiers(root) {
+    const out = new Set();
+    for (let up = 0, dir = root; up < 4; up++) {
+        for (const f of ["tsconfig.json", "tsconfig.base.json"]) {
+            const raw = await readFile(join(dir, f), "utf8").catch(() => null);
+            if (!raw)
+                continue;
+            try {
+                // tsconfig allows comments and trailing commas; a census must not die
+                // on either, and the keys are all we want.
+                for (const m of raw.matchAll(/"([^"]+)\/?\*?"\s*:\s*\[/g)) {
+                    const key = m[1].replace(/\/\*$/, "").replace(/\*$/, "");
+                    if (key && !key.startsWith("."))
+                        out.add(key.replace(/\/$/, ""));
+                }
+            }
+            catch {
+                // unreadable config costs the aliases, not the run
+            }
+        }
+        for (const group of ["packages", "libs", "apps"]) {
+            for (const e of await readdir(join(dir, group), {
+                withFileTypes: true,
+            }).catch(() => [])) {
+                if (!e.isDirectory())
+                    continue;
+                const raw = await readFile(join(dir, group, e.name, "package.json"), "utf8").catch(() => null);
+                if (!raw)
+                    continue;
+                try {
+                    const name = JSON.parse(raw).name;
+                    if (typeof name === "string" && name)
+                        out.add(name);
+                }
+                catch {
+                    // same
+                }
+            }
+        }
+        const parent = join(dir, "..");
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return [...out];
+}

package/dist/doctor/contract-check.js

@@ -0,0 +1,94 @@
+/**
+ * DOES THE CODE STAY INSIDE THE CONTRACT IT SIGNED?
+ *
+ * A system that arrived from `import` carries its exclusive components as
+ * CONTRACTS: the axes declared, the styles empty. That was worth doing only if
+ * something checks them afterwards - otherwise the declaration is a comment.
+ *
+ * This is that check, and it is the first one the product makes about
+ * COMPOSITION rather than about values. A colour outside the palette has always
+ * been drift; now `<WidgetCard variant="danger">` is drift too, on a component
+ * whose contract offers `neutral` and `ocean` - and nothing else in the
+ * toolchain can say that, because the answer lives in the design system rather
+ * than in the types.
+ *
+ * Silent by construction. An axis the contract does not declare is not checked
+ * (the system has no opinion about it), a component the system does not carry is
+ * not checked, and a value that cannot be read as a literal is not guessed at.
+ * A check that fires on what it does not know teaches people to ignore it.
+ */
+/** `WidgetCard` → `widget-card`, the same shape the contract was written under. */
+export function recipeNameOf(element) {
+    return element
+        .split(".")
+        .join("-")
+        .replace(/([a-z0-9])([A-Z])/g, "$1-$2")
+        .toLowerCase()
+        .replace(/[^a-z0-9-]/g, "-")
+        .replace(/-+/g, "-")
+        .replace(/^-|-$/g, "");
+}
+/** axis → the options a recipe declares, read off the document. */
+export function axesOfDocument(doc) {
+    const out = new Map();
+    const comps = doc?.components;
+    if (!comps)
+        return out;
+    for (const [name, recipe] of Object.entries(comps)) {
+        const variants = recipe
+            ?.variants;
+        if (!variants)
+            continue;
+        const axes = new Map();
+        for (const [axis, options] of Object.entries(variants)) {
+            const keys = Object.keys((options ?? {})).filter(Boolean);
+            // One option is not a closed set; the contract writer refuses to declare
+            // those, and this refuses to enforce them for the same reason.
+            if (keys.length >= 2)
+                axes.set(axis.toLowerCase(), keys);
+        }
+        if (axes.size > 0)
+            out.set(name.toLowerCase(), axes);
+    }
+    return out;
+}
+export function checkContracts(used, documents) {
+    const axes = new Map();
+    for (const doc of documents) {
+        for (const [name, a] of axesOfDocument(doc))
+            axes.set(name, a);
+    }
+    if (axes.size === 0)
+        return [];
+    const out = [];
+    for (const c of used) {
+        // A third party's component answers to its own package, not to this system.
+        if (c.from)
+            continue;
+        const recipe = recipeNameOf(c.name);
+        const contract = axes.get(recipe);
+        if (!contract)
+            continue;
+        for (const [prop, values] of Object.entries(c.props)) {
+            const offered = contract.get(prop.toLowerCase());
+            if (!offered)
+                continue;
+            const allowed = new Set(offered.map((o) => o.toLowerCase()));
+            for (const value of values) {
+                const v = value.trim().toLowerCase();
+                // `true` is what a bare boolean records; a contract about options has
+                // nothing to say about a flag.
+                if (!v || v === "true" || allowed.has(v))
+                    continue;
+                out.push({
+                    element: c.name,
+                    recipe,
+                    axis: prop,
+                    used: value,
+                    offered,
+                });
+            }
+        }
+    }
+    return out;
+}

package/dist/doctor/crosswalk.js

@@ -337,3 +337,41 @@ export function crosswalk(components) {
     })
         .sort((a, b) => b.component.files - a.component.files);
 }
+/** Below this a repetition is a coincidence rather than a habit. */
+export const RULE_MIN_FILES = 3;
+export function observedRules(components) {
+    const out = [];
+    for (const c of components) {
+        if (c.from)
+            continue;
+        for (const [prop, values] of Object.entries(c.props)) {
+            if (values.length !== 1)
+                continue;
+            const value = values[0];
+            // A law is about a DESIGN AXIS or a flag. `marginBottom="1em"` and
+            // `textAlign="center"` are CSS escaping through a prop - a real finding,
+            // and a different one, but writing "always textAlign=center" as a law of
+            // the component is nonsense (dono, 31/07).
+            const isAxis = AXIS_SYNONYM[prop.toLowerCase()] != null;
+            if (!isAxis && value !== "true")
+                continue;
+            // The prop's OWN reach, never the component's: `Text` lives in 66 files
+            // and `textAlign` may appear in one of them, and the first version
+            // claimed all 66 agreed.
+            const files = c.propFiles?.[prop] ?? 0;
+            if (files < RULE_MIN_FILES)
+                continue;
+            out.push({
+                component: c.name,
+                prop,
+                value,
+                files,
+                count: c.count,
+                text: value === "true"
+                    ? `Always set ${prop} - every one of the ${files} files that passes it does.`
+                    : `Always ${prop}="${value}" - all ${files} files that pass it agree.`,
+            });
+        }
+    }
+    return out.sort((a, b) => b.files - a.files || b.count - a.count);
+}

package/package.json

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