Codebase Organizer

Maintain optimal file sizes for AI-assisted development by splitting large files into focused modules.

Quick Start

Most common usage:

# Check file sizes
make report-file-sizes

# If files >800 lines found:
# 1. Analyze structure
# 2. Plan split
# 3. Execute with test validation

When to Use This Skill

Invoke when user says:

• "Check file sizes" / "report file sizes"
• "Split this file" / "refactor large file"
• "Organize the codebase"
• "Make files AI-friendly"

File Size Targets

Size	Status	Action
200-500 lines	Sweet spot	None needed
500-800 lines	Acceptable	Consider splitting
>800 lines	CRITICAL	Must split

Workflow

Step 1: Status Check

# Find all large files
make report-file-sizes

# Or manually:
find internal -name "*.go" -exec wc -l {} \; | awk '$1 > 500 {print}' | sort -rn

Output format:

=== File Size Report ===

CRITICAL (>800 lines):
  internal/types/typechecker_core.go: 2736 lines
  internal/parser/parser.go: 2518 lines

WARNING (500-800 lines):
  internal/eval/eval_core.go: 765 lines

Step 2: Plan the Split

Before ANY refactoring:

1. Run baseline tests:

   make test

2. Identify natural boundaries:

   • Expression parsing vs statement parsing
   • Type inference vs type checking
   • Different AST node types
   • Public API vs internal helpers

3. Plan file names (match to primary functions):

   • expressions.go

     →

     parseExpression()

     ,

     parseCall()

   • statements.go

     →

     parseStatement()

     ,

     parseLetDecl()

   • helpers.go

     → utility functions

4. Check for circular dependency risks

Step 3: Execute Split

# 1. Create new files with clear names
# 2. Move related functions together (maintain cohesion)
# 3. Update imports in all affected files
# 4. Keep main struct in pkg.go

Keep together:

• Tightly coupled functions
• Helper functions used by one main function
• Functions that share complex state

Step 4: Validate

# MUST run after every split
make test              # All tests must pass
make lint              # No linting errors
make check-file-sizes  # Verify all <800 lines

If tests fail:

1. DO NOT COMMIT
2. Analyze failure (missing import? broken reference?)
3. Fix issue
4. Re-run tests
5. Only commit when tests pass

Step 5: Document & Commit

Update package documentation:

// Package parser implements AILANG source code parsing.
//
// # Architecture
//
// The parser is split into several files:
//   - parser.go: Main struct and entry points
//   - expressions.go: Expression parsing
//   - statements.go: Statement parsing

Commit with descriptive message:

git add internal/path/*.go
git commit -m "Split path/file.go into N files (AI-friendly)

- parser.go: Main struct (200 lines)
- expressions.go: Expression parsing (450 lines)
..."

Error Handling

Circular Dependency

If split creates circular dependency:

1. Identify cycle: File A imports B, File B imports A
2. Solutions:
   • Extract shared code to new file (e.g.,

     types.go

     )
   • Use interfaces to break dependency
   • Restructure to have one-way dependency
   • Merge files if truly inseparable (<800 lines combined)

Test Failures

Common issues after split:

• Missing import in new file
• Function moved but still referenced in old location
• Test file not updated to match new structure

Example Session

User: "Check codebase organization"

Response:

Running make report-file-sizes...

=== File Size Report ===

CRITICAL (>800 lines):
  internal/parser/parser.go: 2518 lines

WARNING (500-800 lines):
  internal/eval/eval_core.go: 765 lines

Recommendation: Split internal/parser/parser.go into ~6 focused files.
Would you like me to analyze and propose a split plan?

User: "Yes, split parser.go"

Response:

Analyzing internal/parser/parser.go (2518 lines)...

Proposed split:
  parser.go (200 lines) - Main struct, entry points
  expressions.go (450 lines) - Expression parsing
  statements.go (400 lines) - Declaration parsing
  types.go (300 lines) - Type annotation parsing
  patterns.go (350 lines) - Pattern parsing
  modules.go (300 lines) - Module system
  helpers.go (200 lines) - Utilities

Proceed? Tests will run before and after.

Success Metrics

After refactoring:

• 0 files over 800 lines
• <5 files between 500-800 lines
• Average file size: 300-400 lines
• 100% test pass rate maintained

Important Reminders

• ALWAYS run tests before and after refactoring
• NEVER commit if tests fail
• One refactoring at a time (easier to debug)
• Show plan before executing (get user approval)
• Keep related functions together (maintain cohesion)