ucn 4.2.3 → 5.0.2

package/core/verify.js

@@ -5,9 +5,89 @@
  * as the first argument instead of using `this`.
  */
 
-const { detectLanguage, getParser, getLanguageModule, safeParse, langTraits } = require('../languages');
+const { detectLanguage, getParser, getLanguageAdapter, safeParse, langTraits } = require('../languages');
 const { escapeRegExp, codeUnitCompare } = require('./shared');
 
+function codeUnitColumnForByteColumn(line, byteColumn) {
+    if (!Number.isInteger(byteColumn) || byteColumn < 0) return null;
+    let bytes = 0;
+    for (let i = 0; i <= line.length; i++) {
+        if (bytes === byteColumn) return i;
+        if (i === line.length) break;
+        const cp = line.codePointAt(i);
+        const ch = String.fromCodePoint(cp);
+        bytes += Buffer.byteLength(ch);
+        if (ch.length === 2) i++;
+    }
+    return null;
+}
+
+/** Replace only AST identifier tokens on one source line. */
+function renameIdentifierTokens(index, filePath, lineNumber, oldName, newName,
+    preferredByteColumns = null, expectedCallCount = null) {
+    const absolute = filePath && require('path').isAbsolute(filePath)
+        ? filePath : require('path').join(index.root, filePath || '');
+    const content = index._readFile(absolute);
+    const sourceLine = content.split('\n')[lineNumber - 1] || '';
+    let byteColumns = Array.isArray(preferredByteColumns)
+        ? preferredByteColumns.filter(Number.isInteger) : [];
+
+    if (byteColumns.length === 0) {
+        const language = index.files.get(absolute)?.language ||
+            detectLanguage(absolute, index.root);
+        const parser = language && getParser(language);
+        const tree = parser && (index._getParsedTree?.(absolute, content, language) ||
+            safeParse(parser, content));
+        if (tree) {
+            const targetRow = lineNumber - 1;
+            const stack = [tree.rootNode];
+            while (stack.length > 0) {
+                const node = stack.pop();
+                if (node.endPosition.row < targetRow ||
+                    node.startPosition.row > targetRow) continue;
+                if (node.startPosition.row === targetRow && node.text === oldName &&
+                    /identifier(?:_pattern)?$/.test(node.type)) {
+                    let eligible = preferredByteColumns == null;
+                    if (!eligible) {
+                        const callTypes = new Set([
+                            'call', 'call_expression', 'method_invocation',
+                            'invocation_expression', 'method_call_expression',
+                        ]);
+                        for (let parent = node.parent, depth = 0;
+                            parent && depth < 5; parent = parent.parent, depth++) {
+                            if (!callTypes.has(parent.type)) continue;
+                            const target = parent.childForFieldName('function') ||
+                                parent.childForFieldName('name') ||
+                                parent.childForFieldName('method') ||
+                                parent.namedChild(0);
+                            if (target && node.startIndex >= target.startIndex &&
+                                node.endIndex <= target.endIndex) eligible = true;
+                            break;
+                        }
+                    }
+                    if (eligible) byteColumns.push(node.startPosition.column);
+                    continue;
+                }
+                stack.push(...(node.namedChildren || []));
+            }
+        }
+    }
+
+    const columns = [...new Set(byteColumns
+        .map(column => codeUnitColumnForByteColumn(sourceLine, column))
+        .filter(Number.isInteger))].sort((a, b) => b - a);
+    if (expectedCallCount != null && columns.length !== expectedCallCount) {
+        return { source: sourceLine.trim(), renamed: sourceLine.trim(), count: 0 };
+    }
+    let renamed = sourceLine;
+    for (const column of columns) {
+        if (renamed.slice(column, column + oldName.length) !== oldName) continue;
+        renamed = renamed.slice(0, column) + newName +
+            renamed.slice(column + oldName.length);
+    }
+    return { source: sourceLine.trim(), renamed: renamed.trim(), count: columns.length };
+}
+
 // ============================================================================
 // CALL-SITE CLASSIFICATION (Feature A)
 // ============================================================================
