ucn 4.2.3 → 5.0.2

package/core/reporting.js

@@ -9,10 +9,25 @@
 
 const fs = require('fs');
 const { codeUnitCompare, CALLABLE_SYMBOL_KINDS } = require('./shared');
-const { _declaredFieldType, _projectTopLevelNames } = require('./callers');
 const path = require('path');
 const { isTestFile } = require('./discovery');
 const { summarizeCommandTrust } = require('./trust-matrix');
+const { projectComputedDispatch } = require('./ast-analysis');
+const { langTraits } = require('../languages');
+
+function matchesReportingScope(index, relativePath, options = {}) {
+    if (!relativePath) return false;
+    if (options.file && !relativePath.includes(options.file)) return false;
+    const exclude = Array.isArray(options.exclude)
+        ? options.exclude
+        : (options.exclude
+            ? String(options.exclude).split(',').map(s => s.trim()).filter(Boolean)
+            : []);
+    return index.matchesFilters(relativePath, {
+        ...(exclude.length > 0 && { exclude }),
+        ...(options.in && { in: options.in }),
+    });
+}
 
 /**
  * Get project statistics: file counts, symbol counts, LOC, language breakdown.
@@ -22,15 +37,15 @@ const { summarizeCommandTrust } = require('./trust-matrix');
  * @returns {object}
  */
 function getStats(index, options = {}) {
-    // Count total symbols (not just unique names)
-    let totalSymbols = 0;
-    for (const [, symbols] of index.symbols) {
-        totalSymbols += symbols.length;
-    }
+    const scopedFiles = [...index.files].filter(([, fileEntry]) =>
+        matchesReportingScope(index, fileEntry.relativePath, options));
+    const scopedPaths = new Set(scopedFiles.map(([filePath]) => filePath));
+    const totalSymbols = scopedFiles.reduce(
+        (sum, [, fileEntry]) => sum + (fileEntry.symbols || []).length, 0);
 
     const stats = {
         root: index.root,
-        files: index.files.size,
+        files: scopedFiles.length,
         symbols: totalSymbols,  // Total symbol count, not unique names
         buildTime: index.buildTime,
         byLanguage: {},
@@ -38,7 +53,7 @@ function getStats(index, options = {}) {
         ...(index.truncated && { truncated: index.truncated })
     };
 
-    for (const [, fileEntry] of index.files) {
+    for (const [, fileEntry] of scopedFiles) {
         const lang = fileEntry.language;
         if (!stats.byLanguage[lang]) {
             stats.byLanguage[lang] = { files: 0, lines: 0, symbols: 0 };
@@ -48,8 +63,8 @@ function getStats(index, options = {}) {
         stats.byLanguage[lang].symbols += fileEntry.symbols.length;
     }
 
-    for (const [, symbols] of index.symbols) {
-        for (const sym of symbols) {
+    for (const [, fileEntry] of scopedFiles) {
+        for (const sym of fileEntry.symbols || []) {
             if (!Object.hasOwn(stats.byType, sym.type)) {
                 stats.byType[sym.type] = 0;
             }
@@ -59,17 +74,22 @@ function getStats(index, options = {}) {
 
     // Surface build warnings (parse failures, skipped files)
     if (index.failedFiles && index.failedFiles.size > 0) {
-        stats.warnings = {
-            failedFiles: [...index.failedFiles].map(f => path.relative(index.root, f)),
-            count: index.failedFiles.size
-        };
+        const failedFiles = [...index.failedFiles]
+            .map(f => path.relative(index.root, f))
+            .filter(rel => matchesReportingScope(index, rel, options));
+        if (failedFiles.length > 0) {
+            stats.warnings = {
+                failedFiles,
+                count: failedFiles.length,
+            };
+        }
     }
 
     // Per-function line counts for complexity audits
     if (options.functions) {
         const functions = [];
-        for (const [, symbols] of index.symbols) {
-            for (const sym of symbols) {
+        for (const [, fileEntry] of scopedFiles) {
+            for (const sym of fileEntry.symbols || []) {
                 if (CALLABLE_SYMBOL_KINDS.has(sym.type)) {
                     const lineCount = sym.endLine - sym.startLine + 1;
                     const relativePath = sym.relativePath || (sym.file ? path.relative(index.root, sym.file) : '');
@@ -107,258 +127,112 @@ function getStats(index, options = {}) {
             index.buildCalleeIndex();
         }
 
-        // BUG-H2: aggregate calls by *resolution kind* so a method call like
-        // `dict.get()` doesn't get attributed to a standalone `function get()`.
-        //
-        // Buckets per name:
-        //   bareNameCounts[name]     — calls with !isMethod (e.g. `get()`)
-        //   methodByReceiverType[t][name] — calls with isMethod and inferred receiverType
-        //   methodByName[name]       — all isMethod calls (fallback denominator)
-        //   importedReceiverCounts[name] — method calls whose receiver is an imported
-        //                                  module alias in the calling file (e.g.
-        //                                  `mod.foo()` where `mod` is a require alias).
-        //                                  These resolve like top-level function calls.
-        //
-        // self/this/cls/super counted under bareNameCounts since they always resolve
-        // to the enclosing class's method (handled in attribution below).
-        // We dedupe per file by (name, line) so multi-record call sites count once.
-        const SELF_RECEIVERS = new Set(['self', 'this', 'cls', 'super']);
-        const bareNameCounts = new Map();           // name -> count
-        const methodByReceiverType = new Map();      // receiverType -> Map(name -> count)
-        const methodByName = new Map();              // name -> count of all method calls
-        const selfMethodByName = new Map();          // name -> count of self/this.name() calls
-        const importedReceiverCounts = new Map();    // name -> count of `mod.name()` calls
-                                                     //          where mod is an import alias
-
-        // Pre-compute import-alias sets per file. Used to distinguish `mod.foo()`
-        // (resolves to top-level foo) from `obj.foo()` on a local variable.
-        const fileImportAliases = new Map();         // filePath -> Set<string> of alias names
-        const fieldHopCache = new Map();             // rootType\0field -> declared type|null
-        // Names import-bound to an EXTERNAL module, per file (fix #256,
-        // dogfood-measured: 895 node:test `describe(...)` calls in test
-        // files were attributed to a project closure named `describe` —
-        // the #215 name discipline says an externally-bound bare name
-        // cannot reach a project def, so it never counts toward the hot
-        // leaderboard). Relative modules, resolved modules, and resolver
-        // gaps (first segment names a project path) all stay countable.
-        const fileExternalNames = new Map();         // filePath -> Set<string>
-        for (const [filePath, fileEntry] of index.files) {
-            const aliases = new Set();
-            // importNames are the named imports/exports brought into this file.
-            // importAliases (when present) carry namespace import aliases (e.g.
-            // `import * as mod from "..."` → 'mod').
-            for (const n of (fileEntry.importNames || [])) aliases.add(n);
-            if (Array.isArray(fileEntry.importAliases)) {
-                for (const a of fileEntry.importAliases) {
-                    if (a && a.local) aliases.add(a.local);
-                }
-            }
-            fileImportAliases.set(filePath, aliases);
-            let ext = null;
-            for (const b of (fileEntry.importBindings || [])) {
-                const mod = String(b.module || '');
-                if (!b.name || !mod || mod.startsWith('.') || mod.startsWith('/')) continue;
-                if (fileEntry.moduleResolved && fileEntry.moduleResolved[mod]) continue;
-                const firstSeg = mod.split(/[./]/).filter(Boolean)[0];
-                if (firstSeg && _projectTopLevelNames(index).has(firstSeg)) continue;
-                (ext || (ext = new Set())).add(b.name);
-            }
-            if (ext) fileExternalNames.set(filePath, ext);
-        }
-
+        // Build a cheap, provenance-independent upper bound per spelling.
+        // Every confirmed caller must first exist as a call record bearing the
+        // target name (or resolved import alias), so this count can safely
+        // decide which definitions are capable of entering the requested top
+        // N. Exact pinned caller resolution is then run only until no unseen
+        // candidate can beat the current Nth result.
+        const rawUpperByName = new Map();
         for (const [filePath, entry] of index.callsCache) {
+            if (!scopedPaths.has(filePath)) continue;
+            if (index.files.get(filePath)?.isBundled) continue;
             if (!entry || !Array.isArray(entry.calls)) continue;
             const seenInFile = new Set();
-            const aliasesForFile = fileImportAliases.get(filePath) || new Set();
             for (const c of entry.calls) {
                 if (!c || !c.name) continue;
                 const key = `${c.name}::${c.line || 0}`;
-                if (seenInFile.has(key)) continue;
-                seenInFile.add(key);
-
-                const isSelfMethod = c.isMethod && SELF_RECEIVERS.has(c.receiver);
-                if (!c.isMethod) {
-                    // Bare-name call: foo() or pkg.Foo() (Go package call has receiver
-                    // but isMethod:false — keep counting under bareName since they
-                    // resolve like top-level functions in their package).
-                    // Externally-bound names are the external library's calls,
-                    // never a project def's (fix #256).
-                    if (fileExternalNames.get(filePath)?.has(c.name)) continue;
-                    bareNameCounts.set(c.name, (bareNameCounts.get(c.name) || 0) + 1);
-                } else if (isSelfMethod) {
-                    // self/this.foo() — attributed to the enclosing class's foo
-                    selfMethodByName.set(c.name, (selfMethodByName.get(c.name) || 0) + 1);
-                    methodByName.set(c.name, (methodByName.get(c.name) || 0) + 1);
-                } else {
-                    methodByName.set(c.name, (methodByName.get(c.name) || 0) + 1);
-                    // Module-alias receiver? `mod.foo()` where `mod` was imported here.
-                    // Treat the call as resolving to a top-level `foo` (the standalone
-                    // function exported from `mod`).
-                    if (c.receiver && aliasesForFile.has(c.receiver)) {
-                        importedReceiverCounts.set(c.name,
-                            (importedReceiverCounts.get(c.name) || 0) + 1);
-                    }
-                    // Field-access receivers (fix #251): `tm.service.Save()`
-                    // carries receiverRootType, not receiverType — the same
-                    // #202/#231 declared-field hop the caller/callee engine
-                    // uses. Without it, edges `context` confirms were
-                    // invisible to the hot leaderboard.
-                    let recvType = c.receiverType;
-                    if (!recvType && c.receiverField && c.receiverRootType) {
-                        const hopKey = `${c.receiverRootType}\u0000${c.receiverField}`;
-                        if (!fieldHopCache.has(hopKey)) {
-                            const lang = index.files.get(filePath)?.language;
-                            fieldHopCache.set(hopKey,
-                                lang ? _declaredFieldType(index, c.receiverRootType, c.receiverField, lang) : null);
-                        }
-                        recvType = fieldHopCache.get(hopKey);
-                    }
-                    if (recvType) {
-                        let inner = methodByReceiverType.get(recvType);
-                        if (!inner) {
-                            inner = new Map();
-                            methodByReceiverType.set(recvType, inner);
-                        }
-                        inner.set(c.name, (inner.get(c.name) || 0) + 1);
-                    }
+                if (!seenInFile.has(key)) {
+                    seenInFile.add(key);
+                    rawUpperByName.set(c.name, (rawUpperByName.get(c.name) || 0) + 1);
                 }
-                // Also account for resolvedName aliases (e.g. `import {foo as bar}; bar()`
-                // resolves to `foo`). Treat the resolved form the same way as the original.
                 if (c.resolvedName && c.resolvedName !== c.name) {
                     const rkey = `${c.resolvedName}::${c.line || 0}`;
                     if (!seenInFile.has(rkey)) {
                         seenInFile.add(rkey);
-                        if (!c.isMethod) {
-                            bareNameCounts.set(c.resolvedName,
-                                (bareNameCounts.get(c.resolvedName) || 0) + 1);
-                        }
+                        rawUpperByName.set(c.resolvedName,
+                            (rawUpperByName.get(c.resolvedName) || 0) + 1);
                     }
                 }
             }
         }
 
-        // For each name, count how many distinct classes/types own a method with
-        // that name (used to split method-call counts when receiverType is unknown).
-        const classOwnersByName = new Map();         // name -> Set<className>
+        const candidates = [];
+        const seenDefinitions = new Set();
         for (const [name, symbols] of index.symbols) {
-            for (const sym of symbols) {
-                if (!FUNCTION_TYPES.has(sym.type)) continue;
-                const owner = sym.className || (sym.receiver && sym.receiver.replace(/^\*/, ''));
-                if (owner) {
-                    let s = classOwnersByName.get(name);
-                    if (!s) { s = new Set(); classOwnersByName.set(name, s); }
-                    s.add(owner);
+            const upper = rawUpperByName.get(name) || 0;
+            if (upper === 0) continue;
+            const callable = symbols.filter(symbol =>
+                FUNCTION_TYPES.has(symbol.type) &&
+                matchesReportingScope(index, symbol.relativePath, options));
+            for (const symbol of callable) {
+                if (index.files.get(symbol.file)?.isBundled) continue;
+                if (options.productionCallsOnly && require('./shared').isTestPath(symbol.relativePath)) continue;
+                const identity = `${symbol.file}:${symbol.startLine}:${name}:` +
+                    `${symbol.className || symbol.receiver || ''}:${symbol.params || ''}`;
+                if (seenDefinitions.has(identity)) continue;
+                seenDefinitions.add(identity);
+
+                // A linked C/C++ prototype and implementation close to the
+                // same compiler identity. Show the implementation once.
+                if (symbol.isSignature && callable.some(candidate =>
+                    !candidate.isSignature &&
+                    (candidate.className || candidate.receiver || null) ===
+                        (symbol.className || symbol.receiver || null) &&
+                    (index.importGraph.get(candidate.file)?.has(symbol.file) ||
+                        index.importGraph.get(symbol.file)?.has(candidate.file)))) {
+                    continue;
                 }
+                candidates.push({ name, symbol, upper });
             }
         }
+        candidates.sort((a, b) =>
+            (b.upper - a.upper) ||
+            codeUnitCompare(a.symbol.relativePath, b.symbol.relativePath) ||
+            (a.symbol.startLine || 0) - (b.symbol.startLine || 0));
 
-        // MEDIUM-6: aggregate by name. Multiple definitions of the same name
-        // in different files (e.g. `tmp` in test/helpers/index.js AND
-        // test/accuracy.test.js) previously each got the GLOBAL call count,
-        // duplicating the row and inflating the leaderboard. We now emit
-        // one row per name with a `locations` list, so the user sees both
-        // definitions but the count appears exactly once.
-        //
-        // BUG-H2: with the buckets above, attribute counts per (name, ownerClass):
-        //   - standalone function:   bareNameCounts[name]
-        //   - class method (Foo.bar): methodByReceiverType[Foo][bar]
-        //                              + selfMethodByName[bar] / numOwnerClasses
-        //                              + (residual unresolved method calls split evenly)
-        //   - falls back to methodByName[name] when no receiverType evidence exists.
         const hotList = [];
-        let usedHeuristicSplit = false;  // whether any row's count was approximated
-        for (const [name, symbols] of index.symbols) {
-            // Filter to function-shaped definitions, dedup by file:line.
-            const seenLoc = new Set();
-            const locations = [];
-            let representative = null;
-            const ownerClasses = new Set();      // classes/receivers that own this name
-            for (const sym of symbols) {
-                if (!FUNCTION_TYPES.has(sym.type)) continue;
-                const relativePath = sym.relativePath ||
-                    (sym.file ? path.relative(index.root, sym.file) : '');
-                const locKey = `${relativePath}:${sym.startLine}`;
-                if (seenLoc.has(locKey)) continue;
-                seenLoc.add(locKey);
-                locations.push({
-                    file: relativePath,
-                    startLine: sym.startLine,
-                    endLine: sym.endLine,
-                    ...(sym.className && { className: sym.className }),
+        const { findCallers } = require('./callers');
+        const scopedCallerQuery = !!(options.file || options.in ||
+            (options.exclude && options.exclude.length > 0));
+        let refined = 0;
+        if (top > 0) {
+            for (let candidateIndex = 0; candidateIndex < candidates.length; candidateIndex++) {
+                const { name, symbol } = candidates[candidateIndex];
+                const exact = findCallers(index, name, {
+                    targetDefinitions: [symbol],
+                    includeTests: true,
+                    collectAccount: true,
                 });
-                const owner = sym.className || (sym.receiver && sym.receiver.replace(/^\*/, ''));
-                if (owner) ownerClasses.add(owner);
-                if (!representative) representative = sym;
-            }
-            if (locations.length === 0) continue;
-
-            // Decide if this row represents a standalone function or a method.
-            // Mixed-type defs (e.g. "tmp" defined as both a function and a class method
-            // somewhere) are rare; for them we use the representative's flavor and
-            // accept that the count may be approximate.
-            const isMethodRow = ownerClasses.size > 0 &&
-                (!representative || !!representative.className || !!representative.receiver);
-
-            let count;
-            let approximate = false;
-            if (!isMethodRow) {
-                // Standalone function (or top-level package call): use bare-name calls
-                // plus method-style calls where the receiver was an imported module
-                // alias (e.g. `lib.foo()` where `lib` is a require/import alias).
-                // We deliberately do NOT include arbitrary `obj.foo()` calls — those
-                // would inflate the count with unrelated method calls (the H2 bug).
-                count = (bareNameCounts.get(name) || 0) +
-                        (importedReceiverCounts.get(name) || 0);
-            } else {
-                // Method definition. Count only calls we can resolve to this owner:
-                //   - typed hits (receiverType matches one of this row's owner classes)
-                //   - self-method calls inside this owner class (counted via callerSymbol)
-                // Calls like `dict.get()` (no receiverType) are NOT attributed — they
-                // would inflate the count with builtin/unrelated method calls.
-                const selfShare = selfMethodByName.get(name) || 0;
-                const totalOwners = (classOwnersByName.get(name) || new Set()).size || 1;
-
-                let typedHits = 0;
-                for (const cls of ownerClasses) {
-                    const inner = methodByReceiverType.get(cls);
-                    if (inner) typedHits += (inner.get(name) || 0);
+                refined++;
+                const count = exact.filter(caller =>
+                    caller.tier !== 'unverified' &&
+                    (!scopedCallerQuery || scopedPaths.has(caller.file)) &&
+                    !index.files.get(caller.file)?.isBundled &&
+                    (!options.productionCallsOnly ||
+                        !require('./shared').isTestPath(caller.relativePath || caller.file))).length;
+                if (count > 0) {
+                    const owner = symbol.className ||
+                        (symbol.receiver || '').replace(/^\*/, '');
+                    hotList.push({
+                        name: owner ? `${owner}.${name}` : name,
+                        file: symbol.relativePath,
+                        startLine: symbol.startLine,
+                        endLine: symbol.endLine,
+                        callCount: count,
+                        evidence: 'confirmed-callers',
+                    });
+                }
+                hotList.sort((a, b) =>
+                    (b.callCount - a.callCount) ||
+                    codeUnitCompare(a.file, b.file) ||
+                    (a.startLine || 0) - (b.startLine || 0));
+                if (hotList.length >= top) {
+                    const threshold = hotList[top - 1].callCount;
+                    const nextUpper = candidates[candidateIndex + 1]?.upper ?? -1;
+                    if (nextUpper < threshold) break;
                 }
-
-                // Self-method calls: split evenly across owner classes (each class's own
-                // self.method() resolves to itself). When this row covers all owners
-                // (locations cover the only class that has this method), give the full
-                // self-share to this row.
-                const selfShareForRow = selfShare * (ownerClasses.size / totalOwners);
-
-                count = typedHits + Math.round(selfShareForRow);
-                // If we used the self-method heuristic across multiple classes, mark approximate.
-                if (selfShare > 0 && totalOwners > 1) approximate = true;
             }
-            if (count === 0) continue; // skip dead symbols
-
-            if (approximate) usedHeuristicSplit = true;
-            // Sort locations by (file, startLine) for stable display.
-            locations.sort((a, b) =>
-                codeUnitCompare(a.file, b.file) ||
-                (a.startLine || 0) - (b.startLine || 0)
-            );
-            const primary = locations[0];
-            hotList.push({
-                // Use the representative symbol's className for display name
-                // (so "Foo.bar" is preserved when applicable). When defs
-                // disagree on className, just show the bare name.
-                name: representative && representative.className
-                    ? `${representative.className}.${name}`
-                    : name,
-                // Primary location remains for backward-compat with consumers
-                // that read `file`/`startLine`/`endLine` directly.
-                file: primary.file,
-                startLine: primary.startLine,
-                endLine: primary.endLine,
-                callCount: count,
-                ...(approximate && { approximate: true }),
-                ...(locations.length > 1 && { locations }),
-            });
         }
 
         // Stable order: callCount desc, then (relativePath, startLine) asc.
@@ -370,11 +244,13 @@ function getStats(index, options = {}) {
 
         stats.hot = {
             top,
-            total: hotList.length,
+            total: refined === candidates.length ? hotList.length : candidates.length,
+            totalKind: refined === candidates.length ? 'confirmed' : 'raw-call-candidates',
+            refined,
             items: hotList.slice(0, top),
-            ...(usedHeuristicSplit && {
-                note: 'Method-call counts approximated when receiver type was unknown — values within those rows may include unresolved calls split across owner classes.'
-            }),
+            note: refined === candidates.length
+                ? 'Counts are confirmed caller-engine edges pinned to each displayed definition; unverified dispatch is excluded.'
+                : `Displayed counts are exact confirmed caller-engine edges; ${candidates.length} raw candidates were bounded and ${refined} required exact refinement.`,
         };
     }
 
@@ -435,11 +311,10 @@ function getToc(index, options = {}) {
         if (options.in) {
             if (!index.matchesFilters(fileEntry.relativePath, { in: options.in })) continue;
         }
-        let functions = fileEntry.symbols.filter(s =>
-            s.type === 'function' || s.type === 'method' || s.type === 'static' ||
-            s.type === 'constructor' || s.type === 'public' || s.type === 'abstract' ||
-            s.type === 'classmethod'
-        );
+        // Every callable kind, incl. accessors/properties/indexers — a
+        // hand-rolled subset here silently dropped C# `this[]` (kind
+        // 'property') and Python accessor kinds from the detailed listing.
+        let functions = fileEntry.symbols.filter(s => CALLABLE_SYMBOL_KINDS.has(s.type));
         const classes = fileEntry.symbols.filter(s =>
             ['class', 'interface', 'type', 'enum', 'struct', 'trait', 'impl', 'record', 'namespace'].includes(s.type)
         );
@@ -521,7 +396,10 @@ function getToc(index, options = {}) {
 
     return {
         meta: {
-            complete: totalDynamic === 0,
+            // `complete` describes this returned list, while the narrower
+            // dynamic-import fact has an unambiguous name of its own.
+            complete: hiddenFiles === 0 && totalDynamic === 0,
+            noDynamicImports: totalDynamic === 0,
             skipped: 0,
             dynamicImports: totalDynamic,
             uncertain: 0,
@@ -561,11 +439,19 @@ function getToc(index, options = {}) {
  * @param {object} options - { deep, sampleSize, in, file }
  */
 function doctor(index, options = {}) {
-    const inFilter = options.in || options.file || null;
-    const matchInFilter = (rel) => {
-        if (!inFilter) return true;
-        return rel.includes(inFilter);
-    };
+    const projectLanguage = index._getPredominantLanguage();
+    const staticSpecialImports = projectLanguage &&
+        !langTraits(projectLanguage)?.hasDynamicImports;
+    const importBlindspotLabel = staticSpecialImports
+        ? (projectLanguage === 'rust' ? 'glob import(s)' : 'blank/dot import(s)')
+        : 'dynamic import(s)';
+    const normalizedExclude = Array.isArray(options.exclude)
+        ? options.exclude.filter(Boolean)
+        : (options.exclude
+            ? String(options.exclude).split(',').map(s => s.trim()).filter(Boolean)
+            : []);
+    const hasFilter = !!(options.in || options.file || normalizedExclude.length > 0);
+    const matchInFilter = (rel) => matchesReportingScope(index, rel, options);
 
     const fileCounts = { total: 0, scanned: 0 };
     const langs = {};
@@ -580,8 +466,13 @@ function doctor(index, options = {}) {
         dynamicImports: { count: 0, fileCount: 0, files: [] },
         evalCalls:      { count: 0, fileCount: 0, files: [] },
         reflection:     { count: 0, fileCount: 0, files: [] },
+        computedDispatch:{ count: 0, fileCount: 0, files: [] },
         parseFailures:  { count: 0, fileCount: 0, files: [] },
         parseRecoveries:{ count: 0, fileCount: 0, files: [] },
+        unsupportedSources: {
+            count: 0, fileCount: 0, files: [], languages: {}, extensions: {},
+        },
+        skippedSources: { count: 0, fileCount: 0, files: [], reasons: {} },
     };
 
     // Reflection/eval signals come from the shared text-blind-spot counter
@@ -589,6 +480,7 @@ function doctor(index, options = {}) {
     // footer, so the two never drift (field-report #2). Occurrence counts.
     const { hasTextBlindspots, countTextBlindspots } = require('./shared');
 
+    const computedDispatch = projectComputedDispatch(index);
     for (const [filePath, fe] of index.files) {
         fileCounts.total++;
         const rel = fe.relativePath || filePath;
@@ -610,6 +502,10 @@ function doctor(index, options = {}) {
         };
 
         if (fe.dynamicImports && fe.dynamicImports > 0) recordBlind(blindSpots.dynamicImports, fe.dynamicImports);
+        if (computedDispatch.has(filePath)) {
+            recordBlind(blindSpots.computedDispatch,
+                computedDispatch.get(filePath).length);
+        }
         if (fe.parseError) recordBlind(blindSpots.parseFailures, 1);
         if (fe.parseRecovery) recordBlind(blindSpots.parseRecoveries, 1);
 
@@ -640,6 +536,35 @@ function doctor(index, options = {}) {
         recordedParseFailureFiles.add(rel);
     }
 
+    // Project-wide discovery also records common source languages for which
+    // UCN has no parser. These are not parse failures: they are an explicit
+    // engine boundary and a required grep/ripgrep handoff.
+    for (const skipped of index.unsupportedFiles || []) {
+        const rel = skipped.relativePath;
+        if (!matchInFilter(rel)) continue;
+        const unsupported = blindSpots.unsupportedSources;
+        unsupported.count++;
+        unsupported.fileCount++;
+        unsupported.languages[skipped.language] =
+            (unsupported.languages[skipped.language] || 0) + 1;
+        unsupported.extensions[skipped.extension] =
+            (unsupported.extensions[skipped.extension] || 0) + 1;
+        if (unsupported.files.length < BLINDSPOT_FILE_CAP) unsupported.files.push(rel);
+    }
+    fileCounts.unsupported = blindSpots.unsupportedSources.fileCount;
+
+    for (const issue of index.discoveryIssues || []) {
+        const rel = issue.relativePath || '.';
+        if (!matchInFilter(rel)) continue;
+        const skipped = blindSpots.skippedSources;
+        skipped.count++;
+        skipped.fileCount++;
+        skipped.reasons[issue.reason || 'unknown'] =
+            (skipped.reasons[issue.reason || 'unknown'] || 0) + 1;
+        if (skipped.files.length < BLINDSPOT_FILE_CAP) skipped.files.push(rel);
+    }
+    fileCounts.skipped = blindSpots.skippedSources.fileCount;
+
     // Evidence profile — sampled only in deep mode. This is deliberately NOT
     // called "accuracy" or "coverage": it describes how UCN classified edges
     // it found. Compiler/LSP oracle evaluation is the accuracy measurement.
@@ -663,47 +588,80 @@ function doctor(index, options = {}) {
     if (blindSpots.parseRecoveries.count > 0) blindSignals.push(`${blindSpots.parseRecoveries.count} parse-recovery file(s)`);
     if (blindSpots.evalCalls.count > 0) blindSignals.push(`${blindSpots.evalCalls.count} eval/exec use(s) in ${blindSpots.evalCalls.fileCount} file(s)`);
     if (blindSpots.reflection.count > 0) blindSignals.push(`${blindSpots.reflection.count} reflection use(s) in ${blindSpots.reflection.fileCount} file(s)`);
-    if (blindSpots.dynamicImports.count > 0) blindSignals.push(`${blindSpots.dynamicImports.count} dynamic import(s) in ${blindSpots.dynamicImports.fileCount} file(s)`);
+    if (blindSpots.computedDispatch.count > 0) {
+        blindSignals.push(`${blindSpots.computedDispatch.count} computed dispatch call(s) in ${blindSpots.computedDispatch.fileCount} file(s)`);
+    }
+    if (blindSpots.dynamicImports.count > 0) blindSignals.push(`${blindSpots.dynamicImports.count} ${importBlindspotLabel} in ${blindSpots.dynamicImports.fileCount} file(s)`);
+    if (blindSpots.unsupportedSources.count > 0) {
+        const mix = Object.entries(blindSpots.unsupportedSources.languages)
+            .map(([language, count]) => `${language} ${count}`)
+            .join(', ');
+        blindSignals.push(`${blindSpots.unsupportedSources.count} unsupported source file(s): ${mix}`);
+    }
+    if (blindSpots.skippedSources.count > 0) {
+        const reasons = Object.entries(blindSpots.skippedSources.reasons)
+            .map(([reason, count]) => `${reason} ${count}`).join(', ');
+        blindSignals.push(`${blindSpots.skippedSources.count} source discovery gap(s): ${reasons}`);
+    }
 
     // Trust is task-specific. A healthy index can be excellent for navigation
     // while still requiring review before a breaking refactor or deletion.
     // Never infer semantic accuracy from rule-assigned confidence decimals.
-    const indexLevel = fileCounts.scanned === 0 ? 'UNKNOWN'
-        : blindSpots.parseFailures.count > 0 || blindSpots.parseRecoveries.count > 0 ||
-            cache.fresh === false ? 'MEDIUM' : 'HIGH';
-    const indexReason = fileCounts.scanned === 0 ? 'empty scope'
+    const unsupportedCount = blindSpots.unsupportedSources.count;
+    const incompleteIndex = blindSpots.parseFailures.count > 0 ||
+        blindSpots.parseRecoveries.count > 0 || cache.fresh === false ||
+        !!index.truncated || unsupportedCount > 0 || blindSpots.skippedSources.count > 0;
+    const indexLevel = fileCounts.scanned === 0 && unsupportedCount > 0 ? 'UNSUPPORTED'
+        : fileCounts.scanned === 0 ? 'UNKNOWN'
+            : incompleteIndex ? 'PARTIAL' : 'HIGH';
+    const indexReason = fileCounts.scanned === 0 && unsupportedCount > 0
+        ? `0 supported files indexed; ${unsupportedCount} unsupported source file(s) require grep/ripgrep`
+        : fileCounts.scanned === 0 ? 'empty scope'
         : blindSpots.parseFailures.count > 0
             ? `${blindSpots.parseFailures.count} file(s) failed to parse`
             : blindSpots.parseRecoveries.count > 0
                 ? `${blindSpots.parseRecoveries.count} file(s) required parser recovery; indexed results may be partial`
-                : cache.fresh === false ? 'index cache is stale' : 'fresh index; no parse failures';
+                : cache.fresh === false ? 'index cache is stale'
+                    : index.truncated ? `file discovery stopped at maxFiles=${index.truncated.maxFiles}`
+                        : blindSpots.skippedSources.count > 0
+                            ? `${blindSpots.skippedSources.count} source path(s) were not indexed; inspect discovery reasons`
+                        : unsupportedCount > 0
+                            ? `${fileCounts.scanned} supported file(s) indexed; ${unsupportedCount} unsupported source file(s) require grep/ripgrep`
+                            : 'fresh index; no parse failures';
 
     let evidenceLevel = 'UNKNOWN';
     let evidenceReason = 'not sampled; run --deep for a stratified evidence profile';
     if (evidenceProfile) {
         if (evidenceProfile.total === 0) {
+            evidenceLevel = 'NONE';
             evidenceReason = 'sample contained no caller edges';
         } else {
             const confirmedShare = evidenceProfile.confirmed / evidenceProfile.total;
-            evidenceLevel = !evidenceProfile.adequate ? 'UNKNOWN'
-                : confirmedShare >= 0.85 ? 'HIGH'
-                    : confirmedShare >= 0.55 ? 'MEDIUM' : 'LOW';
+            // Confirmed share is a classification mix, not accuracy and not a
+            // readiness score. A conservative engine can be excellent while
+            // intentionally routing many edges to visible unverified bands.
+            evidenceLevel = evidenceProfile.adequate ? 'PROFILED' : 'LIMITED';
             evidenceReason = `${(confirmedShare * 100).toFixed(1)}% confirmed-evidence edges across ${evidenceProfile.sampled} pinned definitions`;
             if (!evidenceProfile.adequate) evidenceReason += '; sample too small for a readiness decision';
         }
     }
 
-    const dynamicCount = blindSpots.evalCalls.count + blindSpots.reflection.count + blindSpots.dynamicImports.count;
+    const dynamicCount = blindSpots.evalCalls.count + blindSpots.reflection.count +
+        blindSpots.dynamicImports.count + blindSpots.computedDispatch.count;
     const semanticLevel = blindSpots.parseFailures.count > 0 || blindSpots.parseRecoveries.count > 0 ? 'LOW'
-        : dynamicCount > 0 ? 'MEDIUM' : 'UNKNOWN';
+        : unsupportedCount > 0 ? 'PARTIAL'
+            : dynamicCount > 0 ? 'REVIEW' : 'UNKNOWN';
     const semanticReason = blindSignals.length
         ? `semantic recall may miss runtime-resolved edges: ${blindSignals.join(', ')}`
         : 'no known runtime blind spots detected; alias/dynamic completeness is not compiler-verified locally';
 
     const navigationLevel = indexLevel;
-    const refactorLevel = indexLevel === 'UNKNOWN' || evidenceLevel === 'UNKNOWN' ? 'UNKNOWN'
-        : indexLevel === 'HIGH' && evidenceLevel === 'HIGH' && semanticLevel === 'UNKNOWN' ? 'MEDIUM'
-            : indexLevel === 'LOW' || evidenceLevel === 'LOW' || semanticLevel === 'LOW' ? 'LOW' : 'MEDIUM';
+    const hardIndexRisk = blindSpots.parseFailures.count > 0 ||
+        blindSpots.parseRecoveries.count > 0 || cache.fresh === false || !!index.truncated;
+    const refactorLevel = indexLevel === 'UNKNOWN' ? 'UNKNOWN'
+        : indexLevel === 'UNSUPPORTED' ? 'UNSUPPORTED'
+            : hardIndexRisk ? 'LOW'
+                : unsupportedCount > 0 ? 'PARTIAL' : 'REVIEW';
     const deletionLevel = refactorLevel === 'LOW' ? 'LOW' : 'REVIEW';
     const dimensions = {
         index: { level: indexLevel, reason: indexReason },
@@ -712,36 +670,46 @@ function doctor(index, options = {}) {
         navigation: { level: navigationLevel, reason: indexReason },
         refactor: {
             level: refactorLevel,
-            reason: refactorLevel === 'UNKNOWN'
-                ? 'run --deep; review unverified and non-call occurrences before changing code'
-                : 'text-ground accounting is available; aliases, reflection, and unverified edges still require review',
+            reason: indexLevel === 'UNKNOWN'
+                ? 'no supported source scope was indexed'
+                : indexLevel === 'UNSUPPORTED'
+                    ? 'UCN cannot analyze this source scope; use grep/ripgrep and a language-native tool'
+                    : unsupportedCount > 0
+                        ? 'supported files are analyzable, but skipped language files require grep/ripgrep before cross-language changes'
+                        : 'text-ground accounting is available; aliases, reflection, and unverified edges still require review',
         },
         deletion: {
             level: deletionLevel,
             reason: 'deletion additionally requires usages/deadcode review and tests; caller accounting alone is insufficient',
         },
     };
-    const trust = refactorLevel;
-    const trustReason = dimensions.refactor.reason;
+    // `repo` is an orientation/navigation command. Its headline must answer
+    // that task, while refactor/deletion remain separately visible dimensions.
+    const trust = navigationLevel;
+    const trustReason = dimensions.navigation.reason;
 
     return {
         root: index.root,
+        projectLanguage,
         version: require('../package.json').version,  // running ucn version — surfaces MCP/CLI drift (field-report #3)
         files: fileCounts,
         symbols: totalSymbols,
         languages: langs,
         blindSpots,
         evidenceProfile,
-        // Backward-compatible field name. `kind` prevents consumers from
-        // mistaking this for semantic coverage or measured accuracy.
-        coverage: evidenceProfile,
         cache,
         commandTrust: summarizeCommandTrust(),
         trust,
         trustReason,
-        trustScope: 'refactor-readiness',
+        trustScope: 'navigation-readiness',
         dimensions,
-        ...(inFilter && { filter: inFilter }),
+        ...(hasFilter && {
+            filter: {
+                ...(options.file && { file: options.file }),
+                ...(options.in && { in: options.in }),
+                ...(normalizedExclude.length > 0 && { exclude: normalizedExclude }),
+            },
+        }),
     };
 }
 
@@ -807,6 +775,9 @@ function computeEvidenceProfile(index, { sampleSize, matchInFilter }) {
         const allEdges = [...callers, ...(callers.unverifiedEntries || [])];
         const seenSites = new Set();
         for (const c of allEdges) {
+            const rel = c.relativePath ||
+                (c.file && path.isAbsolute(c.file) ? path.relative(index.root, c.file) : c.file);
+            if (!matchInFilter(rel)) continue;
             const site = `${c.file || c.relativePath}:${c.line}:${c.tier || c.reason || ''}`;
             if (seenSites.has(site)) continue;
             seenSites.add(site);
@@ -836,16 +807,34 @@ function computeEvidenceProfile(index, { sampleSize, matchInFilter }) {
  */
 function orient(index, options = {}) {
     const top = options.top || 8;
-    // Fetch a deeper hot list so production functions survive the filter
-    // below even when test helpers dominate raw call counts.
-    const stats = getStats(index, { hot: true, top: Math.min(top * 5, 200) });
-    const health = doctor(index, {});
+    const scope = {
+        file: options.file,
+        in: options.in,
+        exclude: options.exclude,
+    };
+    const { isTestPath } = require('./shared');
+    const hasProductionFiles = [...index.files.values()].some(fileEntry => {
+        const relativePath = fileEntry.relativePath;
+        return relativePath &&
+            matchesReportingScope(index, relativePath, scope) &&
+            !isTestPath(relativePath);
+    });
+    const stats = getStats(index, {
+        ...scope,
+        hot: true,
+        top,
+        // A production-only call count is useful only when the selected scope
+        // actually contains production files. In an all-test repository it
+        // would erase the raw ranking that orient promises as its fallback.
+        productionCallsOnly: options.includeTests !== true && hasProductionFiles,
+    });
+    const health = doctor(index, scope);
 
     // Densest directories (leaf dirname rollup — "where does the code live")
     const dirMap = new Map();
     for (const [, fe] of index.files) {
         const rp = fe.relativePath;
-        if (!rp) continue;
+        if (!rp || !matchesReportingScope(index, rp, scope)) continue;
         const slash = rp.lastIndexOf('/');
         const dir = slash === -1 ? '.' : rp.slice(0, slash);
         const e = dirMap.get(dir) || { dir, files: 0, symbols: 0 };
@@ -861,7 +850,24 @@ function orient(index, options = {}) {
     let entrypoints = null;
     try {
         const { detectEntrypoints } = require('./entrypoints');
-        const eps = detectEntrypoints(index, {});
+        const { addTestExclusions } = require('./shared');
+        const orientExclude = Array.isArray(options.exclude)
+            ? options.exclude
+            : (options.exclude
+                ? String(options.exclude).split(',').map(s => s.trim()).filter(Boolean)
+                : []);
+        // Same default as the entrypoints command: the orientation count
+        // describes the project's own entry surface, not test fixtures.
+        const detected = detectEntrypoints(index, {
+            file: options.file,
+            exclude: options.includeTests === true
+                ? orientExclude
+                : addTestExclusions(orientExclude),
+        });
+        const eps = Array.isArray(detected)
+            ? detected.filter(entry => matchesReportingScope(
+                index, entry.relativePath || entry.file, scope))
+            : detected;
         if (Array.isArray(eps)) {
             const byType = new Map();
             for (const e of eps) byType.set(e.type, (byType.get(e.type) || 0) + 1);
@@ -877,7 +883,6 @@ function orient(index, options = {}) {
     // Orientation wants the ENGINE's hot functions, not fixture helpers —
     // prefer production-path entries (labeled as such by the formatter);
     // an all-test project falls back to the raw ranking.
-    const { isTestPath } = require('./shared');
     const allHot = (stats.hot?.items || []).map(i => ({
         name: i.name,
         file: i.file,
@@ -892,22 +897,39 @@ function orient(index, options = {}) {
 
     return {
         root: stats.root,
+        ...(options.in && { scope: options.in }),
+        ...(options.file && !options.in && { scope: options.file }),
         files: stats.files,
         symbols: stats.symbols,
         buildTime: stats.buildTime,
         byLanguage: stats.byLanguage,
         dirs,
-        hot: { total: stats.hot?.total ?? 0, top, production, items: hotItems },
+        hot: {
+            total: stats.hot?.total ?? 0,
+            totalKind: stats.hot?.totalKind || 'confirmed',
+            refined: stats.hot?.refined ?? 0,
+            top,
+            production,
+            items: hotItems,
+        },
         entrypoints,
         trust: {
             level: health.trust,
+            projectLanguage: health.projectLanguage,
             blindSpots: {
                 dynamicImports: health.blindSpots?.dynamicImports?.count ?? 0,
                 evalCalls: health.blindSpots?.evalCalls?.count ?? 0,
                 reflection: health.blindSpots?.reflection?.count ?? 0,
+                computedDispatch: health.blindSpots?.computedDispatch?.count ?? 0,
                 parseFailures: health.blindSpots?.parseFailures?.count ?? 0,
+                parseRecoveries: health.blindSpots?.parseRecoveries?.count ?? 0,
+                unsupportedSources: health.blindSpots?.unsupportedSources?.count ?? 0,
+                skippedSources: health.blindSpots?.skippedSources?.count ?? 0,
             },
         },
+        unsupportedSources: health.blindSpots?.unsupportedSources ?? null,
+        skippedSources: health.blindSpots?.skippedSources ?? null,
+        projectLanguage: health.projectLanguage,
         suggest: hottestProd ? hottestProd.name : null,
     };
 }