Local-first Python CLI and reusable GitHub Action for verifying Python repositories. It runs deterministic checks, normalizes evidence, calculates a transparent confidence score, and exports JSON, Markdown, and HTML reports. It does not claim that code is correct.
- Ruff, mypy, pytest, Bandit, Semgrep and import-smoke adapters
- Weighted policy and required-tool gates
- AST test-gap inventory and reviewable smoke-test generation
- CI-friendly exit codes
- GitHub composite Action
- Local-first scanning
- Modern local developer workspace (
codeproof serve) with presets, durable history, findings search, comparison, tool readiness, and policy inspection
python -m venv .venv
# Windows: .venv\Scripts\activate
# Linux/macOS: source .venv/bin/activate
pip install -e ".[checkers]"
codeproof scan .codeproof tools # supported checks and execution behavior
codeproof doctor # availability and install guidance
codeproof init # write a default policy
codeproof inventory . # public symbols, not coverage
codeproof generate-tests . --output tests/generated
codeproof scan . --format all --fail-under 70 --jobs 3
codeproof scan . --config path/to/policy.yml --checks ruff,pytest,syntaxReports are stored under .codeproof/reports/. Open codeproof-report.html for offline search, status filters, and expandable evidence. JSON and Markdown remain available. Paths are positional; the earlier --path option is also supported. Exit codes: 0 policy passed, 1 policy failed, 2 invalid usage or configuration.
Partial policies overlay the six default checks; explicitly disable any you do not want. A selected or configured check cannot bypass a required tool gate. Remove a tool from required_tools only when intentionally changing the policy. For a quick execution-free syntax-only scan, use:
# .codeproof.yml
required_tools: []
source_paths: [src]
checks:
syntax: {enabled: true, weight: 10}codeproof scan . --checks syntaxTo add dependency auditing, install pip install 'codeproof-ai[audit]', provide a root requirements.txt, and add pip-audit: {enabled: true, weight: 15} under checks. This opt-in tool queries vulnerability services and may invoke package tooling while resolving dependencies. Unsupported manifests are reported unavailable; the developer environment is never audited as a fallback.
jobs: 1 (default) runs serially; --jobs 2 through --jobs 8 allow concurrency. Tests and imports can share resources, so choose concurrency to suit the repository. Invalid thresholds, negative/nonfinite weights, unknown tools, and unknown policy keys are rejected.
Generated tests check symbol exposure and execute imports; review them before running. Existing files are preserved unless --force is passed. See the audit and prioritized roadmap for delivered changes, compatibility notes, and follow-up work.
codeproof serve .
# Open http://127.0.0.1:8765/Run scans from a responsive browser workspace with four presets, durable history, searchable findings, report comparison, tool readiness and policy inspection. Export JSON, Markdown, HTML or SARIF. Required policy gates remain active. Browser scans require opt-in for code execution and network checks. History keeps the latest 50 runs locally.
codeproof scan . --format sarifRead the workspace guide and use cases for setup, workflows, storage and deployment boundaries. This is a local single-user workspace. Reports are stored under .codeproof/reports/.
The score is the weighted percentage of included checks that pass. Missing required tools fail policy. Missing optional tools are marked unavailable and excluded from the denominator. A passing report is evidence that configured checks passed, not proof of correctness.
pytest and import checks execute repository code. Scan untrusted repositories only in an isolated container or ephemeral runner. Semgrep auto can retrieve rules; use a local rules directory for offline operation.
pip install -e ".[dev]"
pytestMIT