@starklab/stark-mcp 0.1.0

package/src/adopt/propApiResolver.test.js

@@ -0,0 +1,229 @@
+import { mkdtempSync, rmSync, mkdirSync, writeFileSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+import { describe, it, expect, afterEach } from 'vitest';
+import traverseModule from '@babel/traverse';
+
+import { evaluateCallSite, resolvePropApi } from './propApiResolver.js';
+import { parseSource } from './parseSource.js';
+
+const traverse = traverseModule.default ?? traverseModule;
+
+// Parses a single-element JSX snippet and returns its opening element's
+// attribute nodes — the same shape resolvePropApi's own traversal passes
+// into evaluateCallSite, so these unit tests exercise the exact input shape
+// without needing a real mapping file or a scanned consumer app on disk.
+function attrsFor(jsx) {
+  const ast = parseSource(`const El = () => (${jsx});`, 'snippet.jsx');
+  let attributes = null;
+  traverse(ast, {
+    JSXOpeningElement(p) {
+      if (attributes === null) attributes = p.node.attributes;
+    },
+  });
+  return attributes;
+}
+
+const ENUM_PROP_MAP = [
+  { react: 'variant', type: 'enum', values: { primary: 'primary', ghost: 'ghost' } },
+];
+
+let tmpDirs = [];
+
+afterEach(() => {
+  for (const dir of tmpDirs) rmSync(dir, { recursive: true, force: true });
+  tmpDirs = [];
+});
+
+function fixture(files) {
+  const root = mkdtempSync(path.join(os.tmpdir(), 'stark-adopt-propapi-'));
+  tmpDirs.push(root);
+  for (const [rel, content] of Object.entries(files)) {
+    const full = path.join(root, rel);
+    mkdirSync(path.dirname(full), { recursive: true });
+    writeFileSync(full, content);
+  }
+  return root;
+}
+
+describe('evaluateCallSite — enum values', () => {
+  it('classifies a literal value inside the declared enum as valid', () => {
+    const { checks, findings } = evaluateCallSite({
+      attributes: attrsFor('<Button variant="primary" />'),
+      propMap: ENUM_PROP_MAP,
+      component: 'Button',
+    });
+    expect(checks).toEqual([{ component: 'Button', prop: 'variant', rule: 'enum-value', classification: 'valid', value: 'primary', file: undefined, line: undefined }]);
+    expect(findings).toEqual([]);
+  });
+
+  it('classifies a literal value outside the declared enum as invalid, with an invalid-enum-value finding', () => {
+    const { checks, findings } = evaluateCallSite({
+      attributes: attrsFor('<Button variant="primry" />'),
+      propMap: ENUM_PROP_MAP,
+      component: 'Button',
+    });
+    expect(checks[0].classification).toBe('invalid');
+    expect(findings).toEqual([
+      { rule: 'invalid-enum-value', severity: 'critical', component: 'Button', prop: 'variant', value: 'primry', allowed: ['primary', 'ghost'], file: undefined, line: undefined },
+    ]);
+  });
+
+  it('classifies a dynamic expression as unresolved, never valid or invalid', () => {
+    const { checks, findings } = evaluateCallSite({
+      attributes: attrsFor('<Button variant={someVar} />'),
+      propMap: ENUM_PROP_MAP,
+      component: 'Button',
+    });
+    expect(checks[0].classification).toBe('unresolved');
+    expect(findings).toEqual([]);
+  });
+
+  it('also treats a template literal or ternary as unresolved', () => {
+    for (const jsx of ['<Button variant={`primary`} />', '<Button variant={cond ? "primary" : "ghost"} />']) {
+      const { checks } = evaluateCallSite({ attributes: attrsFor(jsx), propMap: ENUM_PROP_MAP, component: 'Button' });
+      expect(checks[0].classification).toBe('unresolved');
+    }
+  });
+});
+
+describe('evaluateCallSite — required props', () => {
+  const REQUIRED_PROP_MAP = [{ react: 'label', type: 'text', required: true }];
+
+  it('flags a missing required prop as invalid, with a required-prop-missing finding', () => {
+    const { checks, findings } = evaluateCallSite({
+      attributes: attrsFor('<Field />'),
+      propMap: REQUIRED_PROP_MAP,
+      component: 'Field',
+    });
+    expect(checks).toEqual([{ component: 'Field', prop: 'label', rule: 'required-prop', classification: 'invalid', file: undefined, line: undefined }]);
+    expect(findings).toEqual([{ rule: 'required-prop-missing', severity: 'critical', component: 'Field', prop: 'label', file: undefined, line: undefined }]);
+  });
+
+  it('classifies a present required prop as valid', () => {
+    const { checks, findings } = evaluateCallSite({
+      attributes: attrsFor('<Field label="Name" />'),
+      propMap: REQUIRED_PROP_MAP,
+      component: 'Field',
+    });
+    expect(checks).toEqual([{ component: 'Field', prop: 'label', rule: 'required-prop', classification: 'valid', file: undefined, line: undefined }]);
+    expect(findings).toEqual([]);
+  });
+
+  it('leaves a missing required prop unresolved (not flagged) when the element spreads props', () => {
+    const { checks, findings } = evaluateCallSite({
+      attributes: attrsFor('<Field {...rest} />'),
+      propMap: REQUIRED_PROP_MAP,
+      component: 'Field',
+    });
+    expect(checks).toEqual([{ component: 'Field', prop: 'label', rule: 'required-prop', classification: 'unresolved', file: undefined, line: undefined }]);
+    expect(findings).toEqual([]);
+  });
+});
+
+describe('evaluateCallSite — deprecated props', () => {
+  it('flags a deprecated prop only when actually passed, with the reason carried through', () => {
+    const propMap = [{ react: 'legacy', type: 'text', deprecated: 'use "modern" instead' }];
+
+    const passed = evaluateCallSite({ attributes: attrsFor('<Widget legacy="x" />'), propMap, component: 'Widget' });
+    expect(passed.findings).toEqual([
+      { rule: 'deprecated-prop-passed', severity: 'warning', component: 'Widget', prop: 'legacy', reason: 'use "modern" instead', file: undefined, line: undefined },
+    ]);
+    // Presence-based, not value-based — doesn't feed the valid/invalid/unresolved ledger.
+    expect(passed.checks).toEqual([]);
+
+    const absent = evaluateCallSite({ attributes: attrsFor('<Widget />'), propMap, component: 'Widget' });
+    expect(absent.findings).toEqual([]);
+  });
+
+  it('flags a plain deprecated: true prop with no reason field', () => {
+    const propMap = [{ react: 'legacy', type: 'text', deprecated: true }];
+    const { findings } = evaluateCallSite({ attributes: attrsFor('<Widget legacy="x" />'), propMap, component: 'Widget' });
+    expect(findings[0].reason).toBeUndefined();
+  });
+});
+
+describe('evaluateCallSite — className/style escape hatch', () => {
+  it('flags className and style as style-escape-hatch findings, outside the ledger', () => {
+    const { checks, findings } = evaluateCallSite({
+      attributes: attrsFor('<Card className="foo" style={{ color: "red" }} />'),
+      propMap: [],
+      ignore: ['className', 'style'],
+      component: 'Card',
+    });
+    expect(checks).toEqual([]);
+    expect(findings).toEqual([
+      { rule: 'style-escape-hatch', severity: 'warning', component: 'Card', prop: 'className', file: undefined, line: undefined },
+      { rule: 'style-escape-hatch', severity: 'warning', component: 'Card', prop: 'style', file: undefined, line: undefined },
+    ]);
+  });
+});
+
+describe('evaluateCallSite — untracked props', () => {
+  it('never flags a prop in the mapping ignore list, or one absent from both propMap and ignore', () => {
+    const { checks, findings } = evaluateCallSite({
+      attributes: attrsFor('<Button aria-label="Close" onClick={fn} data-testid="x" />'),
+      propMap: ENUM_PROP_MAP,
+      ignore: ['aria-label', 'onClick', 'data-testid'],
+      component: 'Button',
+    });
+    expect(checks).toEqual([]);
+    expect(findings).toEqual([]);
+  });
+});
+
+describe('resolvePropApi — integration against the real Button mapping', () => {
+  it('throws for platform !== "web" — prop-mapping/ has no RN equivalent', () => {
+    const root = fixture({ 'src/App.jsx': `export const App = () => null;` });
+    expect(() => resolvePropApi(root, { platform: 'native' })).toThrow(/only supports platform "web"/);
+  });
+
+  it('reports a valid check for a correct enum value at a real Button call site', () => {
+    const root = fixture({
+      'src/App.jsx': `
+        import { Button } from '@starklab/stk-components';
+        export const App = () => <Button variant="primary">Go</Button>;
+      `,
+    });
+    const result = resolvePropApi(root, { platform: 'web' });
+    expect(result.report).toEqual({ total: 1, valid: 1, validPct: 100, invalid: 0, invalidPct: 0, unresolved: 0, unresolvedPct: 0 });
+    expect(result.findings).toEqual([]);
+  });
+
+  it('flags an invalid Button variant and a className passthrough at a real call site', () => {
+    const root = fixture({
+      'src/App.jsx': `
+        import { Button } from '@starklab/stk-components';
+        export const App = () => <Button variant="primry" className="hero-cta">Go</Button>;
+      `,
+    });
+    const result = resolvePropApi(root, { platform: 'web' });
+    expect(result.report.invalid).toBe(1);
+    expect(result.report.valid).toBe(0);
+
+    const enumFinding = result.findings.find((f) => f.rule === 'invalid-enum-value');
+    expect(enumFinding).toMatchObject({ component: 'Button', prop: 'variant', value: 'primry', severity: 'critical' });
+
+    const styleFinding = result.findings.find((f) => f.rule === 'style-escape-hatch');
+    expect(styleFinding).toMatchObject({ component: 'Button', prop: 'className', severity: 'warning' });
+  });
+
+  it('leaves a dynamic Button variant unresolved rather than scoring it', () => {
+    const root = fixture({
+      'src/App.jsx': `
+        import { Button } from '@starklab/stk-components';
+        export const App = ({ v }) => <Button variant={v}>Go</Button>;
+      `,
+    });
+    const result = resolvePropApi(root, { platform: 'web' });
+    expect(result.report).toEqual({ total: 1, valid: 0, validPct: 0, invalid: 0, invalidPct: 0, unresolved: 1, unresolvedPct: 100 });
+  });
+
+  it('reports an all-zero ledger when the consumer uses no catalog components', () => {
+    const root = fixture({ 'src/App.jsx': `export const App = () => <div />;` });
+    const result = resolvePropApi(root, { platform: 'web' });
+    expect(result.report).toEqual({ total: 0, valid: 0, validPct: 0, invalid: 0, invalidPct: 0, unresolved: 0, unresolvedPct: 0 });
+    expect(result.findings).toEqual([]);
+  });
+});

package/src/adopt/referenceResolver.js

@@ -0,0 +1,151 @@
+import path from 'node:path';
+
+import traverseModule from '@babel/traverse';
+
+import { loadCatalog, packageNameForPlatform } from './catalog.js';
+import { buildModuleGraph, resolveOrigin } from './moduleGraph.js';
+
+const traverse = traverseModule.default ?? traverseModule;
+
+export const KIND_CONFIDENCE = {
+  jsx: 'certain',
+  createElement: 'certain',
+  hoc: 'high',
+  indirect: 'needs-review',
+  reexport: 'not-a-usage',
+};
+
+function isCreateElementCallee(node) {
+  if (!node) return false;
+  if (node.type === 'Identifier') return node.name === 'createElement';
+  if (node.type === 'MemberExpression' && !node.computed) {
+    return node.property.type === 'Identifier' && node.property.name === 'createElement';
+  }
+  return false;
+}
+
+/**
+ * Classifies a single reference to a catalog component per
+ * ADOPTION_APP_PLAN.md §4 blind spot 2's five-kind table:
+ *   jsx           — rendered as a JSX element (`<Button/>`, `<Foo.Bar/>`)
+ *   createElement — rendered via a non-JSX call (`React.createElement(Button, ...)`,
+ *                   or the component invoked directly as a function)
+ *   hoc           — passed as an argument to some other function (`styled(Button)`)
+ *   indirect      — referenced any other way (variable, object value, ternary
+ *                   branch, spread, member access) — needs human review, may
+ *                   or may not render
+ *   reexport      — forwarded via `export { Button }` — not a usage
+ */
+export function classifyReference(refPath) {
+  const parent = refPath.parentPath;
+  if (!parent) return 'indirect';
+
+  // The closing tag (`</Button>`) is a second reference to the same binding
+  // for the same element the opening tag already counted — skip it rather
+  // than double-counting or misclassifying it as indirect.
+  if (parent.isJSXClosingElement()) return null;
+
+  if (parent.isJSXOpeningElement() && parent.node.name === refPath.node) return 'jsx';
+  if (parent.isJSXMemberExpression() && parent.node.object === refPath.node) {
+    // Same closing-tag skip as above, one level up for `<Foo.Bar/>` compound
+    // tags: the identifier's direct parent is the JSXMemberExpression, whose
+    // own parent is the (opening or closing) element.
+    if (parent.parentPath?.isJSXClosingElement()) return null;
+    return 'jsx';
+  }
+  if (parent.isExportSpecifier() && parent.node.local === refPath.node) return 'reexport';
+
+  if (parent.isCallExpression()) {
+    if (parent.node.callee === refPath.node) return 'createElement';
+    if (isCreateElementCallee(parent.node.callee) && parent.node.arguments[0] === refPath.node) {
+      return 'createElement';
+    }
+    return 'hoc';
+  }
+
+  return 'indirect';
+}
+
+/**
+ * Scans every source file under `root`, resolves each local binding back to
+ * a catalog component (directly imported, or transitively re-exported
+ * through the consumer's own barrels), classifies every reference site by
+ * kind, and left-joins the result onto the full catalog so components with
+ * zero usages appear as 0 rather than being silently absent from the report
+ * (§4 blind spots 1 & 2).
+ */
+export function resolveReferences(root, { platform = 'web', ignore = [] } = {}) {
+  const pkgName = packageNameForPlatform(platform);
+  const catalog = loadCatalog(platform);
+  const byName = new Map(catalog.components.map((c) => [c.name, c]));
+
+  const moduleGraph = buildModuleGraph(root, { ignore });
+
+  const results = new Map(
+    catalog.components.map((c) => [
+      c.name,
+      {
+        name: c.name,
+        slug: c.slug,
+        counts: { jsx: 0, createElement: 0, hoc: 0, indirect: 0, reexport: 0 },
+        sites: [],
+      },
+    ])
+  );
+
+  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, {
+      Program(programPath) {
+        for (const [localName, componentName] of localToComponent) {
+          const binding = programPath.scope.getBinding(localName);
+          if (!binding) continue;
+          const result = results.get(componentName);
+          for (const refPath of binding.referencePaths) {
+            const kind = classifyReference(refPath);
+            if (!kind) continue; // closing-tag identifier — not a distinct usage
+            result.counts[kind] += 1;
+            result.sites.push({
+              file: path.relative(root, file),
+              line: refPath.node.loc?.start.line ?? null,
+              kind,
+              confidence: KIND_CONFIDENCE[kind],
+            });
+          }
+        }
+      },
+    });
+  }
+
+  const components = [...results.values()].sort((a, b) => a.name.localeCompare(b.name));
+  const zeroUsage = components.filter(
+    (c) => c.counts.jsx + c.counts.createElement + c.counts.hoc + c.counts.indirect === 0
+  );
+
+  return {
+    platform,
+    package: pkgName,
+    root,
+    scannedFiles: moduleGraph.files.length,
+    unresolvedFiles,
+    components,
+    zeroUsage: zeroUsage.map((c) => c.name),
+  };
+}

