@soleri/core 9.0.4 → 9.2.0

package/src/vault/obsidian-sync.test.ts

@@ -0,0 +1,342 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { mkdirSync, rmSync, existsSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { randomUUID } from 'node:crypto';
+import {
+  toObsidianMarkdown,
+  fromObsidianMarkdown,
+  titleToSlug,
+  ObsidianSync,
+} from './obsidian-sync.js';
+import type { IntelligenceEntry } from '../intelligence/types.js';
+
+function makeEntry(overrides: Partial<IntelligenceEntry> = {}): IntelligenceEntry {
+  return {
+    id: `test-${randomUUID().slice(0, 8)}`,
+    type: 'pattern',
+    domain: 'architecture',
+    title: 'Test Pattern',
+    severity: 'suggestion',
+    description: 'A test pattern description.',
+    tags: ['testing', 'unit'],
+    ...overrides,
+  };
+}
+
+// ─── Format Helpers ──────────────────────────────────────────────────
+
+describe('toObsidianMarkdown', () => {
+  it('produces valid frontmatter with id, type, domain', () => {
+    const md = toObsidianMarkdown(makeEntry({ id: 'e1', type: 'pattern', domain: 'arch' }));
+    expect(md).toContain('---');
+    expect(md).toContain('id: "e1"');
+    expect(md).toContain('type: "pattern"');
+    expect(md).toContain('domain: "arch"');
+  });
+
+  it('includes tags array in frontmatter', () => {
+    const md = toObsidianMarkdown(makeEntry({ tags: ['a', 'b'] }));
+    expect(md).toContain('tags: ["a", "b"]');
+  });
+
+  it('includes severity when present', () => {
+    const md = toObsidianMarkdown(makeEntry({ severity: 'critical' }));
+    expect(md).toContain('severity: "critical"');
+  });
+
+  it('includes title as H1 heading', () => {
+    const md = toObsidianMarkdown(makeEntry({ title: 'My Pattern' }));
+    expect(md).toContain('# My Pattern');
+  });
+
+  it('includes description as body', () => {
+    const md = toObsidianMarkdown(makeEntry({ description: 'Body text here.' }));
+    expect(md).toContain('Body text here.');
+  });
+
+  it('omits tags line when tags are empty', () => {
+    const md = toObsidianMarkdown(makeEntry({ tags: [] }));
+    expect(md).not.toContain('tags:');
+  });
+
+  it('includes updated timestamp', () => {
+    const md = toObsidianMarkdown(makeEntry());
+    expect(md).toMatch(/updated: \d+/);
+  });
+});
+
+describe('fromObsidianMarkdown', () => {
+  it('parses frontmatter and body', () => {
+    const md = [
+      '---',
+      'id: "e1"',
+      'type: "pattern"',
+      'domain: "arch"',
+      'severity: "warning"',
+      'tags: ["a", "b"]',
+      'updated: 123456',
+      '---',
+      '',
+      '# My Title',
+      '',
+      'Some description text.',
+    ].join('\n');
+
+    const parsed = fromObsidianMarkdown(md);
+    expect(parsed.id).toBe('e1');
+    expect(parsed.type).toBe('pattern');
+    expect(parsed.domain).toBe('arch');
+    expect(parsed.severity).toBe('warning');
+    expect(parsed.tags).toEqual(['a', 'b']);
+    expect(parsed.title).toBe('My Title');
+    expect(parsed.description).toBe('Some description text.');
+    expect(parsed.updated).toBe(123456);
+  });
+
+  it('handles missing frontmatter gracefully', () => {
+    const parsed = fromObsidianMarkdown('# Just a Title\n\nSome text.');
+    expect(parsed.title).toBe('Just a Title');
+    expect(parsed.description).toBe('Some text.');
+  });
+
+  it('infers anti-pattern type from content', () => {
+    const md = '# Test\n\nAvoid using inline styles — anti-pattern detected.';
+    const parsed = fromObsidianMarkdown(md);
+    expect(parsed.type).toBe('anti-pattern');
+  });
+
+  it('infers pattern type from content', () => {
+    const md = '# Test\n\nAlways use semantic tokens in your components.';
+    const parsed = fromObsidianMarkdown(md);
+    expect(parsed.type).toBe('pattern');
+  });
+
+  it('infers rule type from content starting with Rule:', () => {
+    // "Rule:" must not also match anti-pattern keywords like "never"
+    const md = '# Test\n\nRule: keep components under 400 lines.';
+    const parsed = fromObsidianMarkdown(md);
+    expect(parsed.type).toBe('rule');
+  });
+
+  it('defaults to concept for ambiguous content', () => {
+    const md = '# Test\n\nThis is a general explanation of something.';
+    const parsed = fromObsidianMarkdown(md);
+    expect(parsed.type).toBe('concept');
+  });
+
+  it('preserves explicit type from frontmatter over inference', () => {
+    const md = '---\ntype: "rule"\n---\n# Test\n\nAvoid using inline styles.';
+    const parsed = fromObsidianMarkdown(md);
+    expect(parsed.type).toBe('rule');
+  });
+});
+
+describe('titleToSlug', () => {
+  it('converts to lowercase kebab-case', () => {
+    expect(titleToSlug('Hello World')).toBe('hello-world');
+  });
+
+  it('removes special characters', () => {
+    expect(titleToSlug('Use Semantic Tokens!')).toBe('use-semantic-tokens');
+  });
+
+  it('collapses multiple dashes', () => {
+    expect(titleToSlug('A -- B')).toBe('a-b');
+  });
+
+  it('trims leading and trailing dashes', () => {
+    expect(titleToSlug(' -Hello- ')).toBe('hello');
+  });
+
+  it('truncates to 80 characters', () => {
+    const long = 'A'.repeat(100);
+    expect(titleToSlug(long).length).toBeLessThanOrEqual(80);
+  });
+
+  it('returns empty string for empty input', () => {
+    expect(titleToSlug('')).toBe('');
+  });
+
+  it('handles whitespace-only input', () => {
+    expect(titleToSlug('   ')).toBe('');
+  });
+});
+
+// ─── Sync Engine ─────────────────────────────────────────────────────
+
+describe('ObsidianSync', () => {
+  let tmpDir: string;
+  let obsidianDir: string;
+
+  function makeMockVault(entryList: IntelligenceEntry[] = []) {
+    return {
+      list: vi.fn().mockReturnValue(entryList),
+      get: vi.fn().mockImplementation((id: string) => entryList.find((e) => e.id === id) ?? null),
+      seed: vi.fn().mockReturnValue(1),
+      update: vi.fn().mockReturnValue(null),
+    } as unknown;
+  }
+
+  beforeEach(() => {
+    tmpDir = join(tmpdir(), `obsidian-sync-${randomUUID().slice(0, 8)}`);
+    obsidianDir = join(tmpDir, 'obsidian');
+    mkdirSync(obsidianDir, { recursive: true });
+  });
+
+  afterEach(() => {
+    rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  // ── export ──────────────────────────────────────────────────────────
+
+  it('exports entries as markdown files', () => {
+    const entries = [makeEntry({ id: 'e1', title: 'First', domain: 'arch' })];
+    const sync = new ObsidianSync({ vault: makeMockVault(entries) });
+    const result = sync.export(obsidianDir);
+    expect(result.exported).toBe(1);
+    expect(result.files).toHaveLength(1);
+    expect(existsSync(join(obsidianDir, 'arch', 'first.md'))).toBe(true);
+  });
+
+  it('filters by types when specified', () => {
+    const entries = [
+      makeEntry({ id: 'e1', type: 'pattern' }),
+      makeEntry({ id: 'e2', type: 'anti-pattern' }),
+    ];
+    const sync = new ObsidianSync({ vault: makeMockVault(entries) });
+    const result = sync.export(obsidianDir, { types: ['pattern'] });
+    expect(result.exported).toBe(1);
+  });
+
+  it('filters by domains when specified', () => {
+    const entries = [
+      makeEntry({ id: 'e1', domain: 'arch' }),
+      makeEntry({ id: 'e2', domain: 'security' }),
+    ];
+    const sync = new ObsidianSync({ vault: makeMockVault(entries) });
+    const result = sync.export(obsidianDir, { domains: ['security'] });
+    expect(result.exported).toBe(1);
+  });
+
+  it('skips entries with empty slugs', () => {
+    const entries = [makeEntry({ id: 'e1', title: '' })];
+    const sync = new ObsidianSync({ vault: makeMockVault(entries) });
+    const result = sync.export(obsidianDir);
+    expect(result.exported).toBe(0);
+    expect(result.skipped).toBe(1);
+  });
+
+  it('does not write files in dry run mode', () => {
+    const entries = [makeEntry({ id: 'e1', title: 'DryRun', domain: 'test' })];
+    const sync = new ObsidianSync({ vault: makeMockVault(entries) });
+    const result = sync.export(obsidianDir, { dryRun: true });
+    expect(result.exported).toBe(1);
+    expect(existsSync(join(obsidianDir, 'test', 'dryrun.md'))).toBe(false);
+  });
+
+  // ── import ──────────────────────────────────────────────────────────
+
+  it('imports markdown files into vault', () => {
+    const md = [
+      '---',
+      'id: "new-entry"',
+      'type: "pattern"',
+      'domain: "test"',
+      '---',
+      '',
+      '# Imported Pattern',
+      '',
+      'Description of imported pattern.',
+    ].join('\n');
+    mkdirSync(join(obsidianDir, 'test'), { recursive: true });
+    writeFileSync(join(obsidianDir, 'test', 'imported.md'), md, 'utf-8');
+
+    const mockVault = makeMockVault([]);
+    const sync = new ObsidianSync({ vault: mockVault });
+    const result = sync.import(obsidianDir);
+    expect(result.imported).toBe(1);
+    expect(mockVault.seed).toHaveBeenCalled();
+  });
+
+  it('updates existing entries on import', () => {
+    const existing = makeEntry({ id: 'existing', domain: 'test' });
+    const md = [
+      '---',
+      'id: "existing"',
+      'type: "pattern"',
+      '---',
+      '',
+      '# Updated Title',
+      '',
+      'Updated description.',
+    ].join('\n');
+    mkdirSync(join(obsidianDir, 'test'), { recursive: true });
+    writeFileSync(join(obsidianDir, 'test', 'updated.md'), md, 'utf-8');
+
+    const mockVault = makeMockVault([existing]);
+    const sync = new ObsidianSync({ vault: mockVault });
+    const result = sync.import(obsidianDir);
+    expect(result.updated).toBe(1);
+    expect(mockVault.update).toHaveBeenCalledWith('existing', expect.objectContaining({
+      title: 'Updated Title',
+    }));
+  });
+
+  it('skips files without title or description', () => {
+    writeFileSync(join(obsidianDir, 'empty.md'), '---\nid: "x"\n---\n', 'utf-8');
+    const sync = new ObsidianSync({ vault: makeMockVault([]) });
+    const result = sync.import(obsidianDir);
+    expect(result.skipped).toBe(1);
+    expect(result.imported).toBe(0);
+  });
+
+  it('uses directory name as domain fallback', () => {
+    const md = '# Title\n\nDescription text.';
+    mkdirSync(join(obsidianDir, 'custom-domain'), { recursive: true });
+    writeFileSync(join(obsidianDir, 'custom-domain', 'entry.md'), md, 'utf-8');
+
+    const mockVault = makeMockVault([]);
+    const sync = new ObsidianSync({ vault: mockVault });
+    sync.import(obsidianDir);
+    const seedCall = mockVault.seed.mock.calls[0][0][0];
+    expect(seedCall.domain).toBe('custom-domain');
+  });
+
+  // ── sync ────────────────────────────────────────────────────────────
+
+  it('push mode only exports', () => {
+    const entries = [makeEntry({ id: 'e1', title: 'Push', domain: 'test' })];
+    const sync = new ObsidianSync({ vault: makeMockVault(entries) });
+    const result = sync.sync(obsidianDir, { mode: 'push' });
+    expect(result.pushed).toBe(1);
+    expect(result.pulled).toBe(0);
+    expect(result.mode).toBe('push');
+  });
+
+  it('pull mode only imports', () => {
+    const md = '# Pull Entry\n\nSome text.';
+    mkdirSync(join(obsidianDir, 'test'), { recursive: true });
+    writeFileSync(join(obsidianDir, 'test', 'pull.md'), md, 'utf-8');
+
+    const sync = new ObsidianSync({ vault: makeMockVault([]) });
+    const result = sync.sync(obsidianDir, { mode: 'pull' });
+    expect(result.pulled).toBe(1);
+    expect(result.pushed).toBe(0);
+    expect(result.mode).toBe('pull');
+  });
+
+  it('bidirectional mode exports and imports', () => {
+    const entries = [makeEntry({ id: 'e1', title: 'Bidir', domain: 'test' })];
+    const sync = new ObsidianSync({ vault: makeMockVault(entries) });
+    const result = sync.sync(obsidianDir, { mode: 'bidirectional' });
+    expect(result.mode).toBe('bidirectional');
+    expect(result.pushed).toBe(1);
+  });
+
+  it('defaults to bidirectional mode', () => {
+    const sync = new ObsidianSync({ vault: makeMockVault([]) });
+    const result = sync.sync(obsidianDir);
+    expect(result.mode).toBe('bidirectional');
+  });
+});

package/src/vault/playbook.test.ts

@@ -0,0 +1,152 @@
+import { describe, it, expect } from 'vitest';
+import {
+  validatePlaybook,
+  parsePlaybookFromEntry,
+  type Playbook,
+  type PlaybookStep,
+} from './playbook.js';
+import type { IntelligenceEntry } from '../intelligence/types.js';
+
+function makeStep(overrides: Partial<PlaybookStep> = {}, index = 1): PlaybookStep {
+  return {
+    order: index,
+    title: `Step ${index}`,
+    description: `Description for step ${index}`,
+    ...overrides,
+  };
+}
+
+function makePlaybook(overrides: Partial<Playbook> = {}): Playbook {
+  return {
+    id: 'pb-1',
+    title: 'Test Playbook',
+    domain: 'testing',
+    description: 'A test playbook',
+    steps: [makeStep({}, 1), makeStep({}, 2)],
+    tags: ['test'],
+    createdAt: 0,
+    updatedAt: 0,
+    ...overrides,
+  };
+}
+
+function makeEntry(overrides: Partial<IntelligenceEntry> = {}): IntelligenceEntry {
+  return {
+    id: 'entry-1',
+    type: 'playbook',
+    domain: 'testing',
+    title: 'Test Playbook',
+    severity: 'suggestion',
+    description: 'A test playbook entry',
+    tags: ['test'],
+    context: JSON.stringify({ steps: [makeStep({}, 1)] }),
+    ...overrides,
+  };
+}
+
+describe('validatePlaybook', () => {
+  it('returns valid for a well-formed playbook', () => {
+    const result = validatePlaybook(makePlaybook());
+    expect(result.valid).toBe(true);
+    expect(result.errors).toEqual([]);
+  });
+
+  it('rejects empty title', () => {
+    const result = validatePlaybook(makePlaybook({ title: '' }));
+    expect(result.valid).toBe(false);
+    expect(result.errors).toContain('Playbook title must not be empty');
+  });
+
+  it('rejects whitespace-only title', () => {
+    const result = validatePlaybook(makePlaybook({ title: '   ' }));
+    expect(result.valid).toBe(false);
+    expect(result.errors).toContain('Playbook title must not be empty');
+  });
+
+  it('rejects empty steps array', () => {
+    const result = validatePlaybook(makePlaybook({ steps: [] }));
+    expect(result.valid).toBe(false);
+    expect(result.errors).toContain('Playbook must have at least one step');
+  });
+
+  it('rejects out-of-order steps', () => {
+    const steps = [makeStep({ order: 2 }, 1), makeStep({ order: 1 }, 2)];
+    // Fix: steps[0] has order=2 but expected=1
+    const result = validatePlaybook(makePlaybook({ steps }));
+    expect(result.valid).toBe(false);
+    expect(result.errors[0]).toContain('Step 1 has order 2, expected 1');
+  });
+
+  it('rejects step with empty title', () => {
+    const steps = [makeStep({ title: '' }, 1)];
+    const result = validatePlaybook(makePlaybook({ steps }));
+    expect(result.valid).toBe(false);
+    expect(result.errors).toContain('Step 1 title must not be empty');
+  });
+
+  it('rejects step with empty description', () => {
+    const steps = [makeStep({ description: '' }, 1)];
+    const result = validatePlaybook(makePlaybook({ steps }));
+    expect(result.valid).toBe(false);
+    expect(result.errors).toContain('Step 1 description must not be empty');
+  });
+
+  it('collects multiple errors', () => {
+    const steps = [makeStep({ title: '', description: '' }, 1)];
+    const result = validatePlaybook(makePlaybook({ title: '', steps }));
+    expect(result.valid).toBe(false);
+    expect(result.errors.length).toBeGreaterThanOrEqual(3);
+  });
+});
+
+describe('parsePlaybookFromEntry', () => {
+  it('parses a valid playbook entry', () => {
+    const playbook = parsePlaybookFromEntry(makeEntry());
+    expect(playbook).not.toBeNull();
+    expect(playbook!.id).toBe('entry-1');
+    expect(playbook!.title).toBe('Test Playbook');
+    expect(playbook!.steps).toHaveLength(1);
+    expect(playbook!.steps[0].order).toBe(1);
+  });
+
+  it('returns null for non-playbook type', () => {
+    const result = parsePlaybookFromEntry(makeEntry({ type: 'pattern' }));
+    expect(result).toBeNull();
+  });
+
+  it('returns null for missing context', () => {
+    const result = parsePlaybookFromEntry(makeEntry({ context: undefined }));
+    expect(result).toBeNull();
+  });
+
+  it('returns null for invalid JSON context', () => {
+    const result = parsePlaybookFromEntry(makeEntry({ context: 'not-json' }));
+    expect(result).toBeNull();
+  });
+
+  it('returns null when context has no steps array', () => {
+    const result = parsePlaybookFromEntry(makeEntry({ context: JSON.stringify({ other: true }) }));
+    expect(result).toBeNull();
+  });
+
+  it('returns null when steps is not an array', () => {
+    const result = parsePlaybookFromEntry(
+      makeEntry({ context: JSON.stringify({ steps: 'not-array' }) }),
+    );
+    expect(result).toBeNull();
+  });
+
+  it('sets createdAt and updatedAt to 0', () => {
+    const playbook = parsePlaybookFromEntry(makeEntry());
+    expect(playbook!.createdAt).toBe(0);
+    expect(playbook!.updatedAt).toBe(0);
+  });
+
+  it('preserves domain and tags from the entry', () => {
+    const playbook = parsePlaybookFromEntry(
+      makeEntry({ domain: 'security', tags: ['sec', 'audit'] }),
+    );
+    expect(playbook!.domain).toBe('security');
+    expect(playbook!.tags).toEqual(['sec', 'audit']);
+  });
+});

package/src/vault/scope-detector.test.ts

@@ -0,0 +1,187 @@
+import { describe, it, expect } from 'vitest';
+import { detectScope, type ScopeInput } from './scope-detector.js';
+
+function makeInput(overrides: Partial<ScopeInput> = {}): ScopeInput {
+  return {
+    title: 'Test Entry',
+    description: 'A generic description.',
+    ...overrides,
+  };
+}
+
+describe('detectScope', () => {
+  // ── Default behavior ──────────────────────────────────────────────
+
+  it('defaults to agent tier when no signals detected', () => {
+    const result = detectScope(makeInput());
+    expect(result.tier).toBe('agent');
+    expect(result.confidence).toBe('LOW');
+    expect(result.reason).toContain('defaulting to agent');
+  });
+
+  // ── Team detection via content ─────────────────────────────────────
+
+  it('detects team tier for accessibility content', () => {
+    const result = detectScope(
+      makeInput({ description: 'Always use ARIA labels for screen reader support' }),
+    );
+    expect(result.tier).toBe('team');
+    expect(result.signals.some((s) => s.tier === 'team' && s.source === 'content')).toBe(true);
+  });
+
+  it('detects team tier for WCAG/contrast content', () => {
+    const result = detectScope(
+      makeInput({ description: 'Ensure contrast ratio meets WCAG AA standard' }),
+    );
+    expect(result.tier).toBe('team');
+  });
+
+  it('detects team tier for design system content', () => {
+    const result = detectScope(
+      makeInput({ description: 'Use semantic token from the design system' }),
+    );
+    expect(result.tier).toBe('team');
+  });
+
+  it('detects team tier for security content', () => {
+    const result = detectScope(
+      makeInput({ description: 'Sanitize all user input to prevent XSS attacks' }),
+    );
+    expect(result.tier).toBe('team');
+  });
+
+  it('detects team tier for touch target / UX content', () => {
+    const result = detectScope(
+      makeInput({ description: 'Touch target must be 44px minimum per Fitts law' }),
+    );
+    expect(result.tier).toBe('team');
+  });
+
+  // ── Project detection via content ──────────────────────────────────
+
+  it('detects project tier for scoped package references', () => {
+    const result = detectScope(
+      makeInput({ description: 'Import from @soleri/core for vault operations' }),
+    );
+    expect(result.tier).toBe('project');
+  });
+
+  it('detects project tier for monorepo path references', () => {
+    const result = detectScope(
+      makeInput({ description: 'The module lives in packages/core/src/vault.ts' }),
+    );
+    expect(result.tier).toBe('project');
+  });
+
+  it('detects project tier for explicit project references', () => {
+    const result = detectScope(
+      makeInput({ description: 'This project uses a custom build pipeline' }),
+    );
+    expect(result.tier).toBe('project');
+  });
+
+  // ── Agent detection via content ────────────────────────────────────
+
+  it('detects agent tier for personal preferences', () => {
+    const result = detectScope(
+      makeInput({ description: 'I prefer using vim keybindings in my editor' }),
+    );
+    expect(result.tier).toBe('agent');
+  });
+
+  it('detects agent tier for home directory paths', () => {
+    const result = detectScope(
+      makeInput({ description: 'Config lives in ~/dotfiles/zshrc' }),
+    );
+    expect(result.tier).toBe('agent');
+  });
+
+  // ── Category signals ───────────────────────────────────────────────
+
+  it('boosts team tier for team categories', () => {
+    const result = detectScope(makeInput({ category: 'accessibility' }));
+    expect(result.tier).toBe('team');
+    expect(result.signals.some((s) => s.source === 'category')).toBe(true);
+  });
+
+  it('boosts project tier for project categories', () => {
+    const result = detectScope(makeInput({ category: 'infrastructure' }));
+    expect(result.tier).toBe('project');
+  });
+
+  it('produces no category signal for unknown categories', () => {
+    const result = detectScope(makeInput({ category: 'random' }));
+    expect(result.signals.filter((s) => s.source === 'category')).toEqual([]);
+  });
+
+  // ── Tag signals ────────────────────────────────────────────────────
+
+  it('boosts team tier for team tags', () => {
+    const result = detectScope(makeInput({ tags: ['universal', 'best-practice'] }));
+    expect(result.tier).toBe('team');
+  });
+
+  it('boosts project tier for project tags', () => {
+    const result = detectScope(makeInput({ tags: ['project-specific', 'internal'] }));
+    expect(result.tier).toBe('project');
+  });
+
+  it('boosts agent tier for agent tags', () => {
+    const result = detectScope(makeInput({ tags: ['personal', 'preference'] }));
+    expect(result.tier).toBe('agent');
+  });
+
+  it('handles empty tags array', () => {
+    const result = detectScope(makeInput({ tags: [] }));
+    expect(result.tier).toBe('agent'); // default
+  });
+
+  // ── Confidence levels ──────────────────────────────────────────────
+
+  it('returns HIGH confidence when strong signals with no competition', () => {
+    const result = detectScope(
+      makeInput({
+        description: 'Accessibility a11y ARIA screen reader WCAG contrast ratio',
+        category: 'accessibility',
+        tags: ['a11y', 'wcag'],
+      }),
+    );
+    expect(result.tier).toBe('team');
+    expect(result.confidence).toBe('HIGH');
+  });
+
+  it('returns MEDIUM confidence for moderate signal competition', () => {
+    // Mix of team and project signals
+    const result = detectScope(
+      makeInput({
+        description: 'This project uses type safety patterns from @soleri/core',
+        tags: ['pattern'],
+      }),
+    );
+    expect(['HIGH', 'MEDIUM']).toContain(result.confidence);
+  });
+
+  // ── Signal structure ───────────────────────────────────────────────
+
+  it('includes signals with expected shape', () => {
+    const result = detectScope(
+      makeInput({ description: 'Use focus ring for keyboard navigation' }),
+    );
+    for (const signal of result.signals) {
+      expect(signal).toHaveProperty('tier');
+      expect(signal).toHaveProperty('source');
+      expect(signal).toHaveProperty('indicator');
+      expect(signal).toHaveProperty('weight');
+      expect(signal.weight).toBeGreaterThan(0);
+      expect(signal.weight).toBeLessThanOrEqual(1);
+    }
+  });
+
+  it('reason summarizes top signals', () => {
+    const result = detectScope(
+      makeInput({ description: 'Accessibility best practice for a11y compliance' }),
+    );
+    expect(result.reason.length).toBeGreaterThan(0);
+    expect(result.reason).not.toContain('defaulting');
+  });
+});