autodocs-engine 0.9.8 → 0.10.0

package/dist/mcp/queries.js

@@ -67,6 +67,31 @@ export function getWorkflowRules(analysis, filePath) {
         return rules;
     return rules.filter((r) => r.trigger.includes(filePath) || r.action.includes(filePath));
 }
+export function getImplicitCouplingForFile(analysis, filePath, packagePath) {
+    const pkg = resolvePackage(analysis, packagePath);
+    const edges = pkg.implicitCoupling ?? [];
+    return edges.filter((e) => e.file1 === filePath || e.file2 === filePath).sort((a, b) => b.jaccard - a.jaccard);
+}
+export function getExportedNamesForFile(analysis, filePath, packagePath) {
+    const pkg = resolvePackage(analysis, packagePath);
+    return pkg.publicAPI.filter((e) => e.sourceFile === filePath && !e.isTypeOnly).map((e) => e.name);
+}
+export function getExecutionFlows(analysis, packagePath) {
+    return resolvePackage(analysis, packagePath).executionFlows ?? [];
+}
+export function getFlowsForFiles(analysis, files, packagePath) {
+    const flows = getExecutionFlows(analysis, packagePath);
+    const fileSet = new Set(files);
+    return flows.filter((f) => f.files.some((file) => fileSet.has(file)));
+}
+export function getFlowsForFunction(analysis, fnName, packagePath) {
+    const flows = getExecutionFlows(analysis, packagePath);
+    return flows.filter((f) => f.steps.includes(fnName));
+}
+export function getImportersOfSymbol(analysis, symbol, sourceFile, packagePath) {
+    const pkg = resolvePackage(analysis, packagePath);
+    return (pkg.importChain ?? []).filter((e) => e.source === sourceFile && e.symbols.includes(symbol));
+}
 export function getContributionPatterns(analysis, packagePath, directory) {
     const pkg = resolvePackage(analysis, packagePath);
     const patterns = pkg.contributionPatterns ?? [];
@@ -360,11 +385,108 @@ function findLastExportFromLine(content) {
     return lastLine;
 }
 // ─── Diagnose Queries ───────────────────────────────────────────────────────
-// Scoring thresholds (validated by adversarial review, 10 models)
-const MISSING_CO_CHANGE_MIN_COUNT = 5; // Minimum co-change frequency to activate signal
-const MISSING_CO_CHANGE_MIN_JACCARD = 0.4; // Minimum Jaccard coupling for missing co-change
-const RECENCY_DECAY_LAMBDA = 0.05; // Exponential decay: half-life ~14 hours
-const RECENCY_FLOOR = 0.05; // Minimum recency score (prevents zero for old changes)
+// ─── Scoring Functions (Phase 4: continuous weights, bi-modal decay, sigmoid smoothing) ───
+/** Bi-modal recency decay: fast initial + slow tail for weekend bugs. */
+function recencyScore(hoursAgo) {
+    // At 1h: 0.94, 6h: 0.61, 14h: 0.39, 48h: 0.21, 72h: 0.19
+    return 0.7 * Math.exp(-0.2 * hoursAgo) + 0.3 * Math.exp(-0.01 * hoursAgo);
+}
+/** Sigmoid with configurable steepness. k=5 gives a meaningfully smooth transition. */
+function sigmoid(value, midpoint, k = 5) {
+    return 1 / (1 + Math.exp(-k * (value - midpoint)));
+}
+// Weight interpolation thresholds
+const RECENT_RICHNESS_SATURATION = 10; // ≥10 recent files = full recent signal
+const COCHANGE_RICHNESS_SATURATION = 20; // ≥20 co-change edges = full co-change signal
+/**
+ * Continuous weight interpolation based on data richness (replaces 3 discrete configs).
+ * Weights sum to ~100 at any data richness level. When recent data is sparse,
+ * coupling/dependency absorb the weight. When co-change data is sparse, recency dominates.
+ */
+function computeWeights(recentFilesCount, cochangeEdgesCount) {
+    const rr = Math.min(recentFilesCount / RECENT_RICHNESS_SATURATION, 1); // 0-1
+    const cr = Math.min(cochangeEdgesCount / COCHANGE_RICHNESS_SATURATION, 1); // 0-1
+    return {
+        missingCoChange: 30 * rr * cr, // only active with both recent changes AND co-change data
+        recency: 20 * rr + 10 * (1 - cr) * rr, // absorbs co-change weight when co-change sparse
+        coupling: 15 * cr + 20 * (1 - rr) * cr, // absorbs recency weight when recent data sparse
+        dependency: 10 + 15 * (1 - rr) * (1 - cr), // baseline + absorbs when both signals sparse
+        workflow: 10 + 5 * (1 - cr), // baseline + boost when co-change sparse
+        testMapping: 15, // always active — test name convention is high-precision, 0-cost
+        directoryLocality: 10, // always active — test/plugins/X → src/plugins/X
+    };
+}
+/**
+ * Test-to-source mapping using two complementary signals:
+ * 1. Naming convention (high precision): test/foo.test.ts → src/foo.ts identifies test SUBJECT
+ * 2. Import graph (broader recall): test imports this candidate — tiebreaker for imports
+ *
+ * Naming match returns 1.0 (strong), import match returns 0.5 (weaker — test may import many files).
+ */
+function testToSourceScore(testFile, candidateFile, importByImporter) {
+    if (!testFile)
+        return 0;
+    // Signal 1 (primary): naming convention — "this test is ABOUT this file"
+    const stripped = testFile.replace(/\.(test|spec)\.(ts|tsx|js|jsx)$/, ".$2").replace(/^(test|__tests__)\//, "src/");
+    if (candidateFile === stripped)
+        return 1;
+    // Signal 2 (tiebreaker): import graph — "the test uses this file"
+    const testImports = importByImporter.get(testFile);
+    if (testImports?.some((e) => e.source === candidateFile))
+        return 0.5;
+    return 0;
+}
+/** Directory locality: test path shares a SPECIFIC component with candidate source path. */
+const GENERIC_PATH_PARTS = new Set([
+    "test",
+    "tests",
+    "__tests__",
+    "src",
+    "lib",
+    "dist",
+    "build",
+    "fixtures",
+    "plugins",
+    "detectors",
+    "handlers",
+    "controllers",
+    "routes",
+    "utils",
+    "helpers",
+    "core",
+    "common",
+    "shared",
+    "internal",
+    "packages",
+]);
+function directoryLocalityScore(testFile, candidateFile) {
+    if (!testFile)
+        return 0;
+    // Extract the most specific non-generic path component from the test file
+    // For "test/plugins/astro-sharp-image-service.test.ts" → "astro-sharp-image-service" → try "astro"
+    const testBase = testFile.replace(/.*\//, "").replace(/\.(test|spec)\.[^.]+$/, "");
+    const candParts = candidateFile.split("/").filter((p) => !p.includes("."));
+    // Primary: test base name contains or is contained by a candidate directory
+    // "astro-sharp-image-service" contains "astro" → matches src/plugins/astro/
+    for (const cp of candParts) {
+        if (GENERIC_PATH_PARTS.has(cp))
+            continue;
+        if (testBase.includes(cp) || cp.includes(testBase))
+            return 1;
+    }
+    return 0;
+}
+function classifyErrorType(typeName, message) {
+    if (typeName === "TypeError")
+        return "type";
+    if (typeName === "ReferenceError")
+        return "reference";
+    if (typeName === "SyntaxError")
+        return "syntax";
+    if (typeName === "AssertionError" || /assert|expect|toBe|toEqual|toMatch/i.test(message))
+        return "assertion";
+    return "runtime";
+}
 /**
  * Extract file paths, test file, and error message from raw error/stack trace text.
  * Handles V8 stacks, TypeScript compiler errors, Vitest output, and generic patterns.
@@ -374,10 +496,16 @@ export function parseErrorText(errorText, rootDir) {
     let testFile = null;
     let message = null;
     // Cap input to prevent DoS from pathologically large error strings
-    const text = errorText.length > 100_000 ? errorText.slice(0, 100_000) : errorText;
-    const msgMatch = text.match(/(?:TypeError|ReferenceError|Error|SyntaxError):\s*(.+)/);
-    if (msgMatch)
-        message = msgMatch[1].trim();
+    // Strip ANSI escape codes (terminal colors, bold, etc.)
+    const capped = errorText.length > 100_000 ? errorText.slice(0, 100_000) : errorText;
+    // biome-ignore lint/suspicious/noControlCharactersInRegex: ANSI escape sequence stripping requires \x1B
+    const text = capped.replace(/\x1B\[[0-9;]*m/g, "");
+    let errorType = null;
+    const msgMatch = text.match(/(TypeError|ReferenceError|AssertionError|SyntaxError|Error):\s*([^\n]+)/);
+    if (msgMatch) {
+        errorType = classifyErrorType(msgMatch[1], msgMatch[2]);
+        message = msgMatch[2].trim();
+    }
     for (const line of text.split("\n")) {
         let m;
         // Vitest FAIL header: "FAIL  test/foo.test.ts > ..."
@@ -400,13 +528,27 @@ export function parseErrorText(errorText, rootDir) {
             addProjectFile(fileSet, m[1], rootDir);
             continue;
         }
+        // Webpack/Vite build error: "ERROR in ./src/foo.ts" or "[vite] Error: ... src/foo.ts"
+        if ((m = line.match(/ERROR\s+in\s+\.?\/?([\w/.-]+\.[jt]sx?)/))) {
+            addProjectFile(fileSet, m[1], rootDir);
+            continue;
+        }
+        if ((m = line.match(/\[vite\]\s+.*?([\w/.-]+\.[jt]sx?)/))) {
+            addProjectFile(fileSet, m[1], rootDir);
+            continue;
+        }
+        // Nested stack trace: "Caused by: ... at file:line:col"
+        if ((m = line.match(/[Cc]aused by:.*?([\w/.-]+\.[jt]sx?):(\d+)/))) {
+            addProjectFile(fileSet, m[1], rootDir);
+            continue;
+        }
         // Generic: any relative path with a directory separator, ending in .ts/.js:line
         // Covers app/, pages/, components/, packages/, server/, api/, etc.
         if ((m = line.match(/\b([a-zA-Z][^\s:]*\/[^\s:]+\.[jt]sx?):(\d+)/))) {
             addProjectFile(fileSet, m[1], rootDir);
         }
     }
-    return { files: [...fileSet], testFile, message };
+    return { files: [...fileSet], testFile, message, errorType };
 }
 /**
  * Query git for recently changed files: uncommitted (hoursAgo=0) + committed (last 7 days).
@@ -497,15 +639,19 @@ export function traceImportChain(analysis, from, to, packagePath) {
 }
 /**
  * Score candidate files using 5 signals with dynamic weights + call graph bonus.
- * Returns top 5 suspects sorted by score descending.
+ * Returns top 5 suspects with confidence assessment based on signal quality.
  */
-export function buildSuspectList(analysis, errorFiles, recentChanges, packagePath) {
+export function buildSuspectList(analysis, errorFiles, recentChanges, packagePath, testFile) {
     const pkg = resolvePackage(analysis, packagePath);
     const errorSet = new Set(errorFiles);
     const chain = pkg.importChain ?? [];
     const coChangeEdges = pkg.gitHistory?.coChangeEdges ?? [];
     const callGraph = pkg.callGraph ?? [];
     const workflowRules = analysis.crossPackage?.workflowRules ?? [];
+    // Detect unselective imports: does the test file import the package entry point?
+    // If so, the import graph floods with candidates — downweight dependency signal.
+    const entryPoint = pkg.architecture.entryPoint;
+    const testImportsEntryPoint = testFile && entryPoint ? chain.some((e) => e.importer === testFile && e.source === entryPoint) : false;
     // Index recent changes by file
     const changeMap = new Map();
     for (const c of recentChanges) {
@@ -513,80 +659,147 @@ export function buildSuspectList(analysis, errorFiles, recentChanges, packagePat
             changeMap.set(c.file, c);
     }
     const changedFiles = new Set(changeMap.keys());
-    // 1. Collect candidates: import neighbors + co-change partners of error files
-    const candidateSymbols = new Map(); // file → max symbolCount
+    // 1. Collect candidates with directional awareness:
+    //    Upstream (dependencies of error site) are more likely root causes.
+    //    Downstream (consumers of error site) are more likely needing updates.
+    const upstreamSymbols = new Map(); // files error site depends on
+    const downstreamSymbols = new Map(); // files that depend on error site
     const candidateCoupling = new Map(); // file → max Jaccard
-    for (const errorFile of errorFiles) {
-        // Files the error file imports from (upstream — likely root cause)
-        for (const edge of chain) {
-            if (edge.importer === errorFile) {
-                setMax(candidateSymbols, edge.source, edge.symbolCount);
-            }
+    // Index import chain by both importer and source for O(1) lookup
+    const importByImporter = new Map();
+    const importBySource = new Map();
+    for (const edge of chain) {
+        let byImp = importByImporter.get(edge.importer);
+        if (!byImp) {
+            byImp = [];
+            importByImporter.set(edge.importer, byImp);
         }
-        // Files that import from error file (downstream — may need updating)
-        for (const edge of chain) {
-            if (edge.source === errorFile) {
-                setMax(candidateSymbols, edge.importer, edge.symbolCount);
+        byImp.push(edge);
+        let bySrc = importBySource.get(edge.source);
+        if (!bySrc) {
+            bySrc = [];
+            importBySource.set(edge.source, bySrc);
+        }
+        bySrc.push(edge);
+    }
+    // Index co-change edges by both files
+    const coChangeByFile = new Map();
+    for (const edge of coChangeEdges) {
+        for (const f of [edge.file1, edge.file2]) {
+            let arr = coChangeByFile.get(f);
+            if (!arr) {
+                arr = [];
+                coChangeByFile.set(f, arr);
             }
+            arr.push(edge);
         }
-        // Co-change partners
-        for (const edge of coChangeEdges) {
-            if (edge.file1 === errorFile) {
-                setMax(candidateCoupling, edge.file2, edge.jaccard);
+    }
+    // Multi-hop upstream traversal: BFS through imports up to depth 2
+    // Depth 1 = direct dependency (full score), depth 2 = transitive (half score)
+    // Depth 3+ floods candidate pool on large repos — diminishing returns
+    const MAX_CANDIDATE_DEPTH = 2;
+    const visited = new Set(errorFiles);
+    let frontier = new Set(errorFiles);
+    for (let depth = 1; depth <= MAX_CANDIDATE_DEPTH; depth++) {
+        const depthFactor = 1 / depth; // 1.0, 0.5, 0.33
+        const nextFrontier = new Set();
+        for (const file of frontier) {
+            // Upstream: files this node imports FROM
+            for (const edge of importByImporter.get(file) ?? []) {
+                if (!visited.has(edge.source)) {
+                    setMax(upstreamSymbols, edge.source, edge.symbolCount * depthFactor);
+                    nextFrontier.add(edge.source);
+                }
             }
-            else if (edge.file2 === errorFile) {
-                setMax(candidateCoupling, edge.file1, edge.jaccard);
+            // Downstream: only at depth 1 (direct consumers of error site)
+            if (depth === 1) {
+                for (const edge of importBySource.get(file) ?? []) {
+                    if (!visited.has(edge.importer)) {
+                        setMax(downstreamSymbols, edge.importer, edge.symbolCount);
+                    }
+                }
+            }
+            // Co-change partners (only at depth 1)
+            if (depth === 1) {
+                for (const edge of coChangeByFile.get(file) ?? []) {
+                    const partner = edge.file1 === file ? edge.file2 : edge.file1;
+                    setMax(candidateCoupling, partner, edge.jaccard);
+                }
             }
         }
+        for (const f of nextFrontier)
+            visited.add(f);
+        frontier = nextFrontier;
     }
-    // Include error files as candidates (they may have been recently changed)
     for (const f of errorFiles) {
-        if (!candidateSymbols.has(f) && !candidateCoupling.has(f)) {
-            candidateSymbols.set(f, 0);
+        if (!upstreamSymbols.has(f) && !downstreamSymbols.has(f) && !candidateCoupling.has(f)) {
+            upstreamSymbols.set(f, 0);
+        }
+    }
+    const allCandidates = new Set([...upstreamSymbols.keys(), ...downstreamSymbols.keys(), ...candidateCoupling.keys()]);
+    // Directory locality candidate discovery: when test imports entry point (unselective),
+    // scan all known files for directory-name matches with the test file.
+    // This adds candidates that the import graph can't reach.
+    if (testImportsEntryPoint && testFile) {
+        const allKnownFiles = new Set();
+        for (const edge of chain) {
+            allKnownFiles.add(edge.importer);
+            allKnownFiles.add(edge.source);
+        }
+        for (const file of allKnownFiles) {
+            if (allCandidates.has(file) || errorSet.has(file))
+                continue;
+            if (directoryLocalityScore(testFile, file) > 0) {
+                allCandidates.add(file);
+            }
         }
     }
-    const allCandidates = new Set([...candidateSymbols.keys(), ...candidateCoupling.keys()]);
-    // 2. Missing co-change: for each recently-changed relevant file,
-    //    find high-coupling partners that weren't updated
+    // 2. Missing co-change: joint sigmoid on both Jaccard AND count
     const missingCoChange = new Map();
     const relevant = [...changedFiles].filter((f) => errorSet.has(f) || allCandidates.has(f));
     for (const changedFile of relevant) {
         for (const edge of coChangeEdges) {
             const partner = edge.file1 === changedFile ? edge.file2 : edge.file2 === changedFile ? edge.file1 : null;
-            if (!partner)
-                continue;
-            if (edge.coChangeCount < MISSING_CO_CHANGE_MIN_COUNT || edge.jaccard <= MISSING_CO_CHANGE_MIN_JACCARD)
-                continue;
-            if (changedFiles.has(partner))
+            if (!partner || changedFiles.has(partner))
                 continue;
-            setMax(missingCoChange, partner, edge.jaccard);
-            allCandidates.add(partner);
-        }
-    }
-    // 3. Dynamic weights — adapt to available signals
-    const hasRecentChanges = recentChanges.some((c) => c.hoursAgo < 24);
-    const hasCoChangeData = coChangeEdges.length > 0;
-    const w = hasRecentChanges
-        ? hasCoChangeData
-            ? { missingCoChange: 35, recency: 25, coupling: 20, dependency: 10, workflow: 10 }
-            : { missingCoChange: 0, recency: 40, dependency: 35, coupling: 0, workflow: 25 }
-        : { missingCoChange: 0, recency: 0, coupling: 50, dependency: 35, workflow: 15 };
+            // Joint sigmoid: both Jaccard and count must be strong
+            const score = sigmoid(edge.jaccard, 0.4, 5) * sigmoid(Math.log(edge.coChangeCount), Math.log(5), 3);
+            if (score > 0.05) {
+                setMax(missingCoChange, partner, score);
+                allCandidates.add(partner);
+            }
+        }
+    }
+    // 3. Continuous weight interpolation
+    const recentCount = recentChanges.filter((c) => c.hoursAgo < 48).length;
+    const w = computeWeights(recentCount, coChangeEdges.length);
     // 4. Score each candidate
     const suspects = [];
     for (const file of allCandidates) {
         const change = changeMap.get(file);
+        const rawCoupling = candidateCoupling.get(file) ?? 0;
+        // Directional dependency: upstream gets mild boost only when no recency data
+        const upScore = Math.min((upstreamSymbols.get(file) ?? 0) / 10, 1);
+        const downScore = Math.min((downstreamSymbols.get(file) ?? 0) / 10, 1);
+        const upstreamBoost = recentChanges.length === 0 ? 1.3 : 1.0;
+        // When test imports entry point, import graph is unselective — reduce dependency weight
+        const selectivityFactor = testImportsEntryPoint ? 0.5 : 1.0;
         const signals = {
             missingCoChange: missingCoChange.get(file) ?? 0,
-            recency: change ? Math.max(RECENCY_FLOOR, Math.exp(-RECENCY_DECAY_LAMBDA * change.hoursAgo)) : 0,
-            coupling: candidateCoupling.get(file) ?? 0,
-            dependency: Math.min((candidateSymbols.get(file) ?? 0) / 10, 1),
+            recency: change ? recencyScore(change.hoursAgo) : 0,
+            coupling: sigmoid(rawCoupling, 0.2, 5),
+            dependency: Math.max(upScore * upstreamBoost, downScore) * selectivityFactor,
             workflow: workflowRules.some((r) => r.trigger.includes(file) || r.action.includes(file)) ? 1.0 : 0,
+            testMapping: testToSourceScore(testFile ?? null, file, importByImporter),
+            directoryLocality: directoryLocalityScore(testFile ?? null, file),
         };
         let score = w.missingCoChange * signals.missingCoChange +
             w.recency * signals.recency +
             w.coupling * signals.coupling +
             w.dependency * signals.dependency +
-            w.workflow * signals.workflow;
+            w.workflow * signals.workflow +
+            w.testMapping * signals.testMapping +
+            w.directoryLocality * signals.directoryLocality;
         // Call graph bonus: 1.5x if call edge exists, but NOT for the error site itself
         const callGraphBonus = !errorSet.has(file) &&
             callGraph.some((e) => (e.fromFile === file && errorSet.has(e.toFile)) || (e.toFile === file && errorSet.has(e.fromFile)));
@@ -594,18 +807,26 @@ export function buildSuspectList(analysis, errorFiles, recentChanges, packagePat
             score *= 1.5;
         // Build human-readable reason
         const reasons = [];
+        if (signals.testMapping > 0) {
+            reasons.push("directly imported by failing test");
+        }
         if (signals.missingCoChange > 0) {
-            reasons.push(`Missing co-change: expected to change (${Math.round(signals.missingCoChange * 100)}% coupling) but wasn't updated`);
+            reasons.push(`Missing co-change: expected to change but wasn't updated`);
         }
         if (signals.recency > 0.1 && change) {
             const ago = change.isUncommitted ? "uncommitted changes" : `changed ${formatHoursAgo(change.hoursAgo)}`;
             reasons.push(ago + (change.commitMessage ? `: "${change.commitMessage}"` : ""));
         }
-        if (signals.coupling > 0) {
-            reasons.push(`${Math.round(signals.coupling * 100)}% co-change coupling`);
+        if (signals.coupling > 0.1) {
+            reasons.push(`${Math.round(rawCoupling * 100)}% co-change coupling`);
         }
         if (signals.dependency > 0) {
-            reasons.push(`${candidateSymbols.get(file) ?? 0} symbols shared with error site`);
+            const isUpstream = (upstreamSymbols.get(file) ?? 0) > 0;
+            const symCount = Math.max(upstreamSymbols.get(file) ?? 0, downstreamSymbols.get(file) ?? 0);
+            reasons.push(`${symCount} symbols ${isUpstream ? "(dependency of" : "(depends on"} error site)`);
+        }
+        if (signals.directoryLocality > 0) {
+            reasons.push("directory matches test name");
         }
         if (callGraphBonus) {
             reasons.push("call graph connection (1.5x)");
@@ -620,10 +841,69 @@ export function buildSuspectList(analysis, errorFiles, recentChanges, packagePat
             reason: reasons.join("; "),
         });
     }
-    return suspects
+    const ranked = suspects
         .filter((s) => s.score > 0)
         .sort((a, b) => b.score - a.score)
         .slice(0, 5);
+    return assessConfidence(ranked, {
+        hasRecentChanges: recentChanges.length > 0,
+        hasCoChangeData: coChangeEdges.length > 0,
+        hasCallGraph: callGraph.length > 0,
+        testHasDirectImport: testFile ? (importByImporter.get(testFile)?.length ?? 0) > 0 : false,
+        testImportsEntryPoint,
+        candidatePoolSize: allCandidates.size,
+    });
+}
+/**
+ * Assess confidence based on signal quality — not the suspects themselves.
+ * High: multiple independent signals available, top suspect strongly differentiated.
+ * Medium: some signals available, moderate differentiation.
+ * Low: thin signal (no co-change, test doesn't import sources, large candidate pool).
+ */
+function assessConfidence(suspects, signals) {
+    if (suspects.length === 0) {
+        return { suspects, confidence: "low", confidenceReason: "No suspects found" };
+    }
+    // Count how many independent signal sources are available
+    let signalCount = 0;
+    if (signals.hasRecentChanges)
+        signalCount++;
+    if (signals.hasCoChangeData)
+        signalCount++;
+    if (signals.hasCallGraph)
+        signalCount++;
+    if (signals.testHasDirectImport)
+        signalCount++;
+    // Score discrimination: how much does #1 stand out from #2?
+    const topScore = suspects[0].score;
+    const secondScore = suspects.length > 1 ? suspects[1].score : 0;
+    const discrimination = secondScore > 0 ? topScore / secondScore : topScore > 0 ? 10 : 0;
+    // Large candidate pool with low discrimination = noisy
+    const isNoisy = signals.candidatePoolSize > 20 && discrimination < 1.5;
+    let confidence;
+    let confidenceReason;
+    if (signalCount >= 3 && discrimination >= 1.5 && !isNoisy) {
+        confidence = "high";
+        confidenceReason = `${signalCount} independent signals, clear top suspect`;
+    }
+    else if (signalCount >= 2 || (signalCount >= 1 && discrimination >= 2)) {
+        confidence = "medium";
+        confidenceReason = `${signalCount} signal${signalCount === 1 ? "" : "s"}, ${discrimination >= 1.5 ? "moderate" : "weak"} differentiation`;
+    }
+    else {
+        confidence = "low";
+        const reasons = [];
+        if (signals.testImportsEntryPoint)
+            reasons.push("test imports package entry point (integration test pattern)");
+        else if (!signals.testHasDirectImport)
+            reasons.push("test doesn't directly import source modules");
+        if (!signals.hasCoChangeData)
+            reasons.push("no co-change history available");
+        if (isNoisy)
+            reasons.push(`${signals.candidatePoolSize} candidates with similar scores`);
+        confidenceReason = reasons.length > 0 ? reasons.join("; ") : "limited signal available";
+    }
+    return { suspects, confidence, confidenceReason };
 }
 // ─── Diagnose Helpers ───────────────────────────────────────────────────────
 function normalizePath(raw, rootDir) {