@archora/core 1.1.0

package/src/analyzer/__tests__/signals.test.ts

@@ -0,0 +1,316 @@
+import { describe, expect, it } from 'vitest';
+import {
+  applySignalSuppressions,
+  buildArchitectureSignals,
+  canSignalFailCi,
+  projectSignalsToRecommendations,
+  reconcileSignalLifecycle,
+} from '../signals';
+import type { ArchitectureSignal, ParsedFileSummary, Recommendation } from '../types';
+
+function rec(overrides: Partial<Recommendation> = {}): Recommendation {
+  return {
+    id: 'r1',
+    kind: 'contract-violation',
+    modules: ['src/a.ts'],
+    params: { severity: 'error' },
+    weight: 10,
+    ...overrides,
+  };
+}
+
+function parserFact(overrides: Partial<ParsedFileSummary> = {}): ParsedFileSummary {
+  return {
+    relPath: 'src/a.ts',
+    language: 'ts',
+    loc: 1,
+    imports: [],
+    exports: [],
+    runtimeFacts: [],
+    frameworkFacts: [],
+    routeFacts: [],
+    stateFacts: [],
+    assetFacts: [],
+    limitations: [],
+    ...overrides,
+  };
+}
+
+describe('buildArchitectureSignals', () => {
+  it('builds stable keys without legacy recommendation ids', () => {
+    const a = buildArchitectureSignals({
+      recommendations: [rec({ id: 'generated-a', modules: ['src/b.ts', 'src/a.ts'] })],
+      warnings: [],
+    }).signals[0];
+    const b = buildArchitectureSignals({
+      recommendations: [rec({ id: 'generated-b', modules: ['src/a.ts', 'src/b.ts'] })],
+      warnings: [],
+    }).signals[0];
+
+    expect(a?.stableKey).toBe(b?.stableKey);
+  });
+
+  it('changes stable keys when evidence modules or facts differ', () => {
+    const a = buildArchitectureSignals({
+      recommendations: [rec({ modules: ['src/a.ts'] })],
+      warnings: [],
+    }).signals[0];
+    const b = buildArchitectureSignals({
+      recommendations: [rec({ modules: ['src/other.ts'] })],
+      warnings: [],
+    }).signals[0];
+
+    expect(a?.stableKey).not.toBe(b?.stableKey);
+  });
+
+  it('keeps heuristic-only legacy signals out of top insights', () => {
+    const { signals, insights } = buildArchitectureSignals({
+      recommendations: [
+        rec({
+          id: 'h1',
+          kind: 'unused-utility',
+          modules: ['src/unused.ts'],
+          weight: 100,
+        }),
+      ],
+      warnings: [],
+    });
+
+    expect(signals[0]?.confidence).toBe('low');
+    expect(signals[0]?.maturity).toBe('experimental');
+    expect(insights).toEqual([]);
+  });
+
+  it('demotes graph-derived signals when parser facts are approximate', () => {
+    const { signals, insights } = buildArchitectureSignals({
+      recommendations: [rec({ kind: 'cycle-break-cluster', params: {}, weight: 10 })],
+      warnings: [],
+      parserFacts: [
+        parserFact({
+          imports: [
+            {
+              specifier: './dynamic/',
+              kind: 'dynamic',
+              resolutionKind: 'prefix',
+              confidence: 'low',
+              approximate: true,
+            },
+          ],
+        }),
+      ],
+    });
+
+    expect(signals[0]?.confidence).toBe('medium');
+    expect(signals[0]?.limitations[0]).toContain('parser uncertainty');
+    expect(insights[0]?.confidence).toBe('medium');
+  });
+
+  it('groups related actionable signals into one insight', () => {
+    const { insights } = buildArchitectureSignals({
+      recommendations: [
+        rec({
+          id: 'contract',
+          kind: 'contract-violation',
+          modules: ['src/a.ts'],
+          params: { severity: 'error' },
+          weight: 10,
+        }),
+        rec({
+          id: 'cycle',
+          kind: 'cycle-break-candidate',
+          modules: ['src/a.ts', 'src/b.ts'],
+          params: {},
+          weight: 8,
+        }),
+      ],
+      warnings: [],
+    });
+
+    expect(insights).toHaveLength(1);
+    expect(insights[0]?.signals).toHaveLength(2);
+    expect(insights[0]?.modules).toEqual(['src/a.ts', 'src/b.ts']);
+    expect(insights[0]?.title).toContain('related');
+  });
+
+  it('applies insight noise controls without dropping raw signals', () => {
+    const { signals, insights } = buildArchitectureSignals({
+      recommendations: [
+        rec({ id: 'stable', kind: 'contract-violation', params: { severity: 'error' } }),
+        rec({ id: 'medium', kind: 'cycle-break-candidate', params: {}, modules: ['src/b.ts'] }),
+      ],
+      warnings: [],
+      insightLimit: 1,
+      minInsightSeverity: 'high',
+      minInsightConfidence: 'high',
+    });
+
+    expect(signals).toHaveLength(2);
+    expect(insights).toHaveLength(1);
+    expect(insights[0]?.severity).toBe('high');
+  });
+
+  it('projects resolve warnings as non-CI parser signals', () => {
+    const { signals, insights } = buildArchitectureSignals({
+      recommendations: [],
+      warnings: [
+        {
+          code: 'resolve-failed',
+          message: 'Could not resolve import',
+          file: 'src/a.ts',
+          detail: './missing',
+        },
+      ],
+    });
+
+    expect(signals[0]?.kind).toBe('warning:resolve-failed');
+    expect(signals[0] ? canSignalFailCi(signals[0]) : true).toBe(false);
+    expect(insights).toEqual([]);
+  });
+});
+
+describe('canSignalFailCi', () => {
+  it('allows stable high-confidence high severity signals to fail CI', () => {
+    const { signals } = buildArchitectureSignals({
+      recommendations: [rec()],
+      warnings: [],
+    });
+
+    expect(signals[0] ? canSignalFailCi(signals[0]) : false).toBe(true);
+  });
+
+  it('does not let beta or experimental signals fail CI by default', () => {
+    const { signals } = buildArchitectureSignals({
+      recommendations: [
+        rec({
+          id: 'b1',
+          kind: 'bundle-bloat',
+          params: { severity: 'high' },
+          weight: 10,
+        }),
+        rec({
+          id: 'h1',
+          kind: 'unused-utility',
+          modules: ['src/unused.ts'],
+          weight: 100,
+        }),
+      ],
+      warnings: [],
+    });
+
+    expect(signals.map((signal) => signal.maturity)).toEqual(['beta', 'experimental']);
+    expect(signals.some((signal) => canSignalFailCi(signal))).toBe(false);
+  });
+
+  it('does not fail CI for suppressed or resolved signals', () => {
+    const signal = buildArchitectureSignals({ recommendations: [rec()], warnings: [] }).signals[0];
+    expect(signal).toBeDefined();
+    expect(canSignalFailCi({ ...signal!, suppressed: true })).toBe(false);
+    expect(canSignalFailCi({ ...signal!, status: 'resolved' })).toBe(false);
+  });
+});
+
+describe('projectSignalsToRecommendations', () => {
+  it('projects signal-only compatible findings for legacy consumers', () => {
+    const signal = buildArchitectureSignals({ recommendations: [rec()], warnings: [] }).signals[0]!;
+    const signalOnly = { ...signal };
+    delete signalOnly.legacyRecommendationId;
+    const projected = projectSignalsToRecommendations([{ ...signalOnly, id: 'signal-only' }]);
+
+    expect(projected[0]).toMatchObject({
+      id: `signal:${signal.stableKey}`,
+      kind: 'contract-violation',
+      modules: ['src/a.ts'],
+      params: {
+        stableKey: signal.stableKey,
+        severity: 'high',
+      },
+    });
+  });
+});
+
+describe('reconcileSignalLifecycle', () => {
+  it('marks matching signals existing and missing baseline signals resolved', () => {
+    const current = buildArchitectureSignals({ recommendations: [rec()], warnings: [] })
+      .signals[0]!;
+    const baseline: ArchitectureSignal = { ...current, id: 'baseline-signal' };
+
+    const result = reconcileSignalLifecycle([baseline], [current]);
+
+    expect(result.current[0]?.status).toBe('existing');
+    expect(result.resolved).toEqual([]);
+  });
+
+  it('marks severity or confidence increases as regressed', () => {
+    const current = buildArchitectureSignals({ recommendations: [rec()], warnings: [] })
+      .signals[0]!;
+    const baseline: ArchitectureSignal = { ...current, severity: 'medium', confidence: 'medium' };
+
+    const result = reconcileSignalLifecycle([baseline], [current]);
+
+    expect(result.current[0]?.status).toBe('regressed');
+  });
+
+  it('returns resolved signals that disappeared from current scan', () => {
+    const baseline = buildArchitectureSignals({ recommendations: [rec()], warnings: [] })
+      .signals[0]!;
+
+    const result = reconcileSignalLifecycle([baseline], []);
+
+    expect(result.current).toEqual([]);
+    expect(result.resolved[0]?.status).toBe('resolved');
+    expect(result.resolved[0]?.stableKey).toBe(baseline.stableKey);
+  });
+});
+
+describe('applySignalSuppressions', () => {
+  it('marks active matching suppressions without removing signals', () => {
+    const signal = buildArchitectureSignals({ recommendations: [rec()], warnings: [] }).signals[0]!;
+
+    const result = applySignalSuppressions(
+      [signal],
+      [
+        {
+          stableKey: signal.stableKey,
+          reason: 'accepted debt',
+          createdAt: '2026-01-01T00:00:00.000Z',
+        },
+      ],
+      { now: '2026-02-01T00:00:00.000Z' },
+    );
+
+    expect(result.signals[0]?.suppressed).toBe(true);
+    expect(result.signals[0]?.suppressionReason).toBe('accepted debt');
+  });
+
+  it('ignores expired suppressions and reports stale suppressions', () => {
+    const signal = buildArchitectureSignals({ recommendations: [rec()], warnings: [] }).signals[0]!;
+
+    const result = applySignalSuppressions(
+      [signal],
+      [
+        {
+          stableKey: signal.stableKey,
+          reason: 'expired',
+          createdAt: '2026-01-01T00:00:00.000Z',
+          expiresAt: '2026-01-15T00:00:00.000Z',
+        },
+        {
+          stableKey: 'missing',
+          reason: 'old',
+          createdAt: '2026-01-01T00:00:00.000Z',
+        },
+      ],
+      { now: '2026-02-01T00:00:00.000Z' },
+    );
+
+    expect(result.signals[0]?.suppressed).toBeUndefined();
+    expect(result.staleSuppressions).toEqual([
+      {
+        stableKey: 'missing',
+        reason: 'old',
+        createdAt: '2026-01-01T00:00:00.000Z',
+        status: 'stale',
+      },
+    ]);
+  });
+});

