@starklab/stark-mcp 0.1.0

package/src/adopt/moduleGraph.js

@@ -0,0 +1,232 @@
+import { readFileSync, existsSync, statSync } from 'node:fs';
+import path from 'node:path';
+
+import fg from 'fast-glob';
+
+import { parseSource } from './parseSource.js';
+
+const DEFAULT_IGNORE = [
+  '**/node_modules/**',
+  '**/dist/**',
+  '**/build/**',
+  '**/.next/**',
+  '**/coverage/**',
+  '**/storybook-static/**',
+  '**/.storybook*/**',
+  '**/*.stories.*',
+  '**/*.test.*',
+  '**/*.spec.*',
+];
+
+export const EXTENSIONS = ['.tsx', '.ts', '.jsx', '.js', '.mjs', '.cjs'];
+
+export function resolveRelative(fromFile, specifier) {
+  const base = path.resolve(path.dirname(fromFile), specifier);
+  const candidates = [
+    base,
+    ...EXTENSIONS.map((ext) => base + ext),
+    ...EXTENSIONS.map((ext) => path.join(base, 'index' + ext)),
+  ];
+  for (const candidate of candidates) {
+    if (existsSync(candidate) && statSync(candidate).isFile()) return candidate;
+  }
+  return null;
+}
+
+/**
+ * Parses every source file under `root` once and extracts each file's import
+ * bindings and re-export edges. This is the graph the reference resolver
+ * walks to trace a local binding — however many hops of the consumer's own
+ * barrels away — back to its ultimate origin package (ADOPTION_APP_PLAN.md
+ * §4 blind spot 2: "resolve barrel re-exports transitively so a consumer's
+ * own src/ui/index.ts doesn't hide everything behind it").
+ *
+ * Known limitation: `export * from '...'` edges are recorded (exportAll) but
+ * not chased during resolution — this repo's own barrels use flat named
+ * re-exports exclusively (see reconcile-catalog.js's readBarrel, which makes
+ * the same assumption), so it's consistent with the convention being
+ * measured, not a shortcut around it.
+ */
+export function buildModuleGraph(root, { ignore = [] } = {}) {
+  const files = fg.sync(['**/*.{js,jsx,ts,tsx,mjs,cjs}'], {
+    cwd: root,
+    absolute: true,
+    ignore: [...DEFAULT_IGNORE, ...ignore],
+  });
+
+  const graph = new Map();
+
+  for (const file of files) {
+    let code;
+    try {
+      code = readFileSync(file, 'utf-8');
+    } catch {
+      continue;
+    }
+
+    let ast;
+    try {
+      ast = parseSource(code, file);
+    } catch {
+      graph.set(file, {
+        ast: null,
+        code,
+        imports: new Map(),
+        reexports: new Map(),
+        exportAll: [],
+        parseError: true,
+      });
+      continue;
+    }
+
+    const imports = new Map();
+    const reexports = new Map();
+    const exportAll = [];
+
+    for (const node of ast.program.body) {
+      if (node.type === 'ImportDeclaration') {
+        const source = node.source.value;
+        for (const spec of node.specifiers) {
+          if (spec.type === 'ImportDefaultSpecifier') {
+            imports.set(spec.local.name, { source, imported: 'default' });
+          } else if (spec.type === 'ImportNamespaceSpecifier') {
+            imports.set(spec.local.name, { source, imported: '*' });
+          } else if (spec.type === 'ImportSpecifier') {
+            const importedName = spec.imported.type === 'Identifier' ? spec.imported.name : spec.imported.value;
+            imports.set(spec.local.name, { source, imported: importedName });
+          }
+        }
+      } else if (node.type === 'ExportNamedDeclaration') {
+        if (node.source) {
+          for (const spec of node.specifiers) {
+            const localName = spec.local.name;
+            const exportedName = spec.exported.type === 'Identifier' ? spec.exported.name : spec.exported.value;
+            reexports.set(exportedName, { source: node.source.value, imported: localName });
+          }
+        } else if (node.specifiers?.length) {
+          // export { X, Y as Z }; — forwarding a local binding. Only meaningful
+          // as a reexport edge when the local name is itself an import binding
+          // (forwarding a locally-*defined* wrapper is blind spot 3's concern).
+          for (const spec of node.specifiers) {
+            const localName = spec.local.name;
+            const exportedName = spec.exported.type === 'Identifier' ? spec.exported.name : spec.exported.value;
+            if (imports.has(localName)) {
+              reexports.set(exportedName, imports.get(localName));
+            }
+          }
+        }
+      } else if (node.type === 'ExportAllDeclaration') {
+        exportAll.push(node.source.value);
+      }
+    }
+
+    graph.set(file, { ast, code, imports, reexports, exportAll, parseError: false });
+  }
+
+  return { root, files, graph };
+}
+
+/**
+ * Resolves `name` back to its ultimate origin, following relative-import and
+ * re-export hops within the target repo only (never into node_modules).
+ *
+ *   viaExport=false — `name` is a local variable in `file`'s own code; look
+ *     it up in that file's *imports* (what does `file` bind `name` to?).
+ *   viaExport=true  — `name` is an exported symbol of `file`; look it up in
+ *     that file's *reexports* (what does `file` re-export as `name`?). These
+ *     are deliberately kept separate: falling back to `imports` on a
+ *     viaExport lookup would let an unrelated same-named local import
+ *     masquerade as an export that doesn't actually exist.
+ *
+ * Returns:
+ *   { pkg, name }   — terminal is a bare package import (e.g. stk-components)
+ *   { cycle: [...] } — the chain revisits a file+name it already visited
+ *   null            — unresolved (third-party package, missing file, or no
+ *                     such binding)
+ */
+export function resolveOrigin(moduleGraph, file, name, opts = {}) {
+  const { visited = new Set(), depth = 0, viaExport = false } = opts;
+  const MAX_DEPTH = 20; // safety valve only — see ADOPTION_APP_PLAN.md §4 "5 is governance, 20 is safety"
+  const key = `${file}#${viaExport ? 'export' : 'local'}#${name}`;
+  if (visited.has(key)) return { cycle: [...visited, key] };
+  if (depth > MAX_DEPTH) return null;
+
+  const entry = moduleGraph.graph.get(file);
+  if (!entry) return null;
+
+  const binding = viaExport ? entry.reexports.get(name) : entry.imports.get(name);
+  if (!binding) return null;
+
+  const { source, imported } = binding;
+  const nextVisited = new Set(visited).add(key);
+
+  if (!source.startsWith('.') && !source.startsWith('/')) {
+    return { pkg: source, name: imported };
+  }
+
+  if (imported === '*') {
+    // Namespace import/re-export — X.Foo member access isn't walked by the
+    // reference resolver, so there's nothing further to resolve here.
+    return null;
+  }
+
+  const resolvedFile = resolveRelative(file, source);
+  if (!resolvedFile || !moduleGraph.graph.has(resolvedFile)) return null;
+
+  return resolveOrigin(moduleGraph, resolvedFile, imported, {
+    visited: nextVisited,
+    depth: depth + 1,
+    viaExport: true,
+  });
+}
+
+/**
+ * Like resolveOrigin, but never gives up at "no import/reexport edge for this
+ * name" — it reports that as a *local* terminal instead of null. That's the
+ * distinction blind spot 3 (wrapper resolution, ADOPTION_APP_PLAN.md §4) needs:
+ * resolveOrigin's null means "not a catalog-package usage, don't care what it
+ * is"; resolveOriginDeep's {type:'local', file, name} means "this name isn't
+ * imported from anywhere — it's declared right here," which is exactly what a
+ * consumer's own wrapper component looks like from an importer's point of view.
+ *
+ * Returns:
+ *   { type: 'package', pkg, name } — terminal is a bare package import
+ *   { type: 'local', file, name }  — terminal is a same-repo local declaration
+ *   { cycle: [...] }               — the chain revisits a file+name already visited
+ *   null                           — dead end (missing file, namespace import, unparseable)
+ */
+export function resolveOriginDeep(moduleGraph, file, name, opts = {}) {
+  const { visited = new Set(), depth = 0, viaExport = false } = opts;
+  const MAX_DEPTH = 20; // safety valve only — see ADOPTION_APP_PLAN.md §4 "5 is governance, 20 is safety"
+  const key = `${file}#${viaExport ? 'export' : 'local'}#${name}`;
+  if (visited.has(key)) return { cycle: [...visited, key] };
+  if (depth > MAX_DEPTH) return null;
+
+  const entry = moduleGraph.graph.get(file);
+  if (!entry) return null;
+
+  const binding = viaExport ? entry.reexports.get(name) : entry.imports.get(name);
+  if (!binding) {
+    return { type: 'local', file, name };
+  }
+
+  const { source, imported } = binding;
+  const nextVisited = new Set(visited).add(key);
+
+  if (!source.startsWith('.') && !source.startsWith('/')) {
+    return { type: 'package', pkg: source, name: imported };
+  }
+
+  if (imported === '*') {
+    return null;
+  }
+
+  const resolvedFile = resolveRelative(file, source);
+  if (!resolvedFile || !moduleGraph.graph.has(resolvedFile)) return null;
+
+  return resolveOriginDeep(moduleGraph, resolvedFile, imported, {
+    visited: nextVisited,
+    depth: depth + 1,
+    viaExport: true,
+  });
+}

