@archora/core 1.1.0

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

@@ -0,0 +1,187 @@
+import { describe, it, expect } from 'vitest';
+import { createTsParser } from '../parsers/tsParser';
+import { createVueParser } from '../parsers/vueParser';
+import { createParserRegistry, isParseFailure } from '../parsers';
+
+describe('tsParser', () => {
+  it('captures static, dynamic, type-only and side-effect imports', () => {
+    const p = createTsParser();
+    const result = p.parse({
+      relPath: 'sample.ts',
+      language: 'ts',
+      content: `
+        import a from './a';
+        import type { B } from './b';
+        import './style.css';
+        import { type C, d } from './cd';
+        const lazy = () => import('./lazy');
+        export { e } from './e';
+      `,
+    });
+    const byKind = (k: string) =>
+      result.imports.filter((i) => i.kind === k).map((i) => i.specifier);
+    expect(byKind('static').sort()).toEqual(['./a', './cd', './e'].sort());
+    expect(byKind('type-only')).toContain('./b');
+    expect(byKind('side-effect')).toContain('./style.css');
+    expect(byKind('dynamic')).toContain('./lazy');
+  });
+
+  it('detects defineStore', () => {
+    const p = createTsParser();
+    const result = p.parse({
+      relPath: 'store.ts',
+      language: 'ts',
+      content: `import { defineStore } from 'pinia'; export const s = defineStore('x', {});`,
+    });
+    expect(result.hasDefineStore).toBe(true);
+  });
+
+  it('lists exports', () => {
+    const p = createTsParser();
+    const result = p.parse({
+      relPath: 'x.ts',
+      language: 'ts',
+      content: `export const a = 1; export function b() {} export default {};`,
+    });
+    expect(result.exports).toContain('a');
+    expect(result.exports).toContain('b');
+  });
+
+  it('extracts static prefix from template-literal dynamic imports', () => {
+    const p = createTsParser();
+    const result = p.parse({
+      relPath: 'loader.ts',
+      language: 'ts',
+      content: `
+        async function load(name: string) {
+          return import(\`./mfes/\${name}/index\`);
+        }
+      `,
+    });
+    const dyn = result.imports.filter((i) => i.kind === 'dynamic');
+    expect(dyn).toHaveLength(1);
+    expect(dyn[0]?.specifier).toBe('./mfes/');
+    expect(dyn[0]?.pattern).toBe('prefix');
+  });
+
+  it('extracts static prefix from string-concat dynamic imports', () => {
+    const p = createTsParser();
+    const result = p.parse({
+      relPath: 'loader.ts',
+      language: 'ts',
+      content: `
+        function load(name: string) {
+          return import('./mfes/' + name + '/index');
+        }
+      `,
+    });
+    const dyn = result.imports.filter((i) => i.kind === 'dynamic');
+    expect(dyn).toHaveLength(1);
+    expect(dyn[0]?.specifier).toBe('./mfes/');
+    expect(dyn[0]?.pattern).toBe('prefix');
+  });
+
+  it('keeps literal pattern for plain dynamic imports', () => {
+    const p = createTsParser();
+    const result = p.parse({
+      relPath: 'a.ts',
+      language: 'ts',
+      content: `const m = import('./b');`,
+    });
+    const dyn = result.imports.filter((i) => i.kind === 'dynamic');
+    expect(dyn[0]?.pattern).toBeUndefined();
+    expect(dyn[0]?.specifier).toBe('./b');
+  });
+
+  it('captures CJS require() as a static import', () => {
+    const p = createTsParser();
+    const result = p.parse({
+      relPath: 'a.cjs',
+      language: 'js',
+      content: `const x = require('./b'); const y = require('lodash');`,
+    });
+    const statics = result.imports.filter((i) => i.kind === 'static');
+    expect(statics.map((i) => i.specifier).sort()).toEqual(['./b', 'lodash']);
+  });
+
+  it('captures import.meta.glob string-literal patterns', () => {
+    const p = createTsParser();
+    const result = p.parse({
+      relPath: 'router.ts',
+      language: 'ts',
+      content: `const pages = import.meta.glob('./pages/**/*.vue', { eager: false });`,
+    });
+    const globs = result.imports.filter((i) => i.pattern === 'glob');
+    expect(globs).toHaveLength(1);
+    expect(globs[0]?.specifier).toBe('./pages/**/*.vue');
+    expect(globs[0]?.kind).toBe('dynamic');
+  });
+
+  it('captures import.meta.glob with array-of-patterns', () => {
+    const p = createTsParser();
+    const result = p.parse({
+      relPath: 'router.ts',
+      language: 'ts',
+      content: `const m = import.meta.glob(['./a/**/*.ts', './b/**/*.ts']);`,
+    });
+    const globs = result.imports.filter((i) => i.pattern === 'glob');
+    expect(globs.map((g) => g.specifier).sort()).toEqual(['./a/**/*.ts', './b/**/*.ts']);
+  });
+
+  it('captures import.meta.globEager patterns as eager glob imports', () => {
+    const p = createTsParser();
+    const result = p.parse({
+      relPath: 'modules.ts',
+      language: 'ts',
+      content: `const modules = import.meta.globEager('./modules/**/*.ts');`,
+    });
+    const globs = result.imports.filter((i) => i.pattern === 'glob');
+    expect(globs).toHaveLength(1);
+    expect(globs[0]).toMatchObject({
+      specifier: './modules/**/*.ts',
+      kind: 'dynamic',
+      confidence: 'medium',
+      globEager: true,
+    });
+  });
+
+  it('captures namespace re-export names', () => {
+    const parser = createParserRegistry();
+    const result = parser.parse({
+      relPath: 'src/index.ts',
+      content: "export * as FeatureApi from './feature';",
+    });
+    if (isParseFailure(result)) throw new Error('parse failed');
+    expect(result.exports).toContain('FeatureApi');
+    expect(result.imports).toEqual([{ specifier: './feature', kind: 'static' }]);
+  });
+
+  it('skips dynamic imports with no static prefix', () => {
+    const p = createTsParser();
+    const result = p.parse({
+      relPath: 'a.ts',
+      language: 'ts',
+      content: `function load(p: string) { return import(p); }`,
+    });
+    expect(result.imports.filter((i) => i.kind === 'dynamic')).toHaveLength(0);
+  });
+});
+
+describe('vueParser', () => {
+  it('extracts imports from <script setup>', () => {
+    const tp = createTsParser();
+    const vp = createVueParser(tp);
+    const result = vp.parse({
+      relPath: 'Foo.vue',
+      content: `<template><div /></template>
+<script setup lang="ts">
+import Bar from '@/Bar.vue';
+import { useFoo } from '@/composables/useFoo';
+</script>`,
+    });
+    expect(result.language).toBe('vue');
+    const specs = result.imports.map((i) => i.specifier);
+    expect(specs).toContain('@/Bar.vue');
+    expect(specs).toContain('@/composables/useFoo');
+  });
+});

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