package/src/adopt/referenceResolver.test.js

@@ -0,0 +1,213 @@
+import { mkdtempSync, rmSync, mkdirSync, writeFileSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+import { describe, it, expect, afterEach } from 'vitest';
+
+import { resolveReferences } from './referenceResolver.js';
+
+let tmpDirs = [];
+
+afterEach(() => {
+  for (const dir of tmpDirs) rmSync(dir, { recursive: true, force: true });
+  tmpDirs = [];
+});
+
+function fixture(files) {
+  const root = mkdtempSync(path.join(os.tmpdir(), 'stark-adopt-'));
+  tmpDirs.push(root);
+  for (const [rel, content] of Object.entries(files)) {
+    const full = path.join(root, rel);
+    mkdirSync(path.dirname(full), { recursive: true });
+    writeFileSync(full, content);
+  }
+  return root;
+}
+
+function component(result, name) {
+  const found = result.components.find((c) => c.name === name);
+  if (!found) throw new Error(`No component named "${name}" in result`);
+  return found;
+}
+
+describe('resolveReferences — reference kind classification', () => {
+  it('classifies a directly-imported JSX element as jsx, without double-counting the closing tag', () => {
+    const root = fixture({
+      'src/App.jsx': `
+        import { Button } from '@starklab/stk-components';
+        export const App = () => <Button variant="primary">Click</Button>;
+      `,
+    });
+    const result = resolveReferences(root, { platform: 'web' });
+    const button = component(result, 'Button');
+    expect(button.counts).toEqual({ jsx: 1, createElement: 0, hoc: 0, indirect: 0, reexport: 0 });
+    expect(button.sites).toHaveLength(1);
+    expect(button.sites[0].confidence).toBe('certain');
+  });
+
+  it('classifies a compound JSX member expression (<Foo.Bar/>) as jsx, once per element', () => {
+    const root = fixture({
+      'src/App.jsx': `
+        import { Accordion } from '@starklab/stk-components';
+        export const App = () => <Accordion.Item>content</Accordion.Item>;
+      `,
+    });
+    const result = resolveReferences(root, { platform: 'web' });
+    const accordion = component(result, 'Accordion');
+    expect(accordion.counts.jsx).toBe(1);
+  });
+
+  it('classifies React.createElement(Component, ...) and a bare invocation as createElement', () => {
+    const root = fixture({
+      'src/App.js': `
+        import React from 'react';
+        import { Button } from '@starklab/stk-components';
+        const a = React.createElement(Button, { variant: 'primary' });
+        const b = Button({ variant: 'ghost' });
+      `,
+    });
+    const result = resolveReferences(root, { platform: 'web' });
+    const button = component(result, 'Button');
+    expect(button.counts.createElement).toBe(2);
+    expect(button.counts.jsx).toBe(0);
+  });
+
+  it('classifies a component passed as an argument to another function as hoc', () => {
+    const root = fixture({
+      'src/App.js': `
+        import styled from 'styled-components';
+        import { Button } from '@starklab/stk-components';
+        const StyledButton = styled(Button)\`color: red;\`;
+      `,
+    });
+    const result = resolveReferences(root, { platform: 'web' });
+    const button = component(result, 'Button');
+    expect(button.counts.hoc).toBe(1);
+    expect(button.sites[0].confidence).toBe('high');
+  });
+
+  it('classifies a variable/ternary reference as indirect', () => {
+    const root = fixture({
+      'src/App.js': `
+        import { Button } from '@starklab/stk-components';
+        const chosen = true ? Button : null;
+        const obj = { Comp: Button };
+      `,
+    });
+    const result = resolveReferences(root, { platform: 'web' });
+    const button = component(result, 'Button');
+    expect(button.counts.indirect).toBe(2);
+    expect(button.sites.every((s) => s.confidence === 'needs-review')).toBe(true);
+  });
+
+  it('classifies a forwarding export as reexport and excludes it from usage totals', () => {
+    const root = fixture({
+      'src/App.js': `
+        import { Button } from '@starklab/stk-components';
+        export { Button };
+      `,
+    });
+    const result = resolveReferences(root, { platform: 'web' });
+    const button = component(result, 'Button');
+    expect(button.counts.reexport).toBe(1);
+    expect(button.counts.jsx + button.counts.createElement + button.counts.hoc + button.counts.indirect).toBe(0);
+    // A reexport-only component still isn't "usage", so it shows up as zero-usage.
+    expect(result.zeroUsage).toContain('Button');
+  });
+});
+
+describe('resolveReferences — left-join over the catalog (blind spot 1)', () => {
+  it('reports every catalog component, including ones with no references at all', () => {
+    const root = fixture({
+      'src/App.jsx': `
+        import { Button } from '@starklab/stk-components';
+        export const App = () => <Button>Click</Button>;
+      `,
+    });
+    const result = resolveReferences(root, { platform: 'web' });
+    // Total catalog size, not just what was referenced.
+    expect(result.components.length).toBeGreaterThan(50);
+    const accordion = component(result, 'Accordion');
+    expect(accordion.counts).toEqual({ jsx: 0, createElement: 0, hoc: 0, indirect: 0, reexport: 0 });
+    expect(result.zeroUsage).toContain('Accordion');
+    expect(result.zeroUsage).not.toContain('Button');
+  });
+});
+
+describe('resolveReferences — transitive barrel resolution (blind spot 2)', () => {
+  it('resolves a component re-exported through two hops of the consumer’s own barrels', () => {
+    const root = fixture({
+      'src/ui/index.js': `export { Button } from '../components/ButtonLocal.js';`,
+      'src/components/ButtonLocal.js': `export { Button } from '@starklab/stk-components';`,
+      'src/App.jsx': `
+        import { Button } from './ui/index.js';
+        export const App = () => <Button>Click</Button>;
+      `,
+    });
+    const result = resolveReferences(root, { platform: 'web' });
+    const button = component(result, 'Button');
+    expect(button.counts.jsx).toBe(1);
+  });
+
+  it('does not resolve or crash on a circular local re-export chain', () => {
+    const root = fixture({
+      'src/a.js': `export { Button } from './b.js';`,
+      'src/b.js': `export { Button } from './a.js';`,
+      'src/App.jsx': `
+        import { Button } from './a.js';
+        export const App = () => <Button>Click</Button>;
+      `,
+    });
+    expect(() => resolveReferences(root, { platform: 'web' })).not.toThrow();
+    const result = resolveReferences(root, { platform: 'web' });
+    const button = component(result, 'Button');
+    // Never actually terminates at the real package, so it isn't counted.
+    expect(button.counts).toEqual({ jsx: 0, createElement: 0, hoc: 0, indirect: 0, reexport: 0 });
+  });
+});
+
+describe('resolveReferences — platform separation', () => {
+  it('never counts a stk-react-native import while scanning the web platform', () => {
+    const root = fixture({
+      'src/App.jsx': `
+        import { Button } from '@starklab/stk-react-native';
+        export const App = () => <Button>Click</Button>;
+      `,
+    });
+    const result = resolveReferences(root, { platform: 'web' });
+    const button = component(result, 'Button');
+    expect(button.counts).toEqual({ jsx: 0, createElement: 0, hoc: 0, indirect: 0, reexport: 0 });
+  });
+});
+
+describe('resolveReferences — resilience', () => {
+  it('records an unparseable file without failing the whole scan', () => {
+    const root = fixture({
+      'src/broken.js': `this is not { valid javascript at all +++`,
+      'src/App.jsx': `
+        import { Button } from '@starklab/stk-components';
+        export const App = () => <Button>Click</Button>;
+      `,
+    });
+    const result = resolveReferences(root, { platform: 'web' });
+    const button = component(result, 'Button');
+    expect(button.counts.jsx).toBe(1);
+  });
+
+  it('excludes files matched by the ignore option from the scan', () => {
+    const root = fixture({
+      'src/App.jsx': `
+        import { Button } from '@starklab/stk-components';
+        export const App = () => <Button>Click</Button>;
+      `,
+      'src/generated/Skip.jsx': `
+        import { BadgeStatus } from '@starklab/stk-components';
+        export const Skip = () => <BadgeStatus>Skip</BadgeStatus>;
+      `,
+    });
+    const result = resolveReferences(root, { platform: 'web', ignore: ['**/generated/**'] });
+    expect(result.scannedFiles).toBe(1);
+    const button = component(result, 'Button');
+    expect(button.counts.jsx).toBe(1);
+  });
+});