Modularize

Modularize

A skill for automatically refactoring, splitting, and compressing codebase files when they exceed size or complexity boundaries.

1. Core heuristics & guardrails

Rather than enforcing a strict, rigid line count, utilize ~200 lines as a warning light/signal to evaluate logical cohesion and maintainability.

Heuristics to evaluate before refactoring:

• Logical Cohesion: Does the file focus on one primary concern? Or does it contain independent blocks?
• Function/Block Size: Prioritize keeping functions small (under 20-30 lines) first.
• Nesting/Complexity: High cyclomatic complexity/nesting vs. simple flat lists.
• Fragmentation Risk: Avoid "jump-to-definition" fatigue by not over-splitting cohesive units.

Guardrails:

• The "Abort" Condition: Skip refactoring if the file is predominantly a configuration dictionary, list of constants, or single massive switch statement that logically belongs together.
• API Contract Preservation: Maintain public APIs using barrel files (e.g., index.ts) to re-export split modules, preventing breaking changes for consumers.
• Dependency Injection: Favor passing context via arguments rather than creating tangled relative imports (e.g., ../../../).

2. Refactoring patterns

A. test files

For large test suites (e.g., splitting a 600+ line test file):

• Split by Behavior/Topic: Group tests into separate files named after the feature or option under test (e.g. coercion.test.ts, arrays.test.ts, options.test.ts, etc.).
• Shared Setup: Extract common setup, beforeEach/afterEach hooks, mocks, or helper functions into a small local test utility or shared helper file, but only when duplication is real and significant.
• Run Focused Tests: After splitting, run the affected test suite files individually before running the wider project check.

B. source modules

For CLI commands, components, or services:

• Isolate Concerns: Isolate interactive UI prompts, file system adapters, API clients, and terminal reporters into discrete sub-modules.
• High-Level Orchestrator: Keep the original file purely as a high-level orchestrator that coordinates the sub-modules.
• Avoid Speculative Abstractions: Avoid creating generic reusable classes/functions before there are multiple active callers. Keep them as local module splits first.

3. Step-by-step workflow

1. Inspect & Classify: Read the file, identify dependencies/imports, and evaluate heuristics to decide whether to refactor or abort.
2. Design Boundaries: Formulate a plan for the split. Define clear boundaries, minimal interfaces, and ensure no public contracts are broken.
3. Incremental Execution: Extract sub-modules or smaller test files in small, logical batches. Check compilation/type-checking at each step.
4. Update Imports & Exports: Re-wire caller modules, update barrel/index files, and resolve imports cleanly.
5. Verify: Run the targeted tests, execute typechecking (e.g., pnpm typecheck or pnpm typecheck:packages), run the package build step (e.g., pnpm build or pnpm build:packages) to guarantee ESM/CJS module resolution/exports remain intact, and execute linting and formatting checks (e.g., pnpm fix).