synthesisui 0.16.62 → 0.16.65

package/dist/commands/import.js

@@ -1,10 +1,12 @@
 import { mkdir, readdir, readFile, writeFile } from "node:fs/promises";
 import { basename, dirname, join, relative } from "node:path";
 import { readCredentials, readToken, resolveRegistry, sameRegistry, } from "../config.js";
+import { findBrokenRefs } from "../doctor/broken-refs.js";
 import { isNearDuplicate, isNeutral, lightness, } 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 { describeConvention, detectConventions, IDIOM_LABEL, } from "../doctor/idiom.js";
 import { diagnose, scanSource } from "../doctor/scan.js";
 import { parseSchemeBlocks } from "../doctor/scheme-blocks.js";
 import { buildTable } from "../doctor/tokens.js";
@@ -273,11 +275,15 @@ export async function takeCensus(root) {
     const tally = emptyTally();
     const internal = await internalSpecifiers(root);
     const defined = [];
+    // Kept for the reference check below, which needs every file at once: a name
+    // is only broken if NOTHING declares it, anywhere.
+    const sources = [];
     for await (const file of walk(root)) {
         const src = await readFile(file, "utf8").catch(() => "");
         if (!src)
             continue;
         const rel = relative(root, file);
+        sources.push({ file: rel, source: src });
         reports.push(scanSource(rel, src, table));
         // Stories and tests compose components to SHOW them; counting those as the
         // product's own composition is the same lie the colour census told before
@@ -368,10 +374,21 @@ export async function takeCensus(root) {
             // an unreadable package.json costs the name, not the run
         }
     }
+    // Every name their CSS defines, from the same harvest the token table came
+    // from - so a reference is judged against what actually exists, not against
+    // the subset we managed to read as a ramp.
+    const declaredNames = new Set();
+    for (const m of css.matchAll(/(--[a-zA-Z0-9_-]+)\s*:/g)) {
+        declaredNames.add(m[1]);
+    }
+    const brokenRefs = findBrokenRefs(sources, declaredNames);
+    const conventions = detectConventions(sources);
     return {
         census: 1,
         project: { name, stack: await detectStack(root) },
         declared: Object.fromEntries(table.byName),
+        ...(brokenRefs.length > 0 ? { brokenRefs } : {}),
+        ...(conventions.length > 0 ? { conventions } : {}),
         ...(schemes.alt.size > 0
             ? { declaredAlt: Object.fromEntries(schemes.alt) }
             : {}),
@@ -435,6 +452,55 @@ function summarize(c) {
             console.log(body(`${paint.strong(v.value)} ${paint.faint(`${v.kind}, ${v.count}× in ${v.files} file${v.files === 1 ? "" : "s"}`)}`));
         }
     }
+    sayConventions(c);
+    sayBrokenRefs(c);
+}
+/**
+ * THEIR VOCABULARY, MEASURED. This section exists so every later finding can be
+ * phrased as "you already do X, and here you did not" instead of "adopt ours".
+ */
+function sayConventions(c) {
+    const list = c.conventions ?? [];
+    if (list.length === 0)
+        return;
+    console.log("");
+    console.log(section("How you reference a value"));
+    for (const conv of list) {
+        console.log(body(describeConvention(conv)));
+        const off = conv.offIdiom.filter((o) => o.count > 0).slice(0, 3);
+        if (off.length > 0) {
+            console.log(body(paint.faint(`  and ${off.map((o) => `${o.count} ${IDIOM_LABEL[o.idiom]}`).join(", ")}`)));
+        }
+    }
+    console.log("");
+    console.log(body(paint.faint("Nothing here is a rule we brought. It is what your own files do most, so the rest can be named against it.")));
+}
+/**
+ * NOT DRIFT - BROKEN. A `var()` no declaration answers renders nothing at all,
+ * so this goes above everything else the census has to say. It is also the one
+ * finding that needs no agreement with us: the convention being broken is
+ * theirs.
+ */
+function sayBrokenRefs(c) {
+    const broken = c.brokenRefs ?? [];
+    if (broken.length === 0)
+        return;
+    const uses = broken.reduce((n, b) => n + b.count, 0);
+    console.log("");
+    console.log(section("These resolve to nothing"));
+    console.log(body(`${uses} reference${uses === 1 ? "" : "s"} to ${broken.length} token${broken.length === 1 ? "" : "s"} your CSS never declares. A ${paint.strong("var()")} with no declaration paints no colour - not a different colour.`));
+    console.log("");
+    for (const b of broken.slice(0, 8)) {
+        const where = `${b.count}× in ${b.files} file${b.files === 1 ? "" : "s"}`;
+        console.log(body(b.meant
+            ? `${paint.strong(`var(${b.name})`)} ${paint.faint(where)} - you declare ${paint.strong(b.meant)}`
+            : `${paint.strong(`var(${b.name})`)} ${paint.faint(`${where}, and nothing close is declared`)}`));
+    }
+    if (broken.length > 8) {
+        console.log(body(paint.faint(`(${broken.length - 8} more)`)));
+    }
+    console.log("");
+    console.log(body(paint.faint("Yours to fix in your own words - nothing here asks you to adopt ours.")));
 }
 /**
  * The contract an agent needs, printed where an agent will read it.

package/dist/doctor/broken-refs.js

@@ -0,0 +1,75 @@
+/**
+ * TOKENS REFERENCED AND NEVER DECLARED.
+ *
+ * Not drift, not taste - a variable that resolves to nothing. `var(--ocean-50)`
+ * in a project whose token is `--color-ocean-50` renders no colour at all, and
+ * the component ships with no background.
+ *
+ * Found by accident (dono, 01/08) while sizing something else: seven of nine
+ * references in one real `ImageUploader` were missing the `color-` prefix, and
+ * it is live. Nobody noticed because a missing background looks like a design
+ * choice.
+ *
+ * This is the highest-value thing a first read can say, and it costs nothing to
+ * find: it is arithmetic over two sets. It also needs no adoption of anything of
+ * ours - the convention being violated is THEIRS. A person can act on it in
+ * their own vocabulary, in the next commit, without agreeing to a single idea
+ * this product has (dono, 01/08: "a normalização será de acordo com cada
+ * projeto").
+ */
+/** `var(--x)`, including inside a Tailwind arbitrary value: `bg-[var(--x)]`. */
+const VAR_REF = /var\(\s*(--[a-zA-Z0-9_-]+)/g;
+/**
+ * PREFIXES A DECLARATION MAY CARRY that a reference dropped.
+ *
+ * Tailwind v4's `@theme` is the reason this happens at all: declaring
+ * `--color-ocean-50` publishes the variable under that full name AND the
+ * utility `bg-ocean-50`, so a person who reads their own utilities and then
+ * reaches for `var()` writes the utility's name and gets nothing.
+ */
+const NAMESPACES = [
+    "color",
+    "spacing",
+    "radius",
+    "font",
+    "text",
+    "shadow",
+    "ease",
+    "animate",
+];
+/**
+ * Every reference no declaration answers, commonest first.
+ *
+ * `declared` is the set of names their own CSS defines, verbatim. Anything the
+ * scan could not attribute is left out rather than guessed at.
+ */
+export function findBrokenRefs(sources, declared) {
+    const seen = new Map();
+    for (const { file, source } of sources) {
+        for (const m of source.matchAll(VAR_REF)) {
+            const name = m[1];
+            if (declared.has(name))
+                continue;
+            const hit = seen.get(name) ?? { count: 0, files: new Set() };
+            hit.count += 1;
+            hit.files.add(file);
+            seen.set(name, hit);
+        }
+    }
+    const out = [];
+    for (const [name, hit] of seen) {
+        const bare = name.slice(2);
+        const meant = NAMESPACES.map((ns) => `--${ns}-${bare}`).find((c) => declared.has(c));
+        out.push({
+            name,
+            count: hit.count,
+            files: hit.files.size,
+            ...(meant ? { meant } : {}),
+        });
+    }
+    // A broken reference somebody typed nine times is worse than one typed once,
+    // and one we can name a target for is actionable before one we cannot.
+    return out.sort((a, b) => Number(b.meant != null) - Number(a.meant != null) ||
+        b.count - a.count ||
+        a.name.localeCompare(b.name));
+}

package/dist/doctor/idiom.js

@@ -0,0 +1,132 @@
+/**
+ * HOW THIS PROJECT REFERENCES A VALUE - and it is not one answer per project.
+ *
+ * Measured on a real monorepo (dono, 01/08), scoping by project looked like
+ * divergence and was not: `packages/ui` read 52% `var()` and 39% utility, which
+ * is one directory holding `.tsx` and `.scss` in the same bucket. Split by
+ * LANGUAGE the picture is unambiguous:
+ *
+ *     .tsx    80% tailwind utility
+ *     .scss   66% css var()
+ *     .css    67% css var()
+ *
+ * So the convention belongs to the language, the project is already chosen by
+ * `--scope`, and neither needs a person to pick it - it is measured. What a
+ * person gets instead is the useful half: what does NOT follow the idiom their
+ * own files overwhelmingly use.
+ *
+ * WHY THIS MATTERS MORE THAN OUR TOKENS (dono, 01/08). A report that says "use
+ * `{color.ocean.500}`" asks somebody to restructure a repo to suit us - in a
+ * shadcn project that is a migration with real incompatibility risk and a commit
+ * nobody wants to review. A report that says "you write `bg-ocean-500` in 80% of
+ * your JSX and here you wrote a hex" asks for nothing. Same decision, their
+ * vocabulary, a commit the size of the problem.
+ *
+ * It also explained the worst bug this census has found. `bg-[var(--ocean-50)]`
+ * is not merely a dropped `color-` prefix: it is the CSS idiom used inside the
+ * JSX idiom - a change of language mid-sentence - and the `.scss` beside it
+ * spells the same token correctly, because there that language is the right one.
+ */
+/** How each idiom reads, for the report. */
+export const IDIOM_LABEL = {
+    "tailwind-utility": "Tailwind utility",
+    "css-var": "var(--token)",
+    "raw-hex": "raw hex",
+    "tailwind-arbitrary-var": "var() inside a utility",
+    "shadcn-hsl": "hsl(var(--token))",
+};
+const PATTERNS = [
+    // Order matters where two could match the same text: the shadcn wrapper and
+    // the arbitrary-value form are both `var()` and both more specific than it.
+    ["shadcn-hsl", /hsl\(\s*var\(\s*--/g],
+    [
+        "tailwind-arbitrary-var",
+        /\b(?:bg|text|border|ring|fill|stroke|shadow|from|to|via)-\[var\(\s*--/g,
+    ],
+    [
+        "tailwind-utility",
+        /\b(?:bg|text|border|ring|fill|stroke|from|to|via)-(?:[a-z]+-)+\d{2,3}\b/g,
+    ],
+    ["css-var", /var\(\s*--/g],
+    ["raw-hex", /#[0-9a-fA-F]{6}\b/g],
+];
+/**
+ * Extensions worth reporting separately, because they are separate languages
+ * with separate correct answers. Anything else is counted and not split out.
+ */
+const LANGUAGES = new Set([".tsx", ".jsx", ".scss", ".css", ".less", ".sass"]);
+/**
+ * A custom-property declaration, whose right-hand side is a DEFINITION.
+ * Deliberately not anchored to a line start: these are written inside `:root`,
+ * `@theme` and nested blocks at every indentation.
+ */
+const DECLARATION = /--[a-zA-Z0-9_-]+\s*:[^;}]*/g;
+/**
+ * Count references per language and name the dominant idiom.
+ *
+ * A language with too few references to be conclusive is left out rather than
+ * given a convention on the strength of three sightings: claiming a project's
+ * convention from noise is worse than saying nothing, because every later
+ * finding inherits the claim.
+ */
+export function detectConventions(sources, minReferences = 20) {
+    const byLanguage = new Map();
+    for (const { file, source } of sources) {
+        const dot = file.lastIndexOf(".");
+        const ext = dot === -1 ? "" : file.slice(dot).toLowerCase();
+        if (!LANGUAGES.has(ext))
+            continue;
+        const counts = byLanguage.get(ext) ?? new Map();
+        // A DECLARATION IS NOT A REFERENCE. `--color-ocean-500: #059aed` is where a
+        // hex belongs, and counting it made a design system's own token file read as
+        // 87% raw hex - the worst drift in the repo, when it is the opposite: the one
+        // place every other value should be pointing at (dono, 01/08).
+        let rest = source.replace(DECLARATION, "");
+        // A more specific pattern claims its matches first, so the same text is
+        // never counted twice - `bg-[var(--x)]` is one arbitrary-value reference,
+        // not also a `var()` one.
+        for (const [idiom, re] of PATTERNS) {
+            const found = rest.match(re);
+            if (!found)
+                continue;
+            counts.set(idiom, (counts.get(idiom) ?? 0) + found.length);
+            rest = rest.replace(re, "");
+        }
+        byLanguage.set(ext, counts);
+    }
+    const out = [];
+    for (const [language, counts] of byLanguage) {
+        const total = [...counts.values()].reduce((n, v) => n + v, 0);
+        if (total < minReferences)
+            continue;
+        const ranked = [...counts.entries()].sort((a, b) => b[1] - a[1]);
+        const [idiom, top] = ranked[0];
+        out.push({
+            language,
+            idiom,
+            share: top / total,
+            total,
+            offIdiom: ranked.slice(1).map(([i, count]) => ({ idiom: i, count })),
+        });
+    }
+    return out.sort((a, b) => b.total - a.total);
+}
+/**
+ * One line per language, in the report's voice and in THEIR vocabulary.
+ *
+ * A raw hex winning is NOT a convention. It is the absence of one, and saying
+ * "this language reaches for raw hex" dignifies it into a house style somebody
+ * might defend - when what the number means is that nothing there points at
+ * anything (dono, 01/08).
+ */
+export function describeConvention(c) {
+    const pct = Math.round(c.share * 100);
+    if (c.idiom === "raw-hex") {
+        return `${c.language} has no convention - ${pct}% of its ${c.total} references are values typed in place`;
+    }
+    return `${c.language} reaches for ${IDIOM_LABEL[c.idiom]} - ${pct}% of the ${c.total} references in it`;
+}
+/** True when this language's dominant answer is "no answer". */
+export function hasConvention(c) {
+    return c.idiom !== "raw-hex";
+}

package/dist/skill-import.js

@@ -166,29 +166,107 @@ about which one is the page. Read a screen and see.
 **\`fonts\` and \`concept\`** - the voice, and one paragraph on what this product is. The concept
 feeds every recommendation downstream, so a real one beats a generic one by a wide margin.
 
-### 3. Confirm once, then send
+### 3. Walk them through the decisions, one at a time
 
-You have made three decisions on their behalf by now - **where** you measured, **what** it will
-be called, and **which values** carry which meaning. Put all three in one place and ask. Not a
-report that contains a question at the bottom: a question.
+Four decisions are theirs. **Ask them as separate questions with selectable options** - use your
+question tool, one call per decision, so they pick instead of reading a wall and composing a
+reply. A single block containing everything is a report, and a report gets read, not answered.
 
-Offer the alternatives you actually considered, so choosing is a choice and not a veto:
+Every question carries **your recommendation first, marked as such**, and the evidence for it in
+one line. They are choosing, not auditing you.
 
+**3a. Source** - the folder you measure the system out of.
+
+Options are the candidates the CLI already ranked, each with what it would produce, plus the
+whole repo, plus *somewhere else* for a path they type:
+
+\`\`\`
+Where should the system come from?
+
+  packages/ui (recommended)    114 files · 47% of its values already named ·
+                               92 tokens of their own · every app imports it
+  the whole repo               2797 files · 36% · the average of one dark app
+                               and two light ones, which is a diagnosis and
+                               not a system
+  apps/web-dashboard           the heaviest consumer, if you want one app's
+                               vocabulary rather than the shared one
+  somewhere else               a path you name
+\`\`\`
+
+If they name a path you cannot use, say which of the two it is and offer the list again:
+
+- **it does not exist**, or holds no files you can read
+- **it holds no design values** - no colours, no radii, no tokens. A folder of server code or
+  config is not a design system, and measuring it produces a system of nothing.
+
+**3b. Name** - suggest theirs, and let Enter take it:
+
+\`\`\`
+What should it be called?  (SignalUI)
+\`\`\`
+
+Say where the suggestion came from - \`Introduction.mdx\`, the package name, the folder. A name
+they recognise is worth more than a clever one. The slug is derived once and never changes, so
+this is the moment.
+
+**3c. Primary** - and explain the role before offering the choice, because *primary* is our word
+and not necessarily theirs:
+
+\`\`\`
+Primary is the colour that carries action - buttons, links, focus, the thing
+you want pressed. Everything else in the system is measured for contrast
+against it.
+
+  #059aed  ocean-500 (recommended)     your ColorPalette.mdx calls Ocean the
+                                       "Primary branding scale"
+  #1a4ed8  royal-blue-500              your docs label this one secondary
+  #ec4899  vivid-pink-500              half of your signature AI gradient
+  #4A90E2  blue-500                    the most-painted blue in the folder,
+                                       but it sits after your own
+                                       /* End - Signal UI */ marker
 \`\`\`
-I'd create a system from packages/ui, called SignalUI, opening dark.
 
-  from      packages/ui   114 files, 47% of its values already named
-            (apps/web-dashboard, apps/web-review and apps/web-admin
-             are the consumers; measuring all of them gave 36%, which
-             is the average of a light app and two dark ones)
-  called    SignalUI      their own name, from Introduction.mdx
-  brand     #059aed       their docs call Ocean the primary scale
-  opens     dark          data-theme="dark" in the root layout
+Always name the hex AND the token, and always give the reason a value is *not* recommended when
+frequency would have picked it. That last row is the whole point of asking.
 
-This creates it on your account. Go ahead, or change any of these?
+**3d. Default theme** - which face it opens in:
+
+\`\`\`
+  dark (recommended)   data-theme="dark" in the root layout, next-themes
+                       defaultTheme="dark", enableSystem={false}
+  light                the other one, also real here
+\`\`\`
+
+**Two is all there is** - a SynthesisUI system carries one palette and one alternate, and the
+schema is \`"light" | "dark"\`. So this is not "which themes do you support", it is "which one do
+docs and installs open in". If both are real, both get built from their own tokens; this picks
+the face.
+
+**3e. Canvas** - confirm, do not offer a list. The page is measured, not chosen:
+
+\`\`\`
+canvas  #222326  darkgray-500 - what DashboardLayout paints on <main>
+                 (your sidebar sits a step deeper at darkgray-700)
 \`\`\`
 
-Then, and only after they answer:
+Say it and let them object. Offering five near-blacks to pick between is asking someone to
+re-decide something their code already decided.
+
+**3f. Fonts** - do not ask at all. Report and move on:
+
+\`\`\`
+fonts   Figtree for both display and body - the only family declared
+        (--font-sans, and next/font Figtree in all three root layouts)
+\`\`\`
+
+If a project genuinely declares two families, say which is which and why you paired them that
+way. If it declares one, there is nothing to decide.
+
+**A note on colour swatches.** You cannot paint a hex in this conversation, so the token name
+carries the weight - \`ocean-500\` tells someone more than a square would. When they run
+\`npx synthesisui import\` themselves in a terminal, the CLI paints them.
+
+Then, and only after all four are answered:
 
 \`\`\`
 npx synthesisui import --census _synthesisui/census.json --name "<the name>" [--registry <from step 0>]
@@ -196,10 +274,11 @@ npx synthesisui import --census _synthesisui/census.json --name "<the name>" [--
 
 **This is the one real write.** Everything before it is on their disk and costs nothing to redo.
 
-The CLI asks for a name unless \`--name\` is passed, and it does **not** ask about the scheme when
-your reading already answered - a second question would only be a chance to contradict you. So
-if you skip the confirmation above, nobody is asked about the scope at all, and the first time
-they learn where their system came from is when they open it.
+Pass every answer explicitly - \`--name\`, \`--scope\` if they changed it, and the reading rewritten
+with their primary and their theme. The CLI cannot ask anything when you are the one running it:
+it has no terminal, so its own prompts are skipped by design. **Whatever you did not ask, nobody
+asked.** Skip 3a and the first time they learn where their system came from is when they open
+it.
 
 If it refuses, it says which of the three it is: no session, an expired one, or a token issued
 by a different host. All are recoverable from the census on disk; none need a re-measure.

package/package.json

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