cp.nvim/CLAUDE.md

# CP.nvim Modernization Status & Upcoming Changes

## ✅ Completed Modernization

### Core System Overhaul
- **Eliminated makefile dependency** - Pure Lua implementation using `vim.system()`
- **Native Neovim 0.10+ APIs** throughout (no more shell scripts or `vim.fn.system`)
- **JSON-based problem scraping** replacing `---INPUT---` format with structured data
- **Modular architecture** with dedicated modules:
  - `execute.lua` - Compilation and execution
  - `scrape.lua` - Problem scraping with JSON parsing
  - `window.lua` - Native window management
  - `config.lua` - Base + extension configuration system

### Enhanced Features
- **Configurable timeouts** per contest type
- **Contest-specific compiler flags** with inheritance
- **Direct Python scraper integration** without shell script middleware
- **Native diff mode** with proper window state management (eliminated vim-zoom dependency)
- **LuaSnip integration** with automatic snippet expansion
- **Debug flag accuracy** in output formatting

### Configuration System
- **Base + extension pattern** for contest configuration
- **Dynamic C++ standard flag generation** (`-std=c++XX`)
- **Default snippet templates** built into the plugin

## 🔧 Upcoming Development Tasks

### 1. Multi-Test Case Support
**Current**: Only writes first scraped test case to `.in`/`.expected`
**Needed**: 
- Write all test cases or let users cycle through them
- Support for test case selection/management

### 2. Template System Enhancement
**Current**: Basic snippet expansion with contest types
**Needed**:
- Template customization beyond snippets
- Problem-specific template variables
- Integration with scraped problem metadata

### 3. Enhanced Output Processing
**Current**: Basic output comparison with expected results
**Needed**:
- Better diff visualization in output window
- Partial match scoring
- Test case result breakdown for multi-case problems

### 4. Error Handling & User Experience
**Current**: Basic error messages and logging
**Needed**:
- Better error recovery from failed scraping
- Progress indicators for long-running operations
- More descriptive compilation error formatting

### 5. Contest Platform Extensions
**Current**: AtCoder, Codeforces, CSES support
**Potential**:
- USACO integration (mentioned in TODO)
- Additional platform support as needed

### 6. Documentation & Examples
**Current**: Basic README
**Needed**:
- Video demonstration (TODO item)
- Comprehensive vim docs (`:help cp.nvim`)
- Configuration examples and best practices

## 🏗️ Architecture Notes for Future Development

### Plugin Structure
```
lua/cp/
├── init.lua      # Main plugin logic & command setup
├── config.lua    # Configuration with inheritance
├── execute.lua   # Compilation & execution (vim.system)
├── scrape.lua    # JSON-based problem scraping
├── snippets.lua  # Default LuaSnip templates
└── window.lua    # Native window management
```

### Key Design Principles
1. **Pure Lua** - No external shell dependencies
2. **Modular** - Each concern in separate module
3. **Configurable** - Base + extension configuration pattern
4. **Modern APIs** - Neovim 0.10+ native functions
5. **Graceful Fallbacks** - Degrade gracefully when optional deps unavailable

## 📊 Current Feature Completeness

| Feature | Status | Notes |
|---------|--------|-------|
| Problem Setup | ✅ Complete | Native scraping + file generation |
| Code Execution | ✅ Complete | Direct compilation with timeouts |
| Debug Mode | ✅ Complete | Separate flags + debug output |
| Diff Comparison | ✅ Complete | Native window management |
| LuaSnip Integration | ✅ Complete | Auto-expanding templates |
| Multi-platform | ✅ Complete | AtCoder, Codeforces, CSES |
| Configuration | ✅ Complete | Flexible inheritance system |

## 📋 PLAN - Remaining Tasks

### Phase 1: Core System Testing (High Priority)
1. **End-to-end functionality testing**
   - Test all contest types: `CP atcoder`, `CP codeforces`, `CP cses`
   - Verify problem setup with scraping: `CP atcoder abc123 a`
   - Test run/debug/diff workflow for each platform
   - Validate compilation with different C++ standards

2. **Python environment validation**
   - Verify `uv sync` creates proper virtual environment
   - Test Python scrapers output valid JSON
   - Handle scraping failures gracefully
   - Check scraper dependencies (requests, beautifulsoup, etc.)

3. **Configuration system testing**
   - Test default vs custom contest configurations
   - Verify timeout settings work correctly
   - Test compiler flag inheritance and overrides
   - Validate C++ version flag generation

### Phase 2: Integration Testing (Medium Priority)
4. **LuaSnip integration validation**
   - Test snippet expansion for contest types
   - Verify fallback when LuaSnip unavailable
   - Test custom user snippets alongside defaults
   - Validate snippet triggering in empty files

5. **Window management testing**
   - Test diff mode enter/exit functionality
   - Verify layout save/restore works correctly
   - Test window state persistence across operations
   - Validate split ratios and window positioning

6. **File I/O and path handling**
   - Test with various problem ID formats
   - Verify input/output/expected file handling
   - Test directory creation (build/, io/)
   - Validate file path resolution across platforms

### Phase 3: Error Handling & Edge Cases (Medium Priority)
7. **Error scenario testing**
   - Test with invalid contest types
   - Test with missing Python dependencies
   - Test compilation failures
   - Test scraping failures (network issues, rate limits)
   - Test with malformed JSON from scrapers

8. **Performance validation**
   - Test timeout handling for slow compilations
   - Verify non-blocking execution with vim.system
   - Test with large output files
   - Validate memory usage with multiple test cases

### Phase 4: User Experience Testing (Lower Priority)
9. **Command completion and validation**
   - Test command-line completion for contest types
   - Test argument validation and error messages
   - Verify help text accuracy

10. **Documentation verification**
    - Test all examples in README work correctly
    - Verify installation instructions are accurate
    - Test user configuration examples

### Phase 5: Regression Testing (Ongoing)
11. **Compare with original functionality**
    - Ensure no features were lost in migration
    - Verify output format matches expectations
    - Test backward compatibility with existing workflows

### Testing Priority Order:
1. **Critical Path**: Problem setup → Run → Output verification
2. **Core Features**: Debug mode, diff mode, LuaSnip integration
3. **Error Handling**: Graceful failures, helpful error messages
4. **Edge Cases**: Unusual problem formats, network issues
5. **Performance**: Large problems, slow networks, timeout handling

### Success Criteria:
- All basic workflows complete without errors
- Python scrapers produce valid problem files
- Compilation and execution work for all contest types
- LuaSnip integration functions or degrades gracefully
- Error messages are clear and actionable
- No vim.fn.system calls remain (all migrated to vim.system)

The plugin is now fully modernized and ready for comprehensive testing to ensure production readiness.