Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 8 additions & 1 deletion .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -3,9 +3,16 @@ on: [push, pull_request]
jobs:
test:
runs-on: ubuntu-latest
strategy:
matrix:
python-version: ["3.10", "3.12"]
steps:
- uses: actions/checkout@v4
- uses: actions/setup-python@v5
with: {python-version: "3.12"}
with:
python-version: ${{ matrix.python-version }}
- run: pip install -e ".[dev]"
- run: ruff check src tests
- run: ruff format --check src tests
- run: mypy src
- run: pytest
2 changes: 2 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -8,3 +8,5 @@ __pycache__/
dist/
build/
*.egg-info/

.codeproof/workspace/
62 changes: 59 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,18 +20,74 @@ pip install -e ".[checkers]"
codeproof scan .
```

<!-- coderabbit-ai-generated:v1 -->

<!-- coderabbit-ai-generated-section:v1:3b67dbb46462cc622268fbccfec224b9fadec6e62adcd31c971ddfbdf0fff3c1 -->

## Commands

```bash
codeproof doctor
codeproof init
codeproof inventory .
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,syntax
```

Reports 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.

### Policy and additional tools

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:

```yaml
# .codeproof.yml
required_tools: []
source_paths: [src]
checks:
syntax: {enabled: true, weight: 10}
```

```bash
codeproof scan . --checks syntax
```

To 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](docs/roadmap.md) for delivered changes, compatibility notes, and follow-up work.

<!-- /coderabbit-ai-generated:v1 -->

<!-- coderabbit-ai-generated:v1 -->

<!-- coderabbit-ai-generated-section:v1:92fa63fb64ba1e1531e19feb0d45a9570a922b4234965c93f86f078af595fe02 -->

## Developer workspace

```bash
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.

```bash
codeproof scan . --format sarif
```

