ucn 4.0.1 → 4.1.0

package/core/verify.js

@@ -7,8 +7,7 @@
 
 const path = require('path');
 const { detectLanguage, getParser, getLanguageModule, safeParse, langTraits } = require('../languages');
-const { escapeRegExp } = require('./shared');
-const { extractImports } = require('./imports');
+const { escapeRegExp, codeUnitCompare } = require('./shared');
 
 // ============================================================================
 // CALL-SITE CLASSIFICATION (Feature A)
@@ -141,9 +140,21 @@ function classifyCallContext(callNode, language) {
 /**
  * Find a call expression node at the target line matching funcName
  */
-function findCallNode(node, callTypes, targetRow, funcName) {
+function findCallNode(node, callTypes, targetRow, funcName, occurrence = 0) {
+    // Several same-name calls can share one line (`greet("a") + greet("b")`,
+    // f-strings) — fix #231: callers pass the site's per-line ordinal so each
+    // record is arg-checked against ITS OWN node, not the line's first.
+    // Records and this walk are both pre-order, so ordinals align; an
+    // out-of-range ordinal falls back to the first match (never worse than
+    // the pre-fix behavior when a parse shape hides a node).
+    const matches = _collectCallNodes(node, callTypes, targetRow, funcName, occurrence + 1);
+    return matches[occurrence] || matches[0] || null;
+}
+
+function _collectCallNodes(node, callTypes, targetRow, funcName, limit, out = []) {
+    if (out.length >= limit) return out;
     if (node.startPosition.row > targetRow || node.endPosition.row < targetRow) {
-        return null; // Skip nodes that don't contain the target line
+        return out; // Skip nodes that don't contain the target line
     }
 
     if (callTypes.has(node.type) && node.startPosition.row <= targetRow && node.endPosition.row >= targetRow) {
@@ -153,7 +164,16 @@ function findCallNode(node, callTypes, targetRow, funcName) {
             if (typeNode) {
                 // Strip generics and package qualifiers: com.foo.Bar<T> -> Bar
                 const typeName = typeNode.text.replace(/<.*>$/, '').split('.').pop();
-                if (typeName === funcName) return node;
+                if (typeName === funcName) out.push(node);
+            }
+        } else if (node.type === 'new_expression') {
+            // 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');
+            if (ctorNode) {
+                const typeName = ctorNode.text.replace(/<.*>$/, '').split('.').pop();
+                if (typeName === funcName) out.push(node);
             }
         } else {
             // Check if this call is for our target function
@@ -169,17 +189,19 @@ function findCallNode(node, callTypes, targetRow, funcName) {
                     : funcNode.type === 'scoped_identifier'
                     ? (funcNode.childForFieldName('name') || funcNode.namedChild(funcNode.namedChildCount - 1))?.text
                     : funcNode.text;
-                if (funcText === funcName) return node;
+                if (funcText === funcName) out.push(node);
             }
         }
+        if (out.length >= limit) return out;
     }
 
-    // Recurse into children
+    // Recurse into children — nested same-name calls (`greet(greet(x))`)
+    // are separate records, so a match's children are still scanned.
     for (let i = 0; i < node.childCount; i++) {
-        const result = findCallNode(node.child(i), callTypes, targetRow, funcName);
-        if (result) return result;
+        _collectCallNodes(node.child(i), callTypes, targetRow, funcName, limit, out);
+        if (out.length >= limit) return out;
     }
-    return null;
+    return out;
 }
 
 /**
@@ -439,149 +461,184 @@ function extractArrowTypesFromVarDecl(index, def) {
 }
 
 /**
- * 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.
+ * Constructor parameter lists for a CLASS verify/plan target (fix #230): a
+ * class def carries no paramsStructured, so `verify Task` used to arg-check
+ * `new Task(id, name)` against 0..0 — a false red on every parameterized
+ * constructor, in every language. Sources: indexed constructor members
+ * (JS/TS `constructor`, Python `__init__` — emitted with type
+ * 'constructor'), or a Java AST walk (constructors are deliberately not
+ * indexed as members there). Returns an array of paramsStructured lists —
+ * one per constructor overload — or null when the class declares none.
  * @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}
+ * @param {object} def - Resolved definition (any type; non-class returns null)
+ * @param {string} lang - The definition file's language
+ * @returns {Array<Array<object>>|null}
  */
-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';
+function _constructorParamLists(index, def, lang) {
+    if (!def || !def.file || !['class', 'enum', 'record'].includes(def.type)) return null;
+    const lists = [];
+    const endLine = def.endLine != null ? def.endLine : Infinity;
+    const inRange = (d) => d.file === def.file &&
+        d.startLine >= def.startLine && d.startLine <= endLine &&
+        Array.isArray(d.paramsStructured);
+    for (const ctorName of ['constructor', '__init__']) {
+        for (const d of (index.symbols.get(ctorName) || [])) {
+            if (d.className === def.name && inRange(d)) lists.push(d.paramsStructured);
         }
-        return false;
-    });
+    }
+    // Java constructor members are named after the CLASS (enum-body
+    // constructors carry paramsStructured since fix #230).
+    for (const d of (index.symbols.get(def.name) || [])) {
+        if (d.type === 'constructor' && d.className === def.name && inRange(d)) {
+            lists.push(d.paramsStructured);
+        }
+    }
+    if (lists.length > 0) return lists;
+    if (lang !== 'java') return null;
+    let parser, content;
+    try {
+        parser = getParser('java');
+        content = index._readFile(def.file);
+    } catch (e) {
+        return null;
+    }
+    if (!parser || content == null) return null;
+    const tree = safeParse(parser, content);
+    if (!tree) return null;
+    const { parseStructuredParams } = require('../languages/utils');
+    const targetRow = def.startLine - 1;
+    let classNode = null;
+    (function findClass(node) {
+        if (classNode || !node) return;
+        if ((node.type === 'class_declaration' || node.type === 'enum_declaration' ||
+             node.type === 'record_declaration') &&
+            node.startPosition.row <= targetRow && node.endPosition.row >= targetRow) {
+            const nameNode = node.childForFieldName('name');
+            if (nameNode && nameNode.text === def.name) {
+                classNode = node;
+                return;
+            }
+        }
+        for (let i = 0; i < node.namedChildCount; i++) findClass(node.namedChild(i));
+    })(tree.rootNode);
+    if (!classNode) return null;
+    // Records declare their canonical constructor's params on the header.
+    if (classNode.type === 'record_declaration') {
+        const recParams = classNode.childForFieldName('parameters');
+        if (recParams) lists.push(parseStructuredParams(recParams, 'java') || []);
+    }
+    const collectCtors = (body) => {
+        if (!body) return;
+        for (let i = 0; i < body.namedChildCount; i++) {
+            const child = body.namedChild(i);
+            if (child.type === 'constructor_declaration') {
+                const paramsNode = child.childForFieldName('parameters');
+                lists.push(parseStructuredParams(paramsNode, 'java') || []);
+            } else if (child.type === 'enum_body_declarations') {
+                collectCtors(child);
+            }
+        }
+    };
+    collectCtors(classNode.childForFieldName('body'));
+    return lists.length > 0 ? lists : null;
 }
 
 /**
- * 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 }.
+ * v4 tiered caller sweep shared by verify and plan (BUG-BW lockstep): run
+ * findCallers in collectAccount mode and partition candidates into the
+ * confirmed band (arg-checked / planned) and the VISIBLE unverified band
+ * (rendered with reasons, never silently dropped). The pre-v4 className and
+ * receiver heuristics are gone — engine receiver physics decide tier and
+ * exclusion, and their fallback branches could silently drop true callers.
+ * Namespace-container receivers (BUG-BX `Utils.helper()`) confirm in the
+ * ENGINE since fix #254 (range-based containment + scope evidence), so no
+ * verify-local promotion remains — the bands are the sweep's verbatim.
  *
  * @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}
+ * @param {string} name - Symbol name
+ * @param {object} def - Resolved definition (pinned target)
+ * @returns {{ confirmed: Array, unverified: Array, account: object }}
  */
