Skip to content

feat: suggest a move, and where it goes, for a tangle of files - #41

Merged
alecf merged 13 commits into
mainfrom
feat/cut-moves
Nov 13, 2026
Merged

alecf merged 13 commits into
mainfrom
feat/cut-moves

Conversation

@alecf

@alecf alecf commented Nov 13, 2026

Copy link
Copy Markdown
Owner

What changes

When every member of a tangle is a file, thicket searches for declarations to move instead of an edge to cut.

  • Each move takes along every helper the moved code uses.
  • The report prints suggested move:, move to: and leaves:.
  • The chart draws each edge the move removes as a dotted move · arrow.
  • The JSON gains a move field.
  • Dissolves still apply first.
  • A tangle of directories keeps the edge search. So does a file tangle that no move breaks.

There is no off switch. AGENTS.md §4b now reserves flags for opinions that hide a file or a finding.

Code

  • src/extract/symbols.ts reads each file's bindings, declaration spans and identifier uses. Project.symbolsOf memoizes it.
  • src/graph/moves.ts holds the move search and the home ranking.
  • src/run.ts tries a move before the edge cut. src/report/markdown.ts renders it.

Evidence

  • Round 5, pairwise on 30 tangles. Blind judges preferred the move to the edge cut 19 times to 8.
  • Round 5, homes on 114 moves. The computed home was rated good 71% of the time. The importing file was rated good 16% of the time.
  • Home ranking. The ranking now prefers an existing file that is as safe as a new one. It keeps the judged pick on 34 of 45 moves. Two judges rated the other 11 new picks good 6 and 7 times, against 2 and 1 for the old picks.
  • Agreement with the prototype. On four public repositories, the core picks the same move as the prototype in every tangle except 4. In those 4, a dissolve now does part or all of the work.
  • Run time. No measurable change: about 29 s on one repository, on main and on this branch.

The prototype work and rounds 4 and 5 are recorded in docs/plans/2026-11-11-placement.md.

Tests

  • tests/moves.test.ts, with the new fixture tests/fixtures/moves/
  • The golden report and the README sample are regenerated.
  • Typecheck and the boundary check are clean. All 831 vitest tests pass.
  • Removing the existing-first rule, the package check or the helper closure each fails a test.

🤖 Generated with Claude Code

https://claude.ai/code/session_01S7cyneSpBhH5XCwE3t8w1Y

alecf and others added 13 commits November 12, 2026 11:24
A symbol on a cut often uses a type or constant declared beside it. Left
behind, that helper makes the new home import the old file, and the cut
edge comes back. The prototype now moves the whole closure. When code that
stays also uses a helper, the old file imports it from the new home.

Also count only a variable statement's own declarators as top-level names.
A walk found the locals inside function bodies too, and each one looked
like a helper.

At file granularity on four public repositories, the best home now frees
the cycle for 107 of 111 placed cuts, up from 59.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01S7cyneSpBhH5XCwE3t8w1Y
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01S7cyneSpBhH5XCwE3t8w1Y
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01S7cyneSpBhH5XCwE3t8w1Y
The cut search scores one edge at a time and never asks how much code a
cut moves. A move can remove several edges into one file at once, when
they all import the same declaration. The prototype now tries moves: a
declaration that a tangle file imports, or every declaration on one edge,
with its helpers. It ranks them by the largest cycle left, then the
largest runtime cycle, then the lines moved.

Erasure is decided per binding: `import type`, or a name an interface or
type alias declares. A new file is named after the first declaration the
move was asked for, instead of `moved.ts`.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01S7cyneSpBhH5XCwE3t8w1Y
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01S7cyneSpBhH5XCwE3t8w1Y
A `const` and an `interface` can share a name. The prototype kept one span
per name, so a move took the `const` and left the `interface` behind, and
the cycle stayed. A round 5 judge caught it. Function overloads had the
same problem.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01S7cyneSpBhH5XCwE3t8w1Y
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01S7cyneSpBhH5XCwE3t8w1Y
When every member of a tangle is a file, thicket now searches for
declarations to move instead of an edge to cut. Each move takes its
helpers along. The report prints `suggested move:` and `move to:`, and
the JSON gains a `move` field. A module tangle keeps the edge search,
and so does a file tangle no move breaks.

Blind judges preferred the move to the edge cut 19 times to 8. The home
ranking prefers an existing file that is just as safe as a new one. On
the 11 judged homes that changed, two judges rated the new pick good 6
and 7 times, against 2 and 1 for the old pick.

There is no off switch. AGENTS.md §4b now reserves flags for opinions
that hide something.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01S7cyneSpBhH5XCwE3t8w1Y
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01S7cyneSpBhH5XCwE3t8w1Y
Round 6 judged the shipped output, and all five preregistered bars held.
The judges' reasons exposed two bugs. `leaves:` measured the cycle left
with the code in a new file, so it overstated what remains when the home
is an existing file. And two rejected homes were files that only
re-export.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01S7cyneSpBhH5XCwE3t8w1Y
Some generators write no banner, so the banner scan misses their output,
and the move search picked such files as homes. A file named `*.gen.ts`
is now skipped like a generated directory. The denominator skips it too.
The report counts these files on their own, and --include-generated
brings them back.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01S7cyneSpBhH5XCwE3t8w1Y
Three fixes to the cycle a move is said to leave. Only the tangle's files
and the home count, not a cycle the home was already in. Edges the report
dissolves first are dropped in the home check too, as in the search. And
a file that re-exports from the owner beside code of its own keeps its
edge, because symbolsOf now records every `export … from` target.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01S7cyneSpBhH5XCwE3t8w1Y
@alecf
alecf merged commit edc7297 into main Nov 13, 2026
10 checks passed
@alecf
alecf deleted the feat/cut-moves branch November 13, 2026 04:11
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant