synthesisui 0.16.77 → 0.16.79

package/dist/anatomy-read.js

@@ -0,0 +1,272 @@
+/**
+ * THE ANATOMY THE SKILL READ, TURNED INTO SOMETHING THE SYSTEM CAN HOLD.
+ *
+ * The first version of this contract asked for the parts as a FLAT LIST and threw
+ * away the structure the skill had just finished reading. So an `ArticleCard`
+ * with a 16:9 cover, a title, a full editor and a footer of five buttons came
+ * back as four labels in a row - and the owner compared it to the real component
+ * and saw a broken version of it. It was not a broken version. It was not a
+ * version of anything (dono, 01/08).
+ *
+ * THE THREE FRONTIERS, and knowing which one a node is is the whole job:
+ *
+ *   a PART       an element of theirs      it has styles, and we draw it
+ *   a COMPONENT  a component of theirs     it has a recipe of its own, so it
+ *                                          renders as a NAMED BLOCK and becomes
+ *                                          a rule about the two of them
+ *   an EXTERNAL  a third-party library     we do not have it and never will, so
+ *                                          it renders as a block and becomes
+ *                                          rules about how to build with it
+ *
+ * **Depth is not a number, it is where the frontier sits.** The skill descends
+ * until it meets another component or a library, stops, and records the edge -
+ * which answers "how deep should a part go" without inventing a parameter, and
+ * makes the answer different per component because it genuinely is.
+ *
+ * WHAT THIS FILE GUARANTEES, and it is the reason the two halves are derived from
+ * one source instead of being sent as two fields: the flat `parts` map and the
+ * tree can never disagree. A tree pointing at a part that does not exist would
+ * validate everywhere and render as a hole, and "valid and unread" is the worst
+ * of the three outcomes this pipeline has paid for twice.
+ */
+import { transcribe, } from "./doctor/transcribe.js";
+/** The nine forms, closed. A renderer that accepts any tag draws anything. */
+const FORMS = new Set([
+    "image",
+    "heading",
+    "text",
+    "button",
+    "field",
+    "icon",
+    "row",
+    "stack",
+    "component",
+    "external",
+]);
+/** The two that arrange, and the only two that take children. */
+const CONTAINERS = new Set(["row", "stack"]);
+/** The two frontiers: no name, no styles - what is there is not ours to hold. */
+const FRONTIERS = new Set(["component", "external"]);
+/**
+ * Names that ARE the element itself. A node for one of these draws a box inside
+ * its own box, because its styles already sit on the component's base.
+ */
+const STRUCTURAL = /^(root|wrapper|base|el|outer)$/i;
+/** A pathological transcription of somebody's DOM, bounded. Six levels reaches
+ *  any real component; past that it is layout divs all the way down. */
+const MAX_DEPTH = 6;
+const MAX_NODES = 48;
+/**
+ * `Actions.Generate` → `actions-generate`, and never `actions.generate`.
+ *
+ * A dot compiles to `.ds-card-actions.generate`, which is two classes and
+ * invalid - and `z.record(z.string())` validates the key all the way through to
+ * a broken stylesheet, so the guard has to be here rather than in the schema.
+ */
+export function safePartName(raw) {
+    return raw
+        .trim()
+        .replace(/([a-z0-9])([A-Z])/g, "$1-$2")
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/-+/g, "-")
+        .replace(/^-|-$/g, "")
+        .replace(/^([0-9])/, "n$1");
+}
+/**
+ * Which form a node takes, forgiving a wrong label without losing the subtree.
+ *
+ * A tenth form is a mistake, and the cheap response - drop the node - would take
+ * its children with it. Something with children ARRANGES, so it becomes a stack;
+ * something without carries content, so it becomes text.
+ */
+function formOf(node) {
+    const as = String(node.as ?? "")
+        .trim()
+        .toLowerCase();
+    if (FORMS.has(as))
+        return { as, coerced: false };
+    const arranges = Array.isArray(node.children) && node.children.length > 0;
+    return { as: arranges ? "stack" : "text", coerced: true };
+}
+/**
+ * Fold the anatomy into a flat parts map and a tree, in one pass.
+ *
+ * `declared` is their own tokens, so a `bg-ocean-500` on a nested part resolves
+ * to the name they gave it rather than to a literal.
+ */
+export function resolveAnatomy(read, declared, deps, 
+/** Their name → the slug it reaches in this system. See `RefResolver`. */
+resolve, 
+/** What the component returns, when the skill said and it is not a plain tag. */
+root) {
+    const parts = {};
+    const composes = [];
+    const external = [];
+    const notes = [];
+    let budget = MAX_NODES;
+    let coerced = 0;
+    /**
+     * A SINGLE STRUCTURAL ROOT IS THE COMPONENT, NOT A NODE OF IT.
+     *
+     * The skill is told not to send `root`/`wrapper`, and when it does anyway at
+     * the top the honest fix is to unwrap it: its styles are the base's, and
+     * keeping it would draw the component inside a copy of itself.
+     */
+    let top = read;
+    while (Array.isArray(top) &&
+        top.length === 1 &&
+        top[0] &&
+        STRUCTURAL.test(String(top[0].name ?? "")) &&
+        Array.isArray(top[0].children) &&
+        top[0].children.length > 0) {
+        top = top[0].children;
+        notes.push("the outermost wrapper is the component itself, so its children are the anatomy");
+    }
+    /** Part names, deduped: a second `label` becomes `label-2`, deterministically. */
+    const claim = (wanted) => {
+        if (parts[wanted] == null)
+            return wanted;
+        for (let n = 2; n < 100; n++) {
+            const candidate = `${wanted}-${n}`;
+            if (parts[candidate] == null)
+                return candidate;
+        }
+        return `${wanted}-x`;
+    };
+    const walk = (nodes, depth) => {
+        const out = [];
+        if (depth > MAX_DEPTH)
+            return out;
+        for (const node of nodes) {
+            if (!node || typeof node !== "object")
+                continue;
+            if (budget <= 0)
+                break;
+            budget -= 1;
+            const { as, coerced: wasCoerced } = formOf(node);
+            if (wasCoerced)
+                coerced += 1;
+            // A FRONTIER carries a reference and nothing else. A name or a class list
+            // on one would be us claiming styles that belong to somebody else.
+            if (FRONTIERS.has(as)) {
+                if (as === "component") {
+                    const name = String(node.ref ?? "").trim();
+                    if (!name)
+                        continue;
+                    if (!composes.includes(name))
+                        composes.push(name);
+                    /**
+                     * THE CROSSWALK DECIDES WHAT THIS REACHES.
+                     *
+                     * `Tag` is bucketed `nearly` with canonical `badge`; kebab-casing it
+                     * looks for `ds-tag` and finds nothing. Without a resolver we keep the
+                     * kebab, which is what a system generated by us would want anyway.
+                     */
+                    const slug = resolve?.(name) ?? safePartName(name);
+                    out.push(slug && slug !== safePartName(name)
+                        ? { as, ref: slug, refName: name }
+                        : { as, ref: slug || safePartName(name) });
+                    continue;
+                }
+                const from = String(node.from ?? "").trim();
+                if (!from)
+                    continue;
+                const version = deps?.[from];
+                if (!external.some((e) => e.from === from))
+                    external.push({ from, version });
+                out.push(version ? { as, from, version } : { as, from });
+                continue;
+            }
+            const node_ = { as };
+            // The NAME is what carries the styles, so it is claimed even when nothing
+            // resolved: the tree triggers on presence, and structure is most of the
+            // value. A node with no name is pure structure and that is legitimate.
+            const wanted = safePartName(String(node.name ?? ""));
+            if (wanted) {
+                const key = claim(wanted);
+                if (key !== wanted) {
+                    notes.push(`two parts named \`${wanted}\` - the second is \`${key}\``);
+                }
+                const classes = typeof node.classes === "string"
+                    ? node.classes.split(/\s+/).filter(Boolean)
+                    : [];
+                const t = transcribe(classes, declared);
+                parts[key] = { base: t.base, dark: t.dark, states: t.states };
+                node_.part = key;
+            }
+            const text = typeof node.text === "string" ? node.text.trim() : "";
+            if (text)
+                node_.text = text.slice(0, 120);
+            // Only the two arrangers descend. A leaf with children is a leaf that was
+            // labelled wrongly, and its children would render nowhere.
+            if (CONTAINERS.has(as) && Array.isArray(node.children)) {
+                const children = walk(node.children, depth + 1);
+                if (children.length > 0)
+                    node_.children = children;
+            }
+            else if (Array.isArray(node.children) && node.children.length > 0) {
+                const children = walk(node.children, depth + 1);
+                // Hoist rather than lose them: the label was wrong, the structure was not.
+                out.push(node_, ...children);
+                continue;
+            }
+            out.push(node_);
+        }
+        return out;
+    };
+    const tree = walk(top, 0);
+    /**
+     * THE ROOT, RESOLVED THE SAME WAY.
+     *
+     * A dotted capitalised name is somebody else's namespace - `Radio.Root`,
+     * `BaseDialog.Root` - so there is nothing of theirs to reach and the honest
+     * answer is to name the library. Anything else is a component of theirs and goes
+     * through the crosswalk exactly like a child frontier does.
+     */
+    let rootOut;
+    const rootRaw = String(root ?? "").trim();
+    if (rootRaw && /^[A-Z]/.test(rootRaw)) {
+        if (rootRaw.includes(".")) {
+            rootOut = { from: rootRaw };
+        }
+        else {
+            const slug = resolve?.(rootRaw) ?? safePartName(rootRaw);
+            if (slug)
+                rootOut = { ref: slug, name: rootRaw };
+        }
+    }
+    if (coerced > 0) {
+        notes.push(`${coerced} node${coerced === 1 ? "" : "s"} named a form that does not exist - kept, drawn as what ${coerced === 1 ? "it holds" : "they hold"}`);
+    }
+    if (budget <= 0) {
+        notes.push(`the anatomy was longer than ${MAX_NODES} nodes - the rest is layout, and it is not read`);
+    }
+    return {
+        parts,
+        tree,
+        composes,
+        external,
+        notes,
+        ...(rootOut ? { root: rootOut } : {}),
+    };
+}
+/**
+ * The OLD flat form, folded into the same result shape.
+ *
+ * 23 standard components carry flat parts and no tree, and a skill written
+ * against the previous contract sends this. Both keep working: the parts style
+ * correctly, and the absence of a tree means the preview lays them out in a row
+ * exactly as it did before.
+ */
+export function resolveFlatParts(read, declared) {
+    const parts = {};
+    for (const part of read) {
+        const name = safePartName(String(part?.name ?? ""));
+        if (!name || typeof part.classes !== "string")
+            continue;
+        const t = transcribe(part.classes.split(/\s+/).filter(Boolean), declared);
+        parts[name] = { base: t.base, dark: t.dark, states: t.states };
+    }
+    return { parts, tree: [], composes: [], external: [], notes: [] };
+}

