ucn 5.4.0 → 5.4.2

package/.claude/skills/ucn/SKILL.md

@@ -73,7 +73,9 @@ When the selected definition is a property/getter/setter, `impact` adds a
 separate `PROPERTY ACCESS SITES` band. Confirmed reads/writes have receiver
 identity; matching attribute syntax with an unresolved receiver stays
 unverified. These are change dependencies, not fabricated caller edges, so
-the caller `ACCOUNT` remains a call-shaped partition.
+the caller `ACCOUNT` remains a call-shaped partition. Reads and writes include
+access kind and token column; getter/setter handles describe the same property.
+Unambiguous inherited properties share that owner evidence.
 
 When the selected definition is a type, interface, enum, trait, or record,
 `impact` adds a `TYPE REFERENCE SITES` band: annotation and reference sites
@@ -85,6 +87,10 @@ Target-less `impact` and `check` diff the working tree against `HEAD` AND
 include untracked, non-ignored source files as whole-file additions, so new
 modules are checked before `git add`. `--staged` keeps its index-only meaning.
 The changed-path note also counts untracked documentation and configuration.
+Classes, interfaces, types, and fields appear in separate declaration bands
+with their dependency sites. Modified/deleted declarations block `check` until
+reviewed with the language toolchain: arity checks cannot validate shape or
+inheritance compatibility.
 
 An observed-text zero is not semantic zero or safe-delete proof. Numeric evidence values are ordinal ranking weights, not probabilities.
 
@@ -136,8 +142,9 @@ ucn source src/server.js:40-80 --raw
 Records go to stdout; the `ACCOUNT` / `CONTRACT` lines, notes, and the
 same-name disambiguation go to stderr prefixed `# ` (MCP keeps them in the one
 text block, and `--raw` appends its note as one trailing `# ` line there).
-`usages` emits one record per occurrence, so a source line may repeat; deduplicate
-`path:line` values for line counts. Definition handles start at decorators when
+`usages --lines` emits one record per source line, combining occurrence kinds
+and disclosing repeated occurrences (including JSX open/close tags). JSON keeps
+the individual occurrence records. Definition handles start at decorators when
 present, while usages point at token lines (`nameLine` identifies the declaration
 token when it differs from `startLine`). Structural `search --unused` keeps its
 safety note and decorator tags in shell output; runtime registrations can appear
@@ -145,7 +152,7 @@ and zero call edges do not prove a symbol is safe to delete.
 `--lines` lists the whole band without default row/character caps, so pipe through
 `grep -v '# unverified'` for the confirmed tier. To count distinct source lines
 per file, use `cut -d: -f1,2 | sort -u | cut -d: -f1 | sort | uniq -c`;
-counting raw usage records can count a source line more than once.
+JSON usage records can count a source line more than once.
 Nothing to list prints nothing and exits 1, grep's
 contract; errors exit 2. Explicit `--top`/`--limit` still apply and disclose
 omissions. `show --lines` accepts only callers/callees sections; target-less
@@ -191,6 +198,9 @@ target token); Java `pkg.Type.method()` and C# `Ns.Type.Method()` /
 same-name types exist. A qualifier the resolver cannot place stays visible as
 `method-ambiguous`, never confirmed by first-definition order.
 
+`endpoints` labels test routes and requests with `[test]` (JSON `isTest`).
+Use `--exclude-tests` for a production inventory or `--in=api/` for a directory.
+
 `endpoints` recognizes client receivers by evidence (a receiver typed to an
 HTTP client class, or bound to a pytest fixture that constructs one), not only
 by name. Request-shaped calls with a path literal on an unrecognized receiver

package/.claude/skills/ucn/references/commands.md

@@ -35,7 +35,7 @@ structural or code-only search.
 | `deps <file>` | File dependency graph. Use `--direction=imports\|importers\|both`, `--detailed`, or `--cycles`. Cycles distinguish eager edges from function-local, Python typing-guarded, and TypeScript type-only edges. Complete cycle groups remain visible when enumeration is capped. |
 | `api [file]` | Static exported/public surface for a project or file. An exact file includes tests; broader scans exclude tests with a count. Use `--include-tests` to include them. |
 | `entrypoints` | Framework, route, task, test, and runtime entry points. |
-| `endpoints` | Server/client HTTP surface; `--bridge` adds advisory matching. |
+| `endpoints` | Server/client HTTP surface; `--bridge` adds advisory matching. Test sites carry `[test]`; `--exclude-tests` removes them and `--in=DIR` scopes the inventory. |
 
 ## Focused audits and runtime evidence
 