-function computePlanCallSites(index, name, def, options) {
-    let callerResults = index.findCallers(name, {
+function contractedCallerSweep(index, name, def) {
+    const rawCallers = index.findCallers(name, {
         includeMethods: true,
-        includeUncertain: false,
         targetDefinitions: [def],
+        collectAccount: true,
     });
 
-    // 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;
-        });
+    const confirmed = [];
+    const unverified = [];
+    for (const c of rawCallers) {
+        if (c.tier !== 'unverified') confirmed.push(c);
+        else unverified.push(c);
+    }
+    for (const u of rawCallers.unverifiedEntries || []) {
+        unverified.push(u);
     }
 
-    // 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;
+    // Conservation account from the sweep's claims (impact's manual
+    // composition).
+    const { computeGroundSet, buildAccount } = require('./account');
+    const groundSet = computeGroundSet(index, name);
+    const accountRaw = rawCallers.accountRaw || { unverifiedLines: [], excludedEntries: [] };
+    const confirmedEntries = confirmed.map(c => ({ file: c.file, line: c.line }));
+    const unverifiedEntries = [
+        ...accountRaw.unverifiedLines,
+        ...unverified.map(u => ({ file: u.file, line: u.line })),
+    ];
+    for (const s of rawCallers.shadowEntries || []) {
+        (s.tier === 'unverified' ? unverifiedEntries : confirmedEntries).push({ file: s.file, line: s.line });
     }
+    const account = buildAccount(index, name, {
+        groundSet,
+        confirmedEntries,
+        unverifiedEntries,
+        excludedEntries: accountRaw.excludedEntries,
+    });
+
+    // Ground call-lines no engine candidate claimed: visible one-liners
+    // (already counted unverified in the account arithmetic).
+    const { callNotResolvedEntries } = require('./analysis');
+    for (const e of callNotResolvedEntries(index, account)) unverified.push(e);
+    unverified.sort((a, b) => {
+        const ap = a.relativePath || '';
+        const bp = b.relativePath || '';
+        if (ap !== bp) return codeUnitCompare(ap, bp);
+        return (a.line || 0) - (b.line || 0);
+    });
+
+    return { confirmed, unverified, account };
+}
+
+/** Map an unverified sweep entry to the public site shape (relative `file`). */
+function unverifiedSiteShape(u) {
+    return {
+        file: u.relativePath,
+        line: u.line,
+        expression: (u.content || '').trim(),
+        callerName: u.callerName ?? null,
+        tier: 'unverified',
+        ...(u.reason && { reason: u.reason }),
+        ...(u.dispatchVia && { dispatchVia: u.dispatchVia }),
+        ...(u.dispatchCandidates != null && { dispatchCandidates: u.dispatchCandidates }),
+    };
+}
+
+/**
+ * BUG-BW: Build the list of call sites for `plan` using the SAME sweep verify
+ * uses. This guarantees plan and verify agree on which sites need updating.
+ *
+ * @param {object} index - ProjectIndex instance
+ * @param {string} name - Function name being refactored
+ * @param {object} def - Resolved definition
+ * @returns {{ sites: Array, unverifiedSites: Array, account: object }}
+ */
+function computePlanCallSites(index, name, def) {
+    const { confirmed, unverified, account } = contractedCallerSweep(index, name, def);
 
     const sites = [];
-    for (const c of callerResults) {
+    const planLineSeen = new Map(); // 'file:line' -> per-line ordinal (fix #231)
+    for (const c of confirmed) {
         const call = {
             file: c.file,
             relativePath: c.relativePath,
@@ -590,23 +647,10 @@ function computePlanCallSites(index, name, def, options) {
             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;
-            }
-        }
-
+        const siteKey = `${c.file}:${c.line}`;
+        const occurrence = planLineSeen.get(siteKey) || 0;
+        planLineSeen.set(siteKey, occurrence + 1);
+        const analysis = analyzeCallSite(index, call, name, occurrence);
         sites.push({
             file: call.relativePath,
             line: call.line,
@@ -618,11 +662,11 @@ function computePlanCallSites(index, name, def, options) {
     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));
+        const fc = codeUnitCompare(String(a.file), String(b.file));
         if (fc !== 0) return fc;
         return (a.line || 0) - (b.line || 0);
     });
-    return sites;
+    return { sites, unverifiedSites: unverified.map(unverifiedSiteShape), account };
 }
 
 /**
@@ -657,7 +701,7 @@ function computePlanScopeWarning(index, name, def, options) {
  * @param {string} funcName - Function name to find
  * @returns {object} { args, argCount, hasSpread, hasVariable }
  */
-function analyzeCallSite(index, call, funcName) {
+function analyzeCallSite(index, call, funcName, occurrence = 0) {
     try {
         const language = detectLanguage(call.file);
         if (!language) return { args: null, argCount: 0 };
@@ -687,11 +731,12 @@ function analyzeCallSite(index, call, funcName) {
         }
 
         // Call node types vary by language
-        const callTypes = new Set(['call_expression', 'call', 'method_invocation', 'object_creation_expression']);
+        const callTypes = new Set(['call_expression', 'call', 'method_invocation',
+            '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
-        const callNode = findCallNode(tree.rootNode, callTypes, targetRow, funcName);
+        const callNode = findCallNode(tree.rootNode, callTypes, targetRow, funcName, occurrence);
         if (!callNode) return { args: null, argCount: 0 };
 
         // Check if this is a method call (obj.func()) vs a direct call (func())
@@ -954,105 +999,37 @@ function verify(index, name, options = {}) {
     // 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 || [];
+    // Class target: arg-check against CONSTRUCTOR parameters (fix #230).
+    // Multiple lists = constructor overloads (Java): a call is valid when it
+    // fits the combined range; a class with only an inherited constructor
+    // (extends, no own ctor) has an arity UCN can't see — accept any count
+    // rather than false-flag every call against the implicit 0-arg default.
+    const ctorParamLists = _constructorParamLists(index, def, lang);
+    const inheritedCtorOnly = !ctorParamLists && def.type === 'class' && !!def.extends;
     const selfParams = langTraits(lang)?.selfParam;
-    if (selfParams && params.length > 0 && selfParams.includes(params[0].name)) {
-        params = params.slice(1);
-    }
-    const hasRest = params.some(p => p.rest);
-    // Rest params don't count toward expected/min — they accept 0+ extra args
-    const nonRestParams = params.filter(p => !p.rest);
-    const expectedParamCount = nonRestParams.length;
-    const optionalCount = nonRestParams.filter(p => p.optional || p.default !== undefined).length;
-    const minArgs = expectedParamCount - optionalCount;
-
-    // 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: verifyIncludeUncertain,
-        targetDefinitions: [def],
+    const stripSelf = (list) => (selfParams && list.length > 0 && list[0] && selfParams.includes(list[0].name))
+        ? list.slice(1) : list;
+    const rawParamLists = ctorParamLists ||
+        [(arrowTypes?.paramsStructured) || def.paramsStructured || []];
+    const params = stripSelf(rawParamLists[0]);
+    const arities = rawParamLists.map(l => {
+        const list = stripSelf(l);
+        const nonRest = list.filter(p => !p.rest);
+        const optional = nonRest.filter(p => p.optional || p.default !== undefined).length;
+        return { hasRest: list.some(p => p.rest), max: nonRest.length, min: nonRest.length - optional };
     });
+    const hasRest = inheritedCtorOnly || arities.some(a => a.hasRest);
+    // Rest params don't count toward expected/min — they accept 0+ extra args
+    const expectedParamCount = Math.max(...arities.map(a => a.max));
+    const minArgs = inheritedCtorOnly ? 0 : Math.min(...arities.map(a => a.min));
 
-    // When className is explicitly provided, filter out method calls whose
-    // receiver clearly belongs to a different type (same logic as impact()).
-    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;
-            // Check local variable 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;
-                        }
-                    }
-                }
-            }
-            // Check parameter type annotations: def foo(tracker: SourceTracker) → tracker.record()
-            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: if the called method exists on exactly one class
-            // and it matches the target, include the call (no other class could match)
-            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;
-                }
-            }
-            // className explicitly set but receiver type unknown — filter it out
-            return false;
-        });
-    }
+    // v4 tiered contract: the confirmed band is arg-checked below; unverified
+    // candidates stay VISIBLE in their own band with reasons (never silently
+    // dropped). Engine receiver physics replace the pre-v4 className filter
+    // and the isMethodCall secondary filter — --include-methods and
+    // --include-uncertain are implied no-ops for verify.
+    const { confirmed: callerResults, unverified: sweepUnverified, account } =
+        contractedCallerSweep(index, name, def);
 
     // Convert caller results to usage-like objects for analyzeCallSite.
     // Carry callerFile/callerStartLine through so we can compute inTestCase.
@@ -1071,36 +1048,7 @@ function verify(index, name, options = {}) {
     const mismatches = [];
     const uncertain = [];
 
-    // If the definition is NOT a method, filter out method calls (e.g., dict.get() vs get())
-    // This prevents false positives where a standalone function name matches method calls.
-    // Exception: module-level calls (module.func()) are kept when the receiver matches the
-    // target module's name and is an imported name (e.g., jobs.submit() where jobs is imported
-    // and the function lives in jobs.py).
     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;
-
-    // Build import-name lookup for receiver checking (module.func() vs dict.get())
-    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;
-    }
 
     // Helper: extract pattern flags (Feature A/B) from analyzeCallSite result.
     // Reused so each valid/mismatch/uncertain entry carries the same shape.
@@ -1114,42 +1062,12 @@ function verify(index, name, options = {}) {
         };
     }
 
+    const verifyLineSeen = new Map(); // 'file:line' -> per-line ordinal (fix #231)
     for (const call of calls) {
-        const analysis = analyzeCallSite(index, call, name);
-
-        // Skip method calls when verifying a non-method definition.
-        // This prevents false positives (e.g., dict.get() vs standalone get()).
-        // 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)
-        // 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);
-                if (!importedNames.has(callReceiver)) continue;
-                // Receiver matches target module and is imported — keep it
-            } else if (callReceiver && langTraits(defLang)?.hasReceiverPackageCalls) {
-                // Go: receiver is package alias (last segment of import path, e.g., "controller"
-                // from "k8s.io/.../pkg/controller"), not the filename ("controller_utils").
-                // Check if receiver matches the directory name of the target file.
-                const targetDir = path.basename(path.dirname(def.file));
-                if (callReceiver !== targetDir) {
-                    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;
-            }
-        }
+        const siteKey = `${call.file}:${call.line}`;
+        const occurrence = verifyLineSeen.get(siteKey) || 0;
+        verifyLineSeen.set(siteKey, occurrence + 1);
+        const analysis = analyzeCallSite(index, call, name, occurrence);
 
         // Carry callerFile/callerStartLine so tagInTestCase can resolve the
         // enclosing function in a later pass.