package/src/analyzer/__tests__/suggestContracts.test.ts

@@ -0,0 +1,108 @@
+import { describe, expect, it } from 'vitest';
+import { suggestContracts } from '../suggestContracts';
+import type { Cycle, DependencyEdge, ModuleNode } from '../types';
+
+function mod(id: string): ModuleNode {
+  return { id, absPath: id, kind: 'unknown', language: 'ts', loc: 10, exports: [], isInfra: false };
+}
+function edge(from: string, to: string): DependencyEdge {
+  return { from, to, kind: 'static', specifier: to, resolved: true };
+}
+
+describe('suggestContracts', () => {
+  it('proposes features-isolation when there are >=2 sibling features', () => {
+    const modules = [
+      mod('src/features/auth/index.ts'),
+      mod('src/features/auth/lib/x.ts'),
+      mod('src/features/billing/index.ts'),
+      mod('src/features/billing/lib/y.ts'),
+    ];
+    const result = suggestContracts({ modules, edges: [], cycles: [] });
+    const rule = result.contracts.boundaries?.find((r) => r.name === 'features-isolation');
+    expect(rule).toBeDefined();
+    expect(rule?.crossInstance).toBe(true);
+    expect(rule?.from).toBe('src/features/*/**');
+    expect(rule?.to).toBe('src/features/*/**');
+  });
+
+  it('does not propose features-isolation when only one feature exists', () => {
+    const modules = [mod('src/features/auth/index.ts'), mod('src/features/auth/lib/x.ts')];
+    const result = suggestContracts({ modules, edges: [], cycles: [] });
+    expect(
+      result.contracts.boundaries?.find((r) => r.name === 'features-isolation'),
+    ).toBeUndefined();
+  });
+
+  it('proposes layer-discipline rules for observed FSD violations', () => {
+    const modules = [mod('src/shared/lib/u.ts'), mod('src/widgets/foo/Foo.vue')];
+    const edges = [edge('src/shared/lib/u.ts', 'src/widgets/foo/Foo.vue')];
+    const result = suggestContracts({ modules, edges, cycles: [] });
+    const rule = result.contracts.boundaries?.find((r) => r.name === 'layer-shared-not-widgets');
+    expect(rule).toBeDefined();
+    expect(rule?.from).toBe('src/shared/**');
+    expect(rule?.to).toBe('src/widgets/**');
+    expect(rule?.mode).toBe('must-not');
+  });
+
+  it('proposes no-cycles budgets only for clean folders that exist', () => {
+    const modules = [
+      mod('src/shared/lib/a.ts'),
+      mod('src/shared/lib/b.ts'),
+      mod('src/entities/x/y.ts'),
+    ];
+    const cycles: Cycle[] = [
+      {
+        id: 'c1',
+        modules: ['src/entities/x/y.ts', 'src/entities/x/z.ts'],
+        length: 2,
+        severity: 'direct',
+      },
+    ];
+    const result = suggestContracts({ modules, edges: [], cycles });
+    const sharedBudget = result.contracts.budgets?.find((r) => r.name === 'no-cycles-shared');
+    const entitiesBudget = result.contracts.budgets?.find((r) => r.name === 'no-cycles-entities');
+    expect(sharedBudget).toBeDefined();
+    expect(sharedBudget?.maxCycles).toBe(0);
+    // entities has cycles -> skip
+    expect(entitiesBudget).toBeUndefined();
+  });
+
+  it('does not duplicate rules already present in existing config', () => {
+    const modules = [mod('src/features/auth/index.ts'), mod('src/features/billing/index.ts')];
+    const result = suggestContracts({
+      modules,
+      edges: [],
+      cycles: [],
+      existing: {
+        boundaries: [
+          {
+            name: 'features-isolation',
+            from: 'src/features/*/**',
+            to: 'src/features/*/**',
+            mode: 'must-not',
+          },
+        ],
+      },
+    });
+    expect(
+      result.contracts.boundaries?.find((r) => r.name === 'features-isolation'),
+    ).toBeUndefined();
+  });
+
+  it('skips type-only edges when computing layer pairs', () => {
+    const modules = [mod('src/shared/lib/u.ts'), mod('src/widgets/foo/Foo.vue')];
+    const edges: DependencyEdge[] = [
+      {
+        from: 'src/shared/lib/u.ts',
+        to: 'src/widgets/foo/Foo.vue',
+        kind: 'type-only',
+        specifier: 'x',
+        resolved: true,
+      },
+    ];
+    const result = suggestContracts({ modules, edges, cycles: [] });
+    expect(
+      result.contracts.boundaries?.find((r) => r.name === 'layer-shared-not-widgets'),
+    ).toBeUndefined();
+  });
+});

