Split a Large File

Split one file into a directory of modules without changing behavior. Where the pieces go, what they are named, and where tests live are owned by source-layout; read it first. This skill owns the procedure: lock behavior with tests, move, extract, then split the tests.

The split changes no behavior. If you find a bug on the way, note it and fix it in a separate commit or PR after the split.

1. Pick the file

Given a file, use it. Otherwise build a shortlist:

git ls-files -z -- 'src/*.ts' 'src/*.tsx' 'apps/*.ts' 'apps/*.tsx' 'packages/*.ts' 'packages/*.tsx' \
  | rg --null-data -v '(^|/)(__tests__|__mocks__|fixtures|locales)/|\.(test|spec)\.|\.d\.ts$' \
  | xargs -0 wc -l | awk '$1 > 1200 && $NF != "total"' | sort -rn | head -30

The shortlist still contains data tables and generated code; filter it by reading. Prefer a file with:

• A real extraction boundary: hand-written logic with separable state, sub-domains, or stages, not a lookup table.
• A repeatable verification surface: behavior that unit or integration tests can observe (including the real-database tests testing requires for models), not one that needs a browser session or live third-party calls.
• A reviewable scope: one PR can hold the split. When this repository is mounted as a submodule, split a file of the submodule only through a PR to the submodule.

Use recent churn (git log --since=3.months --oneline -- <file> | wc -l) only to break ties. State the choice and the reason before starting.

2. Read and plan

Read the whole file and its tests. Find every reference with rg on the module path and basename across source roots: imports, re-exports, dynamic import(), vi.mock('…/Foo'), explicit extensions, and package entry mappings.

Write a short plan before editing: