[WIP] Create complete project structure for PRSpec

[Copilot]

PRSpec Project Implementation Plan

• Create project directory structure (src/, tests/, output/)
• Create requirements.txt with all dependencies
• Create config.yaml with all settings
• Create .env.example with environment variables
• Implement src/init.py with package initialization
• Implement src/config.py for configuration management
• Implement src/spec_fetcher.py for spec downloading
• Implement src/code_fetcher.py for client code downloading
• Implement src/parser.py for parsing specs and code
• Implement src/analyzer.py for LLM-powered analysis
• Implement src/report_generator.py for report generation
• Implement src/cli.py for command-line interface
• Create tests/test_eip1559.py with pytest test suite
• Create run_demo.py for one-click demo
• Update README.md with full documentation
• Create output/.gitkeep to preserve directory
• Test the complete implementation
• Run final validation

Original prompt

Project: PRSpec - Ethereum Specification Compliance Checker

Author: Safi El-Hassanine

Create the complete project structure with all working code files:

Directory Structure Required:

prspec/
├── src/
│   ├── __init__.py
│   ├── config.py          # Configuration management
│   ├── spec_fetcher.py    # Download specs from GitHub
│   ├── code_fetcher.py    # Download client code
│   ├── parser.py          # Parse spec and code files
│   ├── analyzer.py        # LLM-powered analysis
│   ├── report_generator.py # Generate reports
│   └── cli.py             # Command line interface
├── tests/
│   ├── __init__.py
│   └── test_eip1559.py
├── output/                # Generated reports go here (add .gitkeep)
├── requirements.txt
├── config.yaml
├── .env.example
├── run_demo.py            # One-click demo
└── README.md

File Specifications:

1. requirements.txt

openai>=1.0.0
requests>=2.31.0
tree-sitter>=0.20.0
tree-sitter-python>=0.20.0
tree-sitter-go>=0.20.0
pyyaml>=6.0.1
python-dotenv>=1.0.0
click>=8.1.0
rich>=13.0.0
gitpython>=3.1.40
aiohttp>=3.9.0

2. config.yaml

• GitHub repos URLs (ethereum/execution-specs, ethereum/go-ethereum)
• File paths for EIP-1559 spec and code files
• LLM model settings (gpt-4-turbo-preview, temperature 0.1, max_tokens 4096)
• Output formats (json, markdown, html)
• Analysis settings (confidence_threshold 0.7, cache settings)

3. .env.example

OPENAI_API_KEY=your_openai_api_key_here
GITHUB_TOKEN=your_github_token_here
PRSPEC_CACHE_DIR=.prspec_cache
PRSPEC_CONFIG_PATH=config.yaml

4. src/init.py

• Package initialization with version "0.1.0"
• Author: Safi El-Hassanine
• Export all main classes

5. src/config.py

• Config class that loads config.yaml
• Environment variable handling (OPENAI_API_KEY, GITHUB_TOKEN)
• Path management for cache and output directories
• Properties for all LLM settings
• ConfigError exception class

6. src/spec_fetcher.py

• SpecFetcher class
• Clone/pull ethereum/execution-specs repository
• Fetch files via GitHub API (async with aiohttp)
• Cache management with TTL
• Extract EIP sections from markdown
• SpecFetchError exception class

7. src/code_fetcher.py

• CodeFetcher class
• Clone/pull ethereum/go-ethereum repository
• Fetch PR files by PR number
• Fetch files at specific commits
• Support for analyzing specific PRs or commits
• CodeFetchError exception class

8. src/parser.py

• SpecParser class for markdown specifications
  • Parse into SpecSection dataclass (title, level, content, subsections, requirements, parameters)
  • Extract RFC 2119 requirements (MUST, SHOULD, MAY)
  • Extract parameters/constants
• CodeParser class for Go source code
  • Use tree-sitter for AST parsing (with regex fallback)
  • Extract functions (CodeFunction dataclass)
  • Extract structs (CodeStruct dataclass)
  • Extract constants
  • ParsedCode dataclass container

9. src/analyzer.py

• ComplianceAnalyzer class
• Use OpenAI GPT-4 API for analysis
• System prompt for Ethereum protocol analysis
• Compare spec vs code implementation
• Generate structured JSON output
• ComplianceIssue dataclass (severity, category, requirement, location, description, suggestion, confidence)
• ComplianceResult dataclass (eip_id, versions, overall_compliance, issues, verified_requirements, summary)
• Async analysis support
• Constant comparison method

10. src/report_generator.py

• ReportGenerator class
• Generate JSON reports with full details
• Generate Markdown reports (human-readable with tables and emojis)
• Generate HTML reports (styled with CSS, colored severity indicators)
• Timestamp and metadata in all reports

11. src/cli.py

• Click-based CLI with Rich console output
• Commands: check, config, fetch
• check command options: --eip, --commit, --pr, --output, --format, --force-refresh
• Progress indicators with Rich spinners
• Results display with tables
• Verbose logging option

12. tests/test_eip1559.py

• Pytest test suite
• TestConfig class (YAML loading, API key validation)
• TestSpecParser class (markdown parsing, requirement extraction, parameter extraction)
• TestCodeParser class (Go function/struct/constant parsing)
• TestComplianceAnalyzer class (constant comparison tests)
• TestIntegration class (pipeline tests with mocks)
• Fixtures for sample Go code and spec markdown

13. run_demo.py

• Shebang for direct execution
• Banner display with ASCII art "PRSPEC"
• Complete demo workflow:
  1. Check for .env file and API key
  2. Fetch specifications
  3. Fetch go-ethereum code
  4. Parse both
  5. Run LLM analysis
  6. Generate reports
  7. Display results summary
• Error handling with helpful messages

14. README.md (update existing)

• Project title and description
• Features list
• Installation instructions (clone, venv, pip install, .env setup)
• Quick start guide
• CLI usage examples
• Configuration documentation
• Output formats explanation
• Project structure
• Author credit: Safi...

This pull request was created from Copilot chat.

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.