synthesisui 0.16.63 → 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "synthesisui",
-  "version": "0.16.63",
+  "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": {