package/dist/commands/add.js

@@ -6,7 +6,7 @@ import { customFontFamilies, googleFontsHref, nextFontSnippet, } from "../fonts.
 import { buildGuide } from "../guide.js";
 import { body as line, section, snippet } from "../output.js";
 import { fetchDesignSystem } from "../registry.js";
-import { describeFiltered, rulesForProject } from "../rule-filter.js";
+import { describeFiltered, ruleApplies, rulesForProject, } from "../rule-filter.js";
 import { detectStack } from "../stack.js";
 async function readRootLock(path) {
     try {
@@ -97,6 +97,28 @@ export async function add(slug, opts) {
     // a thing the person should hear once, not discover by its absence.
     if (leftOut)
         console.log(line(leftOut));
+    /**
+     * 5b-ii. THE PACKAGES THIS SYSTEM NEEDS, kept where the doctor can read them.
+     *
+     * `rules.md` is prose with maximum authority, and prose is the wrong thing to
+     * enforce against: a check that grepped "requires @tiptap/react" out of a
+     * sentence would break the first time somebody reworded it. So the one
+     * verifiable field travels as data, filtered by THIS project's stack exactly
+     * like the prose was.
+     *
+     * Written only when there is something to say, so a system with no third-party
+     * component leaves no file behind.
+     */
+    const required = (payload.ruleSet ?? [])
+        .filter((r) => r.requires && ruleApplies(r, stack))
+        .map((r) => ({
+        requires: r.requires,
+        applies: r.applies ?? [],
+        ...(r.pinned ? { pinned: r.pinned } : {}),
+    }));
+    if (required.length > 0) {
+        await writeFile(join(slugDir, "requires.json"), `${JSON.stringify(required, null, 2)}\n`, "utf8");
+    }
     // 5c. structured philosophy (personal DS) → philosophy.md at the slug root.
     //     Narrative guidance (mission, principles, voice, motion doctrine…); the
     //     GUIDE points the agent here right after rules.md.

package/dist/commands/component.js

@@ -5,6 +5,7 @@ import { generateComponentFiles } from "../component-codegen.js";
 import { readProjectConfig, resolveRegistry } from "../config.js";
 import { hasInteractiveTemplate, interactiveTemplate, } from "../interactive-templates.js";
 import { body, section, snippet } from "../output.js";
+import { findCollision, reactMajorOf, readInstalledConvention, } from "../project-facts.js";
 import { fetchComponent, RegistryError } from "../registry.js";
 /**
  * Writes the shared `cn.ts` next to the components, built from THIS project's
@@ -27,28 +28,6 @@ async function writeCn(root, compDir, slug) {
         return;
     await writeFile(join(compDir, "..", "cn.ts"), emitCn(slug, readVocabulary(real)), "utf8");
 }
-/**
- * The consumer's React major, or null when we cannot tell.
- *
- * It decides whether the generated components can take a `ref`: from 19 that is
- * an ordinary prop, before it a function component needs `forwardRef`. Guessing
- * high on an older project would emit a type that accepts a ref React then
- * silently drops, so anything unreadable falls back to the ref-less type.
- */
-async function reactMajorOf(root) {
-    const raw = await readFile(join(root, "package.json"), "utf8").catch(() => "");
-    if (!raw)
-        return null;
-    try {
-        const pkg = JSON.parse(raw);
-        const spec = pkg.dependencies?.react ?? pkg.devDependencies?.react;
-        const major = /(\d+)/.exec(spec ?? "")?.[1];
-        return major ? Number(major) : null;
-    }
-    catch {
-        return null;
-    }
-}
 /** Slugs/names are kebab-case by contract; reject anything else before it ever
  *  reaches a filesystem path (defense-in-depth against `../` traversal). */
 const SAFE_NAME = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
@@ -89,6 +68,43 @@ export async function component(slug, name, opts) {
     const config = await readProjectConfig(root);
     const wantInteractive = opts.interactive && hasInteractiveTemplate(res.name);
     if (!opts.artifactsOnly && config.target === "next") {
+        /**
+         * WE DO NOT TAKE A NAME THEY ARE USING.
+         *
+         * This wrote with a bare `writeFile`, so it overwrote whatever was there - and
+         * a project that already has its own `Button` is the normal case. The
+         * crosswalk makes it sharper: their `ToolbarButton` resolves to `button`, so
+         * asking for one hands back a `Button`, which is a different component.
+         *
+         * Re-materializing something WE generated is almost always what they meant, so
+         * that keeps going. Shadowing a component of theirs stops and asks.
+         */
+        const pascalName = res.name
+            .split(/[^a-zA-Z0-9]+/)
+            .filter(Boolean)
+            .map((p) => p[0].toUpperCase() + p.slice(1))
+            .join("");
+        const clash = await findCollision(root, config.componentsDir, res.name, pascalName);
+        if (!opts.force && (clash.exported || (clash.file && !clash.ours))) {
+            console.log(section("This name is already taken in your project"));
+            if (clash.exported) {
+                console.log(body(`\`${pascalName}\` is already exported from ${clash.exported}.`));
+            }
+            if (clash.file && !clash.ours) {
+                console.log(body(`${clash.file} exists and we did not write it.`));
+            }
+            console.log("");
+            console.log(body("The recipe and the compiled CSS are on disk either way - only the .tsx was not written. Your options:"));
+            console.log("");
+            console.log(snippet([
+                `npx synthesisui component ${slug} ${res.name} --force`,
+                `# or bring it under a name of your own:`,
+                `npx synthesisui component ${slug} ${res.name} --as my-${res.name}`,
+            ]));
+            console.log("");
+            console.log(body("Nothing of yours was touched. Which name it takes is your call, not ours."));
+            return;
+        }
         const compDir = join(root, config.componentsDir, res.name);
         await mkdir(compDir, { recursive: true });
         let filenames;
@@ -103,7 +119,16 @@ export async function component(slug, name, opts) {
             filenames = [`${res.name}.tsx`, `${res.name}.css`, "index.ts"];
         }
         else {
-            const files = generateComponentFiles(slug, res.name, res.recipe, res.css, res.version, config.styles, await reactMajorOf(root));
+            const files = generateComponentFiles(slug, res.name, res.recipe, res.css, res.version, config.styles, await reactMajorOf(root), 
+            /**
+             * THE SPELLING, FROM THE VERSION WE JUST FETCHED.
+             *
+             * The response wins over the document on disk because it belongs to the
+             * exact version being written - and the CSS in `res.css` was compiled with
+             * it, so the TSX and the stylesheet in the same folder agree by
+             * construction. Falling back to disk keeps an older registry working.
+             */
+            res.classNames ?? (await readInstalledConvention(root, slug)));
             for (const file of files) {
                 await writeFile(join(compDir, file.filename), file.code, "utf8");
             }

package/dist/commands/doctor.js

@@ -3,6 +3,7 @@ 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 { describeMissing, missingDependencies, summarizeMissing, } from "../doctor/dependencies.js";
 import { findFrozenBindings } from "../doctor/frozen.js";
 import { appendEvent, readEvents, summarize } from "../doctor/ledger.js";
 import { bindingsFromDocument, countComponents, findOverrides, } from "../doctor/overrides.js";
@@ -11,6 +12,7 @@ import { diagnose, scanSource, siblingTokens, } from "../doctor/scan.js";
 import { findSelfConflicts, forbiddenProps, isReset, propMatchesLabel, } from "../doctor/self-conflict.js";
 import { buildTable, EMPTY_TABLE, nearestToken, } from "../doctor/tokens.js";
 import { body, paint, section, snippet } from "../output.js";
+import { resolveDeps } from "../stack.js";
 /**
  * `synthesisui doctor` - the check nobody else ships.
  *
@@ -114,7 +116,12 @@ export async function loadSystem(root) {
             .map((e) => e.name);
     }
     catch {
-        return { table: EMPTY_TABLE, recipes: new Map(), documents: [] };
+        return {
+            table: EMPTY_TABLE,
+            recipes: new Map(),
+            documents: [],
+            requires: [],
+        };
     }
     // Several systems can live side by side; every token is prefixed --ds-, so
     // reading them all is both correct and what the running app actually sees.
@@ -123,6 +130,7 @@ export async function loadSystem(root) {
     let adopted = false;
     const recipes = new Map();
     const documents = [];
+    const requires = [];
     for (const slug of slugs) {
         const dir = join(dsDir, slug);
         const raw = await readFile(join(dir, ".lock"), "utf8").catch(() => "");
@@ -182,11 +190,25 @@ export async function loadSystem(root) {
                 // A document we cannot parse costs the component pass, not the run.
             }
         }
+        // Written by `add` only when this system has a third-party component, so its
+        // absence is the normal case rather than a failure.
+        const reqRaw = await readFile(join(dir, "requires.json"), "utf8").catch(() => "");
+        if (reqRaw) {
+            try {
+                const parsed = JSON.parse(reqRaw);
+                if (Array.isArray(parsed))
+                    requires.push(...parsed);
+            }
+            catch {
+                // Unreadable costs this check, not the run.
+            }
+        }
     }
     return {
         table: buildTable({ css, lock, source: adopted ? "adopted" : "installed" }),
         recipes,
         documents,
+        requires,
     };
 }
 /**
@@ -870,6 +892,32 @@ export async function doctor(opts) {
         say(body("complains - the surface just stays put when the scheme"));
         say(body("moves around it."));
     }
+    /**
+     * THE LIBRARIES THE SYSTEM SAYS YOU NEED - the half that makes a rule about a
+     * third-party component into governance rather than a sentence.
+     *
+     * Some of their components are built on somebody else's library. We do not have
+     * it, cannot draw it, and said so: the anatomy stops at the frontier and the
+     * knowledge moved into a rule carrying the package name as DATA. This is where
+     * that gets checked, against the same manifest reader the stack detection uses.
+     *
+     * It never installs. A dependency has a licence, a bundle cost and a maintainer
+     * attached, so the answer is to report and let them decide.
+     */
+    const missingDeps = missingDependencies(installed.requires, await resolveDeps(root).catch(() => ({})));
+    if (missingDeps.length > 0) {
+        say(section("This system needs libraries you do not have"));
+        const summary = summarizeMissing(missingDeps);
+        if (summary)
+            say(body(summary));
+        say("");
+        for (const dep of describeMissing(missingDeps))
+            say(body(dep));
+        say("");
+        say(body("Nothing was installed for you. Install what you actually use:"));
+        say("");
+        say(`          npm i ${missingDeps.map((d) => d.name).join(" ")}`);
+    }
     const frozenAt = new Set(frozen.map((f) => `${f.component}:${f.where.split(" · ").pop()}`));
     let offSystemCount = 0;
     let lawKeepingCount = 0;

package/dist/commands/generate.js

@@ -2,6 +2,7 @@ import { mkdir, readdir, readFile, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import { generateComponentFiles } from "../component-codegen.js";
 import { readProjectConfig, resolveRegistry } from "../config.js";
+import { reactMajorOf, readInstalledConvention } from "../project-facts.js";
 import { postGenerate, RegistryError } from "../registry.js";
 /** PascalCase para o hint de import (course-card → CourseCard). */
 function pascalName(name) {
@@ -70,7 +71,10 @@ export async function generate(description, opts) {
         const version = await readActiveVersion(root, slug);
         const compDir = join(root, config.componentsDir, res.name);
         await mkdir(compDir, { recursive: true });
-        const files = generateComponentFiles(slug, res.name, res.recipe, res.css, version, config.styles);
+        const files = generateComponentFiles(slug, res.name, res.recipe, res.css, version, config.styles, await reactMajorOf(root), 
+        // Read off the installed document: a generated component lands in the same
+        // project as the stylesheet it has to match.
+        await readInstalledConvention(root, slug));
         for (const file of files) {
             await writeFile(join(compDir, file.filename), file.code, "utf8");
         }