package/src/analyzer/__tests__/svelteParser.test.ts

@@ -0,0 +1,108 @@
+import { describe, it, expect } from 'vitest';
+import { createParserRegistry, isParseFailure } from '../parsers';
+import type { ParsedFile } from '../types';
+
+const parseSvelte = (relPath: string, content: string): ParsedFile => {
+  const registry = createParserRegistry({ framework: 'svelte' });
+  const r = registry.parse({ relPath, content });
+  if (isParseFailure(r)) throw new Error(`unexpected parse failure: ${r.reason}`);
+  return r;
+};
+
+describe('svelteParser', () => {
+  it('extracts static imports from <script lang="ts">', () => {
+    const sfc = `
+<script lang="ts">
+  import Header from './Header.svelte';
+  import { theme } from './stores/theme';
+  export let route: string = 'home';
+</script>
+
+<header><Header /></header>
+`;
+    const file = parseSvelte('App.svelte', sfc);
+    expect(file.language).toBe('svelte');
+    const specs = file.imports.filter((i) => i.kind === 'static').map((i) => i.specifier);
+    expect(specs).toEqual(expect.arrayContaining(['./Header.svelte', './stores/theme']));
+  });
+
+  it('extracts dynamic import() inside script as dynamic edge', () => {
+    const sfc = `
+<script lang="ts">
+  const lazyPage = import('./routes/Settings.svelte');
+</script>
+
+{#await lazyPage then mod}
+  <svelte:component this={mod.default} />
+{/await}
+`;
+    const file = parseSvelte('App.svelte', sfc);
+    const dynamic = file.imports.filter((i) => i.kind === 'dynamic').map((i) => i.specifier);
+    expect(dynamic).toContain('./routes/Settings.svelte');
+  });
+
+  it('handles <script context="module"> in addition to <script>', () => {
+    const sfc = `
+<script context="module" lang="ts">
+  import { sharedConfig } from './shared';
+  export const meta = { name: 'page' };
+</script>
+
+<script lang="ts">
+  import { onMount } from 'svelte';
+  import Footer from './Footer.svelte';
+  let mounted = false;
+  onMount(() => { mounted = true; });
+</script>
+
+<Footer />
+`;
+    const file = parseSvelte('Page.svelte', sfc);
+    const specs = file.imports.map((i) => i.specifier);
+    expect(specs).toEqual(expect.arrayContaining(['./shared', 'svelte', './Footer.svelte']));
+  });
+
+  it('treats template-only .svelte (no <script>) as zero-import file, not a failure', () => {
+    const file = parseSvelte(
+      'Icon.svelte',
+      `<svg width="16" height="16"><circle cx="8" cy="8" r="7" /></svg>`,
+    );
+    expect(file.language).toBe('svelte');
+    expect(file.imports).toEqual([]);
+  });
+
+  it('script tag is matched case-insensitively and tolerates whitespace', () => {
+    const sfc = `<SCRIPT lang="ts" >
+  import { foo } from './foo';
+</  Script   >`;
+    const file = parseSvelte('Weird.svelte', sfc);
+    expect(file.imports.map((i) => i.specifier)).toContain('./foo');
+  });
+
+  it('reports loc of the entire SFC, not just the script', () => {
+    const sfc = `<script lang="ts">
+  import x from './x';
+</script>
+
+<div>line</div>
+<div>line</div>
+<div>line</div>
+`;
+    const file = parseSvelte('A.svelte', sfc);
+    expect(file.loc).toBeGreaterThan(5);
+  });
+});
+
+describe('parserRegistry: .svelte routing', () => {
+  it('routes .svelte to svelteParser regardless of framework', () => {
+    for (const framework of ['svelte', 'vue', 'react', 'unknown'] as const) {
+      const registry = createParserRegistry({ framework });
+      const r = registry.parse({
+        relPath: 'A.svelte',
+        content: `<script>import x from './x';</script>`,
+      });
+      expect(isParseFailure(r)).toBe(false);
+      expect((r as ParsedFile).language).toBe('svelte');
+    }
+  });
+});

