🚀 Major Additions to SpecFact CLI - Recent Releases Summary

[djm81]

🚀 Major Additions to SpecFact CLI - Recent Releases Summary

Hey SpecFact developers! 👋

We've been busy adding some major features to SpecFact CLI over the past few releases. This discussion highlights the most significant additions that you should know about.

---

🎯 Version 0.24.0 - Sidecar Validation CLI Integration (January 2026)

Native Sidecar Validation Workflow

We've completely integrated the sidecar validation workflow into the CLI, making it a first-class citizen of SpecFact CLI!

New Commands

# Initialize a sidecar workspace
specfact validate sidecar init <bundle-name> <repo-path>

# Run complete sidecar validation workflow
specfact validate sidecar run <bundle-name> <repo-path> [--run-crosshair] [--run-specmatic]

Key Features

• 🔍 Automatic Framework Detection: Detects Django, FastAPI, DRF, and pure Python frameworks automatically
• 📋 Route Extraction: Framework-specific route and schema extraction (Django URLs, FastAPI routes, DRF serializers)
• 📝 Contract Population: Automatic population of OpenAPI contracts with extracted routes and schemas
• ⚙️ Environment Manager Support: Automatic detection and use of hatch, poetry, uv, and pip environments
• 🔧 Venv Detection: Automatic detection and configuration of .venv and venv virtual environments
• 📊 Progress Reporting: Rich console progress indicators for long-running operations
• 🔄 Backward Compatibility: Full compatibility with existing template-based sidecar workspaces

CrossHair Summary Reporting

Enhanced CrossHair output parsing with automatic summary generation:

• Summary Parser: Parses CrossHair stdout/stderr to extract validation results
• Summary Files: Automatic generation of crosshair-summary-{timestamp}.json files
• Console Display: Formatted summary line showing confirmed/not confirmed/violations counts
• 15 comprehensive unit tests covering various output scenarios

Specmatic Auto-Skip

Intelligent detection and skipping of Specmatic when no service is available:

• Service Detection: Automatically detects available service endpoints
• Auto-Skip Logic: Specmatic automatically skipped when no service configuration detected
• Clear Messaging: User-friendly warning messages when Specmatic is skipped
• Manual Override: --run-specmatic flag to force execution even without service configuration

Repro Sidecar Integration

Sidecar validation is now integrated into the specfact repro command:

# Run reproducibility checks with sidecar validation
specfact repro --sidecar --sidecar-bundle <name> <repo-path>

Features:

• Unannotated Code Detection: AST-based detection of functions without @icontract or @beartype decorators
• Safe Defaults: Automatic application of conservative timeout defaults for repro mode
• Deterministic Inputs: Support for deterministic inputs from harness inputs.json

Testing & Quality

• 69 sidecar-related tests with ≥80% coverage
• 35 new tests for CrossHair summary, Specmatic auto-skip, unannotated detection, safe defaults, and repro integration
• Comprehensive unit, integration, and end-to-end test coverage

---

⚡ Version 0.23.1 - Performance Optimizations (January 2026)

Contract Extraction Performance Fix

Fixed a critical performance bottleneck that was causing extremely slow contract extraction:

• Nested Parallelism Removal: Eliminated GIL contention from nested ThreadPoolExecutor instances
• Performance Improvement: Contract extraction for large codebases (300+ features) now completes in reasonable time instead of hours
• Cache Invalidation Logic: Fixed cache update logic to properly detect and handle file changes

Import Command Bug Fixes

• Unhashable Type Error: Fixed TypeError: unhashable type: 'Feature' when applying enrichment reports
• Enrichment Performance Regression: Fixed severe performance issue where enrichment forced full contract regeneration
• Contract Extraction Order: Fixed contract extraction to run after enrichment application

Comprehensive Test Coverage

• Integration Tests: New test_import_enrichment_contracts.py with 5 test cases (552 lines)
• Unit Tests: New test_import_contract_extraction.py with 5 test cases (262 lines)

---

📚 Version 0.23.0 - Performance & Progress Reporting (December 2025)

Performance Optimizations for Large Codebases

• Enhanced progress reporting for large codebases
• Improved handling of repositories with 300+ features
• Better memory management and resource utilization

---

📖 Documentation Improvements

New Guides

• Sidecar Validation Guide: Complete user guide with examples (docs/guides/sidecar-validation.md)
• Command Reference: Updated with all new validate sidecar commands
• Troubleshooting Sections: Added for Specmatic auto-skip and common issues

Enhanced Documentation

• Auto-skip behavior documentation with examples
• Repro integration section with usage examples
• Safe defaults documentation
• Framework detection accuracy improvements

---

🛠️ Technical Highlights

New Python Modules

• src/specfact_cli/validators/sidecar/ - Complete sidecar validation package
• src/specfact_cli/validators/sidecar/frameworks/ - Framework-specific extractors (Django, FastAPI, DRF)
• src/specfact_cli/commands/validate.py - Validation command group with sidecar subcommands
• src/specfact_cli/validators/sidecar/crosshair_summary.py - CrossHair output parsing
• src/specfact_cli/validators/sidecar/unannotated_detector.py - AST-based unannotated code detection

Enhanced Models

• TimeoutConfig: Added safe_defaults_for_repro() class method
• CrossHairConfig: Added use_deterministic_inputs and safe_defaults flags
• SidecarConfig: Enhanced with unannotated function detection support

---

🎓 Getting Started

Try Sidecar Validation

# 1. Initialize a sidecar workspace
specfact validate sidecar init my-api /path/to/repo

# 2. Run validation
specfact validate sidecar run my-api /path/to/repo

# 3. Or integrate with repro
specfact repro --sidecar --sidecar-bundle my-api /path/to/repo

Read the Documentation

• Sidecar Validation Guide
• Command Reference
• CHANGELOG.md

---

💬 Questions & Feedback

Have questions about these new features? Found a bug? Want to suggest improvements?

• Issues: Open an issue
• Discussions: Join the conversation here!
• Documentation: Check out docs.specfact.io

---

Happy coding! 🚀

Last updated: January 2026