synthesisui 0.16.9 → 0.16.11

package/dist/commands/hook.js

@@ -0,0 +1,76 @@
+import { readFile } from "node:fs/promises";
+import { relative, resolve } from "node:path";
+import { diagnose, scanSource } from "../doctor/scan.js";
+import { loadSystem } from "./doctor.js";
+const pass = () => ({ continue: true });
+const speak = (context) => ({
+    continue: true,
+    hookSpecificOutput: {
+        hookEventName: "PostToolUse",
+        additionalContext: context,
+    },
+});
+/** Files where a design value can even appear. A hook that parses a README on
+ *  every edit is paying for nothing. */
+const UI_FILE = /\.(tsx|jsx|ts|js|css|scss|vue|svelte)$/i;
+async function report(root, filePath) {
+    const { table } = await loadSystem(root);
+    if (table.byName.size === 0)
+        return null;
+    const src = await readFile(filePath, "utf8").catch(() => "");
+    if (!src)
+        return null;
+    const rel = relative(root, filePath);
+    const d = diagnose([scanSource(rel, src, table)]);
+    const named = d.findings.filter((f) => f.token);
+    const phantoms = d.files.flatMap((f) => f.phantoms ?? []);
+    // Unnamed drift alone is deliberately NOT worth interrupting for. There is
+    // no token to move to, so the only honest advice is "ask a person" - and
+    // saying that after every edit trains the reader to skip the block.
+    if (named.length === 0 && phantoms.length === 0)
+        return null;
+    const lines = [`${rel} - checked against ${table.name ?? table.slug}.`];
+    if (named.length > 0) {
+        lines.push("", "Values written by hand that this system already has a name for:", ...named
+            .slice(0, 20)
+            .map((f) => `  line ${f.line}  ${f.literal} → ${f.token}`), "", "Replace them now, while you still have this file in mind.");
+    }
+    if (phantoms.length > 0) {
+        lines.push("", "Names this system does not declare. These look tokenized and apply nothing at all:", ...phantoms.slice(0, 20).map((p) => `  line ${p.line}  ${p.name}`), "", "Use a name the system has, or say which value you need and what you would call it. Do NOT invent a token.");
+    }
+    return lines.join("\n");
+}
+export async function hook(opts) {
+    const root = resolve(opts.dir ?? process.cwd());
+    let raw = "";
+    for await (const chunk of process.stdin)
+        raw += chunk;
+    let input;
+    try {
+        input = JSON.parse(raw);
+    }
+    catch {
+        // Anything we cannot read must let the edit through untouched. A hook that
+        // fails loudly on a payload change is worse than no hook.
+        process.stdout.write(`${JSON.stringify(pass())}\n`);
+        return;
+    }
+    const writes = input.tool_name === "Write" ||
+        input.tool_name === "Edit" ||
+        input.tool_name === "MultiEdit";
+    const file = input.tool_input?.file_path;
+    if (input.hook_event_name !== "PostToolUse" || !writes || !file) {
+        process.stdout.write(`${JSON.stringify(pass())}\n`);
+        return;
+    }
+    const abs = resolve(root, file);
+    // Our own installed artifacts are the answer, not the problem - and a file
+    // outside the project is none of our business.
+    const inside = !relative(root, abs).startsWith("..");
+    if (!UI_FILE.test(abs) || !inside || abs.includes("_synthesisui")) {
+        process.stdout.write(`${JSON.stringify(pass())}\n`);
+        return;
+    }
+    const body = await report(root, abs).catch(() => null);
+    process.stdout.write(`${JSON.stringify(body ? speak(body) : pass())}\n`);
+}

package/dist/doctor/tokens.js