@@ -1184,7 +1102,20 @@ function verify(index, name, options = {}) {
             continue;
         }
 
-        const argCount = analysis.argCount;
+        let argCount = analysis.argCount;
+        // Method-expression / UFCS receiver shift (fix #230): Go
+        // `M.Add(*m, 2)` and Rust `Engine::run(&e, 1)` pass the receiver as
+        // the FIRST argument — the same +1 shift the #205 arity discipline
+        // already applies when confirming these sites. Without it the
+        // arg-check false-flagged every confirmed method-expression call.
+        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) ||
+                (qualStyle === 'path' && def.isMethod)) {
+                argCount -= 1;
+            }
+        }
 
         // Check if arg count is valid
         if (hasRest) {
@@ -1319,7 +1250,10 @@ function verify(index, name, options = {}) {
             optional: p.optional || p.default !== undefined,
             hasDefault: p.default !== undefined
         })),
-        expectedArgs: { min: minArgs, max: hasRest ? '∞' : expectedParamCount },
+        // max: null = unbounded (rest param) — typed for JSON consumers;
+        // the text formatter renders it as `${min}+` (fix #230, was the
+        // string '∞' leaking into JSON output).
+        expectedArgs: { min: minArgs, max: hasRest ? null : expectedParamCount },
         totalCalls: valid.length + mismatches.length + uncertain.length,
         valid: valid.length,
         mismatches: mismatches.length,
