@starklab/stark-mcp 0.1.0

package/src/adopt/tokenAliasResolver.test.js

@@ -0,0 +1,319 @@
+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 { resolveTokenAliases } from './tokenAliasResolver.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-alias-'));
+  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 property(result, name) {
+  const found = result.properties.find((p) => p.name === name);
+  if (!found) throw new Error(`No property "${name}" in result. Found: ${result.properties.map((p) => p.name).join(', ')}`);
+  return found;
+}
+
+function findingsFor(result, rule, propName) {
+  return result.findings.filter((f) => f.rule === rule && f.property === propName);
+}
+
+describe('resolveTokenAliases — terminal classification', () => {
+  it('classifies a pure alias to an inventory stk token as conformant', () => {
+    const root = fixture({
+      'src/app.css': `:root { --app-primary: var(--stk-surface-brand-1-default); }`,
+    });
+    const result = resolveTokenAliases(root, { platform: 'web' });
+    const p = property(result, '--app-primary');
+    expect(p.state).toBe('conformant');
+    expect(p.scopes[0].terminal.stkToken).toBe('--stk-surface-brand-1-default');
+  });
+
+  it('classifies a raw-value alias as drift-behind-alias', () => {
+    const root = fixture({
+      'src/app.css': `:root { --app-primary: #1956dd; }`,
+    });
+    const result = resolveTokenAliases(root, { platform: 'web' });
+    const p = property(result, '--app-primary');
+    expect(p.state).toBe('drift');
+    expect(findingsFor(result, 'drift-behind-alias', '--app-primary')).toHaveLength(1);
+  });
+
+  it('classifies an alias to an undefined property as broken', () => {
+    const root = fixture({
+      'src/app.css': `:root { --app-primary: var(--app-does-not-exist); }`,
+    });
+    const result = resolveTokenAliases(root, { platform: 'web' });
+    const p = property(result, '--app-primary');
+    expect(p.state).toBe('broken');
+    expect(findingsFor(result, 'broken-alias', '--app-primary')[0].reason).toBe('undefined');
+  });
+
+  it('classifies a cyclic alias chain as broken without throwing', () => {
+    const root = fixture({
+      'src/app.css': `:root { --a: var(--b); --b: var(--a); }`,
+    });
+    expect(() => resolveTokenAliases(root, { platform: 'web' })).not.toThrow();
+    const result = resolveTokenAliases(root, { platform: 'web' });
+    expect(property(result, '--a').state).toBe('broken');
+    expect(findingsFor(result, 'broken-alias', '--a')[0].reason).toBe('cycle');
+  });
+});
+
+describe('resolveTokenAliases — depth', () => {
+  it('warns past ~3 hops on a multi-hop conformant chain', () => {
+    const root = fixture({
+      'src/app.css': `
+        :root {
+          --hop1: var(--hop2);
+          --hop2: var(--hop3);
+          --hop3: var(--hop4);
+          --hop4: var(--stk-spacing-md);
+        }
+      `,
+    });
+    const result = resolveTokenAliases(root, { platform: 'web' });
+    const p = property(result, '--hop1');
+    expect(p.state).toBe('conformant');
+    expect(findingsFor(result, 'deep-alias-chain', '--hop1')).toHaveLength(1);
+  });
+
+  it('does not warn on a short chain within the depth budget', () => {
+    const root = fixture({
+      'src/app.css': `
+        :root {
+          --hop1: var(--hop2);
+          --hop2: var(--stk-spacing-md);
+        }
+      `,
+    });
+    const result = resolveTokenAliases(root, { platform: 'web' });
+    expect(findingsFor(result, 'deep-alias-chain', '--hop1')).toHaveLength(0);
+  });
+});
+
+describe('resolveTokenAliases — fallbacks', () => {
+  it('flags a raw-value fallback as info, never critical', () => {
+    const root = fixture({
+      'src/app.css': `:root { --app-primary: var(--stk-surface-brand-1-default, #1956dd); }`,
+    });
+    const result = resolveTokenAliases(root, { platform: 'web' });
+    const findings = findingsFor(result, 'raw-fallback', '--app-primary');
+    expect(findings).toHaveLength(1);
+    expect(findings[0].severity).toBe('info');
+    // the primary resolves fine, so the property itself is still conformant
+    expect(property(result, '--app-primary').state).toBe('conformant');
+  });
+
+  it('does not flag a fully nested-var fallback', () => {
+    const root = fixture({
+      'src/app.css': `:root { --app-primary: var(--stk-surface-brand-1-default, var(--stk-spacing-md)); }`,
+    });
+    const result = resolveTokenAliases(root, { platform: 'web' });
+    expect(findingsFor(result, 'raw-fallback', '--app-primary')).toHaveLength(0);
+  });
+
+  it('resolves through a raw fallback when the primary is undefined', () => {
+    const root = fixture({
+      'src/app.css': `:root { --app-primary: var(--app-missing, #1956dd); }`,
+    });
+    const result = resolveTokenAliases(root, { platform: 'web' });
+    const p = property(result, '--app-primary');
+    expect(p.state).toBe('drift');
+    expect(p.scopes[0].terminal.viaFallback).toBe(true);
+  });
+});
+
+describe('resolveTokenAliases — layer violations', () => {
+  it('flags an alias resolving straight to a primitive token', () => {
+    const root = fixture({
+      'src/app.css': `:root { --app-primary: var(--stk-color-shade-palette-1-1); }`,
+    });
+    const result = resolveTokenAliases(root, { platform: 'web' });
+    const p = property(result, '--app-primary');
+    // simultaneously conformant (resolves to an inventory stk token) AND a layer violation
+    expect(p.state).toBe('conformant');
+    const findings = findingsFor(result, 'layer-violation', '--app-primary');
+    expect(findings).toHaveLength(1);
+    expect(findings[0].severity).toBe('critical');
+  });
+
+  it('does not flag an alias resolving to a semantic or component token', () => {
+    const root = fixture({
+      'src/app.css': `:root { --app-primary: var(--stk-surface-brand-1-default); }`,
+    });
+    const result = resolveTokenAliases(root, { platform: 'web' });
+    expect(findingsFor(result, 'layer-violation', '--app-primary')).toHaveLength(0);
+  });
+});
+
+describe('resolveTokenAliases — partial-conformance across scopes', () => {
+  it('reports a property redefined differently under two selectors as partial-conformance, never picking a dominant scope', () => {
+    const root = fixture({
+      'src/app.css': `
+        :root { --app-primary: var(--stk-surface-brand-1-default); }
+        .theme-promo { --app-primary: #ff00ff; }
+      `,
+    });
+    const result = resolveTokenAliases(root, { platform: 'web' });
+    const p = property(result, '--app-primary');
+    expect(p.state).toBe('partial-conformance');
+    expect(p.scopes).toHaveLength(2);
+
+    const finding = result.findings.find((f) => f.rule === 'partial-conformance' && f.property === '--app-primary');
+    expect(finding).toBeDefined();
+    expect(finding.severity).toBeNull();
+    expect(finding.scopes).toEqual(
+      expect.arrayContaining([
+        { selector: ':root', state: 'conformant' },
+        { selector: '.theme-promo', state: 'drift' },
+      ])
+    );
+  });
+
+  it('does not report partial-conformance when two selectors agree on the same state', () => {
+    const root = fixture({
+      'src/app.css': `
+        :root { --app-primary: var(--stk-surface-brand-1-default); }
+        .card { --app-primary: var(--stk-surface-brand-1-strong); }
+      `,
+    });
+    const result = resolveTokenAliases(root, { platform: 'web' });
+    expect(property(result, '--app-primary').state).toBe('conformant');
+  });
+});
+
+describe('resolveTokenAliases — usage classification (Pass 2)', () => {
+  it('classifies a direct --stk-* call site as direct', () => {
+    const root = fixture({
+      'src/app.css': `.btn { background: var(--stk-surface-brand-1-default); }`,
+    });
+    const result = resolveTokenAliases(root, { platform: 'web' });
+    const usage = result.usages.find((u) => u.property === 'background');
+    expect(usage.classification).toBe('direct');
+  });
+
+  it('classifies a call site through a conformant consumer alias as aliased', () => {
+    const root = fixture({
+      'src/app.css': `
+        :root { --app-primary: var(--stk-surface-brand-1-default); }
+        .btn { background: var(--app-primary); }
+      `,
+    });
+    const result = resolveTokenAliases(root, { platform: 'web' });
+    const usage = result.usages.find((u) => u.property === 'background');
+    expect(usage.classification).toBe('aliased');
+  });
+
+  it('classifies a call site through a drifted consumer alias as drift, not aliased', () => {
+    const root = fixture({
+      'src/app.css': `
+        :root { --app-primary: #1956dd; }
+        .btn { background: var(--app-primary); }
+      `,
+    });
+    const result = resolveTokenAliases(root, { platform: 'web' });
+    const usage = result.usages.find((u) => u.property === 'background');
+    expect(usage.classification).toBe('drift');
+  });
+
+  it('classifies a call site whose scope cannot be bound as unresolved', () => {
+    const root = fixture({
+      'src/app.css': `
+        :root { --app-primary: var(--stk-surface-brand-1-default); }
+        .theme-promo { --app-primary: #ff00ff; }
+        .btn { background: var(--app-primary); }
+      `,
+    });
+    const result = resolveTokenAliases(root, { platform: 'web' });
+    const usage = result.usages.find((u) => u.property === 'background');
+    expect(usage.classification).toBe('unresolved');
+    expect(usage.reason).toBe('ambiguous-scope');
+  });
+
+  it('reports the three-number summary with direct + aliased as conformancePct', () => {
+    const root = fixture({
+      'src/app.css': `
+        :root { --app-primary: var(--stk-surface-brand-1-default); }
+        .a { background: var(--stk-surface-brand-1-default); }
+        .b { background: var(--app-primary); }
+        .c { background: #1956dd; }
+      `,
+    });
+    const result = resolveTokenAliases(root, { platform: 'web' });
+    expect(result.report.direct).toBe(1);
+    expect(result.report.aliased).toBe(1);
+    expect(result.report.total).toBe(2); // the raw literal in .c has no var() at all — not a usage site
+    expect(result.report.conformancePct).toBe(100);
+  });
+});
+
+describe('resolveTokenAliases — --stk-* declarations are never treated as consumer aliases', () => {
+  it('does not flag a synced copy of the design system\'s own tokens.css as layer violations or drift', () => {
+    const root = fixture({
+      // Mirrors apps/storybook/src/tokens/ — a checked-in copy of Stark's own
+      // compiled CSS, which legitimately aliases semantic --stk-* names
+      // straight to primitive --stk-* names. This is Stark's own internal
+      // aliasing, not something a consumer wrote, and must not appear in the
+      // consumer alias graph at all.
+      'src/tokens/tokens.css': `
+        :root {
+          --stk-surface-brand-1-subtlest: var(--stk-color-shade-palette-1-1);
+          --stk-spacing-md: 16px;
+        }
+      `,
+    });
+    const result = resolveTokenAliases(root, { platform: 'web' });
+    expect(result.properties.find((p) => p.name === '--stk-surface-brand-1-subtlest')).toBeUndefined();
+    expect(result.aliasCount).toBe(0);
+    expect(result.findings).toHaveLength(0);
+  });
+
+  it('still counts a genuine consumer alias declared alongside a synced tokens.css copy', () => {
+    const root = fixture({
+      'src/tokens/tokens.css': `:root { --stk-surface-brand-1-subtlest: var(--stk-color-shade-palette-1-1); }`,
+      'src/app.css': `:root { --app-primary: var(--stk-surface-brand-1-default); }`,
+    });
+    const result = resolveTokenAliases(root, { platform: 'web' });
+    expect(result.aliasCount).toBe(1);
+    expect(property(result, '--app-primary').state).toBe('conformant');
+  });
+});
+
+describe('resolveTokenAliases — alias count', () => {
+  it('counts every distinct consumer-declared custom property, conformant or not', () => {
+    const root = fixture({
+      'src/app.css': `
+        :root {
+          --app-primary: var(--stk-surface-brand-1-default);
+          --app-secondary: #1956dd;
+        }
+      `,
+    });
+    const result = resolveTokenAliases(root, { platform: 'web' });
+    expect(result.aliasCount).toBe(2);
+  });
+});
+
+describe('resolveTokenAliases — platform scope', () => {
+  it('throws for a non-web platform since CSS var() has no RN equivalent', () => {
+    const root = fixture({ 'src/app.css': `:root {}` });
+    expect(() => resolveTokenAliases(root, { platform: 'native' })).toThrow(/web/i);
+  });
+});