synthesisui 0.16.78 → 0.16.80

package/dist/component-codegen.js

@@ -207,7 +207,19 @@ const colorKey = (v) => {
         return `series-${series}`;
     return null;
 };
-/** "{typography.scale.sm.fontSize}" → "sm" (the --text-<key> utility). */
+/**
+ * "{typography.scale.sm.fontSize}" → "sm" (the --text-<key> utility).
+ *
+ * A STEP maps to a utility; a ROLE deliberately does not.
+ *
+ * `typography.scale.<step>` names a step the system actually has, and a step it
+ * got from THEIR declaration is bridged into Tailwind's namespace - so `text-h1`
+ * exists and is the prettier output. `typography.role.<slot>` is one of our seven
+ * slots, and the bridge only ever claims a name they gave us: `text-base` may not
+ * exist in an imported system at all. So a role falls through to
+ * `var(--ds-typography-role-base-font-size)`, which is always emitted and can
+ * never dangle.
+ */
 const scaleKey = (v) => {
     const m = v.match(/^\{typography\.scale\.([a-zA-Z0-9-]+)\.fontSize\}$/);
     return m ? kebab(m[1]) : null;
@@ -504,6 +516,7 @@ const FORM_TAG = {
     icon: { tag: "span" },
     row: { tag: "div" },
     stack: { tag: "div" },
+    slot: { tag: "div" },
 };
 /** Only these two arrange; the rest are leaves. */
 const ARRANGES = new Set(["row", "stack"]);
@@ -543,6 +556,16 @@ function emitTree(nodes, comp, indent) {
             lines.push(`${indent}{/* ${node.from} renders here - a third party's component, so its markup is theirs */}`);
             continue;
         }
+        // The caller's content, so the generated code takes it as a prop rather than
+        // inventing a sample. A slot that also carries styles keeps its part element
+        // around the children; a bare one is just `{children}`.
+        if (node.as === "slot") {
+            const inner = `{children}${node.expects ? ` {/* ${node.expects} */}` : ""}`;
+            lines.push(node.part
+                ? `${indent}<${comp}${pascal(node.part)}>${inner}</${comp}${pascal(node.part)}>`
+                : `${indent}${inner}`);
+            continue;
+        }
         if (!node.part) {
             // Pure structure with no styles of its own: keep the arrangement, skip the
             // element - a div that carries nothing is a div nobody needs.
@@ -640,11 +663,13 @@ function partTagFor(part, form) {
         voidEl: Boolean(mapped.voidEl),
     };
 }
-function emitCssMode(slug, name, recipe, version, props, convention) {
+function emitCssMode(slug, name, recipe, version, props, convention, 
+/** The name it takes in THEIR project. The class stays the system's. */
+localName = name) {
     const { tag, attrs, voidEl } = elementFor(name, recipe);
     const el = asElement(tag, attrs, voidEl);
     const axes = axesOf(recipe.variants);
-    const comp = pascal(name);
+    const comp = pascal(localName);
     const propNames = axes.map((a) => a.prop);
     const tree = recipe.preview?.parts ?? [];
     // With a shape the root RENDERS its children, so it needs `children` in the
@@ -713,7 +738,7 @@ ${dataAttrLines(partAxes)}${partAxes.length ? "\n" : ""}      {...props}
     });
     const needsElementType = el.offersAs || Object.keys(recipe.parts ?? {}).length > 0;
     return `${header(slug, name, version, "css")}
-import "./${name}.css";
+import "./${localName}.css";
 
 import type { ${needsElementType ? `ElementType, ${props}` : props} } from "react";
 
@@ -727,11 +752,13 @@ ${rootJsx}
 }
 ${parts.filter(Boolean).join("\n")}`;
 }
-function emitTailwindMode(slug, name, recipe, version, props) {
+function emitTailwindMode(slug, name, recipe, version, props, 
+/** The name it takes in THEIR project. The utilities stay the system's. */
+localName = name) {
     const { tag, attrs, voidEl } = elementFor(name, recipe);
     const el = asElement(tag, attrs, voidEl);
     const axes = axesOf(recipe.variants);
-    const comp = pascal(name);
+    const comp = pascal(localName);
     const variantConsts = axes
         .filter((a) => !a.boolean)
         .map((a) => {
@@ -878,27 +905,37 @@ reactMajor = null,
  * every caller that predates the convention being the user's - and getting this
  * wrong shipped a component wearing classes its own stylesheet never emits.
  */
-convention = DEFAULT_CONVENTION) {
-    const comp = pascal(name);
+convention = DEFAULT_CONVENTION, 
+/**
+ * THE NAME IT TAKES IN THEIR PROJECT, when it cannot take its own.
+ *
+ * A project that already exports `Button` should not have to give the name up to
+ * install ours - we adapt to what they built. So the FILE and the EXPORT can be
+ * renamed while the CLASS stays the design system's: the recipe compiles
+ * `.ds-button`, and a `<MySystemButton>` wearing it is styled correctly and
+ * shadows nothing of theirs.
+ *
+ * Absent means the component keeps its own name, which is every caller today.
+ */
+localName = name) {
     const files = [];
     const props = propsTypeName(reactMajor);
     if (styles === "css") {
         files.push({
-            filename: `${name}.tsx`,
-            code: `${emitCssMode(slug, name, recipe, version, props, convention)}\n`,
+            filename: `${localName}.tsx`,
+            code: `${emitCssMode(slug, name, recipe, version, props, convention, localName)}\n`,
         });
-        files.push({ filename: `${name}.css`, code: `${css}\n` });
+        files.push({ filename: `${localName}.css`, code: `${css}\n` });
     }
     else {
         files.push({
-            filename: `${name}.tsx`,
-            code: `${emitTailwindMode(slug, name, recipe, version, props)}\n`,
+            filename: `${localName}.tsx`,
+            code: `${emitTailwindMode(slug, name, recipe, version, props, localName)}\n`,
         });
     }
     files.push({
         filename: "index.ts",
-        code: `export * from "./${name}";\n`,
+        code: `export * from "./${localName}";\n`,
     });
-    void comp;
     return files;
 }

package/dist/doctor/components-scan.js

@@ -13,17 +13,30 @@ const LITERAL_PROP = /([a-zA-Z][a-zA-Z0-9_-]*)\s*=\s*\{?\s*["']([^"']*)["']\s*\}
 /** `dense` with no value is a boolean prop set to true, and that IS a literal
  *  decision worth counting. */
 const BARE_PROP = /(^|\s)([a-z][a-zA-Z0-9_]*)(?=\s|$)/g;
+/**
+ * A KEYWORD IS NOT AN IDENTIFIER, and the difference decides whether a `<` opens
+ * an element. `return <Card>one</Card>` is a component; `useState<Foo>()` is a
+ * type argument. Both are preceded by a word.
+ *
+ * Prettier writes `return <Foo />;` on one line whenever it fits, so without this
+ * every short component written that way read as a generic and vanished from the
+ * inventory - which is how a spec for something else caught it.
+ */
+const JSX_BEFORE = /\b(return|case|default|await|yield|typeof|in|of|do|else|new)$/;
 /**
  * A generic in type position (`useState<Foo>()`, `Array<Item>`) is not an
  * element. The tell is what precedes the `<`: an identifier or a closing paren
- * means a type argument, while JSX follows `(`, `{`, `>`, a newline or nothing.
+ * means a type argument, while JSX follows `(`, `{`, `>`, a newline, a keyword or
+ * nothing.
  */
 function looksLikeType(source, at) {
     for (let i = at - 1; i >= 0; i--) {
         const c = source[i];
         if (c === " " || c === "\t")
             continue;
-        return /[A-Za-z0-9_)\]]/.test(c);
+        if (!/[A-Za-z0-9_)\]]/.test(c))
+            return false;
+        return !JSX_BEFORE.test(source.slice(Math.max(0, i - 11), i + 1));
     }
     return false;
 }