@@ -1327,6 +1261,11 @@ function verify(index, name, options = {}) {
         validDetails: valid,
         mismatchDetails: mismatches,
         uncertainDetails: uncertain,
+        // v4 tiered contract: candidates without binding/receiver evidence are
+        // NOT arg-checked (they may target another symbol) but stay visible.
+        unverifiedCount: sweepUnverified.length,
+        unverifiedSites: sweepUnverified.map(unverifiedSiteShape),
+        account,
         patterns: patternsAgg,
         scopeWarning
     };
@@ -1352,19 +1291,29 @@ function plan(index, name, options = {}) {
     const def = resolved.def || definitions[0];
     // BUG-BY: enrich types for typed-arrow-fn declarations.
     const arrowTypes = extractArrowTypesFromVarDecl(index, def);
-    const currentParams = (arrowTypes?.paramsStructured) || def.paramsStructured || [];
+    // Class target: the signature being planned is the CONSTRUCTOR's
+    // (fix #230, same rule as verify) — single-ctor classes only; with
+    // overloads the class def's own (empty) list stays, since plan cannot
+    // know which overload the user means.
+    const planLang = index.files.get(def.file)?.language;
+    const planCtorLists = _constructorParamLists(index, def, planLang);
+    const currentParams = (planCtorLists && planCtorLists.length === 1 && planCtorLists[0]) ||
+        (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 currentSignature = formatTypedSignature(def,
+        (planCtorLists && planCtorLists.length === 1)
+            ? { paramsStructured: currentParams }
+            : arrowTypes ? {
+                paramsStructured: arrowTypes.paramsStructured,
+                returnType: arrowTypes.returnType
+            } : {});
+
+    // BUG-BW: plan must discover call sites the same way verify does — both
+    // run contractedCallerSweep (v4 tiered contract), so plan and verify stay
+    // in lock-step by construction. Unverified candidates are NOT planned
+    // (they may target another symbol) but stay visible with reasons.
+    const { sites: planCallSites, unverifiedSites: planUnverified, account: planAccount } =
+        computePlanCallSites(index, name, def);
     const impactScopeWarning = computePlanScopeWarning(index, name, def, options);
 
     // Reject ambiguous multi-op invocations rather than silently coalescing.
@@ -1398,9 +1347,14 @@ function plan(index, name, options = {}) {
             };
         }
         operation = 'add-param';
+        // Default parameter values only exist in some languages (trait).
+        // For Go/Java/Rust a --default value is a suggested ARGUMENT for the
+        // call sites, never signature syntax — `opt = null` is not valid Go.
+        const planFileEntry = index.files.get(def.file);
+        const langHasDefaults = langTraits(planFileEntry?.language)?.hasDefaultParams !== false;
         const newParam = {
             name: options.addParam,
-            ...(options.defaultValue && { default: options.defaultValue })
+            ...(options.defaultValue && langHasDefaults && { default: options.defaultValue })
         };
 
         // When adding a param, insert before rest params (*args/**kwargs) and
@@ -1436,11 +1390,17 @@ function plan(index, name, options = {}) {
         const newRet = arrowTypes?.returnType || def.returnType;
         if (newRet) newSignature += `: ${newRet}`;
 
-        // Describe changes needed at each call site
+        // Describe changes needed at each call site. Without language support
+        // for default values, every call site must pass the new argument.
         for (const site of planCallSites) {
-            const suggestion = options.defaultValue
-                ? `No change needed (has default value)`
-                : `Add argument: ${options.addParam}`;
+            let suggestion;
+            if (options.defaultValue && langHasDefaults) {
+                suggestion = `No change needed (has default value)`;
+            } else if (options.defaultValue) {
+                suggestion = `Add argument: ${options.defaultValue} (no default parameter values in ${planFileEntry?.language || 'this language'})`;
+            } else {
+                suggestion = `Add argument: ${options.addParam}`;
+            }
             changes.push({
                 file: site.file,
                 line: site.line,
@@ -1491,16 +1451,32 @@ function plan(index, name, options = {}) {
         }
         const callerArgIndex = paramIndex - selfOffset;
 
-        // Describe changes at each call site
-        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
-                });
+        // Removing the receiver param itself (self/cls/&self): bound calls
+        // pass it implicitly — no caller-side change exists (fix #230; used
+        // to emit "Remove argument 0: ?" at every site).
+        if (callerArgIndex >= 0) {
+            // Describe changes at each call site
+            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
+                    });
+                } else if (!site.args) {
+                    // Arguments unparseable (macro bodies, generated code) —
+                    // surface for manual review instead of dropping silently
+                    // (fix #230).
+                    changes.push({
+                        file: site.file,
+                        line: site.line,
+                        expression: site.expression,
+                        suggestion: 'Could not parse arguments — review this call site manually',
+                        needsReview: true
+                    });
+                }
             }
         }
     }
