synthesisui 0.12.0 → 0.13.0

package/dist/commands/doctor.js

@@ -137,12 +137,38 @@ async function loadSystem(root) {
     }
     return { table: buildTable({ css, lock }), recipes, documents };
 }
+/**
+ * The project's OWN vocabulary, when we did not put one there.
+ *
+ * Measured 27/07 against a repo holding eight `--acme-*` tokens in `:root`, a
+ * button correctly on `var(--acme-color-primary)` and a banner hardcoding the
+ * same `#3b82f6`: the report said "No system installed" and counted five
+ * anonymous values. That is the exact reader the landing page invites - the
+ * one who already owns a system and wants to know whether the code still
+ * obeys it - and the tool was blind to them because `parseTokens` only ever
+ * looked for our own `--ds-` prefix.
+ *
+ * Reads stylesheets only, and only when nothing of ours is installed, so the
+ * common path pays nothing for it.
+ */
+async function harvestOwnTokens(roots) {
+    let css = "";
+    for await (const file of walkAll(roots)) {
+        if (!/\.(css|scss|sass|less)$/i.test(file))
+            continue;
+        css += `\n${await readFile(file, "utf8").catch(() => "")}`;
+    }
+    return buildTable({ css, source: "yours" });
+}
 const KIND_LABEL = {
     color: "colour",
     radius: "radius",
     spacing: "spacing",
     font: "type",
 };
