@3fn/core 14.0.0 → 15.0.0

package/src/tools/ThemeFileGenerator.ts

@@ -1,109 +0,0 @@
-/**
- * Theme File Generator (Spec 080, Task 6.2)
- *
- * Generates the complete dark theme file skeleton from the live token registry.
- * Every semantic color token gets an entry — populated overrides are exported,
- * unpopulated entries are commented out with their base primitive reference.
- *
- * CI usage: regenerate and diff against existing file to detect:
- * - New tokens added to base (new commented-out entries)
- * - Tokens removed from base (orphaned entries in existing file)
- *
- * @see requirements.md R8 AC1-4
- */
-
-import { getAllSemanticTokens } from '../tokens/semantic';
-import { SemanticCategory } from '../types/SemanticToken';
-import type { SemanticOverrideMap } from '../tokens/themes/types';
-
-/** Derive a section heading from a token name prefix. */
-function sectionHeading(name: string): string {
-  // 'color.feedback.success.text' → 'FEEDBACK — SUCCESS'
-  // 'color.structure.canvas' → 'STRUCTURE'
-  // 'glow.neonPurple' → 'GLOW'
-  const parts = name.startsWith('glow.') ? ['glow'] : name.replace(/^color\./, '').split('.');
-
-  if (parts.length >= 2 && ['feedback', 'progress'].includes(parts[0])) {
-    return `${parts[0].toUpperCase()} — ${parts[1].toUpperCase()}`;
-  }
-  return parts[0].toUpperCase();
-}
-
-/** Format a primitiveReferences object as a readable string. */
-function formatRefs(refs: Record<string, string>): string {
-  const entries = Object.entries(refs);
-  if (entries.length === 1) return `{ ${entries[0][0]}: '${entries[0][1]}' }`;
-  return '{ ' + entries.map(([k, v]) => `${k}: '${v}'`).join(', ') + ' }';
-}
-
-export function generateThemeFile(overrideMap: SemanticOverrideMap): string {
-  const colorTokens = getAllSemanticTokens()
-    .filter(t => t.category === SemanticCategory.COLOR);
-
-  const lines: string[] = [
-    '/**',
-    ' * Dark Theme — Semantic Color Overrides',
-    ' *',
-    ' * AUTO-GENERATED SKELETON — do not edit section structure manually.',
-    ' * To add an override: uncomment the entry, set primitiveReferences to the',
-    ' * dark mode primitive(s), and add to the exported map below.',
-    ' *',
-    ' * @see audit/semantic-color-token-audit.md for classification rationale',
-    ' * @see design.md § "Complete Theme with Fallback"',
-    ' */',
-    '',
-    "import type { SemanticOverrideMap } from '../types';",
-  ];
-
-  // Group tokens by section
-  let currentSection = '';
-  for (const token of colorTokens) {
-    const section = sectionHeading(token.name);
-    if (section !== currentSection) {
-      currentSection = section;
-      lines.push('');
-      lines.push('// ' + '='.repeat(70));
-      lines.push(`// ${section}`);
-      lines.push('// ' + '='.repeat(70));
-    }
-
-    const refs = token.primitiveReferences;
-    const refsStr = formatRefs(refs);
-    lines.push(`// ${token.name}: ${refsStr}`);
-  }
-
-  // Export map with populated overrides
-  lines.push('');
-  lines.push('// ' + '='.repeat(70));
-  lines.push('// EXPORTED OVERRIDE MAP');
-  lines.push('// ' + '='.repeat(70));
-
-  const overrideKeys = Object.keys(overrideMap);
-  if (overrideKeys.length === 0) {
-    lines.push('');
-    lines.push('export const darkSemanticOverrides: SemanticOverrideMap = {};');
-  } else {
-    lines.push('');
-    lines.push('export const darkSemanticOverrides: SemanticOverrideMap = {');
-    for (const key of overrideKeys) {
-      const override = overrideMap[key];
-      const refsStr = formatRefs(override.primitiveReferences);
-      if (override.modifiers !== undefined) {
-        lines.push(`  '${key}': { primitiveReferences: ${refsStr}, modifiers: ${JSON.stringify(override.modifiers)} },`);
-      } else {
-        lines.push(`  '${key}': { primitiveReferences: ${refsStr} },`);
-      }
-    }
-    lines.push('};');
-  }
-
-  lines.push('');
-  return lines.join('\n');
-}
-
-// CLI entry point
-if (require.main === module) {
-  const { darkSemanticOverrides } = require('../tokens/themes/dark/SemanticOverrides');
-  const output = generateThemeFile(darkSemanticOverrides);
-  console.log(output);
-}

