Show HN: SpecFact CLI: Reverse Engineer Legacy Python into Enforceable Contracts

1 point

5 months ago

SpecFact CLI helps teams modernize legacy Python codebases by reverse engineering undocumented code into executable contracts with runtime enforcement.

What it does: - AST-based analysis extracts functions, classes, dependencies from legacy code - Generates runtime contracts (icontract + beartype) that prevent regressions - Symbolic execution (CrossHair) finds edge cases that LLMs miss - CI/CD integration blocks breaking changes automatically

Why brownfield-first: - Works with undocumented code, no type hints required - Designed for legacy modernization, not adapted from greenfield - CLI-first: works offline, no account, zero vendor lock-in

Current status: - Contract extraction and runtime enforcement (production-ready) - Sidecar validation in research phase: We're investigating how to run CrossHair against unmodified codebases without requiring decorators in source. This will enable symbolic execution on third-party/legacy code without editing files. See https://github.com/nold-ai/specfact-cli/issues/57 for progress.

Quick start:

    # Install slash commands (recommended for AI IDEs)
    specfact init --ide cursor
    
    # Then use in your AI IDE:
    /specfact.01-import --repo .

Or CLI-only mode:

    uvx specfact-cli@latest import from-code legacy-api --repo .
    specfact analyze contracts --bundle legacy-api
    specfact enforce sdd --sdd .specfact/sdd.yaml

Built for teams modernizing legacy Python systems in finance, healthcare, and data engineering where bugs cost millions.

Links: - GitHub: https://github.com/nold-ai/specfact-cli - Documentation: https://specfact.io - Blog: https://specfact.dev/blog (technical deep-dives)

What we're looking for: - Feedback on brownfield use cases - Integration examples (VS Code, Cursor, GitHub Actions) - Real-world case studies

I've been using it on my own legacy codebase and caught 4 bugs that would have shipped. Happy to answer questions!