package/src/adopt/parseSource.js

@@ -0,0 +1,25 @@
+import { parse } from '@babel/parser';
+
+// jsx + typescript together handle .tsx (and .jsx/.js files still parse fine
+// with typescript enabled — it only changes how ambiguous syntax like `<Foo>`
+// casts is read, and this codebase's consumers use `as` casts, not the old
+// angle-bracket form). errorRecovery lets one malformed file fall through to
+// the caller as a parseError rather than aborting the whole scan.
+const PLUGINS = [
+  'jsx',
+  'typescript',
+  'classProperties',
+  'objectRestSpread',
+  'optionalChaining',
+  'nullishCoalescingOperator',
+  'decorators-legacy',
+];
+
+export function parseSource(code, filePath) {
+  return parse(code, {
+    sourceType: 'module',
+    sourceFilename: filePath,
+    plugins: PLUGINS,
+    errorRecovery: true,
+  });
+}

package/src/adopt/propApiResolver.js

@@ -0,0 +1,278 @@
+import path from 'node:path';
+
+import traverseModule from '@babel/traverse';
+
+import { loadCatalog, packageNameForPlatform } from './catalog.js';
+import { buildModuleGraph, resolveOrigin } from './moduleGraph.js';
+import { getComponentProps } from '../data.js';
+
+const traverse = traverseModule.default ?? traverseModule;
+
+// className/style bypass the component's own token-driven styling contract
+// (ADOPTION_APP_PLAN.md §4 blind spot 4: "className/style passed to a
+// component whose contract says tokens only → drift"). Both are legitimate,
+// intentional React escape hatches — nearly every mapping file lists them in
+// `ignore` precisely because components accept them — so this is a drift
+// signal to track, not a certain-severity break, unlike an invalid enum
+// value or a missing required prop.
+const STYLE_ESCAPE_ATTRS = new Set(['className', 'style']);
+
+/**
+ * Reads a JSXAttribute's value as a statically-known literal, or reports
+ * that it can't be resolved. Mirrors the literal-vs-passthrough distinction
+ * wrapperResolver.js's analyzeFaithfulness already makes for hardcoded
+ * attributes — a dynamic expression (`variant={someVar}`, a ternary, a
+ * template literal, a call) is never scored as valid or invalid, only
+ * `unresolved` (ADOPTION_APP_PLAN.md §9 Phase 1b: "never scored as a
+ * violation, never scored as clean").
+ */
+function literalAttrValue(attr) {
+  if (attr.value === null) return { resolved: true, value: true }; // boolean shorthand: <Button showLabel />
+  if (attr.value.type === 'StringLiteral') return { resolved: true, value: attr.value.value };
+  if (attr.value.type === 'JSXExpressionContainer') {
+    const expr = attr.value.expression;
+    if (expr.type === 'StringLiteral' || expr.type === 'NumericLiteral' || expr.type === 'BooleanLiteral') {
+      return { resolved: true, value: expr.value };
+    }
+    if (expr.type === 'NullLiteral') return { resolved: true, value: null };
+    return { resolved: false };
+  }
+  return { resolved: false };
+}
+
+/**
+ * Checks one JSX call site's attribute list against one component's
+ * prop-mapping propMap/ignore. Pure and file-agnostic — takes already-loaded
+ * mapping data so it's independently unit-testable without real mapping
+ * files or a scanned consumer app on disk.
+ *
+ * Four checks, per ADOPTION_APP_PLAN.md §4 blind spot 4:
+ *   - invalid enum value       (`checks` + `findings`, severity critical)
+ *   - required prop missing    (`checks` + `findings`, severity critical)
+ *   - deprecated prop passed   (`findings` only, severity warning)
+ *   - className/style passed   (`findings` only, severity warning — "drift")
+ *
+ * `checks` (not `findings`) feed the three-number ledger — only the first
+ * two have a real valid/invalid/unresolved population; the last two only
+ * ever fire when something is actually wrong, so there's no "valid" case to
+ * count (mirrors tokenAliasResolver.js's raw-fallback/layer-violation
+ * findings, which are also never part of its usages ledger).
+ */
+export function evaluateCallSite({ attributes, propMap = [], ignore = [], component, file, line }) {
+  const checks = [];
+  const findings = [];
+
+  const byName = new Map(propMap.map((entry) => [entry.react, entry]));
+  const ignoreSet = new Set(ignore);
+
+  let hasSpread = false;
+  const passedNames = new Set();
+
+  for (const attr of attributes) {
+    if (attr.type === 'JSXSpreadAttribute') {
+      hasSpread = true;
+      continue;
+    }
+    const name = attr.name.name;
+    passedNames.add(name);
+
+    if (STYLE_ESCAPE_ATTRS.has(name)) {
+      findings.push({ rule: 'style-escape-hatch', severity: 'warning', component, prop: name, file, line });
+      continue;
+    }
+
+    // Legitimate prop the mapping deliberately excludes from Figma sync
+    // (aria-*, onClick, id, ref, key, children, ...) — not a contract gap.
+    if (ignoreSet.has(name)) continue;
+
+    const entry = byName.get(name);
+    // Not tracked by the mapping at all. Could be a native DOM attribute or
+    // an untracked passthrough — never flagged (§9: absence of evidence
+    // never becomes a violation).
+    if (!entry) continue;
+
+    if (entry.deprecated) {
+      findings.push({
+        rule: 'deprecated-prop-passed',
+        severity: 'warning',
+        component,
+        prop: name,
+        reason: typeof entry.deprecated === 'string' ? entry.deprecated : undefined,
+        file,
+        line,
+      });
+    }
+
+    if (entry.type === 'enum') {
+      const literal = literalAttrValue(attr);
+      if (!literal.resolved) {
+        checks.push({ component, prop: name, rule: 'enum-value', classification: 'unresolved', file, line });
+        continue;
+      }
+      const key = String(literal.value);
+      const valid = Object.prototype.hasOwnProperty.call(entry.values ?? {}, key);
+      checks.push({
+        component,
+        prop: name,
+        rule: 'enum-value',
+        classification: valid ? 'valid' : 'invalid',
+        value: literal.value,
+        file,
+        line,
+      });
+      if (!valid) {
+        findings.push({
+          rule: 'invalid-enum-value',
+          severity: 'critical',
+          component,
+          prop: name,
+          value: literal.value,
+          allowed: Object.keys(entry.values ?? {}),
+          file,
+          line,
+        });
+      }
+    }
+  }
+
+  for (const entry of propMap) {
+    if (!entry.required) continue;
+    if (passedNames.has(entry.react)) {
+      checks.push({ component, prop: entry.react, rule: 'required-prop', classification: 'valid', file, line });
+      continue;
+    }
+    if (hasSpread) {
+      // A spread (`{...rest}`) might forward the required prop dynamically —
+      // can't be statically ruled out, so this stays unresolved rather than
+      // a false-positive violation.
+      checks.push({ component, prop: entry.react, rule: 'required-prop', classification: 'unresolved', file, line });
+      continue;
+    }
+    checks.push({ component, prop: entry.react, rule: 'required-prop', classification: 'invalid', file, line });
+    findings.push({ rule: 'required-prop-missing', severity: 'critical', component, prop: entry.react, file, line });
+  }
+
+  return { checks, findings };
+}
+
+function summarizeReport(checks) {
+  const counts = { valid: 0, invalid: 0, unresolved: 0 };
+  for (const c of checks) counts[c.classification] += 1;
+  const total = counts.valid + counts.invalid + counts.unresolved;
+  const pct = (n) => (total === 0 ? 0 : Math.round((n / total) * 1000) / 10);
+  return {
+    total,
+    valid: counts.valid,
+    validPct: pct(counts.valid),
+    invalid: counts.invalid,
+    invalidPct: pct(counts.invalid),
+    unresolved: counts.unresolved,
+    unresolvedPct: pct(counts.unresolved),
+  };
+}
+
+/**
+ * Walks every JSX call site of a catalog component and validates its
+ * attributes against `prop-mapping/components/{slug}.mapping.json` (metric
+ * 6, ADOPTION_APP_PLAN.md §4 blind spot 4 / §9 Phase 1b).
+ *
+ * Web only, and not by choice — `prop-mapping/` has no `rn/` subdirectory
+ * (§4 blind spot 4), so there is no artifact to validate an RN prop against.
+ * Matches resolveTokenAliases/resolveTailwindTokens: throws rather than
+ * silently no-opping, so a caller can never mistake "not run" for "clean".
+ *
+ * `required`/`deprecated` propMapEntry fields are optional and, as of this
+ * resolver's introduction, not yet authored into any real mapping file — so
+ * those two checks currently produce zero findings against real data. That
+ * is an honest "not yet assessed" state, not a bug: population is a
+ * separate authoring pass (same shape as §3d.2's RN accessibility-contract
+ * gap), and this resolver never fabricates a requirement that isn't
+ * declared.
+ */
+export function resolvePropApi(root, { platform = 'web', ignore = [] } = {}) {
+  if (platform !== 'web') {
+    throw new Error(`resolvePropApi only supports platform "web" (got "${platform}") — prop-mapping/ has no RN equivalent.`);
+  }
+
+  const pkgName = packageNameForPlatform(platform);
+  const catalog = loadCatalog(platform);
+  const byName = new Map(catalog.components.map((c) => [c.name, c]));
+
+  const mappingCache = new Map();
+  function mappingFor(componentName) {
+    if (mappingCache.has(componentName)) return mappingCache.get(componentName);
+    let result = null;
+    try {
+      const props = getComponentProps(componentName, 'web');
+      result = { propMap: props.propMap, ignore: props.ignore };
+    } catch {
+      result = null; // no mapping file for this component — nothing to validate
+    }
+    mappingCache.set(componentName, result);
+    return result;
+  }
+
+  const moduleGraph = buildModuleGraph(root, { ignore });
+  const checks = [];
+  const findings = [];
+  const unresolvedFiles = [];
+
+  for (const file of moduleGraph.files) {
+    const entry = moduleGraph.graph.get(file);
+    if (!entry) continue;
+    if (entry.parseError) {
+      unresolvedFiles.push(path.relative(root, file));
+      continue;
+    }
+
+    const localToComponent = new Map();
+    for (const localName of entry.imports.keys()) {
+      const origin = resolveOrigin(moduleGraph, file, localName);
+      if (origin?.pkg === pkgName && byName.has(origin.name)) {
+        localToComponent.set(localName, origin.name);
+      }
+    }
+    if (localToComponent.size === 0) continue;
+
+    traverse(entry.ast, {
+      JSXOpeningElement(elPath) {
+        const nameNode = elPath.node.name;
+        let componentName = null;
+        if (nameNode.type === 'JSXIdentifier') {
+          componentName = localToComponent.get(nameNode.name) ?? null;
+        } else if (nameNode.type === 'JSXMemberExpression' && nameNode.object.type === 'JSXIdentifier') {
+          // Compound tags (`<DropdownMenu.Item/>`) validate against the root
+          // component's own propMap — subComponents carry a separate propMap
+          // in the mapping file that a future pass could wire in here.
+          componentName = localToComponent.get(nameNode.object.name) ?? null;
+        }
+        if (!componentName) return;
+
+        const mapping = mappingFor(componentName);
+        if (!mapping) return;
+
+        const result = evaluateCallSite({
+          attributes: elPath.node.attributes,
+          propMap: mapping.propMap,
+          ignore: mapping.ignore,
+          component: componentName,
+          file: path.relative(root, file),
+          line: elPath.node.loc?.start.line ?? null,
+        });
+        checks.push(...result.checks);
+        findings.push(...result.findings);
+      },
+    });
+  }
+
+  return {
+    platform,
+    package: pkgName,
+    root,
+    scannedFiles: moduleGraph.files.length,
+    unresolvedFiles,
+    report: summarizeReport(checks),
+    checks,
+    findings,
+  };
+}