@@ -0,0 +1,93 @@
+import { describe, it, expect } from 'vitest';
+import { createParserRegistry, isParseFailure } from '../parsers';
+import type { ParsedFile } from '../types';
+
+const parseReact = (relPath: string, content: string): ParsedFile => {
+  const registry = createParserRegistry({ framework: 'react' });
+  const r = registry.parse({ relPath, content });
+  if (isParseFailure(r)) throw new Error(`unexpected parse failure: ${r.reason}`);
+  return r;
+};
+
+describe('reactParser (via registry, framework=react)', () => {
+  it('captures lazy(() => import(...)) as a dynamic edge', () => {
+    const file = parseReact(
+      'src/App.tsx',
+      `import { lazy } from 'react';
+       const Settings = lazy(() => import('./routes/Settings'));
+       export const App = () => null;`,
+    );
+    const dynamic = file.imports.filter((i) => i.kind === 'dynamic');
+    expect(dynamic.map((i) => i.specifier)).toContain('./routes/Settings');
+  });
+
+  it('captures multiple lazy imports independently', () => {
+    const file = parseReact(
+      'src/App.tsx',
+      `import { lazy } from 'react';
+       const A = lazy(() => import('./A'));
+       const B = lazy(() => import('./B'));
+       export const App = () => null;`,
+    );
+    const specs = file.imports.filter((i) => i.kind === 'dynamic').map((i) => i.specifier);
+    expect(specs).toEqual(expect.arrayContaining(['./A', './B']));
+  });
+
+  it('captures static imports of JSX components', () => {
+    const file = parseReact(
+      'src/App.tsx',
+      `import { Header } from './components/Header';
+       import { SearchIcon } from './components/icons/SearchIcon';
+       export const App = () => (<div><Header /><SearchIcon /></div>);`,
+    );
+    const statics = file.imports.filter((i) => i.kind === 'static').map((i) => i.specifier);
+    expect(statics).toEqual(
+      expect.arrayContaining(['./components/Header', './components/icons/SearchIcon']),
+    );
+  });
+
+  it('routes .jsx extension as js language', () => {
+    const file = parseReact(
+      'src/App.jsx',
+      `import { Foo } from './foo'; export const App = () => <Foo />;`,
+    );
+    expect(file.language).toBe('js');
+  });
+
+  it('routes .tsx extension as ts language', () => {
+    const file = parseReact(
+      'src/App.tsx',
+      `import { Foo } from './foo'; export const App = (): JSX.Element => <Foo />;`,
+    );
+    expect(file.language).toBe('ts');
+  });
+
+  it('does not treat external react packages as project edges (filtered downstream)', () => {
+    const file = parseReact(
+      'src/App.tsx',
+      `import React, { useState } from 'react';
+       import { useNavigate } from 'react-router-dom';
+       import './side-effect-only';
+       export const App = () => null;`,
+    );
+    // bare specifiers are recorded; buildGraph filters externals later
+    const specs = file.imports.map((i) => i.specifier);
+    expect(specs).toEqual(
+      expect.arrayContaining(['react', 'react-router-dom', './side-effect-only']),
+    );
+  });
+});
+
+describe('parser routing by framework', () => {
+  it('uses tsParser for unknown framework (no React-specific routing today)', () => {
+    const registry = createParserRegistry({ framework: 'unknown' });
+    const r = registry.parse({
+      relPath: 'src/App.tsx',
+      content: `const Settings = lazy(() => import('./Settings')); export const App = () => null;`,
+    });
+    expect(isParseFailure(r)).toBe(false);
+    // reactParser is currently a delegate; just check lazy() emits a dynamic edge
+    const dynamic = (r as ParsedFile).imports.filter((i) => i.kind === 'dynamic');
+    expect(dynamic.map((i) => i.specifier)).toContain('./Settings');
+  });
+});

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

