Skip to content

feat: build tangles from files by default - #44

Merged
alecf merged 1 commit into
mainfrom
feat/file-tangles
Nov 14, 2026
Merged

alecf merged 1 commit into
mainfrom
feat/file-tangles

Conversation

@alecf

@alecf alecf commented Nov 14, 2026

Copy link
Copy Markdown
Owner

What changes for the reader

The ## Module tangle section now lists cycles between files, not directories, unless you pass --granularity. At file level, thicket can say which declaration to move and where. At directory level it mostly could not.

Example (the moves test fixture, 22 files):

Before, with directories as modules:

| dependency cycles | 0 (largest SCC: 0 modules) |

Every cycle sat inside one directory, so grouping by directory hid all of them.

After:

### THK-CYC-668e304f · SCC of 3 modules
- **suggested move:** `storeKey` with its helper `PREFIX` out of `src/store.ts` — 4 lines
- **move to:** `src/Lists.ts`, which uses it

### THK-CYC-79c5900b · SCC of 2 modules under `src/ext/`
- **suggested move:** `stamp` out of `core/owner.ts` — 3 lines
- **move to:** `core/base.ts`, which every user already imports

On the four public repositories:

old default new default
Tangles 11 in total 40 per repository (the cap)
Tangles with a fix 1 109 moves, plus cuts

Blind judges compared the two sections, one judge per order on each repository. The brief asked which section to hand an agent that must reduce the cycles.

old default new default
Picked as better 0 of 8 8 of 8
Mean usefulness, 0 to 3 0.9 3.0

What does not change. The duplication sections are byte-identical to the old default on all four repositories. --granularity auto still gives the old tangle view.

How it works

  • --granularity now sets only the dependency graph: the tangles, propagation cost and the header. It defaults to file.
  • Duplication ranking and placement always group by auto. A copy that spans modules weighs more. At file, every multi-file copy would span modules, which changed 7 to 15 of 45 duplication findings per repository. Those weights were fitted on judged data under auto.
  • Propagation cost and the header's module count now describe the file graph by default.
  • The config hash changes, because it includes the granularity.

Tests

  • A new test runs the callsite fixture, where the two groupings rank differently. It checks that the default ranks duplication the same as auto. Pointing the ranking at the file graph fails it.
  • Three workspace tests that check auto sizing now pass granularity: "auto".
  • The golden report and the README sample change only in the config hash.
  • 840 tests pass. Typecheck and check:boundary are clean.

Known, not fixed here

At file level an edge can show weight 0. It is a dynamic import() or a side-effect import, which binds no name. One repository has 134 of them. This predates the change, but more readers will now see it.

🤖 Generated with Claude Code

https://claude.ai/code/session_01S7cyneSpBhH5XCwE3t8w1Y

`--granularity` now defaults to `file`, so a tangle is a set of files and
the move search applies. On four public repositories the old default found
11 directory tangles and fixed 1. The new default gives 40 tangles each,
and 109 of 160 get a move. Eight blind judges picked the file section
every time.

Duplication ranking and placement keep the `auto` grouping, because their
spread weights were fitted on it. Their output is byte-identical to the
old default on all four repositories. A test pins this on a fixture where
the two groupings rank differently.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01S7cyneSpBhH5XCwE3t8w1Y
@alecf
alecf merged commit d0d10fa into main Nov 14, 2026
10 checks passed
@alecf
alecf deleted the feat/file-tangles branch November 14, 2026 01:23
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