python-file-splitter

# Python File Splitter

Requires `ast-grep`: `npm install -g @ast-grep/cli`

## Full Workflow

### Phase 1: Parse & Plan

0. If you have not yet read the file in question DO NOT READ IT YET. IT MIGHT BE TOO BIG, WAIT AFTER YOU RUN parse.
1. Copy `scripts/split_module.py` to working directory (using cp)
2. Run parse:
   ```bash
   python split_module.py parse path/to/module.py
   ```
3. Analyze output, apply grouping heuristics (see below)
4. Create `groupings.json`
5. Present proposed structure to user, wait for confirmation
   - **(Mode 1 stops here if user just wants to see the plan)**

### Phase 2: Split & Iterate

6. Run split:
   ```bash
   python split_module.py split path/to/module.py groupings.json package.module Class1 Class2
   ```
7. If imports succeed → done!
8. **If imports fail → rollback happens automatically**, then:
   - **Fix `groupings.json`** (add missing items to `base`, adjust groups)
   - **Re-run step 6**
   - Repeat until imports pass

### The Retry Loop

```
split → test fails → rollback → fix groupings.json → repeat
```

**NEVER edit generated files.** They get deleted on rollback. Only `groupings.json` survives - that's your source of truth.

## CLI Reference

```bash
# Parse: print definitions JSON
python split_module.py parse <file.py>

# Split: write files, test imports, rollback on failure
python split_module.py split <file.py> <groupings.json> <module> <Name1> [Name2 ...]
```

## Groupings JSON format

```json
{
  "base": ["BaseClass", "helper_func"],
  "groups": {
    "group_name": ["ClassA", "ClassAVariant"],
    "other": ["ClassB"]
  },
  "init_extras": ["get_instance", "create_thing"]
}
```

## Grouping heuristics

Apply in order:

1. **Base classes** → `base`: parent is `ABC`/`Protocol`/`BaseModel`, or name contains `Base`/`Mixin`
2. **Inheritance chains** → same group: class + all subclasses that inherit from it
3. **Naming patterns** → same group: `FooRenderer`, `FooVLRenderer`, `FooDisableThinkingRenderer`
4. **Helper functio