# Spydecy - Self-Hosted Python/C-to-Rust Compiler-Debugger
[](https://crates.io/crates/spydecy)
[](https://github.com/noahgift/spydecy/actions)
[](https://opensource.org/licenses/MIT)
[](https://crates.io/crates/spydecy)
**Version 0.1.0 Released** 🎉 • **EXTREME TDD** • **Zero Tolerance SATD** • **50 Tests Passing**
Unified Python and C-to-Rust transpilation with introspective debugging capabilities.
## 📦 Published Crates
| [spydecy](https://crates.io/crates/spydecy) | 0.1.0 | Main CLI application |
| [spydecy-hir](https://crates.io/crates/spydecy-hir) | 0.1.0 | Unified HIR (High-level IR) |
| [spydecy-python](https://crates.io/crates/spydecy-python) | 0.1.0 | Python AST parser (PyO3) |
| [spydecy-debugger](https://crates.io/crates/spydecy-debugger) | 0.1.0 | Introspective debugger |
## 🎯 Quick Start
### Installation
#### From crates.io (Recommended)
```bash
# Install the latest release
cargo install spydecy
# Verify installation
spydecy --version
```
#### For Development
**Prerequisites:**
- Rust 1.75.0+
- Python 3.10-dev: `sudo apt-get install python3.10-dev`
- libclang-14-dev: `sudo apt-get install libclang-14-dev`
- PMAT: `cargo install pmat`
```bash
# Clone repository
git clone https://github.com/noahgift/spydecy.git
cd spydecy
# Install all development tools
make install-tools
# Setup project
make setup
# Build
make build
# Run quality gates
make quality-gate
```
### Usage
```bash
# Visualize Python AST
spydecy debug --visualize example.py
# Show version
spydecy --version
# Get help
spydecy --help
```
## 📚 Documentation
**Start Here**: [Response to Gemini AI Review](docs/specification/RESPONSE-TO-GEMINI-REVIEW.md) ⭐
### Critical Documents
1. **[Sprint 0: Tracer Bullet](docs/specification/SPRINT-0-TRACER-BULLET.md)** - 2-week validation sprint
2. **[Incremental Debugger Roadmap](docs/specification/INCREMENTAL-DEBUGGER-ROADMAP.md)** - Build debugger alongside transpiler
3. **[Pluggable C-API Architecture](docs/specification/PLUGGABLE-C-API-ARCHITECTURE.md)** - Extensible C-API analysis
### Full Specification
- [Main Specification](docs/specification/transpiled-python-c-to-rust-self-hosted-compiler-debugger.md)
- [Specification Index](docs/specification/README.md)
## 🧪 Quality Standards
| Test Coverage | ≥80% | PMAT + CI |
| Mutation Score | ≥90% | cargo-mutants |
| Complexity | ≤10 CCN | PMAT pre-commit |
| SATD Comments | 0 | PMAT (zero tolerance) |
| Clippy Warnings | 0 | CI/CD |
| Unsafe Code | <5 per 1000 LOC | Static analysis |
## 🚀 Development
### Quality Gates
```bash
# Fast quality check
make quality-fast
# Full quality gate (with coverage & mutation)
make quality-gate
# Pre-commit checks
make pre-commit
# Continuous improvement analysis
make kaizen
```
### Testing
```bash
# Run all tests
make test
# Property-based tests (1000 cases/property)
make test-property
# Mutation testing
make mutants
# Code coverage
make coverage
```
### Development Mode
```bash
# Auto-reload on changes
make dev
# Watch and run tests
make watch
```
## 🏗️ Project Status
**Current Version**: v0.1.0 (Released 2025-10-22)
**Current Phase**: Sprint 3 - C Transpiler Foundation
### Completed Milestones ✅
- ✅ **Sprint 0**: Tracer Bullet Validation - Core assumption proven: `len()` unification works!
- ✅ **Sprint 2**: Python Transpiler - Full Python AST parsing with PyO3 (7/7 tests)
- ✅ **v0.1.0 Release**: Published to crates.io with 50 passing tests
- spydecy-hir: Unified HIR foundation
- spydecy-python: Python parser working
- spydecy-debugger: Introspective debugger
- spydecy: Main CLI application
### In Progress 🚧
- ⏳ **Sprint 3**: C Transpiler Foundation
- ✅ C parser complete (11/11 tests)
- ✅ CPython API pattern recognition
- ⏳ First unification tests (Python + C → Rust)
- ⏳ C debugger visualization
### Roadmap
- **v0.2.0** (Est. 2 weeks): Complete unification - First Python + C → Rust tests working
- **v0.3.0** (Est. 4 weeks): Cross-layer optimization - Boundary elimination
- **v0.4.0** (Est. 8 weeks): Full code generation pipeline
- **v1.0.0** (Est. 12 weeks): Production ready - Self-hosting capability
See [RELEASE-v0.1.0.md](RELEASE-v0.1.0.md) for detailed release notes.
## 🔬 Architecture
### Multi-Layer Pipeline
```
Python Source → Python HIR ─┐
├─→ Unified HIR → Optimizer → Rust
C Source → C HIR ───────────┘
```
### Key Innovations
1. **Unified Python/C Transpilation** - Leverages CPython's C implementation
2. **Introspective Debugging** - Step through transpilation process
3. **Pluggable C-API** - CPython, NumPy, SciPy, community plugins
4. **Self-Hosting** - Compiler transpiles itself for validation
## 📊 Makefile Targets
```bash
make help # Show all available targets
make install-tools # Install all dev tools (PMAT, etc.)
make quality-gate # Run full quality gate suite
make kaizen # Continuous improvement analysis
make ci # Full CI pipeline
```
## 🤝 Contributing
### Development Methodology: EXTREME TDD
1. **RED**: Write failing tests first
2. **GREEN**: Minimal implementation
3. **REFACTOR**: Meet quality gates (≤10 CCN, 0 SATD, 80%+ coverage)
### Quality Requirements
- ✅ All tests pass
- ✅ Coverage ≥80%
- ✅ Mutation score ≥90%
- ✅ Complexity ≤10 CCN
- ✅ Zero SATD comments (TODO/FIXME/HACK)
- ✅ Zero Clippy warnings
- ✅ Code formatted with rustfmt
### Pre-Commit Hooks
Pre-commit hooks automatically enforce quality gates:
- Code formatting
- Clippy lints
- PMAT complexity & SATD checks
- Fast test suite
## 📜 License
Licensed under either of:
- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE))
- MIT license ([LICENSE-MIT](LICENSE-MIT))
at your option.
## 🙏 Acknowledgments
Inspired by:
- **depyler**: Python-to-Rust transpiler
- **decy**: C-to-Rust transpiler with extreme quality
- **bashrs**: Formal verification and property testing
- **ruchy**: Self-hosting and PMAT integration
- **Toyota Production System**: Jidoka, Kaizen, Genchi Genbutsu
---
**Built with EXTREME quality standards. Zero compromises. 🚀**
**Status**: v0.1.0 Released to crates.io ✅
**Current**: Sprint 3 - C Transpiler Foundation
**Next**: v0.2.0 - First Python + C unification tests
📦 **Install now**: `cargo install spydecy`
📖 **Documentation**: [RELEASE-v0.1.0.md](RELEASE-v0.1.0.md)
🔗 **Crates.io**: https://crates.io/crates/spydecy