@@ -169,7 +249,8 @@ function _collectCallNodes(node, callTypes, targetRow, funcName, limit, out = []
             // JS/TS constructor: new ClassName(args) — class is in 'constructor'
             // field (fix #230: these sites used to fall out as "Could not
             // parse call arguments" and every class verify went uncertain).
-            const ctorNode = node.childForFieldName('constructor');
+            const ctorNode = node.childForFieldName('constructor') ||
+                node.childForFieldName('type');
             if (ctorNode) {
                 const typeName = ctorNode.text.replace(/<.*>$/, '').split('.').pop();
                 if (typeName === funcName) out.push(node);
@@ -183,12 +264,30 @@ function _collectCallNodes(node, callTypes, targetRow, funcName, limit, out = []
                 funcNode = funcNode.childForFieldName('function') || funcNode.namedChild(0);
             }
             if (funcNode) {
-                const funcText = funcNode.type === 'member_expression' || funcNode.type === 'selector_expression' || funcNode.type === 'field_expression' || funcNode.type === 'attribute'
-                    ? (funcNode.childForFieldName('property') || funcNode.childForFieldName('field') || funcNode.childForFieldName('attribute') || funcNode.namedChild(funcNode.namedChildCount - 1))?.text
-                    : funcNode.type === 'scoped_identifier'
+                const memberProperty = funcNode.type === 'member_expression'
+                    ? funcNode.childForFieldName('property')
+                    : null;
+                const indirectKind = memberProperty &&
+                    ['call', 'apply', 'bind'].includes(memberProperty.text)
+                    ? memberProperty.text
+                    : null;
+                const indirectObject = indirectKind
+                    ? funcNode.childForFieldName('object')
+                    : null;
+                const indirectTarget = indirectObject?.type === 'member_expression'
+                    ? indirectObject.childForFieldName('property')?.text
+                    : indirectObject?.text;
+                const funcText = funcNode.type === 'member_expression' ||
+                    funcNode.type === 'member_access_expression' ||
+                    funcNode.type === 'selector_expression' ||
+                    funcNode.type === 'field_expression' || funcNode.type === 'attribute'
+                    ? (funcNode.childForFieldName('property') || funcNode.childForFieldName('name') ||
+                        funcNode.childForFieldName('field') || funcNode.childForFieldName('attribute') ||
+                        funcNode.namedChild(funcNode.namedChildCount - 1))?.text
+                    : funcNode.type === 'scoped_identifier' || funcNode.type === 'qualified_identifier'
                     ? (funcNode.childForFieldName('name') || funcNode.namedChild(funcNode.namedChildCount - 1))?.text
                     : funcNode.text;
-                if (funcText === funcName) out.push(node);
+                if (funcText === funcName || indirectTarget === funcName) out.push(node);
             }
         }
         if (out.length >= limit) return out;
@@ -474,7 +573,7 @@ function extractArrowTypesFromVarDecl(index, def) {
  * @returns {Array<Array<object>>|null}
  */
 function _constructorParamLists(index, def, lang) {
-    if (!def || !def.file || !['class', 'enum', 'record'].includes(def.type)) return null;
+    if (!def || !def.file || !['class', 'struct', 'enum', 'record'].includes(def.type)) return null;
     const lists = [];
     const endLine = def.endLine != null ? def.endLine : Infinity;
     const inRange = (d) => d.file === def.file &&
@@ -652,10 +751,13 @@ function computePlanCallSites(index, name, def) {
         const analysis = analyzeCallSite(index, call, name, occurrence);
         sites.push({
             file: call.relativePath,
+            absoluteFile: call.file,
             line: call.line,
+            ...(Number.isInteger(c.column) && { column: c.column }),
             expression: (call.content || '').trim(),
             args: analysis.args,
             argCount: analysis.argCount,
+            ...(c.calledAs && { calledAs: c.calledAs }),
         });
     }
     clearTreeCache(index);
@@ -711,7 +813,7 @@ function analyzeCallSite(index, call, funcName, occurrence = 0) {
             const content = index._readFile(call.file);
             // HTML files need special handling: parse script blocks as JS
             if (language === 'html') {
-                const htmlModule = getLanguageModule('html');
+                const htmlModule = getLanguageAdapter('html');
                 const htmlParser = getParser('html');
                 const jsParser = getParser('javascript');
                 if (!htmlParser || !jsParser) return { args: null, argCount: 0 };
@@ -731,7 +833,7 @@ function analyzeCallSite(index, call, funcName, occurrence = 0) {
 
         // Call node types vary by language
         const callTypes = new Set(['call_expression', 'call', 'method_invocation',
-            'object_creation_expression', 'new_expression']);
+            'invocation_expression', 'object_creation_expression', 'new_expression']);
         const targetRow = call.line - 1; // tree-sitter is 0-indexed
 
         // Find the call expression at the target line matching funcName
@@ -765,9 +867,56 @@ function analyzeCallSite(index, call, funcName, occurrence = 0) {
         const argsNode = callNode.childForFieldName('arguments');
         if (!argsNode) return { args: [], argCount: 0, isMethodCall, ...ctx };
 
-        const args = [];
+        let args = [];
         for (let i = 0; i < argsNode.namedChildCount; i++) {
-            args.push(argsNode.namedChild(i).text.trim());
+            const argNode = argsNode.namedChild(i);
+            if (argNode.type.includes('comment')) continue;
+            args.push(argNode.text.trim());
+        }
+
+        // Function.prototype indirection has a precise, AST-visible argument
+        // mapping. `fn.call(thisArg, a, b)` invokes fn(a, b). `fn.apply`
+        // is countable only when its argument array is a literal. `bind`
+        // creates a partially applied function rather than invoking it, so it
+        // remains explicitly uncertain instead of looking like a parser bug.
+        let indirectKind = null;
+        if (language === 'javascript' || language === 'typescript' ||
+            language === 'tsx' || language === 'html') {
+            const property = funcNode?.type === 'member_expression'
+                ? funcNode.childForFieldName('property')?.text
+                : null;
+            if (['call', 'apply', 'bind'].includes(property)) indirectKind = property;
+        }
+        if (indirectKind === 'bind') {
+            return {
+                args: null,
+                argCount: 0,
+                indirectKind,
+                uncertainReason: 'Function.bind creates a partial application; final invocation arguments are not known here',
+                isMethodCall,
+                ...ctx,
+            };
+        }
+        if (indirectKind === 'call') {
+            args = args.slice(1);
+        } else if (indirectKind === 'apply') {
+            const arrayArg = argsNode.namedChild(1);
+            if (!arrayArg || arrayArg.type !== 'array') {
+                return {
+                    args: null,
+                    argCount: 0,
+                    indirectKind,
+                    uncertainReason: 'Function.apply argument list is not a static array literal',
+                    isMethodCall,
+                    ...ctx,
+                };
+            }
+            args = [];
+            for (let i = 0; i < arrayArg.namedChildCount; i++) {
+                const argNode = arrayArg.namedChild(i);
+                if (argNode.type.includes('comment')) continue;
+                args.push(argNode.text.trim());
+            }
         }
 
         return {
@@ -776,6 +925,7 @@ function analyzeCallSite(index, call, funcName, occurrence = 0) {
             hasSpread: args.some(a => a.startsWith('...')),
             hasVariable: args.some(a => /^[a-zA-Z_]\w*$/.test(a)),
             isMethodCall,
+            ...(indirectKind && { indirectKind }),
             ...ctx,
         };
     } catch (e) {
@@ -809,7 +959,7 @@ function analyzeCallShape(index, filePath, lineNum, funcName) {
         if (!tree) {
             const content = index._readFile(filePath);
             if (language === 'html') {
-                const htmlModule = getLanguageModule('html');
+                const htmlModule = getLanguageAdapter('html');
                 const htmlParser = getParser('html');
                 const jsParser = getParser('javascript');
                 if (!htmlParser || !jsParser) return null;
@@ -827,7 +977,8 @@ function analyzeCallShape(index, filePath, lineNum, funcName) {
             index._treeCache.set(filePath, tree);
         }
 
-        const callTypes = new Set(['call_expression', 'call', 'method_invocation', 'object_creation_expression']);
+        const callTypes = new Set(['call_expression', 'call', 'method_invocation',
+            'invocation_expression', 'object_creation_expression', 'new_expression']);
         const callNode = findCallNode(tree.rootNode, callTypes, lineNum - 1, funcName);
         if (!callNode) return null;
 
@@ -840,6 +991,7 @@ function analyzeCallShape(index, filePath, lineNum, funcName) {
         const argTexts = [];
         for (let i = 0; i < argsNode.namedChildCount; i++) {
             const argNode = argsNode.namedChild(i);
+            if (argNode.type.includes('comment')) continue;
             argKinds.push(classifyArgNode(argNode));
             argTexts.push(argNode.text.trim());
         }
@@ -987,7 +1139,7 @@ function identifyCallPatterns(callSites, funcName) {
 function verify(index, name, options = {}) {
     index._beginOp();
     try {
-    const { def } = index.resolveSymbol(name, { file: options.file, className: options.className, line: options.line });
+    const { def, warnings } = index.resolveSymbol(name, { file: options.file, className: options.className, line: options.line });
     if (!def) {
         return { found: false, function: name };
     }
@@ -1008,7 +1160,17 @@ function verify(index, name, options = {}) {
     const selfParams = langTraits(lang)?.selfParam;
     const stripSelf = (list) => (selfParams && list.length > 0 && list[0] && selfParams.includes(list[0].name))
         ? list.slice(1) : list;
+    let callableIdentityParams = null;
+    if (!ctorParamLists && ['c', 'cpp'].includes(lang)) {
+        const { _closeCallableIdentityGroup } = require('./callers');
+        const family = _closeCallableIdentityGroup(
+            index, [def], index.symbols.get(name) || [def]);
+        callableIdentityParams = family
+            .filter(member => Array.isArray(member.paramsStructured))
+            .map(member => member.paramsStructured);
+    }
     const rawParamLists = ctorParamLists ||
+        (callableIdentityParams?.length ? callableIdentityParams : null) ||
         [(arrowTypes?.paramsStructured) || def.paramsStructured || []];
     const params = stripSelf(rawParamLists[0]);
     const arities = rawParamLists.map(l => {
@@ -1039,6 +1201,11 @@ function verify(index, name, options = {}) {
         content: c.content,
         usageType: 'call',
         receiver: c.receiver,
+        // Preserve receiver identity through the usage-shaped adapter. Go
+        // permits a local value to have the same spelling as its type; only
+        // a type-qualified call is a method expression with an explicit
+        // receiver argument.
+        receiverType: c.receiverType,
         callerFile: c.callerFile,
         callerStartLine: c.callerStartLine,
     }));
@@ -1081,7 +1248,7 @@ function verify(index, name, options = {}) {
                 file: call.relativePath,
                 line: call.line,
                 expression: call.content.trim(),
-                reason: 'Could not parse call arguments',
+                reason: analysis.uncertainReason || 'Could not parse call arguments',
                 patterns: patternFlagsFrom(analysis),
                 ...carry,
             });
@@ -1110,7 +1277,8 @@ function verify(index, name, options = {}) {
         const targetTypeName = def.className || (def.receiver || '').replace(/^\*/, '');
         if (targetTypeName && call.receiver === targetTypeName && argCount > 0) {
             const qualStyle = langTraits(lang)?.typeQualifiedCallStyle;
-            if ((qualStyle === 'method-expr' && def.receiver) ||
+            if ((qualStyle === 'method-expr' && def.receiver &&
+                !call.receiverType) ||
                 (qualStyle === 'path' && def.isMethod)) {
                 argCount -= 1;
             }
@@ -1266,7 +1434,8 @@ function verify(index, name, options = {}) {
         unverifiedSites: sweepUnverified.map(unverifiedSiteShape),
         account,
         patterns: patternsAgg,
-        scopeWarning
+        scopeWarning,
+        ...(warnings.length > 0 && { warnings }),
     };
     } finally { index._endOp(); }
 }
@@ -1278,6 +1447,44 @@ function verify(index, name, options = {}) {
  * @param {object} options - { addParam, removeParam, renameTo, defaultValue }
  * @returns {object} Plan with before/after signatures and affected call sites
  */
+// Strict reserved words per language — names that can never be identifiers.
+// Contextual/soft keywords (TS `interface`, Python `match`, C# `var`) are
+// deliberately absent: they are legal identifiers, and over-blocking a rename
+// is worse than trusting the compiler for the soft cases. Fail-open for
+// languages without an entry.
+const JS_RESERVED = new Set(('break case catch class const continue debugger default delete do else enum export ' +
+    'extends false finally for function if import in instanceof new null return super switch this throw true try ' +
+    'typeof var void while with yield let static await').split(' '));
+const C_RESERVED = new Set(('auto break case char const continue default do double else enum extern float for goto ' +
+    'if inline int long register restrict return short signed sizeof static struct switch typedef union unsigned ' +
+    'void volatile while _Bool').split(' '));
+const RESERVED_WORDS_BY_LANGUAGE = {
+    javascript: JS_RESERVED,
+    typescript: JS_RESERVED,
+    tsx: JS_RESERVED,
+    python: new Set(('False None True and as assert async await break class continue def del elif else except ' +
+        'finally for from global if import in is lambda nonlocal not or pass raise return try while with yield').split(' ')),
+    go: new Set(('break case chan const continue default defer else fallthrough for func go goto if import ' +
+        'interface map package range return select struct switch type var').split(' ')),
+    rust: new Set(('as async await break const continue crate dyn else enum extern false fn for if impl in let ' +
+        'loop match mod move mut pub ref return self Self static struct super trait true type unsafe use where ' +
+        'while').split(' ')),
+    java: new Set(('abstract assert boolean break byte case catch char class const continue default do double ' +
+        'else enum extends final finally float for goto if implements import instanceof int interface long native ' +
+        'new package private protected public return short static strictfp super switch synchronized this throw ' +
+        'throws transient try void volatile while true false null').split(' ')),
+    c: C_RESERVED,
+    cpp: new Set([...C_RESERVED, ...('bool catch class constexpr delete explicit false friend mutable namespace ' +
+        'new noexcept nullptr operator private protected public template this throw true try typename using ' +
+        'virtual wchar_t').split(' ')]),
+    csharp: new Set(('abstract as base bool break byte case catch char checked class const continue decimal ' +
+        'default delegate do double else enum event explicit extern false finally fixed float for foreach goto if ' +
+        'implicit in int interface internal is lock long namespace new null object operator out override params ' +
+        'private protected public readonly ref return sbyte sealed short sizeof stackalloc static string struct ' +
+        'switch this throw true try typeof uint ulong unchecked unsafe ushort using virtual void volatile ' +
+        'while').split(' ')),
+};
+
 function plan(index, name, options = {}) {
     index._beginOp();
     try {
@@ -1331,10 +1538,33 @@ function plan(index, name, options = {}) {
         };
     }
 
+    // Rename-target sanity: a same-name rename is a 0-change request, and a
+    // reserved word in the target's language would write syntax errors into
+    // the declaration and every call site. (Identifier SHAPE is validated at
+    // the execute layer; keywords need the resolved symbol's language.)
+    if (options.renameTo) {
+        if (options.renameTo === def.name || options.renameTo === name) {
+            return {
+                found: true,
+                function: name,
+                error: `renameTo "${options.renameTo}" matches the current name — nothing to rename.`,
+            };
+        }
+        const reserved = RESERVED_WORDS_BY_LANGUAGE[planLang === 'html' ? 'javascript' : planLang];
+        if (reserved && reserved.has(options.renameTo)) {
+            return {
+                found: true,
+                function: name,
+                error: `renameTo "${options.renameTo}" is a reserved word in ${planLang === 'html' ? 'javascript' : planLang} and cannot be used as an identifier.`,
+            };
+        }
+    }
+
     let newParams = [...currentParams];
     let newSignature = currentSignature;
     let operation = null;
     let changes = [];
+    let unchangedSites = 0;
 
     if (options.addParam) {
         // Check if parameter already exists
@@ -1394,7 +1624,11 @@ function plan(index, name, options = {}) {
         for (const site of planCallSites) {
             let suggestion;
             if (options.defaultValue && langHasDefaults) {
-                suggestion = `No change needed (has default value)`;
+                // The default makes the existing call valid. Keep the fact in
+                // metadata, but do not inflate the concrete edit plan with a
+                // no-op entry (UCN5-166).
+                unchangedSites++;
+                continue;
             } else if (options.defaultValue) {
                 suggestion = `Add argument: ${options.defaultValue} (no default parameter values in ${planFileEntry?.language || 'this language'})`;
             } else {
@@ -1405,7 +1639,8 @@ function plan(index, name, options = {}) {
                 line: site.line,
                 expression: site.expression,
                 suggestion,
-                args: site.args
+                args: site.args,
+                editKind: 'call',
             });
         }
     }
@@ -1462,7 +1697,8 @@ function plan(index, name, options = {}) {
                         line: site.line,
                         expression: site.expression,
                         suggestion: `Remove argument ${callerArgIndex + 1}: ${site.args[callerArgIndex] || '?'}`,
-                        args: site.args
+                        args: site.args,
+                        editKind: 'call',
                     });
                 } else if (!site.args) {
                     // Arguments unparseable (macro bodies, generated code) —
@@ -1473,7 +1709,8 @@ function plan(index, name, options = {}) {
                         line: site.line,
                         expression: site.expression,
                         suggestion: 'Could not parse arguments — review this call site manually',
-                        needsReview: true
+                        needsReview: true,
+                        editKind: 'call',
                     });
                 }
             }
@@ -1489,21 +1726,63 @@ function plan(index, name, options = {}) {
         // line appears ONCE however many call records it holds (fix #230 —
         // the non-global regex left the inner call behind and emitted a
         // duplicate entry per record).
-        const renamedLines = new Set();
+        const callLines = new Map();
         for (const site of planCallSites) {
             const lineKey = `${site.file}:${site.line}`;
-            if (renamedLines.has(lineKey)) continue;
-            renamedLines.add(lineKey);
-            const newExpression = site.expression.replace(
-                new RegExp('\\b' + escapeRegExp(name) + '\\b', 'g'),
-                options.renameTo
-            );
-            changes.push({
+            const group = callLines.get(lineKey) || {
                 file: site.file,
+                absoluteFile: site.absoluteFile,
                 line: site.line,
                 expression: site.expression,
+                columns: [],
+                missingColumn: false,
+                callCount: 0,
+                calledAs: site.calledAs,
+            };
+            if (group.calledAs !== site.calledAs) group.calledAs = null;
+            group.callCount++;
+            if (Number.isInteger(site.column)) group.columns.push(site.column);
+            else group.missingColumn = true;
+            callLines.set(lineKey, group);
+        }
+        for (const site of callLines.values()) {
+            // A renamed import preserves its local alias (`old as local` /
+            // `{ old: local }`). The caller engine carries the authored name
+            // in calledAs; that token must remain unchanged while the import's
+            // source-side identifier is edited below.
+            if (site.calledAs && site.calledAs !== name) continue;
+            const edit = renameIdentifierTokens(index,
+                site.absoluteFile || site.file, site.line, name,
+                options.renameTo, site.missingColumn ? [] : site.columns,
+                site.callCount);
+            const newExpression = edit.renamed;
+            // A confirmed call through an import alias (`xf()`) is a real
+            // caller but the alias spelling does not change. The required
+            // edit is the import's source-side name; never emit a byte-for-
+            // byte no-op that makes the plan look complete.
+            if (newExpression === edit.source) {
+                // Missing parser columns mean UCN can prove the edit is
+                // required but cannot safely synthesize it. Never fall back
+                // to whole-line regex replacement.
+                if (site.missingColumn) {
+                    changes.push({
+                        file: site.file,
+                        line: site.line,
+                        expression: edit.source,
+                        suggestion: `Rename call identifier "${name}" to "${options.renameTo}" manually`,
+                        needsReview: true,
+                        editKind: 'call',
+                    });
+                }
+                continue;
+            }
+            changes.push({
+                file: site.file,
+                line: site.line,
+                expression: edit.source,
                 suggestion: `Rename to: ${newExpression}`,
-                newExpression
+                newExpression,
+                editKind: 'call',
             });
         }
 
@@ -1530,21 +1809,236 @@ function plan(index, name, options = {}) {
                 _nameBindingReaches(index, imp.file, name, renameTargetFiles) === 'no') {
                 continue;
             }
-            const newImport = imp.content.trim().replace(
-                new RegExp('\\b' + escapeRegExp(name) + '\\b'),
-                options.renameTo
-            );
+            const edit = renameIdentifierTokens(index, imp.file,
+                imp.line, name, options.renameTo);
+            const newImport = edit.renamed;
+            if (newImport === edit.source) continue;
             changes.push({
                 file: imp.relativePath || imp.file,
                 line: imp.line,
-                expression: imp.content.trim(),
+                expression: edit.source,
                 suggestion: `Update import: ${newImport}`,
                 newExpression: newImport,
-                isImport: true
+                isImport: true,
+                editKind: 'import',
             });
         }
+
+        // Renamed CJS/Python imports are intentionally surfaced as reference
+        // usages by their parsers, so usageType alone cannot find the import
+        // line. importBindings retains the original/local pair and line.
+        for (const [filePath, fileEntry] of index.files) {
+            for (const binding of fileEntry.importBindings || []) {
+                const localAlias = binding.alias || (fileEntry.importAliases || [])
+                    .find(alias => alias.original === binding.name)?.local;
+                if (binding.name !== name || !localAlias ||
+                    localAlias === name || !binding.line) continue;
+                if (_nameBindingReaches(index, filePath, name,
+                    renameTargetFiles) === 'no') continue;
+                const rel = fileEntry.relativePath || filePath;
+                if (changes.some(change =>
+                    change.file === rel && change.line === binding.line)) continue;
+                const edit = renameIdentifierTokens(index, filePath,
+                    binding.line, name, options.renameTo);
+                const sourceLine = edit.source;
+                const newImport = edit.renamed;
+                if (newImport === sourceLine) continue;
+                changes.push({
+                    file: rel,
+                    line: binding.line,
+                    expression: sourceLine,
+                    suggestion: `Update import: ${newImport}`,
+                    newExpression: newImport,
+                    isImport: true,
+                    editKind: 'import',
+                });
+            }
+        }
+
+        // Export surfaces owned by the selected definition are declaration
+        // references too. In particular, CommonJS shorthand
+        // `module.exports = { helper }` must be renamed or the otherwise
+        // complete caller/import edit set breaks the module API.
+        for (const [exportPath, targetEntry] of index.files) {
+            for (const exported of targetEntry.exportDetails || []) {
+                if ((exported.name !== name && exported.alias !== name) ||
+                    !exported.line) continue;
+                const ownership = _nameBindingReaches(
+                    index, exportPath, name, renameTargetFiles, 8);
+                // Transitive file reachability is not name ownership. A file
+                // can import the target somewhere in its dependency closure
+                // while exporting its own same-spelled local declaration.
+                // Edit the target's own export, or a positively-resolved
+                // re-export chain; unknown CJS/dynamic surfaces are unsafe to
+                // rewrite mechanically.
+                if (exportPath !== def.file && ownership !== 'yes') continue;
+                const exportFile = targetEntry.relativePath || exportPath;
+                if (changes.some(change =>
+                    change.file === exportFile && change.line === exported.line)) {
+                    continue;
+                }
+                const edit = renameIdentifierTokens(index, exportPath,
+                    exported.line, name, options.renameTo);
+                const sourceLine = edit.source;
+                const occurrences = edit.count;
+                const newExpression = edit.renamed;
+                if (newExpression === sourceLine) continue;
+                changes.push({
+                    file: exportFile,
+                    line: exported.line,
+                    expression: sourceLine,
+                    suggestion: `Update export: ${newExpression}`,
+                    newExpression,
+                    isExport: true,
+                    editKind: 'export',
+                    ...(occurrences > 1 && { needsReview: true }),
+                });
+            }
+        }
+
+        // Renaming a virtual/overridden member is one hierarchy-wide change.
+        // Leaving descendant declarations behind either fails compilation
+        // (Java/C#/TS override) or silently changes dispatch (Python/JS).
+        if (def.className) {
+            // Inheritance identity is (class name, defining file), not just
+            // the spelling. Repositories routinely contain two Handler/Base
+            // classes in unrelated packages. Follow only children whose base
+            // resolves from the child's scope to this exact parent file.
+            const identityKey = (className, file) => `${file || ''}\0${className}`;
+            const descendants = new Map();
+            const queue = [{ name: def.className, file: def.file }];
+            const visited = new Set([identityKey(def.className, def.file)]);
+            while (queue.length > 0 && descendants.size < 5000) {
+                const parent = queue.shift();
+                for (const child of index.extendedByGraph.get(parent.name) || []) {
+                    const childName = typeof child === 'string' ? child : child.name;
+                    const childFile = typeof child === 'string'
+                        ? index._resolveClassFile(childName, parent.file)
+                        : child.file;
+                    if (!childName || !childFile) continue;
+                    const parentFile = index._resolveClassFile(parent.name, childFile);
+                    if (parentFile !== parent.file) continue;
+                    const key = identityKey(childName, childFile);
+                    if (visited.has(key)) continue;
+                    visited.add(key);
+                    descendants.set(key, { name: childName, file: childFile });
+                    queue.push({ name: childName, file: childFile });
+                }
+            }
+            for (const override of index.symbols.get(name) || []) {
+                if (!override.className ||
+                    !descendants.has(identityKey(override.className, override.file))) continue;
+                const line = override.nameLine || override.startLine;
+                const rel = override.relativePath || override.file;
+                if (changes.some(change => change.file === rel && change.line === line)) continue;
+                const edit = renameIdentifierTokens(index, override.file,
+                    line, name, options.renameTo);
+                const sourceLine = edit.source;
+                const newExpression = edit.renamed;
+                if (newExpression === sourceLine) continue;
+                changes.push({
+                    file: rel,
+                    line,
+                    expression: sourceLine,
+                    suggestion: `Update overriding definition: ${newExpression}`,
+                    newExpression,
+                    isDefinition: true,
+                    editKind: 'definition',
+                });
+            }
+        }
+
+        // C/C++ declarations and definitions are one compiler symbol. A
+        // selected implementation must carry its matching header prototype,
+        // and selecting the prototype must carry the implementation.
+        if (planLang === 'c' || planLang === 'cpp') {
+            const ownerOf = symbol => symbol.className ||
+                (symbol.receiver || '').replace(/^\*/, '') || null;
+            const signatureOf = symbol => (symbol.paramsStructured || []).map(param =>
+                String(param.type || param.name || '').replace(/\s+/g, '')).join(',');
+            const linked = candidate => candidate.file === def.file ||
+                index.importGraph.get(def.file)?.has(candidate.file) ||
+                index.importGraph.get(candidate.file)?.has(def.file);
+            for (const sibling of index.symbols.get(name) || []) {
+                if (sibling === def || ownerOf(sibling) !== ownerOf(def) ||
+                    signatureOf(sibling) !== signatureOf(def) ||
+                    !(sibling.isSignature || def.isSignature) || !linked(sibling)) continue;
+                const siblingLang = index.files.get(sibling.file)?.language;
+                if (siblingLang !== planLang &&
+                    !new Set(['c', 'cpp']).has(siblingLang)) continue;
+                const line = sibling.nameLine || sibling.startLine;
+                const rel = sibling.relativePath || sibling.file;
+                if (changes.some(change => change.file === rel && change.line === line)) continue;
+                const edit = renameIdentifierTokens(index, sibling.file,
+                    line, name, options.renameTo);
+                if (edit.renamed === edit.source) continue;
+                changes.push({
+                    file: rel,
+                    line,
+                    expression: edit.source,
+                    suggestion: `Update paired declaration: ${edit.renamed}`,
+                    newExpression: edit.renamed,
+                    isDefinition: true,
+                    editKind: 'definition',
+                });
+            }
+        }
+    }
+
+    // Every operation changes the selected declaration. Historically `plan`
+    // only listed callers/imports in changes[], while rendering the new
+    // signature separately. An agent applying the advertised edit array
+    // therefore produced uncompilable code. Keep the declaration in the same
+    // concrete list and count as every other required edit.
+    const definitionLine = def.nameLine || def.startLine;
+    const definitionFile = def.relativePath || def.file;
+    const definitionSource = index.getLineContent(def.file, definitionLine).trim();
+    const existingDefinitionLine = changes.find(change =>
+        change.file === definitionFile && change.line === definitionLine);
+    if (existingDefinitionLine) {
+        existingDefinitionLine.isDefinition = true;
+        existingDefinitionLine.editKind = 'definition';
+        if (options.renameTo) {
+            const renamed = renameIdentifierTokens(index, def.file,
+                definitionLine, name, options.renameTo).renamed;
+            existingDefinitionLine.newExpression = renamed;
+            existingDefinitionLine.suggestion = `Update definition: ${renamed}`;
+        }
+    } else {
+        const definitionChange = {
+            file: definitionFile,
+            line: definitionLine,
+            expression: definitionSource,
+            isDefinition: true,
+            editKind: 'definition',
+        };
+        if (options.renameTo) {
+            const renamed = renameIdentifierTokens(index, def.file,
+                definitionLine, name, options.renameTo).renamed;
+            definitionChange.newExpression = renamed;
+            definitionChange.suggestion = `Update definition: ${renamed}`;
+        } else {
+            definitionChange.suggestion =
+                `Update declaration signature to: ${newSignature}`;
+            // Signature layouts can span multiple lines and differ by
+            // language. The AST proves this edit is required, while the
+            // preview explicitly withholds a fake one-line replacement.
+            definitionChange.needsReview = true;
+        }
+        changes.unshift(definitionChange);
     }
 
+    const changeSummary = {
+        // editKind is a partition: a public declaration that is also an
+        // export remains one definition edit, never two summary buckets.
+        definitions: changes.filter(change => change.editKind === 'definition').length,
+        calls: changes.filter(change => change.editKind === 'call' ||
+            !change.editKind).length,
+        imports: changes.filter(change => change.editKind === 'import').length,
+        exports: changes.filter(change => change.editKind === 'export').length,
+        reviewRequired: changes.filter(change => change.needsReview).length,
+    };
+
     return {
         found: true,
         function: name,
@@ -1564,13 +2058,16 @@ function plan(index, name, options = {}) {
         },
         totalChanges: changes.length,
         filesAffected: new Set(changes.map(c => c.file)).size,
+        changeSummary,
         changes,
+        ...(unchangedSites > 0 && { unchangedSites }),
         // v4 tiered contract: sites that MAY also need this change but lack
         // binding/receiver evidence — review manually before refactoring.
         unverifiedCount: planUnverified.length,
         unverifiedSites: planUnverified,
         account: planAccount,
-        scopeWarning: impactScopeWarning
+        scopeWarning: impactScopeWarning,
+        ...(resolved.warnings.length > 0 && { warnings: resolved.warnings }),
     };
     } finally { index._endOp(); }
 }