@archora/core 1.1.0

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

@@ -0,0 +1,372 @@
+// Architectural contracts engine - unit tests at the engine boundary
+// (input: pre-built modules/edges/cycles/metrics, output: violations) plus
+// one integration test that drives the engine through the full `analyze()`
+// pipeline using `.archora.json` to make sure config plumbing works.
+
+import { describe, expect, it } from 'vitest';
+
+import { analyze } from '../index';
+import { checkContracts } from '../contracts';
+import { createInMemoryFileSource } from '../sources/inMemoryFileSource';
+import type { Cycle, DependencyEdge, ModuleId, ModuleMetrics, ModuleNode } from '../types';
+
+// --- Test helpers ----------------------------------------------------------
+
+function mod(id: ModuleId, overrides: Partial<ModuleNode> = {}): ModuleNode {
+  return {
+    id,
+    absPath: id,
+    kind: 'unknown',
+    language: 'ts',
+    loc: 50,
+    exports: [],
+    isInfra: false,
+    ...overrides,
+  };
+}
+
+function edge(
+  from: ModuleId,
+  to: ModuleId,
+  kind: DependencyEdge['kind'] = 'static',
+): DependencyEdge {
+  return { from, to, kind, specifier: to, resolved: true };
+}
+
+function metrics(
+  values: Partial<Record<ModuleId, Partial<ModuleMetrics>>>,
+): Record<ModuleId, ModuleMetrics> {
+  const out: Record<ModuleId, ModuleMetrics> = {};
+  for (const [id, m] of Object.entries(values)) {
+    out[id] = {
+      fanIn: 0,
+      fanOut: 0,
+      instability: 0,
+      depth: 0,
+      inCycle: false,
+      couplingScore: 0,
+      hotnessScore: 0,
+      ...m,
+    };
+  }
+  return out;
+}
+
+// --- Boundary rules --------------------------------------------------------
+
+describe('boundary: must-not', () => {
+  const modules = [
+    mod('features/auth/api.ts'),
+    mod('features/billing/api.ts'),
+    mod('features/shared/types.ts'),
+    mod('shared/ui/button.ts'),
+  ];
+  const edges = [
+    edge('features/auth/api.ts', 'features/billing/api.ts'), // violation
+    edge('features/auth/api.ts', 'features/shared/types.ts'), // exempted
+    edge('features/auth/api.ts', 'shared/ui/button.ts'), // ok
+  ];
+
+  it('flags forbidden cross-feature import', () => {
+    const v = checkContracts({
+      modules,
+      edges,
+      metrics: {},
+      cycles: [],
+      contracts: {
+        boundaries: [
+          {
+            name: 'features-isolation',
+            from: 'features/*/**',
+            to: 'features/*/**',
+            mode: 'must-not',
+            except: ['features/shared/**'],
+          },
+        ],
+      },
+    });
+    expect(v.length).toBe(1);
+    expect(v[0]?.kind).toBe('boundary');
+    expect(v[0]?.edge).toEqual({
+      from: 'features/auth/api.ts',
+      to: 'features/billing/api.ts',
+      specifier: 'features/billing/api.ts',
+    });
+  });
+
+  it('except whitelist actually exempts matched edges', () => {
+    const v = checkContracts({
+      modules,
+      edges: [edge('features/auth/api.ts', 'features/shared/types.ts')],
+      metrics: {},
+      cycles: [],
+      contracts: {
+        boundaries: [
+          {
+            name: 'features-isolation',
+            from: 'features/*/**',
+            to: 'features/*/**',
+            mode: 'must-not',
+            except: ['features/shared/**'],
+          },
+        ],
+      },
+    });
+    expect(v).toEqual([]);
+  });
+
+  it('ignores type-only edges (mirrors layer-violation behaviour)', () => {
+    const v = checkContracts({
+      modules,
+      edges: [edge('features/auth/api.ts', 'features/billing/api.ts', 'type-only')],
+      metrics: {},
+      cycles: [],
+      contracts: {
+        boundaries: [
+          {
+            name: 'features-isolation',
+            from: 'features/*/**',
+            to: 'features/*/**',
+            mode: 'must-not',
+          },
+        ],
+      },
+    });
+    expect(v).toEqual([]);
+  });
+
+  it('crossInstance: skips same-feature internal edges, flags cross-feature', () => {
+    const v = checkContracts({
+      modules: [
+        mod('features/auth/index.ts'),
+        mod('features/auth/lib/jwt.ts'),
+        mod('features/billing/index.ts'),
+      ],
+      edges: [
+        edge('features/auth/index.ts', 'features/auth/lib/jwt.ts'), // same-feature, OK
+        edge('features/auth/index.ts', 'features/billing/index.ts'), // cross-feature, violation
+      ],
+      metrics: {},
+      cycles: [],
+      contracts: {
+        boundaries: [
+          {
+            name: 'features-isolation',
+            from: 'features/*/**',
+            to: 'features/*/**',
+            mode: 'must-not',
+            crossInstance: true,
+          },
+        ],
+      },
+    });
+    expect(v.length).toBe(1);
+    expect(v[0]?.edge?.to).toBe('features/billing/index.ts');
+  });
+
+  it('respects severity from the rule (default error)', () => {
+    const v = checkContracts({
+      modules,
+      edges,
+      metrics: {},
+      cycles: [],
+      contracts: {
+        boundaries: [
+          {
+            name: 'soft-rule',
+            from: 'features/*/**',
+            to: 'features/*/**',
+            mode: 'must-not',
+            severity: 'warning',
+          },
+        ],
+      },
+    });
+    expect(v[0]?.severity).toBe('warning');
+  });
+});
+
+describe('boundary: can-only', () => {
+  const modules = [
+    mod('src/router/routes.ts'),
+    mod('src/pages/home.ts'),
+    mod('src/utils/helpers.ts'),
+  ];
+
+  it("forbids edges that don't land on the allowed glob", () => {
+    const edges = [
+      edge('src/router/routes.ts', 'src/pages/home.ts'), // ok
+      edge('src/router/routes.ts', 'src/utils/helpers.ts'), // violation
+    ];
+    const v = checkContracts({
+      modules,
+      edges,
+      metrics: {},
+      cycles: [],
+      contracts: {
+        boundaries: [
+          {
+            name: 'router-only-pages',
+            from: 'src/router/**',
+            to: 'src/pages/**',
+            mode: 'can-only',
+          },
+        ],
+      },
+    });
+    expect(v.length).toBe(1);
+    expect(v[0]?.edge?.to).toBe('src/utils/helpers.ts');
+  });
+
+  it('allows internal (within-from-glob) edges without violation', () => {
+    const edges = [edge('src/router/routes.ts', 'src/router/guards.ts')];
+    const v = checkContracts({
+      modules: [...modules, mod('src/router/guards.ts')],
+      edges,
+      metrics: {},
+      cycles: [],
+      contracts: {
+        boundaries: [
+          {
+            name: 'router-only-pages',
+            from: 'src/router/**',
+            to: 'src/pages/**',
+            mode: 'can-only',
+          },
+        ],
+      },
+    });
+    expect(v).toEqual([]);
+  });
+});
+
+// --- Budget rules ----------------------------------------------------------
+
+describe('budget rules', () => {
+  it('triggers maxFanIn when exceeded', () => {
+    const v = checkContracts({
+      modules: [mod('features/auth/index.ts')],
+      edges: [],
+      metrics: metrics({ 'features/auth/index.ts': { fanIn: 50 } }),
+      cycles: [],
+      contracts: {
+        budgets: [{ name: 'auth-fanin', module: 'features/auth/**', maxFanIn: 30 }],
+      },
+    });
+    expect(v.length).toBe(1);
+    expect(v[0]?.detail).toEqual({ metric: 'fanIn', value: 50, limit: 30 });
+  });
+
+  it('does NOT trigger when under the limit', () => {
+    const v = checkContracts({
+      modules: [mod('features/auth/index.ts')],
+      edges: [],
+      metrics: metrics({ 'features/auth/index.ts': { fanIn: 5 } }),
+      cycles: [],
+      contracts: {
+        budgets: [{ name: 'auth-fanin', module: 'features/auth/**', maxFanIn: 30 }],
+      },
+    });
+    expect(v).toEqual([]);
+  });
+
+  it('triggers maxLoc on a per-module basis', () => {
+    const v = checkContracts({
+      modules: [mod('shared/ui/big.ts', { loc: 600 }), mod('shared/ui/small.ts', { loc: 50 })],
+      edges: [],
+      metrics: metrics({
+        'shared/ui/big.ts': {},
+        'shared/ui/small.ts': {},
+      }),
+      cycles: [],
+      contracts: {
+        budgets: [{ name: 'ui-loc', module: 'shared/ui/**', maxLoc: 300 }],
+      },
+    });
+    expect(v.length).toBe(1);
+    expect(v[0]?.modules).toEqual(['shared/ui/big.ts']);
+  });
+
+  it('triggers maxCycles when ≥ N+1 cycles touch the glob', () => {
+    const cycles: Cycle[] = [
+      { id: 'c1', modules: ['shared/ui/a.ts', 'shared/ui/b.ts'], length: 2, severity: 'direct' },
+    ];
+    const v = checkContracts({
+      modules: [mod('shared/ui/a.ts'), mod('shared/ui/b.ts')],
+      edges: [],
+      metrics: {},
+      cycles,
+      contracts: {
+        budgets: [{ name: 'ui-no-cycles', module: 'shared/ui/**', maxCycles: 0 }],
+      },
+    });
+    expect(v.length).toBe(1);
+    expect(v[0]?.detail?.metric).toBe('cycles');
+    expect(v[0]?.detail?.value).toBe(1);
+  });
+
+  it('rule with no numeric ceiling is silently dropped during config parse', () => {
+    // We can't go through normalizeConfig here, but we *can* check that the
+    // engine itself does nothing when the budget object has every threshold
+    // set to undefined. The normalizer (config.test.ts) covers the parse-time
+    // drop-on-empty case.
+    const v = checkContracts({
+      modules: [mod('features/auth/index.ts')],
+      edges: [],
+      metrics: metrics({ 'features/auth/index.ts': { fanIn: 100 } }),
+      cycles: [],
+      contracts: {
+        budgets: [{ name: 'no-op', module: 'features/auth/**' }],
+      },
+    });
+    expect(v).toEqual([]);
+  });
+});
+
+// --- Integration via analyze() --------------------------------------------
+
+describe('integration: analyze() honours .archora.json contracts', () => {
+  it('full pipeline emits contract-violation recommendations', async () => {
+    const config = {
+      contracts: {
+        boundaries: [
+          {
+            name: 'features-isolation',
+            from: 'features/*/**',
+            to: 'features/*/**',
+            mode: 'must-not',
+            except: ['features/shared/**'],
+          },
+        ],
+        budgets: [{ name: 'auth-loc', module: 'features/auth/**', maxLoc: 5 }],
+      },
+    };
+    const source = createInMemoryFileSource('/proj', {
+      'tsconfig.json': '{}',
+      '.archora.json': JSON.stringify(config),
+      'features/auth/index.ts': "import { x } from '../billing/index';\nexport const a = x;\n",
+      'features/billing/index.ts': 'export const x = 1;\n',
+      'features/shared/util.ts': 'export const u = 0;\n',
+    });
+    const scan = await analyze(source);
+
+    expect(scan.contractViolations.length).toBeGreaterThanOrEqual(1);
+    const boundary = scan.contractViolations.find((v) => v.kind === 'boundary');
+    expect(boundary).toBeDefined();
+    expect(boundary?.ruleName).toBe('features-isolation');
+
+    const recs = scan.recommendations.filter((r) => r.kind === 'contract-violation');
+    expect(recs.length).toBeGreaterThanOrEqual(1);
+    expect(recs[0]?.params['rule']).toBe('features-isolation');
+  });
+
+  it('no contracts block → empty contractViolations', async () => {
+    const source = createInMemoryFileSource('/proj', {
+      'tsconfig.json': '{}',
+      'src/a.ts': "import { b } from './b';\nexport const a = b;\n",
+      'src/b.ts': 'export const b = 1;\n',
+    });
+    const scan = await analyze(source);
+    expect(scan.contractViolations).toEqual([]);
+  });
+});

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

@@ -0,0 +1,317 @@
+import { describe, it, expect } from 'vitest';
+import { existsSync, readdirSync, readFileSync, statSync, type Dirent } from 'node:fs';
+import { join, relative as pathRelative, sep as pathSep } from 'node:path';
+import ignore from 'ignore';
+import { analyze } from '../index';
+import { createNodeFsFileSource } from '../sources/nodeFsFileSource';
+import { createBrowserFsAccessFileSource } from '../sources/browserFsAccessFileSource';
+import { createTauriFileSource } from '../sources/tauriFileSource';
+import type { ScanResult } from '../types';
+import { fixturePath } from './_paths';
+
+// analyze() must produce the same ScanResult under all three FileSource impls
+// (node / browser FS Access / tauri). browser+tauri use in-process mocks here.
+
+const REFERENCE_ROOT = fixturePath('../fixtures/reference');
+
+const SUPPORTED_EXT = new Set(['.ts', '.tsx', '.js', '.jsx', '.vue', '.svelte', '.mjs', '.cjs']);
+
+/* ------------------------------------------------------------------ */
+/* Browser File System Access mock                                     */
+/* ------------------------------------------------------------------ */
+
+function makeFileHandle(absPath: string): unknown {
+  return {
+    kind: 'file' as const,
+    name: absPath.split(pathSep).pop() ?? '',
+    async getFile() {
+      return {
+        text: async () => readFileSync(absPath, 'utf8'),
+      };
+    },
+  };
+}
+
+function makeDirHandle(absPath: string, name: string): unknown {
+  return {
+    kind: 'directory' as const,
+    name,
+    async *entries(): AsyncGenerator<[string, unknown]> {
+      const entries: Dirent[] = readdirSync(absPath, {
+        withFileTypes: true,
+        encoding: 'utf8',
+      });
+      entries.sort((a, b) => a.name.localeCompare(b.name));
+      for (const entry of entries) {
+        const childAbs = join(absPath, entry.name);
+        if (entry.isDirectory()) {
+          yield [entry.name, makeDirHandle(childAbs, entry.name)];
+        } else if (entry.isFile()) {
+          yield [entry.name, makeFileHandle(childAbs)];
+        }
+      }
+    },
+    async getDirectoryHandle(child: string): Promise<unknown> {
+      const childAbs = join(absPath, child);
+      if (!existsSync(childAbs) || !statSync(childAbs).isDirectory()) {
+        throw new Error(`No such dir: ${child}`);
+      }
+      return makeDirHandle(childAbs, child);
+    },
+    async getFileHandle(child: string): Promise<unknown> {
+      const childAbs = join(absPath, child);
+      if (!existsSync(childAbs) || !statSync(childAbs).isFile()) {
+        throw new Error(`No such file: ${child}`);
+      }
+      return makeFileHandle(childAbs);
+    },
+  };
+}
+
+/* ------------------------------------------------------------------ */
+/* Tauri invoke mock                                                   */
+/* ------------------------------------------------------------------ */
+
+function isPathEscape(rel: string): boolean {
+  // mirrors read_file / file_exists in src-tauri/src/commands.rs
+  if (/^(?:[a-zA-Z]:)?[\\/]/.test(rel)) return true;
+  return rel.split(/[\\/]/).some((segment) => segment === '..');
+}
+
+function listTreeLikeRust(rootAbs: string): string[] {
+  // mirrors read_project_tree in src-tauri/src/commands.rs
+  const ig = ignore();
+  const gitignore = join(rootAbs, '.gitignore');
+  if (existsSync(gitignore)) {
+    ig.add(readFileSync(gitignore, 'utf8'));
+  }
+  const out: string[] = [];
+  const walk = (absDir: string): void => {
+    let entries: Dirent[];
+    try {
+      entries = readdirSync(absDir, { withFileTypes: true, encoding: 'utf8' });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      const abs = join(absDir, entry.name);
+      const rel = pathRelative(rootAbs, abs).split(pathSep).join('/');
+      if (entry.isDirectory()) {
+        if (ig.ignores(`${rel}/`)) continue;
+        walk(abs);
+        continue;
+      }
+      if (!entry.isFile()) continue;
+      if (ig.ignores(rel)) continue;
+      const ext = entry.name.slice(entry.name.lastIndexOf('.')).toLowerCase();
+      if (!SUPPORTED_EXT.has(ext)) continue;
+      out.push(rel);
+    }
+  };
+  walk(rootAbs);
+  return out.sort();
+}
+
+function buildTauriInvoke(
+  rootAbs: string,
+): <T>(cmd: string, args?: Record<string, unknown>) => Promise<T> {
+  return (async (cmd: string, args?: Record<string, unknown>) => {
+    switch (cmd) {
+      case 'read_project_tree': {
+        const root = String(args?.['root'] ?? '');
+        if (root !== rootAbs) throw new Error(`root mismatch: ${root}`);
+        return listTreeLikeRust(root) as unknown;
+      }
+      case 'read_file': {
+        const root = String(args?.['root'] ?? '');
+        const rel = String(args?.['relative'] ?? '');
+        if (isPathEscape(rel)) throw new Error('invalid relative path');
+        return readFileSync(join(root, rel), 'utf8') as unknown;
+      }
+      case 'file_exists': {
+        const root = String(args?.['root'] ?? '');
+        const rel = String(args?.['relative'] ?? '');
+        if (isPathEscape(rel)) throw new Error('invalid relative path');
+        const abs = join(root, rel);
+        return (existsSync(abs) && statSync(abs).isFile()) as unknown;
+      }
+      default:
+        throw new Error(`unknown tauri command in mock: ${cmd}`);
+    }
+  }) as <T>(cmd: string, args?: Record<string, unknown>) => Promise<T>;
+}
+
+/* ------------------------------------------------------------------ */
+/* Canonicalization                                                    */
+/* ------------------------------------------------------------------ */
+
+// drop wall-clock + project.id/rootPath so only scan semantics are compared
+function canonicalize(r: ScanResult) {
+  const edges = r.edges
+    .map((e) => ({
+      from: e.from,
+      to: e.to,
+      kind: e.kind,
+      specifier: e.specifier,
+      resolved: e.resolved,
+    }))
+    .sort((a, b) => {
+      const k = a.from.localeCompare(b.from);
+      if (k !== 0) return k;
+      const t = a.to.localeCompare(b.to);
+      if (t !== 0) return t;
+      const kk = a.kind.localeCompare(b.kind);
+      if (kk !== 0) return kk;
+      return a.specifier.localeCompare(b.specifier);
+    });
+
+  const modules = r.modules
+    .map((m) => ({
+      id: m.id,
+      kind: m.kind,
+      language: m.language,
+      loc: m.loc,
+      exports: [...m.exports].sort(),
+      isInfra: m.isInfra,
+    }))
+    .sort((a, b) => a.id.localeCompare(b.id));
+
+  const cycles = r.cycles
+    .map((c) => ({
+      length: c.length,
+      severity: c.severity,
+      modules: [...c.modules].sort(),
+    }))
+    .sort((a, b) => a.modules[0]!.localeCompare(b.modules[0]!));
+
+  const recommendations = r.recommendations
+    .map((rec) => ({
+      id: rec.id,
+      kind: rec.kind,
+      modules: [...rec.modules].sort(),
+      weight: rec.weight,
+    }))
+    .sort((a, b) => a.id.localeCompare(b.id));
+
+  const layerViolations = [...r.layerViolations]
+    .map((v) => ({ from: v.from, to: v.to, fromLayer: v.fromLayer, toLayer: v.toLayer }))
+    .sort((a, b) => {
+      const k = a.from.localeCompare(b.from);
+      return k !== 0 ? k : a.to.localeCompare(b.to);
+    });
+
+  const hotZones = [...r.hotZones].sort();
+
+  // round metrics to 3 decimals to dodge iteration-order FP drift
+  type CanonMetric = {
+    fanIn: number;
+    fanOut: number;
+    instability: number;
+    depth: number;
+    inCycle: boolean;
+    couplingScore: number;
+    hotnessScore: number;
+  };
+  const metricEntries: Array<[string, CanonMetric]> = Object.entries(r.metrics).map(([id, m]) => [
+    id,
+    {
+      fanIn: m.fanIn,
+      fanOut: m.fanOut,
+      instability: Math.round(m.instability * 1000) / 1000,
+      depth: m.depth,
+      inCycle: m.inCycle,
+      couplingScore: Math.round(m.couplingScore * 1000) / 1000,
+      hotnessScore: Math.round(m.hotnessScore * 1000) / 1000,
+    },
+  ]);
+  metricEntries.sort((a, b) => a[0].localeCompare(b[0]));
+  const metrics = Object.fromEntries(metricEntries);
+
+  return {
+    framework: r.project.detectedFramework,
+    modules,
+    edges,
+    cycles,
+    recommendations,
+    layerViolations,
+    hotZones,
+    metrics,
+    archDebt: {
+      grade: r.archDebt.grade,
+      score: r.archDebt.score,
+    },
+  };
+}
+
+/* ------------------------------------------------------------------ */
+/* Test grid                                                           */
+/* ------------------------------------------------------------------ */
+
+function listReferenceProjects(): string[] {
+  try {
+    return readdirSync(REFERENCE_ROOT)
+      .filter((name) => {
+        const full = join(REFERENCE_ROOT, name);
+        try {
+          return statSync(full).isDirectory();
+        } catch {
+          return false;
+        }
+      })
+      .sort();
+  } catch {
+    return [];
+  }
+}
+
+const projects = listReferenceProjects();
+
+describe.skipIf(projects.length === 0)('cross-source consistency', () => {
+  for (const name of projects) {
+    it(`${name}: Node / Browser / Tauri sources agree`, async () => {
+      await assertSourcesAgree(join(REFERENCE_ROOT, name), name);
+    });
+  }
+});
+
+// reference fixtures don't ship a .gitignore - copy one over in a tempdir
+describe('cross-source gitignore parity', () => {
+  it('.gitignore applies equally on a non-git fixture', async () => {
+    const fixture = fixturePath('../fixtures/reference/vue-spa-basic');
+    const { mkdtempSync, cpSync, writeFileSync, rmSync } = await import('node:fs');
+    const { tmpdir } = await import('node:os');
+    const tmp = mkdtempSync(join(tmpdir(), 'archora-gi-'));
+    try {
+      cpSync(fixture, tmp, { recursive: true });
+      writeFileSync(join(tmp, '.gitignore'), 'src/views/\n', 'utf8');
+      await assertSourcesAgree(tmp, 'vue-spa-basic+gitignore');
+    } finally {
+      rmSync(tmp, { recursive: true, force: true });
+    }
+  });
+});
+
+async function assertSourcesAgree(rootAbs: string, label: string): Promise<void> {
+  const nodeSource = await createNodeFsFileSource({ rootPath: rootAbs });
+  const browserSource = await createBrowserFsAccessFileSource({
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    rootHandle: makeDirHandle(rootAbs, label) as any,
+  });
+  const tauriSource = await createTauriFileSource({
+    rootPath: rootAbs,
+    invoke: buildTauriInvoke(rootAbs),
+  });
+
+  const [nodeResult, browserResult, tauriResult] = await Promise.all([
+    analyze(nodeSource),
+    analyze(browserSource),
+    analyze(tauriSource),
+  ]);
+
+  const nodeCanon = canonicalize(nodeResult);
+  const browserCanon = canonicalize(browserResult);
+  const tauriCanon = canonicalize(tauriResult);
+
+  expect(browserCanon, `[${label}] Browser vs Node mismatch`).toEqual(nodeCanon);
+  expect(tauriCanon, `[${label}] Tauri vs Node mismatch`).toEqual(nodeCanon);
+}