spydecy 0.2.0

Self-hosted Python/C-to-Rust compiler-debugger with introspective debugging
Documentation

Spydecy - Self-Hosted Python/C-to-Rust Compiler-Debugger

Crates.io CI Status License: MIT OR Apache-2.0 Downloads

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

Crate Version Description
spydecy 0.1.0 Main CLI application
spydecy-hir 0.1.0 Unified HIR (High-level IR)
spydecy-python 0.1.0 Python AST parser (PyO3)
spydecy-debugger 0.1.0 Introspective debugger

🎯 Quick Start

Installation

From crates.io (Recommended)

# 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
# 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

# Visualize Python AST
spydecy debug --visualize example.py

# Show version
spydecy --version

# Get help
spydecy --help

📚 Documentation

Start Here: Response to Gemini AI Review ⭐

Critical Documents

  1. Sprint 0: Tracer Bullet - 2-week validation sprint
  2. Incremental Debugger Roadmap - Build debugger alongside transpiler
  3. Pluggable C-API Architecture - Extensible C-API analysis

Full Specification

🧪 Quality Standards

Metric Target Enforcement
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

# 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

# Run all tests
make test

# Property-based tests (1000 cases/property)
make test-property

# Mutation testing
make mutants

# Code coverage
make coverage

Development Mode

# 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 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

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:

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 🔗 Crates.io: https://crates.io/crates/spydecy