@3fn/core 14.0.0 → 15.0.0

package/src/tools/integrity/SemanticComparator.ts

@@ -1,127 +0,0 @@
-/**
- * SemanticComparator — compares two *normalized* artifacts and reports divergences.
- *
- * Structured (yaml/json): recursive deep-diff. Object comparison is key-order
- * independent (keys compared by name, not position). A key present on only one
- * side emits a single divergence for the whole missing value (not one per leaf),
- * which is exactly how an emptied `components.yaml` surfaces.
- *
- * Text (css/swift/kotlin): positional line diff. Generated output is
- * deterministic and not reordered, so line-by-line positional comparison
- * correctly localizes drift without an external diff dependency.
- *
- * Dimension tagging here is a coarse triage hint; the authoritative provenance
- * bucketing is the DivergenceClassifier's job (Task 1.2).
- */
-
-import { ArtifactRef, Divergence, DivergenceDimension } from './types';
-
-export class SemanticComparator {
-  /** Compare normalized committed vs. fresh for one artifact. */
-  compare(artifact: ArtifactRef, committed: unknown, fresh: unknown): Divergence[] {
-    const out: Divergence[] = [];
-    if (isTextKind(artifact)) {
-      this.compareText(artifact.path, asString(committed), asString(fresh), out);
-    } else {
-      this.deepDiff(artifact.path, '', committed, fresh, out);
-    }
-    return out;
-  }
-
-  private deepDiff(
-    artifactPath: string,
-    locator: string,
-    committed: unknown,
-    fresh: unknown,
-    out: Divergence[],
-  ): void {
-    if (Object.is(committed, fresh)) return;
-
-    // One side missing the whole value → a single divergence for the subtree.
-    if (committed === undefined || fresh === undefined) {
-      this.emit(out, artifactPath, locator || '(root)', committed, fresh);
-      return;
-    }
-
-    if (Array.isArray(committed) && Array.isArray(fresh)) {
-      const max = Math.max(committed.length, fresh.length);
-      for (let i = 0; i < max; i++) {
-        this.deepDiff(artifactPath, `${locator}[${i}]`, committed[i], fresh[i], out);
-      }
-      return;
-    }
-
-    if (isPlainObject(committed) && isPlainObject(fresh)) {
-      const keys = new Set([...Object.keys(committed), ...Object.keys(fresh)]);
-      for (const key of keys) {
-        const child = locator ? `${locator}.${key}` : key;
-        this.deepDiff(artifactPath, child, committed[key], fresh[key], out);
-      }
-      return;
-    }
-
-    // Differing primitives, or a type mismatch (object vs primitive).
-    this.emit(out, artifactPath, locator || '(root)', committed, fresh);
-  }
-
-  private compareText(artifactPath: string, committed: string, fresh: string, out: Divergence[]): void {
-    if (committed === fresh) return;
-    const a = committed.split('\n');
-    const b = fresh.split('\n');
-    const max = Math.max(a.length, b.length);
-    for (let i = 0; i < max; i++) {
-      if (a[i] !== b[i]) {
-        this.emit(out, artifactPath, `line ${i + 1}`, a[i], b[i]);
-      }
-    }
-  }
-
-  private emit(
-    out: Divergence[],
-    artifactPath: string,
-    locator: string,
-    committedValue: unknown,
-    freshValue: unknown,
-  ): void {
-    out.push({
-      id: `${artifactPath}#${locator}`,
-      artifactPath,
-      locator,
-      committedValue,
-      freshValue,
-      dimension: classifyDimension(artifactPath, locator, committedValue, freshValue),
-    });
-  }
-}
-
-function classifyDimension(
-  artifactPath: string,
-  locator: string,
-  committed: unknown,
-  fresh: unknown,
-): DivergenceDimension {
-  const blob = `${asString(committed)}\u0000${asString(fresh)}`;
-  if (locator.includes('value') && /rgba\(|oklch\(/.test(blob)) return 'color-format';
-  if (artifactPath.includes('components.yaml') && (committed === undefined || fresh === undefined)) {
-    return 'component-presence';
-  }
-  if (/themeVarying/i.test(locator)) return 'theme-varying';
-  return 'other';
-}
-
-function isTextKind(artifact: ArtifactRef): boolean {
-  return artifact.kind === 'css' || artifact.kind === 'swift' || artifact.kind === 'kotlin';
-}
-
-function isPlainObject(value: unknown): value is Record<string, unknown> {
-  return value !== null && typeof value === 'object' && !Array.isArray(value);
-}
-
-function asString(value: unknown): string {
-  if (typeof value === 'string') return value;
-  if (value === undefined) return '';
-  // Inputs are parsed YAML/JSON (objects, arrays, primitives) — always
-  // serializable, never circular. If that invariant ever breaks, JSON.stringify
-  // throws and we want to know, not silently degrade.
-  return JSON.stringify(value);
-}

package/src/tools/integrity/__tests__/GenerationIntegrityCheck.test.ts

@@ -1,132 +0,0 @@
-import * as fs from 'fs';
-import * as os from 'os';
-import * as path from 'path';
-import { GenerationIntegrityCheckImpl } from '../GenerationIntegrityCheck';
-import { ArtifactRef, FreshGenerator, IntentionalDivergenceManifest } from '../types';
-import { EMPTY_MANIFEST } from '../manifest';
-
-function makeFresh(
-  files: Record<string, string | null>,
-  opts?: Partial<Pick<FreshGenerator, 'generatedVia' | 'provisional'>>,
-): FreshGenerator {
-  return {
-    generatedVia: opts?.generatedVia ?? 'ts-node-workaround',
-    provisional: opts?.provisional ?? true,
-    read: (p) => (p in files ? files[p] : null),
-  };
-}
-
-describe('GenerationIntegrityCheckImpl', () => {
-  let root: string;
-
-  beforeEach(() => {
-    root = fs.mkdtempSync(path.join(os.tmpdir(), 'integrity-'));
-  });
-
-  afterEach(() => {
-    fs.rmSync(root, { recursive: true, force: true });
-  });
-
-  function writeCommitted(rel: string, content: string): void {
-    const full = path.join(root, rel);
-    fs.mkdirSync(path.dirname(full), { recursive: true });
-    fs.writeFileSync(full, content);
-  }
-
-  const ref = (p: string, kind: ArtifactRef['kind'], optional = false): ArtifactRef => ({ path: p, kind, optional });
-
-  it('reports allEqual when committed and fresh are semantically equal, and flows provisional/generatedVia through', () => {
-    writeCommitted('token-index/primitives.yaml', 'tokens:\n  space100:\n    value: 8\n');
-    const fresh = makeFresh({ 'token-index/primitives.yaml': 'tokens:\n  space100:\n    value: 8\n' });
-    const result = new GenerationIntegrityCheckImpl(fresh, root).run({
-      inventory: [ref('token-index/primitives.yaml', 'yaml')],
-      manifest: EMPTY_MANIFEST,
-    });
-    expect(result.allEqual).toBe(true);
-    expect(result.diffs[0].status).toBe('equal');
-    expect(result.provisional).toBe(true);
-    expect(result.generatedVia).toBe('ts-node-workaround');
-  });
-
-  it('reports diverged when a value changes', () => {
-    writeCommitted('token-index/primitives.yaml', 'tokens:\n  space100:\n    value: 8\n');
-    const fresh = makeFresh({ 'token-index/primitives.yaml': 'tokens:\n  space100:\n    value: 9\n' });
-    const result = new GenerationIntegrityCheckImpl(fresh, root).run({
-      inventory: [ref('token-index/primitives.yaml', 'yaml')],
-      manifest: EMPTY_MANIFEST,
-    });
-    expect(result.allEqual).toBe(false);
-    expect(result.diffs[0].status).toBe('diverged');
-    expect(result.diffs[0].divergences[0].locator).toBe('tokens.space100.value');
-  });
-
-  it('surfaces an emptied components.yaml as a component-presence divergence (the R4 drift)', () => {
-    writeCommitted('token-index/components.yaml', 'tokens:\n  buttonicon.size.small:\n    component: ButtonIcon\n');
-    const fresh = makeFresh({ 'token-index/components.yaml': 'tokens: {}\n' });
-    const result = new GenerationIntegrityCheckImpl(fresh, root).run({
-      inventory: [ref('token-index/components.yaml', 'yaml')],
-      manifest: EMPTY_MANIFEST,
-    });
-    expect(result.allEqual).toBe(false);
-    const div = result.diffs[0].divergences[0];
-    expect(div.dimension).toBe('component-presence');
-    expect(div.freshValue).toBeUndefined();
-  });
-
-  it('treats an allowlisted divergence as equal-enough but still records it as diverged', () => {
-    writeCommitted('token-index/primitives.yaml', 'tokens:\n  space100:\n    value: 8\n');
-    const fresh = makeFresh({ 'token-index/primitives.yaml': 'tokens:\n  space100:\n    value: 9\n' });
-    const manifest: IntentionalDivergenceManifest = {
-      version: '1.0.0',
-      entries: [
-        {
-          matcher: 'token-index/primitives.yaml#tokens.space100.value',
-          reason: 'test fixture',
-          approvedBy: 'test',
-          date: '2026-06-13',
-        },
-      ],
-    };
-    const result = new GenerationIntegrityCheckImpl(fresh, root).run({
-      inventory: [ref('token-index/primitives.yaml', 'yaml')],
-      manifest,
-    });
-    expect(result.allEqual).toBe(true);
-    expect(result.diffs[0].status).toBe('diverged');
-  });
-
-  it('flags a missing-fresh artifact', () => {
-    writeCommitted('dist/DesignTokens.web.css', ':root { --x: 1; }\n');
-    const fresh = makeFresh({ 'dist/DesignTokens.web.css': null });
-    const result = new GenerationIntegrityCheckImpl(fresh, root).run({
-      inventory: [ref('dist/DesignTokens.web.css', 'css')],
-      manifest: EMPTY_MANIFEST,
-    });
-    expect(result.diffs[0].status).toBe('missing-fresh');
-    expect(result.allEqual).toBe(false);
-  });
-
-  it('fails loudly on a non-ENOENT read error instead of masking it as drift', () => {
-    // A directory at the artifact path triggers EISDIR on read — a real I/O error
-    // that must propagate, not be swallowed into a missing/divergence result.
-    const rel = 'token-index/primitives.yaml';
-    fs.mkdirSync(path.join(root, rel), { recursive: true });
-    const fresh = makeFresh({ [rel]: 'tokens: {}\n' });
-    expect(() =>
-      new GenerationIntegrityCheckImpl(fresh, root).run({
-        inventory: [ref(rel, 'yaml')],
-        manifest: EMPTY_MANIFEST,
-      }),
-    ).toThrow();
-  });
-
-  it('treats an unconfigured optional artifact (absent on both sides) as equal', () => {
-    const fresh = makeFresh({ 'dist/product/ProductTokens.web.css': null });
-    const result = new GenerationIntegrityCheckImpl(fresh, root).run({
-      inventory: [ref('dist/product/ProductTokens.web.css', 'css', true)],
-      manifest: EMPTY_MANIFEST,
-    });
-    expect(result.diffs[0].status).toBe('equal');
-    expect(result.allEqual).toBe(true);
-  });
-});

package/src/tools/integrity/__tests__/Invariants.test.ts

@@ -1,142 +0,0 @@
-/**
- * @category evergreen
- * @purpose Spec 117 Task 5.1 — absolute correctness-property invariants (P3 no-rgba scoped to
- *          OKLCH-migrated primitives; P5 theme-varying base-scoped + anti-conflation guard).
- *
- * These assert the invariants the committed-vs-fresh re-diff CANNOT catch (defects intrinsic to
- * both sides). Each test pairs a positive case (corrected artifact passes) with a negative case
- * (a regression is caught and named) — "a changed timestamp is ignored; a changed value is not"
- * applied to invariants: a legacy rgba / a registry-wide leak must NOT pass.
- */
-
-import * as fs from 'fs';
-import * as path from 'path';
-import {
-  assertNoLegacyColorFormat,
-  assertThemeVaryingBaseScoped,
-  assertTokenIndexInvariants,
-  rgbaColorPrimitives,
-  themeVaryingTrueKeys,
-  EXPECTED_BASE_THEME_VARYING,
-  SHADOW_COLOR_PRIMITIVES,
-} from '../Invariants';
-
-const REPO_ROOT = path.resolve(__dirname, '../../../..');
-const PRIMITIVES = path.join(REPO_ROOT, 'token-index/primitives.yaml');
-const SEMANTICS = path.join(REPO_ROOT, 'token-index/semantics.yaml');
-
-const readPrimitives = () => fs.readFileSync(PRIMITIVES, 'utf-8');
-const readSemantics = () => fs.readFileSync(SEMANTICS, 'utf-8');
-
-describe('Invariants — P3 no-rgba scoped to OKLCH-migrated primitives', () => {
-  it('passes on the committed primitives.yaml (only the shadow family carries rgba)', () => {
-    expect(assertNoLegacyColorFormat(readPrimitives())).toEqual([]);
-  });
-
-  it('confirms the rgba-bearing color primitives are EXACTLY the shadow family', () => {
-    expect(rgbaColorPrimitives(readPrimitives()).sort()).toEqual([...SHADOW_COLOR_PRIMITIVES].sort());
-  });
-
-  it('catches a non-shadow OKLCH-migrated primitive that regressed to legacy rgba', () => {
-    const yaml = [
-      'tokens:',
-      '  gray100:',
-      '    family: color',
-      '    value:',
-      '      light:',
-      '        base: rgba(255, 255, 255, 1)', // a legacy regression — gray100 must be oklch
-      '      dark:',
-      '        base: oklch(0.2 0 0)',
-    ].join('\n');
-    const violations = assertNoLegacyColorFormat(yaml);
-    expect(violations).toHaveLength(1);
-    expect(violations[0].invariant).toBe('P3-no-rgba');
-    expect(violations[0].locator).toBe('gray100');
-  });
-
-  it('does NOT flag the shadow family for carrying rgba (the ratified scope)', () => {
-    const yaml = [
-      'tokens:',
-      '  shadowBlack100:',
-      '    family: color',
-      '    value:',
-      '      light:',
-      '        base: rgba(0, 0, 0, 1)',
-    ].join('\n');
-    expect(assertNoLegacyColorFormat(yaml)).toEqual([]);
-  });
-
-  it('surfaces (does not silently pass) a shadow primitive that gained oklch — allowlist must be revisited', () => {
-    const yaml = [
-      'tokens:',
-      '  shadowBlack100:',
-      '    family: color',
-      '    value:',
-      '      light:',
-      '        base: oklch(0 0 0)', // shadow migration landed → allowlist should shrink
-    ].join('\n');
-    const violations = assertNoLegacyColorFormat(yaml);
-    expect(violations).toHaveLength(1);
-    expect(violations[0].locator).toBe('shadowBlack100');
-  });
-
-  it('ignores non-color families even if (hypothetically) they contained an rgba-like string', () => {
-    const yaml = [
-      'tokens:',
-      '  space100:',
-      '    family: spacing',
-      '    value: 8',
-    ].join('\n');
-    expect(assertNoLegacyColorFormat(yaml)).toEqual([]);
-  });
-});
-
-describe('Invariants — P5 theme-varying base-scoped + anti-conflation', () => {
-  it('passes on the committed semantics.yaml (exactly the 5 base keys)', () => {
-    expect(assertThemeVaryingBaseScoped(readSemantics())).toEqual([]);
-  });
-
-  it('confirms the themeVarying:true set equals the expected base-scoped 5', () => {
-    expect(themeVaryingTrueKeys(readSemantics()).sort()).toEqual([...EXPECTED_BASE_THEME_VARYING].sort());
-  });
-
-  it('catches the §4.1 regression: registry-wide WCAG-only over-marks leaking in', () => {
-    // Simulate the index being re-wired to the registry-wide Set (10): the 5 base keys
-    // PLUS the WCAG-only over-marks become themeVarying: true.
-    const lines = ['tokens:'];
-    for (const key of EXPECTED_BASE_THEME_VARYING) {
-      lines.push(`  ${key}:`, `    themeVarying: true`);
-    }
-    // The leak — a WCAG-only over-mark.
-    lines.push('  color.action.primary:', '    themeVarying: true');
-    const violations = assertThemeVaryingBaseScoped(lines.join('\n'));
-    // One "unexpected key" (exact-set) + one named anti-conflation sentinel.
-    const sentinel = violations.find((v) => v.invariant === 'P5-anti-conflation');
-    expect(sentinel).toBeDefined();
-    expect(sentinel!.locator).toBe('color.action.primary');
-  });
-
-  it('catches an under-mark: a base key wrongly flipped to false', () => {
-    const lines = ['tokens:'];
-    // All but one of the base keys marked true.
-    for (const key of EXPECTED_BASE_THEME_VARYING.slice(1)) {
-      lines.push(`  ${key}:`, `    themeVarying: true`);
-    }
-    lines.push(`  ${EXPECTED_BASE_THEME_VARYING[0]}:`, `    themeVarying: false`);
-    const violations = assertThemeVaryingBaseScoped(lines.join('\n'));
-    const underMark = violations.find((v) => v.locator === EXPECTED_BASE_THEME_VARYING[0]);
-    expect(underMark).toBeDefined();
-    expect(underMark!.invariant).toBe('P5-theme-varying-base-scoped');
-  });
-});
-
-describe('Invariants — aggregate over the committed token index', () => {
-  it('all token-index invariants hold on the committed (corrected) artifacts', () => {
-    expect(
-      assertTokenIndexInvariants({
-        primitivesYaml: readPrimitives(),
-        semanticsYaml: readSemantics(),
-      }),
-    ).toEqual([]);
-  });
-});

package/src/tools/integrity/__tests__/Normalizer.test.ts

@@ -1,65 +0,0 @@
-import { Normalizer } from '../Normalizer';
-
-describe('Normalizer — semantic equality (Design D1, R2 AC2)', () => {
-  const n = new Normalizer();
-
-  describe('the core requirement: timestamp ignored, value not', () => {
-    it('ignores a changed volatile timestamp field in structured content', () => {
-      const a = n.normalize('lastIndexTime: 2026-06-13T10:00:00.000Z\ntokens:\n  space100:\n    value: 8\n', 'yaml');
-      const b = n.normalize('lastIndexTime: 2026-06-13T23:59:59.000Z\ntokens:\n  space100:\n    value: 8\n', 'yaml');
-      expect(a).toEqual(b);
-    });
-
-    it('does NOT ignore a changed token value', () => {
-      const a = n.normalize('tokens:\n  space100:\n    value: 8\n', 'yaml');
-      const b = n.normalize('tokens:\n  space100:\n    value: 9\n', 'yaml');
-      expect(a).not.toEqual(b);
-    });
-
-    it('ignores a changed generated-header timestamp line in text artifacts', () => {
-      const a = n.normalize('/* Generated 2026-06-13T10:00:00Z */\n:root { --space-100: 8px; }\n', 'css');
-      const b = n.normalize('/* Generated 2026-06-13T23:59:59Z */\n:root { --space-100: 8px; }\n', 'css');
-      expect(a).toEqual(b);
-    });
-
-    it('does NOT ignore a changed value in text artifacts', () => {
-      const a = n.normalize('/* Generated 2026-06-13T10:00:00Z */\n:root { --space-100: 8px; }\n', 'css');
-      const b = n.normalize('/* Generated 2026-06-13T10:00:00Z */\n:root { --space-100: 9px; }\n', 'css');
-      expect(a).not.toEqual(b);
-    });
-  });
-
-  describe('structured volatile stripping', () => {
-    it('strips volatile keys recursively, regardless of value type', () => {
-      const out = n.normalize('tokens:\n  x:\n    value: 1\n    generatedAt: \'2026-06-13T10:00:00Z\'\n', 'yaml') as {
-        tokens: { x: unknown };
-      };
-      expect(out.tokens.x).toEqual({ value: 1 });
-    });
-
-    it('strips ISO-datetime-valued string fields under any key name', () => {
-      const out = n.normalize("builtOn: '2026-06-13T10:00:00.000Z'\nkeep: hello\n", 'yaml');
-      expect(out).toEqual({ keep: 'hello' });
-    });
-
-    it('preserves a non-timestamp value that merely contains digits', () => {
-      const out = n.normalize('value: 8\nname: space100\n', 'yaml');
-      expect(out).toEqual({ value: 8, name: 'space100' });
-    });
-  });
-
-  describe('JSON parsing', () => {
-    it('parses and strips volatile keys from JSON artifacts', () => {
-      const out = n.normalize('{"generatedAt":"2026-06-13T10:00:00Z","color":{"$value":"#fff"}}', 'json');
-      expect(out).toEqual({ color: { $value: '#fff' } });
-    });
-  });
-
-  describe('text normalization', () => {
-    it('trims trailing whitespace and normalizes CRLF line endings', () => {
-      const a = n.normalize(':root {  \r\n  --x: 1;  \r\n}\r\n', 'css');
-      const b = n.normalize(':root {\n  --x: 1;\n}\n', 'css');
-      expect(a).toEqual(b);
-    });
-  });
-});

package/src/tools/integrity/__tests__/SemanticComparator.test.ts

@@ -1,62 +0,0 @@
-import { SemanticComparator } from '../SemanticComparator';
-import { ArtifactRef } from '../types';
-
-const yamlArtifact = (path = 'token-index/primitives.yaml'): ArtifactRef => ({
-  path,
-  kind: 'yaml',
-  optional: false,
-});
-
-describe('SemanticComparator', () => {
-  const cmp = new SemanticComparator();
-
-  it('reports no divergence for deeply equal structures (key order independent)', () => {
-    const a = { tokens: { space100: { family: 'spacing', value: 8 } } };
-    const b = { tokens: { space100: { value: 8, family: 'spacing' } } }; // reordered keys
-    expect(cmp.compare(yamlArtifact(), a, b)).toEqual([]);
-  });
-
-  it('reports a differing leaf with a precise locator', () => {
-    const a = { tokens: { space100: { value: 8 } } };
-    const b = { tokens: { space100: { value: 9 } } };
-    const divs = cmp.compare(yamlArtifact(), a, b);
-    expect(divs).toHaveLength(1);
-    expect(divs[0].locator).toBe('tokens.space100.value');
-    expect(divs[0].committedValue).toBe(8);
-    expect(divs[0].freshValue).toBe(9);
-  });
-
-  it('reports a missing token subtree as a single component-presence divergence (R4 drift)', () => {
-    const artifact = yamlArtifact('token-index/components.yaml');
-    const a = { tokens: { 'buttonicon.size.small': { component: 'ButtonIcon' } } };
-    const b = { tokens: {} }; // fresh emptied
-    const divs = cmp.compare(artifact, a, b);
-    expect(divs).toHaveLength(1);
-    expect(divs[0].locator).toBe('tokens.buttonicon.size.small');
-    expect(divs[0].freshValue).toBeUndefined();
-    expect(divs[0].dimension).toBe('component-presence');
-  });
-
-  it('tags an rgba→oklch color change as color-format (Finding 1)', () => {
-    const a = { tokens: { gray100: { family: 'color', value: { light: { base: 'rgba(178, 188, 196, 1)' } } } } };
-    const b = { tokens: { gray100: { family: 'color', value: { light: { base: 'oklch(0.78 0.02 260)' } } } } };
-    const divs = cmp.compare(yamlArtifact(), a, b);
-    expect(divs).toHaveLength(1);
-    expect(divs[0].locator).toBe('tokens.gray100.value.light.base');
-    expect(divs[0].dimension).toBe('color-format');
-  });
-
-  it('produces a stable, manifest-matchable id from path and locator', () => {
-    const a = { tokens: { x: { value: 1 } } };
-    const b = { tokens: { x: { value: 2 } } };
-    const divs = cmp.compare(yamlArtifact('token-index/primitives.yaml'), a, b);
-    expect(divs[0].id).toBe('token-index/primitives.yaml#tokens.x.value');
-  });
-
-  it('does a positional line diff for text artifacts', () => {
-    const css: ArtifactRef = { path: 'dist/DesignTokens.web.css', kind: 'css', optional: false };
-    const divs = cmp.compare(css, ':root {\n  --space-100: 8px;\n}', ':root {\n  --space-100: 9px;\n}');
-    expect(divs).toHaveLength(1);
-    expect(divs[0].locator).toBe('line 2');
-  });
-});