@starklab/stark-mcp 0.1.0

package/src/adopt/tokenAliasResolver.js

@@ -0,0 +1,513 @@
+import { readFileSync, existsSync } from 'node:fs';
+import path from 'node:path';
+
+import fg from 'fast-glob';
+import postcss from 'postcss';
+
+import { stkRoot } from '../data.js';
+
+// "5 is governance, 20 is safety" — see ADOPTION_APP_PLAN.md §4/§5a and the
+// same pattern in moduleGraph.js's resolveOrigin/resolveOriginDeep.
+const WARN_DEPTH = 3;
+const MAX_DEPTH = 20;
+
+const DEFAULT_IGNORE = [
+  '**/node_modules/**',
+  '**/dist/**',
+  '**/build/**',
+  '**/.next/**',
+  '**/coverage/**',
+  '**/storybook-static/**',
+  '**/.storybook*/**',
+];
+
+// ---------------------------------------------------------------------------
+// Inventory + layer classification
+//
+// packages/stk/build/css/tokens.css is the flat, authoritative set of every
+// --stk-* custom property the design system ships (mirrors the approach
+// packages/stk/scripts/token-gov/token-scanner.js already trusts for the
+// same purpose). packages/stk/tokens/{base,semantic,components}/*.json are
+// the DTCG source files the CSS was compiled from — their directory of
+// origin is exactly the layer classification (primitive/semantic/component)
+// a "layer violation via alias" finding needs, so this flattens each dir's
+// nested $value leaves back into the CSS variable names Style Dictionary
+// would produce (path segments joined with "-", prefixed "--stk-").
+// ---------------------------------------------------------------------------
+
+function flattenDtcg(node, prefix, layer, out) {
+  if (node == null || typeof node !== 'object') return;
+  if ('$value' in node) {
+    out.set(`--stk-${prefix.join('-')}`, layer);
+    return;
+  }
+  for (const [key, child] of Object.entries(node)) {
+    if (key.startsWith('$')) continue;
+    flattenDtcg(child, [...prefix, key], layer, out);
+  }
+}
+
+function loadTokenLayers(stkPkgRoot) {
+  const layers = new Map(); // cssVarName -> 'primitive' | 'semantic' | 'component'
+  const dirs = [
+    ['base', 'primitive'],
+    ['semantic', 'semantic'],
+    ['components', 'component'],
+  ];
+  for (const [dir, layer] of dirs) {
+    const full = path.join(stkPkgRoot, 'tokens', dir);
+    if (!existsSync(full)) continue;
+    for (const file of fg.sync('**/*.json', { cwd: full, absolute: true })) {
+      let json;
+      try {
+        json = JSON.parse(readFileSync(file, 'utf-8'));
+      } catch {
+        continue;
+      }
+      flattenDtcg(json, [], layer, layers);
+    }
+  }
+  return layers;
+}
+
+export function loadTokenInventory(stkPkgRoot) {
+  const cssPath = path.join(stkPkgRoot, 'build', 'css', 'tokens.css');
+  if (!existsSync(cssPath)) {
+    throw new Error(`Token build not found at ${cssPath} — run "npm run build" in packages/stk first.`);
+  }
+  const src = readFileSync(cssPath, 'utf-8');
+  const inventory = new Set([...src.matchAll(/--stk-([\w-]+)\s*:/g)].map((m) => `--stk-${m[1]}`));
+  const layers = loadTokenLayers(stkPkgRoot);
+  return { inventory, layers };
+}
+
+// ---------------------------------------------------------------------------
+// var() parsing
+//
+// Handles nested var() (fallback chains) and multiple refs in one value
+// (e.g. `padding: var(--x) var(--y)`) without needing a full CSS-values
+// grammar — a hand-rolled paren-depth scan is enough for var()'s own syntax.
+// ---------------------------------------------------------------------------
+
+function topLevelCommaIndex(s) {
+  let depth = 0;
+  for (let i = 0; i < s.length; i++) {
+    if (s[i] === '(') depth++;
+    else if (s[i] === ')') depth--;
+    else if (s[i] === ',' && depth === 0) return i;
+  }
+  return -1;
+}
+
+export function extractVarRefs(value) {
+  const refs = [];
+  let i = 0;
+  while (i < value.length) {
+    const start = value.indexOf('var(', i);
+    if (start === -1) break;
+    let depth = 1;
+    let j = start + 4;
+    while (j < value.length && depth > 0) {
+      if (value[j] === '(') depth++;
+      else if (value[j] === ')') depth--;
+      j++;
+    }
+    const inner = value.slice(start + 4, j - 1);
+    const commaIdx = topLevelCommaIndex(inner);
+    const name = (commaIdx === -1 ? inner : inner.slice(0, commaIdx)).trim();
+    const fallback = commaIdx === -1 ? null : inner.slice(commaIdx + 1).trim();
+    if (/^--[\w-]+$/.test(name)) {
+      refs.push({ name, fallback, start, end: j });
+    }
+    i = j;
+  }
+  return refs;
+}
+
+function isRawFallback(fallback) {
+  return !!fallback && !fallback.trim().startsWith('var(');
+}
+
+// ---------------------------------------------------------------------------
+// Pass 1 — the consumer's own alias graph
+//
+// Scoped per-selector, not global: the same custom-property name can be
+// redefined differently under different selectors (:root conformant vs
+// .theme-promo drift), so resolution must never collapse scopes together
+// (ADOPTION_APP_PLAN.md §5a — "the lossy alternative" is picking a dominant
+// scope; this instead surfaces disagreement as partial-conformance).
+//
+// Known simplification: media-query context is not tracked, so a
+// selector guarded by @media is treated the same as an unguarded one with
+// the same selector text. Full conditional-scope modelling is a possible
+// future enhancement, not required to capture the plan's core example.
+// ---------------------------------------------------------------------------
+
+export function collectCssFiles(root, ignore) {
+  return fg
+    .sync(['**/*.css'], { cwd: root, absolute: true, ignore: [...DEFAULT_IGNORE, ...ignore] })
+    .sort();
+}
+
+export function buildPropertyGraph(cssFiles) {
+  // propName -> selector -> { value, file, line }
+  const graph = new Map();
+
+  for (const file of cssFiles) {
+    let src;
+    try {
+      src = readFileSync(file, 'utf-8');
+    } catch {
+      continue;
+    }
+    let root;
+    try {
+      root = postcss.parse(src, { from: file });
+    } catch {
+      continue;
+    }
+
+    root.walkRules((rule) => {
+      const selectors = rule.selectors ?? [rule.selector];
+      for (const selector of selectors) {
+        const normalizedSelector = selector.trim();
+        rule.walkDecls((decl) => {
+          if (!decl.prop.startsWith('--')) return;
+          // --stk-* declarations are the design system's OWN internal token
+          // definitions (e.g. a synced copy of tokens.css checked into a
+          // consumer's src/tokens/ dir), not a consumer-authored alias — Pass
+          // 1 models "the consumer's own alias graph" (§5a), so these must
+          // never enter it. Without this, scanning a copy of Stark's own
+          // compiled CSS flags its legitimate internal semantic→primitive
+          // aliasing as consumer "layer violations."
+          if (decl.prop.startsWith('--stk-')) return;
+          let bySelector = graph.get(decl.prop);
+          if (!bySelector) {
+            bySelector = new Map();
+            graph.set(decl.prop, bySelector);
+          }
+          bySelector.set(normalizedSelector, {
+            value: decl.value,
+            file,
+            line: decl.source?.start?.line ?? null,
+          });
+        });
+      }
+    });
+  }
+
+  return graph;
+}
+
+function resolveValue(value, propGraph, selector, inventory, layers, visited, depth, meta) {
+  const trimmed = value.trim();
+  const refs = extractVarRefs(trimmed);
+  const isPureVar = refs.length === 1 && trimmed === trimmed.slice(refs[0].start, refs[0].end);
+
+  if (!isPureVar) {
+    // Composite value (calc(), multiple refs, mixed literal + var(), or a
+    // plain literal) — not a 1:1 alias, so it can't be treated as
+    // identity-preserving even if it happens to reference an stk token
+    // somewhere inside (e.g. calc(var(--stk-spacing-md) * 2)).
+    const rawFallbackPresent = refs.some((r) => isRawFallback(r.fallback));
+    return { kind: 'raw', depth, rawFallbackPresent, ...meta };
+  }
+
+  const { name, fallback } = refs[0];
+
+  if (name.startsWith('--stk-')) {
+    if (inventory.has(name)) {
+      return { kind: 'stk', stkToken: name, layer: layers.get(name) ?? 'unknown', depth: depth + 1, rawFallbackPresent: isRawFallback(fallback), ...meta };
+    }
+    // Looks like an stk token name but isn't in the built inventory —
+    // most likely stale/renamed.
+    return { kind: 'undefined', depth: depth + 1, staleStkName: name, rawFallbackPresent: isRawFallback(fallback), ...meta };
+  }
+
+  const resolved = resolveTerminal(propGraph, name, selector, inventory, layers, visited, depth + 1);
+
+  if (resolved.kind === 'undefined' && fallback) {
+    const fallbackResolved = resolveValue(fallback, propGraph, selector, inventory, layers, visited, depth, meta);
+    return { ...fallbackResolved, viaFallback: true, rawFallbackPresent: fallbackResolved.kind !== 'stk' };
+  }
+
+  return { ...resolved, rawFallbackPresent: resolved.rawFallbackPresent || isRawFallback(fallback) };
+}
+
+export function resolveTerminal(propGraph, propName, selector, inventory, layers, visited = new Set(), depth = 0) {
+  const key = `${selector}::${propName}`;
+  if (visited.has(key)) {
+    return { kind: 'cycle', depth, rawFallbackPresent: false };
+  }
+  if (depth > MAX_DEPTH) {
+    return { kind: 'depth-limit', depth, rawFallbackPresent: false };
+  }
+
+  const bySelector = propGraph.get(propName);
+  const boundSelector = bySelector?.has(selector) ? selector : bySelector?.has(':root') ? ':root' : null;
+  if (!boundSelector) {
+    return { kind: 'undefined', depth, rawFallbackPresent: false };
+  }
+
+  const decl = bySelector.get(boundSelector);
+  const nextVisited = new Set(visited).add(key);
+
+  return resolveValue(decl.value, propGraph, selector, inventory, layers, nextVisited, depth, {
+    file: decl.file,
+    line: decl.line,
+    boundSelector,
+  });
+}
+
+export function classifyTerminalState(kind) {
+  if (kind === 'stk') return 'conformant';
+  if (kind === 'raw') return 'drift';
+  return 'broken'; // undefined | cycle | depth-limit
+}
+
+function classifyProperties(propGraph, inventory, layers) {
+  const properties = [];
+  const findings = [];
+
+  for (const [propName, bySelector] of propGraph) {
+    const scopeResults = [];
+    for (const [selector, decl] of bySelector) {
+      const terminal = resolveTerminal(propGraph, propName, selector, inventory, layers, new Set(), 0);
+      const state = classifyTerminalState(terminal.kind);
+      scopeResults.push({ selector, file: decl.file, line: decl.line, state, terminal });
+    }
+
+    const states = new Set(scopeResults.map((s) => s.state));
+    const overall = states.size === 1 ? [...states][0] : 'partial-conformance';
+
+    for (const s of scopeResults) {
+      if (s.terminal.kind === 'stk' && s.terminal.layer === 'primitive') {
+        findings.push({
+          rule: 'layer-violation',
+          severity: 'critical',
+          property: propName,
+          selector: s.selector,
+          file: s.file,
+          line: s.line,
+          stkToken: s.terminal.stkToken,
+        });
+      }
+      if (s.terminal.kind === 'stk' && s.terminal.depth > WARN_DEPTH) {
+        findings.push({
+          rule: 'deep-alias-chain',
+          severity: 'warning',
+          property: propName,
+          selector: s.selector,
+          depth: s.terminal.depth,
+        });
+      }
+      if (s.state === 'drift') {
+        findings.push({
+          rule: 'drift-behind-alias',
+          severity: 'critical',
+          property: propName,
+          selector: s.selector,
+          file: s.file,
+          line: s.line,
+        });
+      }
+      if (s.state === 'broken') {
+        findings.push({
+          rule: 'broken-alias',
+          severity: 'critical',
+          property: propName,
+          selector: s.selector,
+          reason: s.terminal.kind,
+          file: s.file,
+          line: s.line,
+        });
+      }
+      if (s.terminal.rawFallbackPresent) {
+        // Works today, silently becomes a hardcoded value the day the
+        // aliased property is renamed — a latent-risk signal, never Critical.
+        findings.push({
+          rule: 'raw-fallback',
+          severity: 'info',
+          property: propName,
+          selector: s.selector,
+          file: s.file,
+          line: s.line,
+        });
+      }
+    }
+
+    if (overall === 'partial-conformance') {
+      // Nullable severity: this is an observed state, not a graded
+      // judgement — see ADOPTION_APP_PLAN.md §5a.
+      findings.push({
+        rule: 'partial-conformance',
+        severity: null,
+        property: propName,
+        scopes: scopeResults.map((s) => ({ selector: s.selector, state: s.state })),
+      });
+    }
+
+    properties.push({ name: propName, scopes: scopeResults, state: overall });
+  }
+
+  return { properties, findings };
+}
+
+// ---------------------------------------------------------------------------
+// Pass 2 — usage classification
+//
+// Every var(...) occurrence in every declaration value (not just
+// custom-property declarations) is classified against its resolved
+// terminal, not its literal name.
+// ---------------------------------------------------------------------------
+
+function bindUsageScope(bySelector, selector) {
+  if (!bySelector) return null;
+  // Exact-selector match is a confident bind. Otherwise, only fall back
+  // when there is a single declared scope for this property anywhere —
+  // no competing definition to disambiguate against. When multiple scopes
+  // disagree, defaulting to :root would be the "lossy" choice the plan
+  // warns against (we have no DOM tree here to know whether this usage
+  // site's real rendered element sits inside the more specific scope or
+  // not), so it stays unresolved instead.
+  if (bySelector.has(selector)) return selector;
+  if (bySelector.size === 1) return [...bySelector.keys()][0];
+  return null;
+}
+
+function collectUsages(cssFiles, propGraph, inventory, layers) {
+  const usages = [];
+
+  for (const file of cssFiles) {
+    let src;
+    try {
+      src = readFileSync(file, 'utf-8');
+    } catch {
+      continue;
+    }
+    let root;
+    try {
+      root = postcss.parse(src, { from: file });
+    } catch {
+      continue;
+    }
+
+    root.walkRules((rule) => {
+      const selectors = rule.selectors ?? [rule.selector];
+      for (const selector of selectors) {
+        const normalizedSelector = selector.trim();
+        rule.walkDecls((decl) => {
+          // Custom-property declarations are Pass 1's alias-graph edges, not
+          // Pass 2 usage/consumption sites — scanning them here too would
+          // double-count every conformant alias as a phantom "direct" usage
+          // of whatever it ultimately points at.
+          if (decl.prop.startsWith('--')) return;
+          const refs = extractVarRefs(decl.value);
+          for (const ref of refs) {
+            const site = {
+              file,
+              line: decl.source?.start?.line ?? null,
+              selector: normalizedSelector,
+              property: decl.prop,
+              refName: ref.name,
+            };
+
+            if (ref.name.startsWith('--stk-')) {
+              usages.push({
+                ...site,
+                classification: inventory.has(ref.name) ? 'direct' : 'broken',
+                stkToken: ref.name,
+              });
+              continue;
+            }
+
+            const bySelector = propGraph.get(ref.name);
+            if (!bySelector) {
+              usages.push({ ...site, classification: 'broken', reason: 'undefined-property' });
+              continue;
+            }
+
+            const boundSelector = bindUsageScope(bySelector, normalizedSelector);
+            if (!boundSelector) {
+              usages.push({ ...site, classification: 'unresolved', reason: 'ambiguous-scope' });
+              continue;
+            }
+
+            const terminal = resolveTerminal(propGraph, ref.name, boundSelector, inventory, layers, new Set(), 0);
+            const state = classifyTerminalState(terminal.kind);
+            const classification = state === 'conformant' ? 'aliased' : state;
+            usages.push({
+              ...site,
+              classification,
+              boundSelector,
+              depth: terminal.depth,
+              stkToken: terminal.stkToken,
+            });
+          }
+        });
+      }
+    });
+  }
+
+  return usages;
+}
+
+// Per the plan's "report three numbers, never one": direct + aliased is the
+// scored conformance number; everything that fails to resolve to an stk
+// token for any reason (hardcoded/drift, broken, or genuinely unresolvable
+// scope) buckets into "unresolved" for this headline view. The finer-grained
+// per-usage classification (drift vs broken vs unresolved) is preserved in
+// `usages` for findings/tooling that need it.
+function summarizeReport(usages) {
+  const counts = { direct: 0, aliased: 0, unresolved: 0 };
+  for (const u of usages) {
+    if (u.classification === 'direct') counts.direct++;
+    else if (u.classification === 'aliased') counts.aliased++;
+    else counts.unresolved++;
+  }
+  const total = counts.direct + counts.aliased + counts.unresolved;
+  const pct = (n) => (total === 0 ? 0 : Math.round((n / total) * 1000) / 10);
+  return {
+    total,
+    direct: counts.direct,
+    directPct: pct(counts.direct),
+    aliased: counts.aliased,
+    aliasedPct: pct(counts.aliased),
+    unresolved: counts.unresolved,
+    unresolvedPct: pct(counts.unresolved),
+    conformancePct: pct(counts.direct + counts.aliased),
+  };
+}
+
+/**
+ * Resolves a consumer's CSS custom-property alias graph transitively so an
+ * aliased --stk-* token is recognized as adopted, not counted as absent
+ * (ADOPTION_APP_PLAN.md §5a). Web-only: CSS var() has no React Native
+ * equivalent (RN indirection is JS-object based) — that's a separate,
+ * later resolver.
+ */
+export function resolveTokenAliases(root, { platform = 'web', ignore = [] } = {}) {
+  if (platform !== 'web') {
+    throw new Error(`resolveTokenAliases only supports platform "web" (got "${platform}") — CSS custom properties have no RN equivalent.`);
+  }
+
+  const stkPkgRoot = stkRoot();
+  const { inventory, layers } = loadTokenInventory(stkPkgRoot);
+  const cssFiles = collectCssFiles(root, ignore);
+  const propGraph = buildPropertyGraph(cssFiles);
+  const { properties, findings } = classifyProperties(propGraph, inventory, layers);
+  const usages = collectUsages(cssFiles, propGraph, inventory, layers);
+  const report = summarizeReport(usages);
+
+  return {
+    platform,
+    root,
+    scannedFiles: cssFiles.length,
+    tokenInventoryTotal: inventory.size,
+    aliasCount: propGraph.size, // distinct consumer-declared custom properties — a roadmap signal, not a violation
+    properties,
+    usages,
+    findings,
+    report,
+  };
+}