synthesisui 0.16.80 → 0.16.81

package/dist/commands/import.js

@@ -2,9 +2,12 @@ import { mkdir, readdir, readFile, stat, writeFile } from "node:fs/promises";
 import { basename, dirname, join, relative } from "node:path";
 import { resolveAnatomy, resolveFlatParts, safePartName, } from "../anatomy-read.js";
 import { readCredentials, readToken, resolveRegistry, sameRegistry, } from "../config.js";
+import { describeArchitecture, describeChoice, detectArchitectures, } from "../doctor/architecture.js";
 import { findBrokenRefs } from "../doctor/broken-refs.js";
+import { nestingRules, propRules, readDefinitionProps, readNesting, } from "../doctor/call-sites.js";
 import { describeClassStyle, detectClassStyle, } from "../doctor/class-style.js";
 import { isNearDuplicate, isNeutral, lightness, } from "../doctor/color-distance.js";
+import { describeGate, gateComponent, groupSkips, } from "../doctor/component-gate.js";
 import { emptyTally, internalSpecifiers, scanComponentsInto, tallyToInventory, } from "../doctor/components-scan.js";
 import { crosswalk, isLibrary, observedRules } from "../doctor/crosswalk.js";
 import { reconcile, scanDefinitions, } from "../doctor/definitions-scan.js";
@@ -14,6 +17,7 @@ import { parseSchemeBlocks } from "../doctor/scheme-blocks.js";
 import { buildTable } from "../doctor/tokens.js";
 import { rootClasses, rootTag, transcribe, } from "../doctor/transcribe.js";
 import { body, paint, section } from "../output.js";
+import { startProgress } from "../progress.js";
 import { detectStack, resolveDeps } from "../stack.js";
 import { walk, walkAll } from "./doctor.js";
 /**
@@ -216,6 +220,8 @@ export async function takeCensus(root, opts) {
     const tally = emptyTally();
     const internal = await internalSpecifiers(root);
     const defined = [];
+    /** What the gate turned away, with the reason. Never dropped in silence. */
+    const skips = [];
     // Kept for the reference check below, which needs every file at once: a name
     // is only broken if NOTHING declares it, anywhere.
     const sources = [];
@@ -227,11 +233,39 @@ export async function takeCensus(root, opts) {
             declaredValues.set(m[1], m[2].trim());
     }
     const looks = {};
+    /**
+     * The directory shape, gathered while the files are already being walked - so
+     * naming how the project is organised costs no second pass. See `architecture.ts`.
+     */
+    const dirs = new Map();
+    /** Parent → child → the files that put one inside the other. */
+    const nesting = new Map();
+    /** Component → what its own definition names and whether it forwards the rest. */
+    const propsOf = new Map();
+    /**
+     * A census over a real monorepo reads 2797 files, and the terminal said nothing for
+     * most of it. Twenty silent minutes is indistinguishable from twenty broken ones
+     * (dono, 01/08).
+     */
+    const progress = startProgress("Reading");
     for await (const file of walk(root)) {
         const src = await readFile(file, "utf8").catch(() => "");
         if (!src)
             continue;
         const rel = relative(root, file);
+        progress.step(rel);
+        if (/\.(tsx|jsx|vue|svelte)$/i.test(rel)) {
+            const parts = rel.split("/");
+            // Every ancestor learns the name of the child directly under it, which is all
+            // the shape detector needs and is one pass rather than a tree walk.
+            for (let i = 0; i < parts.length - 1; i++) {
+                const at = parts.slice(0, i).join("/");
+                const entry = dirs.get(at) ?? { dirs: new Set(), files: 0 };
+                entry.dirs.add(parts[i]);
+                entry.files += 1;
+                dirs.set(at, entry);
+            }
+        }
         sources.push({ file: rel, source: src });
         reports.push(scanSource(rel, src, table));
         // Stories and tests compose components to SHOW them; counting those as the
@@ -239,9 +273,39 @@ export async function takeCensus(root, opts) {
         // 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.
-            const found = scanDefinitions(rel, src);
+            /**
+             * The other half: what this file EXPORTS, with the axes its types declare. A
+             * library composes almost nothing and exports everything.
+             *
+             * THROUGH THE GATE, which is the difference between 37 and 704. Every test in
+             * it is about CATEGORY - a route, a provider, a config object - never quality,
+             * and every rejection is carried with its reason.
+             */
+            // HOW IT IS USED, not only what it is: which props people pass, what it passes
+            // on, and what shows up inside it. See `call-sites.ts`.
+            readNesting(rel, src, nesting);
+            const found = [];
+            for (const d of scanDefinitions(rel, src)) {
+                const verdict = gateComponent({
+                    name: d.name,
+                    file: rel,
+                    source: src,
+                    internal,
+                });
+                if (verdict.ok) {
+                    found.push(d);
+                    continue;
+                }
+                skips.push({
+                    name: d.name,
+                    file: rel,
+                    why: verdict.why,
+                    because: verdict.because,
+                });
+            }
+            for (const d of found) {
+                propsOf.set(d.name, readDefinitionProps(d.name, src));
+            }
             defined.push(...found);
             // THE LOOK, from their own class names. One transcription per file, keyed
             // by the component it defines - the root element's classes are the
@@ -259,8 +323,14 @@ export async function takeCensus(root, opts) {
             }
         }
     }
