[anakanemison]

Part 7 of 23 of a stacked series (tracking issue: #35). Based on U06-say-what-convergence-covers, the previous part: review and merge that first.

Kind: report. Lab proposal: P3.

What the migration runs showed

Every graphicsgems migration needed 30 to 32 target_map entries, none of them a rename. With basename alignment, target_map holds only real renames (082: 30 entries to 0).

The change

The CMake model keys executables by bare target name (BinRec), the Bazel
model by package-qualified label (gems:BinRec). Executables align by exact
name, so every executable in a non-root package needed a target_map entry
even when nothing was renamed, which buries the entries that record real
renames.

Measured in any2bazel-lab: two graphicsgems migrations wrote 32 and 26
target_map entries, none of them a rename; every entry bridged a bare
CMake name to its package-qualified Bazel label.

After target_map is applied, each CMake executable that still has no
exact-name counterpart aligns with the Bazel executable whose label
basename equals its name, when exactly one unaligned Bazel executable has
that basename. Two packages sharing the basename are left unaligned
(missing_target plus extra_target, as before) for target_map to resolve;
libraries, external-repo labels, and CMake names that are target_map keys
(even when the mapped Bazel target does not exist) never align this way.
The pairs are reported in diff.json as "aligned_by_basename" so the
implicit matches stay reviewable. The alignment is part of _bazel_renames,
the one rename decision the diff and every summary share, so an
exclude_targets entry for an auto-aligned executable is honoured the same
way by the comparison, the excluded list, the levels and the NDEBUG
counts. SKILL.md now reserves target_map for renames and ambiguous
basenames.

In the lab's later graphicsgems run with this change, target_map was empty
(the earlier run had 30 entries).

Testing

pytest tests/ at this commit: 186 passed (130 on main).

🤖 Generated with Claude Code

[armandomontanez]

In the lab's later graphicsgems run with this change, target_map was empty
(the earlier run had 30 entries).

How valuable is it to optimize this? Target remapping everything seems relatively low cost.

For CMake, basename is appropriate since target names are guaranteed globally unique. For GN builds, and I think Soong, basenames aren't guaranteed to be unique as they use forms of scoping (like Bazel).

Another way to look at this problem is how we might use default target name maps to suggest where build files that contain the targets should live. e.g. if we can find map bssl to the cmake file that declared it, we can expect a bssl target to exist in a sibling BULID.bazel to the source CMakeLists.txt file.