synthesisui 0.16.51 → 0.16.53

package/dist/commands/import.js

@@ -4,6 +4,7 @@ import { readToken, resolveRegistry } from "../config.js";
 import { isNearDuplicate } from "../doctor/color-distance.js";
 import { emptyTally, internalSpecifiers, scanComponentsInto, tallyToInventory, } from "../doctor/components-scan.js";
 import { crosswalk, observedRules } from "../doctor/crosswalk.js";
+import { reconcile, scanDefinitions, } from "../doctor/definitions-scan.js";
 import { diagnose, scanSource } from "../doctor/scan.js";
 import { parseSchemeBlocks } from "../doctor/scheme-blocks.js";
 import { buildTable } from "../doctor/tokens.js";
@@ -271,6 +272,7 @@ export async function takeCensus(root) {
     const reports = [];
     const tally = emptyTally();
     const internal = await internalSpecifiers(root);
+    const defined = [];
     for await (const file of walk(root)) {
         const src = await readFile(file, "utf8").catch(() => "");
         if (!src)
@@ -282,14 +284,44 @@ export async function takeCensus(root) {
         // they were set aside.
         if (!/(\.(spec|test|stories)\.[a-z]+$|__tests__\/|(^|\/)\.storybook\/)/.test(rel)) {
             scanComponentsInto(tally, rel, src, internal);
+            // The other half: what this file EXPORTS, with the axes its types
+            // declare. A library composes almost nothing and exports everything.
+            defined.push(...scanDefinitions(rel, src));
         }
     }
     const d = diagnose(reports);
     const inventory = tallyToInventory(tally);
+    /**
+     * THE TWO READINGS BECOME ONE LIST before anything is judged.
+     *
+     * The crosswalk saw only what a project COMPOSES, so a library's report said
+     * "only yours (4)" three lines above "37 components exported here" - the two
+     * sections talking past each other (dono, 31/07). Worse, the contracts that
+     * travel are picked from that list, so a library would have sent four.
+     *
+     * A component that is defined and never composed here is still a component:
+     * in a library that is the entire point. Its axes come from the TYPE, which
+     * is the better source anyway - usage shows what somebody picked, the
+     * declaration shows what the author designed.
+     */
+    const composed = new Set(inventory.map((c) => c.name));
+    const fromTypes = defined
+        .filter((d) => !composed.has(d.name))
+        .map((d) => ({
+        name: d.name,
+        count: 0,
+        files: 0,
+        props: {
+            ...Object.fromEntries(Object.entries(d.axes)),
+            ...Object.fromEntries(d.flags.map((f) => [f, ["true"]])),
+        },
+        propFiles: {},
+    }));
+    const merged = [...inventory, ...fromTypes];
     // The verdict travels WITH the payload: the platform reads one reading rather
     // than computing a second opinion from the same numbers, which is how two
     // implementations of the same judgement start disagreeing.
-    const verdicts = new Map(crosswalk(inventory).map((r) => [
+    const verdicts = new Map(crosswalk(merged).map((r) => [
         r.component.name,
         { bucket: r.bucket, canonical: r.canonical, because: r.because },
     ]));
@@ -297,7 +329,7 @@ export async function takeCensus(root) {
     for (const r of observedRules(inventory)) {
         laws.set(r.component, [...(laws.get(r.component) ?? []), r.text]);
     }
-    const components = inventory.map((c) => ({
+    const components = merged.map((c) => ({
         ...c,
         ...(verdicts.get(c.name) ?? {}),
         ...(laws.has(c.name) ? { laws: laws.get(c.name) } : {}),
@@ -321,6 +353,7 @@ export async function takeCensus(root) {
             : {}),
         observed: distinctValues(d),
         ...(components.length > 0 ? { components } : {}),
+        ...(defined.length > 0 ? { defined } : {}),
         totals: {
             scanned: d.scanned,
             values: d.findings.length,
@@ -408,6 +441,54 @@ function printComponents(c) {
     }
     printCrosswalk(mine);
     printObserved(mine);
+    printDefined(c, mine);
+}
+/**
+ * What the project DEFINES, and what crossing that with usage reveals.
+ *
+ * A library exports components rather than composing them, so a usage-only
+ * reading of `packages/ui` found thirteen of its thirty-one (dono, 31/07).
+ * This is the other half, and the crossing is the part no toolchain offers.
+ */
+function printDefined(census, used) {
+    const defined = census.defined ?? [];
+    if (defined.length === 0)
+        return;
+    const withAxes = defined.filter((d) => Object.keys(d.axes).length > 0);
+    console.log("");
+    console.log(section("What this project defines"));
+    console.log(body(`${defined.length} components exported here, ${withAxes.length} with axes their types declare`));
+    console.log("");
+    for (const d of withAxes.slice(0, 8)) {
+        const axes = Object.entries(d.axes)
+            .map(([a, o]) => `${a}(${o.join("|")})`)
+            .join(" ");
+        console.log(body(`  ${paint.strong(d.name.padEnd(20))} ${paint.dim(axes)}`));
+    }
+    if (withAxes.length > 8) {
+        console.log(body(paint.faint(`  (${withAxes.length - 8} more)`)));
+    }
+    const crossed = reconcile(defined, used);
+    const dead = crossed.filter((r) => r.deadOptions.length > 0);
+    const stray = crossed.filter((r) => r.undeclared.length > 0);
+    const orphans = crossed.filter((r) => r.orphan);
+    if (dead.length === 0 && stray.length === 0 && orphans.length === 0)
+        return;
+    console.log("");
+    console.log(section("What the two readings disagree about"));
+    for (const r of stray.slice(0, 4)) {
+        for (const u of r.undeclared) {
+            console.log(body(`  ${paint.strong(r.name)} is passed ${u.axis}="${u.values.join('" | "')}" ${paint.faint("- its own type does not offer that")}`));
+        }
+    }
+    for (const r of dead.slice(0, 4)) {
+        for (const d of r.deadOptions) {
+            console.log(body(`  ${paint.strong(r.name)} declares ${d.axis}="${d.options.join('" | "')}" ${paint.faint("- and nothing ever passes it")}`));
+        }
+    }
+    if (orphans.length > 0) {
+        console.log(body(paint.dim(`  ${orphans.length} defined here and composed nowhere in this folder - expected in a library, worth a look in an app.`)));
+    }
 }
 /**
  * Laws their code already obeys, printed with the evidence that found them.
@@ -455,7 +536,7 @@ function printCrosswalk(mine) {
             return;
         console.log(body(paint.strong(title)));
         for (const r of list.slice(0, limit)) {
-            console.log(body(`  ${r.component.name.padEnd(18)} ${paint.faint(`${r.component.files} files`)}  ${paint.dim(r.because)}`));
+            console.log(body(`  ${r.component.name.padEnd(18)} ${paint.faint(r.component.files === 0 ? "declared" : `${r.component.files} files`)}  ${paint.dim(r.because)}`));
         }
         if (list.length > limit) {
             console.log(body(paint.faint(`  (${list.length - limit} more)`)));

package/dist/doctor/definitions-scan.js

@@ -0,0 +1,116 @@
+/**
+ * WHAT A PROJECT DEFINES, as opposed to what it composes.
+ *
+ * The inventory reads usage, and that is blind in exactly the place a component
+ * LIBRARY lives. Measured on a real one (dono, 31/07): `packages/ui` holds 31
+ * component directories and composes almost none of them internally - a library
+ * exports components, it does not use them - so a usage reader found thirteen
+ * and the other eighteen were invisible.
+ *
+ * And the definition is the better source anyway. A declared union IS the closed
+ * set, verbatim:
+ *
+ *     type ButtonProps = { variant?: "neutral" | "ocean" }
+ *
+ * Usage can only ever show the options somebody happened to pick; the type shows
+ * the ones the author designed, including the one nobody has chosen yet - which
+ * is a finding of its own once the two readings are crossed.
+ *
+ * A SCANNER, NOT A PARSER, like everything else here. It reads the shapes people
+ * actually write and stays silent on the rest: a props type built by `Omit<>` or
+ * spread from another interface yields no axes rather than wrong ones.
+ */
+/** `export function X`, `export default function X`, `export const X =`. */
+const EXPORTED = /export\s+(?:default\s+)?(?:async\s+)?(?:function\s+([A-Z][A-Za-z0-9_]*)|const\s+([A-Z][A-Za-z0-9_]*)\s*[:=])/g;
+/** `type ButtonProps = { … }` or `interface ButtonProps { … }`, to its closing
+ *  brace, wherever it sits.
+ *
+ * Two stricter versions failed a spec each: requiring the brace at column zero
+ * missed an indented declaration, and requiring it on its own line missed a
+ * one-liner. Ending at the first `}` can cut a nested object short, and that is
+ * the safe direction - the field reader below simply finds no literal union in
+ * the fragment and stays quiet. */
+const PROPS_BLOCK = /(?:type|interface)\s+([A-Z][A-Za-z0-9_]*?)Props\b[^{]*\{([\s\S]*?)\}/g;
+/** One field of a props type: `variant?: "a" | "b"`. Fields are separated by a
+ *  newline OR a semicolon, and a one-line type uses only the second. */
+const FIELD = /(?:^|[;{])\s*(\w+)\??\s*:\s*([^;\n}]+)/gm;
+/** A union made only of string literals - the shape of a designed axis. */
+const LITERAL_UNION = /^\s*(["'][^"']+["']\s*\|\s*)+["'][^"']+["']\s*$/;
+export function scanDefinitions(file, source) {
+    if (!/\.(tsx|jsx|vue|svelte)$/i.test(file))
+        return [];
+    // Props types first, keyed by the component name they belong to: `ButtonProps`
+    // is Button's. Matching by name prefix is the convention essentially every
+    // codebase follows, and guessing past it would attach axes to the wrong thing.
+    const propsOf = new Map();
+    PROPS_BLOCK.lastIndex = 0;
+    for (const block of source.matchAll(PROPS_BLOCK)) {
+        const owner = block[1];
+        const body = block[2];
+        const axes = {};
+        const flags = [];
+        FIELD.lastIndex = 0;
+        for (const f of body.matchAll(FIELD)) {
+            const prop = f[1];
+            const type = f[2].trim().replace(/,$/, "");
+            if (type === "boolean") {
+                flags.push(prop);
+                continue;
+            }
+            if (!LITERAL_UNION.test(type))
+                continue;
+            const options = [...type.matchAll(/["']([^"']+)["']/g)].map((m) => m[1]);
+            // One option is not a closed set - the same rule the contract writer and
+            // the doctor already follow.
+            if (options.length >= 2)
+                axes[prop] = options;
+        }
+        if (Object.keys(axes).length > 0 || flags.length > 0) {
+            propsOf.set(owner, { axes, flags });
+        }
+    }
+    const out = [];
+    const seen = new Set();
+    EXPORTED.lastIndex = 0;
+    for (const m of source.matchAll(EXPORTED)) {
+        const name = m[1] ?? m[2];
+        if (!name || seen.has(name))
+            continue;
+        seen.add(name);
+        const props = propsOf.get(name);
+        out.push({
+            name,
+            file,
+            axes: props?.axes ?? {},
+            flags: props?.flags ?? [],
+        });
+    }
+    return out;
+}
+export function reconcile(defined, used) {
+    const usage = new Map(used.filter((u) => !u.from).map((u) => [u.name, u]));
+    const out = [];
+    for (const d of defined) {
+        const u = usage.get(d.name);
+        const deadOptions = [];
+        const undeclared = [];
+        for (const [axis, options] of Object.entries(d.axes)) {
+            const passed = new Set((u?.props[axis] ?? []).map((v) => v.trim().toLowerCase()));
+            const dead = options.filter((o) => !passed.has(o.toLowerCase()));
+            // Every option unused means the axis is untouched, not that each option
+            // is dead - reporting the whole set as dead reads as an accusation about
+            // options rather than about an axis nobody reaches for.
+            if (dead.length > 0 && dead.length < options.length) {
+                deadOptions.push({ axis, options: dead });
+            }
+            const declared = new Set(options.map((o) => o.toLowerCase()));
+            const stray = (u?.props[axis] ?? []).filter((v) => v !== "true" && !declared.has(v.trim().toLowerCase()));
+            if (stray.length > 0)
+                undeclared.push({ axis, values: stray });
+        }
+        if (deadOptions.length > 0 || undeclared.length > 0 || !u) {
+            out.push({ name: d.name, deadOptions, undeclared, orphan: !u });
+        }
+    }
+    return out;
+}

package/package.json

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