@starklab/stark-mcp 0.1.0 → 0.2.1

package/src/adopt/__fixtures__/dominion-fixture-app/src/theme.css

@@ -1,34 +0,0 @@
-:root {
-  /* nested aliases — app-base -> app-mid -> app-top -> app-deep, terminal
-     depth 4 (deeper than tokenAliasResolver's WARN_DEPTH of 3), exercising
-     both transitive resolution and the deep-alias-chain finding */
-  --app-base: var(--stk-surface-brand-1-strong);
-  --app-mid: var(--app-base);
-  --app-top: var(--app-mid);
-  --app-deep: var(--app-top);
-
-  /* raw fallback — resolves conformant, still flagged info-level since the
-     fallback silently becomes load-bearing the day
-     --stk-surface-brand-1-strong is renamed */
-  --app-cta: var(--stk-surface-brand-1-strong, #1956dd);
-
-  /* primitive alias — layer violation: a consumer property pointing straight
-     at a base/primitive token instead of a semantic one */
-  --app-gap: var(--stk-spacing-md);
-
-  /* scoped-override target — conformant at :root */
-  --app-accent: var(--stk-surface-brand-1-strong);
-}
-
-/* scoped override — same property, different selector, resolving to a raw
-   hex under .theme-promo: :root and .theme-promo disagree, so the property
-   overall is partial-conformance rather than collapsed to one scope */
-.theme-promo {
-  --app-accent: #1956dd;
-}
-
-/* Tailwind v4 theme entry — Home.jsx's className="dark:bg-primary" resolves
-   through this back to a Stark token */
-@theme {
-  --color-primary: var(--stk-surface-brand-1-strong);
-}

package/src/adopt/__fixtures__/dominion-fixture-app/src/wrappers/AppButton.jsx

@@ -1,8 +0,0 @@
-import React from 'react';
-import { Button } from '@starklab/stk-components';
-
-// Transparent wrapper — spreads props through unmodified, no hardcoded or
-// style-only attributes.
-export function AppButton(props) {
-  return <Button {...props} />;
-}

package/src/adopt/__fixtures__/dominion-fixture-app/src/wrappers/BrandButton.jsx

@@ -1,9 +0,0 @@
-import React from 'react';
-import { Button } from '@starklab/stk-components';
-
-// Divergent wrapper — a hardcoded className makes this a styling override,
-// not a faithful passthrough. Used from several call sites (see
-// pages/Home.jsx and pages/Profile.jsx) to exercise high fanout.
-export function BrandButton(props) {
-  return <Button className="brand-button" {...props} />;
-}

package/src/adopt/__fixtures__/dominion-fixture-app/src/wrappers/CardBase.jsx

@@ -1,9 +0,0 @@
-import React from 'react';
-import { Card } from '@starklab/stk-components';
-
-// First hop of a two-level wrapper chain (see FeatureCard.jsx) — transparent
-// passthrough. Only consumed internally by FeatureCard, so its own external
-// fanout should be zero (the chain edge itself is excluded from fanout).
-export function CardBase(props) {
-  return <Card {...props} />;
-}

package/src/adopt/__fixtures__/dominion-fixture-app/src/wrappers/FeatureCard.jsx

@@ -1,7 +0,0 @@
-import React from 'react';
-import { CardBase } from './CardBase';
-
-// Second hop of the chain — resolves through CardBase down to Card.
-export function FeatureCard(props) {
-  return <CardBase {...props} />;
-}

package/src/adopt/__fixtures__/dominion-fixture-app/src/wrappers/SectionCard.jsx

@@ -1,12 +0,0 @@
-import React from 'react';
-import { Card } from '@starklab/stk-components';
-
-// An "as"-polymorphic call site. ADOPTION_APP_PLAN.md §4 "Polymorphism" calls
-// for a declared `polymorphicProp` field in prop-mapping/schema.json as
-// future work — no dedicated `as`-detection exists in wrapperResolver.js yet,
-// so a hardcoded `as` attribute is classified through the ordinary
-// hardcodedProps -> "constraining" path, same as any other literal prop.
-// This fixture documents that current (pre-declaration) behavior.
-export function SectionCard(props) {
-  return <Card as="section" {...props} />;
-}

package/src/adopt/dominionFixture.test.js

@@ -1,165 +0,0 @@
-import { describe, it, expect } from 'vitest';
-import path from 'node:path';
-import { fileURLToPath } from 'node:url';
-
-import { resolveReferences } from './referenceResolver.js';
-import { resolveWrappers } from './wrapperResolver.js';
-import { resolveTokenAliases } from './tokenAliasResolver.js';
-import { resolveTailwindTokens } from './tailwindResolver.js';
-import { resolvePropApi } from './propApiResolver.js';
-
-// This fixture app (__fixtures__/dominion-fixture-app/) is the shared
-// consumer app ADOPTION_APP_PLAN.md's Phase 1 roadmap calls for — one app
-// exercising every element the plan names (a theme file, nested aliases, a
-// scoped override, a raw fallback, a primitive alias, a Tailwind variant, a
-// transparent wrapper, a divergent high-fanout wrapper, a two-level wrapper
-// chain, an "as"-polymorphic call site, a compound Foo.Bar usage, a direct
-// invalid-enum-value call site, and a className passthrough) run through all
-// five web resolvers together — treated as their test suite.
-const root = path.join(path.dirname(fileURLToPath(import.meta.url)), '__fixtures__', 'dominion-fixture-app');
-
-describe('dominion fixture app — resolveReferences', () => {
-  it('attributes direct and compound-tag usages to the right catalog components', () => {
-    const result = resolveReferences(root, { platform: 'web' });
-    const byName = new Map(result.components.map((c) => [c.name, c]));
-
-    expect(byName.get('Button').counts.jsx).toBe(3); // AppButton.jsx, BrandButton.jsx, Home.jsx
-    expect(byName.get('Card').counts.jsx).toBe(2); // CardBase.jsx, SectionCard.jsx
-    // outer <DropdownMenu> opening tag + <DropdownMenu.SubTrigger>'s object ref
-    expect(byName.get('DropdownMenu').counts.jsx).toBe(2);
-  });
-});
-
-describe('dominion fixture app — resolveWrappers', () => {
-  it('classifies faithfulness, chain depth, and fanout for every wrapper', () => {
-    const result = resolveWrappers(root, { platform: 'web' });
-    const byExportedAs = new Map(result.wrappers.map((w) => [w.exportedAs, w]));
-
-    const appButton = byExportedAs.get('AppButton');
-    expect(appButton.component).toBe('Button');
-    expect(appButton.chain[0].faithfulness).toBe('transparent');
-    expect(appButton.depth).toBe(1);
-
-    const brandButton = byExportedAs.get('BrandButton');
-    expect(brandButton.component).toBe('Button');
-    expect(brandButton.chain[0].faithfulness).toBe('divergent');
-    expect(brandButton.fanout.counts.jsx).toBe(5); // 3x Home.jsx + 2x Profile.jsx
-
-    const cardBase = byExportedAs.get('CardBase');
-    expect(cardBase.component).toBe('Card');
-    expect(cardBase.chain[0].faithfulness).toBe('transparent');
-    // Only consumer is FeatureCard's own chain edge — excluded from fanout.
-    expect(cardBase.fanout.counts.jsx).toBe(0);
-
-    const featureCard = byExportedAs.get('FeatureCard');
-    expect(featureCard.component).toBe('Card');
-    expect(featureCard.depth).toBe(2);
-    expect(featureCard.warnDepth).toBe(false);
-    expect(featureCard.fanout.counts.jsx).toBe(1); // Home.jsx
-
-    const sectionCard = byExportedAs.get('SectionCard');
-    expect(sectionCard.component).toBe('Card');
-    // No dedicated `as`-polymorphism detection yet (ADOPTION_APP_PLAN.md §4)
-    // — a hardcoded `as` attribute takes the generic hardcodedProps path.
-    expect(sectionCard.chain[0].faithfulness).toBe('constraining');
-
-    const byComponent = new Map(result.byComponent.map((c) => [c.name, c]));
-    expect(byComponent.get('Card').viaWrappers.map((w) => w.exportedAs).sort()).toEqual([
-      'CardBase',
-      'FeatureCard',
-      'SectionCard',
-    ]);
-    expect(byComponent.get('Button').viaWrappers.map((w) => w.exportedAs).sort()).toEqual([
-      'AppButton',
-      'BrandButton',
-    ]);
-  });
-});
-
-describe('dominion fixture app — resolveTokenAliases', () => {
-  it('resolves nested aliases, flags deep chains, layer violations, raw fallbacks, and partial conformance', () => {
-    const result = resolveTokenAliases(root, { platform: 'web' });
-    const byName = new Map(result.properties.map((p) => [p.name, p]));
-
-    expect(byName.get('--app-base').state).toBe('conformant');
-    expect(byName.get('--app-mid').state).toBe('conformant');
-    expect(byName.get('--app-top').state).toBe('conformant');
-    expect(byName.get('--app-deep').state).toBe('conformant');
-
-    const deepChain = result.findings.find((f) => f.rule === 'deep-alias-chain' && f.property === '--app-deep');
-    expect(deepChain).toBeDefined();
-    expect(deepChain.depth).toBe(4);
-    // Shallower hops in the same chain stay under WARN_DEPTH (3).
-    expect(result.findings.some((f) => f.rule === 'deep-alias-chain' && f.property === '--app-top')).toBe(false);
-
-    const rawFallback = result.findings.find((f) => f.rule === 'raw-fallback' && f.property === '--app-cta');
-    expect(rawFallback).toBeDefined();
-
-    const layerViolation = result.findings.find((f) => f.rule === 'layer-violation' && f.property === '--app-gap');
-    expect(layerViolation).toBeDefined();
-    expect(layerViolation.severity).toBe('critical');
-
-    expect(byName.get('--app-accent').state).toBe('partial-conformance');
-    expect(
-      result.findings.some(
-        (f) => f.rule === 'drift-behind-alias' && f.property === '--app-accent' && f.selector === '.theme-promo'
-      )
-    ).toBe(true);
-    expect(result.findings.some((f) => f.rule === 'partial-conformance' && f.property === '--app-accent')).toBe(true);
-  });
-});
-
-describe('dominion fixture app — resolveTailwindTokens', () => {
-  it('resolves a v4 @theme entry through a variant-prefixed utility class back to a Stark token', () => {
-    const result = resolveTailwindTokens(root, { platform: 'web' });
-
-    expect(result.detected).toBe(true);
-    expect(result.source).toBe('v4');
-
-    const colorPrimary = result.properties.find((p) => p.name === '--color-primary');
-    expect(colorPrimary.state).toBe('conformant');
-
-    const usage = result.usages.find((u) => u.className === 'dark:bg-primary');
-    expect(usage).toBeDefined();
-    expect(usage.classification).toBe('aliased');
-    expect(result.report.aliased).toBeGreaterThanOrEqual(1);
-  });
-});
-
-describe('dominion fixture app — resolvePropApi', () => {
-  it('flags an invalid enum value and every className/style passthrough against real button/card mapping data', () => {
-    const result = resolvePropApi(root, { platform: 'web' });
-
-    // Only one literal enum value appears anywhere in the fixture app
-    // (Home.jsx's `variant="primry"`) — everything else is either a spread
-    // passthrough (AppButton.jsx, CardBase.jsx), an untracked attribute
-    // (`as` on SectionCard.jsx's Card, absent from both propMap and ignore),
-    // or has no attributes at all (Menu.jsx's DropdownMenu tags).
-    expect(result.report).toEqual({ total: 1, valid: 0, validPct: 0, invalid: 1, invalidPct: 100, unresolved: 0, unresolvedPct: 0 });
-
-    const enumFinding = result.findings.find((f) => f.rule === 'invalid-enum-value');
-    expect(enumFinding).toMatchObject({
-      component: 'Button',
-      prop: 'variant',
-      value: 'primry',
-      allowed: ['primary', 'ghost', 'outline', 'danger'],
-      severity: 'critical',
-      file: 'src/pages/Home.jsx',
-    });
-
-    // className shows up on two real Button call sites — BrandButton.jsx's
-    // hardcoded wrapper prop and Home.jsx's own direct passthrough.
-    const styleFindings = result.findings.filter((f) => f.rule === 'style-escape-hatch');
-    expect(styleFindings.map((f) => f.file).sort()).toEqual([
-      'src/pages/Home.jsx',
-      'src/wrappers/BrandButton.jsx',
-    ]);
-    expect(styleFindings.every((f) => f.component === 'Button' && f.prop === 'className' && f.severity === 'warning')).toBe(true);
-
-    // SectionCard.jsx's hardcoded `as="section"` is neither in Card's
-    // propMap nor its ignore list — absence of evidence, never a violation.
-    expect(result.findings.some((f) => f.file === 'src/wrappers/SectionCard.jsx')).toBe(false);
-
-    expect(result.findings).toHaveLength(3);
-  });
-});

package/src/adopt/propApiResolver.test.js

@@ -1,229 +0,0 @@
-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([]);
-  });
-});