package/src/tools/integrity/DiskFreshGenerator.ts

@@ -1,36 +0,0 @@
-/**
- * DiskFreshGenerator — a FreshGenerator that reads fresh artifacts from a
- * directory produced by a prior `generate` run (e.g. an isolated git worktree).
- *
- * Separating "run generate" (worktree lifecycle, done by the audit runner) from
- * "read fresh content" (this adapter) keeps each concern testable. Carries the
- * `generatedVia` / `provisional` flags so the documented-CLI trust gate (P7)
- * propagates honestly: a worktree generated via the ts-node workaround is
- * `provisional: true` until Finding 2 is resolved.
- */
-
-import * as fs from 'fs';
-import * as path from 'path';
-import { FreshGenerator, GeneratedVia } from './types';
-
-export class DiskFreshGenerator implements FreshGenerator {
-  readonly generatedVia: GeneratedVia;
-  readonly provisional: boolean;
-  private readonly root: string;
-
-  constructor(root: string, generatedVia: GeneratedVia, provisional: boolean) {
-    this.root = root;
-    this.generatedVia = generatedVia;
-    this.provisional = provisional;
-  }
-
-  read(relPath: string): string | null {
-    try {
-      return fs.readFileSync(path.resolve(this.root, relPath), 'utf-8');
-    } catch (err) {
-      // Missing fresh artifact is a legitimate divergence; other I/O errors fail loudly.
-      if ((err as NodeJS.ErrnoException).code === 'ENOENT') return null;
-      throw err;
-    }
-  }
-}

package/src/tools/integrity/GenerationIntegrityCheck.ts

@@ -1,132 +0,0 @@
-/**
- * GenerationIntegrityCheck — the core engine (R2; Design "shared machinery").
- *
- * Compares committed artifacts (read from disk) against a fresh generate
- * (supplied by a pluggable FreshGenerator) using semantic equality, and
- * reports divergences for classification. This is the *same* comparison the
- * audit runs first (Phase 1) and the verification runs repeatably (Phase 3) —
- * the fix's guard and the audit are one artifact.
- *
- * Task 1.1 builds this engine with the FreshGenerator injected. The real
- * generator (running `generate` to a scratch tree) lands in Task 1.2; the
- * `provisional` / `generatedVia` flags flow through from whichever generator
- * is supplied, so the documented-CLI trust gate (P7) is honoured, not faked.
- */
-
-import * as fs from 'fs';
-import * as path from 'path';
-import {
-  ArtifactDiff,
-  ArtifactRef,
-  Divergence,
-  FreshGenerator,
-  GenerationIntegrityCheck,
-  IntegrityResult,
-  IntentionalDivergenceManifest,
-} from './types';
-import { Normalizer } from './Normalizer';
-import { SemanticComparator } from './SemanticComparator';
-import { matchesManifest } from './manifest';
-
-export class GenerationIntegrityCheckImpl implements GenerationIntegrityCheck {
-  private readonly fresh: FreshGenerator;
-  private readonly committedRoot: string;
-  private readonly normalizer: Normalizer;
-  private readonly comparator: SemanticComparator;
-
-  constructor(
-    fresh: FreshGenerator,
-    committedRoot: string = process.cwd(),
-    normalizer: Normalizer = new Normalizer(),
-    comparator: SemanticComparator = new SemanticComparator(),
-  ) {
-    this.fresh = fresh;
-    this.committedRoot = committedRoot;
-    this.normalizer = normalizer;
-    this.comparator = comparator;
-  }
-
-  run(opts: {
-    inventory: ArtifactRef[];
-    manifest: IntentionalDivergenceManifest;
-  }): IntegrityResult {
-    const diffs = opts.inventory.map((artifact) => this.diffArtifact(artifact));
-    const allEqual = diffs.every((diff) =>
-      diff.status === 'equal' ||
-      (diff.divergences.length > 0 &&
-        diff.divergences.every((d) => matchesManifest(d, opts.manifest))),
-    );
-    return {
-      diffs,
-      allEqual,
-      provisional: this.fresh.provisional,
-      generatedVia: this.fresh.generatedVia,
-    };
-  }
-
-  private diffArtifact(artifact: ArtifactRef): ArtifactDiff {
-    const committedRaw = this.readCommitted(artifact.path);
-    const freshRaw = this.fresh.read(artifact.path);
-
-    // Both absent: a non-divergence only for optional artifacts (e.g. unconfigured product tokens).
-    if (committedRaw === null && freshRaw === null) {
-      if (artifact.optional) return { artifact, status: 'equal', divergences: [] };
-      return {
-        artifact,
-        status: 'missing-committed',
-        divergences: [presenceDivergence(artifact, null, null)],
-      };
-    }
-    if (committedRaw === null) {
-      return {
-        artifact,
-        status: 'missing-committed',
-        divergences: [presenceDivergence(artifact, null, freshRaw)],
-      };
-    }
-    if (freshRaw === null) {
-      return {
-        artifact,
-        status: 'missing-fresh',
-        divergences: [presenceDivergence(artifact, committedRaw, null)],
-      };
-    }
-
-    const committed = this.normalizer.normalize(committedRaw, artifact.kind);
-    const fresh = this.normalizer.normalize(freshRaw, artifact.kind);
-    const divergences = this.comparator.compare(artifact, committed, fresh);
-    return {
-      artifact,
-      status: divergences.length === 0 ? 'equal' : 'diverged',
-      divergences,
-    };
-  }
-
-  private readCommitted(relPath: string): string | null {
-    const full = path.resolve(this.committedRoot, relPath);
-    try {
-      return fs.readFileSync(full, 'utf-8');
-    } catch (err) {
-      // A missing file is a legitimate divergence (missing-committed). Any other
-      // I/O error is a real problem and must fail loudly, not masquerade as drift.
-      if ((err as NodeJS.ErrnoException).code === 'ENOENT') return null;
-      throw err;
-    }
-  }
-}
-
-/** A file-presence divergence (file-not-found on one or both sides). */
-function presenceDivergence(
-  artifact: ArtifactRef,
-  committed: string | null,
-  fresh: string | null,
-): Divergence {
-  return {
-    id: `${artifact.path}#(file-presence)`,
-    artifactPath: artifact.path,
-    locator: '(file-presence)',
-    committedValue: committed === null ? undefined : '<present>',
-    freshValue: fresh === null ? undefined : '<present>',
-    dimension: artifact.path.includes('components.yaml') ? 'component-presence' : 'other',
-  };
-}

package/src/tools/integrity/Invariants.ts

@@ -1,228 +0,0 @@
-/**
- * Invariants — the absolute correctness-property assertions (Spec 117, Task 5.1).
- *
- * The committed-vs-fresh re-diff (GenerationIntegrityCheck) catches DRIFT — where
- * fresh differs from committed. But two of this spec's correctness properties are
- * *absolute* invariants the re-diff cannot catch, because committed and fresh
- * reproduce each other and the defect (if any) is intrinsic to BOTH sides:
- *
- *   - P3 (no legacy color format): a color primitive carrying rgba() instead of
- *     OKLCH is wrong even when committed == fresh — the re-diff is silent on it.
- *     This is exactly how Finding 1 hid (216 rgba in both committed and fresh).
- *
- *   - P5 (theme-varying rule): the index's `themeVarying` set must be the
- *     dist base-mode set (5 keys), NOT the registry-wide set (10 keys). A future
- *     "simplification" that pipes the registry-wide Set through to the index would
- *     reproduce identically committed-vs-fresh while silently re-breaking R5.
- *     (§4.1 residual risk, Task 3 completion.)
- *
- * These functions parse the token-index YAML and assert the properties directly.
- * They are pure (YAML-string in, result out) so each is unit-tested in isolation.
- *
- * SCOPING (ratified by Peter 2026-06-24, Task 3): P3's "no rgba" is scoped to
- * OKLCH-MIGRATED color primitives. The shadow color family (shadowBlack/Blue/
- * Orange/Gray100) was never migrated to OKLCH by Spec 112 (no channel tokens;
- * dist emits them as rgba too), so the index emitting them as rgba is faithful
- * reproduction of dist, NOT a divergence — and NOT a manifest entry. See
- * .kiro/issues/2026-06-24-oklch-shadow-color-family-not-migrated.md.
- */
-
-import * as yaml from 'js-yaml';
-
-/** The shadow color family — the only color primitives allowed to carry rgba (see header). */
-export const SHADOW_COLOR_PRIMITIVES = [
-  'shadowBlack100',
-  'shadowBlue100',
-  'shadowOrange100',
-  'shadowGray100',
-] as const;
-
-/**
- * The base-scoped theme-varying set the INDEX must mark `themeVarying: true`
- * (the 5 dist base-mode dark-override keys). This is the readout the index uses;
- * it is deliberately NOT the registry-wide 10 (which over-includes WCAG-only
- * contrast keys). See Task 3 completion §"Why two theme-varying sets coexist".
- */
-export const EXPECTED_BASE_THEME_VARYING = [
-  'color.action.navigation',
-  'color.background.primary.subtle',
-  'color.icon.navigation.inactive',
-  'color.structure.border.subtle',
-  'color.structure.canvas',
-] as const;
-
-/**
- * Sentinel WCAG-only over-marks: keys that the registry-wide set (10) marks but
- * the base-scoped set (5) must NOT. If any of these is `themeVarying: true`, the
- * index has been silently re-wired to the registry-wide Set — the §4.1 regression.
- * (This is the anti-conflation guard's negative assertion.)
- */
-export const WCAG_ONLY_OVERMARKS = [
-  'color.action.primary',
-  'color.contrast.onAction',
-  'color.feedback.info.text',
-  'color.feedback.info.background',
-  'color.feedback.info.border',
-] as const;
-
-export interface InvariantViolation {
-  invariant: 'P3-no-rgba' | 'P5-theme-varying-base-scoped' | 'P5-anti-conflation';
-  locator: string;
-  detail: string;
-}
-
-interface PrimitiveEntry {
-  family?: string;
-  value?: unknown;
-}
-
-interface SemanticEntry {
-  themeVarying?: boolean;
-}
-
-function tokensOf(rawYaml: string): Record<string, unknown> {
-  const doc = yaml.load(rawYaml) as { tokens?: Record<string, unknown> } | undefined;
-  const tokens = doc?.tokens;
-  if (!tokens || typeof tokens !== 'object') {
-    throw new Error('Invariants: token-index YAML has no `tokens` map');
-  }
-  return tokens;
-}
-
-function containsRgba(value: unknown): boolean {
-  return JSON.stringify(value ?? null).includes('rgba(');
-}
-
-function containsOklch(value: unknown): boolean {
-  return JSON.stringify(value ?? null).includes('oklch(');
-}
-
-/**
- * P3 — no legacy color format among OKLCH-migrated primitives.
- *
- * Asserts: the set of color primitives carrying `rgba(` equals EXACTLY the
- * shadow family. Any OTHER color primitive carrying rgba is a P3 violation
- * (an un-migrated legacy value); a shadow primitive that has SOMEHOW gained
- * oklch (i.e. the migration moved without this assertion knowing) is reported
- * so the allowlist is re-examined rather than silently widening.
- */
-export function assertNoLegacyColorFormat(primitivesYaml: string): InvariantViolation[] {
-  const tokens = tokensOf(primitivesYaml);
-  const violations: InvariantViolation[] = [];
-  const allowed = new Set<string>(SHADOW_COLOR_PRIMITIVES);
-
-  for (const [name, raw] of Object.entries(tokens)) {
-    const entry = raw as PrimitiveEntry;
-    if (entry.family !== 'color') continue;
-    const hasRgba = containsRgba(entry.value);
-    if (hasRgba && !allowed.has(name)) {
-      violations.push({
-        invariant: 'P3-no-rgba',
-        locator: name,
-        detail: `OKLCH-migrated color primitive carries legacy rgba(): ${JSON.stringify(entry.value)}`,
-      });
-    }
-    // Defensive: a shadow primitive that gained oklch means the shadow family was
-    // migrated — the allowlist should then shrink. Surface it, don't silently pass.
-    if (allowed.has(name) && containsOklch(entry.value)) {
-      violations.push({
-        invariant: 'P3-no-rgba',
-        locator: name,
-        detail:
-          `Shadow-family primitive now carries oklch() — the shadow OKLCH migration may ` +
-          `have landed; revisit the SHADOW_COLOR_PRIMITIVES allowlist and the linked issue.`,
-      });
-    }
-  }
-  return violations;
-}
-
-/** Names of color primitives currently carrying rgba (diagnostic helper for the runner). */
-export function rgbaColorPrimitives(primitivesYaml: string): string[] {
-  const tokens = tokensOf(primitivesYaml);
-  return Object.entries(tokens)
-    .filter(([, raw]) => (raw as PrimitiveEntry).family === 'color' && containsRgba((raw as PrimitiveEntry).value))
-    .map(([name]) => name)
-    .sort();
-}
-
-/**
- * P5 — theme-varying is the base-scoped set, NOT the registry-wide set.
- *
- * Two assertions (both must hold):
- *   (a) the index's `themeVarying: true` set equals EXACTLY the expected 5 base keys
- *       (a missing or extra key is a divergence from the dist base-mode set); and
- *   (b) NONE of the known WCAG-only over-marks is `themeVarying: true` — the
- *       anti-conflation guard. (b) is redundant with (a) when (a) holds, but it
- *       is the explicit, named regression sentinel: if a future change pipes the
- *       registry-wide 10 through to the index, (b) names exactly which over-marks
- *       reappeared, making the §4.1 re-break legible rather than a generic "extra key".
- */
-export function assertThemeVaryingBaseScoped(semanticsYaml: string): InvariantViolation[] {
-  const tokens = tokensOf(semanticsYaml);
-  const violations: InvariantViolation[] = [];
-
-  const actualTrue = new Set(
-    Object.entries(tokens)
-      .filter(([, raw]) => (raw as SemanticEntry).themeVarying === true)
-      .map(([name]) => name),
-  );
-  const expected = new Set<string>(EXPECTED_BASE_THEME_VARYING);
-
-  // (a) exact-set equality with the base-scoped 5.
-  for (const key of expected) {
-    if (!actualTrue.has(key)) {
-      violations.push({
-        invariant: 'P5-theme-varying-base-scoped',
-        locator: key,
-        detail: `Expected base theme-varying key is NOT marked themeVarying: true (under-marked).`,
-      });
-    }
-  }
-  for (const key of actualTrue) {
-    if (!expected.has(key)) {
-      violations.push({
-        invariant: 'P5-theme-varying-base-scoped',
-        locator: key,
-        detail:
-          `Unexpected key marked themeVarying: true — not in the dist base-mode set. ` +
-          `If this is the registry-wide set leaking in, R5 has re-broken (§4.1).`,
-      });
-    }
-  }
-
-  // (b) anti-conflation sentinel — name the specific WCAG-only over-marks.
-  for (const key of WCAG_ONLY_OVERMARKS) {
-    if (actualTrue.has(key)) {
-      violations.push({
-        invariant: 'P5-anti-conflation',
-        locator: key,
-        detail:
-          `WCAG-only over-mark is themeVarying: true — the index appears wired to the ` +
-          `registry-wide Set (10), not the base-scoped Set (5). This is the §4.1 R5 regression.`,
-      });
-    }
-  }
-
-  return violations;
-}
-
-/** The base-scoped theme-varying keys actually marked `true` (diagnostic helper). */
-export function themeVaryingTrueKeys(semanticsYaml: string): string[] {
-  const tokens = tokensOf(semanticsYaml);
-  return Object.entries(tokens)
-    .filter(([, raw]) => (raw as SemanticEntry).themeVarying === true)
-    .map(([name]) => name)
-    .sort();
-}
-
-/** Run all token-index invariants; aggregate violations. Empty array = all hold. */
-export function assertTokenIndexInvariants(opts: {
-  primitivesYaml: string;
-  semanticsYaml: string;
-}): InvariantViolation[] {
-  return [
-    ...assertNoLegacyColorFormat(opts.primitivesYaml),
-    ...assertThemeVaryingBaseScoped(opts.semanticsYaml),
-  ];
-}