@@ -180,6 +180,57 @@ export function parseTokens(css) {
  * Harmless while nothing asked about existence. The moment the phantom check
  * did, it called them invented (caught before shipping, 27/07).
  */
+/**
+ * AN ALIAS IS NOT A DEAD END. IT IS USUALLY THE ANSWER.
+ *
+ * Every real system is written in two layers - `--ds-color-blue-600: #2563eb`
+ * on the shelf, `--ds-color-semantic-info: var(--ds-color-blue-600)` for the
+ * intent - and the value table only ever held the first. So `tokenFor` answered
+ * `#2563eb → --ds-color-blue-600`, the shelf, and its own rule two lines below
+ * ("semantic roles name intent; prefer intent") could never fire, because no
+ * semantic name was in the table to prefer.
+ *
+ * That is the one sentence the product is sold on: not "you have a hardcoded
+ * colour" but "your system already calls it this". It was naming the wrong
+ * thing on every system that layers its tokens, which is all of them. Found
+ * when an agent using the MCP tools read the answer, checked it against
+ * CLAUDE.md, and corrected the tool (my-test4, 27/07).
+ *
+ * Following the chain costs one pass and needs no CSS engine: a token either
+ * holds a literal or points at exactly one other token.
+ */
+export function resolveAliases(raw) {
+    const out = new Map();
+    const literal = (name, depth) => {
+        // A cycle is malformed CSS, not something to crash on. Ten hops is far
+        // past any real system and stops the recursion dead.
+        if (depth > 10)
+            return null;
+        const value = raw.get(name);
+        if (value === undefined)
+            return null;
+        const alias = /^var\(\s*(--[a-z0-9_-]+)/i.exec(value.trim());
+        return alias ? literal(alias[1].toLowerCase(), depth + 1) : value;
+    };
+    for (const name of raw.keys()) {
+        const value = literal(name, 0);
+        if (value !== null)
+            out.set(name, value);
+    }
+    return out;
+}
+/** Every `--ds-*` declaration, aliases kept - the input `resolveAliases` needs.
+ *  `parseTokens` drops them, which is right for a table of literals and wrong
+ *  for a table of what things are called. */
+export function parseTokensWithAliases(css) {
+    const out = new Map();
+    for (const m of css.matchAll(/(--ds-[a-z0-9-]+)\s*:\s*([^;}]+)[;}]/gi)) {
+        const name = m[1].toLowerCase();
+        if (!out.has(name))
+            out.set(name, m[2].trim());
+    }
+    return out;
+}
 export function parseDeclaredNames(css) {
     const out = new Set();
     for (const m of css.matchAll(/(--[a-z0-9_-]+)\s*:\s*[^;}]+[;}]/gi))
@@ -280,14 +331,35 @@ export function buildTable(input) {
     const byName = source === "installed"
         ? parseTokens(input.css)
         : parseRootTokens(input.css);
+    /**
+     * Built from the RESOLVED map, not from `byName`. A semantic role that
+     * aliases a primitive has to be findable by the primitive's value, or the
+     * "prefer intent" rule below is unreachable.
+     */
+    const resolved = source === "installed"
+        ? resolveAliases(parseTokensWithAliases(input.css))
+        : byName;
+    /**
+     * Aliases first in every list.
+     *
+     * `tokenFor` preferred a name containing `-semantic-`, which covers colour
+     * and nothing else: `--ds-spacing-md: var(--ds-spacing-4)` has no such
+     * marker, so the answer came back as the raw step rather than the scale name
+     * anyone actually writes. The general rule is structural, not lexical - in a
+     * layered system the name that POINTS at another name is the layer above.
+     */
+    const raw = source === "installed" ? parseTokensWithAliases(input.css) : new Map();
+    const isAlias = (name) => /^var\(/.test((raw.get(name) ?? "").trim());
     const byValue = new Map();
-    for (const [name, value] of byName) {
+    for (const [name, value] of resolved) {
         const key = normalizeValue(value);
         const list = byValue.get(key);
-        if (list)
-            list.push(name);
-        else
+        if (!list)
             byValue.set(key, [name]);
+        else if (isAlias(name))
+            list.unshift(name);
+        else
+            list.push(name);
     }
     return {
         source: byName.size > 0 ? source : null,

package/dist/index.js

@@ -6,6 +6,7 @@ import { clean } from "./commands/clean.js";
 import { component } from "./commands/component.js";
 import { doctor } from "./commands/doctor.js";
 import { generate } from "./commands/generate.js";
+import { hook } from "./commands/hook.js";
 import { init } from "./commands/init.js";
 import { list } from "./commands/list.js";
 import { login } from "./commands/login.js";
@@ -134,6 +135,11 @@ async function main() {
                 slug: typeof flags.slug === "string" ? flags.slug : undefined,
             });
             break;
+        // Both of these read stdin and write a protocol frame to stdout, so
+        // nothing that prints may run near them.
+        case "hook":
+            await hook({ dir });
+            return;
         // Long-lived: it owns stdin/stdout until the client closes the pipe, so
         // it must not be reached by anything that prints.
         case "mcp":

package/package.json

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