@@ -55,13 +55,13 @@ Structural `search --param` matches parameter names, types, and defaults; `--ret
 
 `repo` summary/stats `buildTime` is the duration of the last index build (discovery, parsing, and graphs), retained in the cache. It excludes cache loading/saving and query execution, so it is not command wall time; `buildTimeNote` states this boundary.
 
-`--lines` writes one record per output line. `usages` records occurrences, so multiple tokens on the same source line can produce repeated `path:line` values. Deduplicate those values when counting source lines.
+`--lines` writes one record per output line. `usages --lines` groups occurrences by source line and tags their kinds and counts. JSON retains individual occurrence records.
 
 Public JSON source paths (`file`, caller files, dependency roots and edges) are project-relative, with the absolute base in `meta.pathBase`. Project roots and external paths remain absolute. Indexed absolute handles are accepted as well as relative handles.
 
 Default test exclusions follow language conventions. Python `spec.py` and `*_spec.py` are included; `test_*.py`, `*_test.py`, and test directories are excluded. Structural search reports hidden test-file counts, including on empty results. `--include-tests` disables these defaults; explicit `--exclude` patterns still apply.
 
-`audit-async` checks recognized async producers, including captured JS/TS/HTML promises used as resolved values in the same lexical scope. Promise returns and handlers are valid; alias flow and unknown receivers require compiler/type-checker review.
+`audit-async` checks recognized async producers, including Python coroutine calls discarded in synchronous functions or module scope and captured JS/TS/HTML promises used as resolved values in the same lexical scope. Promise returns and handlers are valid; alias flow and unknown receivers require compiler/type-checker review.
 
 ## Common flags
 

package/cli/index.js

@@ -485,6 +485,7 @@ function formatCliText(command, result, params, execution, displayFlags) {
         all: !!displayFlags?.all,
         surface: 'cli',
         params,
+        trailingChars: 1, // emitCliText appends the terminal newline.
     }).text;
 }
 
@@ -932,9 +933,9 @@ Common flags:
   --all --compact --no-compact --json --include-tests --class-name=X --line=N
   --range=N-M (source with --file=PATH)
   --base=REF --staged --no-cache --clear-cache [--all] --max-files=N --workers=N
-  --max-chars=N (text output; default 10K targeted / 3K broad, ceiling 100K)
+  --max-chars=N (text characters, not UTF-8 bytes; default 10K targeted / 3K broad, ceiling 100K)
   --lines  find/usages/search/show/impact: grep -n shape, one path:line:text
-           record per output line; usages may repeat a source line per occurrence
+           record per output line; usages combines occurrences on each source line
            (tags after a tab: # unverified: <reason>, # import,
            # callee); accounting and notes go to stderr as "# " lines; exit 1
            when nothing matched; exit 2 on errors. No default result cap.

package/core/accessors.js

@@ -2,6 +2,48 @@
 
 const path = require('path');
 const { codeUnitCompare } = require('./shared');
+const { getParser, safeParse } = require('../languages');
+
+function inheritedAccessor(index, enclosing, name, definition) {
+    let owner = enclosing?.className;
+    let file = enclosing?.file;
+    const seen = new Set();
+    while (owner && file && !seen.has(`${file}\0${owner}`)) {
+        seen.add(`${file}\0${owner}`);
+        if (owner === ownerName(definition) && file === definition.file) return true;
+        // An override owns this spelling. Multiple inheritance and duplicate
+        // declarations need richer lookup evidence, so keep them unverified.
+        if ((index.symbols.get(name) || []).some(d => d.className === owner && d.file === file)) return false;
+        const definitions = (index.symbols.get(owner) || []).filter(d => d.file === file && ['class', 'struct'].includes(d.type));
+        if (definitions.length !== 1) return false;
+        const parents = index._getInheritanceParentsAt(owner, file, definitions[0].startLine) || [];
+        if (parents.length !== 1) return false;
+        const parentName = bareTypeName(parents[0]);
+        const candidates = (index.symbols.get(parentName) || []).filter(d => ['class', 'struct'].includes(d.type));
+        const local = candidates.filter(d => d.file === file);
+        const imported = candidates.filter(d => index.importGraph.get(file)?.has(d.file));
+        const targets = local.length ? local : imported;
+        if (targets.length !== 1) return false;
+        owner = targets[0].name;
+        file = targets[0].file;
+    }
+    return false;
+}
+
+function accessKind(tree, usage) {
+    if (!tree || !Number.isInteger(usage.column)) return 'access';
+    let node = tree.rootNode.descendantForPosition({ row: usage.line - 1, column: usage.column });
+    if (['attribute', 'member_expression', 'member_access_expression'].includes(node.parent?.type)) node = node.parent;
+    const parent = node.parent;
+    if (parent?.type === 'update_expression' || parent?.type === 'delete_statement') return parent.type === 'update_expression' ? 'read/write' : 'delete';
+    if (['assignment', 'assignment_expression', 'augmented_assignment', 'augmented_assignment_expression'].includes(parent?.type)) {
+        const left = parent.childForFieldName('left');
+        if (left && left.startIndex === node.startIndex && left.endIndex === node.endIndex) {
+            return parent.type.startsWith('augmented') ? 'read/write' : 'write';
+        }
+    }
+    return 'read';
+}
 
 // Descriptors/properties are consumed through reads and writes, not only
 // call syntax. Keep this vocabulary shared by impact and refactoring so the
@@ -87,11 +129,14 @@ function findAccessorReferences(index, name, definition, options = {}) {
             occurrences = index._getCachedUsages(file, name);
         } catch { continue; }
         if (!occurrences) continue;
+        const parser = getParser(entry.language);
+        const tree = parser ? safeParse(parser, content) : null;
         const lines = content.split('\n');
         for (const usage of occurrences) {
             if (usage.usageType !== 'reference') continue;
             refs.push({
                 ...usage,
+                accessKind: accessKind(tree, usage),
                 file,
                 relativePath: entry.relativePath,
                 content: lines[usage.line - 1] || '',
@@ -106,6 +151,7 @@ function findAccessorReferences(index, name, definition, options = {}) {
             absoluteFile: ref.file,
             line: ref.line,
             expression: (ref.content || '').trim(),
+            accessKind: ref.accessKind,
             ...(Number.isInteger(ref.column) && { column: ref.column }),
             ...(ref.receiver && { receiver: ref.receiver }),
         };
@@ -122,7 +168,8 @@ function findAccessorReferences(index, name, definition, options = {}) {
         const enclosing = index.findEnclosingFunction(ref.file, ref.line, true);
         const receiver = ref.receiver || null;
         if (receiver && ['self', 'cls', 'this'].includes(receiver) &&
-            enclosing?.className === owner && enclosing.file === definition.file) {
+            ((enclosing?.className === owner && enclosing.file === definition.file) ||
+                inheritedAccessor(index, enclosing, name, definition))) {
             confirmed.push({
                 ...shaped,
                 callerName: enclosing.name,

package/core/analysis.js

@@ -17,7 +17,7 @@ const { NON_CALLABLE_TYPES, addTestExclusions, countTextBlindspots,
 const { isTestFile } = require('./discovery');
 const { computeReachability, symbolKey } = require('./entrypoints');
 const { getLanguageAdapter } = require('../languages');
-const { projectComputedDispatch } = require('./ast-analysis');
+const { projectComputedDispatch, declarationSnapshots } = require('./ast-analysis');
 const { findAccessorReferences } = require('./accessors');
 
 // JS/TS test framework helpers — calls to these bracket a test case.
@@ -1181,6 +1181,7 @@ function impact(index, name, options = {}) {
         // Convert findCallers results to the format expected by analyzeCallSite
         const calls = callerResults.map(c => ({
             file: c.file,
+            calledAs: c.calledAs,
             relativePath: c.relativePath,
             line: c.line,
             content: c.content,
@@ -2085,6 +2086,7 @@ function diffImpact(index, options = {}) {
             moduleLevelChanges: [],
             newFunctions: [],
             deletedFunctions: [],
+            symbols: [], newSymbols: [], deletedSymbols: [],
             summary: { modifiedFunctions: 0, deletedFunctions: 0, newFunctions: 0, totalCallSites: 0, unverifiedCallSites: 0, affectedFiles: 0 }
         };
     }
@@ -2093,6 +2095,7 @@ function diffImpact(index, options = {}) {
     const moduleLevelChanges = [];
     const newFunctions = [];
     const deletedFunctions = [];
+    const symbolChanges = { symbols: [], newSymbols: [], deletedSymbols: [] };
     const callerFileSet = new Set();
     let totalCallSites = 0;
     let totalUnverifiedSites = 0;
@@ -2120,6 +2123,7 @@ function diffImpact(index, options = {}) {
                         { cwd: index.root, encoding: 'utf-8', maxBuffer: 10 * 1024 * 1024, stdio: ['ignore', 'pipe', 'ignore'] }
                     );
                     const oldParsed = parse(oldContent, lang);
+                    collectNonCallableChanges(index, change, oldParsed, [], symbolChanges);
                     for (const oldFn of extractCallableSymbols(oldParsed)) {
                         deletedFunctions.push({
                             name: oldFn.name,
@@ -2144,6 +2148,8 @@ function diffImpact(index, options = {}) {
         // The identity key is `name\0className` (matches deletion-detection below).
         let oldSymbolIdentities = null; // null = unknown (file untracked or git failed)
         let oldCallables = null;        // old symbols WITH ranges — deleted lines are old-file coordinates
+        let oldParsed = null;
+        let oldLines = null;
         if (change.deletedLines.length > 0 || change.addedLines.length > 0) {
             const ref = staged ? 'HEAD' : base;
             try {
@@ -2153,7 +2159,8 @@ function diffImpact(index, options = {}) {
                 );
                 const fileLang = detectLanguage(change.filePath);
                 if (fileLang) {
-                    const oldParsed = parse(oldContent, fileLang);
+                    oldParsed = parse(oldContent, fileLang);
+                    oldLines = oldContent.split('\n');
                     oldSymbolIdentities = new Set();
                     oldCallables = extractCallableSymbols(oldParsed);
                     for (const oldFn of oldCallables) {
@@ -2165,8 +2172,13 @@ function diffImpact(index, options = {}) {
             }
         }
 
+        collectNonCallableChanges(index, change, oldParsed, fileEntry.symbols, symbolChanges, oldLines);
+
         for (const line of change.addedLines) {
-            const symbol = index.findEnclosingFunction(change.filePath, line, true);
+            // Arrow fields are indexed as fields but their bodies still need
+            // callable impact once declaration-only changes are separated out.
+            const symbol = index.findEnclosingFunction(change.filePath, line, true) ||
+                fileEntry.symbols.find(s => isDiffCallable(s) && s.startLine <= line && s.endLine >= line);
             if (symbol) {
                 const key = `${symbol.name}:${symbol.startLine}`;
                 if (!affectedSymbols.has(key)) {
@@ -2193,7 +2205,7 @@ function diffImpact(index, options = {}) {
         // still exists to its CURRENT definition for modification attribution.
         const currentByIdentity = new Map();
         for (const s of fileEntry.symbols) {
-            if (NON_CALLABLE_TYPES.has(s.type)) continue;
+            if (!isDiffCallable(s)) continue;
             const k = `${s.name}\0${s.className || ''}`;
             if (!currentByIdentity.has(k)) currentByIdentity.set(k, []);
             currentByIdentity.get(k).push(s);
@@ -2249,7 +2261,7 @@ function diffImpact(index, options = {}) {
                 let bestExact = false;
                 let bestRange = Infinity;
                 for (const symbol of fileEntry.symbols) {
-                    if (NON_CALLABLE_TYPES.has(symbol.type)) continue;
+                    if (!isDiffCallable(symbol)) continue;
                     const exact = line >= symbol.startLine && line <= symbol.endLine;
                     const tolerant = line >= symbol.startLine - 2 && line <= symbol.endLine + 2;
                     if (!exact && !tolerant) continue;
@@ -2324,7 +2336,7 @@ function diffImpact(index, options = {}) {
         if (change.deletedLines.length > 0 && oldCallables !== null) {
             const currentCounts = new Map();
             for (const s of fileEntry.symbols) {
-                if (NON_CALLABLE_TYPES.has(s.type)) continue;
+                if (!isDiffCallable(s)) continue;
                 const key = `${s.name}\0${s.className || ''}`;
                 currentCounts.set(key, (currentCounts.get(key) || 0) + 1);
             }
@@ -2478,6 +2490,22 @@ function diffImpact(index, options = {}) {
         }
     }
 
+    const dependencyFiles = new Set();
+    let totalDependencySites = 0;
+    let unverifiedDependencySites = 0;
+    for (const symbol of [...symbolChanges.symbols, ...symbolChanges.newSymbols]) {
+        const evidence = symbol.impact;
+        if (!evidence) continue;
+        totalCallSites += evidence.totalCallSites || 0;
+        totalUnverifiedSites += evidence.unverifiedSites?.length || 0;
+        for (const group of evidence.byFile || []) callerFileSet.add(path.resolve(index.root, group.file));
+        const refs = evidence.typeReferences || evidence.propertyAccesses;
+        totalDependencySites += refs?.confirmedCount || 0;
+        unverifiedDependencySites += refs?.unverifiedCount || 0;
+        for (const group of refs?.byFile || []) dependencyFiles.add(group.file);
+        for (const site of refs?.unverifiedSites || []) dependencyFiles.add(site.file);
+    }
+
     return {
         base: staged ? '(staged)' : base,
         changedPaths: changes.length,
@@ -2487,10 +2515,17 @@ function diffImpact(index, options = {}) {
         moduleLevelChanges,
         newFunctions,
         deletedFunctions,
+        ...symbolChanges,
         summary: {
             modifiedFunctions: functions.length,
             deletedFunctions: deletedFunctions.length,
             newFunctions: newFunctions.length,
+            modifiedSymbols: symbolChanges.symbols.length,
+            newSymbols: symbolChanges.newSymbols.length,
+            deletedSymbols: symbolChanges.deletedSymbols.length,
+            totalDependencySites,
+            unverifiedDependencySites,
+            dependencyFiles: dependencyFiles.size,
             totalCallSites,
             unverifiedCallSites: totalUnverifiedSites,
             affectedFiles: callerFileSet.size
@@ -2499,10 +2534,95 @@ function diffImpact(index, options = {}) {
     } finally { index._endOp(); }
 }
 
+// Non-callable declarations have change dependencies too. Keep them separate
+// from functions so type references never inflate call-site accounting.
+function collectNonCallableChanges(index, change, oldParsed, currentSymbols, output, oldLines = null) {
+    const nonCallable = s => NON_CALLABLE_TYPES.has(s.type) || s.type === 'record';
+    const oldSymbols = [];
+    for (const cls of oldParsed?.classes || []) {
+        oldSymbols.push(cls);
+        for (const member of cls.members || []) {
+            const symbol = { ...member, type: member.memberType, className: cls.name };
+            if (nonCallable(symbol)) oldSymbols.push(symbol);
+        }
+    }
+    oldSymbols.push(...(oldParsed?.stateObjects || []).map(s => ({ ...s, type: 'state' })));
+    const identity = s => `${s.type}\0${s.className || ''}\0${s.name}`;
+    const before = new Map();
+    for (const s of oldSymbols.filter(nonCallable)) {
+        const key = identity(s);
+        if (!before.has(key)) before.set(key, []);
+        before.get(key).push(s);
+    }
+    const touches = (s, lines) => lines.some(line => line >= s.startLine && line <= (s.endLine || s.startLine));
+    const language = detectLanguage(change.filePath);
+    let currentSnapshots = new Map();
+    let oldSnapshots = new Map();
+    // Unsupported/recovered declaration shapes retain conservative range
+    // reporting. Never turn a failed AST projection into a clean diff.
+    try {
+        if (currentSymbols.some(nonCallable)) currentSnapshots = declarationSnapshots(
+            index._getFileLines(change.filePath).join('\n'), language, currentSymbols.filter(nonCallable));
+    } catch (_) { /* fall back to symbol ranges */ }
+    try {
+        if (oldLines) oldSnapshots = declarationSnapshots(oldLines.join('\n'), language, oldSymbols.filter(nonCallable));
+    } catch (_) { /* fall back to symbol ranges */ }
+    const declarationLines = (s, lines, snapshot) => lines.filter(line =>
+        touches(s, [line]) && (!snapshot || snapshot.lines.has(line)));
+    const append = (symbol, kind, old = null, lines = null) => {
+        const item = {
+            name: symbol.name, type: symbol.type, className: symbol.className,
+            filePath: change.filePath, relativePath: change.relativePath,
+            startLine: symbol.startLine, endLine: symbol.endLine,
+            addedLines: kind === 'deletedSymbols' ? [] : lines.added,
+            deletedLines: kind === 'deletedSymbols' ? change.deletedLines.filter(line => touches(old, [line])) : lines.deleted,
+        };
+        if (kind === 'deletedSymbols') {
+            // The old identity no longer exists. Name occurrences are review
+            // candidates, not proven references to the removed declaration.
+            item.remainingReferences = index.usages(symbol.name, { includeTests: true, codeOnly: true })
+                .filter(u => !u.isDefinition).map(u => ({
+                    file: u.relativePath, line: u.line, expression: u.content,
+                    reason: 'deleted-target-name-match', tier: 'unverified',
+                }));
+        } else {
+            item.impact = impact(index, symbol.name, {
+                file: change.relativePath, line: symbol.startLine, className: symbol.className,
+            });
+        }
+        output[kind].push(item);
+    };
+    for (const symbol of currentSymbols.filter(nonCallable)) {
+        const old = before.get(identity(symbol))?.shift();
+        const currentSnapshot = currentSnapshots.get(symbol);
+        const oldSnapshot = oldSnapshots.get(old);
+        if (old && currentSnapshot && oldSnapshot && currentSnapshot.signature === oldSnapshot.signature) continue;
+        const lines = {
+            added: declarationLines(symbol, change.addedLines, currentSnapshot),
+            deleted: old ? declarationLines(old, change.deletedLines, oldSnapshot) : [],
+        };
+        if (lines.added.length > 0 || lines.deleted.length > 0) {
+            // When the base cannot be read, do not invent a new declaration.
+            append(symbol, old || (!oldParsed && !change.untracked && !change.isNew)
+                ? 'symbols' : 'newSymbols', old, lines);
+        }
+    }
+    for (const group of before.values()) {
+        for (const old of group) {
+            if (touches(old, change.deletedLines)) append(old, 'deletedSymbols', old);
+        }
+    }
+}
+
 // ========================================================================
 // STANDALONE HELPERS (used by diffImpact and parseDiff)
 // ========================================================================
 
+function isDiffCallable(symbol) {
+    const type = symbol.type || symbol.memberType || 'method';
+    return !NON_CALLABLE_TYPES.has(type) || (type === 'field' && symbol.isMethod);
+}
+
 /**
  * Extract all callable symbols (functions + class methods) from a parse result,
  * matching how indexFile builds the symbol list — the identity keys
@@ -2525,7 +2645,7 @@ function extractCallableSymbols(parsed) {
     for (const cls of parsed.classes) {
         if (cls.members) {
             for (const m of cls.members) {
-                if (NON_CALLABLE_TYPES.has(m.memberType || 'method')) continue;
+                if (!isDiffCallable(m)) continue;
                 symbols.push({ name: m.name, className: cls.name, startLine: m.startLine, endLine: m.endLine });
             }
         }
@@ -2556,8 +2676,10 @@ function parseDiff(diffText, root) {
     const changes = [];
     let currentFile = null;
     let pendingOldPath = null; // Track --- a/ path for deleted files
+    let pendingNewFile = false;
 
     for (const line of diffText.split('\n')) {
+        if (line === '--- /dev/null') pendingNewFile = true;
         // Track old file path from --- header for deleted-file detection
         // Handles both unquoted (--- a/path) and quoted (--- "a/path") formats
         const oldMatch = line.match(/^--- (?:"a\/((?:[^"\\]|\\.)*)"|a\/(.+?))\s*$/);
@@ -2587,8 +2709,10 @@ function parseDiff(diffText, root) {
                 relativePath,
                 addedLines: [],
                 deletedLines: [],
+                ...(pendingNewFile && { isNew: true }),
                 ...(isDevNull && { isDeleted: true })
             };
+            pendingNewFile = false;
             changes.push(currentFile);
             continue;
         }
@@ -2896,7 +3020,7 @@ function auditAsync(index, options = {}) {
                     }
                 }
             }
-            if (asyncFns.length === 0) return;
+            if (asyncFns.length === 0 && language !== 'python') 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
@@ -2965,6 +3089,12 @@ function auditAsync(index, options = {}) {
             // immediate enclosing fn-node is async (so callbacks inside an
             // async fn aren't misclassified as async themselves).
             function nearestAsyncEnclosing(callNode) {
+                // Python creates a dormant coroutine even in a synchronous
+                // scope. A discarded expression never runs; returning or
+                // passing it to an event-loop consumer remains intentional.
+                let expression = callNode;
+                while (expression.parent?.type === 'parenthesized_expression') expression = expression.parent;
+                const discardedPython = language === 'python' && expression.parent?.type === 'expression_statement';
                 let cur = callNode.parent;
                 while (cur) {
                     if (FN_NODE_TYPES.has(cur.type)) {
@@ -2981,11 +3111,16 @@ function auditAsync(index, options = {}) {
                                 endLine: cur.endPosition.row + 1,
                             };
                         }
+                        if (discardedPython) return {
+                            name: cur.childForFieldName('name')?.text || '<anonymous>',
+                            startLine: cur.startPosition.row + 1,
+                            endLine: cur.endPosition.row + 1,
+                        };
                         return null; // Inner non-async fn — stop, don't leak into outer scope.
                     }
                     cur = cur.parent;
                 }
-                return null;
+                return discardedPython ? { name: '<module>' } : null;
             }
 
             function visit(node) {

package/core/ast-analysis.js

@@ -28,6 +28,101 @@ const CALLABLE_NODES = new Set([
     'operator_declaration', 'conversion_operator_declaration',
 ]);
 
+const DECLARATION_NODES = {
+    class: new Set(['class_declaration', 'abstract_class_declaration', 'class_definition', 'class_specifier', 'class']),
+    struct: new Set(['struct_item', 'struct_specifier', 'struct_declaration', 'type_spec']),
+    interface: new Set(['interface_declaration', 'type_spec']),
+    type: new Set(['type_alias_declaration', 'type_definition', 'type_spec', 'type_alias', 'type_item', 'associated_type']),
+    enum: new Set(['enum_declaration', 'enum_item', 'enum_specifier']),
+    trait: new Set(['trait_item']),
+    impl: new Set(['impl_item']),
+    record: new Set(['record_declaration']),
+    field: new Set(['field_definition', 'public_field_definition', 'property_signature', 'field_declaration', 'variable_declarator']),
+    state: new Set(['variable_declarator', 'assignment', 'init_declarator', 'const_item', 'static_item', 'const_spec', 'var_spec']),
+};
+const FUNCTION_EXPRESSIONS = new Set([
+    'function_expression', 'generator_function', 'arrow_function', 'lambda',
+    'func_literal', 'closure_expression', 'lambda_expression', 'anonymous_method_expression',
+]);
+const COMMENT_NODES = new Set(['comment', 'line_comment', 'block_comment']);
+
+/**
+ * Compare declarations by AST tokens, not lines: a class header and its first
+ * method can share a line. Concrete methods belong to the callable diff;
+ * bodyless signatures, fields (including unindexed Python assignments), and
+ * nested types belong to the declaration. Function-valued fields retain their
+ * signature but not their executable body. Nothing here is persisted in the
+ * index, so old and current source use the same projection without a cache bump.
+ * Missing AST mappings return no snapshot; callers keep conservative reporting.
+ */
+function declarationSnapshots(content, language, symbols) {
+    const snapshots = new Map();
+    if (content == null || symbols.length === 0) return snapshots;
+    const parser = getParser(language);
+    if (!parser) return snapshots;
+    const root = safeParse(parser, content).rootNode;
+    const wantedKinds = new Set(symbols.flatMap(s => [...(DECLARATION_NODES[s.type] || [])]));
+    const candidates = new Map();
+    walkNamed(root, node => {
+        if (!wantedKinds.has(node.type)) return;
+        if (!candidates.has(node.type)) candidates.set(node.type, []);
+        candidates.get(node.type).push(node);
+    });
+    const hasName = (node, name) => {
+        if (!node) return false;
+        if (node.text === name) return true;
+        return hasName(node.childForFieldName('name') || node.childForFieldName('declarator') ||
+            (node.type === 'generic_type' && node.childForFieldName('type')), name);
+    };
+    for (const symbol of symbols) {
+        const kinds = DECLARATION_NODES[symbol.type];
+        if (!kinds) continue;
+        let declaration = null;
+        for (const kind of kinds) {
+            for (const node of candidates.get(kind) || []) {
+                if (node.startPosition.row + 1 < symbol.startLine ||
+                    node.endPosition.row + 1 > (symbol.endLine || symbol.startLine)) continue;
+                const name = node.childForFieldName('name') || node.childForFieldName('declarator') ||
+                    node.childForFieldName('left') || (symbol.type === 'impl' && node.childForFieldName('type'));
+                if (!hasName(name, symbol.typeName || symbol.name)) continue;
+                if (!declaration || node.endIndex - node.startIndex > declaration.endIndex - declaration.startIndex) {
+                    declaration = node;
+                }
+            }
+        }
+        if (!declaration || declaration.hasError) continue;
+        // Export modifiers and Python decorators live outside the declaration.
+        while (['export_statement', 'decorated_definition'].includes(declaration.parent?.type) &&
+            declaration.parent.startPosition.row + 1 >= symbol.startLine) declaration = declaration.parent;
+        const tokens = [];
+        const lines = new Set();
+        const visit = node => {
+            if (COMMENT_NODES.has(node.type) || node.type === 'pass_statement') return;
+            if (node.type === 'decorated_definition' &&
+                CALLABLE_NODES.has(node.childForFieldName('definition')?.type)) return;
+            // Class docstrings are documentation, not fields or inheritance.
+            if (language === 'python' && node.type === 'expression_statement' &&
+                node.namedChildCount === 1 && ['string', 'concatenated_string'].includes(node.namedChild(0).type)) return;
+            const body = CALLABLE_NODES.has(node.type) ? node.childForFieldName('body') : null;
+            if (body && !FUNCTION_EXPRESSIONS.has(node.type)) return;
+            if (node.childCount === 0) {
+                // Empty anonymous semicolons between members are separators.
+                if (node.type === ';' && ['class_body', 'interface_body', 'declaration_list'].includes(node.parent?.type)) return;
+                tokens.push([node.type, node.text]);
+                for (let line = node.startPosition.row + 1; line <= node.endPosition.row + 1; line++) lines.add(line);
+                return;
+            }
+            for (const child of node.children) {
+                if (body && child.id === body.id) continue;
+                visit(child);
+            }
+        };
+        visit(declaration);
+        snapshots.set(symbol, { signature: JSON.stringify(tokens), lines });
+    }
+    return snapshots;
+}
+
 const BRANCH_NODES = new Set([
     'if_statement', 'if_expression', 'elif_clause',
     'for_statement', 'for_in_statement', 'for_expression',
@@ -375,6 +470,7 @@ function projectComputedDispatch(index) {
 }
 
 module.exports = {
+    declarationSnapshots,
     computeAstComplexity,
     computedDispatchSites,
     projectComputedDispatch,

package/core/bridge.js

@@ -26,7 +26,7 @@
 'use strict';
 
 const fs = require('fs');
-const { codeUnitCompare } = require('./shared');
+const { codeUnitCompare, isTestPath } = require('./shared');
 const path = require('path');
 const { getCachedCalls } = require('./callers');
 const { getParser, safeParse } = require('../languages');
@@ -1490,9 +1490,12 @@ function endpoints(index, options = {}) {
         showUncertain: options.showUncertain !== false,
     };
 
-    let routes = opts.clientOnly ? [] : extractServerRoutes(index);
-    let requests = (opts.serverOnly ? [] : extractClientRequests(index));
-    let uncertainRequests = opts.serverOnly ? [] : (index._endpointsCache?.uncertainRequests || []);
+    const label = r => ({ ...r, isTest: isTestPath(r.file) });
+    const inScope = r => index.matchesFilters(r.file, { in: options.in }) &&
+        !(options.excludeTests && r.isTest);
+    let routes = (opts.clientOnly ? [] : extractServerRoutes(index)).map(label).filter(inScope);
+    let requests = (opts.serverOnly ? [] : extractClientRequests(index)).map(label).filter(inScope);
+    let uncertainRequests = (opts.serverOnly ? [] : (index._endpointsCache?.uncertainRequests || [])).map(label).filter(inScope);
     if (uncertainRequests.length > 0) {
         // A server route registration (`@app.get("/x")`, `router.get("/x", h)`)
         // is request-shaped too; the route inventory already owns those lines.
@@ -1514,12 +1517,14 @@ function endpoints(index, options = {}) {
         uncertainRequests = uncertainRequests.filter(r => r.method.toUpperCase() === opts.method || r.method === 'request');
     }
 
-    let bridges = opts.bridge ? bridgeEndpoints(index) : [];
+    let bridges = opts.bridge ? bridgeEndpoints(index).map(b => ({
+        ...b, route: label(b.route), request: label(b.request),
+    })) : [];
     if (!opts.showUncertain) {
         bridges = bridges.filter(b => b.matchType !== 'uncertain');
     }
     // If user filtered routes/requests, also constrain bridges
-    if (opts.method || opts.prefix) {
+    if (opts.method || opts.prefix || options.in || options.excludeTests) {
         const routeKeys = new Set(routes.map(r => `${r.absoluteFile}:${r.line}:${r.method}:${r.path}`));
         const reqKeys = new Set(requests.map(r => `${r.absoluteFile}:${r.line}:${r.method}:${r.path}`));
         bridges = bridges.filter(b =>