ucn 3.8.22 → 3.8.25

package/core/analysis.js

@@ -13,6 +13,190 @@ const { execFileSync } = require('child_process');
 const { parse } = require('./parser');
 const { detectLanguage, langTraits } = require('../languages');
 const { NON_CALLABLE_TYPES, addTestExclusions } = require('./shared');
+const { computeReachability, symbolKey } = require('./entrypoints');
+const { getLanguageModule } = require('../languages');
+
+// JS/TS test framework helpers — calls to these bracket a test case.
+// Used to flag call sites whose enclosing function is an arrow callback
+// passed to one of these (the common pattern in mocha/jest/vitest).
+const _JS_TEST_FRAMEWORK_CALLS = new Set(['describe', 'it', 'test', 'spec', 'context', 'suite']);
+
+/**
+ * Tag each call site with `inTestCase` based on its enclosing function's
+ * entry-point classification. Uses each language's `getEntryPointKind`
+ * predicate (kind === 'test') so results match `affectedTests`/etc.
+ *
+ * For JS/TS/HTML, function-level entry-point classification only covers
+ * framework lifecycle methods. Test bodies are framework callbacks
+ * (`it('name', () => {...})`), so we additionally tag a site as inTestCase
+ * when its file has a `describe`/`it`/`test` framework call that brackets
+ * the enclosing function — mirroring `_addAffectedTestCases` in tracing.js.
+ *
+ * Mutates each site in place (sets `site.inTestCase = boolean`).
+ */
+function tagInTestCase(index, sites) {
+    if (!Array.isArray(sites) || sites.length === 0) return;
+    // Per-file cache: language module + JS framework call ranges.
+    const fileMeta = new Map();
+    function getFileMeta(filePath) {
+        if (!filePath) return null;
+        if (fileMeta.has(filePath)) return fileMeta.get(filePath);
+        const fe = index.files.get(filePath);
+        if (!fe) { fileMeta.set(filePath, null); return null; }
+        let langModule = null;
+        try { langModule = getLanguageModule(fe.language); } catch (_) { /* ignore */ }
+        const meta = { fileEntry: fe, langModule, language: fe.language, jsTestRanges: null };
+        // For JS-family files, build line ranges of describe/it/test framework calls.
+        if (langModule && (fe.language === 'javascript' || fe.language === 'typescript' ||
+            fe.language === 'tsx' || fe.language === 'html')) {
+            try {
+                const calls = index.getCachedCalls ? index.getCachedCalls(filePath) : null;
+                if (Array.isArray(calls)) {
+                    const ranges = [];
+                    for (const call of calls) {
+                        if (!_JS_TEST_FRAMEWORK_CALLS.has(call.name)) continue;
+                        // Get the enclosing test-block end via existing fn-bound estimate.
+                        // Without a proper bracket scan we use the next-fn-boundary or +200 lines.
+                        let endLine = call.line + 200;
+                        // Try using the enclosing-symbol range as an upper bound when possible.
+                        if (fe.symbols) {
+                            for (const sym of fe.symbols) {
+                                if (sym.startLine <= call.line && (sym.endLine || 0) >= call.line) {
+                                    endLine = Math.min(endLine, sym.endLine || endLine);
+                                }
+                            }
+                        }
+                        ranges.push({ start: call.line, end: endLine });
+                    }
+                    meta.jsTestRanges = ranges;
+                }
+            } catch (_) { /* ignore */ }
+        }
+        fileMeta.set(filePath, meta);
+        return meta;
+    }
+    for (const site of sites) {
+        site.inTestCase = false;
+        const meta = getFileMeta(site.callerFile);
+        if (!meta || !meta.langModule) continue;
+        // First: kinded entry-point predicate (Python/Go/Java/Rust + JS lifecycle).
+        const classify = meta.langModule.getEntryPointKind;
+        if (classify && site.callerFile && site.callerStartLine != null) {
+            const encl = index.findEnclosingFunction
+                ? index.findEnclosingFunction(site.callerFile, site.line, true)
+                : null;
+            if (encl && classify(encl) === 'test') {
+                site.inTestCase = true;
+                continue;
+            }
+        }
+        // Second: JS/TS framework-call brackets (it/test/describe). The site is
+        // inside a test case when its line falls within a describe/it block.
+        if (meta.jsTestRanges && meta.jsTestRanges.length > 0 && site.line != null) {
+            for (const r of meta.jsTestRanges) {
+                if (site.line >= r.start && site.line <= r.end) {
+                    site.inTestCase = true;
+                    break;
+                }
+            }
+        }
+    }
+}
+
+// ============================================================================
+// TRUST SIGNALS: HISTOGRAM + REACHABILITY
+// ============================================================================
+
+/**
+ * Bucket a confidence score into 'high' / 'medium' / 'low'.
+ * Boundaries are inclusive at the lower end:
+ *   confidence > 0.8  → high
+ *   0.5 <= c <= 0.8   → medium
+ *   c < 0.5           → low
+ *
+ * @param {number} c - Confidence score (0.0-1.0)
+ * @returns {'high'|'medium'|'low'}
+ */
+function bucketConfidence(c) {
+    if (c == null) return 'low';
+    if (c > 0.8) return 'high';
+    if (c >= 0.5) return 'medium';
+    return 'low';
+}
+
+/**
+ * Build a confidence histogram from an array of edges (callers/callees).
+ * Returns null when there are no edges (caller drops the section entirely).
+ *
+ * @param {Array} edges - Array of objects with `confidence` field
+ * @returns {{ high: number, medium: number, low: number, total: number }|null}
+ */
+function buildHistogram(edges) {
+    if (!edges || edges.length === 0) return null;
+    const h = { high: 0, medium: 0, low: 0, total: edges.length };
+    for (const e of edges) {
+        h[bucketConfidence(e.confidence)]++;
+    }
+    return h;
+}
+
+/**
+ * Tag a list of caller objects with `reachable: boolean`.
+ * Uses (callerFile, callerStartLine) to look up the caller symbol's reachability.
+ * Module-level callers (no callerStartLine) are treated as unreachable.
+ *
+ * @param {Array} callers - Caller objects from findCallers
+ * @param {Set<string>} reachableSet - Set of reachable symbol keys
+ * @returns {Array} Same callers with `reachable` field added (mutated in place)
+ */
+function tagCallersReachable(callers, reachableSet) {
+    if (!callers) return callers;
+    for (const c of callers) {
+        if (c.callerFile && c.callerStartLine != null) {
+            c.reachable = reachableSet.has(symbolKey(c.callerFile, c.callerStartLine));
+        } else {
+            // Module-level / unknown caller — treat as unreachable (no enclosing function)
+            c.reachable = false;
+        }
+    }
+    return callers;
+}
+
+/**
+ * Tag a list of callee objects with `reachable: boolean`.
+ * Callee objects from findCallees have `file` + `startLine` directly.
+ *
+ * @param {Array} callees - Callee objects from findCallees
+ * @param {Set<string>} reachableSet - Set of reachable symbol keys
+ * @returns {Array} Same callees with `reachable` field added (mutated in place)
+ */
+function tagCalleesReachable(callees, reachableSet) {
+    if (!callees) return callees;
+    for (const c of callees) {
+        if (c.file && c.startLine != null) {
+            c.reachable = reachableSet.has(symbolKey(c.file, c.startLine));
+        } else {
+            c.reachable = false;
+        }
+    }
+    return callees;
+}
+
+/**
+ * Attach side-effect tags to each callee by AST scan of its body.
+ * Tags = ['fs', 'network', 'process', 'global_mutation'] subset.
+ * Cached per-symbol on the index so repeat queries are cheap.
+ */
+function tagCalleesSideEffects(index, callees) {
+    if (!callees || callees.length === 0) return callees;
+    const { sideEffectsFor } = require('./brief');
+    for (const c of callees) {
+        const tags = sideEffectsFor(index, c);
+        if (tags && tags.length > 0) c.sideEffects = tags;
+    }
+    return callees;
+}
+
 
 /**
  * Context: quick caller/callee view for a symbol.
@@ -25,7 +209,7 @@ const { NON_CALLABLE_TYPES, addTestExclusions } = require('./shared');
 function context(index, name, options = {}) {
     index._beginOp();
     try {
-    const resolved = index.resolveSymbol(name, { file: options.file, className: options.className });
+    const resolved = index.resolveSymbol(name, { file: options.file, className: options.className, line: options.line });
     let { def, warnings } = resolved;
     if (!def) {
         return null;
@@ -87,6 +271,45 @@ function context(index, name, options = {}) {
         confidenceFiltered = callerResult.filtered + calleeResult.filtered;
     }
 
+    // Stable output ordering: callers by (file, line). Callees retain their
+    // call-count order from findCallees (most-called first) — that's a value
+    // the user expects, not a stability concern, since the secondary sort
+    // by line keeps ties deterministic.
+    callers = [...callers].sort((a, b) => {
+        const fa = a.relativePath || a.file || '';
+        const fb = b.relativePath || b.file || '';
+        if (fa !== fb) return fa.localeCompare(fb);
+        return (a.line || 0) - (b.line || 0);
+    });
+    callees = [...callees].sort((a, b) => {
+        // Primary: callCount desc (preserves "most-called first" UX)
+        const ca = a.callCount || 0, cb = b.callCount || 0;
+        if (ca !== cb) return cb - ca;
+        // Tiebreaker: file then line, for determinism
+        const fa = a.relativePath || a.file || '';
+        const fb = b.relativePath || b.file || '';
+        if (fa !== fb) return fa.localeCompare(fb);
+        return (a.startLine || 0) - (b.startLine || 0);
+    });
+
+    // Trust signals: tag each caller/callee with reachability and build confidence histograms.
+    // Reachability is computed once per index and cached (see entrypoints.computeReachability).
+    const reachableSet = computeReachability(index);
+    tagCallersReachable(callers, reachableSet);
+    tagCalleesReachable(callees, reachableSet);
+
+    // Side-effect tags on callees (lazy-cached per symbol on the index)
+    tagCalleesSideEffects(index, callees);
+
+    // Optional: filter to unreachable-only (helps surface dead-path callers/callees)
+    if (options.unreachableOnly) {
+        callers = callers.filter(c => !c.reachable);
+        callees = callees.filter(c => !c.reachable);
+    }
+
+    const callerHistogram = buildHistogram(callers);
+    const calleeHistogram = buildHistogram(callees);
+
     const filesInScope = new Set([def.file]);
     callers.forEach(c => filesInScope.add(c.file));
     callees.forEach(c => filesInScope.add(c.file));
@@ -105,6 +328,8 @@ function context(index, name, options = {}) {
         returnType: def.returnType,
         callers,
         callees,
+        callerHistogram,
+        calleeHistogram,
         meta: {
             complete: stats.uncertain === 0 && dynamicImports === 0 && confidenceFiltered === 0,
             skipped: 0,
@@ -139,7 +364,7 @@ function context(index, name, options = {}) {
 function smart(index, name, options = {}) {
     index._beginOp();
     try {
-    const { def } = index.resolveSymbol(name, { file: options.file, className: options.className });
+    const { def } = index.resolveSymbol(name, { file: options.file, className: options.className, line: options.line });
     if (!def) {
         return null;
     }
@@ -291,7 +516,7 @@ function detectCompleteness(index) {
 function related(index, name, options = {}) {
     index._beginOp();
     try {
-    const { def } = index.resolveSymbol(name, { file: options.file, className: options.className });
+    const { def } = index.resolveSymbol(name, { file: options.file, className: options.className, line: options.line });
     if (!def) {
         return null;
     }
@@ -353,13 +578,24 @@ function related(index, name, options = {}) {
     if (related.similarNames.length > similarLimit) related.similarNames = related.similarNames.slice(0, similarLimit);
 
     // 3. Shared callers - functions called by the same callers
-    const myCallers = new Set(index.findCallers(name).map(c => c.callerName).filter(Boolean));
+    // Cap findCallers to avoid O(hundreds × findCallees) on ambiguous names
+    const maxSharedCallerScan = options.all ? 50 : 20;
+    const myCallersRaw = index.findCallers(name, { maxResults: maxSharedCallerScan * 3 });
+    const myCallers = new Set(myCallersRaw.map(c => c.callerName).filter(Boolean));
     if (myCallers.size > 0) {
         const callerCounts = new Map();
+        const calleeCache = new Map();
+        let scannedCallers = 0;
         for (const callerName of myCallers) {
+            if (scannedCallers >= maxSharedCallerScan) break;
             const callerDef = index.symbols.get(callerName)?.[0];
             if (callerDef) {
-                const callees = index.findCallees(callerDef);
+                let callees = calleeCache.get(callerName);
+                if (!callees) {
+                    callees = index.findCallees(callerDef);
+                    calleeCache.set(callerName, callees);
+                }
+                scannedCallers++;
                 for (const callee of callees) {
                     if (callee.name !== name) {
                         callerCounts.set(callee.name, (callerCounts.get(callee.name) || 0) + 1);
@@ -394,9 +630,14 @@ function related(index, name, options = {}) {
         const myCalleeNames = new Set(myCallees.map(c => c.name));
         if (myCalleeNames.size > 0) {
             const calleeCounts = new Map();
+            // Cap callee scan to avoid O(callees × findCallers) explosion
+            const maxCalleeScan = options.all ? 30 : 15;
+            let scannedCallees = 0;
             for (const calleeName of myCalleeNames) {
+                if (scannedCallees >= maxCalleeScan) break;
+                scannedCallees++;
                 // Find other functions that also call this callee
-                const callers = index.findCallers(calleeName);
+                const callers = index.findCallers(calleeName, { maxResults: 50 });
                 for (const caller of callers) {
                     if (caller.callerName && caller.callerName !== name) {
                         calleeCounts.set(caller.callerName, (calleeCounts.get(caller.callerName) || 0) + 1);
@@ -437,20 +678,34 @@ function related(index, name, options = {}) {
 function impact(index, name, options = {}) {
     index._beginOp();
     try {
-    const { def } = index.resolveSymbol(name, { file: options.file, className: options.className });
+    const { def } = index.resolveSymbol(name, { file: options.file, className: options.className, line: options.line });
     if (!def) {
         return null;
     }
     const defIsMethod = def.isMethod || def.type === 'method' || def.className || def.receiver;
+    // RUST-3: type definitions (class/struct/interface/etc.) are callable through
+    // constructor invocations (`new ClassName()`) — about() handles them via its
+    // CALLABLE_TYPES set since the M3 fix. Route them through the same findCallers
+    // path here so `impact ClassName` agrees with `about ClassName` rather than
+    // returning 0 because the legacy "function" branch doesn't recognize types.
+    const TYPE_DEF_KINDS = new Set(['class', 'struct', 'interface', 'type',
+        'enum', 'trait', 'impl', 'record', 'namespace']);
+    const defIsTypeDef = TYPE_DEF_KINDS.has(def.type);
+
+    // BUG-H3: default includeMethods:true for impact ("what breaks if I change this"
+    // should include every callable site — including obj.method() invocations).
+    // User can disable with --no-include-methods to scope down.
+    const impactIncludeMethods = options.includeMethods ?? true;
+    const impactIncludeUncertain = options.includeUncertain ?? false;
 
     // Use findCallers for className-scoped or method queries (sophisticated binding resolution)
     // Fall back to usages-based approach for simple function queries (backward compatible)
     let callSites;
-    if (options.className || defIsMethod) {
+    if (options.className || defIsMethod || defIsTypeDef) {
         // findCallers has proper method call resolution (self/this, binding IDs, receiver checks)
         let callerResults = index.findCallers(name, {
-            includeMethods: true,
-            includeUncertain: false,
+            includeMethods: impactIncludeMethods,
+            includeUncertain: impactIncludeUncertain,
             targetDefinitions: [def],
         });
 
@@ -584,15 +839,22 @@ function impact(index, name, options = {}) {
                 line: c.line,
                 expression: c.content.trim(),
                 callerName: c.callerName,
+                callerFile: c.callerFile,
+                callerStartLine: c.callerStartLine,
+                confidence: c.confidence,
+                resolution: c.resolution,
                 ...analysis
             });
         }
         index._clearTreeCache();
     } else {
         // Use findCallers (benefits from callee index) instead of usages() for speed
+        // BUG-H3: respect user-supplied includeMethods (defaults true above).
+        // For standalone functions, method-style calls (e.g. `obj.findCallers()`)
+        // resolve to the function when the receiver is a project object.
         const callerResults = index.findCallers(name, {
-            includeMethods: false,
-            includeUncertain: false,
+            includeMethods: impactIncludeMethods,
+            includeUncertain: impactIncludeUncertain,
             targetDefinitions: [def],
         });
         const targetBindingId = def.bindingId;
@@ -604,6 +866,10 @@ function impact(index, name, options = {}) {
             content: c.content,
             usageType: 'call',
             callerName: c.callerName,
+            callerFile: c.callerFile,
+            callerStartLine: c.callerStartLine,
+            confidence: c.confidence,
+            resolution: c.resolution,
         }));
         // Keep the same binding filter for backward compat (findCallers already handles this,
         // but cross-check with usages-based binding filter for safety)
@@ -635,10 +901,13 @@ function impact(index, name, options = {}) {
         const targetDir = defLang === 'go' ? path.basename(path.dirname(def.file)) : null;
         for (const call of filteredCalls) {
             const analysis = index.analyzeCallSite(call, name);
+            // BUG-H3: when includeMethods is true, keep method-style calls
+            // (e.g. obj.findCallers() resolves to standalone findCallers via the
+            // bindingId path — findCallers already filters by targetDefinitions).
             // Skip method calls (obj.parse()) when target is a standalone function (parse())
             // For Go, allow calls where receiver matches the package directory name
             // (e.g., controller.FilterActive() where file is in pkg/controller/)
-            if (analysis.isMethodCall && !defIsMethod) {
+            if (analysis.isMethodCall && !defIsMethod && !impactIncludeMethods) {
                 if (targetDir) {
                     // Get receiver from parsed calls cache
                     const parsedCalls = index.getCachedCalls(call.file);
@@ -657,6 +926,10 @@ function impact(index, name, options = {}) {
                 line: call.line,
                 expression: call.content.trim(),
                 callerName: call.callerName || index.findEnclosingFunction(call.file, call.line),
+                callerFile: call.callerFile,
+                callerStartLine: call.callerStartLine,
+                confidence: call.confidence,
+                resolution: call.resolution,
                 ...analysis
             });
         }
@@ -669,6 +942,21 @@ function impact(index, name, options = {}) {
         filteredSites = callSites.filter(s => index.matchesFilters(s.file, { exclude: options.exclude }));
     }
 
+    // Trust signals: tag each call site with reachability, build a confidence histogram.
+    // Histogram is computed BEFORE top-N truncation so the trust signal reflects the full scope.
+    const impactReachable = computeReachability(index);
+    for (const site of filteredSites) {
+        if (site.callerFile && site.callerStartLine != null) {
+            site.reachable = impactReachable.has(symbolKey(site.callerFile, site.callerStartLine));
+        } else {
+            site.reachable = false;
+        }
+    }
+    if (options.unreachableOnly) {
+        filteredSites = filteredSites.filter(s => !s.reachable);
+    }
+    const callerHistogram = buildHistogram(filteredSites);
+
     // Apply top limit if specified (limits total call sites shown)
     const totalBeforeLimit = filteredSites.length;
     if (options.top && options.top > 0 && filteredSites.length > options.top) {
@@ -684,6 +972,11 @@ function impact(index, name, options = {}) {
         byFile.get(site.file).push(site);
     }
 
+    // Feature A: tag each call site with `inTestCase` (whether the enclosing
+    // function is a test entry per language's getEntryPointKind predicate).
+    // Done BEFORE identifyCallPatterns so the aggregate count is correct.
+    tagInTestCase(index, filteredSites);
+
     // Identify patterns
     const patterns = index.identifyCallPatterns(filteredSites, name);
 
@@ -714,11 +1007,15 @@ function impact(index, name, options = {}) {
         paramsStructured: def.paramsStructured,
         totalCallSites: totalBeforeLimit,
         shownCallSites: filteredSites.length,
-        byFile: Array.from(byFile.entries()).map(([file, sites]) => ({
-            file,
-            count: sites.length,
-            sites
-        })),
+        callerHistogram,
+        // Stable ordering: files alphabetical, sites by line ascending. Documented contract.
+        byFile: Array.from(byFile.entries())
+            .sort((a, b) => a[0].localeCompare(b[0]))
+            .map(([file, sites]) => ({
+                file,
+                count: sites.length,
+                sites: [...sites].sort((s1, s2) => (s1.line || 0) - (s2.line || 0))
+            })),
         patterns,
         scopeWarning
     };
@@ -762,12 +1059,58 @@ function about(index, name, options = {}) {
     }
 
     // Use resolveSymbol for consistent primary selection (prefers non-test files)
-    const { def: resolved } = index.resolveSymbol(name, { file: options.file, className: options.className });
+    const { def: resolved, warnings: resolveWarnings } = index.resolveSymbol(name, { file: options.file, className: options.className, line: options.line });
     const primary = resolved || definitions[0];
     const others = definitions.filter(d =>
         d.relativePath !== primary.relativePath || d.startLine !== primary.startLine
     );
 
+    // BUG-M4: signal when about auto-picked a primary among multiple candidates
+    // and the user supplied no --file/--class disambiguator. The resolveSymbol
+    // warnings array already includes an "ambiguous" entry — surface it on the
+    // result so formatters can render the note.
+    //
+    // R3-NEW-4: align the displayed count with `find`'s filtered count by
+    // dropping test-file definitions when --include-tests is not set.
+    // Without this, `find foo` could report 2 matches while `about foo` says
+    // "Found 7 definitions" — same query, divergent counts.
+    const aboutWarnings = [];
+    if (!options.file && !options.className && resolveWarnings && resolveWarnings.length > 0) {
+        const { isTestPath } = require('./shared');
+        const { isTestFile } = require('./discovery');
+        const filterTests = !options.includeTests;
+        for (const w of resolveWarnings) {
+            if (w.type !== 'ambiguous') continue;
+            if (!filterTests) {
+                aboutWarnings.push(w);
+                continue;
+            }
+            // Recompute the count using the same test exclusion that find applies.
+            // Always include `def` (the picked primary) so the message wording
+            // ("Using <def>...") stays consistent with the count.
+            const visible = definitions.filter(d => {
+                if (d === primary || (d.relativePath === primary.relativePath && d.startLine === primary.startLine)) return true;
+                const lang = detectLanguage(d.file);
+                if (isTestFile(d.relativePath, lang) || isTestPath(d.relativePath)) return false;
+                return true;
+            });
+            if (visible.length <= 1) {
+                // After test filtering, no real ambiguity remained — drop the warning.
+                continue;
+            }
+            const visibleOthers = visible.filter(d => d !== primary && (d.relativePath !== primary.relativePath || d.startLine !== primary.startLine));
+            const shown = visibleOthers.slice(0, 5);
+            const extra = visibleOthers.length - shown.length;
+            const alsoIn = shown.map(d => `${d.relativePath}:${d.startLine}`).join(', ');
+            const suffix = extra > 0 ? `, and ${extra} more` : '';
+            aboutWarnings.push({
+                type: 'ambiguous',
+                message: `Found ${visible.length} definitions for "${name}". Using ${primary.relativePath}:${primary.startLine}. Also in: ${alsoIn}${suffix}. Use file= to disambiguate.`,
+                alternatives: visibleOthers.map(d => ({ file: d.relativePath, line: d.startLine })),
+            });
+        }
+    }
+
     // Use the actual symbol name (may differ from query if fuzzy matched)
     const symbolName = primary.name;
 
@@ -787,10 +1130,24 @@ function about(index, name, options = {}) {
     let allCallers = null;
     let allCallees = null;
     let aboutConfFiltered = 0;
-    if (primary.type === 'function' || primary.params !== undefined) {
+    // BUG-M3: include classes/structs/interfaces — `new Foo()` invocations are
+    // tracked as calls in the parser (isConstructor:true) and findCallers resolves
+    // them. Without this, `about ClassName` produced "USAGES: 5 calls" but no
+    // CALLERS section, hiding the actual constructor sites.
+    const CALLABLE_TYPES = new Set(['function', 'method', 'static', 'constructor',
+        'public', 'abstract', 'classmethod', 'class', 'struct', 'interface',
+        'type', 'enum', 'trait', 'impl', 'record', 'namespace']);
+    if (CALLABLE_TYPES.has(primary.type) || primary.params !== undefined) {
         // Use maxResults to limit file iteration (with buffer for exclude filtering)
-        const callerCap = maxCallers === Infinity ? undefined : maxCallers * 3;
-        allCallers = index.findCallers(symbolName, { includeMethods, includeUncertain: options.includeUncertain, targetDefinitions: [primary], maxResults: callerCap });
+        // Reduce buffer for highly ambiguous names (many definitions = more noise, less value per caller)
+        const callerMultiplier = definitions.length > 5 ? 1.5 : 3;
+        const callerCap = maxCallers === Infinity ? undefined : Math.ceil(maxCallers * callerMultiplier);
+        // BUG-H1: pass needsTotal:true so the returned array's `totalCount` reflects the
+        // true pre-truncation candidate count. Without this, `about` would report the
+        // capped count as the total (e.g. "showing 10 of 30" when there are actually 153).
+        const rawCallers = index.findCallers(symbolName, { includeMethods, includeUncertain: options.includeUncertain, targetDefinitions: [primary], maxResults: callerCap, needsTotal: true });
+        const shadowCallers = rawCallers.shadowEntries || [];
+        allCallers = rawCallers;
         // Apply exclude filter before slicing
         if (options.exclude && options.exclude.length > 0) {
             allCallers = allCallers.filter(c => index.matchesFilters(c.relativePath, { exclude: options.exclude }));
@@ -802,16 +1159,72 @@ function about(index, name, options = {}) {
             allCallers = callerResult.kept;
             aboutConfFiltered += callerResult.filtered;
         }
+        // BUG-H1: post-filter total — count the un-enriched shadow candidates that
+        // also pass the same filters, so the displayed "showing N of <total>"
+        // matches what `context` (which runs unbounded) would have shown.
+        let shadowSurvivors = shadowCallers;
+        if (options.exclude && options.exclude.length > 0) {
+            shadowSurvivors = shadowSurvivors.filter(c => index.matchesFilters(c.relativePath, { exclude: options.exclude }));
+        }
+        if (options.minConfidence > 0) {
+            shadowSurvivors = shadowSurvivors.filter(c => (c.confidence || 0) >= options.minConfidence);
+        }
+        // Tag reachability on raw caller objects so we can preserve the field on the projection.
+        // Reachability is computed once per index and cached.
+        const aboutReachable = computeReachability(index);
+        tagCallersReachable(allCallers, aboutReachable);
+
+        // Optional: filter to unreachable-only callers
+        if (options.unreachableOnly) {
+            allCallers = allCallers.filter(c => !c.reachable);
+            // Apply same filter to shadows using their callerStartLine/file when available.
+            // Shadows lack callerStartLine, so they're treated as reachable=false (conservative,
+            // matches the historical behavior where un-enriched callers had no reachability info).
+            // We exclude all shadows here since unreachableOnly is a niche flag and the cost of
+            // building a perfect estimate isn't justified.
+            shadowSurvivors = []; // conservative — drop shadows for unreachableOnly mode
+        }
+        // Stash the post-filter total on allCallers so the result builder can use it.
+        Object.defineProperty(allCallers, '__postFilterTotal', {
+            value: allCallers.length + shadowSurvivors.length,
+            enumerable: false,
+            configurable: true,
+        });
+        // R3-NEW-1: stash shadow survivors so the histogram can include them.
+        // Without this the histogram only reflects the enriched (capped) callers,
+        // not the true total reported in `total`.
+        Object.defineProperty(allCallers, '__shadowSurvivors', {
+            value: shadowSurvivors,
+            enumerable: false,
+            configurable: true,
+        });
+
         callers = allCallers.slice(0, maxCallers).map(c => ({
             file: c.relativePath,
             line: c.line,
+            // Stable handle for the *caller function*, not the call site.
+            // Lets the caller copy-paste the handle to drill into who-called-this.
+            ...(c.callerStartLine && c.callerName && {
+                handle: `${c.relativePath}:${c.callerStartLine}:${c.callerName}`
+            }),
             expression: c.content.trim(),
             callerName: c.callerName,
             confidence: c.confidence,
             resolution: c.resolution,
+            reachable: c.reachable,
         }));
 
-        allCallees = index.findCallees(primary, { includeMethods, includeUncertain: options.includeUncertain });
+        // BUG-M3: classes/structs/interfaces don't have meaningful callees
+        // (their body is methods, not a sequence of calls). Skip findCallees
+        // for type definitions — callers (constructor/instantiation sites)
+        // are the useful signal here.
+        const TYPE_DEF_KINDS = new Set(['class', 'struct', 'interface', 'type',
+            'enum', 'trait', 'impl', 'record', 'namespace']);
+        if (TYPE_DEF_KINDS.has(primary.type)) {
+            allCallees = [];
+        } else {
+            allCallees = index.findCallees(primary, { includeMethods, includeUncertain: options.includeUncertain });
+        }
         // Apply exclude filter before slicing
         if (options.exclude && options.exclude.length > 0) {
             allCallees = allCallees.filter(c => index.matchesFilters(c.relativePath, { exclude: options.exclude }));
@@ -823,21 +1236,37 @@ function about(index, name, options = {}) {
             allCallees = calleeResult.kept;
             aboutConfFiltered += calleeResult.filtered;
         }
+
+        // Tag callee reachability + optional unreachable-only filter
+        tagCalleesReachable(allCallees, aboutReachable);
+        if (options.unreachableOnly) {
+            allCallees = allCallees.filter(c => !c.reachable);
+        }
+        tagCalleesSideEffects(index, allCallees);
+
         callees = allCallees.slice(0, maxCallees).map(c => ({
             name: c.name,
             file: c.relativePath,
             line: c.startLine,
             startLine: c.startLine,
             endLine: c.endLine,
+            handle: c.startLine ? `${c.relativePath}:${c.startLine}:${c.name}` : undefined,
             weight: c.weight,
             callCount: c.callCount,
             confidence: c.confidence,
             resolution: c.resolution,
+            reachable: c.reachable,
+            ...(c.returnType && { returnType: c.returnType }),
+            ...(c.paramTypes && { paramTypes: c.paramTypes }),
+            ...(c.paramsStructured && { paramsStructured: c.paramsStructured }),
+            ...(c.docstring && { docstring: c.docstring }),
+            ...(c.sideEffects && c.sideEffects.length && { sideEffects: c.sideEffects }),
         }));
     }
 
     // Find tests — scope to the same file/class as the primary definition
-    const tests = index.tests(symbolName, {
+    // Skip expensive test search for highly ambiguous names (>10 other definitions)
+    const tests = (others.length > 10 && !options.all) ? [] : index.tests(symbolName, {
         file: options.file,
         className: options.className || primary.className,
         exclude: options.exclude,
@@ -891,6 +1320,16 @@ function about(index, name, options = {}) {
         }
     }
 
+    // Optional git enrichment for the primary symbol's file.
+    // Attached only when options.git is set; skipped silently if not a git repo.
+    // Cheap (single git log invocation, cached per process) and gracefully
+    // degrades — formatters check `git.available` before rendering.
+    let gitInfo = null;
+    if (options.git) {
+        const { getGitInfo } = require('./git-enrich');
+        gitInfo = getGitInfo(index.root, primary.relativePath);
+    }
+
     const result = {
         found: true,
         symbol: {
@@ -899,21 +1338,39 @@ function about(index, name, options = {}) {
             file: primary.relativePath,
             startLine: primary.startLine,
             endLine: primary.endLine,
+            handle: require('./shared').formatSymbolHandle(primary),
             params: primary.params,
+            ...(primary.paramsStructured && { paramsStructured: primary.paramsStructured }),
             returnType: primary.returnType,
+            ...(primary.paramTypes && { paramTypes: primary.paramTypes }),
+            ...(primary.isAsync && { isAsync: true }),
+            ...(primary.isGenerator && { isGenerator: true }),
+            ...(primary.decorators && primary.decorators.length && { decorators: primary.decorators }),
             modifiers: primary.modifiers,
             docstring: primary.docstring,
             signature: index.formatSignature(primary)
         },
+        ...(gitInfo && { git: gitInfo }),
         usages: usagesByType,
         totalUsages: usagesByType.calls + usagesByType.imports + usagesByType.references,
         callers: {
-            total: allCallers?.length ?? 0,
-            top: callers
+            // BUG-H1: prefer post-filter total (computed from enriched + shadow candidates).
+            // Falls back to allCallers.length when the post-filter total wasn't computed
+            // (e.g., when primary is not a function and findCallers wasn't called).
+            total: allCallers?.__postFilterTotal ?? allCallers?.length ?? 0,
+            top: callers,
+            // R3-NEW-1: include shadow callers (un-enriched candidates that passed the
+            // same filters) so the histogram counts sum to `total`, not maxResults*3.
+            histogram: buildHistogram(
+                allCallers && allCallers.__shadowSurvivors && allCallers.__shadowSurvivors.length > 0
+                    ? [...allCallers, ...allCallers.__shadowSurvivors]
+                    : allCallers
+            ),
         },
         callees: {
             total: allCallees?.length ?? 0,
-            top: callees
+            top: callees,
+            histogram: buildHistogram(allCallees),
         },
         tests: testSummary,
         otherDefinitions: (options.all ? others : others.slice(0, 3)).map(d => ({
@@ -925,6 +1382,9 @@ function about(index, name, options = {}) {
         code,
         includeMethods,
         ...(aboutConfFiltered > 0 && { confidenceFiltered: aboutConfFiltered }),
+        // BUG-M4: surface ambiguous-resolution warnings so formatters can render
+        // a "auto-selected ... pass --file to choose" note.
+        ...(aboutWarnings.length > 0 && { warnings: aboutWarnings }),
         completeness: detectCompleteness(index)
     };
 
@@ -1051,6 +1511,31 @@ function diffImpact(index, options = {}) {
         // Track which functions are affected by added/modified lines
         const affectedSymbols = new Map(); // symbolName -> { symbol, addedLines, deletedLines }
 
+        // Pre-compute old file's symbol identities (BUG-F): use the old AST as the
+        // authoritative source for "did this function exist before?". Avoids the
+        // line-arithmetic guess that was wrong for tightly-packed 1-line functions.
+        // The identity key is `name\0className` (matches deletion-detection below).
+        let oldSymbolIdentities = null; // null = unknown (file untracked or git failed)
+        if (change.deletedLines.length > 0 || change.addedLines.length > 0) {
+            const ref = staged ? 'HEAD' : base;
+            try {
+                const oldContent = execFileSync(
+                    'git', ['show', `${ref}:${change.gitRelativePath}`],
+                    { cwd: index.root, encoding: 'utf-8', maxBuffer: 10 * 1024 * 1024, stdio: ['ignore', 'pipe', 'ignore'] }
+                );
+                const fileLang = detectLanguage(change.filePath);
+                if (fileLang) {
+                    const oldParsed = parse(oldContent, fileLang);
+                    oldSymbolIdentities = new Set();
+                    for (const oldFn of extractCallableSymbols(oldParsed)) {
+                        oldSymbolIdentities.add(`${oldFn.name}\0${oldFn.className || ''}`);
+                    }
+                }
+            } catch (e) {
+                // File didn't exist in base, or git error — leave null (unknown).
+            }
+        }
+
         for (const line of change.addedLines) {
             const symbol = index.findEnclosingFunction(change.filePath, line, true);
             if (symbol) {
@@ -1080,18 +1565,47 @@ function diffImpact(index, options = {}) {
             // since those lines no longer exist. Track as module-level unless they map
             // to a function that still exists (the function was modified, not deleted).
             // We approximate: if a deleted line is within the range of a known symbol, it's a modification.
-            let matched = false;
+            // Pick the MOST-SPECIFIC match: prefer exact-contained over tolerance-contained,
+            // and among ties prefer the smallest range (innermost). This avoids an earlier
+            // symbol's expanded ±2 range claiming a line that actually belongs to a later
+            // 1-line function in tightly-packed files (BUG-F).
+            let bestSymbol = null;
+            let bestExact = false;
+            let bestRange = Infinity;
             for (const symbol of fileEntry.symbols) {
                 if (NON_CALLABLE_TYPES.has(symbol.type)) continue;
-                // Use a generous range — deleted lines near a function likely belong to it
-                if (line >= symbol.startLine - 2 && line <= symbol.endLine + 2) {
-                    const key = `${symbol.name}:${symbol.startLine}`;
+                const exact = line >= symbol.startLine && line <= symbol.endLine;
+                const tolerant = line >= symbol.startLine - 2 && line <= symbol.endLine + 2;
+                if (!exact && !tolerant) continue;
+                const range = symbol.endLine - symbol.startLine;
+                // Prefer exact-contained over tolerance-contained; among same kind, smaller range wins.
+                const better = bestSymbol === null
+                    || (exact && !bestExact)
+                    || (exact === bestExact && range < bestRange);
+                if (better) {
+                    bestSymbol = symbol;
+                    bestExact = exact;
+                    bestRange = range;
+                }
+            }
+            let matched = false;
+            if (bestSymbol) {
+                // Only attribute to a symbol that ALSO existed in the old file. If we
+                // know the old identities and this symbol wasn't there, it's a brand-new
+                // function — its "deleted line" is really a neighboring line that gets
+                // pushed up by the diff hunk header. Treat as module-level so the new
+                // symbol stays cleanly in newFunctions[] (BUG-F).
+                const identityKey = `${bestSymbol.name}\0${bestSymbol.className || ''}`;
+                const existedBefore = oldSymbolIdentities === null
+                    ? true
+                    : oldSymbolIdentities.has(identityKey);
+                if (existedBefore) {
+                    const key = `${bestSymbol.name}:${bestSymbol.startLine}`;
                     if (!affectedSymbols.has(key)) {
-                        affectedSymbols.set(key, { symbol, addedLines: [], deletedLines: [] });
+                        affectedSymbols.set(key, { symbol: bestSymbol, addedLines: [], deletedLines: [] });
                     }
                     affectedSymbols.get(key).deletedLines.push(line);
                     matched = true;
-                    break;
                 }
             }
             if (!matched) {
@@ -1109,12 +1623,22 @@ function diffImpact(index, options = {}) {
             }
         }
 
-        // Detect new functions: all added lines are within a single function range
-        // and the function didn't exist before (approximation: all lines in the function are added)
+        // Detect new functions: a function is new if it didn't exist in the old file
+        // by identity (name + className). This is authoritative — no more line-count
+        // heuristics. Falls back to the old line-arithmetic approximation when the
+        // old file is unreachable (e.g. untracked or pre-base).
         for (const [key, data] of affectedSymbols) {
             const { symbol, addedLines } = data;
-            const fnLineCount = symbol.endLine - symbol.startLine + 1;
-            if (addedLines.length >= fnLineCount * 0.8 && data.deletedLines.length === 0) {
+            const identityKey = `${symbol.name}\0${symbol.className || ''}`;
+            let isNew;
+            if (oldSymbolIdentities !== null) {
+                isNew = !oldSymbolIdentities.has(identityKey);
+            } else {
+                // Fallback: 80% of body lines added and no deletions hit this symbol.
+                const fnLineCount = symbol.endLine - symbol.startLine + 1;
+                isNew = addedLines.length >= fnLineCount * 0.8 && data.deletedLines.length === 0;
+            }
+            if (isNew) {
                 newFunctions.push({
                     name: symbol.name,
                     filePath: change.filePath,
@@ -1390,6 +1914,403 @@ function parseDiff(diffText, root) {
     return changes;
 }
 
+// ============================================================================
+// AUDIT-ASYNC (Feature B)
+// ============================================================================
+
+// Languages for which audit-async runs (those with async/await keyword we
+// track). Go/Java/Rust have async machinery but audit-async is scoped to
+// JS/TS/Python per spec.
+const _AUDIT_ASYNC_LANGS = new Set(['javascript', 'typescript', 'tsx', 'python', 'html']);
+
+// Built-in/standard-library callees that return promises and are commonly
+// missing-awaited. Conservative starter set (rule #9 — generic, not
+// project-specific). The audit only flags when the caller is async, the
+// callee is provably async, AND the call isn't awaited; this set covers
+// callees we can recognize without project-symbol resolution.
+const _KNOWN_ASYNC_CALLEES = new Set([
+    // JS/TS
+    'fetch',
+    // Node.js fs.promises etc. are method calls — `fs.readFile` resolves
+    // through the symbol table as a method. We avoid hardcoding receiver
+    // names here. setTimeout/setInterval are fire-and-forget by design.
+]);
+
+// Fire-and-forget patterns — calls inside these contexts are intentionally
+// unawaited. Used to suppress false positives.
+//   - Promise.all / Promise.allSettled / Promise.race / Promise.any
+//   - void <expr>
+//   - <expr>.then() / .catch() (the call provides its own handler)
+const _FIRE_AND_FORGET_PROMISE_FNS = new Set(['all', 'allSettled', 'race', 'any']);
+
+/**
+ * Run an async/await audit across the project.
+ *
+ * Finds call sites that are likely missing an `await`. A site is flagged
+ * when ALL of:
+ *   1. The enclosing function is async (or top-level module code in an
+ *      async-context module — JS modules with top-level await).
+ *   2. The callee is provably async (its symbol's `isAsync` is true) OR
+ *      the callee is a known async standard function (e.g., `fetch`).
+ *   3. The call is not wrapped in `await` (or its Python equivalent).
+ *   4. The call is not in a known fire-and-forget context (Promise.all
+ *      arguments, `void fn()`, `.then(...)`, return statement, assignment
+ *      to a variable — these are intentional non-await uses).
+ *
+ * Detection is AST-based per language; the language must support an
+ * `await` keyword (JS/TS/Python). Other languages are skipped.
+ *
+ * @param {object} index - ProjectIndex instance
+ * @param {object} [options] - { file, exclude }
+ * @returns {{issues: Array<{file:string,line:number,callerName:string,calleeName:string,reason?:string}>}}
+ */
+function auditAsync(index, options = {}) {
+    index._beginOp();
+    try {
+        const { detectLanguage, getParser, getLanguageModule, safeParse } = require('../languages');
+        const issues = [];
+
+        // Build a "is this name provably async" lookup from the symbol table.
+        // We accept a global name only if EVERY callable definition with that
+        // name is async — this avoids flagging ambiguous calls like `Map.get()`
+        // where the project also has a `DataService.get()` async method.
+        //
+        // BUT: we ALSO track per-file async-name resolution. JavaScript/Python
+        // module scope means a same-file definition shadows globals, so when
+        // a caller's file contains an async definition with that name, that
+        // definition wins regardless of what other files contain. This is
+        // critical to avoid silent false-negatives caused by name collisions
+        // across files (HIGH-1 fix).
+        const asyncNames = new Set();
+        const ambiguousNames = new Set(); // any non-async def exists somewhere
+        const callableDefs = (defs) => defs.filter(d => d && (
+            d.type === 'function' || d.type === 'method' ||
+            d.type === 'constructor' || d.type === 'arrow' ||
+            d.params != null || d.paramsStructured != null
+        ));
+        const isDefAsync = (d) => d.isAsync === true ||
+            (Array.isArray(d.modifiers) && d.modifiers.includes('async'));
+        for (const [name, defs] of index.symbols) {
+            const callable = callableDefs(defs);
+            if (callable.length === 0) continue;
+            const allAsync = callable.every(isDefAsync);
+            if (allAsync) {
+                asyncNames.add(name);
+            } else if (callable.some(isDefAsync)) {
+                ambiguousNames.add(name);
+            }
+        }
+
+        // Helper: does the call site (callExpr node) sit in a "fire-and-forget"
+        // context? Walk up at most a few levels and check for known patterns.
+        function isFireAndForget(callNode, language) {
+            let p = callNode.parent;
+            // 1. Direct `void fn()` (JS/TS only)
+            if (p && p.type === 'unary_expression') {
+                const op = p.childForFieldName('operator');
+                if (op && op.text === 'void') return true;
+                // Some grammars expose first child as the operator
+                const first = p.namedChild(0);
+                if (first && first.type === 'void') return true;
+            }
+            // 2. Argument of `Promise.all([...])` / `Promise.allSettled` / etc.
+            //    Walk up: arguments > call > selector_expression(member) > 'Promise'.<allSettled>.
+            //    The call site is somewhere inside the array; check if the
+            //    enclosing call is a Promise.all-style helper.
+            let cur = callNode.parent;
+            let depth = 0;
+            while (cur && depth++ < 6) {
+                if ((cur.type === 'call_expression' || cur.type === 'call') && cur !== callNode) {
+                    const fn = cur.childForFieldName('function');
+                    if (fn) {
+                        if (fn.type === 'member_expression' || fn.type === 'attribute') {
+                            const obj = fn.childForFieldName('object') || fn.namedChild(0);
+                            const prop = fn.childForFieldName('property') || fn.namedChild(fn.namedChildCount - 1);
+                            if (obj && prop) {
+                                const objText = obj.text;
+                                const propText = prop.text;
+                                if ((objText === 'Promise' || objText === 'asyncio') &&
+                                    _FIRE_AND_FORGET_PROMISE_FNS.has(propText)) {
+                                    return true;
+                                }
+                                // .then(...) / .catch(...) — caller is providing a handler;
+                                // the inner call is intentional.
+                                if (propText === 'then' || propText === 'catch' || propText === 'finally') {
+                                    // Only flag when callNode is INSIDE the chain target,
+                                    // not just an argument
+                                    return true;
+                                }
+                            }
+                        }
+                    }
+                    // Stop at the first enclosing call — we don't want to leak
+                    // analysis past the immediate parent call.
+                    break;
+                }
+                cur = cur.parent;
+            }
+            // 3. Right-hand side of an assignment / variable_declarator — the
+            //    promise is being captured for later use, not lost. NOT
+            //    fire-and-forget but also NOT a missing-await; treat as
+            //    intentional.
+            //    (We keep this distinct so the "captured" call doesn't get
+            //    flagged.)
+            let q = callNode.parent;
+            // Skip await wrappers (already handled by caller)
+            if (q && (q.type === 'await_expression' || q.type === 'await')) {
+                q = q.parent;
+            }
+            if (q) {
+                if (q.type === 'variable_declarator' || q.type === 'assignment_expression') {
+                    return true;
+                }
+                if (q.type === 'return_statement') {
+                    return true;  // returning the promise — caller awaits it
+                }
+                // Yielded as an expression: `yield fn()` — caller awaits / async iterator
+                if (q.type === 'yield_expression' || q.type === 'yield') {
+                    return true;
+                }
+            }
+            return false;
+        }
+
+        // Process one file: find async functions, then call sites within them.
+        function processFile(filePath, fileEntry) {
+            if (!fileEntry || !_AUDIT_ASYNC_LANGS.has(fileEntry.language)) return;
+            const language = fileEntry.language;
+
+            // Collect async functions from the file's symbol list.
+            // Also build a per-file set of names that are async in THIS file —
+            // these win over the global "all-or-nothing" check (HIGH-1 fix).
+            // JS/Python module scope means a same-file def shadows imports of
+            // the same name, so a sync def of `helper` elsewhere in the project
+            // shouldn't make `helper()` ambiguous in a file that defines
+            // `async function helper()` locally.
+            const asyncFns = [];
+            const fileAsyncNames = new Set();
+            const fileAnyDefNames = new Set();
+            if (Array.isArray(fileEntry.symbols)) {
+                for (const sym of fileEntry.symbols) {
+                    if (!sym || !sym.startLine || !sym.endLine) continue;
+                    const isAsync = sym.isAsync === true ||
+                                    (Array.isArray(sym.modifiers) && sym.modifiers.includes('async'));
+                    if (isAsync) asyncFns.push(sym);
+                    if (sym.name && (
+                        sym.type === 'function' || sym.type === 'method' ||
+                        sym.type === 'constructor' || sym.type === 'arrow' ||
+                        sym.params != null || sym.paramsStructured != null
+                    )) {
+                        fileAnyDefNames.add(sym.name);
+                        if (isAsync) fileAsyncNames.add(sym.name);
+                    }
+                }
+            }
+            if (asyncFns.length === 0) return;
+
+            // Re-parse file to find awaited-vs-not call sites. We use a fresh
+            // parse rather than tree cache because we want to walk every
+            // call_expression in the async function ranges.
+            let parser, content, tree;
+            try {
+                if (language === 'html') {
+                    const htmlModule = getLanguageModule('html');
+                    const htmlParser = getParser('html');
+                    const jsParser = getParser('javascript');
+                    if (!htmlParser || !jsParser) return;
+                    content = index._readFile(filePath);
+                    const blocks = htmlModule.extractScriptBlocks(content, htmlParser);
+                    if (blocks.length === 0) return;
+                    const virtualJS = htmlModule.buildVirtualJSContent(content, blocks);
+                    tree = safeParse(jsParser, virtualJS);
+                } else {
+                    parser = getParser(language);
+                    if (!parser) return;
+                    content = index._readFile(filePath);
+                    tree = safeParse(parser, content);
+                }
+            } catch (_) { return; }
+            if (!tree) return;
+
+            // Walk every call_expression within an async function range.
+            const callTypes = new Set(['call_expression', 'call', 'method_invocation', 'object_creation_expression']);
+
+            // Function-boundary nodes per language (used to find the nearest
+            // enclosing function and determine if IT is async — not just any
+            // outer ancestor).
+            const FN_NODE_TYPES = {
+                javascript: new Set(['function_declaration', 'function_expression', 'arrow_function', 'method_definition', 'generator_function', 'generator_function_declaration']),
+                typescript: new Set(['function_declaration', 'function_expression', 'arrow_function', 'method_definition', 'generator_function', 'generator_function_declaration', 'function_signature']),
+                tsx:        new Set(['function_declaration', 'function_expression', 'arrow_function', 'method_definition', 'generator_function', 'generator_function_declaration', 'function_signature']),
+                html:       new Set(['function_declaration', 'function_expression', 'arrow_function', 'method_definition', 'generator_function', 'generator_function_declaration']),
+                python:     new Set(['function_definition', 'async_function_definition', 'lambda']),
+            }[language] || new Set();
+
+            function isAsyncFnNode(node) {
+                if (!node) return false;
+                // Python: async_function_definition is the explicit marker.
+                if (node.type === 'async_function_definition') return true;
+                // JS/TS arrow_function / function_expression / function_declaration:
+                // the `async` keyword is a child of the node OR appears as
+                // first token in node text.
+                const t = node.text || '';
+                if (t.trimStart().startsWith('async ')) return true;
+                // method_definition: scan first child for 'async' identifier.
+                for (let i = 0; i < node.namedChildCount; i++) {
+                    const c = node.namedChild(i);
+                    if (c.type === 'async') return true;
+                }
+                return false;
+            }
+
+            // Find the nearest enclosing function symbol whose name matches
+            // a top-level async fn. Returns the symbol when the call's
+            // immediate enclosing fn-node is async (so callbacks inside an
+            // async fn aren't misclassified as async themselves).
+            function nearestAsyncEnclosing(callNode) {
+                let cur = callNode.parent;
+                while (cur) {
+                    if (FN_NODE_TYPES.has(cur.type)) {
+                        if (isAsyncFnNode(cur)) {
+                            // Match against asyncFns to get caller name.
+                            const startLine = cur.startPosition.row + 1;
+                            for (const fn of asyncFns) {
+                                if (fn.startLine === startLine) return fn;
+                            }
+                            // Anonymous async fn — return a synthetic record.
+                            return {
+                                name: '<anonymous>',
+                                startLine,
+                                endLine: cur.endPosition.row + 1,
+                            };
+                        }
+                        return null; // Inner non-async fn — stop, don't leak into outer scope.
+                    }
+                    cur = cur.parent;
+                }
+                return null;
+            }
+
+            function visit(node) {
+                if (!node) return;
+                if (callTypes.has(node.type)) {
+                    const line = node.startPosition.row + 1;
+                    const enclosing = nearestAsyncEnclosing(node);
+                    if (enclosing) {
+                        // Get the callee name + skip if not async.
+                        const funcNode = node.childForFieldName('function') ||
+                                         node.childForFieldName('name');
+                        if (funcNode) {
+                            let calleeName;
+                            let isMethodCall = false;
+                            if (funcNode.type === 'member_expression' || funcNode.type === 'attribute' ||
+                                funcNode.type === 'selector_expression' || funcNode.type === 'field_expression') {
+                                const prop = funcNode.childForFieldName('property') ||
+                                             funcNode.childForFieldName('field') ||
+                                             funcNode.childForFieldName('attribute');
+                                calleeName = prop ? prop.text : null;
+                                isMethodCall = true;
+                            } else {
+                                calleeName = funcNode.text;
+                            }
+                            if (calleeName) {
+                                // Check whether the callee is provably async.
+                                // File-local resolution wins (HIGH-1 fix): if
+                                // THIS file defines an async function with that
+                                // name, the call resolves to it regardless of
+                                // what other files contain. This avoids silent
+                                // false-negatives caused by name collisions
+                                // (e.g., async helper in bad.js + sync helper
+                                // in unrelated.js — bad.js's helper() should
+                                // still be flagged).
+                                let calleeIsAsync;
+                                if (fileAsyncNames.has(calleeName)) {
+                                    calleeIsAsync = true;
+                                } else if (fileAnyDefNames.has(calleeName)) {
+                                    // Same-file def exists and isn't async →
+                                    // local def shadows globals → not async.
+                                    calleeIsAsync = false;
+                                } else {
+                                    // No same-file def — fall back to global
+                                    // all-or-nothing check.
+                                    calleeIsAsync = asyncNames.has(calleeName) ||
+                                                    _KNOWN_ASYNC_CALLEES.has(calleeName);
+                                }
+                                if (calleeIsAsync) {
+                                    // Skip method calls in structural type
+                                    // systems (JS/TS/Python). Without receiver
+                                    // type evidence we can't tell `obj.get()`
+                                    // calling `Map.get` (sync) from a project
+                                    // class's async `get`. Method-call audits
+                                    // need a more sophisticated receiver
+                                    // resolution that we don't have here.
+                                    if (isMethodCall) {
+                                        // (Allow only when callee is in the
+                                        // KNOWN_ASYNC_CALLEES list — those are
+                                        // standard global functions, not
+                                        // methods.)
+                                        if (!_KNOWN_ASYNC_CALLEES.has(calleeName)) {
+                                            // Continue walking — don't flag.
+                                        } else {
+                                            // Fall through to common flag logic
+                                        }
+                                    }
+                                    if (!isMethodCall || _KNOWN_ASYNC_CALLEES.has(calleeName)) {
+                                        // Check: is the call awaited?
+                                        let awaited = false;
+                                        const p = node.parent;
+                                        if (p && (p.type === 'await_expression' || p.type === 'await')) {
+                                            awaited = true;
+                                        }
+                                        if (!awaited && !isFireAndForget(node, language)) {
+                                            issues.push({
+                                                file: fileEntry.relativePath || filePath,
+                                                line,
+                                                callerName: enclosing.name,
+                                                calleeName,
+                                            });
+                                        }
+                                    }
+                                }
+                            }
+                        }
+                    }
+                }
+                for (let i = 0; i < node.namedChildCount; i++) {
+                    visit(node.namedChild(i));
+                }
+            }
+            visit(tree.rootNode);
+        }
+
+        // Apply file/exclude filters via index.matchesFilters when available.
+        const exclude = Array.isArray(options.exclude) ? options.exclude : [];
+        const fileFilter = options.file || null;
+
+        for (const [filePath, fileEntry] of index.files) {
+            if (exclude.length > 0 && !index.matchesFilters(filePath, { exclude })) continue;
+            if (fileFilter && !(fileEntry.relativePath || '').includes(fileFilter)) continue;
+            processFile(filePath, fileEntry);
+        }
+
+        // Stable ordering (rule #11): sort by (file, line, callerName, calleeName).
+        issues.sort((a, b) => {
+            const fc = String(a.file).localeCompare(String(b.file));
+            if (fc !== 0) return fc;
+            if (a.line !== b.line) return a.line - b.line;
+            const cc = String(a.callerName || '').localeCompare(String(b.callerName || ''));
+            if (cc !== 0) return cc;
+            return String(a.calleeName || '').localeCompare(String(b.calleeName || ''));
+        });
+
+        return {
+            issues,
+            totalIssues: issues.length,
+            filesAffected: new Set(issues.map(i => i.file)).size,
+        };
+    } finally { index._endOp(); }
+}
+
 module.exports = {
     context,
     smart,
@@ -1401,4 +2322,6 @@ module.exports = {
     parseDiff,
     extractCallableSymbols,
     unquoteDiffPath,
+    auditAsync,
+    tagInTestCase,
 };