{"id":50757644,"url":"https://github.com/yumin-chen/ferris-proof","last_synced_at":"2026-06-11T06:32:13.888Z","repository":{"id":331170259,"uuid":"1125558483","full_name":"yumin-chen/ferris-proof","owner":"yumin-chen","description":"Correctness pipeline for Rust that combines formal modeling (TLA+, Alloy), Rust's type system, and property-based testing to guarantee memory-safety, structural soundness, and functional correctness.","archived":false,"fork":false,"pushed_at":"2025-12-31T19:52:19.000Z","size":278,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-04T00:24:55.474Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"cc0-1.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/yumin-chen.png","metadata":{"files":{"readme":"ReadMe.md","changelog":null,"contributing":"Contributing.md","funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-31T00:18:28.000Z","updated_at":"2025-12-31T19:52:22.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/yumin-chen/ferris-proof","commit_stats":null,"previous_names":["yumin-chen/ferris-proof"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/yumin-chen/ferris-proof","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yumin-chen%2Fferris-proof","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yumin-chen%2Fferris-proof/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yumin-chen%2Fferris-proof/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yumin-chen%2Fferris-proof/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/yumin-chen","download_url":"https://codeload.github.com/yumin-chen/ferris-proof/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yumin-chen%2Fferris-proof/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34186385,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-11T02:00:06.485Z","response_time":57,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-11T06:32:12.993Z","updated_at":"2026-06-11T06:32:13.881Z","avatar_url":"https://github.com/yumin-chen.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# FerrisProof\n\n\u003e **Rust. Verified. Proven.**: *Making Rust systems provably correct, one layer at a time.* \n\nFerrisProof is a **full-stack correctness pipeline** for Rust applications, combining **formal modeling (TLA+, Alloy)**, **Rust's type system**, and **property-based testing** to ensure your systems are **memory-safe, structurally sound, and functionally correct**.\n\n[![Coverage](https://codecov.io/gh/yumin-chen/ferris-proof/branch/main/graph/badge.svg)](https://codecov.io/gh/yumin-chen/ferris-proof)\n[![License: CC0-1.0](https://img.shields.io/badge/License-CC0%201.0-lightgrey.svg)](http://creativecommons.org/publicdomain/zero/1.0/)\n\n\u003e **🚧 Active Development**: FerrisProof is currently in active development. Core infrastructure and CLI tools are complete, with verification layers being progressively implemented.\n\nMulti-layer correctness pipeline for Rust applications that combines formal modeling, type-level verification, and property-based testing to ensure systems are memory-safe, structurally sound, and functionally correct.\n\n---\n\n## Quick Start\n\n### Installation\n\n```bash\n# Clone the repository\ngit clone https://github.com/yumin-chen/ferris-proof.git\ncd ferris-proof\n\n# Build and install the CLI tool\ncargo install --path ferris-proof-cli\n```\n\n### Initialise a New Project\n\n```bash\n# Initialise with standard verification level\nferris-proof init --level standard\n\n# Interactive initialization with prompts\nferris-proof init --interactive\n\n# Initialise with formal verification level\nferris-proof init --level formal\n```\n\n### Basic Commands\n\n```bash\n# Show project configuration\nferris-proof config\n\n# Validate configuration\nferris-proof config --validate\n\n# Show configuration for specific file\nferris-proof config --file src/main.rs\n\n# Explain error codes\nferris-proof explain FP-CF-001\n\n# Get help\nferris-proof --help\nferris-proof init --help\n\n# Cache management\nferris-proof cache info\nferris-proof cache health\nferris-proof cache cleanup\nferris-proof cache clear\n```\n\n---\n\n## Features\n\n- **🚀 Command-Line Interface**: Full-featured CLI with project initialization, configuration management, and error explanation\n- **📊 Multi-Layer Verification**: Four progressive verification layers targeting different classes of errors\n- **📝 Formal Specifications**: TLA+ and Alloy integration for protocol-level correctness\n- **🔒 Type-Level Verification**: Session types and refinement types for compile-time guarantees\n- **🧪 Property-Based Testing**: Comprehensive property testing with proptest integration\n- **📈 Production Monitoring**: Runtime assertions and observability hooks\n- **⬆️ Progressive Adoption**: Gradual verification level upgrades with automated scaffolding\n- **🔄 CI/CD Integration**: GitHub Actions support with configurable enforcement modes\n- **⚙️ Hierarchical Configuration**: Module-level and item-level verification overrides\n- **💾 Comprehensive Caching**: Content-addressed verification result caching with Blake3 hashing, AST normalization, zstd compression, and management commands\n- **🔐 Security-First**: Sandboxed execution and local-only verification options\n\n---\n\n## Architecture Overview\n\n### Multi-Layer Verification Architecture\n\n```mermaid\ngraph TB\n    %% Core FerrisProof Components\n    subgraph \"FerrisProof Core\"\n        CLI[\"CLI Tool\"]\n        CM[\"Configuration Manager\"]\n        VE[\"Verification Engine\"]\n        Cache[\"Verification Cache\"]\n        Metrics[\"Metrics Collector\"]\n        PM[\"Plugin Manager\"]\n    end\n\n    %% Verification Layers (DAG with Rust guarantees)\n    subgraph \"Verification Layers\"\n        L1[\"Layer 1: Formal Spec (TLA+/Alloy)\"]\n        L2[\"Layer 2: Type-Level Verification (Session \u0026 Refinement Types)\"]\n        L3[\"Layer 3: Property-Based Testing (Proptest/Kani/Bolero)\"]\n        L4[\"Layer 4: Production Monitoring (Runtime Assertions, Metrics)\"]\n    end\n\n    %% Rust Type Guarantees\n    subgraph \"Rust-Specific Safety\"\n        TS[\"Typestate \u0026 Linear Types\"]\n        RT[\"Refinement Types\"]\n        AST[\"AST Validation \u0026 Attribute Macros\"]\n    end\n\n    %% Sandboxed External Tools\n    subgraph \"External Tools (Sandboxed)\"\n        TLA[\"TLA+ TLC\"]\n        ALLOY[\"Alloy Analyzer\"]\n        PROP[\"Proptest\"]\n        KANI[\"Kani Verifier\"]\n        LOOM[\"Loom Concurrency\"]\n    end\n\n    %% CLI \u0026 Config Flow\n    CLI --\u003e CM\n    CLI --\u003e VE\n    CM --\u003e VE\n    VE --\u003e Cache\n    VE --\u003e Metrics\n    VE --\u003e PM\n\n    %% Layer Execution with Rust Guarantees\n    VE --\u003e L1\n    L1 --\u003e TS\n    L1 --\u003e ALLOY\n    VE --\u003e L2\n    L2 --\u003e TS\n    L2 --\u003e RT\n    VE --\u003e L3\n    L3 --\u003e AST\n    VE --\u003e L4\n\n    %% Layer DAG Enforcement\n    L1 --\u003e|success| L2\n    L2 --\u003e|success| L3\n    L3 --\u003e|success| L4\n\n    %% Plugin Manager \u0026 Sandbox\n    PM --\u003e TLA\n    PM --\u003e ALLOY\n    PM --\u003e PROP\n    PM --\u003e KANI\n    PM --\u003e LOOM\n\n    TLA --\u003e FS1[\"Filesystem: Restricted Paths\"]\n    ALLOY --\u003e FS1\n    PROP --\u003e FS2[\"Filesystem: Restricted Paths\"]\n    KANI --\u003e FS2\n    LOOM --\u003e FS2\n\n    TLA --\u003e NET1[\"Network: Denied/Allowlist\"]\n    ALLOY --\u003e NET1\n    PROP --\u003e NET2[\"Network: Denied/Allowlist\"]\n    KANI --\u003e NET2\n    LOOM --\u003e NET2\n\n    %% Cache Awareness\n    L1 --\u003e Cache\n    L2 --\u003e Cache\n    L3 --\u003e Cache\n    L4 --\u003e Cache\n\n    %% Metrics \u0026 Observability\n    L1 --\u003e Metrics\n    L2 --\u003e Metrics\n    L3 --\u003e Metrics\n    L4 --\u003e Metrics\n\n    %% Styling\n    classDef rustType fill:#c6f5d0,stroke:#2a9d8f,stroke-width:2px;\n    class CLI,CM,VE,Cache,Metrics,PM,L1,L2,L3,L4,TS,RT,AST rustType\n    classDef sandbox fill:#fdf6e3,stroke:#f4a261,stroke-width:2px;\n    class TLA,ALLOY,PROP,KANI,LOOM,FS1,FS2,NET1,NET2 sandbox\n```\n\n### **Highlights**\n\n1. **Rust-Centric Type Guarantees**\n\n   * Typestate \u0026 linear types enforce layer dependencies at compile-time.\n   * Refinement types validate value-level invariants.\n   * AST validation ensures attribute macros and configuration correctness.\n\n2. **Layered DAG Enforcement**\n\n   * Each layer only executes if prior layers pass successfully.\n   * Ensures **formal → type → property → monitoring** sequence is never violated.\n\n3. **Incremental Verification \u0026 Caching**\n\n   * All layers are cache-aware; avoids redundant execution.\n   * Cache keyed by **AST content, configuration hash, and tool versions**.\n\n4. **Sandboxed Plugin Execution**\n\n   * External tools run in isolated sandboxes with:\n\n     * Restricted filesystem access\n     * Network denied or allowlist\n     * Resource limits (CPU, memory, file descriptors)\n   * Captures outputs for structured parsing.\n\n5. **Observability \u0026 Metrics**\n\n   * Metrics collected for all layers: execution time, cache hits, violations.\n   * Supports structured logs for CI and human-readable output.\n\n6. **Unified Orchestration**\n\n   * CLI → Config → Verification Engine → Plugin Manager → Layers → Cache/Metrics\n   * Ensures reproducible, safe, and type-checked verification runs.\n\n### Configuration Hierarchy\n\n```mermaid\ngraph TD\n    ROOT[Root Config\u003cbr/\u003eferrisproof.toml]\n\n    subgraph \"Module Overrides\"\n        CRYPTO[crypto/*\u003cbr/\u003elevel: formal]\n        API[api/*\u003cbr/\u003elevel: standard]\n        UTILS[utils/*\u003cbr/\u003elevel: minimal]\n    end\n\n    subgraph \"Item Attributes\"\n        FUNC[\"Function Level\u003cbr/\u003e\u003ccode\u003e#[verification(level = strict)]\u003c/code\u003e\"]\n        MOD[\"Module Level\u003cbr/\u003e\u003ccode\u003e#[verification(spec = raft.tla)]\u003c/code\u003e\"]\n    end\n\n    ROOT --\u003e CRYPTO\n    ROOT --\u003e API\n    ROOT --\u003e UTILS\n\n    CRYPTO --\u003e FUNC\n    API --\u003e MOD\n```\n\n---\n\n## Project Structure\n\n```\nferris-proof/\n├── ferris-proof-cli/             # Command-line interface\n├── ferris-proof-core/            # Core verification engine\n├── ferris-proof-config/          # Configuration management\n├── ferris-proof-plugins/         # Plugin system and tool integrations\n├── scripts/                      # CI/CD and development scripts\n│   ├── run-tests.sh             # Unified test runner with comprehensive options\n│   ├── ci-local.sh              # Local CI pipeline\n│   ├── ci-setup.sh              # Development environment setup\n│   ├── container-build.sh       # Container build script\n│   └── verify-containerfiles.sh # Container validation script\n├── docs/                         # Documentation\n│   ├── ferris-proof.tsd.specs.md # Detailed architecture design\n│   ├── ferris-proof.prd.specs.md # Functional requirements\n│   └── ci-pipeline.md           # CI/CD documentation\n├── Cargo.toml                    # Workspace configuration\n├── Containerfile                 # Standard container build\n├── Containerfile.alpine          # Minimal Alpine container build\n├── Makefile                      # Common development tasks\n├── .gitlab-ci.yml               # GitLab CI/CD pipeline with comprehensive testing\n├── .github/                      # GitHub Actions workflows\n│   ├── workflows/ci.yml         # Main CI pipeline with multi-platform testing\n│   ├── workflows/property-tests.yml # Dedicated property-based testing workflow\n│   └── workflows/release.yml    # Release automation\n├── proptest.toml                 # Property-based test configuration\n├── ReadMe.md                     # This file\n├── Contributing.md               # Contribution guidelines\n└── Licence.md                    # CC0 1.0 Universal licence\n```\n\n---\n\n## Development Status\n\n### ✅ Completed\n- **Core Infrastructure**: Rust workspace with 4 crates\n- **CLI Tool**: Complete command-line interface with project initialization, configuration management, error explanation, and cache management\n- **Configuration System**: Hierarchical TOML configuration with validation and discovery\n- **Plugin Architecture**: Extensible verification tool integration with sandboxed execution and network isolation\n- **Property-Based Testing**: Framework for correctness validation with comprehensive test coverage (20+ property tests)\n- **Verification Cache**: Complete content-addressed caching system with Blake3 hashing, AST normalization, compression, and management commands\n- **CI/CD Pipeline**: Comprehensive automated testing with GitHub Actions and GitLab CI, multi-platform support, property-based test automation, extended fuzzing, regression detection, and configurable test parameters\n- **Test Automation**: Unified test runner script with support for unit, integration, and property tests, configurable parameters, coverage reporting, and environment variable integration\n- **Documentation**: Comprehensive specs, API docs, getting-started guides, and CI pipeline documentation\n- **Security**: Sandboxed execution, input validation, network isolation, and local-only verification\n\n### 🚧 In Progress\n- **Verification Engine**: Core orchestration logic for multi-layer verification\n- **Formal Specification Integration**: TLA+ and Alloy tool integration\n- **Type-Level Verification**: Session types and refinement types implementation\n\n### 📋 Planned\n- **Production Monitoring**: Runtime assertions and observability hooks\n- **Advanced Tool Integrations**: Kani, Loom, and additional verification backends\n- **Performance Optimisations**: Parallel verification and advanced caching strategies\n\n## Setup \u0026 Installation\n\n### Prerequisites\n\n- **Rust 1.83+** (specified in `rust-toolchain.toml`)\n- **Git** for version control\n- **pkg-config** and **libssl-dev** (Linux) or **openssl** (macOS) for SSL support\n\n### Optional Tools (for full verification)\n\n- **TLA+ Toolbox**: [Download here](https://lamport.azurewebsites.net/tla/tools.html)\n- **Alloy Analyzer**: [Download here](http://alloytools.org/)\n\n### Build from Source\n\n```bash\n# Clone the repository\ngit clone https://github.com/yumin-chen/ferris-proof.git\ncd ferris-proof\n\n# Build all crates\ncargo build --all-features\n\n# Run tests using the unified test runner\n./scripts/run-tests.sh             # Run all tests with default settings\n./scripts/run-tests.sh -t unit     # Unit tests only\n./scripts/run-tests.sh -t integration # Integration tests only\n./scripts/run-tests.sh -t property # Property-based tests only\n./scripts/run-tests.sh -t all      # All tests explicitly\n\n# Run tests with custom configuration\n./scripts/run-tests.sh -t property -c 5000 -s 50000  # 5000 cases, 50000 shrink iterations\n./scripts/run-tests.sh -C          # Generate coverage report\n./scripts/run-tests.sh -v -t all   # Verbose output for all tests\n\n# Traditional cargo test (also works)\ncargo test --all-features\n\n# Install CLI tool\ncargo install --path ferris-proof-cli\n\n# Verify installation\nferris-proof --version\n```\n\n### Using the CLI Tool\n\n```bash\n# Initialise a new project\nferris-proof init --level standard\n\n# Show project configuration\nferris-proof config\n\n# Validate configuration\nferris-proof config --validate\n\n# Explain error codes\nferris-proof explain FP-CF-001\n\n# Get help for any command\nferris-proof --help\nferris-proof init --help\n```\n\n---\n\n## Verification Cache System\n\nFerrisProof includes a sophisticated verification cache system that dramatically improves performance by avoiding redundant verification work:\n\n### Cache Features\n\n- **Content-Addressed Storage**: Cache entries organized by Blake3 content hashes\n- **AST Normalization**: Rust files normalized to ignore comments and whitespace changes\n- **Tool Version Tracking**: Automatic invalidation when external tool versions change\n- **Zstd Compression**: Efficient storage with transparent compression/decompression\n- **Atomic Operations**: Safe concurrent access with atomic file operations\n- **Persistence**: Cache survives across verification runs and system restarts\n\n### Cache Management Commands\n\n```bash\n# Show cache statistics and health information\nferris-proof cache info\n\n# Check cache integrity and get recommendations\nferris-proof cache health\n\n# Remove expired cache entries\nferris-proof cache cleanup\n\n# Clear all cache entries (with confirmation)\nferris-proof cache clear\n\n# Optimise cache storage and remove expired entries\nferris-proof cache compact\n\n# Repair corrupted cache entries\nferris-proof cache repair\n```\n\n### Cache Configuration\n\nThe cache system is configured in your `ferrisproof.toml`:\n\n```toml\n[features]\ncache_enabled = true           # Enable/disable caching\ncache_ttl = 86400             # Cache entry TTL in seconds (24 hours)\n\n[thresholds]\nmax_memory_usage = 2147483648  # Maximum memory usage (2GB)\n```\n\n### Cache Performance\n\nThe cache system provides significant performance improvements:\n\n- **Cache Hit Rate**: Typically 70-90% for incremental changes\n- **Storage Efficiency**: 60-80% compression ratio with zstd\n- **Access Speed**: Sub-millisecond cache lookups\n- **Memory Usage**: Configurable limits with automatic cleanup\n\n---\n\n## Configuration\n\nFerrisProof uses hierarchical TOML configuration. Initialise a project to get started:\n\n```bash\n# Initialise with interactive prompts\nferris-proof init --interactive\n\n# Or initialise with a specific level\nferris-proof init --level standard\n```\n\nThis creates a `ferrisproof.toml` file in your project root:\n\n```toml\n[profile]\nlevel = \"standard\"\nenforcement = \"warning\"\nenabled_techniques = [\"TypeSafety\", \"PropertyTests\"]\n\n[tools.proptest]\ncases = 1000\nmax_shrink_iters = 10000\n\n[features]\ncache_enabled = true\nparallel_execution = true\ngenerate_reports = true\n\n[thresholds]\nmax_verification_time = 300  # 5 minutes\nmax_memory_usage = 2147483648  # 2GB\ncache_ttl = 86400  # 24 hours\n```\n\n### Verification Levels\n\n- **Minimal**: Type safety only\n- **Standard**: Type safety + Property-based testing\n- **Strict**: + Session types, refinement types, concurrency testing\n- **Formal**: + Formal specifications (TLA+, Alloy)\n\n### Configuration Commands\n\n```bash\n# Show current configuration\nferris-proof config\n\n# Validate configuration\nferris-proof config --validate\n\n# Show effective configuration for a specific file\nferris-proof config --file src/main.rs\n```\n\n### Configuration Hierarchy\n\nFerrisProof uses hierarchical TOML configuration with the following precedence (highest to lowest):\n\n1. **Item-level attributes** (`#[verification(...)]`)\n2. **Module-level glob patterns** (most specific path match)\n3. **Module configuration files** (nearest ancestor directory)\n4. **Root configuration** (`ferrisproof.toml`)\n\n---\n\n## Verification Reports\n\nFerrisProof generates comprehensive verification reports in multiple formats:\n\n- **JSON**: Machine-readable for CI integration\n- **Markdown**: Human-readable with rich formatting\n- **HTML**: Interactive web-based reports\n\nReport contents include:\n- Verification status per layer\n- Violations with severity levels\n- Performance metrics and timing\n- Cache hit rates and efficiency\n- Tool versions and configurations\n\n---\n\n## Security \u0026 Privacy\n\nFerrisProof is designed with security in mind:\n\n- **No external data transmission** without explicit consent\n- **Local-only verification** for sensitive codebases\n- **Sandboxed execution** of external tools\n- **Input validation** to prevent path traversal\n- **Secure configuration parsing**\n\n---\n\n## Performance Targets\n\n| Verification Level | Project Size | Target Duration | Memory Usage | Cache Hit Rate |\n|--------------------|--------------|-----------------|--------------|----------------|\n| Minimal            | \u003c100k LOC    | \u003c30s           | \u003c500 MB      | 85-95%         |\n| Standard           | \u003c100k LOC    | \u003c5 min         | \u003c2 GB        | 75-90%         |\n| Strict             | \u003c50k LOC     | \u003c10 min        | \u003c4 GB        | 70-85%         |\n| Formal             | \u003c10k LOC     | \u003c30 min        | \u003c8 GB        | 60-80%         |\n\n---\n\n## Error Handling\n\nFerrisProof provides comprehensive error handling with detailed explanations:\n\n```bash\n# Explain any error code\nferris-proof explain FP-CF-001\nferris-proof explain FP-VR-001\nferris-proof explain FP-TL-001\n```\n\n### Error Code Categories\n\n- **FP-CF-XXX**: Configuration errors\n- **FP-VR-XXX**: Verification errors  \n- **FP-TL-XXX**: Tool errors\n- **FP-IO-XXX**: I/O and file system errors\n- **FP-CH-XXX**: Cache system errors\n\n### Common Error Codes\n\n| Code | Description | Suggested Fix |\n|------|-------------|---------------|\n| FP-CF-001 | Invalid verification level | Use: minimal, standard, strict, formal |\n| FP-CF-002 | Missing required configuration field | Run `ferris-proof init` |\n| FP-VR-001 | Property test failure | Review counterexample |\n| FP-TL-001 | TLA+ TLC not found | Install TLA+ tools |\n| FP-CH-001 | Cache corruption detected | Run `ferris-proof cache repair` |\n| FP-CH-002 | Cache storage full | Run `ferris-proof cache cleanup` |\n\nEach error explanation includes:\n- Detailed description\n- Common causes\n- Step-by-step solutions\n- Code examples\n- Related error codes\n\n---\n\n## CLI Reference\n\n### Global Options\n\n```bash\nferris-proof [OPTIONS] \u003cCOMMAND\u003e\n\nOptions:\n  --config \u003cFILE\u003e              Path to configuration file\n  -v, --verbose...             Enable verbose output (can be repeated)\n  --output-format \u003cFORMAT\u003e     Output format: human, json, compact\n  --no-color                   Disable colored output\n  -h, --help                   Print help\n  -V, --version                Print version\n```\n\n### Commands\n\n#### `init` - Initialise Project\n```bash\nferris-proof init [OPTIONS]\n\nOptions:\n  --level \u003cLEVEL\u003e              Verification level [default: standard]\n  --interactive                Use interactive mode\n  --template \u003cTEMPLATE\u003e        Project template to use\n```\n\n#### `config` - Show Configuration\n```bash\nferris-proof config [OPTIONS]\n\nOptions:\n  --file \u003cFILE\u003e                Show config for specific file\n  --validate                   Validate configuration\n```\n\n#### `cache` - Cache Management\n```bash\nferris-proof cache \u003cSUBCOMMAND\u003e\n\nSubcommands:\n  info                         Show cache statistics and information\n  health                       Check cache health and integrity\n  cleanup                      Remove expired cache entries\n  clear                        Clear all cache entries\n  compact                      Optimise cache storage\n  repair                       Repair corrupted cache entries\n```\n\n### Test Runner Script\n\nThe unified test runner script (`scripts/run-tests.sh`) provides comprehensive test execution:\n\n```bash\n./scripts/run-tests.sh [OPTIONS]\n\nOptions:\n  -t, --type TYPE              Test type: unit, integration, property, all (default: all)\n  -v, --verbose                Enable verbose output\n  -c, --cases NUM              Number of property test cases (default: 1000)\n  -s, --shrink NUM             Max shrink iterations for property tests (default: 10000)\n  -T, --timeout MIN            Timeout in minutes (default: 30)\n  -j, --parallel               Run tests in parallel (default: true)\n  -C, --coverage               Generate code coverage report\n  -h, --help                   Show help message\n\nExamples:\n  ./scripts/run-tests.sh                      # Run all tests with defaults\n  ./scripts/run-tests.sh -t unit              # Run only unit tests\n  ./scripts/run-tests.sh -t property -c 5000  # Run property tests with 5000 cases\n  ./scripts/run-tests.sh -C                   # Run all tests with coverage\n  ./scripts/run-tests.sh -v -t all            # Run all tests with verbose output\n\nEnvironment Variables:\n  PROPTEST_CASES               Override property test case count\n  PROPTEST_MAX_SHRINK_ITERS    Override max shrink iterations\n  PROPTEST_TIMEOUT             Override property test timeout (ms)\n  RUST_BACKTRACE               Enable Rust backtraces (0, 1, full)\n  CARGO_TERM_COLOR             Control colored output (auto, always, never)\n```\n\n---\n\n## Workflow Examples\n\n### Project Initialization\n\n```mermaid\nsequenceDiagram\n    participant U as User\n    participant CLI as CLI Tool\n    participant CM as Config Manager\n    participant FS as File System\n\n    U-\u003e\u003eCLI: ferris-proof init --level standard\n    CLI-\u003e\u003eCLI: Parse arguments and validate level\n    CLI-\u003e\u003eCM: create_config_for_level(standard)\n    CM-\u003e\u003eFS: write ferrisproof.toml\n    FS--\u003e\u003eCM: Success\n    CLI-\u003e\u003eFS: create directory structure\n    CLI-\u003e\u003eFS: create template files (if specified)\n    CLI--\u003e\u003eU: ✓ Project initialised successfully\n```\n\n### Configuration Management\n\n```mermaid\nsequenceDiagram\n    participant U as User\n    participant CLI as CLI Tool\n    participant CM as Config Manager\n    participant V as Validator\n\n    U-\u003e\u003eCLI: ferris-proof config --validate\n    CLI-\u003e\u003eCM: load_project_config()\n    CM-\u003e\u003eCM: discover_config_files()\n    CM-\u003e\u003eCM: merge_hierarchical_configs()\n    CM-\u003e\u003eV: validate_config()\n    alt Valid Configuration\n        V--\u003e\u003eCM: ValidationResult::Ok\n        CM--\u003e\u003eCLI: Configuration valid\n        CLI--\u003e\u003eU: ✓ Configuration is valid\n    else Invalid Configuration\n        V--\u003e\u003eCM: ValidationResult::Error(details)\n        CM--\u003e\u003eCLI: Validation errors\n        CLI--\u003e\u003eU: ✗ Configuration validation failed\n    end\n```\n\n### Error Code Explanation\n\n```mermaid\nsequenceDiagram\n    participant U as User\n    participant CLI as CLI Tool\n    participant EC as Error Catalog\n\n    U-\u003e\u003eCLI: ferris-proof explain FP-CF-001\n    CLI-\u003e\u003eEC: lookup_error_code(\"FP-CF-001\")\n    alt Known Error Code\n        EC--\u003e\u003eCLI: ErrorExplanation{title, description, causes, solutions}\n        CLI--\u003e\u003eU: Display formatted explanation\n    else Unknown Error Code\n        EC--\u003e\u003eCLI: None\n        CLI--\u003e\u003eU: Unknown error code + suggestions\n    end\n```\n\n### Verification with Caching\n\n```mermaid\nsequenceDiagram\n    participant CLI as CLI Tool\n    participant VE as Verification Engine\n    participant Cache as Verification Cache\n    participant CM as Config Manager\n    participant PM as Plugin Manager\n    participant TLA as TLA+ TLC\n\n    CLI-\u003e\u003eVE: verify(targets)\n    VE-\u003e\u003eCM: for_file(target.path)\n    CM--\u003e\u003eVE: EffectiveConfig\n    \n    VE-\u003e\u003eCache: get(target, config_hash)\n    alt Cache Hit\n        Cache--\u003e\u003eVE: CachedResult\n        VE--\u003e\u003eCLI: VerificationResult (cached)\n    else Cache Miss\n        VE-\u003e\u003ePM: plugins_for_technique(FormalSpecs)\n        PM--\u003e\u003eVE: [TLA+ Plugin]\n        VE-\u003e\u003eTLA: verify(spec.tla)\n        TLA--\u003e\u003eVE: ModelCheckResult\n        VE-\u003e\u003eCache: store(target, result)\n        VE--\u003e\u003eCLI: VerificationResult (fresh)\n    end\n```\n\n---\n## Documentation\n\n- [Getting Started Guide](docs/getting-started.md)\n- [CLI Reference](#cli-reference) - Complete command-line interface documentation\n- [Configuration Guide](#configuration) - Hierarchical configuration system\n- [Error Handling](#error-handling) - Comprehensive error code catalog\n- [CI Pipeline](docs/ci-pipeline.md)\n- [API Documentation](https://docs.rs/ferris-proof)\n\nFor detailed technical information:\n\n- **[Design Document](docs/ferris-proof.tsd.specs.md)** - Comprehensive architecture and implementation details\n- **[Requirements Document](docs/ferris-proof.prd.specs.md)** - Functional requirements and acceptance criteria\n- **[Task Tracking](.kiro/specs/ferris-proof/tasks.md)** - Implementation progress and task status\n\n---\n\n## Future Directions\n\n* Auto-generate Rust property tests from Alloy/TLA+ models\n* Extend support for distributed multi-agent systems\n* Continuous verification in CI/CD pipelines\n* Runtime trace comparison with TLA+ execution paths\n* Plugin ecosystem for additional verification backends\n* Advanced cache analytics and performance optimisation\n* Distributed cache sharing for team environments\n\n---\n\n## Contributing\n\nWe welcome contributions! Please see [Contributing.md](Contributing.md) for guidelines.\n\n## Licence\n\nThis work is dedicated to the public domain under the [CC0 1.0 Universal](Licence.md) licence.\n\nTo the extent possible under law, the contributors have waived all copyright and related or neighbouring rights to this work.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyumin-chen%2Fferris-proof","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyumin-chen%2Fferris-proof","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyumin-chen%2Fferris-proof/lists"}