@@ -0,0 +1,171 @@
+import { describe, expect, it } from 'vitest';
+import { computeRecommendations } from '../recommendations';
+import type { Cycle, DependencyEdge, ModuleMetrics, ModuleNode } from '../types';
+
+function module(id: string, overrides: Partial<ModuleNode> = {}): ModuleNode {
+  return {
+    id,
+    absPath: `/${id}`,
+    kind: 'unknown',
+    language: 'ts',
+    loc: 1,
+    exports: [],
+    isInfra: false,
+    ...overrides,
+  };
+}
+
+function metrics(overrides: Partial<ModuleMetrics> = {}): ModuleMetrics {
+  return {
+    fanIn: 0,
+    fanOut: 0,
+    instability: 0,
+    depth: 0,
+    inCycle: false,
+    couplingScore: 0,
+    hotnessScore: 0,
+    ...overrides,
+  };
+}
+
+function edge(from: string, to: string, kind: DependencyEdge['kind'] = 'static'): DependencyEdge {
+  return { from, to, kind, specifier: to, resolved: true };
+}
+
+describe('computeRecommendations', () => {
+  it('flags an unused utility', () => {
+    const modules = [module('src/shared/lib/dead.ts', { kind: 'util' })];
+    const recs = computeRecommendations({
+      modules,
+      edges: [],
+      metrics: { 'src/shared/lib/dead.ts': metrics({ fanIn: 0 }) },
+      cycles: [],
+      layerViolations: [],
+      hotZones: [],
+    });
+    expect(recs.some((r) => r.kind === 'unused-utility')).toBe(true);
+  });
+
+  it('proposes a cycle break candidate', () => {
+    const modules = [module('a.ts'), module('b.ts')];
+    const cycle: Cycle = { id: 'c1', modules: ['a.ts', 'b.ts'], length: 2, severity: 'direct' };
+    const recs = computeRecommendations({
+      modules,
+      edges: [edge('a.ts', 'b.ts'), edge('b.ts', 'a.ts')],
+      metrics: {
+        'a.ts': metrics({ fanOut: 5, couplingScore: 0.8 }),
+        'b.ts': metrics({ fanOut: 1, couplingScore: 0.2 }),
+      },
+      cycles: [cycle],
+      layerViolations: [],
+      hotZones: [],
+    });
+    expect(recs.some((r) => r.kind === 'cycle-break-cluster')).toBe(true);
+  });
+
+  it('cycle-break-cluster carries pattern and feedback edges', () => {
+    // 3-cycle a→b→c→a, all in the same folder, no barrel - should be 'mixed'
+    const modules = [module('foo/a.ts'), module('foo/b.ts'), module('foo/c.ts')];
+    const cycle: Cycle = {
+      id: 'c1',
+      modules: ['foo/a.ts', 'foo/b.ts', 'foo/c.ts'],
+      length: 3,
+      severity: 'indirect',
+    };
+    const recs = computeRecommendations({
+      modules,
+      edges: [
+        edge('foo/a.ts', 'foo/b.ts'),
+        edge('foo/b.ts', 'foo/c.ts'),
+        edge('foo/c.ts', 'foo/a.ts'),
+      ],
+      metrics: Object.fromEntries(modules.map((m) => [m.id, metrics()])),
+      cycles: [cycle],
+      layerViolations: [],
+      hotZones: [],
+    });
+    const cluster = recs.find((r) => r.kind === 'cycle-break-cluster');
+    expect(cluster).toBeDefined();
+    expect(cluster!.params.pattern).toBe('mixed');
+    expect(cluster!.params.sccLength).toBe(3);
+    const fbs = cluster!.params.feedbackEdges;
+    expect(Array.isArray(fbs)).toBe(true);
+    expect((fbs as unknown[]).length).toBe(1); // ring breaks with one edge
+  });
+
+  it('detects barrel-cycle and surfaces barrel/sibling params', () => {
+    const modules = [module('src/foo/index.ts'), module('src/foo/a.ts'), module('src/foo/b.ts')];
+    const cycle: Cycle = {
+      id: 'cb',
+      modules: ['src/foo/index.ts', 'src/foo/a.ts', 'src/foo/b.ts'],
+      length: 3,
+      severity: 'indirect',
+    };
+    const recs = computeRecommendations({
+      modules,
+      edges: [
+        edge('src/foo/index.ts', 'src/foo/a.ts'),
+        edge('src/foo/a.ts', 'src/foo/b.ts'),
+        edge('src/foo/b.ts', 'src/foo/index.ts'),
+      ],
+      metrics: Object.fromEntries(modules.map((m) => [m.id, metrics()])),
+      cycles: [cycle],
+      layerViolations: [],
+      hotZones: [],
+    });
+    const cluster = recs.find((r) => r.kind === 'cycle-break-cluster');
+    expect(cluster?.params.pattern).toBe('barrel-cycle');
+    expect(cluster?.params.barrel).toBe('foo/index.ts');
+  });
+
+  it('flags a god-module by combining fan-in and LOC', () => {
+    const big = module('src/entities/store.ts', { loc: 500 });
+    const callers = Array.from({ length: 12 }, (_, i) => module(`src/c${i}.ts`));
+    const allModules = [big, ...callers];
+    const allMetrics: Record<string, ModuleMetrics> = {
+      'src/entities/store.ts': metrics({ fanIn: 12 }),
+    };
+    for (const c of callers) allMetrics[c.id] = metrics({ fanOut: 1 });
+    const recs = computeRecommendations({
+      modules: allModules,
+      edges: callers.map((c) => edge(c.id, big.id)),
+      metrics: allMetrics,
+      cycles: [],
+      layerViolations: [],
+      hotZones: [],
+    });
+    expect(recs.some((r) => r.kind === 'split-god-module')).toBe(true);
+  });
+
+  it('returns at most 20 items, sorted by weight', () => {
+    const modules = Array.from({ length: 50 }, (_, i) => module(`src/x${i}.ts`, { kind: 'util' }));
+    const m: Record<string, ModuleMetrics> = Object.fromEntries(
+      modules.map((x) => [x.id, metrics()]),
+    );
+    const recs = computeRecommendations({
+      modules,
+      edges: [],
+      metrics: m,
+      cycles: [],
+      layerViolations: [],
+      hotZones: [],
+    });
+    expect(recs.length).toBeLessThanOrEqual(20);
+    for (let i = 0; i < recs.length - 1; i++) {
+      expect(recs[i]!.weight).toBeGreaterThanOrEqual(recs[i + 1]!.weight);
+    }
+  });
+
+  it('emits structured params, not pre-formatted strings', () => {
+    const recs = computeRecommendations({
+      modules: [module('src/shared/lib/dead.ts', { kind: 'util' })],
+      edges: [],
+      metrics: { 'src/shared/lib/dead.ts': metrics() },
+      cycles: [],
+      layerViolations: [],
+      hotZones: [],
+    });
+    const r = recs.find((x) => x.kind === 'unused-utility')!;
+    expect(r.params.name).toBe('dead.ts');
+  });
+});

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

@@ -0,0 +1,63 @@
+import { describe, it, expect } from 'vitest';
+import { readdirSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { analyze } from '../index';
+import { createNodeFsFileSource } from '../sources/nodeFsFileSource';
+import { fixturePath } from './_paths';
+
+/**
+ * Snapshot tests on the benchmark reference corpus.
+ *
+ * We pin two things per reference project: the count of recommendations
+ * per kind, and the total number of modules / edges. This separates
+ * regressions in the heuristics (changes to recommendation counts) from
+ * changes to ground-truth annotations (which only affect bench TP/FP/FN).
+ *
+ * If a heuristic intentionally changes, `npm test -- -u` regenerates the
+ * snapshot. The change must be co-justified with bench numbers in the PR.
+ */
+const REFERENCE_ROOT = fixturePath('../fixtures/reference');
+
+function listReferenceProjects(): string[] {
+  try {
+    return readdirSync(REFERENCE_ROOT)
+      .filter((name) => {
+        try {
+          return statSync(join(REFERENCE_ROOT, name)).isDirectory();
+        } catch {
+          return false;
+        }
+      })
+      .sort();
+  } catch {
+    return [];
+  }
+}
+
+const projects = listReferenceProjects();
+
+describe.skipIf(projects.length === 0)('reference corpus snapshots', () => {
+  for (const name of projects) {
+    it(`${name}: stable summary`, async () => {
+      const source = await createNodeFsFileSource({ rootPath: join(REFERENCE_ROOT, name) });
+      const result = await analyze(source);
+      const byKind: Record<string, number> = {};
+      for (const r of result.recommendations) {
+        byKind[r.kind] = (byKind[r.kind] ?? 0) + 1;
+      }
+      // stable order
+      const sortedByKind = Object.fromEntries(
+        Object.entries(byKind).sort(([a], [b]) => a.localeCompare(b)),
+      );
+      expect({
+        project: name,
+        modules: result.modules.length,
+        edges: result.edges.length,
+        cycles: result.cycles.length,
+        recommendations: result.recommendations.length,
+        recommendationsByKind: sortedByKind,
+        archDebtGrade: result.archDebt.grade,
+      }).toMatchSnapshot();
+    });
+  }
+});