ucn 4.0.1 → 4.1.0

package/core/output/shared.js

@@ -9,13 +9,17 @@ const fs = require('fs');
 const { langTraits } = require('../../languages');
 
 /**
- * Format dynamic imports note with language-appropriate terminology.
- * Go doesn't have "dynamic imports" — uses "blank/dot imports" instead.
+ * Format dynamic imports note with language-appropriate terminology:
+ * Go marks blank/dot imports, Rust marks glob imports (use foo::*) — both
+ * are name-resolution blind spots, neither is a "dynamic import".
  */
 function dynamicImportsNote(count, meta) {
     if (!count) return null;
-    if (meta?.projectLanguage && !langTraits(meta.projectLanguage)?.hasDynamicImports) {
-        return `${count} blank/dot import(s)`;
+    const lang = meta?.projectLanguage;
+    if (lang && !langTraits(lang)?.hasDynamicImports) {
+        return lang === 'rust'
+            ? `${count} glob import(s)`
+            : `${count} blank/dot import(s)`;
     }
     return `${count} dynamic import(s)`;
 }
@@ -85,6 +89,11 @@ function formatFunctionSignature(fn) {
         prefix.push(fn.modifiers.join(' '));
     }
 
+    // Methods carry isAsync without an 'async' modifier entry (fix #252:
+    // `pub async fn get` and TS async methods rendered without the
+    // qualifier while standalone functions kept it).
+    if (fn.isAsync && !(fn.modifiers || []).includes('async')) prefix.push('async');
+
     // Generator marker
     if (fn.isGenerator) prefix.push('*');
 
@@ -336,7 +345,25 @@ function unverifiedReasonLabel(entry) {
     return entry.reason;
 }
 
+// Advisory label line for heuristic commands (v4 two-tier surface: contracted
+// commands carry accounts; advisory commands say so explicitly, in text AND
+// via the result's `advisory` field for JSON consumers).
+const ADVISORY_LABELS = {
+    'similarity-heuristics': 'ranked by similarity heuristics (same file, shared callers/callees, name overlap)',
+    'scored-selection': 'examples picked by usage-quality scoring',
+    'best-effort-frame-matching': 'frames matched by path similarity',
+    'heuristic-route-matching': 'route↔request matches are heuristic (see per-match EXACT/PARTIAL/UNCERTAIN tiers)',
+};
+
+/** Render the advisory line for a result's `advisory` field, or null. */
+function advisoryLine(advisory) {
+    if (!advisory) return null;
+    const desc = ADVISORY_LABELS[advisory] || advisory;
+    return `Advisory: ${desc} — suggestions, not verified claims.`;
+}
+
 module.exports = {
+    advisoryLine,
     dynamicImportsNote,
     formatFileError,
     unverifiedReasonLabel,

package/core/output/tracing.js

@@ -9,6 +9,7 @@
  */
 
 const { unverifiedReasonLabel } = require('./shared');
+const { codeUnitCompare } = require('../shared');
 const { formatAccountLines } = require('./analysis');
 
 /**
@@ -56,10 +57,10 @@ function renderUnverifiedCallees(lines, node, prefix, isParentLast) {
 function treeAccountLine(ta) {
     if (!ta) return null;
     const reasons = Object.entries(ta.unverifiedByReason || {})
-        .sort((a, b) => a[0].localeCompare(b[0]))
+        .sort((a, b) => codeUnitCompare(a[0], b[0]))
         .map(([r, n]) => `${n} ${r}`).join(', ');
     const excludedReasons = Object.entries(ta.excludedByReason || {})
-        .sort((a, b) => a[0].localeCompare(b[0]))
+        .sort((a, b) => codeUnitCompare(a[0], b[0]))
         .map(([r, n]) => `${n} ${r}`).join(', ');
     let line = `TREE ACCOUNT: ${ta.nodesExpanded} node${ta.nodesExpanded === 1 ? '' : 's'} expanded · ` +
         `${ta.confirmedEdges} confirmed edge${ta.confirmedEdges === 1 ? '' : 's'} · ` +
@@ -75,7 +76,7 @@ function calleeAccountLine(ta) {
     if (!ta || !ta.callSites) return null;
     const cs = ta.callSites;
     const reasons = Object.entries(ta.unverifiedByReason || {})
-        .sort((a, b) => a[0].localeCompare(b[0]))
+        .sort((a, b) => codeUnitCompare(a[0], b[0]))
         .map(([r, n]) => `${n} ${r}`).join(', ');
     let line = `CALLEE ACCOUNT: ${ta.nodesExpanded} node${ta.nodesExpanded === 1 ? '' : 's'} expanded · ` +
         `${cs.total} call site${cs.total === 1 ? '' : 's'} = ${cs.confirmed} confirmed + ` +
@@ -207,8 +208,11 @@ function formatTrace(trace, options = {}) {
         lines.push(`\nSome results truncated. ${allHint}`);
     }
 
-    if (trace.includeMethods === false) {
-        const methodsHint = options.methodsHint || 'Note: obj.method() calls excluded — use --include-methods to include them';
+    // Only claim filtering when the account actually filtered edges — the
+    // flag is a no-op for languages where method callees are always analyzed.
+    const traceFiltered = (trace.treeAccount?.callSites?.filtered ?? trace.treeAccount?.filteredEdges ?? 0);
+    if (trace.includeMethods === false && traceFiltered > 0) {
+        const methodsHint = options.methodsHint || `Note: ${traceFiltered} obj.method() callee edge(s) hidden (counted as filtered in the account). Use --include-methods to show them.`;
         lines.push(`\n${methodsHint}`);
     }
 
@@ -339,8 +343,9 @@ function formatBlast(blast, options = {}) {
         lines.push(`\nSome results truncated. ${allHint}`);
     }
 
-    if (blast.includeMethods === false) {
-        lines.push('\nNote: obj.method() calls excluded. Use --include-methods to include them.');
+    const blastFiltered = (blast.treeAccount?.filteredEdges ?? 0);
+    if (blast.includeMethods === false && blastFiltered > 0) {
+        lines.push(`\nNote: ${blastFiltered} obj.method() caller edge(s) hidden (counted as filtered in the account). Use --include-methods to show them.`);
     }
 
     return lines.join('\n');
@@ -459,9 +464,14 @@ function formatReverseTrace(result, options = {}) {
     if (result.summary) {
         lines.push('');
         const { totalEntryPoints, totalFunctions, unverifiedEdges } = result.summary;
+        // totalFunctions counts every traversed node incl. the entry points
+        // themselves — "intermediate" excludes them (fix #237: '4 entry
+        // points reach X through 6 intermediate functions' counted the 4
+        // entry points among the 6).
+        const intermediates = Math.max(0, totalFunctions - (totalEntryPoints || 0));
         let s;
         if (totalFunctions > 0) {
-            s = `Summary: ${totalEntryPoints} entry point${totalEntryPoints !== 1 ? 's' : ''} reach${totalEntryPoints === 1 ? 'es' : ''} ${result.root} through ${totalFunctions} intermediate function${totalFunctions !== 1 ? 's' : ''}`;
+            s = `Summary: ${totalEntryPoints} entry point${totalEntryPoints !== 1 ? 's' : ''} reach${totalEntryPoints === 1 ? 'es' : ''} ${result.root}${intermediates > 0 ? ` through ${intermediates} intermediate function${intermediates !== 1 ? 's' : ''}` : ' directly'}`;
         } else if (unverifiedEdges > 0) {
             s = `Summary: no confirmed callers — ${unverifiedEdges} unverified edge${unverifiedEdges !== 1 ? 's' : ''} (not an entry-point claim)`;
         } else {
@@ -487,8 +497,9 @@ function formatReverseTrace(result, options = {}) {
         lines.push(`\nSome results truncated. ${allHint}`);
     }
 
-    if (result.includeMethods === false) {
-        lines.push('\nNote: obj.method() calls excluded. Use --include-methods to include them.');
+    const rtFiltered = (result.treeAccount?.filteredEdges ?? 0);
+    if (result.includeMethods === false && rtFiltered > 0) {
+        lines.push(`\nNote: ${rtFiltered} obj.method() caller edge(s) hidden (counted as filtered in the account). Use --include-methods to show them.`);
     }
 
     return lines.join('\n');
@@ -516,7 +527,7 @@ function formatAffectedTests(result, options = {}) {
     lines.push(`affected-tests: ${result.root}`);
     lines.push('═'.repeat(60));
     lines.push(`${result.file}:${result.line}`);
-    lines.push(`1 function changed → ${summary.totalAffected} functions affected (depth ${result.depth})`);
+    lines.push(`1 function changed → ${summary.totalAffected} function${summary.totalAffected !== 1 ? 's' : ''} affected (depth ${result.depth})`);
     lines.push('');
 
     if (result.testFiles.length === 0) {

package/core/parser.js

@@ -282,13 +282,15 @@ function getExportedSymbols(result) {
  */
 function cleanHtmlScriptTags(lines, language) {
     if (language === 'html' && lines.length > 0) {
-        // Strip opening <script ...> tag wherever it appears on the first line
-        // (may be preceded by other HTML on the same line, e.g. <p>x</p><script>...).
-        lines[0] = lines[0].replace(/<script\b[^>]*>/i, '');
-        // Strip closing </script> tag wherever it appears on the last line
-        // (may be followed by other HTML on the same line, e.g. ...</script><p>x</p>).
+        // Strip everything up to and including the opening <script ...> tag
+        // on the first line — surrounding same-line markup is not code
+        // (fix #252: `<div><script>function foo()...` leaked `<div>` into
+        // the extraction). Indentation before the tag is kept.
+        lines[0] = lines[0].replace(/^(\s*).*<script\b[^>]*>/i, '$1');
+        // Strip the closing </script> tag and everything after it on the
+        // last line (`...</script></body></html>` leaked trailing markup).
         const last = lines.length - 1;
-        lines[last] = lines[last].replace(/<\/script\s*>/i, '');
+        lines[last] = lines[last].replace(/<\/script\s*>.*$/i, '');
     }
     return lines;
 }

package/core/project.js

@@ -8,12 +8,12 @@
 const fs = require('fs');
 const path = require('path');
 const crypto = require('crypto');
-const { expandGlob, findProjectRoot, detectProjectPattern, isTestFile, parseGitignore, DEFAULT_IGNORES } = require('./discovery');
+const { expandGlob, findProjectRoot, detectProjectPattern, isTestFile, parseGitignore, DEFAULT_IGNORES, compareNames } = require('./discovery');
 const { extractImports, extractExports, resolveImport } = require('./imports');
 const { parse, cleanHtmlScriptTags } = require('./parser');
-const { detectLanguage, getParser, getLanguageModule, safeParse, langTraits } = require('../languages');
+const { detectLanguage, getParser, getLanguageModule, safeParse, langTraits, PARSE_OPTIONS } = require('../languages');
 const { getTokenTypeAtPosition } = require('../languages/utils');
-const { escapeRegExp, NON_CALLABLE_TYPES } = require('./shared');
+const { escapeRegExp, NON_CALLABLE_TYPES, codeUnitCompare } = require('./shared');
 const stacktrace = require('./stacktrace');
 const indexCache = require('./cache');
 const deadcodeModule = require('./deadcode');
@@ -52,6 +52,8 @@ class ProjectIndex {
         this.failedFiles = new Set();    // files that failed to index (e.g. large minified bundles)
         this._opContentCache = null;     // per-operation file content cache (Map<filePath, string>)
         this._opUsagesCache = null;      // per-operation findUsagesInCode cache (Map<"file:name", usages[]>)
+        this._opTreeCache = null;        // per-operation parsed-tree cache (Map<filePath, tree|null>, bounded FIFO)
+        this._opLinesCache = null;       // per-operation split-lines cache (Map<filePath, string[]>, bounded FIFO)
         this.calleeIndex = null;         // name -> Set<filePath> — inverted call index (built lazily)
     }
 
@@ -78,6 +80,8 @@ class ProjectIndex {
             this._opUsagesCache = new Map();
             this._opCallsCountCache = new Map();
             this._opEnclosingFnCache = new Map();
+            this._opTreeCache = new Map();
+            this._opLinesCache = new Map();
             this._opDepth = 0;
         }
         this._opDepth++;
@@ -91,6 +95,8 @@ class ProjectIndex {
             this._opUsagesCache = null;
             this._opCallsCountCache = null;
             this._opEnclosingFnCache = null;
+            this._opTreeCache = null;
+            this._opLinesCache = null;
             // Free cached file content from callsCache entries (retained during
             // operation for _readFile caching, not needed between operations)
             for (const entry of this.callsCache.values()) {
@@ -100,6 +106,50 @@ class ProjectIndex {
         }
     }
 
+    /**
+     * Parse a file once per operation and reuse the tree across symbol names.
+     * Multi-symbol commands (diff-impact, check) classify ground lines for MANY
+     * names against the SAME files; without this, each (file, name) pair costs a
+     * full tree-sitter parse. Bounded FIFO (trees hold native memory).
+     * Returns null when parsing fails or no operation cache is active — callers
+     * fall back to parsing themselves.
+     */
+    _getParsedTree(filePath, content, language) {
+        if (!this._opTreeCache) return null;
+        const cached = this._opTreeCache.get(filePath);
+        if (cached !== undefined) return cached;
+        let tree = null;
+        try {
+            const parser = getParser(language);
+            tree = parser ? safeParse(parser, content, undefined, PARSE_OPTIONS) : null;
+        } catch (e) {
+            tree = null;
+        }
+        if (this._opTreeCache.size >= 512) {
+            this._opTreeCache.delete(this._opTreeCache.keys().next().value);
+        }
+        this._opTreeCache.set(filePath, tree);
+        return tree;
+    }
+
+    /**
+     * Split a file into lines once per operation. Callers must treat the
+     * returned array as read-only — it is shared across the whole operation.
+     */
+    _getFileLines(filePath) {
+        if (this._opLinesCache) {
+            const cached = this._opLinesCache.get(filePath);
+            if (cached !== undefined) return cached;
+            const lines = this._readFile(filePath).split('\n');
+            if (this._opLinesCache.size >= 2048) {
+                this._opLinesCache.delete(this._opLinesCache.keys().next().value);
+            }
+            this._opLinesCache.set(filePath, lines);
+            return lines;
+        }
+        return this._readFile(filePath).split('\n');
+    }
+
     /**
      * Get findUsagesInCode results with per-operation caching.
      * Avoids redundant tree-sitter parsing when the same (file, name) is queried
@@ -132,7 +182,12 @@ class ProjectIndex {
 
             const parser = getParser(lang);
             if (!parser) return null;
-            const usages = langModule.findUsagesInCode(content, name, parser);
+            // Language modules that accept a pre-parsed tree (4th param) reuse
+            // the per-operation tree cache; others (html) parse internally.
+            const tree = langModule.findUsagesInCode.length >= 4
+                ? this._getParsedTree(filePath, content, lang)
+                : null;
+            const usages = langModule.findUsagesInCode(content, name, parser, tree);
             if (this._opUsagesCache) {
                 this._opUsagesCache.set(cacheKey, usages);
             }
@@ -167,6 +222,16 @@ class ProjectIndex {
         const startTime = Date.now();
         const quiet = options.quiet !== false;
 
+        // A (re)build invalidates any cache-loaded reachability set — the
+        // fingerprint guard in computeReachability is content-shaped and
+        // cannot see every rebuild (fix #249: a stale loaded set survived
+        // the rebuild and poisoned "unreachable" notes). Recomputed lazily
+        // on the next reachability query.
+        if (this._reachableSymbols) {
+            this._reachableSymbols = null;
+            this._reachableFingerprint = null;
+        }
+
         // Accept pre-expanded file array (glob mode) or a pattern string
         let files;
         if (Array.isArray(pattern)) {
@@ -204,6 +269,18 @@ class ProjectIndex {
             console.error(`Indexing ${files.length} files in ${this.root}...`);
         }
 
+        // Materialize a lazily-prepared calls cache BEFORE any indexing: the
+        // stale-file path (indexFile → removeFileSymbols) and the deleted-file
+        // cleanup below both delete callsCache entries, but with shards still
+        // unloaded those deletes are no-ops on an empty map — and the later
+        // ensureCallsCacheLoaded() (buildCalleeIndex) RESURRECTED the stale
+        // entries, so queries in this process ran against the pre-edit call
+        // records (fix #227). Cost-neutral: buildCalleeIndex loads all shards
+        // at the end of build() anyway.
+        if (this._callsCachePrepared && !this._callsCacheLoaded) {
+            indexCache.ensureCallsCacheLoaded(this);
+        }
+
         let deletedInRebuild = 0;
         if (options.forceRebuild) {
             // Incremental rebuild: only remove files that no longer exist on disk.
@@ -271,6 +348,11 @@ class ProjectIndex {
             }
         }
 
+        // Canonical order BEFORE derived indexes, so graphs / dir index /
+        // callee index inherit it. This is what makes incremental rebuilds
+        // byte-equivalent to fresh builds (see _canonicalizeOrder).
+        this._canonicalizeOrder();
+
         // Skip graph rebuild when incremental rebuild found no changes
         if (changed > 0 || deletedInRebuild > 0 || !options.forceRebuild) {
             this.buildImportGraph();
@@ -284,6 +366,11 @@ class ProjectIndex {
         // avoiding the 2+ minute deferred cost when the first analysis command runs later.
         this.buildCalleeIndex();
 
+        // buildCalleeIndex re-parses changed files via getCachedCalls, which
+        // appends their entries at the callsCache TAIL — restore canonical
+        // key order so iteration-order consumers match a fresh build.
+        this.callsCache = new Map([...this.callsCache.entries()].sort((a, b) => compareNames(a[0], b[0])));
+
         this.buildTime = Date.now() - startTime;
 
         if (!quiet) {
@@ -356,6 +443,11 @@ class ProjectIndex {
         }
         // Handle last line (no trailing newline)
         if (content.length - lineStart > 1000) longLineCount++;
+        // A trailing newline TERMINATES the last line rather than opening a
+        // new one (fix #251: stats reported wc -l + 1 for newline-terminated
+        // files); an empty file has 0 lines.
+        if (content.length === 0) lineCount = 0;
+        else if (content.charCodeAt(content.length - 1) === 10) lineCount--;
 
         const isBundled = (() => {
             // Webpack bundles contain __webpack_require__ or __webpack_modules__
@@ -528,6 +620,64 @@ class ProjectIndex {
         this._endpointsCache = null;
     }
 
+    /**
+     * Put every order-bearing index structure into ONE canonical order, so the
+     * same repository content produces the same index state — and therefore
+     * byte-identical command output — no matter how the state was reached
+     * (fresh build, cache load, incremental rebuild, parallel build).
+     *
+     * Without this, three paths diverge: build fills fileEntry.symbols/bindings
+     * in parse-emission order while loadCache rebuilds them from the name map
+     * (name-grouped order); an incremental rebuild re-appends a changed file's
+     * defs at the TAIL of each symbols.get(name) array; and calleeIndex sets
+     * grow by tail-append. First-match resolution and account sampling then
+     * give different answers on consecutive runs over identical content.
+     *
+     * Canonical orders: files/callsCache by path (discovery's compareNames, so
+     * a fresh sequential build is already canonical); per-file symbols/bindings
+     * by (startLine, type, className, name); symbols map by name with defs
+     * sorted by (relativePath, startLine, type, className, endLine); calleeIndex
+     * by name with file sets in path order.
+     */
+    _canonicalizeOrder() {
+        // Plain code-unit comparison — canonical order must not depend on the
+        // host ICU locale (localeCompare does).
+        const cmpStr = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+
+        this.files = new Map([...this.files.entries()].sort((a, b) => compareNames(a[0], b[0])));
+
+        const feCmp = (a, b) => (a.startLine - b.startLine)
+            || cmpStr(String(a.type), String(b.type))
+            || cmpStr(String(a.className || ''), String(b.className || ''))
+            || cmpStr(String(a.name), String(b.name));
+        for (const fe of this.files.values()) {
+            if (Array.isArray(fe.symbols)) fe.symbols.sort(feCmp);
+            if (Array.isArray(fe.bindings)) fe.bindings.sort(feCmp);
+        }
+
+        const defCmp = (a, b) => compareNames(a.relativePath || '', b.relativePath || '')
+            || (a.startLine - b.startLine)
+            || cmpStr(String(a.type), String(b.type))
+            || cmpStr(String(a.className || ''), String(b.className || ''))
+            || ((a.endLine || 0) - (b.endLine || 0));
+        const sortedNames = [...this.symbols.keys()].sort();
+        const canonicalSymbols = new Map();
+        for (const name of sortedNames) {
+            canonicalSymbols.set(name, this.symbols.get(name).sort(defCmp));
+        }
+        this.symbols = canonicalSymbols;
+
+        this.callsCache = new Map([...this.callsCache.entries()].sort((a, b) => compareNames(a[0], b[0])));
+
+        if (this.calleeIndex) {
+            const rebuilt = new Map();
+            for (const name of [...this.calleeIndex.keys()].sort()) {
+                rebuilt.set(name, new Set([...this.calleeIndex.get(name)].sort(compareNames)));
+            }
+            this.calleeIndex = rebuilt;
+        }
+    }
+
     /**
      * Build directory→files index for O(1) same-package lookups.
      * Replaces O(N) full-index scans in findCallers and countSymbolUsages.
@@ -965,9 +1115,16 @@ class ProjectIndex {
             const extra = others.length - shown.length;
             const alsoIn = shown.map(d => `${d.relativePath}:${d.startLine}`).join(', ');
             const suffix = extra > 0 ? `, and ${extra} more` : '';
+            // file= can only disambiguate when the alternatives live in other
+            // files (fix #246: same-file collisions — a standalone fn and a
+            // same-name method — need a line or class pin instead).
+            const allSameFile = others.every(d => d.relativePath === def.relativePath);
+            const hint = allSameFile
+                ? 'Use line= or class_name= to disambiguate.'
+                : 'Use file= to disambiguate.';
             warnings.push({
                 type: 'ambiguous',
-                message: `Found ${definitions.length} definitions for "${name}". Using ${def.relativePath}:${def.startLine}. Also in: ${alsoIn}${suffix}. Use file= to disambiguate.`,
+                message: `Found ${definitions.length} definitions for "${name}". Using ${def.relativePath}:${def.startLine}. Also in: ${alsoIn}${suffix}. ${hint}`,
                 alternatives: others.map(d => ({
                     file: d.relativePath,
                     line: d.startLine
@@ -1258,7 +1415,7 @@ class ProjectIndex {
 
         // Sort by file then line
         methods.sort((a, b) => {
-            if (a.relativePath !== b.relativePath) return a.relativePath.localeCompare(b.relativePath);
+            if (a.relativePath !== b.relativePath) return codeUnitCompare(a.relativePath, b.relativePath);
             return a.startLine - b.startLine;
         });
 
@@ -1411,7 +1568,10 @@ class ProjectIndex {
             // Prefer typed rendering when paramTypes/paramsStructured carry annotations
             const { renderTypedParams } = require('./output/shared');
             const typed = renderTypedParams(def);
-            parts.push(`(${typed != null ? typed : def.params})`);
+            // Zero-param functions render `()` — some parsers store the '...'
+            // placeholder for EMPTY lists, which reads as unknown/variadic.
+            const noParams = Array.isArray(def.paramsStructured) && def.paramsStructured.length === 0;
+            parts.push(`(${typed != null ? typed : (noParams ? '' : def.params)})`);
         }
         if (def.returnType) {
             parts.push(`: ${String(def.returnType).replace(/\s+/g, ' ').trim()}`);

package/core/registry.js

@@ -25,7 +25,7 @@ const CANONICAL_COMMANDS = [
     // Refactoring
     'verify', 'plan', 'diffImpact', 'check',
     // Other
-    'typedef', 'stacktrace', 'api', 'stats', 'doctor', 'auditAsync',
+    'typedef', 'stacktrace', 'api', 'stats', 'doctor', 'auditAsync', 'orient',
 ];
 
 // ============================================================================
@@ -107,40 +107,40 @@ const PARAM_MAP = {
 // file* = file is the command subject (required), not a filter pattern.
 const FLAG_APPLICABILITY = {
     // Understanding code
-    about:        ['name', 'file', 'exclude', 'className', 'includeMethods', 'includeUncertain', 'includeTests', 'top', 'all', 'withTypes', 'minConfidence', 'showConfidence', 'unreachableOnly', 'compact', 'git'],
+    about:        ['name', 'file', 'exclude', 'className', 'line', 'includeMethods', 'includeUncertain', 'includeTests', 'top', 'all', 'withTypes', 'minConfidence', 'showConfidence', 'unreachableOnly', 'compact', 'git'],
     // Note: includeMethods/includeUncertain are deprecated no-ops for
     // about/context/impact since the tiered-output contract (unverified
     // callers are always shown in their own section); kept in the matrix so
     // legacy invocations don't warn as "inapplicable". `all` lifts the
     // unverified display cap.
-    context:      ['name', 'file', 'exclude', 'className', 'includeMethods', 'includeUncertain', 'minConfidence', 'showConfidence', 'unreachableOnly', 'compact', 'all'],
-    impact:       ['name', 'file', 'exclude', 'className', 'includeMethods', 'includeUncertain', 'top', 'unreachableOnly', 'compact'],
+    context:      ['name', 'file', 'exclude', 'className', 'line', 'includeMethods', 'includeUncertain', 'minConfidence', 'showConfidence', 'unreachableOnly', 'compact', 'all'],
+    impact:       ['name', 'file', 'exclude', 'className', 'line', 'includeMethods', 'includeUncertain', 'top', 'unreachableOnly', 'compact'],
     // trace/blast/reverseTrace/affectedTests run the tiered tree contract:
     // includeUncertain is an implied no-op (unverified edges are always
     // visible — frontier/possible band); expandUnverified follows unverified
     // CALLER edges, marking downstream nodes chainUnverified (blast/
     // reverseTrace only — surface trace is down-direction, where unresolved
     // callees have no definition to expand into).
-    blast:        ['name', 'file', 'exclude', 'className', 'includeMethods', 'includeUncertain', 'depth', 'all', 'minConfidence', 'expandUnverified'],
-    reverseTrace: ['name', 'file', 'exclude', 'className', 'includeMethods', 'includeUncertain', 'depth', 'all', 'minConfidence', 'expandUnverified'],
-    smart:        ['name', 'file', 'exclude', 'className', 'includeMethods', 'includeUncertain', 'withTypes', 'minConfidence'],
-    trace:        ['name', 'file', 'exclude', 'className', 'includeMethods', 'includeUncertain', 'depth', 'all', 'minConfidence'],
+    blast:        ['name', 'file', 'exclude', 'className', 'line', 'includeMethods', 'includeUncertain', 'depth', 'all', 'minConfidence', 'expandUnverified'],
+    reverseTrace: ['name', 'file', 'exclude', 'className', 'line', 'includeMethods', 'includeUncertain', 'depth', 'all', 'minConfidence', 'expandUnverified'],
+    smart:        ['name', 'file', 'exclude', 'className', 'line', 'includeMethods', 'includeUncertain', 'withTypes', 'minConfidence'],
+    trace:        ['name', 'file', 'exclude', 'className', 'line', 'includeMethods', 'includeUncertain', 'depth', 'all', 'minConfidence'],
     example:      ['name', 'file', 'className', 'diverse', 'top', 'includeTests'],
-    related:      ['name', 'file', 'className', 'top', 'all'],
-    brief:        ['name', 'file', 'className', 'git'],
+    related:      ['name', 'file', 'className', 'line', 'top', 'all'],
+    brief:        ['name', 'file', 'className', 'line', 'git'],
     // Finding code
     find:         ['name', 'file', 'exclude', 'className', 'includeTests', 'top', 'limit', 'exact', 'in', 'all', 'depth', 'compact'],
     usages:       ['name', 'file', 'exclude', 'className', 'includeTests', 'limit', 'codeOnly', 'context', 'in', 'compact'],
     toc:          ['file', 'exclude', 'top', 'limit', 'all', 'detailed', 'topLevel', 'in'],
     search:       ['term', 'file', 'exclude', 'includeTests', 'top', 'limit', 'codeOnly', 'caseSensitive', 'context', 'regex', 'in', 'type', 'param', 'receiver', 'returns', 'decorator', 'exported', 'unused'],
     tests:        ['name', 'file', 'exclude', 'className', 'callsOnly'],
-    affectedTests:['name', 'file', 'exclude', 'className', 'includeMethods', 'includeUncertain', 'depth', 'minConfidence'],
+    affectedTests:['name', 'file', 'exclude', 'className', 'line', 'includeMethods', 'includeUncertain', 'depth', 'minConfidence'],
     deadcode:     ['file', 'exclude', 'includeTests', 'includeExported', 'includeDecorated', 'limit', 'in'],
     entrypoints:  ['file', 'exclude', 'includeTests', 'excludeTests', 'limit', 'type', 'framework'],
     endpoints:    ['file', 'exclude', 'limit', 'framework', 'bridge', 'serverOnly', 'clientOnly', 'unmatched', 'method', 'prefix', 'hideUncertain'],
     // Extracting code
-    fn:           ['name', 'file', 'className', 'all'],
-    class:        ['name', 'file', 'all', 'maxLines'],
+    fn:           ['name', 'file', 'className', 'line', 'all'],
+    class:        ['name', 'file', 'line', 'all', 'maxLines'],
     lines:        ['file', 'range'],
     expand:       ['item'],
     // File dependencies
@@ -150,8 +150,11 @@ const FLAG_APPLICABILITY = {
     graph:        ['file', 'depth', 'direction', 'all'],
     circularDeps: ['file', 'exclude'],
     // Refactoring
-    verify:       ['name', 'file', 'className', 'includeMethods', 'includeUncertain'],
-    plan:         ['name', 'file', 'className', 'addParam', 'removeParam', 'renameTo', 'defaultValue'],
+    // verify runs the tiered caller contract (v4): includeMethods/
+    // includeUncertain are implied no-ops (unverified sites always visible in
+    // their own band); kept in the matrix so legacy invocations don't warn.
+    verify:       ['name', 'file', 'className', 'line', 'includeMethods', 'includeUncertain'],
+    plan:         ['name', 'file', 'className', 'line', 'addParam', 'removeParam', 'renameTo', 'defaultValue'],
     diffImpact:   ['file', 'limit', 'base', 'staged', 'all'],
     check:        ['file', 'base', 'staged', 'limit'],
     // Other
@@ -160,6 +163,7 @@ const FLAG_APPLICABILITY = {
     api:          ['file', 'limit'],
     stats:        ['functions', 'hot', 'top'],
     doctor:       ['file', 'in', 'limit', 'deep'],
+    orient:       ['top'],
     auditAsync:   ['file', 'exclude', 'limit'],
 };
 
@@ -168,7 +172,7 @@ const FLAG_APPLICABILITY = {
 const BROAD_COMMANDS = new Set([
     'toc', 'entrypoints', 'endpoints', 'diffImpact', 'affectedTests',
     'deadcode', 'usages', 'reverseTrace', 'circularDeps',
-    'doctor', 'check', 'auditAsync',
+    'doctor', 'check', 'auditAsync', 'orient',
 ]);
 
 // Commands that can operate on a single file without a project index.