fix(audit): distinguish "file not found" from "file has zero functions" (#2142)

* fix(audit): distinguish "file not found" from "file has zero functions"

codegraph audit <file> printed the same "No file matching" message for
a file that genuinely isn't in the graph and for a real, tracked file
that just has zero own function/method/class definitions (e.g. a pure
re-export barrel) — misleadingly implying the graph doesn't know about
a file it actually parsed correctly.

Adds AuditResult.found, set to false only when explainData finds zero
matching file/symbol entries at all; presentation/audit.ts now renders
a distinct message when found !== false but functions is still empty.

Closes #2135

Impact: 3 functions changed, 3 affected

* fix: base found flag on pre-filter results to avoid false negatives (#2142)

auditData set found: false using the post `--file`/`--kind` filtered
results array, so a function that genuinely exists in the graph but is
filtered out entirely by those options was misreported as "not found" --
the exact bug this PR set out to fix, reachable via a different input
shape. Check explained.results (pre-filter) instead.

Impact: 1 functions changed, 3 affected

Author: carlos-alm

src/features/audit.ts

@@ -162,7 +162,18 @@ export function auditData(
   }
 
   if (results.length === 0) {
-    return { target, kind: explained.kind as 'function' | 'file', functions: [] };
+    // `found` reflects whether the target exists in the graph at all -- check
+    // the pre-filter `explained.results`, not the post `--file`/`--kind` filtered
+    // `results`. Otherwise a real, tracked function filtered out entirely by
+    // e.g. `--file src/other.js` would be misreported as "not found" (the same
+    // bug this PR fixes for barrel files, reachable via a different input shape).
+    const foundInGraph = explained.results.length > 0;
+    return {
+      target,
+      kind: explained.kind as 'function' | 'file',
+      functions: [],
+      found: foundInGraph ? undefined : false,
+    };
   }
 
   // 2. Open DB for enrichment

src/presentation/audit.ts

@@ -97,7 +97,11 @@ export function audit(
   if (outputResult(data, null, opts)) return;
 
   if (data.functions.length === 0) {
-    console.log(`No ${data.kind === 'file' ? 'file' : 'function/symbol'} matching "${target}"`);
+    if (data.found === false) {
+      console.log(`No ${data.kind === 'file' ? 'file' : 'function/symbol'} matching "${target}"`);
+    } else {
+      console.log(`No functions to audit in "${target}" (0 own function/method/class definitions)`);
+    }
     return;
   }
 

src/types.ts

@@ -1731,6 +1731,11 @@ export interface AuditResult {
   target: string;
   kind: 'function' | 'file';
   functions: AuditFunctionEntry[];
+  /** False only when target isn't tracked in the graph at all — distinguishes
+   *  "no such file/symbol" from "file exists but has zero function-kind
+   *  definitions" (e.g. a pure re-export barrel), which also yields an
+   *  empty `functions` array. */
+  found?: boolean;
 }
 
 /** A single manifesto threshold breach reported against an audited function. */

tests/integration/audit.test.ts

@@ -63,6 +63,9 @@ beforeAll(() => {
   insertNode(db, 'src/resolve.js', 'file', 'src/resolve.js', 0);
   insertNode(db, 'src/utils.js', 'file', 'src/utils.js', 0);
   insertNode(db, 'tests/builder.test.js', 'file', 'tests/builder.test.js', 0);
+  // Barrel/re-export-only file — tracked in the graph but has zero own
+  // function/method/class definitions.
+  insertNode(db, 'src/barrel.js', 'file', 'src/barrel.js', 0);
 
   // ── Function/class nodes ──
   const fnBuild = insertNode(
@@ -258,6 +261,33 @@ describe('auditData — edge cases', () => {
     expect(data.functions).toEqual([]);
   });
 
+  test('nonexistent function sets found: false', () => {
+    const data = auditData('nonExistentFunction', dbPath);
+    expect(data.found).toBe(false);
+  });
+
+  test('nonexistent file sets found: false', () => {
+    const data = auditData('src/does/not/exist.js', dbPath);
+    expect(data.functions).toEqual([]);
+    expect(data.found).toBe(false);
+  });
+
+  test('barrel file with zero own functions does not set found: false', () => {
+    const data = auditData('src/barrel.js', dbPath);
+    expect(data.kind).toBe('file');
+    expect(data.functions).toEqual([]);
+    expect(data.found).not.toBe(false);
+  });
+
+  test('--file filter removing every match does not set found: false', () => {
+    // buildGraph exists in src/builder.js, not src/other.js -- the --file
+    // filter legitimately empties the result set, but the symbol IS in the
+    // graph, so this must not be reported as "not found".
+    const data = auditData('buildGraph', dbPath, { file: 'src/other.js' });
+    expect(data.functions).toEqual([]);
+    expect(data.found).not.toBe(false);
+  });
+
   test('function with no complexity row has null health values', () => {
     const data = auditData('formatOutput', dbPath);
     const fn = data.functions.find((f) => f.name === 'formatOutput');