ucn 5.4.1 → 5.5.0

package/core/deadcode.js

@@ -13,7 +13,9 @@ const { isTestFile } = require('./discovery');
 const { isFrameworkEntrypoint } = require('./entrypoints');
 const { splitParentList } = require('./graph-build');
 const { isOverrideMarked, codeUnitCompare, lineInRanges, maskBlockComments, escapeRegExp } = require('./shared');
-const { projectComputedDispatch, reflectionSites } = require('./ast-analysis');
+const { projectComputedDispatch, projectReflectionSites } = require('./ast-analysis');
+const { reflectionPatternReferences } = require('./reflection');
+const { protocolMemberOf, protocolTypeOf, typedLiteralContract } = require('./contract-membership');
 
 const _CLASS_KINDS = ['class', 'struct', 'interface', 'trait', 'record'];
 
@@ -215,12 +217,27 @@ function overridesOutOfTreeBase(index, symbol) {
         if (owners.length <= 1) return true;
     }
     const mods = symbol.modifiers || [];
-    const publicByShape = !mods.includes('private') &&
-        !symbol.name.startsWith('#') && !symbol.name.startsWith('_');
+    // Language-private spellings (`#x`, Python `__x`) never override a base
+    // member; a leading `_` is only a convention in languages that say so
+    // (fix #397: Node stream `_transform` hooks).
+    const privateName = langTraits(index.files.get(symbol.file)?.language)?.privateMemberName;
+    const publicByShape = !mods.includes('private') && !symbol.name.startsWith('#') &&
+        (typeof privateName === 'function' ? !privateName(symbol.name) : !symbol.name.startsWith('_'));
     if (publicByShape && _classHasExternalBase(index, symbol)) return true;
     return false;
 }
 
+/**
+ * A member of an object literal declared with an out-of-project type
+ * (`const traps: ProxyHandler<T> = { get() {} }`, fix #397): the type's
+ * consumer (the runtime, a library) calls it by name, so a zero in-project
+ * usage count is not evidence of deadness.
+ */
+function typedLiteralExternalMember(index, symbol) {
+    if (!symbol.registryContainerType || symbol.className) return false;
+    return !!typedLiteralContract(index, symbol)?.external;
+}
+
 // Go satisfies interfaces implicitly, so no `implements` edge exists for
 // compiler/stdlib callbacks. A zero textual usage for one of these exact
 // method shapes is not evidence of deadness (sort.Interface, http.Handler,
