ucn 3.8.23 → 3.8.25

package/core/verify.js

@@ -10,6 +10,134 @@ const { detectLanguage, getParser, getLanguageModule, safeParse, langTraits } =
 const { escapeRegExp } = require('./shared');
 const { extractImports } = require('./imports');
 
+// ============================================================================
+// CALL-SITE CLASSIFICATION (Feature A)
+// ============================================================================
+// AST node-type sets per language for walk-up classification of call sites.
+// Detection is structural — we walk parents from the call node and stop at
+// function boundaries to keep the classification scoped to the enclosing fn.
+
+// Loop nodes — call sites inside these are "hot path" (likely repeated).
+const LOOP_NODE_TYPES = {
+    javascript: new Set(['for_statement', 'while_statement', 'do_statement', 'for_in_statement', 'for_of_statement']),
+    typescript: new Set(['for_statement', 'while_statement', 'do_statement', 'for_in_statement', 'for_of_statement']),
+    tsx:        new Set(['for_statement', 'while_statement', 'do_statement', 'for_in_statement', 'for_of_statement']),
+    html:       new Set(['for_statement', 'while_statement', 'do_statement', 'for_in_statement', 'for_of_statement']),
+    python:     new Set(['for_statement', 'while_statement']),
+    go:         new Set(['for_statement']),
+    rust:       new Set(['for_expression', 'while_expression', 'loop_expression']),
+    java:       new Set(['for_statement', 'while_statement', 'do_statement', 'enhanced_for_statement']),
+};
+
+// Try nodes — call sites inside these are "guarded" (errors are caught).
+// Go uses defer/recover (skipped). Rust uses Result-based error handling (skipped).
+const TRY_NODE_TYPES = {
+    javascript: new Set(['try_statement']),
+    typescript: new Set(['try_statement']),
+    tsx:        new Set(['try_statement']),
+    html:       new Set(['try_statement']),
+    python:     new Set(['try_statement']),
+    go:         new Set(),
+    rust:       new Set(),
+    java:       new Set(['try_statement', 'try_with_resources_statement']),
+};
+
+// Function boundary nodes — walk-up stops at these (we don't classify across
+// inner function definitions). These also identify "callback wrappers" when
+// they're the value of an argument to another call_expression.
+const FN_NODE_TYPES = {
+    javascript: new Set(['function_declaration', 'function_expression', 'arrow_function', 'method_definition', 'generator_function', 'generator_function_declaration']),
+    typescript: new Set(['function_declaration', 'function_expression', 'arrow_function', 'method_definition', 'generator_function', 'generator_function_declaration', 'function_signature']),
+    tsx:        new Set(['function_declaration', 'function_expression', 'arrow_function', 'method_definition', 'generator_function', 'generator_function_declaration', 'function_signature']),
+    html:       new Set(['function_declaration', 'function_expression', 'arrow_function', 'method_definition', 'generator_function', 'generator_function_declaration']),
+    python:     new Set(['function_definition', 'async_function_definition', 'lambda']),
+    go:         new Set(['function_declaration', 'method_declaration', 'func_literal']),
+    rust:       new Set(['function_item', 'closure_expression']),
+    java:       new Set(['method_declaration', 'constructor_declaration', 'lambda_expression']),
+};
+
+// Await-expression node types per language with async/await support.
+// JS/TS: await is a unary expression `await call()`.
+// Python: await is `await call()`.
+// Go/Java/Rust currently have no await keyword tracked here.
+const AWAIT_NODE_TYPES = {
+    javascript: new Set(['await_expression']),
+    typescript: new Set(['await_expression']),
+    tsx:        new Set(['await_expression']),
+    html:       new Set(['await_expression']),
+    python:     new Set(['await']),
+    go:         new Set(),
+    rust:       new Set(),
+    java:       new Set(),
+};
+
+// Argument-list node types — used to detect callback context. When walking up,
+// if a function/lambda we cross has a parent of these types (which is itself
+// inside a call_expression), the inner call is in a callback.
+const ARGUMENTS_NODE_TYPES = new Set(['arguments', 'argument_list']);
+
+/**
+ * Classify a call site by walking up its ancestors.
+ *
+ * Returns flags describing the structural context: `inLoop`, `inTry`,
+ * `inCallback`, `awaited`. Walks from the call node up to the enclosing
+ * function boundary (so an outer try wrapping an inner function does NOT
+ * leak `inTry: true` into a call inside the inner function).
+ *
+ * `inCallback` is set when, while walking up to the boundary, we cross an
+ * inner function/lambda that is itself an argument of another call.
+ *
+ * `awaited` is set when the call expression's immediate parent is an
+ * await-style node. Non-async languages always return `awaited: false`.
+ *
+ * @param {object} callNode - tree-sitter node for the call
+ * @param {string} language - canonical language name
+ * @returns {{inLoop:boolean, inTry:boolean, inCallback:boolean, awaited:boolean}}
+ */
+function classifyCallContext(callNode, language) {
+    const result = { inLoop: false, inTry: false, inCallback: false, awaited: false };
+    if (!callNode) return result;
+
+    const loopTypes = LOOP_NODE_TYPES[language] || new Set();
+    const tryTypes = TRY_NODE_TYPES[language] || new Set();
+    const fnTypes = FN_NODE_TYPES[language] || new Set();
+    const awaitTypes = AWAIT_NODE_TYPES[language] || new Set();
+
+    // awaited: parent of the call must be an await-style node.
+    // Some grammars (Python) wrap the call in `await { call }`; others
+    // (JS/TS) use `await_expression > call_expression`. Both are detected by
+    // checking the immediate parent.
+    if (callNode.parent && awaitTypes.has(callNode.parent.type)) {
+        result.awaited = true;
+    }
+
+    // Walk up to classify loop/try/callback. Stop when we cross a function
+    // boundary — an inner closure isolates the inner call from outer context.
+    let current = callNode.parent;
+    while (current) {
+        const t = current.type;
+        if (loopTypes.has(t)) result.inLoop = true;
+        if (tryTypes.has(t)) result.inTry = true;
+        // Function boundary — stop, but first check if THIS function is an
+        // argument to another call (callback context). The ancestor chain is:
+        //   outer_call > arguments > arrow_function/lambda > … > inner call
+        if (fnTypes.has(t)) {
+            const parent = current.parent;
+            if (parent && ARGUMENTS_NODE_TYPES.has(parent.type)) {
+                const grand = parent.parent;
+                if (grand && (grand.type === 'call_expression' || grand.type === 'call' ||
+                    grand.type === 'method_invocation' || grand.type === 'object_creation_expression' ||
+                    grand.type === 'macro_invocation')) {
+                    result.inCallback = true;
+                }
+            }
+            break;
+        }
+        current = current.parent;
+    }
+    return result;
+}
+
 /**
  * Find a call expression node at the target line matching funcName
  */
@@ -62,6 +190,466 @@ function clearTreeCache(index) {
     index._treeCache = null;
 }
 