@@ -1509,10 +1485,18 @@ function plan(index, name, options = {}) {
         operation = 'rename';
         newSignature = currentSignature.replace(new RegExp('\\b' + escapeRegExp(name) + '\\b'), options.renameTo);
 
-        // All call sites need renaming
+        // All call sites need renaming. Global replace: a line with several
+        // calls (`compute(compute(1))`) renames every occurrence, and the
+        // 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();
         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'),
+                new RegExp('\\b' + escapeRegExp(name) + '\\b', 'g'),
                 options.renameTo
             );
             changes.push({
@@ -1524,7 +1508,17 @@ function plan(index, name, options = {}) {
             });
         }
 
-        // Also include import statements that reference the renamed function
+        // Also include import statements that reference the renamed function.
+        // Name ownership (fix #230, the #217 rule): an import of the same
+        // NAME from an unrelated module is not this rename's import —
+        // renaming alpha.compute must not rewrite `from beta import compute`
+        // (the plan's own call-site sweep already excludes caller_b's calls
+        // as other-definition-import; the import pass has to agree).
+        // 'no' (the binding provably resolves elsewhere) skips; 'unknown'
+        // (CJS surfaces, star imports, resolver gaps) keeps the import —
+        // a missed import breaks the rename just as surely.
+        const { _nameBindingReaches } = require('./callers');
+        const renameTargetFiles = new Set([def.file]);
         const usages = index.usages(name, { codeOnly: true });
         const importUsages = usages.filter(u => u.usageType === 'import' && !u.isDefinition);
         for (const imp of importUsages) {
@@ -1533,6 +1527,10 @@ function plan(index, name, options = {}) {
                 c.file === (imp.relativePath || imp.file) && c.line === imp.line
             );
             if (alreadyCovered) continue;
+            if (imp.file && def.file &&
+                _nameBindingReaches(index, imp.file, name, renameTargetFiles) === 'no') {
+                continue;
+            }
             const newImport = imp.content.trim().replace(
                 new RegExp('\\b' + escapeRegExp(name) + '\\b'),
                 options.renameTo
@@ -1568,6 +1566,11 @@ function plan(index, name, options = {}) {
         totalChanges: changes.length,
         filesAffected: new Set(changes.map(c => c.file)).size,
         changes,
+        // 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
     };
     } finally { index._endOp(); }