+    progress.done();
+    const architectures = detectArchitectures([...dirs.entries()].map(([path, v]) => ({
+        path: path || ".",
+        dirs: [...v.dirs],
+        files: v.files,
+    })));
     const d = diagnose(reports);
-    const inventory = tallyToInventory(tally);
+    const allComposed = tallyToInventory(tally, 400);
     /**
      * THE EVIDENCE PASS - a second walk that touches ONE reading.
      *
@@ -275,6 +345,7 @@ export async function takeCensus(root, opts) {
      */
     const usageTally = emptyTally();
     const usageSeen = new Set();
+    const usageProgress = (opts?.usage ?? []).length > 0 ? startProgress("Evidence") : null;
     /**
      * THE SCOPE'S OWN PACKAGE NAME IS INTERNAL, always.
      *
@@ -299,9 +370,11 @@ export async function takeCensus(root, opts) {
                 continue;
             }
             usageSeen.add(rel);
+            usageProgress?.step(rel);
             scanComponentsInto(usageTally, rel, src, [...shared, ...uInternal]);
         }
     }
+    usageProgress?.done();
     const usedThere = tallyToInventory(usageTally, 400);
     /**
      * THE TWO READINGS BECOME ONE LIST before anything is judged.
@@ -316,6 +389,16 @@ export async function takeCensus(root, opts) {
      * is the better source anyway - usage shows what somebody picked, the
      * declaration shows what the author designed.
      */
+    /**
+     * THE GATE APPLIES FROM BOTH SIDES.
+     *
+     * A page reaches the inventory two ways: exported (caught above) and COMPOSED -
+     * `<AuthLayout>` wrapping a tree is a JSX tag like any other. Filtering only the
+     * definitions would have let it back in through the usage door under the same
+     * name, and the vitrine cannot tell which door a name came through.
+     */
+    const turnedAway = new Set(skips.map((s) => s.name));
+    const inventory = allComposed.filter((c) => !turnedAway.has(c.name));
     const composed = new Set(inventory.map((c) => c.name));
     const fromTypes = defined
         .filter((d) => !composed.has(d.name))
@@ -436,6 +519,37 @@ export async function takeCensus(root, opts) {
             console.log(body(paint.faint(`(${theirsOnly.length} component${theirsOnly.length === 1 ? "" : "s"} live there and not in the system - ${shown.join(", ")}${theirsOnly.length > shown.length ? ", …" : ""}. Left out on purpose: the system is one place, and a union of two codebases is not a system. Point --scope at them if they belong in it.)`)));
         }
     }
