synthesisui 0.16.9 → 0.16.10

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

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