CodeGen¶

2025-12-312026-01-09

Status: Canonical Reference
Scope: src/codegen/ - Solution skeleton generation with test extraction
Related: Package README

CodeGen generates solution and practice skeleton files for LeetCode problems, providing the infrastructure needed for a LeetCode-like practice experience. It also extracts example test cases from problem descriptions and validates test file consistency.

Table of Contents¶

1. Overview
2. Scope
3. Interfaces
4. CLI Reference
5. How It Fits in the System
6. Typical Workflows
7. Test Generation
8. IO Schema Inference
9. Format Migration
10. Key Design Decisions
11. Configuration
12. Failure Modes and Constraints
13. Related Documentation

Overview¶

CodeGen serves as the code generation engine for the NeetCode practice framework. Its primary purpose is to:

• Generate reference skeleton files to solutions/
• Generate practice skeleton files to practices/
• Extract example test cases from LeetCode problem descriptions
• Provide a consistent structure that integrates with runner/ for testing

The module is designed as a stateless generator - it produces output based on input without maintaining internal state.

Goals¶

Non-Goals¶

Scope¶

What this module handles¶

• ✅ Rendering file-level docstrings (solution_header)
• ✅ Parsing LeetCode code stubs
• ✅ Detecting and emitting helper classes (ListNode, TreeNode, etc.)
• ✅ Assembling complete module files
• ✅ Generating SOLUTIONS dict structure
• ✅ Creating solve() interface (placeholder or inferred)
• ✅ Extracting examples from HTML (example_parser)
• ✅ Inferring IO schema from signatures (io_schema)
• ✅ Generating test files (test_generator)
• ✅ Checking test consistency (checker)
• ✅ Migrating test formats (migrator)

What this module explicitly avoids¶

• ❌ Test execution (handled by runner/)
• ❌ Practice file versioning (handled by practice_workspace)
• ❌ Network requests for problem data (handled by leetcode_datasource)
• ❌ CLI argument parsing for tools (handled by tools/)

Interfaces¶

High-level summary of public APIs. For complete API reference, see Package README.

Core Generation¶

Test Generation¶

Validation & Migration¶

CLI Reference¶

Generate Reference Skeleton¶

# Basic generation
python -m codegen new <problem_id>

# With test files from examples
python -m codegen new <problem_id> --with-tests

# With auto-generated solve()
python -m codegen new <problem_id> --solve-mode infer

# Combined
python -m codegen new <problem_id> --with-tests --solve-mode infer --force

# Preview without writing
python -m codegen new <problem_id> --dry-run

Generate Practice Skeleton¶

python -m codegen practice <problem_id>
python -m codegen practice <problem_id> --all-solutions

Check Test Consistency¶

# Check single problem
python -m codegen check <problem_id>
python -m codegen check <problem_id> -v

# Check all problems
python -m codegen check --all
python -m codegen check --all --limit 10

# JSON output
python -m codegen check --all --report json

Migrate Test Format¶

# Preview migration
python -m codegen migrate <problem_id> --dry-run -v

# Migrate single problem
python -m codegen migrate <problem_id>

# Migrate all problems
python -m codegen migrate --all --dry-run

# Migrate without backup
python -m codegen migrate --all --no-backup

How It Fits in the System¶

┌────────────────────────┐
│  leetcode_datasource   │  ← Problem metadata + HTML
└───────────┬────────────┘
            │
            ▼
┌────────────────────────┐     ┌───────────────────────┐
│       codegen          │ ──► │   practice_workspace  │
│                        │     └───────────────────────┘
│  ┌──────────────────┐  │              │
│  │ test_generator   │  │              │ manages history
│  │ solve_generator  │  │              ▼
│  │ checker          │  │         practices/_history/
│  │ migrator         │  │
│  └──────────────────┘  │
└───────────┬────────────┘
            │ generates
            ▼
       solutions/
       practices/
       tests/
            │
            ▼
┌────────────────────────┐
│        runner          │  ← Executes tests
└────────────────────────┘

Module Relationships¶

Typical Workflows¶

Workflow: Generate Reference with Tests¶

When codegen new <problem_id> --with-tests is invoked:

1. Check existence - If solutions/<id>_<slug>.py exists, stop
2. Fetch metadata - Get problem info and HTML from leetcode_datasource
3. Parse stub - Extract method signature, parameters, return type
4. Detect helpers - Determine if ListNode, TreeNode, etc. are needed
5. Infer IO schema - Map parameter types to input formats
6. Generate solve() - Based on --solve-mode (placeholder or infer)
7. Assemble module - Combine header, imports, helpers, SOLUTIONS, Solution, solve()
8. Write solution - Output to solutions/<id>_<slug>.py
9. Parse examples - Extract examples from HTML
10. Generate tests - Create .in/.out files for each example

Workflow: Check and Migrate¶

# 1. Check current state
python -m codegen check --all

# 2. Preview migration
python -m codegen migrate --all --dry-run

