@starklab/stark-mcp 0.1.0

package/src/adopt/rnTokenAliasResolver.js

@@ -0,0 +1,474 @@
+import { readFileSync, existsSync } from 'node:fs';
+import path from 'node:path';
+
+import fg from 'fast-glob';
+import traverseModule from '@babel/traverse';
+
+import { stkRoot } from '../data.js';
+import { buildModuleGraph, resolveOriginDeep } from './moduleGraph.js';
+
+const traverse = traverseModule.default ?? traverseModule;
+
+// "5 is governance, 20 is safety" — see ADOPTION_APP_PLAN.md §4/§5a and the
+// same pattern in moduleGraph.js's resolveOrigin/resolveOriginDeep and
+// tokenAliasResolver.js's own resolveTerminal.
+const WARN_DEPTH = 3;
+const MAX_DEPTH = 20;
+
+// The RN counterpart of CSS custom properties: no var(), so a Stark RN token
+// constant is always reached through one of these package subpaths
+// (packages/stk/package.json "exports"). Importing the bare web build
+// (`@starklab/stk`) on RN is out of scope — it has no Platform.select
+// values and isn't the documented RN entry point (see the port-to-rn skill).
+const RN_TOKEN_PACKAGES = new Set([
+  '@starklab/stk/rn',
+  '@starklab/stk/rn-spacing',
+  '@starklab/stk/rn-typography',
+  '@starklab/stk/rn-easing',
+  '@starklab/stk/rn-shadows',
+  '@starklab/stk/rn-dark',
+]);
+
+const RN_BUILD_FILES = [
+  'build/rn/tokens.rn.js',
+  'build/rn/tokens.dark.rn.js',
+  'build/rn/spacing.rn.js',
+  'build/rn/typography.rn.js',
+  'build/rn/easing.rn.js',
+  'build/rn/shadows.rn.js',
+];
+
+// ---------------------------------------------------------------------------
+// Inventory + layer classification
+//
+// Same DTCG source as tokenAliasResolver.js's loadTokenLayers, but flattened
+// to RN token names (packages/stk's own strip-"--stk-"/split-"-"/camelCase/
+// prefix-"stk" convention, documented in the port-to-rn skill) instead of CSS
+// custom-property names, so a layer-violation finding (aliasing a primitive
+// token) works the same way it does on web.
+// ---------------------------------------------------------------------------
+
+function cssVarToRnToken(cssVarName) {
+  const rest = cssVarName.replace(/^--stk-/, '');
+  const camel = rest
+    .split('-')
+    .filter(Boolean)
+    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+    .join('');
+  return `stk${camel}`;
+}
+
+function flattenDtcgRn(node, prefix, layer, out) {
+  if (node == null || typeof node !== 'object') return;
+  if ('$value' in node) {
+    out.set(cssVarToRnToken(`--stk-${prefix.join('-')}`), layer);
+    return;
+  }
+  for (const [key, child] of Object.entries(node)) {
+    if (key.startsWith('$')) continue;
+    flattenDtcgRn(child, [...prefix, key], layer, out);
+  }
+}
+
+function loadRnTokenLayers(stkPkgRoot) {
+  const layers = new Map();
+  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;
+      }
+      flattenDtcgRn(json, [], layer, layers);
+    }
+  }
+  return layers;
+}
+
+export function loadRnTokenInventory(stkPkgRoot) {
+  const inventory = new Set();
+  for (const rel of RN_BUILD_FILES) {
+    const full = path.join(stkPkgRoot, rel);
+    if (!existsSync(full)) continue;
+    const src = readFileSync(full, 'utf-8');
+    for (const m of src.matchAll(/export const (stk[A-Za-z0-9]+)\s*=/g)) {
+      inventory.add(m[1]);
+    }
+  }
+  if (inventory.size === 0) {
+    throw new Error(`RN token build not found under ${stkPkgRoot}/build/rn — run "npm run build" in packages/stk first.`);
+  }
+  const layers = loadRnTokenLayers(stkPkgRoot);
+  return { inventory, layers };
+}
+
+// ---------------------------------------------------------------------------
+// Pass 1 — the consumer's own JS-object alias graph
+//
+// The RN equivalent of tokenAliasResolver.js's propGraph: instead of
+// `--app-primary: var(--stk-…)`, the indirection is a local `const` whose
+// initializer is either a scalar alias (`const primary = stkSurfaceBrand1Strong`)
+// or an object literal whose properties alias tokens
+// (`const theme = { primary: stkSurfaceBrand1Strong }`). Each alias is keyed
+// per-file (JS module scope, unlike CSS custom properties which are
+// effectively global) — `localName` for a scalar const, `localName.propName`
+// for an object property.
+//
+// Known simplifications (documented, not oversights — this is the first RN
+// resolver and ADOPTION_APP_PLAN.md §5a explicitly argues for building it
+// only after the web one is validated, since there is no getComputedStyle()
+// oracle to reconcile against on RN):
+//   - Declarations are captured file-wide (any scope depth), not just
+//     module-top-level; if the same name is `const`-declared twice in one
+//     file (e.g. two components each with their own local `theme`), the
+//     later declaration wins. Real component files define one theme/style
+//     object per file, so this rarely matters in practice.
+//   - Only single-hop member access (`obj.prop`) is resolved — `a.b.c` is out
+//     of scope, mirroring tailwindResolver.js's non-theme-utility carve-out
+//     for what static analysis doesn't reach.
+//   - A property whose value isn't one of {Identifier, `obj.prop` member
+//     access, plain literal} (a call, a ternary, a spread, a nested object…)
+//     is not captured as an alias at all — never scored, same "dynamic
+//     expressions are skipped" rule tailwindResolver.js applies to
+//     clsx()/ternary className values.
+// ---------------------------------------------------------------------------
+
+function isPlainLiteral(node) {
+  if (node.type === 'StringLiteral' || node.type === 'NumericLiteral' || node.type === 'BooleanLiteral') return true;
+  if (node.type === 'TemplateLiteral' && node.expressions.length === 0) return true;
+  return false;
+}
+
+export function isAnalyzableValueNode(node) {
+  if (!node) return false;
+  if (node.type === 'Identifier') return true;
+  if (node.type === 'MemberExpression' && !node.computed && node.object.type === 'Identifier' && node.property.type === 'Identifier') return true;
+  return isPlainLiteral(node);
+}
+
+function setAlias(aliasGraph, file, key, node, line) {
+  let byFile = aliasGraph.get(file);
+  if (!byFile) {
+    byFile = new Map();
+    aliasGraph.set(file, byFile);
+  }
+  byFile.set(key, { node, line, file });
+}
+
+export function buildAliasGraph(moduleGraph) {
+  const aliasGraph = new Map(); // file -> Map(key -> {node, line, file})
+  const definitionNodes = new Set(); // value nodes that are alias-graph edges, not Pass-2 usage sites
+
+  for (const file of moduleGraph.files) {
+    const entry = moduleGraph.graph.get(file);
+    if (!entry?.ast) continue;
+
+    traverse(entry.ast, {
+      VariableDeclarator(nodePath) {
+        const { id, init } = nodePath.node;
+        if (!init || id.type !== 'Identifier') return;
+        const localName = id.name;
+
+        if (init.type === 'ObjectExpression') {
+          for (const prop of init.properties) {
+            if (prop.type !== 'ObjectProperty' || prop.computed) continue;
+            const propName =
+              prop.key.type === 'Identifier' ? prop.key.name : prop.key.type === 'StringLiteral' ? prop.key.value : null;
+            if (!propName || !isAnalyzableValueNode(prop.value)) continue;
+            setAlias(aliasGraph, file, `${localName}.${propName}`, prop.value, prop.loc?.start?.line ?? null);
+            definitionNodes.add(prop.value);
+          }
+          return;
+        }
+
+        if (!isAnalyzableValueNode(init)) return;
+        setAlias(aliasGraph, file, localName, init, nodePath.node.loc?.start?.line ?? null);
+        definitionNodes.add(init);
+      },
+    });
+  }
+
+  return { aliasGraph, definitionNodes };
+}
+
+export function classifyTerminalState(kind) {
+  if (kind === 'stk') return 'conformant';
+  if (kind === 'raw') return 'drift';
+  return 'broken'; // undefined | cycle | depth-limit | unsupported
+}
+
+function classifyOrigin(origin, propName, ctx, visited, depth) {
+  if (!origin) return { kind: 'undefined', depth };
+  if (origin.cycle) return { kind: 'cycle', depth };
+
+  if (origin.type === 'package') {
+    if (!RN_TOKEN_PACKAGES.has(origin.pkg)) return { kind: 'undefined', depth };
+    const tokenName = origin.name === '*' ? propName : origin.name;
+    if (!tokenName || !ctx.inventory.has(tokenName)) return { kind: 'undefined', depth };
+    return { kind: 'stk', depth: depth + 1, stkToken: tokenName, layer: ctx.layers.get(tokenName) ?? 'unknown' };
+  }
+
+  if (origin.type === 'local') {
+    const key = propName ? `${origin.name}.${propName}` : origin.name;
+    if (ctx.aliasGraph.get(origin.file)?.has(key)) {
+      return resolveAliasKey(origin.file, key, ctx, visited, depth + 1);
+    }
+    return { kind: 'undefined', depth };
+  }
+
+  return { kind: 'undefined', depth };
+}
+
+function resolveAliasKey(file, key, ctx, visited, depth) {
+  const visitKey = `${file}::${key}`;
+  if (visited.has(visitKey)) return { kind: 'cycle', depth };
+  const entry = ctx.aliasGraph.get(file)?.get(key);
+  if (!entry) return { kind: 'undefined', depth };
+  const nextVisited = new Set(visited).add(visitKey);
+  return classifyNode(file, entry.node, ctx, nextVisited, depth + 1);
+}
+
+function classifyIdentifierRef(file, name, ctx, visited, depth) {
+  if (ctx.aliasGraph.get(file)?.has(name)) {
+    return resolveAliasKey(file, name, ctx, visited, depth);
+  }
+  const origin = resolveOriginDeep(ctx.moduleGraph, file, name);
+  return classifyOrigin(origin, null, ctx, visited, depth);
+}
+
+function classifyMemberRef(file, objName, propName, ctx, visited, depth) {
+  const compoundKey = `${objName}.${propName}`;
+  if (ctx.aliasGraph.get(file)?.has(compoundKey)) {
+    return resolveAliasKey(file, compoundKey, ctx, visited, depth);
+  }
+  const origin = resolveOriginDeep(ctx.moduleGraph, file, objName);
+  return classifyOrigin(origin, propName, ctx, visited, depth);
+}
+
+export function classifyNode(file, node, ctx, visited, depth) {
+  if (depth > MAX_DEPTH) return { kind: 'depth-limit', depth };
+  if (node.type === 'Identifier') return classifyIdentifierRef(file, node.name, ctx, visited, depth);
+  if (node.type === 'MemberExpression' && !node.computed && node.object.type === 'Identifier' && node.property.type === 'Identifier') {
+    return classifyMemberRef(file, node.object.name, node.property.name, ctx, visited, depth);
+  }
+  if (isPlainLiteral(node)) return { kind: 'raw', depth };
+  return { kind: 'unsupported', depth };
+}
+
+function classifyAliasGraph(aliasGraph, ctx) {
+  const properties = [];
+  const findings = [];
+
+  for (const [file, byKey] of aliasGraph) {
+    for (const [key, entry] of byKey) {
+      const terminal = classifyNode(file, entry.node, ctx, new Set(), 0);
+      const state = classifyTerminalState(terminal.kind);
+
+      if (terminal.kind === 'stk' && terminal.layer === 'primitive') {
+        findings.push({ rule: 'layer-violation', severity: 'critical', property: key, file, line: entry.line, stkToken: terminal.stkToken });
+      }
+      if (terminal.kind === 'stk' && terminal.depth > WARN_DEPTH) {
+        findings.push({ rule: 'deep-alias-chain', severity: 'warning', property: key, file, line: entry.line, depth: terminal.depth });
+      }
+      if (state === 'drift') {
+        findings.push({ rule: 'drift-behind-alias', severity: 'critical', property: key, file, line: entry.line });
+      }
+      if (state === 'broken') {
+        findings.push({ rule: 'broken-alias', severity: 'critical', property: key, file, line: entry.line, reason: terminal.kind });
+      }
+
+      properties.push({ name: key, file, line: entry.line, state, terminal });
+    }
+  }
+
+  return { properties, findings };
+}
+
+// ---------------------------------------------------------------------------
+// Pass 2 — usage classification
+//
+// A usage is `obj.prop` or a bare `name` reference outside of the Pass-1
+// definition sites themselves. Three ways a usage resolves:
+//   'direct'  — the reference reaches a Stark RN token constant with no
+//               consumer indirection at all (a namespace-import property
+//               access, a directly-imported token identifier, or — the
+//               `useTokens()` case — an object whose origin isn't statically
+//               traceable but whose property name is an unambiguous "stk"-
+//               prefixed inventory token; this matches the reference's
+//               static *name*, never a resolved *value*, which is the
+//               distinction ADOPTION_APP_PLAN.md §5a's anti-pattern warning
+//               draws — "colour values collide constantly, a metric built on
+//               coincidence is worse than a missing metric").
+//   'aliased' — the reference resolves through a Pass-1 alias-graph entry to
+//               a conformant stk terminal.
+//   (skipped) — anything else (an unrelated object/property pair, e.g.
+//               `props.variant` or `StyleSheet.create`) is out of scope, not
+//               a violation — same "not every property is ours to judge"
+//               rule tailwindResolver.js applies to Tailwind's own default
+//               palette classes.
+// ---------------------------------------------------------------------------
+
+function pushResolvedUsage(usages, { file, line, ref, terminal }) {
+  const state = classifyTerminalState(terminal.kind);
+  const classification = state === 'conformant' ? 'aliased' : state;
+  usages.push({ file, line, ref, classification, stkToken: terminal.stkToken, depth: terminal.depth });
+}
+
+function collectUsages(moduleGraph, definitionNodes, ctx) {
+  const usages = [];
+
+  for (const file of moduleGraph.files) {
+    const entry = moduleGraph.graph.get(file);
+    if (!entry?.ast) continue;
+
+    traverse(entry.ast, {
+      MemberExpression(nodePath) {
+        const node = nodePath.node;
+        if (definitionNodes.has(node)) return; // Pass-1 alias-graph edge, not a usage site
+        if (node.computed) return;
+        if (node.object.type !== 'Identifier' || node.property.type !== 'Identifier') return;
+
+        const objName = node.object.name;
+        const propName = node.property.name;
+        const line = node.loc?.start?.line ?? null;
+        const compoundKey = `${objName}.${propName}`;
+
+        if (ctx.aliasGraph.get(file)?.has(compoundKey)) {
+          pushResolvedUsage(usages, { file, line, ref: compoundKey, terminal: resolveAliasKey(file, compoundKey, ctx, new Set(), 0) });
+          return;
+        }
+
+        const origin = resolveOriginDeep(ctx.moduleGraph, file, objName);
+        if (origin?.type === 'package' && origin.name === '*' && RN_TOKEN_PACKAGES.has(origin.pkg) && ctx.inventory.has(propName)) {
+          usages.push({ file, line, ref: compoundKey, classification: 'direct', stkToken: propName });
+          return;
+        }
+        if (origin?.type === 'local') {
+          const key = `${origin.name}.${propName}`;
+          if (ctx.aliasGraph.get(origin.file)?.has(key)) {
+            pushResolvedUsage(usages, { file, line, ref: compoundKey, terminal: resolveAliasKey(origin.file, key, ctx, new Set(), 0) });
+            return;
+          }
+        }
+
+        if (propName.startsWith('stk') && ctx.inventory.has(propName)) {
+          usages.push({ file, line, ref: compoundKey, classification: 'direct', stkToken: propName, heuristic: true });
+        }
+      },
+
+      Identifier(nodePath) {
+        if (!nodePath.isReferencedIdentifier()) return;
+        const node = nodePath.node;
+        if (definitionNodes.has(node)) return;
+        const name = node.name;
+        const line = node.loc?.start?.line ?? null;
+
+        if (ctx.aliasGraph.get(file)?.has(name)) {
+          pushResolvedUsage(usages, { file, line, ref: name, terminal: resolveAliasKey(file, name, ctx, new Set(), 0) });
+          return;
+        }
+
+        const origin = resolveOriginDeep(ctx.moduleGraph, file, name);
+        if (origin?.type === 'package' && origin.name !== '*' && RN_TOKEN_PACKAGES.has(origin.pkg) && ctx.inventory.has(origin.name)) {
+          usages.push({ file, line, ref: name, classification: 'direct', stkToken: origin.name });
+        }
+      },
+    });
+  }
+
+  return usages;
+}
+
+// Same three-number report as tokenAliasResolver.js/tailwindResolver.js.
+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 own JS-object token indirection on React Native —
+ * the RN analog of tokenAliasResolver.js's CSS custom-property alias graph
+ * (ADOPTION_APP_PLAN.md §5a: "no CSS custom properties, so the indirection is
+ * a JS object… same graph, resolved over imports and property access instead
+ * of var()"). Native-only: CSS var()/Tailwind utility classes have no RN
+ * equivalent — those are the two web-only resolvers.
+ *
+ * Static-only by construction (§5a/§3d): there is no getComputedStyle()-style
+ * runtime oracle on RN to reconcile against, so `confidence: 'uncertain'`
+ * always accompanies a `detected: true` result — never treat this result as
+ * equal-confidence with the web resolver's CSS-based ground truth.
+ */
+export function resolveRnTokenAliases(root, { platform = 'native', ignore = [] } = {}) {
+  if (platform !== 'native') {
+    throw new Error(
+      `resolveRnTokenAliases only supports platform "native" (got "${platform}") — CSS custom properties and Tailwind utility classes are the web analog, see tokenAliasResolver.js/tailwindResolver.js.`
+    );
+  }
+
+  const stkPkgRoot = stkRoot();
+  const { inventory, layers } = loadRnTokenInventory(stkPkgRoot);
+  const moduleGraph = buildModuleGraph(root, { ignore });
+
+  const anyStkImport = [...moduleGraph.graph.values()].some((entry) =>
+    [...entry.imports.values()].some((b) => RN_TOKEN_PACKAGES.has(b.source))
+  );
+  if (!anyStkImport) {
+    // Detection is always cheaper than resolution: no import from any Stark
+    // RN token package anywhere means there's nothing to measure, not a 0%
+    // score — same refusal tailwindResolver.js makes for "no config found".
+    return {
+      platform,
+      root,
+      detected: false,
+      reason:
+        'No import from a @starklab/stk RN token package (rn, rn-spacing, rn-typography, rn-easing, rn-shadows, rn-dark) found anywhere in the scanned files.',
+      report: null,
+    };
+  }
+
+  const { aliasGraph, definitionNodes } = buildAliasGraph(moduleGraph);
+  const ctx = { aliasGraph, moduleGraph, inventory, layers };
+  const { properties, findings } = classifyAliasGraph(aliasGraph, ctx);
+  const usages = collectUsages(moduleGraph, definitionNodes, ctx);
+  const report = summarizeReport(usages);
+
+  return {
+    platform,
+    root,
+    detected: true,
+    scannedFiles: moduleGraph.files.length,
+    tokenInventoryTotal: inventory.size,
+    aliasCount: [...aliasGraph.values()].reduce((n, byKey) => n + byKey.size, 0),
+    properties,
+    usages,
+    findings,
+    report,
+    confidence: 'uncertain',
+    confidenceReason:
+      'Static-only (ADOPTION_APP_PLAN.md §5a): no getComputedStyle()-equivalent runtime oracle exists on React Native to reconcile against, so this result has to be right by construction rather than cross-checked.',
+  };
+}