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.