@archora/core 1.3.0 → 2.0.0

package/src/analyzer/memoryRisk.ts

@@ -41,7 +41,7 @@ const PATTERNS: readonly RiskPattern[] = [
     kind: 'timer-cleanup',
     acquire: 'setTimeout',
     cleanup: 'clearTimeout',
-    testAcquire: isNamedCall('setTimeout'),
+    testAcquire: isCapturedTimer('setTimeout'),
     testCleanup: isNamedCall('clearTimeout'),
   },
   {
@@ -81,7 +81,9 @@ export async function detectMemoryRisks(
       module.id,
       script,
       ts.ScriptTarget.Latest,
-      false,
+      // Parent links are needed to tell a captured `setTimeout` handle from a
+      // discarded fire-and-forget call (see isCapturedResult).
+      true,
       scriptKindFor(module.id),
     );
     const context: RiskContext = {
@@ -255,6 +257,35 @@ function isNamedCall(name: string): (node: ts.Node) => boolean {
   return (node) => ts.isCallExpression(node) && callName(node.expression) === name;
 }
 
+// A bare `setTimeout(fn, n)` expression statement is fire-and-forget and needs no
+// cleanup. Flag only when the timer id is captured (assigned, stored on a property,
+// returned, or passed on), since a kept handle signals the author intended it to be
+// cancellable and leaving it uncleared is the suspicious case.
+function isCapturedTimer(name: string): (node: ts.Node) => boolean {
+  const matchesCall = isNamedCall(name);
+  return (node) => matchesCall(node) && isCapturedResult(node);
+}
+
+function isCapturedResult(node: ts.Node): boolean {
+  const parent = node.parent;
+  if (!parent) return false;
+  if (ts.isVariableDeclaration(parent)) return parent.initializer === node;
+  if (ts.isPropertyDeclaration(parent)) return parent.initializer === node;
+  if (ts.isPropertyAssignment(parent)) return parent.initializer === node;
+  if (ts.isBinaryExpression(parent)) {
+    return parent.operatorToken.kind === ts.SyntaxKind.EqualsToken && parent.right === node;
+  }
+  if (ts.isReturnStatement(parent)) return parent.expression === node;
+  if (ts.isCallExpression(parent) || ts.isNewExpression(parent)) {
+    return parent.arguments?.some((arg) => arg === node) ?? false;
+  }
+  // Parenthesized / as-expression wrappers keep the handle reachable.
+  if (ts.isParenthesizedExpression(parent) || ts.isAsExpression(parent)) {
+    return isCapturedResult(parent);
+  }
+  return false;
+}
+
 function isIdentifierCall(node: ts.CallExpression, name: string): boolean {
   return ts.isIdentifier(node.expression) && node.expression.text === name;
 }

package/src/analyzer/recommendations.ts

@@ -43,10 +43,10 @@ export function computeRecommendations(inputs: {
    */
   bundleBloat?: BundleBloat[];
   /**
-   * Temporal couplings. Only the subset already filtered by
-   * the detector lands here — we further narrow to "hidden" couplings
-   * (no static edge between the pair), since visible ones duplicate signal
-   * the dependency graph already exposes.
+   * Temporal couplings (already risk-sorted by the detector). We narrow to
+   * pairs that are BOTH hidden (no static edge — visible ones duplicate the
+   * dependency graph) AND cross-boundary (different top-level groups), the only
+   * intersection worth a recommendation. Same-group co-change is batch-PR noise.
    */
   temporalCoupling?: TemporalCoupling[];
 }): Recommendation[] {
@@ -250,14 +250,18 @@ export function computeRecommendations(inputs: {
     }
   }
 
-  // 8. temporal coupling: only the *hidden* couplings — pairs
-  // that change together a lot AND have no static edge. The dependency
-  // graph already shows the rest. Weight scales with score: a 0.9 score
-  // pair ranks alongside a god-module rec, a 0.5 pair sits below cycle
-  // breaks. Cap at 8 to keep the panel readable on big histories.
+  // 8. temporal coupling: only the couplings that are BOTH hidden (no static
+  // edge — the dependency graph already shows the rest) AND cross-boundary
+  // (the two modules live in different top-level groups). That intersection is
+  // the actionable "missing abstraction / leaky boundary" smell; everything
+  // else is same-folder co-change a batch PR produces by the dozen. The raw
+  // list is risk-sorted, so the filter keeps the highest-risk pairs first.
+  // Cap at 10 to keep the panel readable on big histories.
   if (inputs.temporalCoupling && inputs.temporalCoupling.length > 0) {
-    const hidden = inputs.temporalCoupling.filter((c) => c.hidden).slice(0, 8);
-    for (const c of hidden) {
+    const couplings = inputs.temporalCoupling
+      .filter((c) => c.hidden && c.crossBoundary)
+      .slice(0, 10);
+    for (const c of couplings) {
       out.push({
         id: `temporal:${c.a}\x00${c.b}`,
         kind: 'temporal-coupling',

package/src/analyzer/resolve.ts

@@ -184,9 +184,20 @@ export function parseTsconfigPaths(content: string): PathAlias[] {
   const baseUrl = (opts.baseUrl ?? '.').replace(/\/+$/u, '');
   const aliases: PathAlias[] = [];
   for (const [key, list] of Object.entries(opts.paths)) {
-    const prefix = trimSuffix(key, '/*');
-    const targets = list.map((t) => joinPosix(baseUrl, trimSuffix(t, '/*')));
-    aliases.push({ prefix, targets });
+    if (key.endsWith('/*')) {
+      // `@x/*`: prefix-strip + suffix-append. Targets keep an interior `*`
+      // (e.g. `packages/*/src`) so the captured suffix is substituted at the
+      // star instead of being appended to a directory that does not exist.
+      const prefix = trimSuffix(key, '/*');
+      const targets = list.map((t) =>
+        t.includes('*') ? joinPosixKeepStar(baseUrl, trimSuffix(t, '/*')) : joinPosix(baseUrl, t),
+      );
+      aliases.push({ prefix, targets });
+      continue;
+    }
+    // exact tsconfig path (no wildcard): `vue` -> `packages/vue/src`.
+    const targets = list.map((t) => joinPosix(baseUrl, t));
+    aliases.push({ prefix: key, targets, exact: true });
   }
   aliases.sort((a, b) => b.prefix.length - a.prefix.length);
   return aliases;
@@ -263,7 +274,13 @@ export function applyAlias(spec: string, aliases: PathAlias[]): string[] {
     const isWildcard = alias.prefix.length > 0;
     if (isWildcard && (spec === alias.prefix || spec.startsWith(`${alias.prefix}/`))) {
       const suffix = spec.slice(alias.prefix.length).replace(/^\//u, '');
-      return alias.targets.map((t) => (suffix ? joinPosix(t, suffix) : t));
+      return alias.targets.map((t) =>
+        t.includes('*')
+          ? normalizePosix(t.replace('*', suffix))
+          : suffix
+            ? joinPosix(t, suffix)
+            : t,
+      );
     }
     if (alias.prefix === '' && !isWildcard) {
       return alias.targets.map((t) => joinPosix(t, spec));
@@ -302,6 +319,14 @@ function joinPosix(...parts: string[]): string {
   return normalizePosix(filtered.join('/'));
 }
 
+// Like joinPosix but preserves an interior `*` segment (tsconfig `paths`
+// substitution target such as `packages/*/src`). normalizePosix would drop
+// nothing for `*`, but the `*` must survive joining with baseUrl untouched.
+function joinPosixKeepStar(base: string, target: string): string {
+  if (!base || base === '.') return target;
+  return `${base}/${target}`.replace(/\/+/gu, '/');
+}
+
 function posixDirname(p: string): string {
   const i = p.lastIndexOf('/');
   return i === -1 ? '' : p.slice(0, i);

package/src/analyzer/rsc.ts

@@ -75,6 +75,19 @@ export function classifyModuleRuntime(input: ClassifyRuntimeInput): ModuleRuntim
   return 'shared';
 }
 
+/**
+ * A `'use server'` directive marks a Next.js Server Actions module: it is
+ * server runtime, but it is *meant* to be imported from client components
+ * (forms/mutations), so a client->this edge is not an `rsc-leak`. Distinct from
+ * server-only modules (`server-only` package / server component / endpoint
+ * conventions), whose import from a client is a real leak. Directives win over
+ * conventions in `classifyModuleRuntime`, so the directive is an authoritative
+ * reason here.
+ */
+export function isServerActionsModule(directives?: ParsedFile['directives']): boolean {
+  return !!directives && directives.includes('use server');
+}
+
 export interface DetectRscLeaksInput {
   modules: ModuleNode[];
   edges: DependencyEdge[];
@@ -97,6 +110,10 @@ export function detectRscLeaks(input: DetectRscLeaksInput): ContractViolation[]
     const from = moduleById.get(e.from);
     const to = moduleById.get(e.to);
     if (!from || !to) continue;
+    // Server Actions (`'use server'`) are server runtime but designed to be
+    // imported from client components — that edge is the intended Next.js
+    // pattern, not a leak.
+    if (to.isServerActions) continue;
     const leak = classifyLeak(from.runtime ?? 'shared', to.runtime ?? 'shared');
     if (!leak) continue;
     directLeaks.add(`${from.id}->${to.id}`);
@@ -142,7 +159,7 @@ export function detectRscLeaks(input: DetectRscLeaksInput): ContractViolation[]
       const node = queue.shift()!;
       for (const to of adj.get(node) ?? []) {
         const toRt = rt(to);
-        if (toRt === 'server') {
+        if (toRt === 'server' && !moduleById.get(to)?.isServerActions) {
           const key = `${c.id}->${to}`;
           if (directLeaks.has(key) || seenTransitive.has(key)) continue;
           seenTransitive.add(key);

package/src/analyzer/types.ts

@@ -65,7 +65,24 @@ export interface ModuleNode {
    * Defaults to `'shared'` when nothing pins it down.
    */
   runtime?: ModuleRuntime;
+  /**
+   * Module is server because of a `'use server'` directive — a Next.js Server
+   * Actions module, designed to be imported and called from client components
+   * (Next compiles the exports into RPC references; nothing server-only ships).
+   * A client->server-actions edge is the intended pattern and is NOT an
+   * `rsc-leak`, unlike client->server-only (`server-only` package / server
+   * component / endpoint conventions). Set only when `'use server'` is the
+   * classification reason.
+   */
+  isServerActions?: boolean;
   isGenerated?: boolean;
+  /**
+   * Re-export barrel (e.g. `index.ts` re-exporting every sibling). High fan-out
+   * is its purpose, not a risk — so barrels are excluded from hot zones and
+   * "split this module" advice. Detected post-graph, where parsed export facts
+   * and the fan-out metric are both available.
+   */
+  isBarrel?: boolean;
 }
 
 export type ModuleRuntime = 'server' | 'client' | 'shared';

package/src/cache/index.ts

@@ -30,10 +30,25 @@ import { incrementalAnalyze } from '../analyzer/incremental';
 import { discoverFiles } from '../analyzer/discover';
 
 /**
- * Bump whenever the on-disk shape of `ScanResult` or the manifest changes.
- * A mismatch causes `loadCache` to treat the entry as missing.
+ * Bump whenever the on-disk shape of `ScanResult`/manifest changes, OR whenever
+ * the analyzer's OUTPUT semantics change (new/changed findings, ranking, or
+ * filtering) — otherwise a warm cache keyed only on source+tool version serves
+ * stale results that don't reflect the improved analysis. A mismatch causes
+ * `loadCache` to treat the entry as missing.
+ *
+ * v3: barrel modules excluded from hot zones; temporal-coupling findings limited
+ *     to hidden cross-boundary pairs.
+ * v4: tsconfig path wildcards with an interior star (key @x/* mapping to target
+ *     pkgs/[star]/src) now resolve, so cross-package edges that were previously
+ *     dropped appear in the graph.
+ * v5: timer-cleanup memory risk no longer flags bare fire-and-forget setTimeout
+ *     calls; only captured (stored/returned/passed) timer handles without
+ *     clearTimeout are reported, reducing false positives.
+ * v7: modules carry `isServerActions`; `rsc-leak` no longer flags client
+ *     imports of `'use server'` Server Actions modules (the intended Next.js
+ *     pattern), only client->server-only imports.
  */
-export const CACHE_FORMAT_VERSION = 2;
+export const CACHE_FORMAT_VERSION = 7;
 
 /**
  * Marker used inside `node_modules/.cache/archora/`. Also the directory

package/src/diff/__tests__/diffScans.test.ts

@@ -1,6 +1,12 @@
 import { describe, it, expect } from 'vitest';
 import { diffScans } from '../diffScans';
-import type { Cycle, ModuleNode, ScanResult } from '../../analyzer/types';
+import type {
+  ContractViolation,
+  Cycle,
+  LayerViolation,
+  ModuleNode,
+  ScanResult,
+} from '../../analyzer/types';
 
 function mod(id: string, overrides: Partial<ModuleNode> = {}): ModuleNode {
   return {
@@ -24,6 +30,33 @@ function cycle(id: string, modules: string[]): Cycle {
   };
 }
 
+function layerViolation(edgeId: string, overrides: Partial<LayerViolation> = {}): LayerViolation {
+  return {
+    edgeId,
+    from: 'src/a.ts',
+    to: 'src/b.ts',
+    fromLayer: 'features',
+    toLayer: 'app',
+    severity: 'error',
+    ...overrides,
+  };
+}
+
+function contractViolation(
+  id: string,
+  overrides: Partial<ContractViolation> = {},
+): ContractViolation {
+  return {
+    id,
+    kind: 'boundary',
+    ruleName: 'no-cross-layer',
+    severity: 'error',
+    message: 'boundary violation',
+    modules: ['src/a.ts'],
+    ...overrides,
+  };
+}
+
 function scan(overrides: Partial<ScanResult>): ScanResult {
   return {
     project: { id: 'p', name: 'p', rootPath: '/p', detectedFramework: 'unknown' },
@@ -98,6 +131,36 @@ describe('diffScans', () => {
       changedModules: 0,
       newCycles: 0,
       resolvedCycles: 0,
+      newLayerViolations: 0,
+      newContractViolations: 0,
     });
   });
+
+  it('diffs layer violations by edgeId', () => {
+    const shared = layerViolation('edge:a→b');
+    const prev = scan({
+      layerViolations: [shared, layerViolation('edge:c→d')],
+    });
+    const next = scan({
+      layerViolations: [shared, layerViolation('edge:e→f')],
+    });
+    const d = diffScans(prev, next);
+    expect(d.newLayerViolations.map((v) => v.edgeId)).toEqual(['edge:e→f']);
+    expect(d.resolvedLayerViolations.map((v) => v.edgeId)).toEqual(['edge:c→d']);
+    expect(d.summary.newLayerViolations).toBe(1);
+  });
+
+  it('diffs contract violations by id', () => {
+    const shared = contractViolation('boundary:auth:0');
+    const prev = scan({
+      contractViolations: [shared, contractViolation('boundary:payment:0')],
+    });
+    const next = scan({
+      contractViolations: [shared, contractViolation('boundary:cart:0')],
+    });
+    const d = diffScans(prev, next);
+    expect(d.newContractViolations.map((v) => v.id)).toEqual(['boundary:cart:0']);
+    expect(d.resolvedContractViolations.map((v) => v.id)).toEqual(['boundary:payment:0']);
+    expect(d.summary.newContractViolations).toBe(1);
+  });
 });

package/src/diff/diffScans.ts

@@ -1,4 +1,4 @@
-import type { Cycle, ScanResult } from '../analyzer/types';
+import type { ContractViolation, Cycle, LayerViolation, ScanResult } from '../analyzer/types';
 import type { ChangedModule, ScanDiff } from './types';
 
 // module id = project-relative path; cycle id = sorted member set.
@@ -35,6 +35,30 @@ export function diffScans(prev: ScanResult, next: ScanResult): ScanDiff {
     if (!nextCyclesByKey.has(key)) resolvedCycles.push(cycle);
   }
 
+  const prevLayerByEdge = new Map(prev.layerViolations.map((v) => [v.edgeId, v]));
+  const nextLayerByEdge = new Map(next.layerViolations.map((v) => [v.edgeId, v]));
+
+  const newLayerViolations: LayerViolation[] = [];
+  for (const [edgeId, v] of nextLayerByEdge) {
+    if (!prevLayerByEdge.has(edgeId)) newLayerViolations.push(v);
+  }
+  const resolvedLayerViolations: LayerViolation[] = [];
+  for (const [edgeId, v] of prevLayerByEdge) {
+    if (!nextLayerByEdge.has(edgeId)) resolvedLayerViolations.push(v);
+  }
+
+  const prevContractById = new Map(prev.contractViolations.map((v) => [v.id, v]));
+  const nextContractById = new Map(next.contractViolations.map((v) => [v.id, v]));
+
+  const newContractViolations: ContractViolation[] = [];
+  for (const [id, v] of nextContractById) {
+    if (!prevContractById.has(id)) newContractViolations.push(v);
+  }
+  const resolvedContractViolations: ContractViolation[] = [];
+  for (const [id, v] of prevContractById) {
+    if (!nextContractById.has(id)) resolvedContractViolations.push(v);
+  }
+
   return {
     projectId: next.project.id,
     projectName: next.project.name,
@@ -45,12 +69,18 @@ export function diffScans(prev: ScanResult, next: ScanResult): ScanDiff {
     changedModules,
     newCycles,
     resolvedCycles,
+    newLayerViolations,
+    resolvedLayerViolations,
+    newContractViolations,
+    resolvedContractViolations,
     summary: {
       addedModules: addedModules.length,
       removedModules: removedModules.length,
       changedModules: changedModules.length,
       newCycles: newCycles.length,
       resolvedCycles: resolvedCycles.length,
+      newLayerViolations: newLayerViolations.length,
+      newContractViolations: newContractViolations.length,
     },
   };
 }

package/src/diff/types.ts

@@ -1,4 +1,10 @@
-import type { Cycle, ModuleId, ModuleNode } from '../analyzer/types';
+import type {
+  ContractViolation,
+  Cycle,
+  LayerViolation,
+  ModuleId,
+  ModuleNode,
+} from '../analyzer/types';
 
 export interface ScanDiff {
   /** Project id and name from the *current* (newer) scan, for display. */
@@ -20,6 +26,16 @@ export interface ScanDiff {
   /** Cycles that disappeared in `next`. */
   resolvedCycles: Cycle[];
 
+  /** Layer violations whose `edgeId` is absent from `prev`. */
+  newLayerViolations: LayerViolation[];
+  /** Layer violations whose `edgeId` was present in `prev` but not in `next`. */
+  resolvedLayerViolations: LayerViolation[];
+
+  /** Contract violations whose `id` is absent from `prev`. */
+  newContractViolations: ContractViolation[];
+  /** Contract violations whose `id` was present in `prev` but not in `next`. */
+  resolvedContractViolations: ContractViolation[];
+
   /** Aggregate counts for quick rendering at the top of a diff view. */
   summary: ScanDiffSummary;
 }
@@ -36,4 +52,6 @@ export interface ScanDiffSummary {
   changedModules: number;
   newCycles: number;
   resolvedCycles: number;
+  newLayerViolations: number;
+  newContractViolations: number;
 }

package/src/git/computeTemporalCoupling.ts

@@ -30,7 +30,11 @@ const DEFAULTS: Required<TemporalCouplingThresholds> = {
   minCoOccurrences: 3,
   minScore: 0.5,
   maxPairs: 100,
-  commitFanOutCap: 50,
+  // Batch PRs (codegen bumps, "touch every composable" passes) co-change dozens
+  // of files at once and flood the raw list with same-group noise. A real
+  // architectural coupling shows up in small, focused commits, so cap fan-out
+  // tighter than a typical batch PR.
+  commitFanOutCap: 30,
 };
 
 export function computeTemporalCoupling(input: ComputeTemporalCouplingInput): TemporalCoupling[] {

package/src/index.ts

@@ -31,6 +31,11 @@ export {
   type FixPlanRepairGroup,
   type BuildFixPlanOptions,
 } from './report/buildFixPlan';
+export {
+  buildDeadCodeReport,
+  type DeadCodeReport,
+  type DeadCodeCandidate,
+} from './report/buildDeadCodeReport';
 export { diffScans, type ScanDiff, type ChangedModule, type ScanDiffSummary } from './diff/index';
 export { compileGlob } from './analyzer/discover';
 export {

package/src/report/__tests__/buildDeadCodeReport.test.ts

@@ -0,0 +1,108 @@
+import { describe, expect, it } from 'vitest';
+import { buildDeadCodeReport } from '../buildDeadCodeReport';
+import type { ScanResult } from '../../analyzer/types';
+
+describe('buildDeadCodeReport', () => {
+  it('returns candidates with correct groups and totalLoc, excluding non-qualifying modules', () => {
+    const scan = scanFixture();
+    const report = buildDeadCodeReport(scan);
+
+    // entry-kind, live module (fanIn>0), and test file must be excluded
+    const ids = report.candidates.map((c) => c.id);
+    expect(ids).not.toContain('src/app/main.ts');
+    expect(ids).not.toContain('src/features/active/model.ts');
+    expect(ids).not.toContain('src/utils/parse.test.ts');
+
+    // isolated source module and script-entry must be included
+    expect(ids).toContain('src/legacy/orphan.ts');
+    expect(ids).toContain('scripts/seed.mjs');
+
+    // groups
+    const orphan = report.candidates.find((c) => c.id === 'src/legacy/orphan.ts');
+    expect(orphan?.group).toBe('isolated');
+    expect(orphan?.loc).toBe(40);
+
+    const script = report.candidates.find((c) => c.id === 'scripts/seed.mjs');
+    expect(script?.group).toBe('script-entry');
+
+    // counts
+    expect(report.isolatedCount).toBe(1);
+    expect(report.scriptEntryCount).toBe(1);
+    expect(report.candidates).toHaveLength(2);
+
+    // totalLoc = sum of candidate locs
+    expect(report.totalLoc).toBe(40 + 8);
+
+    // sorted by loc desc
+    expect(report.candidates.map((c) => c.id)).toEqual([
+      'src/legacy/orphan.ts',
+      'scripts/seed.mjs',
+    ]);
+  });
+
+  it('returns an empty report when no dead modules exist', () => {
+    const report = buildDeadCodeReport({
+      ...scanFixture(),
+      modules: [mod('src/app/main.ts', 'entry', 20)],
+      metrics: {},
+    });
+    expect(report.candidates).toHaveLength(0);
+    expect(report.totalLoc).toBe(0);
+    expect(report.isolatedCount).toBe(0);
+    expect(report.scriptEntryCount).toBe(0);
+  });
+});
+
+function scanFixture(): ScanResult {
+  return {
+    project: { id: 'test', name: 'test', rootPath: '/repo', detectedFramework: 'generic' },
+    modules: [
+      mod('src/app/main.ts', 'entry', 15),
+      mod('src/features/active/model.ts', 'model', 30),
+      mod('src/legacy/orphan.ts', 'module', 40),
+      mod('scripts/seed.mjs', 'module', 8),
+      mod('src/utils/parse.test.ts', 'test', 20),
+    ],
+    edges: [],
+    cycles: [],
+    metrics: {
+      'src/app/main.ts': metric(1, 2),
+      'src/features/active/model.ts': metric(3, 1),
+      'src/legacy/orphan.ts': metric(0, 0),
+      'scripts/seed.mjs': metric(0, 0),
+      'src/utils/parse.test.ts': metric(0, 0),
+    },
+    hotZones: [],
+    layerViolations: [],
+    archDebt: {
+      score: 0,
+      grade: 'A',
+      breakdown: { cycles: 0, layerViolations: 0, hotZones: 0, coupling: 0 },
+    },
+    recommendations: [],
+    contractViolations: [],
+    scannedAt: '2026-06-21T00:00:00.000Z',
+    durationMs: 1,
+    warnings: [],
+  };
+}
+
+function mod(
+  id: string,
+  kind: ScanResult['modules'][number]['kind'],
+  loc: number,
+): ScanResult['modules'][number] {
+  return { id, absPath: `/repo/${id}`, kind, language: 'ts', loc, exports: [], isInfra: false };
+}
+
+function metric(fanIn: number, fanOut: number): ScanResult['metrics'][string] {
+  return {
+    fanIn,
+    fanOut,
+    instability: 0,
+    depth: 0,
+    inCycle: false,
+    couplingScore: 0,
+    hotnessScore: 0,
+  };
+}

package/src/report/buildDeadCodeReport.ts

@@ -0,0 +1,110 @@
+import type { ModuleId, ModuleNode, ScanResult } from '../analyzer/types';
+
+export interface DeadCodeCandidate {
+  id: ModuleId;
+  loc: number;
+  kind: ModuleNode['kind'];
+  group: 'isolated' | 'script-entry';
+  reason: string;
+}
+
+export interface DeadCodeReport {
+  candidates: DeadCodeCandidate[];
+  /** Sum of candidate loc — the reclaimable LOC estimate. */
+  totalLoc: number;
+  isolatedCount: number;
+  scriptEntryCount: number;
+}
+
+const DEAD_MODULE_REASON =
+  'No resolved imports connect this module to the analyzed dependency model.';
+
+export function buildDeadCodeReport(scan: ScanResult): DeadCodeReport {
+  const candidates: DeadCodeCandidate[] = [];
+
+  for (const module of scan.modules) {
+    if (!isReviewModule(module.id)) continue;
+    const metrics = scan.metrics[module.id];
+    const fanIn = metrics?.fanIn ?? 0;
+    const fanOut = metrics?.fanOut ?? 0;
+    if (
+      fanIn === 0 &&
+      fanOut === 0 &&
+      module.exports.length === 0 &&
+      module.kind !== 'entry' &&
+      module.kind !== 'test' &&
+      !module.isGenerated &&
+      !module.isInfra
+    ) {
+      candidates.push({
+        id: module.id,
+        loc: module.loc,
+        kind: module.kind,
+        group: isScriptEntryCandidate(module.id) ? 'script-entry' : 'isolated',
+        reason: DEAD_MODULE_REASON,
+      });
+    }
+  }
+
+  candidates.sort((a, b) => b.loc - a.loc || a.id.localeCompare(b.id));
+
+  const totalLoc = candidates.reduce((sum, c) => sum + c.loc, 0);
+  const isolatedCount = candidates.filter((c) => c.group === 'isolated').length;
+  const scriptEntryCount = candidates.filter((c) => c.group === 'script-entry').length;
+
+  return { candidates, totalLoc, isolatedCount, scriptEntryCount };
+}
+
+/**
+ * Repair action and verify text for an unreachable module finding.
+ * Shared with buildFixPlan so the two never diverge.
+ */
+export function unreachableRepair(id: ModuleId): {
+  action: string;
+  verify: string;
+  params: Record<string, unknown>;
+} {
+  if (isScriptEntryCandidate(id)) {
+    return {
+      action: `Treat ${id} as a script entry: add it to architecture entry configuration or exclude it from review scope; delete only after confirming no package script or CI job calls it.`,
+      verify:
+        'Run archora report . --format fix-plan after entry/exclude config and confirm this script is no longer a priority finding.',
+      params: { entryCandidate: 'script' },
+    };
+  }
+
+  return {
+    action:
+      'Check whether this file is dead code, dynamically loaded outside analyzer reach, or should be declared as an entry point.',
+    verify:
+      'Re-scan after deletion, ignore, or entry-point configuration and confirm the candidate is gone.',
+    params: {},
+  };
+}
+
+/**
+ * Matches modules that should go through architecture review.
+ * Excludes fixture directories and test files — same predicate as buildFixPlan.
+ */
+export function isReviewModule(id: ModuleId): boolean {
+  return !/(^|\/)(fixtures|test\/fixtures|__fixtures__|__tests__|__mocks__)(\/|$)|\.(test|spec)\./u.test(
+    id,
+  );
+}
+
+/**
+ * Heuristic: a file directly under a `scripts/` directory with a JS extension
+ * is likely a standalone Node script, not a dead module.
+ */
+export function isScriptEntryCandidate(id: ModuleId): boolean {
+  const normalized = id.replace(/\\/gu, '/');
+  let scriptsIndex = 0;
+  if (!normalized.startsWith('scripts/')) {
+    const nestedIndex = normalized.indexOf('/scripts/');
+    if (nestedIndex < 0) return false;
+    scriptsIndex = nestedIndex + 1;
+  }
+  const file = normalized.slice(scriptsIndex + 'scripts/'.length);
+  if (!file) return false;
+  return file.endsWith('.js') || file.endsWith('.cjs') || file.endsWith('.mjs');
+}