ucn 4.0.2 → 4.1.1

package/core/check.js

@@ -77,11 +77,16 @@ function check(index, options = {}) {
             ? verifyResult.mismatchDetails
             : [];
 
-        // For modified functions, the existing diffImpact result has `callers` already
+        // For modified functions, the contracted diffImpact result carries both
+        // bands already (confirmed `callers` + visible `unverifiedCallers`).
         let callers = Array.isArray(fn.callers) ? fn.callers : [];
+        let unverifiedCallers = Array.isArray(fn.unverifiedCallers) ? fn.unverifiedCallers : [];
         if (callers.length === 0 && fn._kind === 'added') {
             try {
-                callers = index.findCallers(fn.name, { includeMethods: true, includeUncertain: false }) || [];
+                const raw = index.findCallers(fn.name, { includeMethods: true, collectAccount: true }) || [];
+                callers = raw.filter(c => c.tier !== 'unverified');
+                unverifiedCallers = raw.filter(c => c.tier === 'unverified')
+                    .concat(raw.unverifiedEntries || []);
             } catch (e) { /* skip */ }
         }
 
@@ -91,14 +96,17 @@ function check(index, options = {}) {
             line: fn.startLine || fn.line,
             kind: fn._kind,
             callerCount: callers.length,
+            unverifiedCallerCount: unverifiedCallers.length,
             signatureMismatches: mismatches.length,
             ...(mismatches.length > 0 && { mismatches: mismatches.slice(0, 5) }),
         };
 
-        // Orphan = newly added with zero callers AND not detected as an entry point.
-        // (A new helper called by another new helper is still NOT orphan; reachability
-        //  is rebuilt as the user iterates, and false positives here cause noise.)
-        if (item.kind === 'added' && callers.length === 0) {
+        // Orphan = newly added with zero caller CANDIDATES IN EITHER TIER and
+        // not detected as an entry point. Zero confirmed + N unverified is NOT
+        // orphan (the #223 reverseTrace entry-point soundness rule — claiming
+        // "nobody calls this" after routing candidates to the unverified tier
+        // would be the exact silent-drop the contract forbids).
+        if (item.kind === 'added' && callers.length === 0 && unverifiedCallers.length === 0) {
             // Check entry points: if the symbol is a known entry-point pattern, not orphan
             let isEntry = false;
             try {
@@ -114,7 +122,9 @@ function check(index, options = {}) {
         items.push(item);
     }
 
-    // Surface deleted functions inline — they don't have line/file but still matter
+    // Surface deleted functions inline. remainingCallSites are name-level
+    // matches still present in the tree — a deleted function that is still
+    // called is a likely break, so they count as unverified callers here.
     for (const d of deleted) {
         items.push({
             name: d.name || '(unnamed)',
@@ -122,6 +132,7 @@ function check(index, options = {}) {
             line: d.startLine || 0,
             kind: 'deleted',
             callerCount: 0,
+            unverifiedCallerCount: (d.remainingCallSites || []).length,
             signatureMismatches: 0,
         });
     }
@@ -157,7 +168,7 @@ function check(index, options = {}) {
             actions.push({
                 severity: 'warn',
                 kind: 'orphan_new',
-                message: `${it.name} is new but has no callers and is not an entry point`,
+                message: `${it.name} is new but has no callers (confirmed or unverified) and is not an entry point`,
             });
         }
     }

package/core/deadcode.js

@@ -6,13 +6,20 @@
  */
 
 const { detectLanguage, getParser, getLanguageModule, safeParse, langTraits } = require('../languages');
+const { dirname: pathDirname } = require('path');
 const { isTestFile } = require('./discovery');
 const { isFrameworkEntrypoint } = require('./entrypoints');
 const { splitParentList } = require('./graph-build');
-const { isOverrideMarked } = require('./shared');
+const { isOverrideMarked, codeUnitCompare, lineInRanges, maskBlockComments } = require('./shared');
 
 const _CLASS_KINDS = ['class', 'struct', 'interface', 'trait', 'record'];
 
+// Class-like kinds the audit claims directly (fix #253a — unused classes were
+// never reported: the audit surface had no class kinds). 'impl' stays out (an
+// impl block belongs to its struct — the struct claim covers it); 'type'
+// aliases and macros stay out (deferred — each is its own claim family).
+const CLASS_AUDIT_KINDS = ['class', 'struct', 'interface', 'trait', 'record', 'enum', 'namespace'];
+
 /** Strip a base-type expression to its bare name: `Mapping[str, int]`→Mapping, `java.util.List<Foo>`→List, `a::b::C`→C. */
 function _bareBaseName(raw) {
     return String(raw).replace(/[<[(].*$/s, '').split('.').pop().split('::').pop().trim();
@@ -28,13 +35,31 @@ function _bareBaseName(raw) {
 // convention, rule #9.)
 const _UNIVERSAL_ROOTS = new Set(['object', 'Object']);
 
+// Python typing bases with a fixed, known surface that never dispatch an
+// arbitrary subclass method by name (fix #253b): `class DataService(Generic[T])`
+// is exactly `class DataService` for dispatch purposes — Generic contributes
+// __class_getitem__ machinery, nothing that calls subclass methods. Without
+// this, the external-base shield hid every public method of every generic
+// class. Python-gated: an external class literally named Generic in another
+// language could genuinely dispatch. Protocol stays OUT — protocol classes
+// are contract surface, and their members' "deadness" is a different claim.
+const _PY_NON_DISPATCHING_BASES = new Set(['Generic']);
+
 /** True when a base name resolves to NO in-project class/struct/interface/trait/record (an out-of-tree type). */
-function _baseIsExternal(index, bare) {
+function _baseIsExternal(index, bare, lang) {
     if (!bare || _UNIVERSAL_ROOTS.has(bare)) return false;
+    if (lang === 'python' && _PY_NON_DISPATCHING_BASES.has(bare)) return false;
     const defs = index.symbols.get(bare);
     return !(defs && defs.some(d => _CLASS_KINDS.includes(d.type)));
 }
 
+/** Does this CLASS DEF extend at least one base that is not in the project index? */
+function _classDefHasExternalBase(index, classDef, lang) {
+    if (!classDef.extends) return false;
+    const supers = Array.isArray(classDef.extends) ? classDef.extends : splitParentList(classDef.extends);
+    return supers.some(raw => _baseIsExternal(index, _bareBaseName(raw), lang));
+}
+
 /**
  * Does the method's enclosing class EXTEND at least one base that is NOT in the
  * project index? An out-of-tree base is a framework/library type UCN can't see;
@@ -50,16 +75,10 @@ function _baseIsExternal(index, bare) {
  * `impl Display for`s.
  */
 function _classHasExternalBase(index, symbol) {
+    const lang = index.files.get(symbol.file)?.language;
     const classDefs = (index.symbols.get(symbol.className) || []).filter(c =>
         c.file === symbol.file && _CLASS_KINDS.includes(c.type));
-    for (const cd of classDefs) {
-        if (!cd.extends) continue;
-        const supers = Array.isArray(cd.extends) ? cd.extends : splitParentList(cd.extends);
-        for (const raw of supers) {
-            if (_baseIsExternal(index, _bareBaseName(raw))) return true;
-        }
-    }
-    return false;
+    return classDefs.some(cd => _classDefHasExternalBase(index, cd, lang));
 }
 
 /**
@@ -93,6 +112,55 @@ function overridesOutOfTreeBase(index, symbol) {
     return false;
 }
 
+// Symbol types whose definition NAME line provably cannot reference a
+// same-name VALUE — used to stop same-name defs keeping each other alive
+// (fix #243). 'state' and 'field' stay OUT: `helper = other.helper` and
+// Java `int helper = Other.helper();` genuinely reference the name.
+const DEF_NAME_LINE_KINDS = new Set([
+    'function', 'method', 'static', 'public', 'abstract', 'constructor',
+    'private', 'classmethod', 'property', 'setter', 'deleter', 'get', 'set',
+    'override', 'static get', 'static set', 'override get', 'override set',
+    'static override', 'static override get', 'static override set',
+    'class', 'struct', 'interface', 'trait', 'record', 'enum', 'namespace', 'impl',
+]);
+
+/**
+ * Is EVERY call site of `name` inside the body of a same-name definition?
+ * Recursion is not liveness (fix #253c): if no code outside defs of the name
+ * calls the name, the whole same-name group is unreachable from outside —
+ * `function retry() { ...retry()... }` with no external caller is dead, but
+ * the calleeIndex fast path saw a call site and skipped it. Transitively
+ * sound for the group: a same-name def called only by another same-name def
+ * is dead exactly when its caller is. findCallees already excludes
+ * self-recursion; this mirrors that rule at the deadcode pre-filter.
+ * Conservative on any uncertainty: unknown def ranges or an outside site
+ * keep the name "used".
+ */
+function nameOnlySelfRecursive(index, name) {
+    const files = index.calleeIndex && index.calleeIndex.get(name);
+    if (!files || files.size === 0) return false;
+    const defs = (index.symbols.get(name) || []).filter(d => DEF_NAME_LINE_KINDS.has(d.type));
+    if (defs.length === 0) return false;
+    const defFiles = new Set(defs.map(d => d.file));
+    for (const f of files) {
+        if (!defFiles.has(f)) return false; // call site in a def-less file — external
+    }
+    const { getCachedCalls } = require('./callers');
+    for (const f of files) {
+        let calls;
+        try { calls = getCachedCalls(index, f); } catch { return false; }
+        if (!calls) return false;
+        for (const call of calls) {
+            if (call.name !== name && call.resolvedName !== name &&
+                !(call.resolvedNames && call.resolvedNames.includes(name))) continue;
+            const inside = defs.some(d => d.file === f &&
+                call.line >= d.startLine && call.line <= d.endLine);
+            if (!inside) return false;
+        }
+    }
+    return true;
+}
+
 /** Check if a position in a line is inside a string literal (quotes/backticks) */
 function isInsideString(line, pos) {
     let inSingle = false, inDouble = false, inBacktick = false;
@@ -319,20 +387,41 @@ function deadcode(index, options = {}) {
         index.buildCalleeIndex();
     }
 
-    // Collect callable symbol names to reduce usage index scope
-    const callableTypes = ['function', 'method', 'static', 'public', 'abstract', 'constructor'];
+    // Collect callable symbol names to reduce usage index scope.
+    // Accessor and visibility kinds joined in fix #247 — #private methods,
+    // getters/setters, Python underscore/@property/@classmethod/@x.setter/
+    // @x.deleter members were silently unaudited in BOTH modes (no exclusion
+    // counter said so). Property accessors count reads/writes as usage: the
+    // scan totals ALL usage types, so `obj.value` keeps a getter alive.
+    const callableTypes = ['function', 'method', 'static', 'public', 'abstract', 'constructor',
+        'private', 'get', 'set', 'property', 'setter', 'deleter', 'classmethod',
+        'override', 'static get', 'static set', 'override get', 'override set',
+        'static override', 'static override get', 'static override set',
+        // Class-like kinds joined in fix #253a — unused classes/structs/
+        // interfaces were never audited in either mode.
+        ...CLASS_AUDIT_KINDS];
+    const auditTypeSet = new Set(callableTypes);
+    const classAuditSet = new Set(CLASS_AUDIT_KINDS);
     const callableNames = new Set();
     for (const [symbolName, symbols] of index.symbols) {
-        if (symbols.some(s => callableTypes.includes(s.type))) {
+        if (symbols.some(s => auditTypeSet.has(s.type))) {
             callableNames.add(symbolName);
         }
     }
 
     // Pre-filter: names in the callee index have call sites → definitely used → not dead.
+    // Exception (fix #253c): a name whose EVERY call site sits inside a
+    // same-name definition's own body is only self-recursive — recursion is
+    // not liveness. Those names fall through to the text scan, which excludes
+    // in-body references for them (selfRecursiveNames below).
     let potentiallyDeadNames = new Set();
+    const selfRecursiveNames = new Set();
     for (const name of callableNames) {
         if (!index.calleeIndex.has(name)) {
             potentiallyDeadNames.add(name);
+        } else if (nameOnlySelfRecursive(index, name)) {
+            selfRecursiveNames.add(name);
+            potentiallyDeadNames.add(name);
         }
     }
 
@@ -364,11 +453,113 @@ function deadcode(index, options = {}) {
         potentiallyDeadNames = filteredNames;
     }
 
+    // Export-site line ranges per file (lazy, --include-exported only): the
+    // precise AST regions where a name's appearance is a re-statement of the
+    // export, not consumption (fix #247 — the line-prefix check missed
+    // multi-line `export { a,\n b }` blocks, so every symbol exported that
+    // way was silently absent from the audit). Ranges are identifier-pure by
+    // construction: export clauses, `export default <identifier>`, and
+    // identifier/shorthand values of module.exports/exports.* object maps —
+    // a function body inside an export assignment still counts as usage.
+    const exportRangeCache = new Map();
+    const exportSiteRanges = (filePath) => {
+        let ranges = exportRangeCache.get(filePath);
+        if (ranges) return ranges;
+        ranges = [];
+        exportRangeCache.set(filePath, ranges);
+        const fe = index.files.get(filePath);
+        if (!fe || !['javascript', 'typescript', 'tsx'].includes(fe.language)) return ranges;
+        let content;
+        try { content = index._readFile(filePath); } catch { return ranges; }
+        const tree = index._getParsedTree(filePath, content, fe.language);
+        if (!tree) return ranges;
+        const push = (node) => ranges.push([node.startPosition.row + 1, node.endPosition.row + 1]);
+        // A re-statement is filterable only when consumers reach the symbol
+        // under ITS OWN NAME (text-visible elsewhere). Renaming surfaces are
+        // consumption wiring, never filtered: `export { x as y }` (consumers
+        // use y), `module.exports = x` and `export default x` (consumers
+        // rename at require/import) — the eval measured all three as
+        // FALSE-DEAD when filtered (express createApplication, zod
+        // instanceOfType).
+        const visit = (node) => {
+            if (node.type === 'export_statement') {
+                for (const child of node.namedChildren) {
+                    if (child.type === 'export_clause') {
+                        for (const spec of child.namedChildren) {
+                            if (spec.type !== 'export_specifier') continue;
+                            if (spec.childForFieldName('alias')) continue;
+                            push(spec);
+                        }
+                    }
+                }
+                return; // never descend into exported declarations
+            }
+            if (node.type === 'assignment_expression') {
+                const lhs = node.childForFieldName('left');
+                const rhs = node.childForFieldName('right');
+                const lhsText = lhs ? lhs.text : '';
+                const wholeModule = lhsText === 'module.exports' || lhsText === 'exports';
+                const namedExport = lhsText.startsWith('module.exports.') || lhsText.startsWith('exports.');
+                if (rhs && (wholeModule || namedExport)) {
+                    if (rhs.type === 'identifier') {
+                        if (namedExport) push(rhs); // exports.helper = helper — name-preserving
+                    } else if (rhs.type === 'object') {
+                        for (const prop of rhs.namedChildren) {
+                            if (prop.type === 'shorthand_property_identifier') push(prop);
+                            else if (prop.type === 'pair') {
+                                const v = prop.childForFieldName('value');
+                                const k = prop.childForFieldName('key');
+                                // `{ helper: helper }` filters; `{ other: helper }`
+                                // renames — consumption wiring.
+                                if (v && v.type === 'identifier' && k && k.text === v.text) push(v);
+                            }
+                        }
+                    }
+                    if (!wholeModule) return;
+                    // exports = module.exports = X chains: descend the RHS.
+                }
+            }
+            for (const child of node.namedChildren) visit(child);
+        };
+        try { visit(tree.rootNode); } catch { /* partial ranges are fine */ }
+        return ranges;
+    };
+
     // Build usage index for potentially dead names using text scan (no tree-sitter reparsing).
     // The callee index already covers all call-based usages. For remaining names, a word-boundary
     // text scan catches imports, exports, shorthand properties, type refs, and variable refs.
     // Trade-off: may match names in comments/strings (false "used" → fewer dead code reports),
     // but avoids ~1.9s of tree-sitter re-parsing. buildUsageIndex() is kept for direct callers.
+    // Names owned by an ACCESSOR-kind definition (getter/setter/@property):
+    // their entire consumption form is a paren-less attribute read
+    // (`response.num_bytes_downloaded`), whose receiver is usually a local
+    // the #123/#216 dotted discipline can't resolve. Dropping those reads
+    // claimed 15 live properties dead across httpx/rich (fix #247, eval-
+    // measured) — for these names the read keeps the usage UNSCOPED
+    // (conservative: keeps every same-name symbol alive), exactly the #243
+    // decorator rule. Non-accessor names keep the strict discipline.
+    const ACCESSOR_KINDS = new Set(['property', 'setter', 'deleter', 'get', 'set',
+        'static get', 'static set', 'override get', 'override set',
+        'static override get', 'static override set']);
+    const accessorNames = new Set();
+    // Names owned by a class-kind definition (fix #253a): in PYTHON files,
+    // string-interior matches count as usage for these — PEP 484 forward
+    // references (`x: "Foo"`, `Optional["Foo"]`) are real type references
+    // the type checker resolves; skipping them claimed live classes dead.
+    // Conservative direction only (docstring mentions also keep the class
+    // alive). Other languages keep the string skip: their in-string names
+    // are reflection (a documented limitation), not a language feature.
+    const classKindNames = new Set();
+    for (const name of potentiallyDeadNames) {
+        const defs = index.symbols.get(name) || [];
+        if (defs.some(s => ACCESSOR_KINDS.has(s.type))) {
+            accessorNames.add(name);
+        }
+        if (defs.some(s => classAuditSet.has(s.type))) {
+            classKindNames.add(name);
+        }
+    }
+
     const usageIndex = new Map();
     if (potentiallyDeadNames.size > 0) {
         for (const [filePath, fileEntry] of index.files) {
@@ -390,7 +581,11 @@ function deadcode(index, options = {}) {
                     if (present) namesInFile.push(name);
                 }
                 if (namesInFile.length === 0) continue;
-                const lines = content.split('\n');
+                // Block-comment interiors masked to spaces (fix #253d): the
+                // per-line skip below only handles // and # comments, so a
+                // name inside /* ... */ counted as usage — commented-out code
+                // silently kept its symbols "alive" and hid true dead claims.
+                const lines = maskBlockComments(content, fileEntry.language).split('\n');
                 for (const name of namesInFile) {
                     const nameLen = name.length;
                     for (let i = 0; i < lines.length; i++) {
@@ -413,8 +608,11 @@ function deadcode(index, options = {}) {
                             // Skip if inside a # comment (Python — # preceded by whitespace or at start)
                             if (hashIdx !== -1 && hashIdx < pos &&
                                 (hashIdx === 0 || /\s/.test(line[hashIdx - 1]))) continue;
-                            // Skip if inside a string literal
-                            if (isInsideString(line, pos)) continue;
+                            // Skip if inside a string literal — EXCEPT class-
+                            // kind names in Python (fix #253a): `x: "Foo"`
+                            // forward references are real type references.
+                            if (isInsideString(line, pos) &&
+                                !(fileEntry.language === 'python' && classKindNames.has(name))) continue;
                             // Property/field access (preceded by '.'), not a
                             // call: resolve the RECEIVER (fix #216, express-
                             // measured false-dead — `app.all(route, user.load)`
@@ -431,10 +629,29 @@ function deadcode(index, options = {}) {
                             let dottedScope;
                             if (pos > 0 && line[pos - 1] === '.' &&
                                 (pos + nameLen >= line.length || line[pos + nameLen] !== '(')) {
+                                // Bare dotted DECORATOR application (@bus.subscribe,
+                                // @a.b.helper) executes at import time — always a
+                                // usage, whatever the receiver is (fix #243,
+                                // FALSE-DEAD: deleting @bus.subscribe's subscribe
+                                // breaks the module at import; the receiver `bus`
+                                // is a local instance, not an import binding).
+                                const before = line.slice(0, pos);
+                                const atIdx = before.lastIndexOf('@');
+                                const isDecoratorRef = atIdx !== -1 &&
+                                    /^[\w$.]*$/.test(before.slice(atIdx + 1)) &&
+                                    before.slice(0, atIdx).trim() === '';
                                 let r = pos - 2;
                                 while (r >= 0 && /[\w$]/.test(line[r])) r--;
                                 const receiver = line.slice(r + 1, pos - 1);
-                                if (!receiver) continue;
+                                // A CHAINED receiver (`z.string().email().isEmail`)
+                                // extracts as empty — for accessor-kind names
+                                // that read is still the consumption form, so
+                                // the #247 unscoped fallback below must get
+                                // its chance (zod-measured false-dead: eight
+                                // v3 getters whose only references are
+                                // chained reads; the empty-receiver drop
+                                // fired before the accessor exemption).
+                                if (!receiver && !isDecoratorRef && !accessorNames.has(name)) continue;
                                 if (['this', 'self', 'cls'].includes(receiver)) {
                                     dottedScope = 'same-file';
                                 } else {
@@ -442,14 +659,37 @@ function deadcode(index, options = {}) {
                                         .find(b => b.name === receiver);
                                     const resolved = binding && fileEntry.moduleResolved &&
                                         fileEntry.moduleResolved[binding.module];
-                                    if (!resolved) continue;
-                                    dottedScope = resolved;
+                                    if (resolved) {
+                                        dottedScope = resolved;
+                                    } else if (!isDecoratorRef && !accessorNames.has(name)) {
+                                        continue;
+                                    }
+                                    // decorator with unresolvable receiver, or
+                                    // an attribute read of an ACCESSOR-kind
+                                    // name (fix #247 — the read IS how
+                                    // getters/properties are consumed): keep
+                                    // the usage UNSCOPED (conservative —
+                                    // keeps every same-name symbol alive)
                                 }
                             }
-                            // Skip object literal key: name followed by ':' (not '::' for Rust paths)
+                            // Skip object literal key: name followed by ':' (not '::' for Rust paths).
+                            // A DOTTED access is never a literal key — object keys are bare
+                            // (fix #247, eval-measured: Python's block colon made
+                            // `if merge_url.is_relative_url:` read as a key, dropping the
+                            // property's only consumption).
+                            // Python is exempt entirely (fix #253a): it has NO
+                            // bare-identifier-key syntax where the name is not
+                            // an expression — dict keys are expressions, and
+                            // `except Foo:` / `-> Foo:` / `while Foo:` are all
+                            // real usages the skip was dropping. `case Foo:`
+                            // (switch/match) is likewise an expression usage in
+                            // every language.
                             const afterChar = pos + nameLen < line.length ? line[pos + nameLen] : '';
                             const afterChar2 = pos + nameLen + 1 < line.length ? line[pos + nameLen + 1] : '';
-                            if (afterChar === ':' && afterChar2 !== ':') continue;
+                            if (afterChar === ':' && afterChar2 !== ':' &&
+                                fileEntry.language !== 'python' &&
+                                !(pos > 0 && line[pos - 1] === '.') &&
+                                !/(^|[^\w$])case\s+$/.test(line.slice(0, pos))) continue;
                             // Valid reference found
                             if (!usageIndex.has(name)) usageIndex.set(name, []);
                             usageIndex.get(name).push({
@@ -467,9 +707,47 @@ function deadcode(index, options = {}) {
     }
 
     for (const [name, symbols] of index.symbols) {
+        // Definition NAME lines of same-name def-kind symbols are
+        // declarations, not usages — two never-called same-name methods used
+        // to keep each other alive (fix #243: three unreferenced `delete`
+        // methods invisible). nameLine only (never a decorated def's
+        // startLine — a `@helper` decorator line IS a usage of the name).
+        let sameNameDefLines = null;
+        const defNameLines = () => {
+            if (sameNameDefLines) return sameNameDefLines;
+            sameNameDefLines = new Map();
+            for (const other of symbols) {
+                if (!DEF_NAME_LINE_KINDS.has(other.type)) continue;
+                const ln = other.nameLine ?? other.startLine;
+                if (ln == null) continue;
+                let set = sameNameDefLines.get(other.file);
+                if (!set) { set = new Set(); sameNameDefLines.set(other.file, set); }
+                set.add(ln);
+            }
+            return sameNameDefLines;
+        };
+
+        // Same-name definition BODY ranges — consulted only for names the
+        // self-recursion carve-out (fix #253c) admitted: for those, a usage
+        // inside a same-name def's own body is the recursion itself, never
+        // outside liveness. Scoped to carve-out names so a sibling-method
+        // call (`self.f()` from another method) keeps counting elsewhere.
+        let sameNameDefRanges = null;
+        const defRanges = () => {
+            if (sameNameDefRanges) return sameNameDefRanges;
+            sameNameDefRanges = new Map();
+            for (const other of symbols) {
+                if (!DEF_NAME_LINE_KINDS.has(other.type)) continue;
+                let arr = sameNameDefRanges.get(other.file);
+                if (!arr) { arr = []; sameNameDefRanges.set(other.file, arr); }
+                arr.push([other.startLine, other.endLine]);
+            }
+            return sameNameDefRanges;
+        };
+
         for (const symbol of symbols) {
-            // Skip non-function/class types (callableTypes defined above)
-            if (!callableTypes.includes(symbol.type)) {
+            // Skip non-audited types (callableTypes defined above)
+            if (!auditTypeSet.has(symbol.type)) {
                 continue;
             }
 
@@ -527,9 +805,40 @@ function deadcode(index, options = {}) {
             }
 
             // Fast path: name has call sites in callee index → definitely used → not dead
-            if (index.calleeIndex.has(name)) {
+            // (unless every site is the name's own recursion — fix #253c).
+            if (index.calleeIndex.has(name) && !selfRecursiveNames.has(name)) {
                 continue;
             }
+            // Constructor members are invoked through the CLASS name
+            // (fix #239, G2-js-measured: `new Widget()` indexes under
+            // 'Widget' — the member lookup claimed every instantiated
+            // class's constructor dead).
+            if (symbol.className &&
+                (symbol.type === 'constructor' || name === 'constructor' || name === '__init__') &&
+                index.calleeIndex.has(symbol.className) &&
+                !selfRecursiveNames.has(symbol.className)) {
+                continue;
+            }
+
+            // Class-kind claims (fix #253a): a class whose member the runtime
+            // or a framework invokes is live with zero textual references of
+            // the class NAME — `class Main { public static void main }`,
+            // a class with @app.route methods. Deleting the class deletes the
+            // entry point. Framework-registered members follow the same
+            // --include-decorated reveal as directly decorated symbols.
+            if (classAuditSet.has(symbol.type)) {
+                const members = (fileEntry?.symbols || []).filter(s =>
+                    s !== symbol && s.className === name);
+                if (members.some(m => langModule.isEntryPoint?.(m))) {
+                    continue;
+                }
+                if (members.some(m => isFrameworkEntrypoint(m, index))) {
+                    if (!options.includeDecorated) {
+                        excludedDecorated++;
+                        continue;
+                    }
+                }
+            }
 
             // Slow path: check AST-based usage index for remaining names
             const allUsages = usageIndex.get(name) || [];
@@ -542,30 +851,36 @@ function deadcode(index, options = {}) {
             // unrelated module's same-name symbol.
             let nonDefUsages = allUsages.filter(u =>
                 !(u.file === symbol.file && (u.line === symbol.startLine || u.line === symbol.nameLine)) &&
+                !(defNameLines().get(u.file)?.has(u.line)) &&
+                // Self-recursion carve-out names (fix #253c): a reference
+                // inside a same-name def's own body is the recursion itself.
+                !(selfRecursiveNames.has(name) &&
+                    lineInRanges(u.line, defRanges().get(u.file) || [])) &&
                 (!u.dottedScope ||
                     (u.dottedScope === 'same-file'
                         ? u.file === symbol.file
-                        : u.dottedScope === symbol.relativePath))
+                        // Directory-scoped packages (Go): the import binds the
+                        // package DIRECTORY, so the resolved module file may
+                        // be any sibling of the symbol's file (fix #253,
+                        // grpc-go-measured false-dead: the only usages of
+                        // `internal.EnforceSubConnEmbedding` resolved to a
+                        // sibling of internal/internal.go and were dropped).
+                        : (u.dottedScope === symbol.relativePath ||
+                            (langTraits(lang)?.packageScope === 'directory' &&
+                                pathDirname(u.dottedScope) === pathDirname(symbol.relativePath)))))
             );
 
             // For exported symbols in --include-exported mode, also filter out export-site
             // references (e.g., `module.exports = { helperC }` or `export { helperC }`).
             // These are just re-statements of the export, not actual consumption.
+            // AST ranges, not line prefixes (fix #247): a multi-line
+            // `export { a,\n b }` block's continuation lines counted as
+            // consumption, silently hiding every symbol exported that way.
             if (isExported && options.includeExported) {
                 nonDefUsages = nonDefUsages.filter(u => {
                     if (u.file !== symbol.file) return true; // cross-file usage always counts
-                    // Check if same-file usage is on an export line
-                    let content;
-                    try { content = index._readFile(u.file); } catch { return true; }
-                    if (!content) return true;
-                    const lines = content.split('\n');
-                    const line = lines[u.line - 1] || '';
-                    const trimmed = line.trim();
-                    // CJS: module.exports = { ... } or exports.name = ...
-                    if (trimmed.startsWith('module.exports') || /^exports\.\w+\s*=/.test(trimmed)) return false;
-                    // ESM: export { ... } or export default
-                    if (/^export\s*\{/.test(trimmed) || /^export\s+default\s/.test(trimmed)) return false;
-                    return true;
+                    const ranges = exportSiteRanges(u.file);
+                    return !lineInRanges(u.line, ranges);
                 });
             }
 
@@ -578,7 +893,14 @@ function deadcode(index, options = {}) {
                 // fix #210). A zero usage count is not evidence of deadness.
                 // Hidden by default; revealed under --include-exported, since
                 // it is external-reachable surface, not internal dead code.
-                const isExternalContract = overridesOutOfTreeBase(index, symbol);
+                // Class-kind claims (fix #253a) get the same shield when the
+                // class itself EXTENDS an unresolved base: frameworks discover
+                // such subclasses non-textually (django `Command(BaseCommand)`
+                // by module path, pytest plugins by registration) — zero
+                // in-project references is not evidence of deadness there.
+                const isExternalContract = classAuditSet.has(symbol.type)
+                    ? _classDefHasExternalBase(index, symbol, lang)
+                    : overridesOutOfTreeBase(index, symbol);
                 if (isExternalContract && !options.includeExported) {
                     excludedExternalContract++;
                     continue;
@@ -621,8 +943,14 @@ function deadcode(index, options = {}) {
                     file: symbol.relativePath,
                     startLine: symbol.startLine,
                     endLine: symbol.endLine,
+                    // Two dead constructors in one file rendered identically
+                    // without their class (fix #247).
+                    ...(symbol.className && { className: symbol.className }),
                     isExported,
                     usageCount: 0,
+                    // The name's only references are its own recursion
+                    // (fix #253c) — say so, the reader will see call sites.
+                    ...(selfRecursiveNames.has(name) && { selfRecursive: true }),
                     ...(decorators.length > 0 && { decorators }),
                     ...(annotations.length > 0 && { annotations }),
                     ...(declaredOn && { declaredOn }),
@@ -634,7 +962,7 @@ function deadcode(index, options = {}) {
 
     // Sort by file then line
     results.sort((a, b) => {
-        if (a.file !== b.file) return a.file.localeCompare(b.file);
+        if (a.file !== b.file) return codeUnitCompare(a.file, b.file);
         return a.startLine - b.startLine;
     });
 
@@ -647,4 +975,4 @@ function deadcode(index, options = {}) {
     } finally { index._endOp(); }
 }
 
-module.exports = { buildUsageIndex, deadcode };
+module.exports = { buildUsageIndex, deadcode, nameOnlySelfRecursive, DEF_NAME_LINE_KINDS };