fix: exclude test files from coverage/coupling metrics (#12)

## Summary

Fixes #7

- Added `isTestFile` detection to FileMetrics (matches `.test.ts`,
`.spec.tsx`, `__tests__/`, etc.)
- Filtered test files from coverage and coupling hotspot results
- Adjusted coupling formula: `fanOut / (max(fanIn, 1) + fanOut)` — leaf
consumers no longer auto-rank highest
- Updated existing tests for new coupling formula

## Test plan

- [x] Regression tests for all ACs (19 new tests)
- [x] All existing tests pass (205 total)
- [x] Quality gates: lint, typecheck, build, test

Author: bntvllnt

docs/data-model.md

@@ -63,7 +63,7 @@ FileMetrics {
   betweenness: number
   fanIn: number
   fanOut: number
-  coupling: number        // fanOut / (fanIn + fanOut)
+  coupling: number        // fanOut / (max(fanIn, 1) + fanOut)
   tension: number         // Entropy of multi-module pulls
   isBridge: boolean       // betweenness > 0.1
 
@@ -76,6 +76,7 @@ FileMetrics {
   cyclomaticComplexity: number  // Avg complexity of exports
   blastRadius: number           // Transitive dependent count
   deadExports: string[]         // Unused export names
+  isTestFile: boolean           // Whether this file is a test file
 }
 
 ModuleMetrics {

docs/metrics.md

@@ -10,7 +10,7 @@ All metrics are computed per-file and stored in `FileMetrics`. Module-level aggr
 | **betweenness** | number | 0-1 | graphology-metrics | How often file bridges shortest paths between others. Normalized. |
 | **fanIn** | number | 0-N | graph in-degree | Count of files that import this file. |
 | **fanOut** | number | 0-N | graph out-degree | Count of files this file imports. |
-| **coupling** | number | 0-1 | derived | `fanOut / (fanIn + fanOut)`. 0=pure dependency, 1=pure dependent. |
+| **coupling** | number | 0-1 | derived | `fanOut / (max(fanIn, 1) + fanOut)`. 0=pure dependency. Leaf consumers (fan_in=0) score < 1.0. |
 | **tension** | number | 0-1 | entropy | Evenness of pulls from multiple modules. >0.3 = tension. |
 | **isBridge** | boolean | - | derived | `betweenness > 0.1`. Bridges separate clusters. |
 | **churn** | number | 0-N | git log | Number of commits touching this file. 0 if not a git repo. |
@@ -19,6 +19,7 @@ All metrics are computed per-file and stored in `FileMetrics`. Module-level aggr
 | **deadExports** | string[] | - | cross-ref | Export names not consumed by any edge in the graph. |
 | **hasTests** | boolean | - | filename match | Whether a matching `.test.ts`/`.spec.ts`/`__tests__/` file exists. |
 | **testFile** | string | - | filename match | Relative path to the test file, if found. |
+| **isTestFile** | boolean | - | parser | Whether this file IS a test file (`.test.`/`.spec.`/`__tests__/`). Used to filter test files from coverage and coupling hotspots. |
 
 ## Module Metrics
 

specs/history.log

@@ -2,3 +2,4 @@
 2026-03-02 | shipped | mcp-parity-readme-sync | 3h→2h | 1d | 100% MCP-REST parity: +2 tools, enhanced 3 tools, 15 tool descriptions, README sync, 21 new tests
 2026-03-11 | shipped | fix-dead-export-false-positives | 2h→1.5h | 1d | Fix 33% false positive rate: merge duplicate imports, include same-file calls, call graph consumption. 8 regression tests.
 2026-03-11 | shipped | fix-error-handling | 1h→0.5h | 1d | Consistent impact_analysis error handling, LOC off-by-one fix, empty file guard. 17 regression tests.
+2026-03-11 | shipped | fix-metrics-test-files | 2h→1.5h | 1d | Exclude test files from coverage/coupling metrics, isTestFile detection, coupling formula fix. 19 regression tests.

specs/shipped/2026-03-11-fix-metrics-test-files.md

@@ -90,7 +90,7 @@ describe("analyzeGraph", () => {
     expect(metricsD?.fanOut).toBe(0);
   });
 
-  it("computes coupling = fanOut / (fanIn + fanOut)", () => {
+  it("computes coupling = fanOut / (max(fanIn, 1) + fanOut)", () => {
     const files = [
       makeFile("a.ts", { imports: [imp("b.ts"), imp("c.ts")] }),
       makeFile("b.ts"),
@@ -99,8 +99,8 @@ describe("analyzeGraph", () => {
     const built = buildGraph(files);
     const result = analyzeGraph(built);
 
-    // a.ts: fanIn=0, fanOut=2 → coupling = 2/(0+2) = 1.0
-    expect(result.fileMetrics.get("a.ts")?.coupling).toBe(1);
+    // a.ts: fanIn=0, fanOut=2 → coupling = 2/(max(0,1)+2) = 2/3 ≈ 0.667
+    expect(result.fileMetrics.get("a.ts")?.coupling).toBeCloseTo(2 / 3, 5);
 
     // b.ts: fanIn=1, fanOut=0 → coupling = 0/(1+0) = 0
     expect(result.fileMetrics.get("b.ts")?.coupling).toBe(0);

src/analyzer/index.test.ts

@@ -63,7 +63,7 @@ export function analyzeGraph(built: BuiltGraph, parsedFiles?: ParsedFile[]): Cod
   for (const node of fileNodes) {
     const fanIn = graph.inDegree(node.id);
     const fanOut = graph.outDegree(node.id);
-    const coupling = fanOut === 0 && fanIn === 0 ? 0 : fanOut / (fanIn + fanOut);
+    const coupling = fanOut === 0 && fanIn === 0 ? 0 : fanOut / (Math.max(fanIn, 1) + fanOut);
     const pr = pageRanks.get(node.id) ?? 0;
     const btwn = betweennessScores.get(node.id) ?? 0;
 
@@ -94,6 +94,7 @@ export function analyzeGraph(built: BuiltGraph, parsedFiles?: ParsedFile[]): Cod
       deadExports,
       hasTests: parsed?.testFile !== undefined,
       testFile: parsed?.testFile ?? "",
+      isTestFile: parsed?.isTestFile ?? false,
     });
   }
 

src/analyzer/index.ts

@@ -204,7 +204,10 @@ export function registerTools(server: McpServer, graph: CodebaseGraph): void {
           });
         }
       } else {
+        const filterTestFiles = metric === "coverage" || metric === "coupling";
         for (const [filePath, metrics] of graph.fileMetrics) {
+          if (filterTestFiles && metrics.isTestFile) continue;
+
           let score: number;
           let reason: string;
 

src/mcp/index.ts

@@ -95,6 +95,7 @@ export interface FileMetrics {
   deadExports: string[];
   hasTests: boolean;
   testFile: string;
+  isTestFile: boolean;
 }
 
 export interface ModuleMetrics {

src/types/index.ts

@@ -0,0 +1,9 @@
+import { describe, it, expect } from "vitest";
+import { UserService } from "./user-service.js";
+
+describe("UserService", () => {
+  it("should create an instance", () => {
+    const service = new UserService();
+    expect(service).toBeDefined();
+  });
+});