package/src/analyzer/__tests__/typeOnlyCandidates.test.ts

@@ -0,0 +1,163 @@
+import { describe, it, expect } from 'vitest';
+import { findTypeOnlyCandidates } from '../typeOnlyCandidates';
+import type { FileSource } from '../fileSource';
+import type { ModuleNode } from '../types';
+
+function makeSource(files: Record<string, string>): FileSource {
+  return {
+    rootPath: '/virtual',
+    list: async () => Object.keys(files),
+    read: async (rel: string) => {
+      const c = files[rel];
+      if (c === undefined) throw new Error(`missing: ${rel}`);
+      return c;
+    },
+    exists: async (rel: string) => rel in files,
+  };
+}
+
+const mod = (id: string, language: 'ts' | 'js' | 'vue' | 'svelte' = 'ts'): ModuleNode => ({
+  id,
+  absPath: id,
+  kind: 'unknown',
+  language,
+  loc: 1,
+  exports: [],
+  isInfra: false,
+});
+
+describe('findTypeOnlyCandidates', () => {
+  it('flags import used only in TypeReference', () => {
+    const source = makeSource({
+      'a.ts': `
+        import { Foo } from './b';
+        export function take(x: Foo): void { void x; }
+      `,
+    });
+    const modules = [mod('a.ts'), mod('b.ts')];
+    return findTypeOnlyCandidates({
+      edges: [{ from: 'a.ts', to: 'b.ts', specifier: './b' }],
+      source,
+      modules,
+    }).then((cands) => {
+      expect(cands).toHaveLength(1);
+      expect(cands[0]?.bindings).toEqual(['Foo']);
+    });
+  });
+
+  it('flags import used in HeritageClause', async () => {
+    const source = makeSource({
+      'a.ts': `
+        import { Base } from './b';
+        export class Derived extends Base {}
+      `,
+    });
+    // class-extends is a value position, not a type position - should NOT flag
+    const cands = await findTypeOnlyCandidates({
+      edges: [{ from: 'a.ts', to: 'b.ts', specifier: './b' }],
+      source,
+      modules: [mod('a.ts'), mod('b.ts')],
+    });
+    expect(cands).toHaveLength(0);
+  });
+
+  it('flags interface heritage', async () => {
+    const source = makeSource({
+      'a.ts': `
+        import type {} from 'unrelated';
+        import { IFoo } from './b';
+        export interface Bar extends IFoo {}
+      `,
+    });
+    const cands = await findTypeOnlyCandidates({
+      edges: [{ from: 'a.ts', to: 'b.ts', specifier: './b' }],
+      source,
+      modules: [mod('a.ts'), mod('b.ts')],
+    });
+    expect(cands).toHaveLength(1);
+    expect(cands[0]?.bindings).toEqual(['IFoo']);
+  });
+
+  it('rejects when import is used as a value', async () => {
+    const source = makeSource({
+      'a.ts': `
+        import { Foo } from './b';
+        const x: Foo = new Foo();
+      `,
+    });
+    const cands = await findTypeOnlyCandidates({
+      edges: [{ from: 'a.ts', to: 'b.ts', specifier: './b' }],
+      source,
+      modules: [mod('a.ts'), mod('b.ts')],
+    });
+    expect(cands).toHaveLength(0);
+  });
+
+  it('rejects when used in typeof position (needs runtime value)', async () => {
+    const source = makeSource({
+      'a.ts': `
+        import { router } from './b';
+        type R = typeof router;
+        export function use(): R { return router; }
+      `,
+    });
+    const cands = await findTypeOnlyCandidates({
+      edges: [{ from: 'a.ts', to: 'b.ts', specifier: './b' }],
+      source,
+      modules: [mod('a.ts'), mod('b.ts')],
+    });
+    expect(cands).toHaveLength(0);
+  });
+
+  it('skips already-type-only imports', async () => {
+    const source = makeSource({
+      'a.ts': `
+        import type { Foo } from './b';
+        export function take(x: Foo): void { void x; }
+      `,
+    });
+    const cands = await findTypeOnlyCandidates({
+      edges: [{ from: 'a.ts', to: 'b.ts', specifier: './b' }],
+      source,
+      modules: [mod('a.ts'), mod('b.ts')],
+    });
+    expect(cands).toHaveLength(0);
+  });
+
+  it('handles named import with mixed type-only specifier (ignores already-typed names)', async () => {
+    const source = makeSource({
+      'a.ts': `
+        import { type Foo, doIt } from './b';
+        doIt();
+        export function take(x: Foo): void { void x; }
+      `,
+    });
+    // doIt is a value - mixed usage, NOT all-types
+    const cands = await findTypeOnlyCandidates({
+      edges: [{ from: 'a.ts', to: 'b.ts', specifier: './b' }],
+      source,
+      modules: [mod('a.ts'), mod('b.ts')],
+    });
+    expect(cands).toHaveLength(0);
+  });
+
+  it('extracts script block from .vue file', async () => {
+    const source = makeSource({
+      'A.vue': `
+        <script setup lang="ts">
+        import type {} from 'noop';
+        import { Foo } from './b';
+        defineProps<{ x: Foo }>();
+        </script>
+        <template><div /></template>
+      `,
+    });
+    const cands = await findTypeOnlyCandidates({
+      edges: [{ from: 'A.vue', to: 'b.ts', specifier: './b' }],
+      source,
+      modules: [mod('A.vue', 'vue'), mod('b.ts')],
+    });
+    expect(cands).toHaveLength(1);
+    expect(cands[0]?.bindings).toEqual(['Foo']);
+  });
+});