@@ -81,6 +94,56 @@ function importedNames(source, internal = []) {
     }
     return out;
 }
+/**
+ * Capitalised names a file BINDS ITSELF and does not export.
+ *
+ * `<Component>` and `<CustomLegend/>` both arrived in a real library's inventory as
+ * components of the system (dono, 01/08). Neither is one:
+ *
+ *     function Text({ as: Component = "p" })     // React's polymorphic idiom -
+ *                                                // `Component` is a prop rename
+ *     const CustomLegend = () => (…)             // a closure inside LineChart
+ *
+ * Capitalisation is React's rule for "not an html tag", which is not the same
+ * question as "is this a component the system offers". The test that separates them
+ * is REACHABILITY: a component of the system is either imported from somewhere or
+ * exported to somewhere. A name that only exists inside one function body is that
+ * function's private wiring, and giving it a recipe invents a component nobody can
+ * import.
+ *
+ * Local AND exported stays, of course - that is just a component defined where it
+ * is used.
+ */
+const BOUND = /(?:const|let|var|function|class)\s+([A-Z][A-Za-z0-9_]*)|[{,]\s*\w+\s*:\s*([A-Z][A-Za-z0-9_]*)\s*(?:=[^,}]*)?\s*[,}]/g;
+const EXPORTED_NAME = /export\s+(?:default\s+)?(?:async\s+)?(?:function|class|const|let|var)\s+([A-Z][A-Za-z0-9_]*)|export\s+default\s+([A-Z][A-Za-z0-9_]*)|export\s*\{([^}]*)\}/g;
+export function localOnlyNames(source) {
+    const exported = new Set();
+    EXPORTED_NAME.lastIndex = 0;
+    for (const m of source.matchAll(EXPORTED_NAME)) {
+        if (m[1])
+            exported.add(m[1]);
+        if (m[2])
+            exported.add(m[2]);
+        if (m[3]) {
+            for (const raw of m[3].split(",")) {
+                const name = raw
+                    .trim()
+                    .split(/\s+as\s+/)[0]
+                    ?.trim();
+                if (name && /^[A-Z]/.test(name))
+                    exported.add(name);
+            }
+        }
+    }
+    const out = new Set();
+    BOUND.lastIndex = 0;
+    for (const m of source.matchAll(BOUND)) {
+        const name = m[1] ?? m[2];
+        if (name && !exported.has(name))
+            out.add(name);
+    }
+    return out;
+}
 export function emptyTally() {
     return new Map();
 }