# 3. Migrate with backup
python -m codegen migrate --all

# 4. Verify
python -m codegen check --all

Test Generation¶

Canonical Test Format¶

All generated test files use the JSON literal format:

Input File (.in):

[2,7,11,15]
9

Output File (.out):

[0,1]

Format Rules¶

Type Support Tiers¶

IO Schema Inference¶

Data Flow¶

Question.Code (stub) 
  → parse_code_stub() → StubInfo 
  → infer_io_schema() → IOSchema
  → generate_solve_function() → solve() code

IOSchema Structure¶

@dataclass
class IOSchema:
    method_name: str
    params: List[ParamSchema]  # [(name, type, format, separators)]
    return_type: str
    return_format: ParamFormat  # SCALAR, ARRAY_1D, ARRAY_2D, etc.
    needs_helpers: Set[str]     # {"ListNode", "TreeNode"}

ParamFormat Types¶

Format Migration¶

Purpose¶

The migrator converts existing test files from legacy formats (space-separated, comma-separated) to the canonical JSON literal format.

Detected Formats¶

Migration Report¶

============================================================
MIGRATION REPORT
============================================================
Problems processed: 45
Total files: 218
  Migrated: 93
  Skipped (already canonical): 125
  Errors: 0

Key Design Decisions¶

Design Philosophy¶

┌─────────────────────────────────────────────────────────┐
│  codegen = stateless      → Only generates, no state    │
│  workspace = stateful     → Manages history/restore     │
│  runner = execution       → Runs tests, no generation   │
│                                                         │
│  stub_parser: parse only  → Separation of concerns      │
│  io_schema: infer format  → Type-driven generation      │
│  helpers: centralized     → Single source of truth      │
│  assemble.py: unified     → Avoid duplication           │
└─────────────────────────────────────────────────────────┘

Configuration¶

Config File Location¶

.neetcode/codegen.toml

Configuration Options¶

Priority Order¶

CLI flag > .neetcode/codegen.toml > package defaults

Failure Modes and Constraints¶

Exit Codes¶

Related Documentation¶

Appendix: Output File Structure¶

Reference skeleton output follows the Solution Contract:

"""
Problem: Two Sum
Link: https://leetcode.com/problems/two-sum/
...
"""
from typing import List, Optional
from _runner import get_solver

# Helper classes (if detected)
class ListNode:
    ...

# SOLUTIONS dict
SOLUTIONS = {
    "default": {
        "class": "Solution",
        "method": "twoSum",
        "complexity": "TODO: O(?)",
        "description": "TODO: describe your approach",
    },
}

# Solution class
class Solution:
    def twoSum(self, nums: List[int], target: int) -> List[int]:
        # TODO: Implement your solution
        pass

# solve() interface (auto-generated with --solve-mode infer)
def solve():
    """
    Input format (JSON literal, one per line):
        nums: List[int]
        target: int

    Output: List[int]
    """
    import sys
    import json

    data = sys.stdin.read().strip().split('\n')

    nums = json.loads(data[0].strip())
    target = int(data[1].strip())

    solver = get_solver(SOLUTIONS)
    result = solver.twoSum(nums, target)

    print(json.dumps(result, separators=(',', ':')))


if __name__ == "__main__":
    solve()

Appendix: Module Structure¶

codegen/
├── __init__.py              # Public API re-exports
├── __main__.py              # python -m codegen
├── cli.py                   # CLI: new / practice / check / migrate
├── checker.py               # Test consistency checker
├── analyzer.py              # Mismatch analysis and reporting
├── migrator.py              # Format migration tool
├── core/
│   ├── __init__.py
│   ├── solution_header.py   # Header rendering
│   ├── stub_parser.py       # LeetCode stub parsing
│   ├── assemble.py          # Module assembly
│   ├── config.py            # Configuration management
│   ├── io_schema.py         # IO format inference
│   ├── example_parser.py    # HTML example extraction
│   ├── solve_generator.py   # solve() auto-generation
│   ├── tiered_solve_generator.py  # Tiered solve() for Tier-1/1.5 problems
│   ├── problem_support.py   # Problem-specific config loading
│   ├── test_generator.py    # Test file generation
│   ├── catalog/             # Problem catalog utilities
│   │   └── __init__.py
│   └── helpers/
│       ├── __init__.py
│       ├── catalog.py       # Canonical helper definitions
│       ├── detect.py        # Helper detection logic
│       └── emit.py          # Helper code emission
├── reference/
│   ├── __init__.py
│   └── generator.py         # Reference skeleton generation
└── practice/
    ├── __init__.py
    ├── generator.py         # Practice skeleton generation
    └── reuse.py             # Reuse from reference

Tiered Solve Generation¶

For problems involving complex types (TreeNode, ListNode), use --solve-mode tiered:

python -m codegen new 104 --solve-mode tiered

This generates solve() functions with codec support for serialization/deserialization of complex types. See Problem Support Boundary for tier definitions.