@soleri/core 9.0.4 → 9.3.0

package/src/domain-packs/knowledge-installer.test.ts

@@ -0,0 +1,163 @@
+/**
+ * Colocated tests for domain-packs/knowledge-installer.ts
+ *
+ * Tests: three-tier installation, immutable canonical skip, empty knowledge,
+ * missing directories.
+ */
+
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { mkdtempSync, writeFileSync, mkdirSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { installKnowledge } from './knowledge-installer.js';
+import type { DomainPack } from './types.js';
+import type { AgentRuntime } from '../runtime/types.js';
+
+let tempDir: string;
+
+function mockPack(overrides: Partial<DomainPack> = {}): DomainPack {
+  return {
+    name: 'test-pack',
+    version: '1.0.0',
+    domains: ['testing'],
+    ops: [],
+    ...overrides,
+  };
+}
+
+function mockRuntime(): AgentRuntime {
+  const entries = new Map<string, unknown>();
+  return {
+    vault: {
+      get: vi.fn((id: string) => entries.get(id) ?? null),
+      add: vi.fn((entry: Record<string, unknown>) => entries.set(entry.id as string, entry)),
+      search: vi.fn(() => []),
+    },
+  } as unknown;
+}
+
+function writeMdFiles(dir: string, files: Record<string, string>) {
+  mkdirSync(dir, { recursive: true });
+  for (const [name, content] of Object.entries(files)) {
+    writeFileSync(join(dir, name), content, 'utf-8');
+  }
+}
+
+beforeEach(() => {
+  tempDir = mkdtempSync(join(tmpdir(), 'knowledge-test-'));
+});
+
+afterEach(() => {
+  rmSync(tempDir, { recursive: true, force: true });
+});
+
+describe('installKnowledge', () => {
+  it('returns zeros when pack has no knowledge', async () => {
+    const result = await installKnowledge(mockPack(), mockRuntime(), tempDir);
+    expect(result).toEqual({ canonical: 0, curated: 0, captured: 0, skipped: 0 });
+  });
+
+  it('installs canonical entries', async () => {
+    const canonicalDir = join(tempDir, 'canonical');
+    writeMdFiles(canonicalDir, {
+      'no-raw-colors.md': '# No Raw Colors\nAlways use tokens.',
+      'token-priority.md': '# Token Priority\nSemantic first.',
+    });
+    const runtime = mockRuntime();
+    const result = await installKnowledge(
+      mockPack({ knowledge: { canonical: 'canonical' } }),
+      runtime,
+      tempDir,
+    );
+    expect(result.canonical).toBe(2);
+    expect(runtime.vault.add).toHaveBeenCalledTimes(2);
+  });
+
+  it('installs curated entries', async () => {
+    const curatedDir = join(tempDir, 'curated');
+    writeMdFiles(curatedDir, { 'pattern-a.md': 'Pattern A content.' });
+    const runtime = mockRuntime();
+    const result = await installKnowledge(
+      mockPack({ knowledge: { curated: 'curated' } }),
+      runtime,
+      tempDir,
+    );
+    expect(result.curated).toBe(1);
+  });
+
+  it('installs captured entries', async () => {
+    const capturedDir = join(tempDir, 'captured');
+    writeMdFiles(capturedDir, { 'lesson-1.md': 'A lesson.' });
+    const runtime = mockRuntime();
+    const result = await installKnowledge(
+      mockPack({ knowledge: { captured: 'captured' } }),
+      runtime,
+      tempDir,
+    );
+    expect(result.captured).toBe(1);
+  });
+
+  it('skips canonical entries that already exist (immutable)', async () => {
+    const canonicalDir = join(tempDir, 'canonical');
+    writeMdFiles(canonicalDir, { 'existing.md': 'Content.' });
+    const runtime = mockRuntime();
+    // Pre-populate vault with existing entry
+    (runtime.vault.get as unknown).mockImplementation((id: string) =>
+      id === 'pack-test-pack-existing' ? { id } : null,
+    );
+    const result = await installKnowledge(
+      mockPack({ knowledge: { canonical: 'canonical' } }),
+      runtime,
+      tempDir,
+    );
+    expect(result.canonical).toBe(0);
+  });
+
+  it('skips non-existing directories gracefully', async () => {
+    const runtime = mockRuntime();
+    const result = await installKnowledge(
+      mockPack({ knowledge: { canonical: 'no-such-dir', curated: 'also-missing' } }),
+      runtime,
+      tempDir,
+    );
+    expect(result.canonical).toBe(0);
+    expect(result.curated).toBe(0);
+  });
+
+  it('tags entries with pack source and tier', async () => {
+    const canonicalDir = join(tempDir, 'canonical');
+    writeMdFiles(canonicalDir, { 'tagged.md': 'Tagged entry.' });
+    const runtime = mockRuntime();
+    await installKnowledge(mockPack({ knowledge: { canonical: 'canonical' } }), runtime, tempDir);
+    const addCall = (runtime.vault.add as unknown).mock.calls[0][0];
+    expect(addCall.tags).toContain('pack:test-pack');
+    expect(addCall.tags).toContain('tier:canonical');
+    expect(addCall.origin).toBe('pack');
+    expect(addCall.domain).toBe('test-pack');
+  });
+
+  it('generates correct entry id from pack name and filename', async () => {
+    const curatedDir = join(tempDir, 'curated');
+    writeMdFiles(curatedDir, { 'my-pattern.md': 'Content.' });
+    const runtime = mockRuntime();
+    await installKnowledge(mockPack({ knowledge: { curated: 'curated' } }), runtime, tempDir);
+    const addCall = (runtime.vault.add as unknown).mock.calls[0][0];
+    expect(addCall.id).toBe('pack-test-pack-my-pattern');
+  });
+
+  it('installs all three tiers in a single call', async () => {
+    writeMdFiles(join(tempDir, 'c'), { 'a.md': 'A' });
+    writeMdFiles(join(tempDir, 'u'), { 'b.md': 'B' });
+    writeMdFiles(join(tempDir, 'p'), { 'c.md': 'C' });
+    const runtime = mockRuntime();
+    const result = await installKnowledge(
+      mockPack({ knowledge: { canonical: 'c', curated: 'u', captured: 'p' } }),
+      runtime,
+      tempDir,
+    );
+    expect(result.canonical).toBe(1);
+    expect(result.curated).toBe(1);
+    expect(result.captured).toBe(1);
+    expect(runtime.vault.add).toHaveBeenCalledTimes(3);
+  });
+});

package/src/domain-packs/loader.test.ts

@@ -0,0 +1,86 @@
+/**
+ * Colocated tests for domain-packs/loader.ts
+ *
+ * resolveDependencies is covered in __tests__/domain-packs.test.ts.
+ * Here we add edge cases and test loadDomainPack / loadDomainPacksFromConfig.
+ */
+
+import { describe, it, expect } from 'vitest';
+import { resolveDependencies, loadDomainPack, loadDomainPacksFromConfig } from './loader.js';
+import type { DomainPack } from './types.js';
+
+function stub(name: string, overrides: Partial<DomainPack> = {}): DomainPack {
+  return {
+    name,
+    version: '1.0.0',
+    domains: ['test'],
+    ops: [{ name: `${name}_op`, description: 'op', auth: 'read', handler: async () => ({}) }],
+    ...overrides,
+  };
+}
+
+describe('resolveDependencies', () => {
+  it('returns empty array for empty input', () => {
+    expect(resolveDependencies([])).toEqual([]);
+  });
+
+  it('preserves order for independent packs', () => {
+    const a = stub('a');
+    const b = stub('b');
+    const sorted = resolveDependencies([a, b]);
+    expect(sorted.map((p) => p.name)).toEqual(['a', 'b']);
+  });
+
+  it('handles diamond dependency graph', () => {
+    const base = stub('base');
+    const left = stub('left', { requires: ['base'] });
+    const right = stub('right', { requires: ['base'] });
+    const top = stub('top', { requires: ['left', 'right'] });
+    const sorted = resolveDependencies([top, left, right, base]);
+    const names = sorted.map((p) => p.name);
+    expect(names.indexOf('base')).toBeLessThan(names.indexOf('left'));
+    expect(names.indexOf('base')).toBeLessThan(names.indexOf('right'));
+    expect(names.indexOf('left')).toBeLessThan(names.indexOf('top'));
+    expect(names.indexOf('right')).toBeLessThan(names.indexOf('top'));
+  });
+
+  it('handles chain A → B → C', () => {
+    const c = stub('c');
+    const b = stub('b', { requires: ['c'] });
+    const a = stub('a', { requires: ['b'] });
+    const sorted = resolveDependencies([a, b, c]);
+    expect(sorted.map((p) => p.name)).toEqual(['c', 'b', 'a']);
+  });
+
+  it('throws on self-dependency (circular)', () => {
+    const self = stub('self', { requires: ['self'] });
+    expect(() => resolveDependencies([self])).toThrow(/circular/i);
+  });
+
+  it('throws with names of packs in the cycle', () => {
+    const a = stub('alpha', { requires: ['beta'] });
+    const b = stub('beta', { requires: ['alpha'] });
+    expect(() => resolveDependencies([a, b])).toThrow('alpha');
+  });
+});
+
+describe('loadDomainPack', () => {
+  it('throws on non-existent package', async () => {
+    await expect(loadDomainPack('@soleri/nonexistent-pack-xyz')).rejects.toThrow(
+      /Failed to import domain pack/,
+    );
+  });
+
+  it('throws when module fails validation (no valid pack shape)', async () => {
+    // node:path has a default export but it's not a valid DomainPack
+    await expect(loadDomainPack('node:path')).rejects.toThrow(/failed validation/);
+  });
+});
+
+describe('loadDomainPacksFromConfig', () => {
+  it('throws when any pack ref fails to load', async () => {
+    await expect(
+      loadDomainPacksFromConfig([{ name: 'bad', package: '@soleri/nonexistent-xyz' }]),
+    ).rejects.toThrow(/Failed to import/);
+  });
+});

package/src/domain-packs/pack-runtime.test.ts

@@ -0,0 +1,140 @@
+/**
+ * Colocated tests for domain-packs/pack-runtime.ts
+ *
+ * Tests createPackRuntime adapter: vault proxy, project registry proxy,
+ * session store proxy with graceful degradation.
+ */
+
+import { describe, it, expect, vi } from 'vitest';
+import { createPackRuntime } from './pack-runtime.js';
+import type { PackProjectContext, PackCheckContext } from './pack-runtime.js';
+
+function mockVault() {
+  return { search: vi.fn(), get: vi.fn(), add: vi.fn() } as unknown;
+}
+
+function mockRegistry(projects: PackProjectContext[] = []) {
+  return {
+    get: vi.fn((id: string) => projects.find((p) => p.id === id) ?? null),
+    list: vi.fn(() => projects.map((p) => ({ id: p.id, name: p.name, path: p.path }))),
+  };
+}
+
+function mockSessionStore() {
+  const checks = new Map<string, PackCheckContext>();
+  return {
+    createCheck: vi.fn((type: string, data: Record<string, unknown>) => {
+      const id = `check-${Date.now()}`;
+      checks.set(id, { id, type, data, timestamp: Date.now() });
+      return id;
+    }),
+    validateCheck: vi.fn((id: string, type: string) => {
+      const c = checks.get(id);
+      return c && c.type === type ? c : null;
+    }),
+    validateAndConsume: vi.fn((id: string, type: string) => {
+      const c = checks.get(id);
+      if (c && c.type === type) {
+        checks.delete(id);
+        return c;
+      }
+      return null;
+    }),
+  };
+}
+
+describe('createPackRuntime', () => {
+  it('exposes vault from the runtime', () => {
+    const vault = mockVault();
+    const pr = createPackRuntime({ vault, projectRegistry: mockRegistry() });
+    expect(pr.vault).toBe(vault);
+  });
+
+  it('getProject returns project by id', () => {
+    const project: PackProjectContext = { id: 'p1', name: 'Test', path: '/test' };
+    const pr = createPackRuntime({ vault: mockVault(), projectRegistry: mockRegistry([project]) });
+    expect(pr.getProject('p1')).toEqual(project);
+  });
+
+  it('getProject returns undefined for unknown id', () => {
+    const pr = createPackRuntime({ vault: mockVault(), projectRegistry: mockRegistry() });
+    expect(pr.getProject('unknown')).toBeUndefined();
+  });
+
+  it('listProjects returns all registered projects', () => {
+    const projects: PackProjectContext[] = [
+      { id: 'a', name: 'A', path: '/a' },
+      { id: 'b', path: '/b' },
+    ];
+    const pr = createPackRuntime({ vault: mockVault(), projectRegistry: mockRegistry(projects) });
+    const list = pr.listProjects();
+    expect(list).toHaveLength(2);
+    expect(list[0].id).toBe('a');
+    expect(list[1].id).toBe('b');
+  });
+
+  it('createCheck delegates to session store', () => {
+    const store = mockSessionStore();
+    const pr = createPackRuntime({
+      vault: mockVault(),
+      projectRegistry: mockRegistry(),
+      sessionStore: store,
+    });
+    const id = pr.createCheck('contrast', { ratio: 4.5 });
+    expect(typeof id).toBe('string');
+    expect(store.createCheck).toHaveBeenCalledWith('contrast', { ratio: 4.5 });
+  });
+
+  it('createCheck throws when session store is unavailable', () => {
+    const pr = createPackRuntime({ vault: mockVault(), projectRegistry: mockRegistry() });
+    expect(() => pr.createCheck('test', {})).toThrow(/Session store not available/);
+  });
+
+  it('validateCheck returns null when session store is unavailable', () => {
+    const pr = createPackRuntime({ vault: mockVault(), projectRegistry: mockRegistry() });
+    expect(pr.validateCheck('id', 'type')).toBeNull();
+  });
+
+  it('validateAndConsume returns null when session store is unavailable', () => {
+    const pr = createPackRuntime({ vault: mockVault(), projectRegistry: mockRegistry() });
+    expect(pr.validateAndConsume('id', 'type')).toBeNull();
+  });
+
+  it('validateCheck delegates to session store', () => {
+    const store = mockSessionStore();
+    const pr = createPackRuntime({
+      vault: mockVault(),
+      projectRegistry: mockRegistry(),
+      sessionStore: store,
+    });
+    const id = pr.createCheck('contrast', { ratio: 4.5 });
+    const result = pr.validateCheck(id, 'contrast');
+    expect(result).not.toBeNull();
+    expect(result!.type).toBe('contrast');
+  });
+
+  it('validateCheck returns null for wrong type', () => {
+    const store = mockSessionStore();
+    const pr = createPackRuntime({
+      vault: mockVault(),
+      projectRegistry: mockRegistry(),
+      sessionStore: store,
+    });
+    const id = pr.createCheck('contrast', {});
+    expect(pr.validateCheck(id, 'wrong-type')).toBeNull();
+  });
+
+  it('validateAndConsume removes the check after use', () => {
+    const store = mockSessionStore();
+    const pr = createPackRuntime({
+      vault: mockVault(),
+      projectRegistry: mockRegistry(),
+      sessionStore: store,
+    });
+    const id = pr.createCheck('contrast', { ratio: 21 });
+    const first = pr.validateAndConsume(id, 'contrast');
+    expect(first).not.toBeNull();
+    const second = pr.validateAndConsume(id, 'contrast');
+    expect(second).toBeNull();
+  });
+});

package/src/domain-packs/skills-installer.test.ts

@@ -0,0 +1,135 @@
+/**
+ * Colocated tests for domain-packs/skills-installer.ts
+ *
+ * Tests: install, skip existing, force overwrite, missing source, empty skills.
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdtempSync, writeFileSync, mkdirSync, readFileSync, existsSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { installSkills } from './skills-installer.js';
+import type { DomainPack } from './types.js';
+
+let tempDir: string;
+let sourceDir: string;
+let targetDir: string;
+
+function mockPack(overrides: Partial<DomainPack> = {}): DomainPack {
+  return {
+    name: 'test-pack',
+    version: '1.0.0',
+    domains: ['testing'],
+    ops: [],
+    ...overrides,
+  };
+}
+
+beforeEach(() => {
+  tempDir = mkdtempSync(join(tmpdir(), 'skills-test-'));
+  sourceDir = join(tempDir, 'pack-root');
+  targetDir = join(tempDir, 'agent-skills');
+  mkdirSync(sourceDir, { recursive: true });
+});
+
+afterEach(() => {
+  rmSync(tempDir, { recursive: true, force: true });
+});
+
+describe('installSkills', () => {
+  it('returns zeros when pack has no skills', () => {
+    const result = installSkills(mockPack(), targetDir, sourceDir);
+    expect(result).toEqual({ installed: 0, skipped: 0 });
+  });
+
+  it('returns zeros when skills array is empty', () => {
+    const result = installSkills(mockPack({ skills: [] }), targetDir, sourceDir);
+    expect(result).toEqual({ installed: 0, skipped: 0 });
+  });
+
+  it('installs skill files to target directory', () => {
+    const skillPath = join(sourceDir, 'my-skill.md');
+    writeFileSync(skillPath, '# My Skill\nDo the thing.');
+    const result = installSkills(
+      mockPack({ skills: [{ name: 'my-skill', path: 'my-skill.md' }] }),
+      targetDir,
+      sourceDir,
+    );
+    expect(result.installed).toBe(1);
+    expect(result.skipped).toBe(0);
+    expect(existsSync(join(targetDir, 'my-skill.md'))).toBe(true);
+    expect(readFileSync(join(targetDir, 'my-skill.md'), 'utf-8')).toContain('# My Skill');
+  });
+
+  it('creates target directory if it does not exist', () => {
+    const skillPath = join(sourceDir, 'skill.md');
+    writeFileSync(skillPath, 'Content.');
+    const nestedTarget = join(tempDir, 'deeply', 'nested', 'skills');
+    installSkills(
+      mockPack({ skills: [{ name: 'skill', path: 'skill.md' }] }),
+      nestedTarget,
+      sourceDir,
+    );
+    expect(existsSync(join(nestedTarget, 'skill.md'))).toBe(true);
+  });
+
+  it('skips existing skill files by default', () => {
+    const skillPath = join(sourceDir, 'existing.md');
+    writeFileSync(skillPath, 'New content.');
+    mkdirSync(targetDir, { recursive: true });
+    writeFileSync(join(targetDir, 'existing.md'), 'Old content.');
+    const result = installSkills(
+      mockPack({ skills: [{ name: 'existing', path: 'existing.md' }] }),
+      targetDir,
+      sourceDir,
+    );
+    expect(result.skipped).toBe(1);
+    expect(result.installed).toBe(0);
+    expect(readFileSync(join(targetDir, 'existing.md'), 'utf-8')).toBe('Old content.');
+  });
+
+  it('overwrites existing when force is true', () => {
+    const skillPath = join(sourceDir, 'existing.md');
+    writeFileSync(skillPath, 'New content.');
+    mkdirSync(targetDir, { recursive: true });
+    writeFileSync(join(targetDir, 'existing.md'), 'Old content.');
+    const result = installSkills(
+      mockPack({ skills: [{ name: 'existing', path: 'existing.md' }] }),
+      targetDir,
+      sourceDir,
+      true,
+    );
+    expect(result.installed).toBe(1);
+    expect(readFileSync(join(targetDir, 'existing.md'), 'utf-8')).toBe('New content.');
+  });
+
+  it('skips when source file does not exist', () => {
+    const result = installSkills(
+      mockPack({ skills: [{ name: 'missing', path: 'nonexistent.md' }] }),
+      targetDir,
+      sourceDir,
+    );
+    expect(result.skipped).toBe(1);
+    expect(result.installed).toBe(0);
+  });
+
+  it('handles mix of installable and skippable skills', () => {
+    writeFileSync(join(sourceDir, 'good.md'), 'Good skill.');
+    mkdirSync(targetDir, { recursive: true });
+    writeFileSync(join(targetDir, 'existing.md'), 'Existing.');
+    writeFileSync(join(sourceDir, 'existing.md'), 'New.');
+    const result = installSkills(
+      mockPack({
+        skills: [
+          { name: 'good', path: 'good.md' },
+          { name: 'existing', path: 'existing.md' },
+          { name: 'missing', path: 'no-file.md' },
+        ],
+      }),
+      targetDir,
+      sourceDir,
+    );
+    expect(result.installed).toBe(1);
+    expect(result.skipped).toBe(2);
+  });
+});

package/src/domain-packs/token-resolver.test.ts

@@ -0,0 +1,148 @@
+/**
+ * Colocated tests for domain-packs/token-resolver.ts
+ *
+ * Tests: hex passthrough, named colors, semantic tokens, SCALE[SHADE],
+ * Tailwind-style tokens, listProjectTokens, buildReverseIndex.
+ */
+
+import { describe, it, expect } from 'vitest';
+import { resolveToken, listProjectTokens, buildReverseIndex } from './token-resolver.js';
+import type { PackProjectContext } from './pack-runtime.js';
+
+function projectWithColors(): PackProjectContext {
+  return {
+    id: 'proj-1',
+    name: 'TestProject',
+    path: '/test',
+    colors: {
+      primary: { scale: { '500': '#3b82f6', '700': '#1d4ed8' }, base: '#3b82f6' },
+      neutral: { scale: { '100': '#f5f5f5', '900': '#171717' }, base: '#737373' },
+    },
+    semanticTokens: {
+      'text-primary': '#171717',
+      'bg-surface': '#ffffff',
+      'text-inverse': '#ffffff',
+    },
+  };
+}
+
+function emptyProject(): PackProjectContext {
+  return { id: 'empty', path: '/empty' };
+}
+
+describe('resolveToken', () => {
+  it('passes through hex values unchanged (uppercased)', () => {
+    expect(resolveToken('#dc0000', emptyProject())).toBe('#DC0000');
+    expect(resolveToken('#FFF', emptyProject())).toBe('#FFF');
+  });
+
+  it('resolves named colors', () => {
+    expect(resolveToken('white', emptyProject())).toBe('#FFFFFF');
+    expect(resolveToken('black', emptyProject())).toBe('#000000');
+    expect(resolveToken('transparent', emptyProject())).toBe('#00000000');
+  });
+
+  it('is case-insensitive for named colors', () => {
+    expect(resolveToken('WHITE', emptyProject())).toBe('#FFFFFF');
+    expect(resolveToken('Black', emptyProject())).toBe('#000000');
+  });
+
+  it('resolves semantic tokens', () => {
+    const project = projectWithColors();
+    expect(resolveToken('text-primary', project)).toBe('#171717');
+    expect(resolveToken('bg-surface', project)).toBe('#FFFFFF');
+    expect(resolveToken('text-inverse', project)).toBe('#FFFFFF');
+  });
+
+  it('resolves SCALE[SHADE] format', () => {
+    const project = projectWithColors();
+    expect(resolveToken('PRIMARY[500]', project)).toBe('#3B82F6');
+    expect(resolveToken('neutral[900]', project)).toBe('#171717');
+  });
+
+  it('resolves Tailwind-style tokens', () => {
+    const project = projectWithColors();
+    expect(resolveToken('bg-primary-500', project)).toBe('#3B82F6');
+    expect(resolveToken('text-neutral-900', project)).toBe('#171717');
+    expect(resolveToken('border-primary-700', project)).toBe('#1D4ED8');
+  });
+
+  it('supports all Tailwind prefixes', () => {
+    const project = projectWithColors();
+    for (const prefix of ['bg', 'text', 'border', 'ring', 'fill', 'stroke']) {
+      expect(resolveToken(`${prefix}-primary-500`, project)).toBe('#3B82F6');
+    }
+  });
+
+  it('throws for unknown token', () => {
+    expect(() => resolveToken('unknown-token', emptyProject())).toThrow(/Cannot resolve token/);
+  });
+
+  it('throws for unknown color scale', () => {
+    const project = projectWithColors();
+    expect(() => resolveToken('DANGER[500]', project)).toThrow(/Unknown color scale/);
+  });
+
+  it('throws for unknown shade in valid scale', () => {
+    const project = projectWithColors();
+    expect(() => resolveToken('PRIMARY[999]', project)).toThrow(/Unknown shade/);
+  });
+
+  it('throws when project has no color scales for SCALE[SHADE]', () => {
+    expect(() => resolveToken('PRIMARY[500]', emptyProject())).toThrow(/no color scales/);
+  });
+});
+
+describe('listProjectTokens', () => {
+  it('returns empty array for project with no colors or tokens', () => {
+    expect(listProjectTokens(emptyProject())).toEqual([]);
+  });
+
+  it('lists all scale tokens', () => {
+    const tokens = listProjectTokens(projectWithColors());
+    const scaleTokens = tokens.filter((t) => t.scale !== 'semantic');
+    expect(scaleTokens.length).toBe(4); // 2 primary shades + 2 neutral shades
+  });
+
+  it('lists all semantic tokens', () => {
+    const tokens = listProjectTokens(projectWithColors());
+    const semanticTokens = tokens.filter((t) => t.scale === 'semantic');
+    expect(semanticTokens.length).toBe(3);
+  });
+
+  it('uppercases all hex values', () => {
+    const tokens = listProjectTokens(projectWithColors());
+    for (const t of tokens) {
+      expect(t.hex).toBe(t.hex.toUpperCase());
+    }
+  });
+});
+
+describe('buildReverseIndex', () => {
+  it('returns empty map for empty project', () => {
+    expect(buildReverseIndex(emptyProject()).size).toBe(0);
+  });
+
+  it('maps hex to token name', () => {
+    const index = buildReverseIndex(projectWithColors());
+    expect(index.get('#3B82F6')).toBe('primary-500');
+    expect(index.get('#171717')).toBeDefined();
+  });
+
+  it('keys are uppercased hex', () => {
+    const index = buildReverseIndex(projectWithColors());
+    for (const key of index.keys()) {
+      expect(key).toBe(key.toUpperCase());
+      expect(key.startsWith('#')).toBe(true);
+    }
+  });
+
+  it('last-write-wins when hex values collide', () => {
+    // Both text-primary and neutral-900 map to #171717
+    const index = buildReverseIndex(projectWithColors());
+    const val = index.get('#171717');
+    expect(val).toBeDefined();
+    // It should be one of the tokens that map to that hex
+    expect(['neutral-900', 'text-primary']).toContain(val);
+  });
+});