Read the [workspace guide and use cases](docs/developer-workspace.md) for setup, workflows, storage and deployment boundaries. This is a local single-user workspace.
codeproof scan . --format all --fail-under 70
codeproof gui . --host 127.0.0.1 --port 8787
```
Reports are stored under `.codeproof/reports/`. The GUI runs locally and uses the same core engine/policy as the CLI. See `ROADMAP.md` for planned enhancements.

## Confidence model

<!-- /coderabbit-ai-generated:v1 -->
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.

## Security
Expand Down
16 changes: 13 additions & 3 deletions action.yml
Original file line number Diff line number Diff line change
Expand Up @@ -3,13 +3,23 @@ description: Evidence-backed Python repository verification
inputs:
path: {description: Repository path, required: false, default: .}
fail-under: {description: Minimum score, required: false, default: "70"}
jobs: {description: Concurrent check workers (1-8), required: false, default: "1"}
runs:
using: composite
steps:
- shell: bash
run: python -m pip install "${{ github.action_path }}[checkers]"
env:
CODEPROOF_ACTION_PATH: ${{ github.action_path }}
run: python -m pip install "${CODEPROOF_ACTION_PATH}[checkers]"
- shell: bash
run: codeproof scan "${{ inputs.path }}" --fail-under "${{ inputs.fail-under }}"
env:
CODEPROOF_TARGET: ${{ inputs.path }}
CODEPROOF_THRESHOLD: ${{ inputs.fail-under }}
CODEPROOF_JOBS: ${{ inputs.jobs }}
run: codeproof scan "$CODEPROOF_TARGET" --fail-under "$CODEPROOF_THRESHOLD" --jobs "$CODEPROOF_JOBS"
- if: always()
uses: actions/upload-artifact@v4
with: {name: codeproof-report, path: "${{ inputs.path }}/.codeproof/"}
with:
name: codeproof-report
path: "${{ inputs.path }}/.codeproof/reports/"
include-hidden-files: true
59 changes: 59 additions & 0 deletions docs/developer-workspace.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,59 @@
<!-- coderabbit-ai-generated:v1 -->

# CodeProof Developer Workspace

## Start here

```bash
pip install -e ".[checkers]"
codeproof serve .
```

Open **http://127.0.0.1:8765/**. The same repository-scoped engine powers the browser, CLI and GitHub Action. The workspace uses Python's standard library HTTP server and SQLite; there is no frontend build step or new service dependency. All CSS, scripts and fonts are local. Dates follow the browser locale and stored timestamps use UTC.

Use `codeproof doctor` to check availability. Add `pip install 'codeproof-ai[audit]'` for dependency auditing and a root requirements.txt. The CLI and existing static reports remain supported. `--format all` still generates the original JSON, Markdown and HTML files; `--format sarif` explicitly generates codeproof-report.sarif.

## Developer workflows and product use cases

| Audience / problem | Workflow | Evidence delivered |
|---|---|---|
| Python developers catching errors before commit | Fast feedback preset: syntax, Ruff and mypy plus required gates | Tool statuses, structured findings, file locations and raw output |
| Reviewers evaluating a pull request | Code quality preset: syntax, lint, types, pytest and Bandit plus required gates | Weighted score, required-check result, downloadable report and SARIF |
| Maintainers tracking regressions | Scan history and baseline/current comparison | Score difference and new/resolved normalized findings, with a warning if check sets/weights/thresholds differ |
| Security champions triaging Python code | Security preset: syntax, Bandit, Semgrep and pip-audit plus required gates | Security-pattern and dependency findings; unavailable tools remain visible |
| Release engineers applying shared standards | Repository policy preset and Quality policy page | The existing policy, explicit threshold, required gates and repeatable scan evidence |
| New contributors learning a repository's quality workflow | Tool readiness, installation guidance, use-case guides and downloadable YAML | Clear setup steps and one scan dialog instead of remembering CLI options |
| Teams moving evidence between CI tools | Export JSON, Markdown, HTML or SARIF 2.1.0 | Portable snapshots; SARIF exports normalized findings only, not raw-only diagnostics |

The product is a Python verification workspace. It does not write application code, prove correctness, measure test coverage, offer an AI chat model, or certify compliance. Generated tests in the CLI check symbol exposure and should be reviewed before running.

## Interface and behavior

- Repository overview: actual score, check counts, findings and policy outcome; no simulated statistics.
- Quality trend: latest 12 completed runs with scores and timestamps. Different presets can measure different check sets; compare their configurations before treating a trend as improvement.
- Findings explorer: search message/rule/file, filter by tool/severity, and page through 25 rows at a time. Check evidence includes commands, structured findings, diagnostics and execution time.
- Scan dialog: four presets, threshold 0–100, workers 1–8, and explicit code-execution/network opt-ins. Existing required checks are included and disabled required checks still fail policy. Mypy plugins and package resolution can execute code, so their profiles require execution consent.
- Run history: statuses include running, complete, error and interrupted; a failing policy is a completed scan with a failed policy outcome. Reports survive application restarts.
- Comparison: tool, rule, path, line and message identify a normalized finding. Location shifts may count as new/resolved. Up to 100 changes per group are rendered. Raw-only errors are outside finding comparison. Complete environment/rule snapshots are not yet recorded, so identical check sets do not establish identical execution conditions.
- Toolchain, policy downloads and command helpers support onboarding and terminal/CI use. Browser changes apply only to that scan and never overwrite .codeproof.yml.
- Responsive navigation, native dialogs, keyboard focus styles, live status messaging, locale-sensitive timestamps and no external asset requests keep the app useful across devices and networks.

## Local scale and storage

History is stored in `.codeproof/workspace/history.sqlite3`, ignored by Git. The oldest run is deleted when admitting a run beyond the 50-run retention limit. Keep exported reports elsewhere if longer retention is needed. History reads summary columns rather than loading every report payload. Browser caching is capped at 50 reports. Check execution uses the existing bounded pool of up to eight workers.

One active scan is admitted per server process; further submissions receive HTTP 409. There is no unbounded execution queue. Run one workspace server per repository. A restart marks unfinished records interrupted; it does not resume or cancel orphan subprocess trees. Existing per-tool timeouts still apply. Subprocess output is still buffered in memory before truncation; large-repository and load benchmarks remain follow-up work. No throughput improvement or distributed execution is claimed.

## Access and deployment

The default bind address is loopback. The API pins the repository at startup; requests cannot supply arbitrary target paths or shell commands. Mutations require a per-session token, matching Origin when present, and a permitted Host. Downloads are attachments and untrusted report text is escaped. Requests are limited to 64 KB and connections have a 15-second timeout. Assets use a restrictive content-security policy.

For a trusted development reverse proxy, specify its exact hostname using `--allowed-host` and use `--host 0.0.0.0` only when that proxy is appropriately restricted. The workspace token prevents cross-site scan submission; it is not user authentication. This release is a local single-user app. Public team deployment requires user authentication, authorization, isolated execution workers, shared storage/queues, quotas, observability and a separate deployment review.

## Product expansion priorities

1. Validate adoption with the four developer workflows, improve onboarding from real feedback, and add richer normalization for pytest and mypy.
2. Add report provenance for source revision, tool versions and effective policy; improve comparison equivalence checks and configure retention.
3. Add measured process/output limits and process-tree cancellation before raising concurrency or introducing incremental caching.
4. Add localization using an explicit translation catalog and validate keyboard/screen-reader workflows; English and browser-locale date formatting are delivered now.
5. Build a hosted team edition only after defining tenant isolation, identity, billing, data residency and operating budgets. Corporate visual design alone does not establish enterprise security or compliance.
Loading
Loading