Any body edit alongside a rename loses the rename AND the behaviour change

[n1ckyb]

Found by two independent UAT testers, reproduced on the 0.0.2b1 wheel.

Extracting a helper destroys rename detection, and the behaviour change disappears entirely.

Reproduction

old.py

import os
import sys

def calculate_total(items):
    total = 0
    for i in items:
        total += i.price * i.qty
    return min(total, 50)

new.py — rename, extract a helper, and change one literal

import sys
import os

def _subtotal(i):
    return i.price * i.qty

def compute_order_total(items):
    total = 0
    for i in items:
        total += _subtotal(i)
    return min(total, 75)

$ intentumdiff file old.py new.py
| Changes   3      |
| DELETION | Delete function_definition('calculate_total')        |
| ADDITION | Insert -> function_definition('_subtotal')           |
| ADDITION | Insert -> function_definition('compute_order_total') |

Two defects

1. The rename is not detected. A delete/add pair is exactly what a line diff gives. The control proves the capability exists and is specifically lost:

$ intentumdiff file o2.py n2.py     # rename ALONE, nothing else
| REFACTORING | Rename function_definition('calculate_total') -> ('compute_order_total') |

So rename detection works — until a helper is extracted alongside it. That is the realistic case: people rename while refactoring.

2. The behaviour change is missing. min(total, 50) → min(total, 75) raises the discount cap by 50% and appears nowhere in the output. Three changes reported, all structural. A reviewer trusting this sees a refactor and approves it.

The second is worse than the first. A missed rename is a weaker answer; a missed behaviour change is a wrong one.

This is the headline claim

The product's pitch is telling a refactor from a real change. On the canonical refactor — extract method plus rename — it does neither: no refactoring reported, and the one behaviour change swallowed.

On 0.0.1 it failed differently, and confidently

The VS Code UAT (extension 0.0.2-beta.1 against engine 0.0.1, the only combination installable today) got a wrong answer at full confidence rather than no answer:

Refactoring · Internal · Renamed calculate_total -> _subtotal   (100%)
Meaningful  · Behavior · Added function compute_order_total

The rename points at the newly extracted helper, and the renamed original is reported as a new function — the two categories inverted, asserted at 100%. Whatever changed between 0.0.1 and 0.0.2b1 removed the false positive but did not produce a correct answer.

Expected

• compute_order_total recognised as the rename of calculate_total
• _subtotal recognised as an extraction, not an unrelated addition
• The 50 → 75 change reported as a meaningful behaviour change, prominently

Fix should include

Per the repo rule, both a Rust #[cfg(test)] test and a Python acceptance test, using this exact fixture — rename + extraction + one literal change in a single file. It is small, canonical, and currently answered wrongly.

[n1ckyb]

Root cause located — rename pairing is keyed on node id equality

crates/rust-core-host/src/draft_promotions.rs, promote_same_id_identifier_renames_from_add_delete_drafts (line ~108):

let deleted_by_id: HashMap<&str, &SemanticNode> = changes
    .iter()
    .filter(|change| change.change_type == "DELETION")
    .filter_map(|change| change.old_node)
    .filter(|node| node.node_type == "identifier" && !node.label.is_empty())
    .map(|node| (node.id.as_str(), node))
    .collect();

// ...then, for each ADDITION identifier:
let Some(old_node) = deleted_by_id.get(new_node.id.as_str()) else {
    continue;                      // <-- no id match, no rename
};

A DELETION and an ADDITION are only paired into a rename when old and new share the same node.id. The function name is even in the function name: promote_same_id_....

That explains the observed behaviour exactly:

• rename alone → the identifier keeps its id, ids match, REFACTORING / RENAME_SYMBOL is promoted ✅
• rename + a new sibling function → inserting _subtotal ahead of it changes the renamed function's id, the lookup misses, and it falls through as an unrelated DELETION + ADDITION ❌

So the capability is not "weak on complex diffs" — it is structurally unable to survive a sibling insertion, because identity is positional. Extract-method always inserts a sibling, which is why the canonical refactor is exactly the case that fails.

Why this also explains the second half of the bug

The min(total, 50) → min(total, 75) change disappearing is likely downstream of the same thing: with the rename unpaired, the old function is a whole-subtree DELETION and the new one a whole-subtree ADDITION, so there is no surviving node pair for the literal change to be attached to. It is not "missed" so much as swallowed by two coarse structural changes. Worth confirming rather than assuming.

Next steps for whoever picks this up