@@ -626,6 +643,15 @@ function symbolIsExported(index, symbol, fileEntry) {
     if (fileEntry.exports.includes(name) || mods.includes('export') || mods.includes('public')) {
         return true;
     }
+    // fix #379: a C++ member that follows a macro invocation whose access
+    // effect the parser could not read (the macro is defined in another
+    // file) takes the access its project definitions spell; an external or
+    // configuration-dependent macro leaves it unknown, and an unknown-access
+    // member is treated as public API.
+    if (symbol.accessAfterMacro && symbol.className) {
+        const access = memberAccessAfterMacro(index, symbol.accessAfterMacro);
+        if (access === null || access === 'public') return true;
+    }
     const traits = langTraits(fileEntry.language);
     // Python's language-level public surface is every top-level non-underscore
     // name when __all__ is absent. Apply the same rule here as `api`: deadcode
@@ -645,6 +671,22 @@ function symbolIsExported(index, symbol, fileEntry) {
     if (traits?.exportVisibility === 'capitalization') {
         return /^[A-Z]/.test(name);
     }
+    // fix #367f: members of an interface/trait carry the container's
+    // visibility (Rust trait items cannot be marked `pub`; Java and C#
+    // interface members are implicitly public), so the members of an
+    // exported interface/trait are public API exactly as `api` lists them.
+    if (symbol.className && !mods.includes('private')) {
+        const container = (index.symbols.get(symbol.className) || []).find(c =>
+            c.file === symbol.file && (c.type === 'interface' || c.type === 'trait') &&
+            c.startLine <= symbol.startLine && symbol.startLine <= (c.endLine ?? c.startLine));
+        if (container) {
+            const cmods = container.modifiers || [];
+            if (fileEntry.exports.includes(container.name) || cmods.includes('export') ||
+                cmods.includes('public') || cmods.includes('pub')) {
+                return true;
+            }
+        }
+    }
     if (traits?.implicitlyPublicMembers && symbol.className &&
         !mods.includes('private') && !name.startsWith('#') && !name.startsWith('_')) {
         const classSyms = index.symbols.get(symbol.className) || [];
@@ -661,6 +703,21 @@ function symbolIsExported(index, symbol, fileEntry) {
     return false;
 }
 
+/**
+ * Access in effect after `macro` for a member whose lexical access before the
+ * invocation was `before`: the last access specifier every project
+ * definition of the macro spells (or `before` when none spells one). Null
+ * when the macro has no readable project definition or its definitions
+ * disagree.
+ */
+function memberAccessAfterMacro(index, { macro, before } = {}) {
+    const { macroAccessEffect } = require('../languages/c-family');
+    const definitions = (index.symbols.get(macro) || []).filter(d => d.type === 'macro');
+    if (definitions.length === 0 || definitions.some(d => typeof d.ppBody !== 'string')) return null;
+    const effects = new Set(definitions.map(d => macroAccessEffect(d.ppBody) || before || null));
+    return effects.size === 1 ? [...effects][0] : null;
+}
+
 function isPythonPackageFile(index, fileEntry) {
     if (fileEntry?.language !== 'python' || !fileEntry.relativePath) return false;
     let dir = path.dirname(path.join(index.root, fileEntry.relativePath));
@@ -674,40 +731,6 @@ function isPythonPackageFile(index, fileEntry) {
     return false;
 }
 
-const JAVA_SERIALIZATION_CALLBACKS = new Set([
-    'readResolve', 'writeReplace', 'readObject', 'writeObject',
-    'readObjectNoData',
-]);
-
-/**
- * Java serialization invokes these callbacks reflectively, so there is no
- * text call edge. Require a Serializable/Externalizable heritage path before
- * suppressing a dead-code claim; name alone is not enough.
- */
-function isJavaSerializationCallback(index, symbol, fileEntry) {
-    if (fileEntry?.language !== 'java' || !symbol.className ||
-        !JAVA_SERIALIZATION_CALLBACKS.has(symbol.name)) return false;
-    const head = value => String(value || '')
-        .replace(/<.*$/, '').split(/[.$]/).pop().trim();
-    const seen = new Set();
-    const serializable = className => {
-        const normalized = head(className);
-        if (!normalized || seen.has(normalized)) return false;
-        if (normalized === 'Serializable' || normalized === 'Externalizable') return true;
-        seen.add(normalized);
-        const defs = (index.symbols.get(normalized) || []).filter(candidate =>
-            ['class', 'interface', 'record', 'enum'].includes(candidate.type));
-        return defs.some(definition => {
-            const implemented = Array.isArray(definition.implements)
-                ? definition.implements : String(definition.implements || '').split(',');
-            const parents = [definition.extends, ...implemented]
-                .filter(Boolean).map(head);
-            return parents.some(serializable);
-        });
-    };
-    return serializable(symbol.className);
-}
-
 /**
  * Find dead code (unused functions/classes)
  * @param {object} index - ProjectIndex instance
@@ -742,29 +765,48 @@ function deadcode(index, options = {}) {
     const reflectionInfo = {
         count: 0,
         literalCount: 0,
+        patternCount: 0,
         dynamicCount: 0,
         fileCount: 0,
         files: [],
         names: [],
+        patterns: [],
+        withheld: 0,
+        withheldByPattern: [],
     };
-    for (const [reflectionFile, fe] of index.files) {
+    // Reflection is liveness evidence wherever it sits (a test or script
+    // outside --in still reaches the member); the disclosure counts cover the
+    // audited scope.
+    const reflectionPatterns = new Set();
+    for (const [reflectionFile, sites] of projectReflectionSites(index)) {
+        const fe = index.files.get(reflectionFile);
+        if (!fe || sites.length === 0) continue;
+        for (const site of sites) {
+            if (site.name) literalReflectionNames.add(site.name);
+            if (site.patterns && site.patterns.length > 0 && !site.name) {
+                // Exact alternatives of a multi-spelling site are literals.
+                for (const pattern of site.patterns) {
+                    if (!pattern.includes('*')) literalReflectionNames.add(pattern);
+                }
+            }
+        }
         if (!index.matchesFilters(fe.relativePath, options)) continue;
-        let sites = [];
-        try {
-            sites = reflectionSites(index._readFile(reflectionFile), fe.language);
-        } catch { /* coverage diagnostics own unreadable-file reporting */ }
-        if (sites.length === 0) continue;
         reflectionInfo.count += sites.length;
-        reflectionInfo.literalCount += sites.filter(site => !site.dynamic).length;
-        reflectionInfo.dynamicCount += sites.filter(site => site.dynamic).length;
+        for (const site of sites) {
+            if (site.name) reflectionInfo.literalCount++;
+            else if (site.patterns && site.patterns.length > 0) reflectionInfo.patternCount++;
+            if (site.dynamic) reflectionInfo.dynamicCount++;
+            for (const pattern of site.patterns || []) {
+                if (pattern.includes('*')) reflectionPatterns.add(pattern);
+            }
+        }
         reflectionInfo.fileCount++;
         if (reflectionInfo.files.length < 10) {
             reflectionInfo.files.push(fe.relativePath);
         }
-        for (const site of sites) {
-            if (site.name) literalReflectionNames.add(site.name);
-        }
     }
+    reflectionInfo.patterns = [...reflectionPatterns].sort(codeUnitCompare);
+    const reflectionWithheldByPattern = new Map();
     reflectionInfo.names = [...literalReflectionNames].sort(codeUnitCompare);
 
     // Ensure callee index is built (lazy, reused across operations)
@@ -845,10 +887,48 @@ function deadcode(index, options = {}) {
         potentiallyDeadNames.delete(reflectedName);
     }
 
+    // C/C++ token-pasting macros (fix #362): names an expanded invocation
+    // produces in value position (`{ #name, handle_##name }` tables) are
+    // uses. A paste pattern whose produced names cannot be enumerated (a
+    // pasting macro with a blind invocation, or one never seen expanded)
+    // withholds every candidate the pattern could spell.
+    const macroPaste = { sites: 0, blind: null, withheld: 0, withheldNames: [], patterns: 0 };
+    const macroSuppressedNames = new Set();
+    if ([...index.files.values()].some(fe => langTraits(fe.language)?.textualIncludes)) {
+        const { macroExpansionSummary } = require('./macro-expansion');
+        const { matchesPastePattern } = require('../languages/c-preprocessor');
+        const summary = macroExpansionSummary(index);
+        macroPaste.sites = summary.sites;
+        macroPaste.blind = summary.blind;
+        for (const name of summary.refNames) {
+            potentiallyDeadNames.delete(name);
+            macroSuppressedNames.add(name);
+        }
+        const patterns = summary.patterns.filter(p => p.pattern.some(piece => piece && piece.length > 0));
+        macroPaste.patterns = patterns.length;
+        if (patterns.length > 0) {
+            for (const name of [...potentiallyDeadNames].sort(codeUnitCompare)) {
+                const cFamily = (index.symbols.get(name) || []).some(def =>
+                    langTraits(index.files.get(def.file)?.language)?.textualIncludes);
+                if (!cFamily) continue;
+                const pattern = patterns.find(p => matchesPastePattern(p.pattern, name));
+                if (!pattern) continue;
+                potentiallyDeadNames.delete(name);
+                macroSuppressedNames.add(name);
+                macroPaste.withheld++;
+                if (macroPaste.withheldNames.length < 10) {
+                    macroPaste.withheldNames.push({ name, macro: pattern.macro,
+                        file: pattern.file, line: pattern.line });
+                }
+            }
+        }
+    }
+
     const coverage = scanDeadcodeCoverage(index, potentiallyDeadNames);
     const coverageSuppressedNames = new Set([
         ...coverage.matchedNames,
         ...literalReflectionNames,
+        ...macroSuppressedNames,
     ]);
     if (coverage.claimsWithdrawn) {
         // An unreadable file/directory can contain a use of any candidate.
@@ -1205,6 +1285,12 @@ function deadcode(index, options = {}) {
             if (symbol.bodyScopedName) {
                 continue;
             }
+            // Generated by a project macro_rules! invocation (fix #374): the
+            // definition is the macro's template or the invocation's
+            // arguments, never a deletable declaration of its own.
+            if (symbol.macroExpansion) {
+                continue;
+            }
             const fileEntry = index.files.get(symbol.file);
             const lang = fileEntry?.language;
 
@@ -1267,7 +1353,11 @@ function deadcode(index, options = {}) {
             if (langModule.isEntryPoint?.(symbol)) {
                 continue;
             }
-            if (isJavaSerializationCallback(index, symbol, fileEntry)) {
+            // Members the runtime/compiler invokes by name (trait
+            // languageProtocolMember): Java serialization callbacks on
+            // Serializable types, Python Enum hooks on Enum subclasses, C#
+            // pattern-bound members, JS toJSON/then/[Symbol.*] (fix #363).
+            if (protocolMemberOf(index, symbol) || protocolTypeOf(index, symbol)) {
                 excludedRuntimeContract++;
                 continue;
             }
@@ -1422,6 +1512,7 @@ function deadcode(index, options = {}) {
                 const isExternalContract = classAuditSet.has(symbol.type)
                     ? _heritageReachesExternalBase(index, symbol, lang, false)
                     : overridesOutOfTreeBase(index, symbol) ||
+                        typedLiteralExternalMember(index, symbol) ||
                         (lang === 'go' && goImplicitExternalContract(symbol));
                 if (isExternalContract && !options.includeExported) {
                     excludedExternalContract++;
@@ -1472,6 +1563,22 @@ function deadcode(index, options = {}) {
                     continue;
                 }
 
+                // Reflection by name pattern (fix #363): a reflective access
+                // whose name is built from literal fragments around a runtime
+                // part (`getattr(self, "_get_%s_permissions" % src)`) can
+                // reach every member the pattern spells on a receiver that may
+                // hold this class. That is a runtime use, not deadness.
+                const reflected = reflectionPatternReferences(index, symbol);
+                if (reflected.length > 0) {
+                    const first = reflected[0];
+                    const pattern = first.site.receiver?.kind === 'module'
+                        ? `${first.pattern}\u0000${first.relativePath}` : first.pattern;
+                    reflectionWithheldByPattern.set(pattern,
+                        (reflectionWithheldByPattern.get(pattern) || 0) + 1);
+                    reflectionInfo.withheld++;
+                    continue;
+                }
+
                 results.push({
                     name: symbol.name,
                     type: symbol.type,
@@ -1508,7 +1615,22 @@ function deadcode(index, options = {}) {
     results.excludedRuntimeContract = excludedRuntimeContract;
     results.excludedDynamicDispatch = excludedDynamicDispatch;
     results.computedDispatch = computedDispatchInfo;
+    reflectionInfo.withheldByPattern = [...reflectionWithheldByPattern]
+        .map(([key, count]) => {
+            const [pattern, namespaceOf] = key.split('\u0000');
+            return { pattern, count, ...(namespaceOf && { namespaceOf }) };
+        })
+        .sort((a, b) => b.count - a.count || codeUnitCompare(a.pattern, b.pattern));
     results.reflection = reflectionInfo;
+    if (macroPaste.sites > 0 || macroPaste.blind?.count > 0 || macroPaste.withheld > 0) {
+        results.macroPaste = macroPaste;
+    }
+    // Project macro_rules! invocations that could not be expanded (fix #374).
+    if ([...index.files.values()].some(fe => fe.rustMacroExpansion?.blind)) {
+        const { rustMacroExpansionSummary } = require('./rust-macro-expansion');
+        const summary = rustMacroExpansionSummary(index);
+        if (summary.blind.count > 0) results.macroRulesBlind = summary.blind;
+    }
     results.coverage = {
         complete: coverage.complete,
         claimsWithdrawn: coverage.claimsWithdrawn,

package/core/decorator-binding.js

@@ -0,0 +1,260 @@
+/**
+ * core/decorator-binding.js - Decorators that may bind a callable by its name
+ * (fix #392).
+ *
+ * Where a decorator replaces the callable (`decoratorsWrapCallables`: Python,
+ * JS/TS), it receives the function object, and with it the function's NAME:
+ * a pytest fixture is requested by it, a click command and a Flask endpoint
+ * are named after it, a registry may key on `fn.__name__`, a TS member
+ * decorator receives the property key. Renaming the definition and its
+ * references is then not the whole rename. A decorator is known to keep the
+ * name out of it when:
+ *   - it resolves (through the file's import bindings or builtins) to one of
+ *     the language's name-preserving decorators (trait `callableDecorators`:
+ *     `transparent`, `asyncContextManagers`, `namePreserving`);
+ *   - it is the member's own property accessor (`@size.setter` on `size`);
+ *   - it resolves to a project function whose decorated-callable parameter is
+ *     only called, returned, passed to `functools.wraps`/`update_wrapper`, or
+ *     tested with `callable`/`isinstance` (Python), or whose name/context
+ *     parameters are never read (JS/TS); a decorator factory `@f(args)` is
+ *     proven through the decorator it returns.
+ * Any other decorator is reported, so the plan asks for review.
+ */
+
+'use strict';
+
+const { langTraits, getParser, safeParse } = require('../languages');
+const { sameNode, traverseTree } = require('../languages/utils');
+const { resolveDecorator } = require('./async-producers');
+
+function namedChildrenOf(node) {
+    return node ? node.namedChildren || [] : [];
+}
+
+function treeOf(index, filePath) {
+    const entry = index.files.get(filePath);
+    if (!entry) return null;
+    let content;
+    try { content = index._readFile(filePath); } catch { return null; }
+    const tree = index._getParsedTree?.(filePath, content, entry.language);
+    if (tree) return tree;
+    const parser = getParser(entry.language);
+    return parser ? safeParse(parser, content) : null;
+}
+
+/** The function node declared at `line` (1-based) with `name`. */
+function functionNodeAt(tree, line, name) {
+    let found = null;
+    const row = line - 1;
+    traverseTree(tree.rootNode, node => {
+        if (found) return false;
+        if (node.endPosition.row < row || node.startPosition.row > row) return false;
+        const nameNode = node.childForFieldName?.('name');
+        if (nameNode && nameNode.text === name && nameNode.startPosition.row === row &&
+            /function|method|arrow/.test(node.type)) {
+            found = node;
+            return false;
+        }
+        if (node.type === 'variable_declarator' && nameNode?.text === name &&
+            nameNode.startPosition.row === row) {
+            const value = node.childForFieldName('value');
+            if (value && /function|arrow/.test(value.type)) {
+                found = value;
+                return false;
+            }
+        }
+        return true;
+    });
+    return found;
+}
+
+function firstParamName(fnNode, family) {
+    const params = fnNode.childForFieldName('parameters') || fnNode.childForFieldName('parameter');
+    if (!params) return null;
+    if (params.type === 'identifier') return params.text;
+    for (const param of namedChildrenOf(params)) {
+        if (param.type === 'identifier') return param.text;
+        const nameNode = param.childForFieldName?.('name') || param.childForFieldName?.('pattern');
+        if (nameNode?.type === 'identifier') return nameNode.text;
+        if (family === 'python' && param.type === 'typed_parameter' &&
+            param.namedChild(0)?.type === 'identifier') return param.namedChild(0).text;
+        return null;
+    }
+    return null;
+}
+
+function paramNames(fnNode) {
+    const params = fnNode.childForFieldName('parameters') || fnNode.childForFieldName('parameter');
+    if (!params) return [];
+    if (params.type === 'identifier') return [params.text];
+    const names = [];
+    for (const param of namedChildrenOf(params)) {
+        if (param.type === 'identifier') { names.push(param.text); continue; }
+        const nameNode = param.childForFieldName?.('name') || param.childForFieldName?.('pattern');
+        names.push(nameNode?.type === 'identifier' ? nameNode.text : null);
+    }
+    return names;
+}
+
+/**
+ * Python: the decorated-callable parameter `p` of decorator `fnNode` is only
+ * called, returned, passed to functools.wraps/update_wrapper, or tested.
+ */
+function pythonParamKeepsName(fnNode, p, resolveName) {
+    const body = fnNode.childForFieldName('body');
+    if (!body) return false;
+    let proven = true;
+    traverseTree(body, node => {
+        if (!proven) return false;
+        if (node.type !== 'identifier' || node.text !== p) return true;
+        const parent = node.parent;
+        if (!parent) { proven = false; return false; }
+        // `return p`
+        if (parent.type === 'return_statement') return true;
+        // `p(...)`
+        if (parent.type === 'call' && sameNode(parent.childForFieldName('function'), node)) return true;
+        // `wraps(p)`, `update_wrapper(w, p)`, `callable(p)`, `isinstance(p, T)`
+        if (parent.type === 'argument_list' && parent.parent?.type === 'call') {
+            const callee = parent.parent.childForFieldName('function');
+            const key = callee ? resolveName(callee.text) : null;
+            if (key === 'functools.wraps' || key === 'functools.update_wrapper' ||
+                key === 'builtins.callable' || key === 'builtins.isinstance') return true;
+        }
+        proven = false;
+        return false;
+    });
+    return proven;
+}
+
+/** JS/TS: every parameter after the decorated value is unread. */
+function jsExtraParamsUnread(fnNode) {
+    const names = paramNames(fnNode).slice(1);
+    if (names.some(n => n === null)) return false;
+    if (names.length === 0) return true;
+    const body = fnNode.childForFieldName('body');
+    if (!body) return true;
+    let read = false;
+    traverseTree(body, node => {
+        if (read) return false;
+        if (node.type === 'identifier' && names.includes(node.text)) read = true;
+        return !read;
+    });
+    return !read;
+}
+
+/** The nested decorator a factory returns (`return inner` / `return lambda..`). */
+function returnedDecorator(fnNode, family) {
+    const body = fnNode.childForFieldName('body');
+    if (!body) return null;
+    const nested = new Map();
+    const returns = [];
+    traverseTree(body, node => {
+        if (sameNode(node, body)) return true;
+        if (/^(function_definition|function_declaration)$/.test(node.type)) {
+            const n = node.childForFieldName('name');
+            if (n) nested.set(n.text, node);
+            return false;
+        }
+        if (/function|arrow|lambda/.test(node.type)) return false;
+        if (node.type === 'variable_declarator') {
+            const n = node.childForFieldName('name');
+            const v = node.childForFieldName('value');
+            if (n && v && /function|arrow/.test(v.type)) nested.set(n.text, v);
+        }
+        if (node.type === 'return_statement') returns.push(node);
+        return true;
+    });
+    // JS arrow shorthand: `(x) => (target, key) => {}`
+    if (family === 'js' && body.type !== 'statement_block' && /function|arrow/.test(body.type)) return body;
+    if (returns.length !== 1) return null;
+    const value = returns[0].namedChild(0);
+    if (!value) return null;
+    if (value.type === 'identifier') return nested.get(value.text) || null;
+    if (/function|arrow/.test(value.type)) return value;
+    return null;
+}
+
+/**
+ * Resolve a decorator's head name to one project callable definition, or null.
+ */
+function projectDecoratorDef(index, def, head, rest) {
+    const { _nameBindingReaches, _moduleAttributeBindingReaches } = require('./callers');
+    const target = rest ? rest.slice(1) : head;
+    if (rest && rest.includes('.', 1)) return null;
+    const candidates = (index.symbols.get(target) || []).filter(candidate =>
+        !candidate.className && /function|method/.test(candidate.type || 'function'));
+    const reaching = candidates.filter(candidate => {
+        const targets = new Set([candidate.file]);
+        if (!rest) {
+            if (candidate.file === def.file) return true;
+            return _nameBindingReaches(index, def.file, head, targets) === 'yes';
+        }
+        return _moduleAttributeBindingReaches(index, def.file, head, target, targets) === 'yes';
+    });
+    return reaching.length === 1 ? reaching[0] : null;
+}
+
+function provenProjectDecorator(index, def, text, family, resolveName, memo) {
+    const call = text.indexOf('(');
+    const expr = (call >= 0 ? text.slice(0, call) : text).trim();
+    if (!/^[A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)?$/.test(expr)) return false;
+    const dot = expr.indexOf('.');
+    const head = dot < 0 ? expr : expr.slice(0, dot);
+    const rest = dot < 0 ? '' : expr.slice(dot);
+    const target = projectDecoratorDef(index, def, head, rest);
+    if (!target) return false;
+    const key = `${target.file}\0${target.startLine}\0${call >= 0 ? 1 : 0}`;
+    if (memo.has(key)) return memo.get(key);
+    memo.set(key, false); // recursion guard
+    const tree = treeOf(index, target.file);
+    let fnNode = tree ? functionNodeAt(tree, target.nameLine || target.startLine, target.name) : null;
+    if (fnNode && call >= 0) fnNode = returnedDecorator(fnNode, family);
+    let proven = false;
+    if (fnNode) {
+        if (family === 'python') {
+            const p = firstParamName(fnNode, family);
+            const targetEntry = index.files.get(target.file);
+            const vocab = langTraits(targetEntry?.language)?.callableDecorators || {};
+            const resolveInTarget = name => resolveDecorator(name, targetEntry, vocab)?.name || null;
+            proven = !!p && pythonParamKeepsName(fnNode, p, resolveInTarget);
+        } else {
+            proven = jsExtraParamsUnread(fnNode);
+        }
+    }
+    memo.set(key, proven);
+    return proven;
+}
+
+/**
+ * Decorators of `def` not proven to keep its name out of what they do.
+ * Returns [] when the language's decorators never replace the callable.
+ */
+function nameBindingDecorators(index, def, memo = new Map()) {
+    const decorators = Array.isArray(def.decorators) ? def.decorators : [];
+    if (decorators.length === 0) return [];
+    const fileEntry = index.files.get(def.file);
+    const traits = fileEntry ? langTraits(fileEntry.language) : null;
+    if (!traits?.decoratorsWrapCallables) return [];
+    const family = fileEntry.language === 'python' ? 'python' : 'js';
+    const vocab = traits.callableDecorators || {};
+    const preserving = new Set([...(vocab.transparent || []), ...(vocab.asyncContextManagers || []),
+        ...(vocab.namePreserving || [])]);
+    const resolveName = name => resolveDecorator(name, fileEntry, vocab)?.name || null;
+    const unproven = [];
+    for (const raw of decorators) {
+        const text = String(typeof raw === 'string' ? raw : raw?.name || '').replace(/^@/, '').trim();
+        if (!text) continue;
+        const resolved = resolveDecorator(text, fileEntry, vocab);
+        if (resolved) {
+            const key = resolved.name + (resolved.called ? '()' : '');
+            if (preserving.has(key) || preserving.has(resolved.name)) continue;
+        }
+        // The member's own property accessors keep its name by definition.
+        if (new RegExp(`^${def.name.replace(/[$]/g, '\\$')}\\.(setter|getter|deleter)$`).test(text)) continue;
+        if (provenProjectDecorator(index, def, text, family, resolveName, memo)) continue;
+        unproven.push(text);
+    }
+    return unproven;
+}
+
+module.exports = { nameBindingDecorators };