package/src/tools/integrity/Normalizer.ts

@@ -1,94 +0,0 @@
-/**
- * Normalizer — the semantic-equality pass (Design Decision D1; R2 AC2).
- *
- * Byte comparison is rejected: generated artifacts embed volatile fields
- * (ISO timestamps, `lastIndexTime`) and harmless ordering/formatting that
- * would produce constant false drift. The Normalizer transforms each side
- * into a canonical comparable form *before* comparison:
- *
- *   - yaml / json  → parsed structure with volatile keys/timestamp values stripped
- *                    (object comparison is key-order independent downstream).
- *   - css / swift / kotlin → text with generated-header timestamp lines removed
- *                    and trailing whitespace / line endings normalized.
- *
- * The rule set is intentionally small here; the complete set is finalized
- * during R2 harness completion (Task 5.1, Open Item 4). Rules are data-driven
- * and individually unit-tested (Testing Strategy: "a changed timestamp is
- * ignored; a changed value is not").
- */
-
-import * as yaml from 'js-yaml';
-import { ArtifactKind, NormalizationRule } from './types';
-
-/** Volatile object keys dropped from structured artifacts regardless of value. */
-const VOLATILE_KEYS = new Set(['lastIndexTime', 'generatedAt', 'generatedOn', 'timestamp']);
-
-/** Full ISO datetime (date + 'T' + time) — the volatile signature in generated headers/fields. */
-const ISO_DATETIME = /\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}/;
-
-export const DEFAULT_NORMALIZATION_RULES: NormalizationRule[] = [
-  {
-    appliesTo: ['yaml', 'json'],
-    description:
-      'Strip volatile keys (lastIndexTime, generatedAt, generatedOn, timestamp) and ISO-datetime-valued fields recursively from parsed structures.',
-    apply: (value) => stripVolatile(value),
-  },
-  {
-    appliesTo: ['css', 'swift', 'kotlin'],
-    description:
-      'Remove generated-header lines carrying an ISO datetime; trim trailing whitespace; normalize line endings.',
-    apply: (value) => normalizeText(value as string),
-  },
-];
-
-export class Normalizer {
-  private readonly rules: NormalizationRule[];
-
-  constructor(rules: NormalizationRule[] = DEFAULT_NORMALIZATION_RULES) {
-    this.rules = rules;
-  }
-
-  /** Parse + normalize raw artifact content into a canonical comparable form. */
-  normalize(raw: string, kind: ArtifactKind): unknown {
-    let value: unknown = this.parse(raw, kind);
-    for (const rule of this.rules) {
-      if (rule.appliesTo === 'all' || rule.appliesTo.includes(kind)) {
-        value = rule.apply(value, kind);
-      }
-    }
-    return value;
-  }
-
-  private parse(raw: string, kind: ArtifactKind): unknown {
-    if (kind === 'yaml') return yaml.load(raw);
-    if (kind === 'json') return JSON.parse(raw);
-    return raw; // text kinds are normalized as strings
-  }
-}
-
-/** Recursively drop volatile keys and ISO-datetime-valued fields from a parsed structure. */
-function stripVolatile(value: unknown): unknown {
-  if (Array.isArray(value)) {
-    return value.map(stripVolatile);
-  }
-  if (value !== null && typeof value === 'object') {
-    const out: Record<string, unknown> = {};
-    for (const [key, child] of Object.entries(value as Record<string, unknown>)) {
-      if (VOLATILE_KEYS.has(key)) continue;
-      if (typeof child === 'string' && ISO_DATETIME.test(child)) continue;
-      out[key] = stripVolatile(child);
-    }
-    return out;
-  }
-  return value;
-}
-
-/** Drop generated-header timestamp lines; trim trailing whitespace; collapse to a single trailing newline. */
-function normalizeText(raw: string): string {
-  return raw
-    .split(/\r?\n/)
-    .filter((line) => !ISO_DATETIME.test(line))
-    .map((line) => line.replace(/\s+$/, ''))
-    .join('\n')
-    .replace(/\n+$/, '\n');
-}