+/**
+ * Render a single parameter with TS-correct optional marker placement.
+ * BUG-BV fix: `?` follows the NAME, not the TYPE (e.g. `opt?: number`,
+ * not the invalid `opt: number?`). Used by verify/plan signature output.
+ * @param {object} p - Param object {name, type?, optional?, default?, rest?}
+ * @returns {string}
+ */
+function formatTypedParam(p) {
+    if (!p || !p.name) return '';
+    // Rest-param prefix:
+    //   Python `**kwargs` / `*args` keep their `*` prefix (name already starts with `*`).
+    //   JS/TS rest like `...rest` keeps `...` (avoid double-prefix if name already has `...`).
+    //   Bare names with rest=true get `...` prefix (JS rest with stripped pattern name).
+    let s;
+    if (p.rest) {
+        const n = String(p.name);
+        if (n.startsWith('*') || n.startsWith('...')) s = n;
+        else s = `...${n}`;
+    } else {
+        s = p.name;
+    }
+    // Optional marker — placed AFTER name, BEFORE type (TS syntax: `opt?: number`)
+    if (p.optional && !p.rest && p.default == null) s += '?';
+    if (p.type) s += `: ${p.type}`;
+    if (p.default != null) s += ` = ${p.default}`;
+    return s;
+}
+
+/**
+ * Render a param name for the plan `before.params` / `after.params` arrays.
+ * These arrays are name-keyed (callers do `.includes('retries')` exact match),
+ * so we keep TS optional `?` and type annotation for BUG-BV/#181 contracts,
+ * but omit the ` = default` suffix and rest `*`/`...` prefix that callers don't
+ * test against. Mirrors the pre-rewrite shape of plan output.
+ * @param {object} p
+ * @returns {string}
+ */
+function formatPlanParamName(p) {
+    if (!p || !p.name) return '';
+    let s = p.name;
+    if (p.optional && !p.default) s += '?';
+    if (p.type) s += `: ${p.type}`;
+    return s;
+}
+
+/**
+ * Compute the modifier-prefix tokens for a function/method definition.
+ * Returns an array of tokens (e.g. ['static', 'async']) drawn from:
+ *   - def.modifiers          (Java, Python async, Rust pub/async, ...)
+ *   - def.isAsync / def.async (JS/TS class methods)
+ *   - def.memberType         (JS/TS: 'static', 'static get', 'static override', ...)
+ *
+ * BUG-5: rename and add-param signature reconstruction must preserve modifier
+ * prefixes (async/static/public/...) — JS class methods don't populate
+ * def.modifiers, so we synthesise tokens from isAsync + memberType.
+ * @param {object} def
+ * @returns {string[]} ordered modifier tokens (no trailing space)
+ */
+function computeModifierTokens(def) {
+    if (!def) return [];
+    const tokens = [];
+    // Pull declared modifiers first (Java public/static/final, Python ['async'], Rust pub/async).
+    if (Array.isArray(def.modifiers) && def.modifiers.length) {
+        for (const m of def.modifiers) {
+            if (typeof m === 'string' && m.length && !tokens.includes(m)) tokens.push(m);
+        }
+    }
+    // JS/TS class methods: memberType encodes static/get/set/override/private.
+    // Examples: 'static', 'static get', 'static override', 'static override get',
+    //           'override', 'override get', 'get', 'set', 'private', 'method',
+    //           'abstract', 'constructor'. Only structural prefixes are added.
+    const memberType = def.memberType;
+    if (typeof memberType === 'string' && memberType.length) {
+        const STRUCTURAL_PREFIXES = new Set(['static', 'override', 'abstract', 'public', 'private', 'protected', 'readonly', 'get', 'set']);
+        for (const tok of memberType.split(/\s+/)) {
+            if (STRUCTURAL_PREFIXES.has(tok) && !tokens.includes(tok)) tokens.push(tok);
+        }
+    }
+    // Async (JS/TS isAsync, fallback for languages that set def.async).
+    const asyncFlag = def.isAsync || def.async || (Array.isArray(def.modifiers) && def.modifiers.includes('async'));
+    if (asyncFlag && !tokens.includes('async')) tokens.push('async');
+    return tokens;
+}
+
+/**
+ * Build a function signature string from a definition, using
+ * TS-correct param formatting (BUG-BV). Local to verify.js to avoid
+ * the shared formatter's incorrect `?` placement.
+ * @param {object} def - Symbol definition
+ * @param {object} [overrides] - Optional { paramsStructured, returnType, name } overrides
+ * @returns {string}
+ */
+function formatTypedSignature(def, overrides = {}) {
+    const parts = [];
+    const modTokens = computeModifierTokens(def);
+    if (modTokens.length) {
+        parts.push(modTokens.join(' '));
+    }
+    const name = overrides.name || def.name;
+    parts.push(name);
+    const ps = overrides.paramsStructured != null ? overrides.paramsStructured : def.paramsStructured;
+    if (Array.isArray(ps)) {
+        const paramTypes = def.paramTypes || {};
+        const parts2 = ps.map(p => {
+            // Apply paramTypes mapping when paramsStructured doesn't carry types
+            const merged = { ...p };
+            if (!merged.type && paramTypes[p.name]) merged.type = paramTypes[p.name];
+            return formatTypedParam(merged);
+        });
+        parts.push(`(${parts2.filter(Boolean).join(', ')})`);
+    } else if (def.params !== undefined) {
+        parts.push(`(${def.params})`);
+    }
+    const rt = overrides.returnType != null ? overrides.returnType : def.returnType;
+    if (rt) parts.push(`: ${rt}`);
+    return parts.join(' ');
+}
+
+/**
+ * BUG-BY: For an arrow function declared as `const x: (a: number) => number = (a) => ...`
+ * the inline arrow params/return type are missing types — they live on the
+ * variable_declarator's type_annotation. Walk up to the declarator and
+ * extract `function_type` parts (params + return type) when present.
+ *
+ * Returns null if no enrichment is available; otherwise an object with
+ * { paramsStructured, returnType } suitable for use as overrides.
+ *
+ * Only applies to TS-family files (typescript/tsx). JS doesn't have function_type
+ * annotations at the variable declarator level.
+ *
+ * @param {object} index - ProjectIndex instance
+ * @param {object} def - Symbol definition (must have file + startLine)
+ * @returns {{ paramsStructured: Array, returnType: string|null }|null}
+ */
+function extractArrowTypesFromVarDecl(index, def) {
+    if (!def || !def.file || !def.startLine) return null;
+    const lang = detectLanguage(def.file);
+    if (lang !== 'typescript' && lang !== 'tsx') return null;
+    // Already have types — nothing to enrich.
+    const ps = def.paramsStructured;
+    const allHaveTypes = Array.isArray(ps) && ps.length > 0 && ps.every(p => p && p.type);
+    if (allHaveTypes && def.returnType) return null;
+    let parser;
+    try {
+        parser = getParser(lang);
+    } catch (e) {
+        return null;
+    }
+    if (!parser) return null;
+    let content;
+    try {
+        content = index._readFile(def.file);
+    } catch (e) {
+        return null;
+    }
+    const tree = safeParse(parser, content);
+    if (!tree) return null;
+
+    // Find the variable_declarator that wraps the arrow function at def.startLine
+    const targetRow = def.startLine - 1;
+    function findVarDecl(node) {
+        if (!node) return null;
+        if (node.startPosition.row > targetRow || node.endPosition.row < targetRow) return null;
+        if (node.type === 'variable_declarator') {
+            // Check if this declarator's value is an arrow_function (or function_expression)
+            const valueNode = node.childForFieldName('value');
+            if (valueNode && (valueNode.type === 'arrow_function' || valueNode.type === 'function_expression' || valueNode.type === 'function')) {
+                // Confirm name matches and starts at our target row
+                const nameNode = node.childForFieldName('name');
+                if (nameNode && nameNode.text === def.name) {
+                    return node;
+                }
+            }
+        }
+        for (let i = 0; i < node.namedChildCount; i++) {
+            const result = findVarDecl(node.namedChild(i));
+            if (result) return result;
+        }
+        return null;
+    }
+    const declarator = findVarDecl(tree.rootNode);
+    if (!declarator) return null;
+
+    // Look for type_annotation child holding a function_type
+    let typeAnno = null;
+    for (let i = 0; i < declarator.namedChildCount; i++) {
+        const child = declarator.namedChild(i);
+        if (child.type === 'type_annotation') { typeAnno = child; break; }
+    }
+    if (!typeAnno) return null;
+    // type_annotation > function_type
+    let fnType = null;
+    for (let i = 0; i < typeAnno.namedChildCount; i++) {
+        const child = typeAnno.namedChild(i);
+        if (child.type === 'function_type') { fnType = child; break; }
+    }
+    if (!fnType) return null;
+    // function_type has formal_parameters + a return type sibling
+    const fp = fnType.childForFieldName('parameters') || (() => {
+        for (let i = 0; i < fnType.namedChildCount; i++) {
+            const c = fnType.namedChild(i);
+            if (c.type === 'formal_parameters') return c;
+        }
+        return null;
+    })();
+    let returnType = null;
+    // Return type is the last named child (predefined_type, type_identifier, etc.) that isn't formal_parameters
+    for (let i = fnType.namedChildCount - 1; i >= 0; i--) {
+        const c = fnType.namedChild(i);
+        if (c.type !== 'formal_parameters' && c.type !== 'type_parameters') {
+            returnType = c.text;
+            break;
+        }
+    }
+    // Build typed paramsStructured by reading param names + types out of fp.
+    // Pair against the existing inline params (from def.paramsStructured) so
+    // we preserve names declared at the arrow site if they differ.
+    let typedParams = [];
+    if (fp) {
+        for (let i = 0; i < fp.namedChildCount; i++) {
+            const param = fp.namedChild(i);
+            const info = {};
+            if (param.type === 'required_parameter' || param.type === 'optional_parameter') {
+                const patternNode = param.childForFieldName('pattern');
+                const tnode = param.childForFieldName('type');
+                if (patternNode) info.name = patternNode.text;
+                if (tnode) info.type = tnode.text.replace(/^:\s*/, '');
+                if (param.type === 'optional_parameter') info.optional = true;
+            } else if (param.type === 'identifier') {
+                info.name = param.text;
+            }
+            if (info.name) typedParams.push(info);
+        }
+    }
+    // If inline params have names (from arrow), prefer those names but keep types from fnType
+    if (Array.isArray(ps) && ps.length === typedParams.length) {
+        typedParams = typedParams.map((tp, i) => ({
+            ...ps[i],   // start from existing (preserves rest, default, etc.)
+            ...(tp.type ? { type: tp.type } : {}),
+            ...(tp.optional ? { optional: true } : {}),
+        }));
+    }
+    return {
+        paramsStructured: typedParams.length ? typedParams : ps,
+        returnType: returnType || def.returnType || null,
+    };
+}
+
+/**
+ * BUG-BX: A receiver like `Utils.helper()` may be a TS namespace member call
+ * for a regular (non-method) exported function. Returns true when the
+ * receiver matches a known namespace/class symbol that contains a function
+ * with the verified name.
+ * @param {object} index - ProjectIndex instance
+ * @param {string} receiver - Receiver text from the call site
+ * @param {string} funcName - Name being verified
+ * @param {string} defFile - The definition's file (to scope the match)
+ * @returns {boolean}
+ */
+function isNamespaceContainerFor(index, receiver, funcName, defFile) {
+    if (!receiver || !funcName) return false;
+    const candidates = index.symbols.get(receiver);
+    if (!candidates || candidates.length === 0) return false;
+    // Accept namespace, module, class, or interface containers
+    return candidates.some(c => {
+        const t = c.type;
+        if (t === 'namespace' || t === 'module' || t === 'class' || t === 'interface') {
+            // Same file as the def is the strongest signal; fall back to project-wide match.
+            if (!defFile || c.file === defFile) return true;
+            // Cross-file: only accept when receiver is a dedicated namespace/module
+            return t === 'namespace' || t === 'module';
+        }
+        return false;
+    });
+}
+
+/**
+ * BUG-BW: Build the list of call sites for `plan` using the SAME findCallers
+ * + className filter logic that verify uses. This guarantees plan and verify
+ * agree on which sites need updating — the previous implementation routed
+ * through `index.impact()` whose filter is stricter for unresolved receivers
+ * (e.g. `this.repo.save()`), causing plan to miss class-method call sites
+ * that verify finds.
+ *
+ * Returns an array of plan-shaped sites: { file, line, expression, args, argCount }.
+ *
+ * @param {object} index - ProjectIndex instance
+ * @param {string} name - Function name being refactored
+ * @param {object} def - Resolved definition
+ * @param {object} options - { file, className, line }
+ * @returns {Array}
+ */
+function computePlanCallSites(index, name, def, options) {
+    let callerResults = index.findCallers(name, {
+        includeMethods: true,
+        includeUncertain: false,
+        targetDefinitions: [def],
+    });
+
+    // Mirror verify's className filter (kept inline rather than re-extracted to
+    // avoid changing verify's behavior).
+    if (options.className && def.className) {
+        const targetClassName = def.className;
+        callerResults = callerResults.filter(c => {
+            if (!c.isMethod) return true;
+            const r = c.receiver;
+            if (!r || ['self', 'cls', 'this', 'super'].includes(r)) return true;
+            if (r.toLowerCase().includes(targetClassName.toLowerCase())) return true;
+            // Local var type inference from constructor assignments
+            if (c.callerFile) {
+                const callerDef = c.callerStartLine ? { file: c.callerFile, startLine: c.callerStartLine, endLine: c.callerEndLine } : null;
+                if (callerDef) {
+                    const callerCalls = index.getCachedCalls(c.callerFile);
+                    if (callerCalls && Array.isArray(callerCalls)) {
+                        const localTypes = new Map();
+                        for (const call of callerCalls) {
+                            if (call.line >= callerDef.startLine && call.line <= callerDef.endLine) {
+                                if (!call.isMethod && !call.receiver) {
+                                    const syms = index.symbols.get(call.name);
+                                    if (syms && syms.some(s => s.type === 'class')) {
+                                        const content = index._readFile(c.callerFile);
+                                        const clines = content.split('\n');
+                                        const cline = clines[call.line - 1] || '';
+                                        const m = cline.match(/^\s*(\w+)\s*=\s*(?:await\s+)?(\w+)\s*\(/);
+                                        if (m && m[2] === call.name) {
+                                            localTypes.set(m[1], call.name);
+                                        }
+                                    }
+                                }
+                            }
+                        }
+                        const receiverType = localTypes.get(r);
+                        if (receiverType) return receiverType === targetClassName;
+                    }
+                }
+            }
+            // Param type annotations
+            if (c.callerFile && c.callerStartLine) {
+                const callerSymbol = index.findEnclosingFunction(c.callerFile, c.line, true);
+                if (callerSymbol && callerSymbol.paramsStructured) {
+                    for (const param of callerSymbol.paramsStructured) {
+                        if (param.name === r && param.type) {
+                            const typeMatches = param.type.match(/\b([A-Za-z_]\w*)\b/g);
+                            if (typeMatches && typeMatches.some(t => t === targetClassName)) {
+                                return true;
+                            }
+                            return false;
+                        }
+                    }
+                }
+            }
+            // Unique method heuristic
+            const methodDefs = index.symbols.get(name);
+            if (methodDefs) {
+                const classNames = new Set();
+                for (const d of methodDefs) {
+                    if (d.className) classNames.add(d.className);
+                }
+                if (classNames.size === 1 && classNames.has(targetClassName)) {
+                    return true;
+                }
+            }
+            return false;
+        });
+    }
+
+    // Apply the same isMethodCall / non-method filter verify uses.
+    const defIsMethod = !!(def.isMethod || def.type === 'method' || def.className);
+    const targetBasename = path.basename(def.file, path.extname(def.file));
+    const defFileEntry = index.files.get(def.file);
+    const defLang = defFileEntry?.language;
+
+    const importNameCache = new Map();
+    function getImportedNames(filePath) {
+        if (importNameCache.has(filePath)) return importNameCache.get(filePath);
+        const names = new Set();
+        const fe = index.files.get(filePath);
+        if (!fe) { importNameCache.set(filePath, names); return names; }
+        try {
+            const content = index._readFile(filePath);
+            const { imports: rawImports, importAliases } = extractImports(content, fe.language);
+            for (const imp of rawImports) {
+                if (imp.names) for (const n of imp.names) names.add(n);
+            }
+            if (importAliases) for (const alias of importAliases) names.add(alias.local);
+        } catch (e) { /* skip */ }
+        importNameCache.set(filePath, names);
+        return names;
+    }
+
+    const sites = [];
+    for (const c of callerResults) {
+        const call = {
+            file: c.file,
+            relativePath: c.relativePath,
+            line: c.line,
+            content: c.content,
+            usageType: 'call',
+            receiver: c.receiver,
+        };
+        const analysis = analyzeCallSite(index, call, name);
+
+        if (analysis.isMethodCall && !defIsMethod) {
+            const callReceiver = call.receiver;
+            if (callReceiver && callReceiver === targetBasename) {
+                const importedNames = getImportedNames(call.file);
+                if (!importedNames.has(callReceiver)) continue;
+            } else if (callReceiver && langTraits(defLang)?.hasReceiverPackageCalls) {
+                const targetDir = path.basename(path.dirname(def.file));
+                if (callReceiver !== targetDir) continue;
+            } else if (callReceiver && isNamespaceContainerFor(index, callReceiver, name, def.file)) {
+                // BUG-BX: TS namespace-qualified call — accept.
+            } else {
+                continue;
+            }
+        }
+
+        sites.push({
+            file: call.relativePath,
+            line: call.line,
+            expression: (call.content || '').trim(),
+            args: analysis.args,
+            argCount: analysis.argCount,
+        });
+    }
+    clearTreeCache(index);
+    // Stable ordering (matches CLAUDE.md rule #11): files alphabetical, sites by line ascending.
+    sites.sort((a, b) => {
+        const fc = String(a.file).localeCompare(String(b.file));
+        if (fc !== 0) return fc;
+        return (a.line || 0) - (b.line || 0);
+    });
+    return sites;
+}
+
+/**
+ * Compute the same scopeWarning that impact() returns for plan output.
+ * @param {object} index - ProjectIndex instance
+ * @param {string} name - Function name
+ * @param {object} def - Resolved definition
+ * @param {object} options
+ * @returns {object|null}
+ */
+function computePlanScopeWarning(index, name, def, options) {
+    const defIsMethod = !!(def.isMethod || def.type === 'method' || def.className);
+    if (!defIsMethod) return null;
+    const allDefs = index.symbols.get(name);
+    if (!allDefs || allDefs.length <= 1) return null;
+    const classNames = [...new Set(allDefs
+        .filter(d => d.className && d.className !== def.className)
+        .map(d => d.className))];
+    if (classNames.length === 0) return null;
+    if (options.className || options.file) return null;
+    return {
+        targetClass: def.className || '(unknown)',
+        otherClasses: classNames,
+        hint: `Results may include calls to ${classNames.join(', ')}.${name}(). Use file= or className= to narrow scope.`
+    };
+}
+
 /**
  * Analyze a call site to understand how it's being called (AST-based)
  * @param {object} index - ProjectIndex instance
@@ -121,8 +709,17 @@ function analyzeCallSite(index, call, funcName) {
             }
         }
 
+        // Feature A/B: classify the call site by structural context.
+        // inLoop/inTry/inCallback come from walking up to the fn boundary.
+        // awaited comes from the immediate parent (await_expression).
+        // inTestCase is computed by the caller via the enclosing function's
+        // entry-point kind — analyzeCallSite doesn't have that info here, so
+        // it's left to be filled in by impact()/about() etc. that have
+        // access to the enclosing-function symbol.
+        const ctx = classifyCallContext(callNode, language);
+
         const argsNode = callNode.childForFieldName('arguments');
-        if (!argsNode) return { args: [], argCount: 0, isMethodCall };
+        if (!argsNode) return { args: [], argCount: 0, isMethodCall, ...ctx };
 
         const args = [];
         for (let i = 0; i < argsNode.namedChildCount; i++) {
@@ -134,13 +731,155 @@ function analyzeCallSite(index, call, funcName) {
             argCount: args.length,
             hasSpread: args.some(a => a.startsWith('...')),
             hasVariable: args.some(a => /^[a-zA-Z_]\w*$/.test(a)),
-            isMethodCall
+            isMethodCall,
+            ...ctx,
         };
     } catch (e) {
         return { args: null, argCount: 0 };
     }
 }
 
+/**
+ * Argument shape analysis for a call site (used by `example --diverse`).
+ *
+ * Returns a per-arg list of AST node types ("string_literal", "number_literal",
+ * "identifier", "member_expression", "call_expression", "arrow_function",
+ * "object", "array", "spread", "other") derived directly from tree-sitter,
+ * plus a stable "shape key" that callers can use for clustering.
+ *
+ * Returns null when the call node can't be located (parse failure, file unreadable).
+ *
+ * @param {object} index - ProjectIndex instance
+ * @param {string} filePath - Absolute file path
+ * @param {number} lineNum - 1-indexed line of the call
+ * @param {string} funcName - Function name being called
+ * @returns {{argKinds: string[], argTexts: string[], argCount: number, shapeKey: string}|null}
+ */
+function analyzeCallShape(index, filePath, lineNum, funcName) {
+    try {
+        const language = detectLanguage(filePath);
+        if (!language) return null;
+
+        // Reuse tree cache to avoid re-parsing during a batch (clustering scans many sites)
+        let tree = index._treeCache?.get(filePath);
+        if (!tree) {
+            const content = index._readFile(filePath);
+            if (language === 'html') {
+                const htmlModule = getLanguageModule('html');
+                const htmlParser = getParser('html');
+                const jsParser = getParser('javascript');
+                if (!htmlParser || !jsParser) return null;
+                const blocks = htmlModule.extractScriptBlocks(content, htmlParser);
+                if (blocks.length === 0) return null;
+                const virtualJS = htmlModule.buildVirtualJSContent(content, blocks);
+                tree = safeParse(jsParser, virtualJS);
+            } else {
+                const parser = getParser(language);
+                if (!parser) return null;
+                tree = safeParse(parser, content);
+            }
+            if (!tree) return null;
+            if (!index._treeCache) index._treeCache = new Map();
+            index._treeCache.set(filePath, tree);
+        }
+
+        const callTypes = new Set(['call_expression', 'call', 'method_invocation', 'object_creation_expression']);
+        const callNode = findCallNode(tree.rootNode, callTypes, lineNum - 1, funcName);
+        if (!callNode) return null;
+
+        const argsNode = callNode.childForFieldName('arguments');
+        if (!argsNode) {
+            return { argKinds: [], argTexts: [], argCount: 0, shapeKey: '0:' };
+        }
+
+        const argKinds = [];
+        const argTexts = [];
+        for (let i = 0; i < argsNode.namedChildCount; i++) {
+            const argNode = argsNode.namedChild(i);
+            argKinds.push(classifyArgNode(argNode));
+            argTexts.push(argNode.text.trim());
+        }
+
+        const shapeKey = `${argKinds.length}:${argKinds.join(',')}`;
+        return {
+            argKinds,
+            argTexts,
+            argCount: argKinds.length,
+            shapeKey,
+        };
+    } catch (e) {
+        return null;
+    }
+}
+
+/**
+ * Map a tree-sitter argument node to a coarse "kind" tag for shape clustering.
+ * The mapping is intentionally tight — a call passing `getUser()` should cluster
+ * with another call passing `loadConfig()` (both `call_expression`), but NOT
+ * with one passing `42` (a `number_literal`).
+ *
+ * Cross-language note: tree-sitter grammars use slightly different node names
+ * (`string_literal` vs `string`, `integer` vs `number_literal`). We canonicalize
+ * to a small set so a JS sample and a Python sample produce the same shape key.
+ */
+function classifyArgNode(node) {
+    if (!node) return 'other';
+    const t = node.type;
+    // Strings
+    if (t === 'string' || t === 'string_literal' || t === 'template_string' ||
+        t === 'raw_string_literal' || t === 'interpreted_string_literal') {
+        return 'string_literal';
+    }
+    // Numbers
+    if (t === 'number' || t === 'integer' || t === 'float' || t === 'number_literal' ||
+        t === 'integer_literal' || t === 'float_literal' || t === 'decimal_integer_literal' ||
+        t === 'hex_integer_literal' || t === 'real_literal') {
+        return 'number_literal';
+    }
+    // Booleans + null
+    if (t === 'true' || t === 'false' || t === 'null' || t === 'null_literal' ||
+        t === 'boolean_literal' || t === 'none' || t === 'nil') {
+        return 'literal';
+    }
+    // Identifiers (bare variable name)
+    if (t === 'identifier' || t === 'shorthand_property_identifier' ||
+        t === 'name' || t === 'simple_identifier' || t === 'type_identifier') {
+        return 'identifier';
+    }
+    // Member access: obj.attr / obj.method (no call)
+    if (t === 'member_expression' || t === 'attribute' || t === 'selector_expression' ||
+        t === 'field_expression' || t === 'field_access' || t === 'scoped_identifier') {
+        return 'member_expression';
+    }
+    // Nested calls: foo(getThing())
+    if (t === 'call_expression' || t === 'call' || t === 'method_invocation' ||
+        t === 'object_creation_expression' || t === 'macro_invocation') {
+        return 'call_expression';
+    }
+    // Anonymous functions
+    if (t === 'arrow_function' || t === 'function_expression' || t === 'function' ||
+        t === 'lambda' || t === 'closure_expression' || t === 'function_literal' ||
+        t === 'lambda_expression') {
+        return 'arrow_function';
+    }
+    // Object/struct literals
+    if (t === 'object' || t === 'object_expression' || t === 'dictionary' ||
+        t === 'struct_expression' || t === 'composite_literal') {
+        return 'object';
+    }
+    // Array/list literals
+    if (t === 'array' || t === 'array_expression' || t === 'list' || t === 'tuple' ||
+        t === 'array_literal') {
+        return 'array';
+    }
+    // Spread / unpacking
+    if (t === 'spread_element' || t === 'spread' || t === 'list_splat' ||
+        t === 'dictionary_splat') {
+        return 'spread';
+    }
+    return 'other';
+}
+
 /**
  * Identify common calling patterns
  * @param {Array} callSites - Array of call site objects
@@ -152,15 +891,25 @@ function identifyCallPatterns(callSites, funcName) {
         constantArgs: 0,    // Call sites with literal/constant arguments
         variableArgs: 0,    // Call sites passing variables
         chainedCalls: 0,    // Calls that are part of method chains
-        awaitedCalls: 0,    // Async calls with await
-        spreadCalls: 0      // Calls using spread operator
+        awaitedCalls: 0,    // Async calls with await (AST-derived from site.awaited)
+        spreadCalls: 0,     // Calls using spread operator
+        // Feature A: structural classification counts.
+        inLoop: 0,          // Call sites inside a loop construct
+        inTry: 0,           // Call sites inside a try block
+        inCallback: 0,      // Call sites inside a callback fn passed as an argument
+        inTestCase: 0       // Call sites whose enclosing function is a test entry
     };
 
     for (const site of callSites) {
         const expr = site.expression;
 
         if (site.hasSpread) patterns.spreadCalls++;
-        if (/await\s/.test(expr)) patterns.awaitedCalls++;
+        // Feature B: prefer the AST-derived `awaited` signal (set by
+        // analyzeCallSite's classifyCallContext walk). Fall back to a text
+        // check on the expression for callers that still pass legacy sites.
+        if (site.awaited === true || (site.awaited !== false && /\bawait\s/.test(expr))) {
+            patterns.awaitedCalls++;
+        }
         if (new RegExp('\\.' + escapeRegExp(funcName) + '\\s*\\(').test(expr)) patterns.chainedCalls++;
 
         if (site.args && site.args.length > 0) {
@@ -171,6 +920,14 @@ function identifyCallPatterns(callSites, funcName) {
             if (hasLiteral) patterns.constantArgs++;
             if (site.hasVariable) patterns.variableArgs++;
         }
+
+        // Feature A counters — these flags are set on each site by
+        // analyzeCallSite (inLoop/inTry/inCallback) or by the caller after
+        // looking up the enclosing function (inTestCase).
+        if (site.inLoop) patterns.inLoop++;
+        if (site.inTry) patterns.inTry++;
+        if (site.inCallback) patterns.inCallback++;
+        if (site.inTestCase) patterns.inTestCase++;
     }
 
     return patterns;
@@ -186,7 +943,7 @@ function identifyCallPatterns(callSites, funcName) {
 function verify(index, name, options = {}) {
     index._beginOp();
     try {
-    const { def } = index.resolveSymbol(name, { file: options.file, className: options.className });
+    const { def } = index.resolveSymbol(name, { file: options.file, className: options.className, line: options.line });
     if (!def) {
         return { found: false, function: name };
     }
@@ -194,7 +951,10 @@ function verify(index, name, options = {}) {
     // (callers don't pass self/cls explicitly: obj.method(a, b) not obj.method(obj, a, b))
     const fileEntry = index.files.get(def.file);
     const lang = fileEntry?.language;
-    let params = def.paramsStructured || [];
+    // BUG-BY: enrich types for arrow functions whose types live on the
+    // enclosing variable_declarator's type_annotation rather than inline.
+    const arrowTypes = extractArrowTypesFromVarDecl(index, def);
+    let params = (arrowTypes?.paramsStructured) || def.paramsStructured || [];
     const selfParams = langTraits(lang)?.selfParam;
     if (selfParams && params.length > 0 && selfParams.includes(params[0].name)) {
         params = params.slice(1);
@@ -208,9 +968,18 @@ function verify(index, name, options = {}) {
 
     // Get all call sites using findCallers for accurate resolution
     // (usages-based approach misses calls when className is set or local names collide)
+    // BUG-H3: accept user-supplied flag. The default keeps the historical behavior:
+    // findCallers always returns method calls (so callers like obj.method() are seen),
+    // and the secondary filter below drops them when verifying a non-method def
+    // (e.g. dict.get() vs standalone get()). Passing --include-methods opts out of
+    // the secondary filter so all method-style calls are treated as candidates.
+    const verifyIncludeMethods = options.includeMethods === true;
+    const verifyIncludeUncertain = options.includeUncertain ?? false;
     let callerResults = index.findCallers(name, {
+        // Always pass true to findCallers so method calls are visible — the secondary
+        // filter inside verify is the one that does the policy-driven filtering.
         includeMethods: true,
-        includeUncertain: false,
+        includeUncertain: verifyIncludeUncertain,
         targetDefinitions: [def],
     });
 
@@ -285,7 +1054,8 @@ function verify(index, name, options = {}) {
         });
     }
 
-    // Convert caller results to usage-like objects for analyzeCallSite
+    // Convert caller results to usage-like objects for analyzeCallSite.
+    // Carry callerFile/callerStartLine through so we can compute inTestCase.
     const calls = callerResults.map(c => ({
         file: c.file,
         relativePath: c.relativePath,
@@ -293,6 +1063,8 @@ function verify(index, name, options = {}) {
         content: c.content,
         usageType: 'call',
         receiver: c.receiver,
+        callerFile: c.callerFile,
+        callerStartLine: c.callerStartLine,
     }));
 
     const valid = [];
@@ -330,6 +1102,18 @@ function verify(index, name, options = {}) {
         return names;
     }
 
+    // Helper: extract pattern flags (Feature A/B) from analyzeCallSite result.
+    // Reused so each valid/mismatch/uncertain entry carries the same shape.
+    function patternFlagsFrom(a) {
+        return {
+            inLoop: !!a.inLoop,
+            inTry: !!a.inTry,
+            inCallback: !!a.inCallback,
+            awaited: !!a.awaited,
+            // inTestCase filled in below via tagInTestCase
+        };
+    }
+
     for (const call of calls) {
         const analysis = analyzeCallSite(index, call, name);
 
@@ -338,7 +1122,11 @@ function verify(index, name, options = {}) {
         // Allow module-level calls only when:
         // 1. Receiver matches target file's basename (e.g., jobs == jobs for jobs.py)
         // 2. Receiver is an imported name (not a local variable)
-        if (analysis.isMethodCall && !defIsMethod) {
+        // BUG-H3: when verifyIncludeMethods is true, keep method-style calls that
+        // findCallers already accepted (binding/import resolution did the heavy lifting).
+        // The receiver-based filtering below is a secondary safety net — skip it when
+        // user explicitly opted into method calls.
+        if (analysis.isMethodCall && !defIsMethod && !verifyIncludeMethods) {
             const callReceiver = call.receiver;
             if (callReceiver && callReceiver === targetBasename) {
                 const importedNames = getImportedNames(call.file);
@@ -353,18 +1141,32 @@ function verify(index, name, options = {}) {
                     continue;
                 }
                 // Receiver matches package directory — keep it
+            } else if (callReceiver && isNamespaceContainerFor(index, callReceiver, name, def.file)) {
+                // BUG-BX: TS namespace-qualified call (e.g. `Utils.helper()` where
+                // `Utils` is a `namespace` symbol containing `helper`). Treat the
+                // call as a direct invocation of the namespace member function.
+                // Same handling for class static methods and module containers.
             } else {
                 continue;
             }
         }
 
+        // Carry callerFile/callerStartLine so tagInTestCase can resolve the
+        // enclosing function in a later pass.
+        const carry = {
+            callerFile: call.callerFile,
+            callerStartLine: call.callerStartLine,
+        };
+
         if (analysis.args === null) {
             // Couldn't parse arguments
             uncertain.push({
                 file: call.relativePath,
                 line: call.line,
                 expression: call.content.trim(),
-                reason: 'Could not parse call arguments'
+                reason: 'Could not parse call arguments',
+                patterns: patternFlagsFrom(analysis),
+                ...carry,
             });
             continue;
         }
@@ -375,7 +1177,9 @@ function verify(index, name, options = {}) {
                 file: call.relativePath,
                 line: call.line,
                 expression: call.content.trim(),
-                reason: 'Uses spread operator'
+                reason: 'Uses spread operator',
+                patterns: patternFlagsFrom(analysis),
+                ...carry,
             });
             continue;
         }
@@ -386,7 +1190,12 @@ function verify(index, name, options = {}) {
         if (hasRest) {
             // With rest param, need at least minArgs
             if (argCount >= minArgs) {
-                valid.push({ file: call.relativePath, line: call.line });
+                valid.push({
+                    file: call.relativePath,
+                    line: call.line,
+                    patterns: patternFlagsFrom(analysis),
+                    ...carry,
+                });
             } else {
                 mismatches.push({
                     file: call.relativePath,
@@ -394,13 +1203,20 @@ function verify(index, name, options = {}) {
                     expression: call.content.trim(),
                     expected: `at least ${minArgs} arg(s)`,
                     actual: argCount,
-                    args: analysis.args
+                    args: analysis.args,
+                    patterns: patternFlagsFrom(analysis),
+                    ...carry,
                 });
             }
         } else {
             // Without rest, need between minArgs and expectedParamCount
             if (argCount >= minArgs && argCount <= expectedParamCount) {
-                valid.push({ file: call.relativePath, line: call.line });
+                valid.push({
+                    file: call.relativePath,
+                    line: call.line,
+                    patterns: patternFlagsFrom(analysis),
+                    ...carry,
+                });
             } else {
                 mismatches.push({
                     file: call.relativePath,
@@ -410,13 +1226,47 @@ function verify(index, name, options = {}) {
                         ? `${expectedParamCount} arg(s)`
                         : `${minArgs}-${expectedParamCount} arg(s)`,
                     actual: argCount,
-                    args: analysis.args
+                    args: analysis.args,
+                    patterns: patternFlagsFrom(analysis),
+                    ...carry,
                 });
             }
         }
     }
     clearTreeCache(index);
 
+    // Feature A: tag each entry with `inTestCase` based on its enclosing function.
+    // Done after the per-call loop because tagInTestCase prefers a single pass
+    // through file metadata to avoid repeated lookups.
+    {
+        const { tagInTestCase } = require('./analysis');
+        // Build a flat list of entries that need tagging — each carries
+        // callerFile + callerStartLine + line. tagInTestCase mutates in place.
+        const allSites = [...valid, ...mismatches, ...uncertain].map(s => ({
+            ...s,
+            // Mirror inputs tagInTestCase expects
+            line: s.line,
+            callerFile: s.callerFile,
+            callerStartLine: s.callerStartLine,
+        }));
+        // Use a parallel array so we can write back patterns.inTestCase.
+        tagInTestCase(index, allSites);
+        let i = 0;
+        for (const s of valid) { s.patterns.inTestCase = !!allSites[i++].inTestCase; }
+        for (const s of mismatches) { s.patterns.inTestCase = !!allSites[i++].inTestCase; }
+        for (const s of uncertain) { s.patterns.inTestCase = !!allSites[i++].inTestCase; }
+    }
+
+    // Strip carry fields — they were internal scaffolding for tagInTestCase
+    // and shouldn't appear in the public result.
+    function strip(arr) {
+        for (const s of arr) {
+            delete s.callerFile;
+            delete s.callerStartLine;
+        }
+    }
+    strip(valid); strip(mismatches); strip(uncertain);
+
     // Detect scope pollution for methods
     let scopeWarning = null;
     if (defIsMethod) {
@@ -435,12 +1285,35 @@ function verify(index, name, options = {}) {
         }
     }
 
+    // Feature A/B: build a top-level patterns aggregate across all call
+    // sites verify saw (valid + mismatches + uncertain). Mirrors the shape
+    // identifyCallPatterns returns in impact() so consumers can compare.
+    const allSitesForAgg = [...valid, ...mismatches, ...uncertain].map(s => ({
+        // identifyCallPatterns reads site.expression / site.args / site.hasSpread /
+        // site.hasVariable and the boolean pattern flags.
+        expression: s.expression || '',
+        args: s.args || null,
+        hasSpread: false,    // already filtered out into uncertain
+        hasVariable: false,  // not propagated from analyzeCallSite here; harmless
+        awaited: !!(s.patterns && s.patterns.awaited),
+        inLoop: !!(s.patterns && s.patterns.inLoop),
+        inTry: !!(s.patterns && s.patterns.inTry),
+        inCallback: !!(s.patterns && s.patterns.inCallback),
+        inTestCase: !!(s.patterns && s.patterns.inTestCase),
+    }));
+    const patternsAgg = identifyCallPatterns(allSitesForAgg, name);
+
     return {
         found: true,
         function: name,
         file: def.relativePath,
         startLine: def.startLine,
-        signature: index.formatSignature(def),
+        // BUG-BV: use local TS-correct param formatter (`opt?: number`, not `opt: number?`).
+        // BUG-BY: when the def is a typed arrow declaration, render with enriched types.
+        signature: formatTypedSignature(def, arrowTypes ? {
+            paramsStructured: arrowTypes.paramsStructured,
+            returnType: arrowTypes.returnType
+        } : {}),
         params: params.map(p => ({
             name: p.name,
             optional: p.optional || p.default !== undefined,
@@ -451,8 +1324,10 @@ function verify(index, name, options = {}) {
         valid: valid.length,
         mismatches: mismatches.length,
         uncertain: uncertain.length,
+        validDetails: valid,
         mismatchDetails: mismatches,
         uncertainDetails: uncertain,
+        patterns: patternsAgg,
         scopeWarning
     };
     } finally { index._endOp(); }
@@ -473,11 +1348,40 @@ function plan(index, name, options = {}) {
         return { found: false, function: name };
     }
 
-    const resolved = index.resolveSymbol(name, { file: options.file, className: options.className });
+    const resolved = index.resolveSymbol(name, { file: options.file, className: options.className, line: options.line });
     const def = resolved.def || definitions[0];
-    const impact = index.impact(name, { file: options.file, className: options.className });
-    const currentParams = def.paramsStructured || [];
-    const currentSignature = index.formatSignature(def);
+    // BUG-BY: enrich types for typed-arrow-fn declarations.
+    const arrowTypes = extractArrowTypesFromVarDecl(index, def);
+    const currentParams = (arrowTypes?.paramsStructured) || def.paramsStructured || [];
+    // BUG-BV: render with TS-correct param formatting (`opt?: number`).
+    const currentSignature = formatTypedSignature(def, arrowTypes ? {
+        paramsStructured: arrowTypes.paramsStructured,
+        returnType: arrowTypes.returnType
+    } : {});
+
+    // BUG-BW: plan must discover call sites the same way verify does for class
+    // methods. Previously plan relied on `index.impact()` whose filter rejected
+    // calls with unresolved receivers (e.g. `this.field.method()`), even when
+    // verify's filter accepts them. Compute call sites locally to keep plan
+    // and verify in lock-step.
+    const planCallSites = computePlanCallSites(index, name, def, options);
+    const impactScopeWarning = computePlanScopeWarning(index, name, def, options);
+
+    // Reject ambiguous multi-op invocations rather than silently coalescing.
+    // The previous behavior reported only the *last* operation in the
+    // headline, which made plan output untrustworthy for multi-op refactors.
+    const requestedOps = [
+        options.addParam ? 'addParam' : null,
+        options.removeParam ? 'removeParam' : null,
+        options.renameTo ? 'renameTo' : null,
+    ].filter(Boolean);
+    if (requestedOps.length > 1) {
+        return {
+            found: true,
+            function: name,
+            error: `plan accepts one operation at a time; got ${requestedOps.length}: ${requestedOps.join(', ')}. Run separately and compose results.`,
+        };
+    }
 
     let newParams = [...currentParams];
     let newSignature = currentSignature;
@@ -522,32 +1426,28 @@ function plan(index, name, options = {}) {
             }
         }
 
-        // Generate new signature
-        const paramsList = newParams.map(p => {
-            let str = (p.rest && !p.name.startsWith('*')) ? `...${p.name}` : p.name;
-            if (p.optional && !p.default) str += '?';
-            if (p.type) str += `: ${p.type}`;
-            if (p.default) str += ` = ${p.default}`;
-            return str;
-        }).join(', ');
-        const asyncPrefix = (def.async || def.isAsync || def.modifiers?.includes('async')) ? 'async ' : '';
-        newSignature = `${asyncPrefix}${name}(${paramsList})`;
-        if (def.returnType) newSignature += `: ${def.returnType}`;
+        // Generate new signature with TS-correct optional marker (BUG-BV)
+        // and arrow-fn enriched return type (BUG-BY).
+        // BUG-5: preserve all modifier tokens (async/static/public/...).
+        const paramsList = newParams.map(formatTypedParam).filter(Boolean).join(', ');
+        const modTokens = computeModifierTokens(def);
+        const modPrefix = modTokens.length ? modTokens.join(' ') + ' ' : '';
+        newSignature = `${modPrefix}${name}(${paramsList})`;
+        const newRet = arrowTypes?.returnType || def.returnType;
+        if (newRet) newSignature += `: ${newRet}`;
 
         // Describe changes needed at each call site
-        for (const fileGroup of impact.byFile) {
-            for (const site of fileGroup.sites) {
-                const suggestion = options.defaultValue
-                    ? `No change needed (has default value)`
-                    : `Add argument: ${options.addParam}`;
-                changes.push({
-                    file: site.file,
-                    line: site.line,
-                    expression: site.expression,
-                    suggestion,
-                    args: site.args
-                });
-            }
+        for (const site of planCallSites) {
+            const suggestion = options.defaultValue
+                ? `No change needed (has default value)`
+                : `Add argument: ${options.addParam}`;
+            changes.push({
+                file: site.file,
+                line: site.line,
+                expression: site.expression,
+                suggestion,
+                args: site.args
+            });
         }
     }
 
@@ -570,17 +1470,15 @@ function plan(index, name, options = {}) {
 
         newParams = currentParams.filter(p => p.name !== removeTarget);
 
-        // Generate new signature
-        const paramsList = newParams.map(p => {
-            let str = (p.rest && !p.name.startsWith('*')) ? `...${p.name}` : p.name;
-            if (p.optional && !p.default) str += '?';
-            if (p.type) str += `: ${p.type}`;
-            if (p.default) str += ` = ${p.default}`;
-            return str;
-        }).join(', ');
-        const asyncPrefix = (def.async || def.isAsync || def.modifiers?.includes('async')) ? 'async ' : '';
-        newSignature = `${asyncPrefix}${name}(${paramsList})`;
-        if (def.returnType) newSignature += `: ${def.returnType}`;
+        // Generate new signature with TS-correct optional marker (BUG-BV)
+        // and arrow-fn enriched return type (BUG-BY).
+        // BUG-5: preserve all modifier tokens (async/static/public/...).
+        const paramsList = newParams.map(formatTypedParam).filter(Boolean).join(', ');
+        const modTokens = computeModifierTokens(def);
+        const modPrefix = modTokens.length ? modTokens.join(' ') + ' ' : '';
+        newSignature = `${modPrefix}${name}(${paramsList})`;
+        const newRet = arrowTypes?.returnType || def.returnType;
+        if (newRet) newSignature += `: ${newRet}`;
 
         // For Python/Rust methods, self/cls/&self/&mut self is in paramsStructured
         // but callers don't pass it. Adjust paramIndex to caller-side position.
@@ -594,17 +1492,15 @@ function plan(index, name, options = {}) {
         const callerArgIndex = paramIndex - selfOffset;
 
         // Describe changes at each call site
-        for (const fileGroup of impact.byFile) {
-            for (const site of fileGroup.sites) {
-                if (site.args && site.argCount > callerArgIndex) {
-                    changes.push({
-                        file: site.file,
-                        line: site.line,
-                        expression: site.expression,
-                        suggestion: `Remove argument ${callerArgIndex + 1}: ${site.args[callerArgIndex] || '?'}`,
-                        args: site.args
-                    });
-                }
+        for (const site of planCallSites) {
+            if (site.args && site.argCount > callerArgIndex) {
+                changes.push({
+                    file: site.file,
+                    line: site.line,
+                    expression: site.expression,
+                    suggestion: `Remove argument ${callerArgIndex + 1}: ${site.args[callerArgIndex] || '?'}`,
+                    args: site.args
+                });
             }
         }
     }
@@ -614,20 +1510,18 @@ function plan(index, name, options = {}) {
         newSignature = currentSignature.replace(new RegExp('\\b' + escapeRegExp(name) + '\\b'), options.renameTo);
 
         // All call sites need renaming
-        for (const fileGroup of impact.byFile) {
-            for (const site of fileGroup.sites) {
-                const newExpression = site.expression.replace(
-                    new RegExp('\\b' + escapeRegExp(name) + '\\b'),
-                    options.renameTo
-                );
-                changes.push({
-                    file: site.file,
-                    line: site.line,
-                    expression: site.expression,
-                    suggestion: `Rename to: ${newExpression}`,
-                    newExpression
-                });
-            }
+        for (const site of planCallSites) {
+            const newExpression = site.expression.replace(
+                new RegExp('\\b' + escapeRegExp(name) + '\\b'),
+                options.renameTo
+            );
+            changes.push({
+                file: site.file,
+                line: site.line,
+                expression: site.expression,
+                suggestion: `Rename to: ${newExpression}`,
+                newExpression
+            });
         }
 
         // Also include import statements that reference the renamed function
@@ -662,26 +1556,19 @@ function plan(index, name, options = {}) {
         operation,
         before: {
             signature: currentSignature,
-            params: currentParams.map(p => {
-                let n = p.name;
-                if (p.optional && !p.default) n += '?';
-                if (p.type) n += `: ${p.type}`;
-                return n;
-            })
+            // BUG-BV: TS-correct optional marker (`opt?: number`); test contract
+            // expects name-keyed array entries (no ` = default`, no rest prefix)
+            // so callers can `.includes('paramName')` for exact match.
+            params: currentParams.map(p => formatPlanParamName(p)).filter(Boolean)
         },
         after: {
             signature: newSignature,
-            params: newParams.map(p => {
-                let n = p.name;
-                if (p.optional && !p.default) n += '?';
-                if (p.type) n += `: ${p.type}`;
-                return n;
-            })
+            params: newParams.map(p => formatPlanParamName(p)).filter(Boolean)
         },
         totalChanges: changes.length,
         filesAffected: new Set(changes.map(c => c.file)).size,
         changes,
-        scopeWarning: impact?.scopeWarning || null
+        scopeWarning: impactScopeWarning
     };
     } finally { index._endOp(); }
 }
@@ -760,4 +1647,4 @@ function analyzeCallSiteAST(index, filePath, lineNum, funcName) {
     return result;
 }
 
-module.exports = { verify, plan, analyzeCallSite, analyzeCallSiteAST, findCallNode, clearTreeCache, identifyCallPatterns };
+module.exports = { verify, plan, analyzeCallSite, analyzeCallSiteAST, analyzeCallShape, classifyArgNode, findCallNode, clearTreeCache, identifyCallPatterns };