modular-large-file-refactor

Modular Large File Refactor

Refactor one large file into a small set of focused modules without creating a mess of tiny shards. Optimize for lower cognitive load, stable public APIs, and obvious ownership boundaries.

Workflow

1. Find the real target first. In this repository, start with the bundled scripts/find_large_files.sh helper instead of ad-hoc shell pipelines.
2. Inspect the oversized file and list its responsibilities before touching code.
3. Classify each block as one of: public API, orchestration, pure logic, state management, side effects, types, constants, or UI rendering.
4. Choose the smallest useful module split that isolates responsibilities cleanly.
5. Extract in safe order: constants/types first, pure helpers next, stateful logic after that, and orchestration last.
6. Keep the original entrypoint stable unless the current public surface is the problem.
7. Re-run the relevant validation after the split.

Built-in Large File Finder

Use the bundled script first:

bash scripts/find_large_files.sh

What it does well:

• scans the repo's real source roots
• ignores dependency and build directories
• highlights severe offenders at 1000+ and 800+ lines
• gives a quick ranked list before deeper analysis

Use the script output to pick the biggest meaningful source file, then start the modular split.

Split Decision Rules

Extract a new module when the code has one clear responsibility.

• Pure transforms, parsers, validators, formatters, and mappers belong in their own helpers.
• Shared types, schemas, and constants move out early because they reduce noise with low risk.
• Repeated UI subsections become components only if they own a meaningful chunk of markup or behavior.
• Stateful logic with a clean interface becomes a hook, service, or internal module.

Keep code together when separation would hide the story.

• Do not create utils.ts or helpers.ts dumping grounds.
• Do not split a file just to reduce line count.
• Do not move tightly coupled code into distant files if the reader now has to bounce between five places to understand one flow.

Extraction Order

1. Stabilize boundaries

• Identify exports that other files already depend on.
• Preserve existing names and call shapes unless changing the contract is intentional.
• Prefer internal re-exports over churning imports across the repo.

2. Remove passive noise

• Extract constants, literal maps, small types, and Zod schemas first.
• Replace repeated inline conditions or object shapes with named helpers.

3. Isolate pure logic

• Pull complex branches into named functions with narrow inputs and outputs.
• Replace nested conditionals with guard clauses when it improves readability.
• Convert anonymous inline callbacks into named functions when they carry real logic.

4. Isolate stateful logic

• Move reusable or bulky state transitions into hooks, services, or internal modules.
• Keep side effects near the orchestration layer; do not bury network or filesystem calls in generic helpers.

5. Simplify the entrypoint

• Leave the original file as the facade that coordinates extracted parts.
• Aim for the top-level file to read like a table of contents for the feature.

Structural Targets

React and TypeScript

• Put shared UI pieces in sibling component files.
• Put non-visual behavior in hooks.
• Put backend calls in service modules that match existing project patterns.
• Put complex text/data transforms in pure helpers with explicit types.

Rust

• Keep the public module or command handler as the facade.
• Move focused logic into sibling modules under the same directory.
• Separate parsing, validation, repository access, and response formatting when they are currently interleaved.

Cross-cutting rule

• Prefer a small directory with 3-6 purposeful files over one huge file or fifteen trivial ones.

Complexity Reduction Moves

• Replace long if/else ladders with lookup tables only when the behavior is data-driven.
• Collapse duplicated setup/teardown into one helper with explicit naming.
• Break giant functions by phase: parse -> validate -> execute -> format.
• Narrow parameter lists by passing a well-named object only when the fields naturally belong together.
• Keep error handling explicit; do not add broad fallback behavior just to make extraction easier.

Anti-Patterns

• Splitting by arbitrary line ranges instead of responsibility
• Creating circular imports between extracted modules
• Hiding critical behavior in vaguely named helpers
• Moving repository or network calls into "pure" utility files
• Re-exporting everything from everywhere
• Changing filenames, symbols, and call paths more than the refactor requires

Output Expectation

When you finish, describe the refactor in this shape:

1. What responsibilities were identified in the original file
2. Which modules were extracted and why
3. Which public entrypoints stayed stable
4. Which risky areas were checked after the split

Reference

Read references/splitting-patterns.md when you need concrete module patterns for React/TypeScript or Rust, or when the right split boundary is not obvious.