1. Confirm the id scheme. Establish whether SemanticNode.id encodes sibling position/child index. If it does, that is the defect; if it is content-derived, the diagnosis above is wrong and needs redoing. Print ids for the two-function fixture in a Rust test — the DTO does not expose them, so this must be done in cargo test, not from Python.
2. Do not "fix" it by loosening the id match. Falling back to label similarity across the whole file is how false renames appear — and 0.0.1 already shipped one, confidently pairing calculate_total with the newly extracted _subtotal at 100%. That regression is worse than the current miss: a wrong answer beats no answer only for the tool, never for the reviewer.
3. Likely direction: pair on a stable identity (signature, body hash, or parent-scope + label) in addition to id, and require corroboration before promoting — the file already has promote_corroborated_variable_renames as precedent for that shape.
4. Test both directions. The fixture in the issue description must produce a rename AND the literal change; a rename-only fixture must keep working; and the 0.0.1 false pairing (calculate_total → _subtotal) must not come back. Rust #[cfg(test)] plus a Python acceptance test, per the repo rule.

Debug in cargo test — seconds per cycle, against ~20 minutes for maturin develop --release plus pytest.

[n1ckyb]

Correction: my earlier root-cause comment was wrong, and the fix built on it does not work

Verified end to end after a maturin develop --release with the change in core#33 — output byte-identical to before:

DELETION|Delete function_definition('calculate_total')
ADDITION|Insert -> function_definition('_subtotal')
ADDITION|Insert -> function_definition('compute_order_total')

[1] rename detected              : FAIL
[2] behaviour change (50 -> 75)  : FAIL
[3] rename-only still detected   : PASS
[4] no false pairing             : PASS

What I got wrong

I identified promote_same_id_identifier_renames_from_add_delete_drafts pairing on exact node-id equality, noted that ids are positional, and concluded that a sibling insertion breaks the pairing. Each of those statements is true. The conclusion does not follow.

That promotion filters on node_type == "identifier". This diff contains no identifier-level drafts — the changes are whole function_definition subtrees. The promotion never executes on this input, so its key was never the constraint.

The evidence was in the output I had already collected. I read a plausible mechanism in the code and stopped, instead of checking whether that code path runs at all on the failing case.

Where the defect actually is

Tree matching, upstream of any promotion.

• rename ALONE: bodies identical → the matcher descends → identifier-level changes → rename promoted ✅
• rename + extraction: body also changed → the matcher gives up higher in the tree → whole-subtree DELETE/ADD ❌

calculate_total and compute_order_total are never matched as the same node, so there is nothing for a rename promotion to promote.

This also explains the missing behaviour change, and resolves the open question from the issue body: with no surviving node pair, min(total, 50) → 75 has nothing to attach to. One cause, both symptoms. It is not a second defect.

Next step

Find the matcher's similarity criterion for pairing two function_definition nodes, and determine why a changed body drops the pair below it. Probably a threshold; possibly a hard requirement that bodies hash equal.

The trap remains the same and is now more dangerous, because the fix is closer to the scoring: a threshold loosened carelessly is exactly how 0.0.1 produced its confident false pairing of calculate_total → _subtotal at 100%. Any change here needs the fixture in this issue AND a test that the false pairing stays absent — check [4] above, which currently passes and must keep passing.

The verification harness is at scratchpad/verify45.py and checks all four properties in one run.

[n1ckyb]

Much broader than this issue says. Extraction is a red herring.

Measured against the built engine, varying one factor at a time:

rename only                    rename=YES   1 change
rename + literal change        rename=no    2 changes    <-- 50 -> 75
rename + body call swap        rename=no    2 changes
rename + helper ADDED above    rename=no    3 changes
rename + helper + call swap    rename=no    3 changes

Any body edit alongside a rename loses the rename. Extract-method was never the trigger; it is simply one way to edit a body.

Minimal reproduction

# old                     # new
def calc(x):              def compute(x):
    return x + 1              return x + 2

DELETION  Delete function_definition('calc')
ADDITION  Insert -> function_definition('compute')

A two-line function, a rename and one token. No rename reported, and the 1 -> 2 change does not appear at all. This is the smallest possible version of the product's headline claim, and both halves fail.

Why

min_similarity defaults to 0.5, and node matching scores with a Dice coefficient over already-mapped descendants:

2.0 * common as f64 / total as f64      // dice_node, lib.rs

For a small function, one changed token is a large fraction of its descendants. With the name node also differing, the score falls under 0.5, the two function_definition nodes are never paired, and everything downstream follows: no rename to promote, and no surviving node pair for the literal change to attach to.

It is worse for SMALL functions, which is the opposite of what you would want — a one-line change to a two-line function is proportionally huge, while the same edit inside a fifty-line function stays comfortably above threshold. The tool is least reliable exactly where a reviewer can most easily check it, which is also where they will first notice it is wrong.

Severity

I would treat this as more serious than the issue title implies. It is not an edge case in refactor detection; renaming anything while changing it is the common case in real review, and the behaviour change vanishing is worse than the missed rename — a reviewer sees a delete/add pair and no indication that behaviour moved.

What NOT to do

Do not simply lower min_similarity. The threshold exists to stop unrelated nodes being paired, and 0.0.1 already shipped the failure mode on the other side: a confident false rename pairing calculate_total with a newly extracted _subtotal at 100%. Trading a miss for a wrong answer is not progress.

Plausible directions, in rough order of safety:

1. Weight the name separately from the body. Two function_definition nodes with different names but structurally similar bodies are the exact shape of a rename; scoring the name as just another differing descendant discards the strongest signal available.
2. Floor the score by node type and arity — same type, same parameter list, same parent scope is strong corroboration independent of body similarity.
3. Size-normalise. Whatever the rule, a single token should not dominate a two-node body.

Each needs the fixture here AND the false-pairing guard (check 4 in scratchpad/verify45.py) to stay green.

[n1ckyb]

Attempted "weight the name separately". It did not work, and it degraded a working case.

Reverted. Recording it so nobody repeats it.

The real gate (this part IS confirmed)

bottom_up_match_candidate_compatible in lib.rs:

if is_named_entity_type(old_node.node_type.as_str()) {
    return old_node.label == new_node.label
        && label_match_parent_compatible(old_node, new_node, old_index, new_index);
}
true

For a named entity the labels must be equal to even be a candidate. A renamed
function_definition is rejected before dice_node is ever called, so this was never about
min_similarity — the name is an absolute veto, not a weight. That diagnosis stands and is
the useful output of this attempt.

What I tried

Replaced the boolean gate with a required-score function: same label → the configured
threshold; different label but parent-compatible → a higher bar
(min_similarity + (1 - min_similarity) / 2, i.e. 0.75 by default), so a rename is admissible
but must be corroborated by a substantially more similar body.

Rust suite stayed green — 289 passed, 0 failed, certification tests included. End to end:

[1] rename detected              : FAIL     (unchanged)
[2] behaviour change (50 -> 75)  : FAIL     (unchanged)
[3] rename-only still detected   : PASS     but now labelled "Rename VARIABLE"
[4] no false pairing             : PASS

Two problems:

1. The target case still fails. A raised bar of 0.75 is evidently not cleared by these
   pairs. That is the trap in this specific defect: the pairs hardest to clear a similarity
   bar are SMALL functions, which is exactly where one changed token is proportionally huge —
   and exactly the case in the report.
2. It degraded the control. Rename-only previously reported
   Rename function_definition('calculate_total') -> ('compute_order_total'); with the change
   it reported Rename variable 'calculate_total' -> 'compute_order_total'. A function
   described as a variable is wrong, and a fix that corrupts a case that already worked is
   worse than the miss it was trying to repair.

That second point also shows the Rust suite does not cover this: 289 tests passed while the
classification of the canonical rename changed. Whatever lands here needs an assertion on the
LABEL, not just on whether a rename was detected.

Where this leaves it

The gate is identified and confirmed. The correct relaxation is not "same bar, higher number":

• A flat higher threshold cannot work — small functions cannot clear any body-similarity bar
  after a one-token edit, and they are the common case.
• Corroboration should probably come from structure rather than body similarity: same node
  type, same arity/parameter list, same enclosing scope, and unique candidacy. Those are
  size-independent, which is the property a body-similarity score lacks.
• Whatever pairs the nodes must also produce the right ENTITY KIND downstream, or the rename
  is reported as a variable.

Still do not lower min_similarity: 0.0.1 shipped the confident false pairing
(calculate_total -> _subtotal at 100%) and that is the worse failure.

Harness: scratchpad/verify45.py checks all four properties in one run. Add a fifth before
attempting this again — that the rename is classified as a FUNCTION, not a variable.

[n1ckyb]

Third attempt: structural corroboration. Also does not fix it. Reverted.

Replaced the label veto with: same node_type, parent-compatible, and at least one
identical child structural_hash (trivial children ignored). The intent was corroboration
that is size-independent, unlike a dice score — a renamed function keeps its parameter list
byte-for-byte even when the body changed.

Rust suite green: 289 passed, 0 failed. End to end: identical output to before. No rename,
no behaviour change.

The useful new datum

An unrelated-function control behaves correctly:

def alpha(a): return a * 3   ->   def beta(b): return b - 9
    DELETION  Delete function_definition('alpha')
    ADDITION  Insert -> function_definition('beta')

So the relaxation is not producing false pairs — it simply is not producing the true pair
either. Combined with the target case still failing, that means removing this gate is not
sufficient: something else also prevents calc/compute from pairing. The label veto is
real and confirmed, but it is not the only blocker.

That is worth knowing before a fourth attempt, because all three attempts so far have assumed
this gate was the single point of failure.

Attempts and what each ruled out

1. Widen rename PROMOTION to tolerate a shifted node id — the promotion never runs on this
   input; it filters on identifier drafts and these are whole-subtree changes. Ruled out
   promotion entirely.
2. Weight the name (higher bar when labels differ) — target still failed, and it degraded
   the control's classification from function_definition to variable. Ruled out any flat
   similarity bar: the cases needing help are small functions, which cannot clear one.
3. Structural corroboration (shared child subtree) — target still failed; no false pairs
   introduced. Ruled out this gate as the sole cause.

Also observed, needs its own look

Both matcher changes (2 and 3) altered the rename-only control from
Rename function_definition(...) to Rename variable '...'. The Rust suite passed 289/289
through both, so nothing asserts the entity kind of a detected rename. A function reported
as a variable is wrong on its own terms, and the suite cannot currently see it. That gap is
worth closing regardless of how #45 is eventually fixed.

For the next attempt

Find what else blocks the pair. Suggested: instrument the bottom-up loop to log, for the
calc/compute pair specifically, whether it is reached as a candidate at all and what dice
score it receives. All three attempts so far reasoned from code reading; that measurement
would settle in one run what has now cost three rebuild cycles at ~20 minutes each.

Harness: scratchpad/verify45.py. Add the entity-kind assertion before attempting again.

[n1ckyb]

Measured. The label veto is the whole blocker — and my previous conclusion was wrong.

Added env-gated tracing to the bottom-up matcher (INTENTUMDIFF_TRACE_MATCH=1) and ran the
minimal fixture. This is what actually happens:

[match] 0.0 'calc' (function_definition) — 1 candidate(s)
[match]     vs 'compute' — gate REJECT (named=true label_eq=false parent_ok=true)
[match] 0.0.1 'x' (parameters)          — vs 'x' — gate PASS
[match] 0.0.2 'block' (block)           — vs 'block' — gate PASS
[match] 0.0.2.0 'return_statement'      — gate PASS
[match] 0.0.2.0.0 'x' (binary_operator) — gate PASS

Four facts, none of them inferred:

1. calc is reached as an unmatched old node.
2. compute is offered as a candidate — exactly one, of the right type.
3. The gate rejects it with parent_ok=true. The scope check passes; the label inequality
   alone is the reason.
4. No dice score is ever computed for the pair. Every hypothesis about thresholds and
   similarity scoring was irrelevant — scoring is never reached.

Every child of the pair matches cleanly. The two function bodies are perfectly matchable; only
the parent is refused.

This corrects my previous comment

I wrote that attempt 3 proved "removing this gate is not sufficient — something else also
blocks the pair". That was wrong. The measurement shows the veto is the sole blocker.
Attempt 3 must therefore have failed because of a defect in my corroboration helper
(renamed_entity_shares_child_structure returning false when it should not have), not because
another gate exists.

I drew a structural conclusion from one negative result instead of measuring. That is the
third time on this issue that reading code produced a confident wrong answer, and the first
measurement settled it in a single run.

What this makes the fix

Narrow and testable: for a named entity whose scope already matches, allow a differing
label to proceed to dice scoring, corroborated by something size-independent. Since scoring is
currently never reached, the open question — whether the dice score for calc/compute clears
0.5 — is still unanswered and is the next thing to measure. The trace prints it as soon as any
pair gets that far.

Note also from the trace: candidate lists here are tiny (1 candidate). The false-pairing risk
that killed 0.0.1 comes from larger files with many same-typed siblings, so any relaxation
must be tested on a file with several similar functions, not just this two-line fixture.

Instrumentation

INTENTUMDIFF_TRACE_MATCH=1 in bottom_up_match — prints per old node: candidate count, and
per candidate the gate result with named / label_eq / parent_ok broken out, plus the dice
score when scoring is reached. Currently local only. Worth landing behind the env var: it
turned a three-attempt guessing exercise into one run.

[n1ckyb]

Prior-art research changes the diagnosis materially. Two gates, not one — and one of them is a field-name bug.

1. The label gate is a misreading of GumTree

In the GumTree paper, label means the grammar production name — the node TYPE, not the identifier text:

"Labels of nodes correspond to the name of their production rule in the grammar... a label, which maps to structural elements of the source code (such as MethodDeclaration or NumberLiteral), and a value that corresponds to the actual tokens" — ASE'14 §2

So the paper's bottom-up rule label(t1) = label(c) means same node type. GumTree's own code compares parent.getType() == src.getType() and never compares identifiers in the bottom-up phase.

Our bottom_up_match_candidate_compatible compares old_node.label == new_node.label — the identifier. We already enforce the real (type) gate at lib.rs:7586 via new_by_type. The label check is a duplicate of the type check applied to the wrong field.

It is also largely dead: the seeding pass at lib.rs:7423 keys new_by_type_label on (node_type, label) and has already paired every same-name entity before bottom-up runs. For a named entity, bottom-up can now only rediscover what seeding found. Verified — both line numbers check out.

2. But there is a SECOND gate, and it is the direct cause

draft_suppressors.rs:121:

|| !rename_body_is_unchanged(old_node, new_node)

A rename is only promoted when the body did not change. That is exactly our failing case, stated as a rule. Even if the matcher paired the nodes, promotion would still refuse.

So #45 needs both fixed. My earlier measurement found gate 1 and stopped; it was never the whole story.

3. Where the 0.0.1 false positive came from — not Dice

promote_same_id_named_renames_from_add_delete_drafts pairs DELETION with ADDITION on old_node.id == new_node.id with confidence: 1.0 hardcoded (draft_suppressors.rs:136, and again at 367 and 444). Node ids are positional, so that is a structural-id collision, not a similarity judgement. It is the same class as GumTree's documented failure where 130 getter/setter pairs swapped position and produced 260 false renames in one commit.

rename_body_is_unchanged was evidently the over-correction for that. It trades every real rename-with-edit for safety.

4. Do NOT simply delete the label gate

Plain GumTree is measured at 28.2% precision on Rename Method (RefactoringMiner TSE 2020, Table 9) — roughly 72% of its reported renames are invented. The paper names our exact scenario as a known failure:

"when a relatively large portion of a method is extracted to a new method, GUMTREE DIFF tends to match the original method in the parent commit with the extracted method in the child commit, resulting in RENAME METHOD false positives."

tool	Rename Method precision	recall
GumTree 2.1.2	28.2%	74.9%
RefDiff 1.0 (τ=0.3)	85.5%	81.1%
RefDiff 2.0 (τ=0.5)	94.6%	69.4%
RefactoringMiner 2.0	98.2%	87.9%

5. The transferable guard — symmetric vs containment similarity

RefDiff uses two similarity functions and this is the key idea:

sim(e1,e2)  = Σ min / Σ max      ← weighted Jaccard: RENAME
simp(e1,e2) = Σ min / Σ w(e1)    ← containment:      EXTRACT/INLINE

On our own false positive: calculate_total (40 nodes) vs _subtotal (8 shared) — symmetric ≈ 8/40 = 0.2, rejected; containment = 8/8 = 1.0, which is exactly the "100%" that shipped. Every serious tool normalises renames by the LARGER side: git uses max_size, GumTree's Chawathe uses max(|src|,|dst|), RefDiff uses Σmax.

Our dice_node already uses the symmetric denominator. The work is auditing the hardcoded confidence: 1.0 sites, not the matcher.

Suggested shape, in dependency order

1. Replace hardcoded confidence: 1.0 with the measured symmetric similarity, and drop rename_body_is_unchanged in favour of that score. This alone may fix Any body edit alongside a rename loses the rename AND the behaviour change #45.
2. Require the old entity to be a genuine non-survivor before it can be a rename source (RefactoringMiner's decisive guard is set arithmetic, not similarity — if the original still exists, no rename is possible).
3. Add git's size-asymmetry pre-reject: refuse when the size difference exceeds half the larger side, before scoring anything.
4. Decline when best and second-best candidates are within a margin — given our constraint, emit nothing rather than guess.
5. Only then reconsider the label gate, with the type gate and scope gate still in force.

Worth knowing regardless

difftastic solves the half we underrate. It never pairs named entities at all — a changed identifier is just a novel leaf, and the surrounding structure still aligns, so the 1→2 change would never vanish. If the intolerable symptom is the disappearing body change rather than the missing rename label, that is a cheaper fix than any of this.

ChangeDistiller is actively wrong for us — it relaxes its threshold to 0.4 for nodes with ≤4 leaves, i.e. more permissive exactly where we fail.

Nobody hits 100%. The best purpose-built detector still invents ~1 rename in 50. If "no invented renames" is literal, the honest design is to attach the body change correctly and decline to label the pairing when confidence is low.

Sources: GumTree ASE'14 · RefactoringMiner TSE'20 · RefDiff MSR'17 · RefDiff 2.0 · Fan et al. ICSE'21 · git diffcore-rename.c · difftastic

[n1ckyb]

Second research pass — the guard we are missing is ANCHORING, not a threshold

Primary sources read directly (GumTree HEAD, Dotzler's thesis, IJM ICSE'18, ChangeDistiller TSE'07, ZS'89, Chawathe'96).

GumTree has never had a label gate

// MappingStore.java:243 — every matcher funnels through this
public boolean isMappingAllowed(Tree src, Tree dst) {
    return src.hasSameType(dst) && areBothUnmapped(src, dst);
}

Type and occupancy. No label comparison anywhere in the bottom-up phase. Confirms the field-name misreading from the previous comment.

What makes label-blindness safe — this is the part to copy

// GreedyBottomUpMatcher.getDstCandidates
if (parent.getType() == src.getType() && !(mappings.isDstMapped(parent) || parent.isRoot()))
    candidates.add(parent);

Candidates are only proposed if they are ancestors of an already-mapped descendant. Two containers sharing no matched content can never be paired. The safety comes from anchoring, not from a similarity cutoff — which is why GumTree can afford to ignore names entirely.

Our matcher buckets candidates by type (new_by_type, lib.rs:7586) with no anchoring requirement, then compensates with a label gate. That is the trade made backwards.

And this explains the small-node failure better than any threshold theory

Bottom-up only considers non-leaves and only proposes anchored candidates. For def calc(x): return x+1 → def compute(x): return x+2, if nothing inside anchors, the function has zero candidates regardless of any threshold.

Our trace showed one candidate and a label rejection, so anchoring did happen here — but it means threshold tuning was never going to be the lever.

Two things that would have made it worse

IJM's name gate would REJECT our case. Its rule is weighted-Levenshtein distance < 0.3 for declarations; calc→compute is ~0.86. IJM exists because GumTree matched fields↔iterator and isEmpty↔hasNext on structure alone — the opposite failure. Its measured benefit is real (UPDATE misclassification 40% → 17%) but it is tuned against a problem we do not have.

Do not port GumTree's ChangeDistiller reimplementation. ChangeDistillerLeavesMatcher.java sorts mappings ascending by similarity and then takes remove(0) — the least similar pair first. Independently confirmed as a real defect in Dotzler's thesis ("the sort order of leaves was wrong"), which retracted MTDIFF's headline result from 98% to 43.7% once fixed. Still present at HEAD. Its structSimThreshold2 field also silently initialises to 0.6 instead of 0.4, so the small-subtree relaxation does not exist unless configure() is called.

The guard that fits our constraint best

SimpleBottomUpMatcher.histogramMatching: among unmapped children of a matched parent, pair two nodes iff each is the only remaining unmapped child of its type. Label-blind, but forced rather than guessed — it declines when ambiguous. Given we shipped a confident false rename, a mechanism that structurally cannot guess is worth more than one that guesses well.

Revised shape

1. Anchoring as the primary guard — require candidates to be ancestors of an already-mapped descendant, matching GumTree.
2. Then delete the label gate, keeping type + scope. Not before: without anchoring it is the only thing preventing arbitrary pairings.
3. Uniqueness/histogram pairing for the remainder — decline when ambiguous.
4. Name as a weighted relabel cost (1 - qGrams(labels), cross-type infinite), never a gate. Under any ZS-admissible cost model relabel is never dearer than delete+insert, so a same-type pair should always prefer alignment.
5. Replace the hardcoded confidence: 1.0 with measured symmetric similarity, and retire rename_body_is_unchanged.

Steps 1–2 are a pair. Doing 2 without 1 is how GumTree gets 28.2% precision.

[n1ckyb]

Third research pass — RefDiff and git, read from source and measured

Two mature, independent implementations converged on the same algorithm shape, which is a strong signal about what to build:

Score all candidate pairs → sort descending → consume greedily with a hard 1:1 conflict rule.

Neither uses optimal assignment. RefDiff considered and did not use Hungarian; git's own comments concede the greedy pairing is sub-optimal and accept it. If we were going to reach for something clever, two mature tools decided it was not worth it.

The shared invariant: an implicit 2x size-ratio bound

Both gate at 0.5, and both therefore reject any pair whose sizes differ by more than 2x — before scoring:

• RefDiff, arithmetically: sim(A,B) <= W(smaller)/W(larger) because the denominator is a max. Below 2x you cannot reach 0.5.
• git, explicitly, in estimate_similarity before any hashing:

  if (max_size * (MAX_SCORE-minimum_score) < delta_size * MAX_SCORE)
      return 0;

This is the single most important thing both share, and it is exactly what kills the calculate_total -> _subtotal pairing on arithmetic alone.

Rename vs extract is a STRUCTURAL decision, not a threshold fight

RefDiff's separation, which is the most transferable idea in all three research passes:

	measure	denominator
RENAME / MOVE	symmetric	max
EXTRACT / INLINE	asymmetric containment	the candidate's own weight

Plus two non-similarity guards:

• Phase ordering — matchExtract() runs LAST, after all matching. Anything already matched is out of the added/removed sets.
• "The original must still exist" — Extract requires the source method to have matched its own after-version, while Rename consumes a removed node. Structurally exclusive; a pair cannot be both.
• Extract additionally requires a call-graph edge: the new node must be called by a method present on both sides, and is compared against the code that vanished from the caller, not the caller itself.

Neither has a minimum-size floor, and git rejected the idea deliberately

Jeff King, in the --rename-empty commit:

"One more flexible alternative would be to allow the caller to specify a minimum size for a blob to be 'interesting'... But that would catch small boilerplate files, not large ones (e.g., if you had the GPL COPYING file in many directories)."

Size does not predict boilerplate-ness. Worth remembering before we add one.

Measured: git on tiny files, and it DOES invent renames

case	score
3 lines, 1 changed	R070
3 lines, 2 changed	R035 — rejected at default
3 lines, all changed	no rename at any threshold
1 line, that line edited	no rename at any threshold
20 lines, 1 changed	R095

The same edit scores 70% on a 3-line file and 95% on a 20-line one. Scores are quantised at ~1/N, and at N=1 it is binary. And measured directly — four small YAML files sharing two boilerplate lines produced:

D    beta.yml
R064 alpha.yml -> epsilon.yml     <-- unrelated files, matched on boilerplate
A    zeta.yml

So git has our failure mode too; it is tolerable there only because git detects renames rather than tracking them — nothing is persisted, a wrong guess is cosmetic and recomputed every time. We surface renames as review intent, so a false one is far more costly for us than for git.

Git's precision comes from the exact pass, not the similarity index

find_exact_renames() runs first, unconditionally, matching on blob SHA — zero false positives — and consumes those candidates before any fuzzy work. Tie-broken on basename. The similarity heuristic only ever sees the residue.

That is the cheap high-precision layer we do not have: an exact-identity pass that consumes candidates before anything fuzzy runs. Our structural_hash is the natural key.

Consolidated recommendation across all three research passes

1. Exact-identity pass first, consuming candidates (git's model). structural_hash equality, tie-broken by scope.
2. Anchoring as the candidate guard (GumTree): candidates must be ancestors of an already-mapped descendant.
3. Symmetric similarity for rename, containment for extract (RefDiff) — this is what makes the two structurally distinguishable rather than threshold-separated.
4. 2x size-ratio pre-reject before scoring (both).
5. Decline when ambiguous — uniqueness/histogram pairing rather than best-guess.
6. Then remove the label gate, and replace hardcoded confidence: 1.0 with the measured symmetric score, retiring rename_body_is_unchanged.

Steps 1-2 are what make step 6 safe. Doing 6 alone is how GumTree gets 28.2% precision.

[n1ckyb]

Correction to my earlier comment, and the strongest idea found so far

I was wrong that IJM would reject calc -> compute

I wrote that IJM's name gate (< 0.3) would refuse that pair. A deeper read of the source rather than the paper shows the paper's sentence is inverted relative to the code:

• Paper: "two names are considered similar if they have a distance of < 0.3"
• Code: StringMetrics.levenshtein().compare() returns a normalised similarity, and the gate is simVal >= 0.3 — i.e. distance <= 0.7, roughly 25x more permissive.

Verified against the project's own unit tests (targetSim = 0.3d): assertEquals/assertFalse scores 0.667 and passes; public/private scores 0.143 and is rejected. Every test outcome matches "similarity >= 0.3", none match "distance < 0.3".

So IJM would very likely accept our pair. My earlier claim was based on the paper's wording; do not act on it.

Two further caveats on IJM if we borrow from it:

• The gate lives only in lastChanceMatch (Zhang-Shasha recovery), never in the main matching loop. Container matching is still pure Jaccard with no name check. "Name-aware bottom-up" describes the recovery step, not the decision.
• Its test suite is entirely @Ignored, including the assertions encoding the anti-false-positive intent (assertMethodMatchNotExists("checkInheritedMethods", "findReplacedMethod")). Those pairs score 0.429 and would pass the shipped gate.

The idea worth taking, corroborated independently

Fold the identifier into the node's label and delete the redundant name child.

IJM does this in its AST builder: a method declaration's node carries the method name as its label, and the separate SimpleName child is not emitted. Because the label enters the subtree hash, the top-down isomorphism pass can no longer match foo() to bar() — rename/move confusion becomes structurally impossible rather than threshold-dependent.

Independently measured by Fan et al. (ICSE 2021), differential testing over 263,165 file revisions: type-confusion errors (mapped tokens of different types) — GumTree 29, MTDiff 24, IJM 0.

But note the cost, measured

The same study shows IJM trades one error class for another: statement-scope errors (mapped tokens in unmapped statements) — GumTree 71, MTDiff 84, IJM 146. That is the predictable price of container partitioning: IJM's own paper states that "a move from a method body to a different method body cannot be detected" unless the subtree is byte-identical.

Overall IJM is measured at 21-30% inaccurate file revisions vs GumTree's 20-29% — marginally worse overall. Its genuine win is the misclassification rate on the actions we care about: MOVE 58.2% -> 43.5%, UPDATE 40% -> 17%.

Also worth knowing before citing IJM's headline: its "12 -> 9 edits" is not comparable — it ran on a reduced AST while the baselines ran on the full one, which the authors concede and which led Matsumoto et al. to refuse to benchmark against it.

Net effect on the plan

Nothing in the earlier recommendation changes, but the ordering firms up. The two ideas with independent measured support are:

1. Identifier-in-label (IJM) — eliminates a whole error class outright, zero threshold tuning.
2. Exact-identity pass first, consuming candidates (git) — where git's real precision comes from; the fuzzy score only ever adjudicates the residue.

Both are structural. Neither is a threshold. Given four failed attempts here have all been threshold or gate tweaks, that is the direction I would take.

[n1ckyb]

Identifier-in-label is ALREADY implemented here. That direction is closed.

The research's strongest recommendation — IJM's "merged name nodes", the one idea with
independent measured support (Fan et al.: 0 type-confusion errors vs GumTree's 29) — turns out
to be something this engine already does. Measured, not inferred:

[match] 0.0   'calc' (function_definition)   <- the NAME is the node's label
[match] 0.0.1 'x'    (parameters)            <- children start at .1
[match] 0.0.2 'block'(block)

There is no separate identifier child at 0.0.0; the child indices skip straight to .1. The
function's name is carried on the function_definition node itself, and
synthetic_structural_hash already folds the label into the hash. That is precisely IJM's
design, already in place.

This explains the label gate. IJM gets its name discipline implicitly: because the name
is in the label and the label is in the subtree hash, the top-down isomorphism pass simply
cannot match foo() to bar(). Someone here appears to have reached for an explicit
label == gate to get the same discipline — and over-applied it, because the hash already
provided it for the top-down phase, while the explicit gate additionally kills the bottom-up
phase, which is the one that is supposed to recover renames.

So we have IJM's guard AND a redundant gate on top, and the redundant one is the defect.

Attempts to date: five, all the same shape

#	approach	outcome
1	widen rename promotion (shifted node id)	promotion never runs on this input
2	weight the name (higher bar when labels differ)	no fix; degraded entity kind to variable
3	structural corroboration (shared child subtree)	no fix; no false pairs either
4	name-excluded dice + relaxed gate (agent)	byte-identical to baseline; agent recommended reverting
5	identifier-in-label	already implemented — nothing to do

Every one of 1-4 was a tweak to the same gate, and the measured trace says the gate is the sole
rejection reason. That combination is strange enough to be the next thing to investigate: the
gate rejects, yet removing or relaxing it changes nothing observable. Attempt 3 and attempt 4
independently confirm that.

The next question is therefore not "how do we relax the gate" but "what happens after the
gate passes". Something downstream is discarding the pair even when bottom-up admits it —
rename_body_is_unchanged at draft_suppressors.rs:121 is the obvious candidate, since it
requires the body to be UNCHANGED and our case changes it by construction.

That would explain every result above: relaxing the matcher lets the pair through, and the
promotion then throws it away for a different reason. Nobody has yet tested the two changes
TOGETHER.

Cheapest next experiment

Relax the gate and drop rename_body_is_unchanged in the same build, then run the harness.
One maturin develop --release, not four. If the rename appears, the fix is the pair of
changes and the remaining work is bounding the false-positive risk (symmetric similarity,
size-ratio reject, decline-when-ambiguous). If it still does not, there is a third gate and the
trace should be extended into the promotion path to find it.