@@ -92,11 +155,16 @@ internal = []) {
     if (!/\.(tsx|jsx|vue|svelte)$/i.test(file))
         return;
     const owners = importedNames(source, internal);
+    const private_ = localOnlyNames(source);
     ELEMENT.lastIndex = 0;
     for (const m of source.matchAll(ELEMENT)) {
         if (m.index != null && looksLikeType(source, m.index))
             continue;
         const name = m[1];
+        // Private wiring, not a component of the system. An import wins: a file may
+        // shadow nothing and still bind a name it also imports.
+        if (!owners.has(name) && private_.has(name.split(".")[0]))
+            continue;
         const body = m[2] ?? "";
         let hit = tally.get(name);
         if (!hit) {

package/dist/doctor/crosswalk.js

@@ -304,8 +304,45 @@ function sharedMeaning(a, b) {
             n += 1;
     return n;
 }
-export function crosswalk(components) {
+/**
+ * WHEN THE SOURCE IS THE LIBRARY, EVERY COMPONENT IS THEIRS.
+ *
+ * The crosswalk was designed for an APP that uses components: "your Pill reads as
+ * our badge, use ours" is exactly right there, because it stops a duplicate. When the
+ * source IS the component library, the premise inverts - their library IS the design
+ * system, and mapping their component onto ours is us overwriting theirs with ours.
+ * The opposite of entering as a complement.
+ *
+ * Measured on a real library (dono, 01/08): of 37 components they export, 16 never
+ * became theirs. `Label`, `Pill` and `Tag` - three distinct components - collapsed
+ * into one `ds-badge` of ours, which is why their Tag previewed as the word "Pill":
+ * that is OUR recipe's sample text. `LineChart`, a real organism, simply was not in
+ * the system.
+ *
+ * The code already knew. `describeOrigin` says it in prose - "declared in
+ * `packages/ui` and composed nowhere inside it, which is what a component library
+ * looks like from the inside" - and then acted as if it were an app.
+ *
+ * THE SIGNAL, and it is not a guess: a library declares and does not compose itself.
+ * When most of what a scope declares is composed nowhere inside it, the scope is a
+ * library. The crosswalk still runs and its verdict still travels as INFORMATION -
+ * "this reads as our badge" is worth knowing - it just stops replacing anything.
+ */
+export function isLibrary(components) {
+    const mine = components.filter((c) => !c.from);
+    if (mine.length < 4)
+        return false;
+    const uncomposed = mine.filter((c) => (c.count ?? 0) === 0).length;
+    return uncomposed / mine.length >= 0.5;
+}
+export function crosswalk(components, 
+/**
+ * Their library is the system. Every component keeps its own recipe, and the
+ * catalogue match becomes a note rather than a substitution.
+ */
+opts) {
     const mine = components.filter((c) => !c.from);
+    const library = opts?.library ?? false;
     // Two of THEIR components reading as the same catalogue entry is the
     // strongest redundancy signal there is, and it needs no threshold: it is not
     // "these look alike", it is "you wrote this twice". The first run filed both
@@ -344,6 +381,24 @@ export function crosswalk(components) {
             .sort((a, b) => b.overlap - a.overlap);
         if (canonical && CATALOGUE[canonical]) {
             const alsoClaiming = (claims.get(canonical) ?? []).filter((n) => n !== component.name);
+            /**
+             * LIBRARY MODE: the match is a NOTE, not a verdict.
+             *
+             * Their component stays exclusive and keeps its own recipe; `canonical` still
+             * travels so a preview can resolve a frontier and so the v2 can say "these
+             * three read alike". What stops happening is their `Label` ceasing to exist.
+             */
+            if (library) {
+                return {
+                    component,
+                    canonical,
+                    twins,
+                    bucket: "exclusive",
+                    because: alsoClaiming.length > 0
+                        ? `yours, and it reads like ds-${canonical} - so do ${alsoClaiming.join(", ")}, which is one decision written ${alsoClaiming.length + 1} times`
+                        : `yours, and it reads like ds-${canonical} - kept as yours because this library IS the system`,
+                };
+            }
             if (alsoClaiming.length > 0) {
                 return {
                     component,
@@ -369,7 +424,9 @@ export function crosswalk(components) {
                 component,
                 canonical,
                 twins,
-                bucket: "nearly",
+                // A twin is a v2 observation either way; in library mode it must not cost
+                // the component its own recipe.
+                bucket: library ? "exclusive" : "nearly",
                 because: `shares ${Math.round(twins[0].overlap * 100)}% of its options with ${twins[0].name} - one decision, two components`,
             };
         }

package/dist/doctor/definitions-scan.js

@@ -20,6 +20,36 @@
  * 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.
  */
+/**
+ * THEIR OWN LADDER, READ OFF THE PATH - never guessed from a name.
+ *
+ * A real library keeps `atoms/Text/Text.tsx`, `molecules/MetricCard/`,
+ * `organisms/DataTable/`: the author saying out loud what composes what, in the
+ * vocabulary the whole industry already shares. Twenty-three components arrived in
+ * one flat bucket and the information was sitting in the path (dono, 01/08).
+ *
+ * A path segment, not a substring: `src/atomsphere/` is a folder called
+ * atomsphere. Returns undefined for the projects that do not organise themselves
+ * this way, which is most of them - and undefined means "no ladder here", not
+ * "unclassified".
+ */
+const TIER_FOLDER = {
+    atoms: "atom",
+    atom: "atom",
+    primitives: "atom",
+    molecules: "molecule",
+    molecule: "molecule",
+    organisms: "organism",
+    organism: "organism",
+};
+export function tierOf(file) {
+    for (const segment of file.split(/[/\\]/)) {
+        const tier = TIER_FOLDER[segment.toLowerCase()];
+        if (tier)
+            return tier;
+    }
+    return undefined;
+}
 /** `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
@@ -78,11 +108,13 @@ export function scanDefinitions(file, source) {
             continue;
         seen.add(name);
         const props = propsOf.get(name);
+        const tier = tierOf(file);
         out.push({
             name,
             file,
             axes: props?.axes ?? {},
             flags: props?.flags ?? [],
+            ...(tier ? { tier } : {}),
         });
     }
     return out;

package/dist/index.js

@@ -41,7 +41,7 @@ Usage - deterministic, FREE:
 
 Usage - governance (deterministic, FREE):
   synthesisui adopt [--write]              turn the design system you ALREADY have into a contract
-  synthesisui import [--dry] [--scope <p>]  read the app you already have and make it a system
+  synthesisui import [--scope <p>] [--usage <p>]  read what you already have and make it a system
                                            your agent follows - without touching your CSS
   synthesisui connect                      wire your agent: the check as an editor hook, the system
                                            as MCP tools, and a contract that stops repeating itself
@@ -66,7 +66,8 @@ Options:
   --version <n>      install a specific version (default: latest)
   --ds <slug>        init: bring this DS in right away · generate: target DS (default: installed)
   --name <name>      preferred component name for generate
-  --scope <path>     import: measure only this folder; the census still lands at the root
+  --scope <path>     import: the SYSTEM - tokens, components, convention. One folder.
+  --usage <path>     import: the EVIDENCE - counts, chosen values, laws. Repeatable.
   --scheme <s>       dark|light - which end of your ladder is the default
   --target <t>       template/init target: next | general (default: next)
   --pages-dir <dir>  init: folder for generated pages (default: app)
@@ -111,9 +112,30 @@ Examples:
   synthesisui generate "an upgrade banner with a title, message and a primary CTA"
 `;
 /** Extracts simple `--flag value` pairs and the remaining positionals. */
+/**
+ * A REPEATED FLAG ACCUMULATES rather than overwriting.
+ *
+ * `--usage apps/web --usage apps/admin` is the natural way to say two, and keeping
+ * only the last would drop one silently - which is the failure mode this codebase
+ * refuses everywhere else. Every existing flag is passed once and still arrives as
+ * a string, so nothing that reads `typeof flags.x === "string"` changes.
+ */
 function parseFlags(argv) {
     const positionals = [];
     const flags = {};
+    const put = (key, value) => {
+        const had = flags[key];
+        if (had === undefined) {
+            flags[key] = value;
+            return;
+        }
+        if (typeof value !== "string")
+            return;
+        flags[key] = [
+            ...(Array.isArray(had) ? had : typeof had === "string" ? [had] : []),
+            value,
+        ];
+    };
     for (let i = 0; i < argv.length; i++) {
         const arg = argv[i];
         if (arg === "-h" || arg === "--help") {
@@ -124,17 +146,17 @@ function parseFlags(argv) {
             const eq = body.indexOf("=");
             if (eq !== -1) {
                 // `--key=value` form (e.g. --out=templates/page.tsx)
-                flags[body.slice(0, eq)] = body.slice(eq + 1);
+                put(body.slice(0, eq), body.slice(eq + 1));
             }
             else {
                 // `--key value` form
                 const next = argv[i + 1];
                 if (next !== undefined && !next.startsWith("--")) {
-                    flags[body] = next;
+                    put(body, next);
                     i++;
                 }
                 else {
-                    flags[body] = true;
+                    put(body, true);
                 }
             }
         }
@@ -165,6 +187,14 @@ async function main() {
                 // invert a system, so it falls through to being measured and asked.
                 // WHAT to read. `--dir` stays WHERE the project is, in every command.
                 scope: typeof flags.scope === "string" ? flags.scope : undefined,
+                // WHERE THE EVIDENCE IS. Repeatable, and comma-separated works too - a
+                // person typing one path with a comma in it means two paths.
+                usage: [flags.usage]
+                    .flat()
+                    .filter((v) => typeof v === "string")
+                    .flatMap((v) => v.split(","))
+                    .map((v) => v.trim())
+                    .filter(Boolean),
                 scheme: flags.scheme === "dark" || flags.scheme === "light"
                     ? flags.scheme
                     : undefined,

package/dist/project-facts.js

@@ -13,8 +13,8 @@
  * handed somebody a React component wearing classes their own stylesheet never
  * emits. It renders completely unstyled, and nothing anywhere reports a problem.
  */
-import { readFile } from "node:fs/promises";
-import { join } from "node:path";
+import { readdir, readFile } from "node:fs/promises";
+import { join, relative } from "node:path";
 import { DEFAULT_CONVENTION, } from "./component-codegen.js";
 /**
  * Which React the consumer is on, for the ref-carrying prop type.
@@ -38,6 +38,62 @@ export async function reactMajorOf(root) {
         return null;
     }
 }
+export async function findCollision(root, componentsDir, name, pascal) {
+    const target = join(root, componentsDir, name, `${name}.tsx`);
+    const head = await readFile(target, "utf8")
+        .then((t) => t.slice(0, 300))
+        .catch(() => null);
+    const ours = head?.includes("Generated by SynthesisUI") ?? false;
+    /**
+     * Their own export of that name, searched where a component library lives.
+     *
+     * Deliberately shallow: `src`, `app`, `components`, `packages` and the
+     * configured folder, skipping anything generated. A deep walk of a monorepo to
+     * answer one question is not worth the seconds.
+     */
+    const pattern = new RegExp(`export\\s+(?:default\\s+)?(?:function|const|class)\\s+${pascal}\\b`);
+    const roots = [
+        componentsDir,
+        "src/components",
+        "components",
+        "src/ui",
+        "packages",
+    ];
+    let exported = null;
+    for (const rel of roots) {
+        if (exported)
+            break;
+        for await (const file of walkShallow(join(root, rel), 3)) {
+            if (!/\.(tsx|jsx|ts)$/.test(file))
+                continue;
+            if (file === target)
+                continue;
+            const source = await readFile(file, "utf8").catch(() => "");
+            if (source.includes("Generated by SynthesisUI"))
+                continue;
+            if (pattern.test(source)) {
+                exported = relative(root, file);
+                break;
+            }
+        }
+    }
+    return { file: head == null ? null : relative(root, target), exported, ours };
+}
+/** Files under `dir`, at most `depth` levels down, skipping the usual noise. */
+async function* walkShallow(dir, depth) {
+    if (depth < 0)
+        return;
+    const entries = await readdir(dir, { withFileTypes: true }).catch(() => []);
+    for (const entry of entries) {
+        if (entry.name.startsWith(".") || entry.name === "node_modules")
+            continue;
+        const full = join(dir, entry.name);
+        if (entry.isDirectory())
+            yield* walkShallow(full, depth - 1);
+        else
+            yield full;
+    }
+}
 /** The pinned version of an installed system, from its `.lock`. */
 async function pinnedVersion(dir) {
     const raw = await readFile(join(dir, ".lock"), "utf8").catch(() => "");