+    /**
+     * WHAT THE GATE TURNED AWAY - said out loud, grouped, with the reason.
+     *
+     * The sentence a person needs when a number drops by an order of magnitude: enough
+     * to trust it, and enough to notice if it dropped too far.
+     */
+    /**
+     * HOW THE PROJECT IS ORGANISED - and the choice it leaves open, when there is one.
+     *
+     * The skill asks which has priority; the chosen one becomes a system-wide rule that
+     * reaches CLAUDE.md, so every prompt after this respects where a new component goes.
+     */
+    if (architectures.length > 0) {
+        console.log("");
+        console.log(section("How this project is organised"));
+        const choice = describeChoice(architectures);
+        if (choice)
+            console.log(body(choice));
+        for (const a of architectures.slice(0, 4)) {
+            console.log(body(paint.faint(`  ${describeArchitecture(a)}`)));
+        }
+    }
+    if (skips.length > 0) {
+        console.log("");
+        console.log(body(describeGate(scoped.length, skips.length)));
+        for (const group of groupSkips(skips)) {
+            const shown = group.names.slice(0, 5);
+            const more = group.names.length - shown.length;
+            console.log(body(paint.faint(`  ${group.names.length} ${group.label}: ${shown.join(", ")}${more > 0 ? `, and ${more} more` : ""}`)));
+        }
+    }
     if (library) {
         console.log("");
         console.log(body(`This scope DECLARES its components and composes almost none of them inside itself - which is what a component library looks like from the inside. So every component it exports arrives as YOURS, with its own recipe. Where one reads like something in our catalogue, that is recorded as a note instead of replacing it.`));
@@ -452,6 +566,26 @@ export async function takeCensus(root, opts) {
     for (const r of observedRules(merged)) {
         laws.set(r.component, [...(laws.get(r.component) ?? []), r.text]);
     }
+    /**
+     * THE OWNER'S STEP FIVE, in the recipe's own `usage`.
+     *
+     * Whether a component forwards the rest of its props is the answer to "can I put an
+     * aria-label on it", and it is never in a type. And which components appear INSIDE it
+     * at its call sites is the composition half of a library's story - empty by
+     * construction until the app is read, because a library composes nothing internally.
+     */
+    const systemOwns = new Set(merged.filter((c) => !c.from).map((c) => c.name));
+    for (const c of merged) {
+        const read = propsOf.get(c.name);
+        if (!read)
+            continue;
+        for (const rule of propRules(c.name, read)) {
+            laws.set(c.name, [...(laws.get(c.name) ?? []), rule.text]);
+        }
+    }
+    for (const pair of nestingRules(nesting, systemOwns)) {
+        laws.set(pair.component, [...(laws.get(pair.component) ?? []), pair.text]);
+    }
     const components = merged.map((c) => ({
         ...c,
         ...(verdicts.get(c.name) ?? {}),
@@ -491,6 +625,16 @@ export async function takeCensus(root, opts) {
         observed: distinctValues(d),
         ...(components.length > 0 ? { components } : {}),
         ...(defined.length > 0 ? { defined } : {}),
+        ...(architectures.length > 0
+            ? { architectures: architectures.slice(0, 6) }
+            : {}),
+        ...(skips.length > 0
+            ? {
+                skipped: skips
+                    .slice(0, 400)
+                    .map(({ name, why, because }) => ({ name, why, because })),
+            }
+            : {}),
         ...((opts?.usage ?? []).length > 0
             ? { usage: (opts?.usage ?? []).map((u) => u.label) }
             : {}),

package/dist/doctor/architecture.js

@@ -0,0 +1,134 @@
+/**
+ * HOW THIS PROJECT IS ORGANISED - measured, chosen, and then true in every prompt.
+ *
+ * "The architecture of the project should live in a general rule as it is structured,
+ * because then in every prompt that architecture and the way the project was structured
+ * will be respected - and this can be analysed in the skill with the user selecting the
+ * correct architecture (a project can have more than one folder architecture, so we can
+ * just select which one has priority)" (dono, 01/08).
+ *
+ * It is the most underrated line in that message. Everything else in this pipeline
+ * describes what a component LOOKS like; this describes where the next one GOES. An
+ * agent that knows the palette and not the tree writes a correct component in the wrong
+ * place, and a person has to move it every time.
+ *
+ * MEASURED, NOT ASKED FIRST. The shapes below are counted off their real directories,
+ * ranked by how many components sit in each. A project genuinely has more than one -
+ * a library organised atomically inside a monorepo whose apps are organised by feature -
+ * so this returns all of them and the person picks which one has PRIORITY. That word is
+ * theirs and it is the right one: the others are still true, they just do not decide.
+ */
+const SHAPES = [
+    {
+        kind: "atomic",
+        needs: [
+            ["atoms", "atom"],
+            ["molecules", "molecule"],
+            ["organisms", "organism"],
+        ],
+        describe: (a) => `Components live in an atomic ladder under \`${a.root}\` - ${a.evidence.join("/")}. A new component goes on the rung that matches what it is made of: an atom composes nothing of yours, a molecule composes atoms, an organism is a whole region of a screen. Put it on the wrong rung and the ladder stops being true.`,
+    },
+    {
+        kind: "feature",
+        needs: [["features", "modules", "domains"]],
+        describe: (a) => `Code is organised BY FEATURE under \`${a.root}\`. A new component belongs to the feature that uses it, beside its own logic, and only moves up to the shared layer when a second feature needs it. Reaching across features is the thing this shape exists to prevent.`,
+    },
+    {
+        kind: "layered",
+        needs: [
+            ["ui", "components"],
+            ["hooks", "lib", "utils"],
+        ],
+        describe: (a) => `Code is split by LAYER under \`${a.root}\` - ${a.evidence.join(", ")}. A component goes in the ui layer and nothing else does; state and helpers stay in theirs. A component reaching into another layer is fine, a helper reaching back into ui is not.`,
+    },
+    {
+        kind: "colocated",
+        needs: [["app", "routes", "pages"]],
+        describe: (a) => `Components sit BESIDE THE ROUTE that uses them, under \`${a.root}\`. A new one starts local to its page and only moves to the shared folder when a second page needs it - which keeps the shared folder meaning "shared" rather than "everything".`,
+    },
+    {
+        kind: "flat",
+        needs: [["components"]],
+        describe: (a) => `Every component sits directly under \`${a.root}\`, one folder deep. It is the shape that stays legible longest while a system is small, and the one to revisit when the folder passes about forty names.`,
+    },
+];
+/**
+ * Which shapes this tree actually has, ranked by how much code each holds.
+ *
+ * `flat` is checked last and only reported when nothing more specific matched under the
+ * same root: a `components/` folder inside an atomic library is not a second
+ * architecture, it is the same one seen from further away.
+ */
+export function detectArchitectures(entries) {
+    const found = [];
+    for (const entry of entries) {
+        const lower = new Map(entry.dirs.map((d) => [d.toLowerCase(), d]));
+        for (const shape of SHAPES) {
+            const evidence = [];
+            let complete = true;
+            for (const alternatives of shape.needs) {
+                const hit = alternatives.map((a) => lower.get(a)).find(Boolean);
+                if (!hit) {
+                    complete = false;
+                    break;
+                }
+                evidence.push(hit);
+            }
+            if (!complete)
+                continue;
+            if (shape.kind === "flat" &&
+                found.some((f) => f.root === entry.path && f.kind !== "flat")) {
+                continue;
+            }
+            found.push({
+                kind: shape.kind,
+                root: entry.path,
+                files: entry.files,
+                evidence,
+            });
+        }
+    }
+    return found
+        .filter((a) => a.kind !== "flat" ||
+        !found.some((b) => b.root === a.root && b.kind !== "flat"))
+        .sort((a, b) => b.files - a.files || a.root.localeCompare(b.root));
+}
+/** The sentence that becomes the rule. Written for an agent about to add a file. */
+export function describeArchitecture(a) {
+    const shape = SHAPES.find((s) => s.kind === a.kind);
+    return shape ? shape.describe(a) : `Components live under \`${a.root}\`.`;
+}
+/**
+ * The rule itself, in the shape `reading.rules` holds.
+ *
+ * `applies` is EMPTY on purpose - this governs the system rather than a component, so
+ * it reaches CLAUDE.md and travels into every prompt instead of waiting for somebody to
+ * open one component. And `fact: true`, because it was read off their directories: it is
+ * true once, not a habit that needs a third sighting.
+ */
+export function architectureRule(a) {
+    return {
+        text: describeArchitecture(a),
+        applies: [],
+        kind: "implementation",
+        fact: true,
+        evidence: `${a.evidence.join("/")} under ${a.root}, holding ${a.files} component file${a.files === 1 ? "" : "s"}`,
+    };
+}
+/**
+ * One line naming what was found, and the choice it leaves open.
+ *
+ * A project with two shapes is not a project with a mistake. Saying so is what keeps
+ * the question from reading as an accusation.
+ */
+export function describeChoice(found) {
+    if (found.length === 0)
+        return null;
+    if (found.length === 1) {
+        return `One shape, read off your directories: ${found[0].kind} under \`${found[0].root}\`.`;
+    }
+    const list = found
+        .map((a) => `${a.kind} under \`${a.root}\` (${a.files} files)`)
+        .join(", ");
+    return `${found.length} shapes, and none of them is a mistake: ${list}. A library organised atomically inside a monorepo whose apps are organised by feature is two true answers. Pick which one has PRIORITY - it becomes the rule every prompt reads, and the others stay true without deciding.`;
+}

package/dist/doctor/call-sites.js

@@ -0,0 +1,171 @@
+/**
+ * HOW A COMPONENT IS ACTUALLY USED - the owner's step five, and the one nothing read.
+ *
+ * "For each component on the page understand how it is used, first the rules, what the
+ * component's recipe is, how many sub-components it has, which properties it is used
+ * with, does it have ...props? which does it make explicit? which does it use? that
+ * would be good to have in the component's usage/recipes" (dono, 01/08).
+ *
+ * Every one of those is answerable deterministically and none of it was being asked.
+ * Two readings already exist - what a component DECLARES and which literal values its
+ * props TAKE - and between them sits the question a person actually has when they are
+ * about to compose something: what do people pass it, what does it pass on, and what
+ * shows up beside it.
+ *
+ * THREE THINGS THIS ADDS
+ *
+ *   forwards      does the definition spread the rest of its props onto its element?
+ *                 If it does, anything you pass reaches the DOM - which is the answer
+ *                 to "can I put an aria-label on it" and it is never in a type.
+ *   explicit      which props the definition names and destructures. A prop that is
+ *                 named is a prop the author thought about; the rest is pass-through.
+ *   together      which components appear INSIDE this one at its call sites. A `Card`
+ *                 used with a `CardHeader` in twelve files is a pair, and that pair is
+ *                 a law nobody wrote down.
+ *
+ * The pairs come from USAGE rather than from the definition on purpose. A definition
+ * says what a component is made of; a call site says what people put in it, and those
+ * are different facts. A library composes nothing internally, so without this the
+ * composition half of a library's story is empty by construction.
+ */
+/**
+ * `function Name({ a, b, ...rest })`, `const Name = ({ a, …}) =>`, and
+ * `const Name = function ({ … })`.
+ *
+ * The arrow and the function expression share one shape - a parameter list opening with
+ * a destructure - so matching that is enough and no `=>` needs to appear. A first
+ * version tried to consume the arrow, and `([^)]*)` swallowed the destructure it was
+ * trying to reach, so every arrow component read as declaring no props (spec, 01/08).
+ */
+const DESTRUCTURED = /(?:function\s+([A-Z][A-Za-z0-9_]*)\s*\(\s*\{([^}]*)\}|(?:const|let)\s+([A-Z][A-Za-z0-9_]*)\s*(?::[^=]*)?=\s*(?:function\s*)?\(\s*\{([^}]*)\})/g;
+/** `{...rest}` / `{...props}` on a JSX element - the forwarding, in the markup. */
+const SPREAD_ONTO = /\{\s*\.\.\.\s*([A-Za-z_$][\w$]*)\s*\}/g;
+/**
+ * What a definition says about its own props.
+ *
+ * Both halves have to be true for `forwards`: a definition can collect a rest parameter
+ * and never spread it, which means the opposite of forwarding - it is deliberately
+ * swallowing what it was given.
+ */
+export function readDefinitionProps(name, source) {
+    const explicit = [];
+    let restName = null;
+    DESTRUCTURED.lastIndex = 0;
+    for (const m of source.matchAll(DESTRUCTURED)) {
+        const found = m[1] ?? m[3];
+        if (found !== name)
+            continue;
+        const body = m[2] ?? m[4] ?? "";
+        for (const raw of body.split(",")) {
+            const part = raw.trim();
+            if (!part)
+                continue;
+            if (part.startsWith("...")) {
+                restName = part.slice(3).trim() || null;
+                continue;
+            }
+            // `as: Component = "p"` names the prop `as`; the local alias is not the prop.
+            const prop = part.split(/[:=]/)[0].trim();
+            if (/^[a-zA-Z_$][\w$]*$/.test(prop) && !explicit.includes(prop)) {
+                explicit.push(prop);
+            }
+        }
+        break;
+    }
+    let forwards = null;
+    if (restName) {
+        SPREAD_ONTO.lastIndex = 0;
+        for (const m of source.matchAll(SPREAD_ONTO)) {
+            if (m[1] === restName) {
+                forwards = restName;
+                break;
+            }
+        }
+    }
+    return { explicit, forwards };
+}
+/**
+ * WHICH COMPONENTS APPEAR INSIDE THIS ONE, at its call sites.
+ *
+ * Depth one only, and that is the point: `<Card><CardHeader/><CardBody/></Card>` says
+ * Card is used with those two. What is inside CardHeader is CardHeader's own story, and
+ * following it further would turn one page into a claim about the whole tree.
+ *
+ * Counted per FILE rather than per occurrence, because "twelve files agree" is a claim
+ * about a habit and "twelve occurrences" can be one loop.
+ */
+export function readNesting(file, source, into = new Map()) {
+    const open = /<([A-Z][A-Za-z0-9_]*(?:\.[A-Z][A-Za-z0-9_]*)*)((?:[^>"']|"[^"]*"|'[^']*')*?)(\/?)>/gs;
+    const stack = [];
+    open.lastIndex = 0;
+    for (const m of source.matchAll(open)) {
+        const name = m[1];
+        const selfClosing = m[3] === "/";
+        const parent = stack[stack.length - 1];
+        if (parent && parent !== name) {
+            const children = into.get(parent) ?? new Map();
+            const files = children.get(name) ?? new Set();
+            files.add(file);
+            children.set(name, files);
+            into.set(parent, children);
+        }
+        if (!selfClosing)
+            stack.push(name);
+        // A closing tag is not matched by the pattern above, so the stack is trimmed by
+        // the next opening tag's own nesting rather than by tracking every `</x>`. It
+        // over-nests in a flat list of siblings, which is why depth is capped at one and
+        // the pair only counts once per file.
+        if (stack.length > 8)
+            stack.shift();
+    }
+    return into;
+}
+/**
+ * The composition pairs worth calling a law, and the sentence each becomes.
+ *
+ * `minFiles` is the ladder's own habit threshold - three files that agree - because
+ * that is what separates a pattern from a coincidence, and it is the same number every
+ * other observed rule uses.
+ */
+export function nestingRules(nesting, own, minFiles = 3) {
+    const out = [];
+    for (const [parent, children] of nesting) {
+        if (!own.has(parent))
+            continue;
+        for (const [child, files] of children) {
+            if (!own.has(child) || files.size < minFiles)
+                continue;
+            out.push({
+                component: parent,
+                child,
+                files: files.size,
+                text: `${parent} is used with ${child} - ${files.size} files put one inside the other, so keep the pair rather than reaching for something else inside it.`,
+            });
+        }
+    }
+    return out.sort((a, b) => b.files - a.files);
+}
+/**
+ * The two prop sentences, for `usage`.
+ *
+ * `forwards` is the one an agent needs and cannot get from a type: it is the difference
+ * between "this component accepts what I pass" and "this component ignores it". Stated
+ * as a permission rather than as a fact about the code, because that is how it will be
+ * read.
+ */
+export function propRules(name, read) {
+    const out = [];
+    if (read.forwards) {
+        out.push({
+            text: `${name} forwards the rest of its props to the element it renders, so anything you pass that it does not name - an id, an aria-label, a data attribute, a ref - reaches the DOM.`,
+            fact: true,
+        });
+    }
+    else if (read.explicit.length > 0) {
+        out.push({
+            text: `${name} names its props and forwards nothing else, so a prop it does not declare is dropped rather than passed through. It takes: ${read.explicit.slice(0, 12).join(", ")}.`,
+            fact: true,
+        });
+    }
+    return out;
+}