+/** "1 file", "2 files" - a report that says "1 files read" on its very first
+ *  line spends credibility before it has said anything. */
+const plural = (n, one, many = `${one}s`) => `${n} ${n === 1 ? one : many}`;
 /** A bar you can read at a glance, in a font that is always monospace. */
 function meter(pct, width = 24) {
     const filled = Math.round((pct / 100) * width);
@@ -217,9 +243,16 @@ function verdict(d, hasSystem, overruled, conflicts) {
 }
 export async function doctor(opts) {
     const root = resolve(opts.dir ?? process.cwd());
-    const { table, recipes, documents } = await loadSystem(root);
-    const hasSystem = table.byName.size > 0;
     const scopes = (opts.scopes ?? []).map((s) => resolve(root, s));
+    const installed = await loadSystem(root);
+    const { recipes, documents } = installed;
+    let table = installed.table;
+    // Nothing of ours here does not mean nothing to measure against. Fall back
+    // to whatever vocabulary the project already declares for itself.
+    if (table.byName.size === 0) {
+        table = await harvestOwnTokens(scopes.length > 0 ? scopes : [root]);
+    }
+    const hasSystem = table.byName.size > 0;
     const reports = [];
     const overrides = [];
     const used = new Map();
@@ -261,9 +294,15 @@ export async function doctor(opts) {
             console.log(line);
     };
     console.log(section("Doctor"));
-    console.log(body(hasSystem
-        ? `${table.name ?? table.slug} v${table.version ?? "?"} - ${table.byName.size} tokens, ${d.scanned} files read`
-        : `No system installed - ${d.scanned} files read`));
+    console.log(body(
+    // Three states, not two. "yours" has no lock to name it, and printing
+    // `null v?` for a project that DOES have a system would be the worst
+    // possible first line.
+    table.source === "installed"
+        ? `${table.name ?? table.slug} v${table.version ?? "?"} - ${plural(table.byName.size, "token")}, ${plural(d.scanned, "file")} read`
+        : table.source === "yours"
+            ? `Your own tokens - ${plural(table.byName.size, "token")} found, ${plural(d.scanned, "file")} read`
+            : `No system installed - ${plural(d.scanned, "file")} read`));
     if (scopes.length > 0) {
         console.log(body(`scope: ${opts.scopes?.join(", ")}`));
     }
@@ -281,11 +320,11 @@ export async function doctor(opts) {
     const asideTotal = [...aside.values()].reduce((n, v) => n + v, 0);
     if (verbose) {
         for (const [reason, count] of aside) {
-            console.log(body(`set aside: ${count} value(s) in ${reason}`));
+            console.log(body(`set aside: ${plural(count, "value")} in ${reason}`));
         }
     }
     else if (asideTotal > 0) {
-        console.log(body(`set aside ${asideTotal} value(s) a token could never hold (--verbose for why)`));
+        console.log(body(`set aside ${plural(asideTotal, "value")} a token could never hold (--verbose for why)`));
     }
     // 0 of 0 is not a perfect score, it is an empty measurement - printing a
     // full bar there would be the report's first lie.
@@ -595,7 +634,7 @@ export async function doctor(opts) {
     else if (!verbose) {
         if (conflictsInUse.length + frozen.length > 0) {
             console.log("");
-            console.log(body(`${conflictsInUse.length + frozen.length} problem(s) in the SYSTEM - not fixable from this repo`));
+            console.log(body(`${plural(conflictsInUse.length + frozen.length, "problem")} in the SYSTEM - not fixable from this repo`));
             for (const c of conflictsInUse) {
                 console.log(`      ds-${c.component}    the law forbids ${c.forbids}, the recipe binds it`);
             }
@@ -605,8 +644,8 @@ export async function doctor(opts) {
         }
         if (d.findings.length > 0 || overrides.length > 0) {
             console.log("");
-            console.log(body(`${d.findings.length} value(s) by hand · ${d.named} already have a name`));
-            console.log(body(`${overrides.length - lawKeepingCount} override(s) · ${offSystemCount} left the system` +
+            console.log(body(`${plural(d.findings.length, "value")} by hand · ${d.named} already ${d.named === 1 ? "has" : "have"} a name`));
+            console.log(body(`${plural(overrides.length - lawKeepingCount, "override")} · ${offSystemCount} left the system` +
                 (lawKeepingCount > 0
                     ? ` · ${lawKeepingCount} more kept a law`
                     : "")));
@@ -633,11 +672,11 @@ export async function doctor(opts) {
         // authors their own system wants the opposite, and asks for it.
         const theirs = conflictsInUse.length + frozen.length;
         if (opts.strictSystem && theirs > 0) {
-            console.log(body(`--strict-system: ${theirs} problem(s) in the system itself. Failing.`));
+            console.log(body(`--strict-system: ${plural(theirs, "problem")} in the system itself. Failing.`));
             process.exitCode = 1;
         }
         else if (theirs > 0) {
-            console.log(body(`${theirs} problem(s) above are in the system, not this repo - not failing.`));
+            console.log(body(`${plural(theirs, "problem")} above ${theirs === 1 ? "is" : "are"} in the system, not this repo - not failing.`));
             console.log(body("Run with --strict-system if the system is yours."));
         }
         if (mine)

package/dist/commands/upgrade.js

@@ -6,6 +6,64 @@ import { diffLocalDocuments, localChangelogMarkdown, } from "../document-diff.js
 import { body, section, snippet } from "../output.js";
 import { fetchChangelog, fetchComponent, fetchDesignSystem, RegistryError, } from "../registry.js";
 import { add } from "./add.js";
+/**
+ * The highest `v<n>` below `installed` among the folder names given, or the one
+ * asked for. Pure, so the version arithmetic can be tested without a disk.
+ */
+export function pickSnapshot(names, installed, asked) {
+    const versions = names
+        .map((n) => /^v(\d+)$/.exec(n))
+        .filter((m) => m !== null)
+        .map((m) => Number(m[1]))
+        .filter((v) => v < installed)
+        .sort((a, b) => b - a);
+    if (asked !== undefined)
+        return versions.includes(asked) ? asked : null;
+    return versions[0] ?? null;
+}
+/**
+ * Re-diff two snapshots already on disk and rewrite UPGRADE.md. Touches
+ * nothing else: the artifacts are already correct, it is only the brief about
+ * them that was written by an older, wronger version of this tool.
+ */
+async function rewriteBrief(slug, slugDir, from, to) {
+    const read = async (v) => JSON.parse(await readFile(join(slugDir, `v${v}`, "design-system.json"), "utf8"));
+    let local;
+    try {
+        local = diffLocalDocuments(await read(from), await read(to));
+    }
+    catch {
+        console.log(`✗ could not read both snapshots (v${from}, v${to}).`);
+        return;
+    }
+    const brief = [
+        localChangelogMarkdown(slug, from, to, local),
+        "",
+        "---",
+        "",
+        "## How to migrate this app",
+        "",
+        "- Fix the **Breaking** items first: search the codebase for each removed",
+        "  token/component/variant and move usages to the closest replacement.",
+        "- Changed tokens re-theme automatically (CSS variables) - review screens",
+        "  that hardcoded values instead of tokens.",
+        "- The full new contract lives in `design-system.json` / `GUIDE.md` next to this file.",
+        "",
+    ].join("\n");
+    await writeFile(join(slugDir, "UPGRADE.md"), brief, "utf8");
+    console.log(section(`Rewrote the brief: ${slug} v${from} → v${to}`));
+    if (local.breaking.length > 0) {
+        console.log(body(`Breaking changes (${local.breaking.length}):`));
+        console.log("");
+        console.log(snippet(local.breaking.map((i) => `- ${i}`)));
+    }
+    else {
+        console.log(body("No breaking changes between those two versions."));
+    }
+    console.log("");
+    console.log(body(`_synthesisui/ds/${slug}/UPGRADE.md`));
+    console.log("");
+}
 /**
  * Marco B - `synthesisui upgrade <slug>`: brings the installed system to the
  * latest version, GUIDED. In one run it:
@@ -38,7 +96,25 @@ export async function upgrade(slug, opts) {
     console.log(`→ checking "${slug}" (installed: v${installed}) …`);
     const latest = await fetchDesignSystem(base, slug);
     if (latest.version === installed) {
-        console.log(`✓ ${slug} is already at the latest version (v${installed}).`);
+        if (!opts.force) {
+            console.log(`✓ ${slug} is already at the latest version (v${installed}).`);
+            return;
+        }
+        // The brief is a PHOTOGRAPH: written once, at the moment of the upgrade,
+        // and it ages. When the tool that wrote it is fixed - as the breaking-change
+        // diff was on 25/07, after it had announced ten changes that were not
+        // breaking - the file on disk keeps the old answer and there is no way back
+        // to it, because there is no version gap left to trigger a rewrite. This is
+        // that way back: re-diff from the highest older snapshot still on disk.
+        const onDisk = await readdir(slugDir).catch(() => []);
+        const from = pickSnapshot(onDisk, installed, opts.from);
+        if (from === null) {
+            console.log(opts.from !== undefined
+                ? `✗ v${opts.from} is not on disk under ${slugDir}.`
+                : `✗ nothing to diff against: no snapshot older than v${installed} on disk.`);
+            return;
+        }
+        await rewriteBrief(slug, slugDir, from, installed);
         return;
     }
     if (latest.version < installed) {

package/dist/doctor/scan.js

@@ -38,23 +38,53 @@ const RADIUS = /(?:border-radius\s*:\s*|rounded(?:-[a-z]+)?-\[)(-?\d*\.?\d+)(px|
 const SPACING = /(?:\b[pmg](?:[trblxy])?-\[|gap-\[|(?:padding|margin|gap)\s*:\s*)(-?\d*\.?\d+)(px|rem)/g;
 /** A font stack written by hand rather than taken from the type scale. */
 const FONT = /font-family\s*:\s*([^;}\n]+)/g;
-/** Uses of the system. Coverage is meaningless without them. */
-const TOKEN_USE = /var\(\s*--ds-[a-z0-9-]+/gi;
+/**
+ * Uses of the system. Coverage is meaningless without them.
+ *
+ * Both of these used to be pinned to our own `--ds-` prefix, which quietly
+ * decided that only OUR systems count. A project with `--acme-color-primary`
+ * in `:root` and `var(--acme-color-primary)` in a button was reported at 0%
+ * coverage while doing everything right (measured 27/07). The rule now: our
+ * prefix always counts, and any other custom property counts once we have
+ * seen it declared - which is exactly what the token table knows.
+ */
+const ANY_VAR_USE = /var\(\s*(--[a-z0-9_-]+)/gi;
+const ANY_VAR_FALLBACK = /var\(\s*(--[a-z0-9_-]+)\s*,([^()]*)\)/gi;
+const isKnownToken = (name, table) => name.startsWith("--ds-") || table.byName.has(name);
+function countTokenUses(line, table) {
+    let n = 0;
+    for (const m of line.matchAll(ANY_VAR_USE)) {
+        if (isKnownToken(m[1].toLowerCase(), table))
+            n++;
+    }
+    return n;
+}
 /**
  * `var(--ds-color-semantic-primary, #5266eb)` - the literal is the TOKEN'S OWN
  * fallback, written for safety, and reporting it as drift told an author to
  * tokenize something they had already tokenized (investidorez, 25/07). The
  * spans below are the fallback arguments on a line.
  */
-const VAR_FALLBACK = /var\(\s*--ds-[a-z0-9-]+\s*,([^()]*)\)/gi;
-function fallbackSpans(line) {
+function fallbackSpans(line, table) {
     const out = [];
-    for (const m of line.matchAll(VAR_FALLBACK)) {
+    for (const m of line.matchAll(ANY_VAR_FALLBACK)) {
+        if (!isKnownToken(m[1].toLowerCase(), table))
+            continue;
         const start = (m.index ?? 0) + m[0].indexOf(",") + 1;
-        out.push([start, start + m[1].length]);
+        out.push([start, start + m[2].length]);
     }
     return out;
 }
+/**
+ * The line that DEFINES a token is not a line that drifted from it.
+ *
+ * Our own tokens.css lives under `_synthesisui`, which the walk skips, so this
+ * never came up. A project's own stylesheet does not have that luxury: on the
+ * first run against one, every `--acme-color-primary: #3b82f6` came back as a
+ * hardcoded colour, which is the tool accusing the author of the very thing it
+ * is measuring them against.
+ */
+const DECLARES_TOKEN = /^\s*(--[a-z0-9_-]+)\s*:/i;
 /** Under this, a radius or spacing value is idiom rather than a decision. */
 const IDIOM = new Set(["0", "0px", "1px", "9999px", "100%", "50%"]);
 export function scanSource(file, source, table) {
@@ -81,7 +111,7 @@ export function scanSource(file, source, table) {
     source.split("\n").forEach((raw, i) => {
         const line = raw.trim();
         const at = i + 1;
-        tokenUses += (line.match(TOKEN_USE) ?? []).length;
+        tokenUses += countTokenUses(line, table);
         // Depth at the START of this line, carried before the early return so a
         // blank line inside an <svg> cannot close the region by accident. The
         // per-match depth is recomputed below, because an icon is often written on
@@ -93,11 +123,18 @@ export function scanSource(file, source, table) {
             (line.match(/<\/svg>/g) ?? []).length);
         if (!line || IGNORE_LINE.test(line))
             return;
+        // The declaration of a token we are measuring against is the definition,
+        // not drift. Scoped to tokens the table already knows, so a one-off
+        // `--card-shadow: 0 2px 8px #0002` invented inside a component is still
+        // reported - that one really is a decision made outside the system.
+        const declares = DECLARES_TOKEN.exec(line);
+        if (declares && table.byName.has(declares[1].toLowerCase()))
+            return;
         // `rgba(${r}, ${g}, ${b}, ${a})` is code computing a colour, not a colour
         // written by hand - flagging it would be telling someone to tokenize a
         // variable. And the same literal twice in one declaration (a two-stop
         // shadow) is one decision, so it is reported once.
-        const spans = fallbackSpans(line);
+        const spans = fallbackSpans(line, table);
         const inFallback = (at) => spans.some(([a, b]) => at >= a && at <= b);
         const seen = new Set();
         // NOT named `at`: that is the line number in this scope, and shadowing it

package/dist/doctor/tokens.js

@@ -12,6 +12,7 @@
  * returns data, so the whole diagnosis is testable without a filesystem.
  */
 export const EMPTY_TABLE = {
+    source: null,
     name: null,
     slug: null,
     version: null,
@@ -21,6 +22,62 @@ export const EMPTY_TABLE = {
 const hex2 = (n) => Math.max(0, Math.min(255, Math.round(n)))
     .toString(16)
     .padStart(2, "0");
+/** Linear-light channel to the sRGB byte a screen actually paints. */
+const gamma = (c) => (c <= 0.0031308 ? 12.92 * c : 1.055 * c ** (1 / 2.4) - 0.055) * 255;
+/**
+ * `oklch(0.648 0.2 131.684)` → the same key as the hex somebody pasted.
+ *
+ * Measured 27/07 against shadcn/ui, 3846 files: 48 tokens found, 1383 values
+ * written by hand, and **zero** matched - because shadcn declares in oklch and
+ * the code hardcodes hex. Tailwind v4 emits oklch by default too, so the one
+ * thing this tool does that a linter cannot - say what your system already
+ * calls the value - silently returned nothing on the most common modern stack.
+ *
+ * This is not fuzzy matching, which the exact-match rule below rightly
+ * forbids. It is finishing the job `normalizeValue` already claims to do:
+ * every dialect lands on one key. Rounding to 8 bits is precisely what the
+ * browser does on an sRGB display, and out-of-gamut coordinates clamp the same
+ * way they would on screen.
+ */
+function oklchToBytes(l, c, hDeg) {
+    const h = (hDeg * Math.PI) / 180;
+    const a = c * Math.cos(h);
+    const b = c * Math.sin(h);
+    const l_ = (l + 0.3963377774 * a + 0.2158037573 * b) ** 3;
+    const m_ = (l - 0.1055613458 * a - 0.0638541728 * b) ** 3;
+    const s_ = (l - 0.0894841775 * a - 1.291485548 * b) ** 3;
+    return [
+        gamma(4.0767416621 * l_ - 3.3077115913 * m_ + 0.2309699292 * s_),
+        gamma(-1.2684380046 * l_ + 2.6097574011 * m_ - 0.3413193965 * s_),
+        gamma(-0.0041960863 * l_ - 0.7034186147 * m_ + 1.707614701 * s_),
+    ];
+}
+/** `hsl(222 47% 11%)`, the dialect shadcn used before it moved to oklch. */
+function hslToBytes(h, s, l) {
+    const k = (n) => (n + h / 30) % 12;
+    const a = s * Math.min(l, 1 - l);
+    const f = (n) => (l - a * Math.max(-1, Math.min(k(n) - 3, Math.min(9 - k(n), 1)))) * 255;
+    return [f(0), f(8), f(4)];
+}
+/** The numbers inside a colour function, in any of CSS's separator dialects. */
+function args(body) {
+    const parts = body.split(/[\s,/]+/).filter(Boolean);
+    if (parts.length < 3)
+        return null;
+    const nums = parts.slice(0, 3).map((p) => {
+        const n = Number.parseFloat(p);
+        return p.endsWith("%") ? n / 100 : n;
+    });
+    if (!nums.every(Number.isFinite))
+        return null;
+    const rawA = parts[3];
+    const alpha = rawA === undefined
+        ? 1
+        : rawA.endsWith("%")
+            ? Number.parseFloat(rawA) / 100
+            : Number.parseFloat(rawA);
+    return { nums, alpha: Number.isFinite(alpha) ? alpha : 1 };
+}
 /**
  * One key per colour, whatever dialect it was written in.
  *
@@ -41,6 +98,29 @@ export function normalizeValue(raw) {
     const long = /^#([0-9a-f]{6})([0-9a-f]{2})?$/.exec(v);
     if (long)
         return `#${long[1]}${long[2] ?? "ff"}`;
+    const ok = /^oklch\(([^)]+)\)$/.exec(v);
+    if (ok) {
+        const a = args(ok[1]);
+        // The hue is an angle, not a fraction: `131.684` must not be read as a
+        // percentage the way lightness is.
+        if (a) {
+            const hue = /%$/.test(ok[1].split(/[\s,/]+/).filter(Boolean)[2] ?? "")
+                ? a.nums[2] * 100
+                : a.nums[2];
+            const [r, g, b] = oklchToBytes(a.nums[0], a.nums[1], hue);
+            return `#${hex2(r)}${hex2(g)}${hex2(b)}${hex2(a.alpha * 255)}`;
+        }
+    }
+    const hsl = /^hsla?\(([^)]+)\)$/.exec(v);
+    if (hsl) {
+        const a = args(hsl[1]);
+        if (a) {
+            const raw = hsl[1].split(/[\s,/]+/).filter(Boolean);
+            const hue = Number.parseFloat(raw[0]);
+            const [r, g, b] = hslToBytes(((hue % 360) + 360) % 360, a.nums[1], a.nums[2]);
+            return `#${hex2(r)}${hex2(g)}${hex2(b)}${hex2(a.alpha * 255)}`;
+        }
+    }
     const rgb = /^rgba?\(([^)]+)\)$/.exec(v);
     if (rgb) {
         const parts = rgb[1].split(/[\s,/]+/).filter(Boolean);
@@ -86,8 +166,53 @@ export function parseTokens(css) {
     }
     return out;
 }
+/**
+ * Custom properties the project declares AT THE ROOT, whatever it calls them.
+ *
+ * This is what lets the tool answer the only question its sharpest reader has:
+ * not "do you use SynthesisUI" but "does my own code still obey my own
+ * system". Someone with `--acme-color-primary: #3b82f6` in `:root` and
+ * `#3b82f6` hardcoded in a banner has drift, and until now we told them no
+ * system was installed and counted their values as anonymous.
+ *
+ * SCOPE IS THE HEURISTIC, not a prefix allow-list. A design token is declared
+ * once at the root; a runtime variable is set per element. That single rule
+ * keeps `:root`, `html`, `:host` and Tailwind v4's `@theme` - all places an
+ * author writes their vocabulary - and drops Tailwind v3's `--tw-*` defaults
+ * (declared on `*, ::before, ::after`) and Radix's `--radix-*` (set on the
+ * component) without naming a single vendor.
+ *
+ * The flat brace regex is deliberate and handles one level of nesting for
+ * free: against `@media x { :root { ... } }` the outer selector fails to match
+ * because its body contains a brace, so the scan moves on and finds the inner
+ * block on its own.
+ */
+export function parseRootTokens(css) {
+    const out = new Map();
+    for (const block of css.matchAll(/([^{}]*)\{([^{}]*)\}/g)) {
+        const selector = block[1].trim();
+        const isRoot = /^@theme\b/i.test(selector) ||
+            /(^|[\s,>+~])(:root|html|:host)\b/i.test(selector);
+        if (!isRoot)
+            continue;
+        for (const m of block[2].matchAll(/(--[a-z0-9_-]+)\s*:\s*([^;}]+)/gi)) {
+            const name = m[1].toLowerCase();
+            // Belt and braces: v4 emits some `--tw-*` bookkeeping into @theme, and
+            // it is machinery, not somebody's design vocabulary.
+            if (name.startsWith("--tw-"))
+                continue;
+            const value = m[2].trim();
+            if (!value || value.startsWith("var("))
+                continue;
+            if (!out.has(name))
+                out.set(name, value);
+        }
+    }
+    return out;
+}
 export function buildTable(input) {
-    const byName = parseTokens(input.css);
+    const source = input.source ?? "installed";
+    const byName = source === "yours" ? parseRootTokens(input.css) : parseTokens(input.css);
     const byValue = new Map();
     for (const [name, value] of byName) {
         const key = normalizeValue(value);
@@ -98,6 +223,7 @@ export function buildTable(input) {
             byValue.set(key, [name]);
     }
     return {
+        source: byName.size > 0 ? source : null,
         name: input.lock?.name ?? null,
         slug: input.lock?.slug ?? null,
         version: input.lock?.version ?? null,

package/dist/index.js

@@ -52,6 +52,8 @@ Options:
   --instruction <s>  refit: extra guidance for the adaptation
   --dry              refit: adapt and print, but save nothing
   --force            clean: apply the changes (without it, dry run)
+                     upgrade: rewrite UPGRADE.md even with no version gap left
+  --from <n>         upgrade --force: which older snapshot to diff from
   --strict           doctor: exit 1 when drift is found in THIS repo (for CI)
   --strict-system    doctor: also exit 1 when the system itself is inconsistent
   --verbose          doctor: every finding, file by file (default is a summary)
@@ -267,7 +269,12 @@ async function main() {
                 process.exitCode = 1;
                 return;
             }
-            await upgrade(slug, { registry, dir });
+            await upgrade(slug, {
+                registry,
+                dir,
+                force: flags.force === true,
+                from: typeof flags.from === "string" ? Number(flags.from) : undefined,
+            });
             break;
         }
         case "use": {

package/package.json

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