Metadata-Version: 2.4
Name: reqdonkey
Version: 0.1.0
Summary: The Requirements Donkey: deterministic auditing of whether code honors its implied, documented, and specified requirements. Computes the PPI (Polysemy Preservation Index). Local, zero-exfiltration -- your code never leaves; only the verdict does.
Author: doloop
License: MIT
Project-URL: Homepage, https://doloop.io/ppi/
Project-URL: Source, https://github.com/ekras-doloop/doloop-machine
Keywords: static-analysis,code-quality,requirements,ppi,deterministic
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: semgrep>=1.0

# The Requirements Donkey + PPI — open standard & reference implementation

The public, verifiable home of the **PPI (Polysemy Preservation Index)** and the Requirements
Donkey that computes it. Every number on **doloop.io/ppi** recomputes byte-identically from these
files. No model sits in the verdict path.

## What's here
- **`PPI_STANDARD.md`** — the open standard: the formula, the 6 dimensions, the versioned inputs.
- **`reqdonkey/`** — the reference implementation (deterministic):
  - `dim1.py` code-internal consistency (validation taint via the Semgrep *witness*; error-handling
    + resource-cleanup + type-hints via `ast`; a non-adoption FLOOR so unused readings aren't penalized) · `dim2.py` doc-reader (`reqlex@v1` lexicon + RFC/CWE refs +
    undoc-API) · `dim3.py` code↔doc concordance + the provenance tell · `dim4.py` spec-conformance
    (vendored `MUST` clauses; Heartbleed vs RFC 6520 §4) · `ppi.py` the scalar · `ratchet.py` the
    per-tenant memory · `record.py` the unified Requirement (3 provenance sources, one shape).
- **`THEORIES.md`** — the falsifiable ledger: every claim has a test that could have failed.
- **`ppi_benchmark.json`** — the published corpus + PPI rows.
- **`global_norms.py` / `global_norms.json`** — the global norms derived from the corpus (dim 6).
- **`designs/`** — the design recommendations behind each dimension.

## Install + run (local, zero-exfiltration)
```
pip install -e .               # from this directory; PyPI name `reqdonkey` (publish pending)
reqdonkey /path/to/repo        # the PPI, the inferred requirements, and the gaps
reqdonkey /path/to/repo --json
```
Same repo + same versioned inputs (`ppi@v0`, `reqlex@v1`, `classes@v0`, the vendored specs, the
pinned witness) → byte-identical PPI, gaps, and provenance tell.

## Badge
Show your construction score. In CI, emit the shields endpoint JSON and serve it (commit it, or
publish to a gist / Pages):
```
reqdonkey . --no-ratchet --badge > ppi-badge.json
```
Then in your README:
```
![PPI](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/OWNER/REPO/main/ppi-badge.json)
```
Color tracks the global bar (doloop.io/ppi): brightgreen ≥ 0.85, green ≥ 0.78, yellow ≥ 0.6.

## Reproduce the benchmark + the global norms
```
modal run modal_benchmark.py     # the corpus (or run reqdonkey per repo)
python3 global_norms.py          # the global norms from the corpus
```

## The method (why it's a moat, not a tool)
Witnesses (Semgrep today; Infer/CodeQL next) do the dataflow — the commodity a competent engineer
gets for free. doloop's layer is the part no analyzer does: it **infers the requirement from the
codebase's own consistency** (≥4 sites, ≥70% adherence → the norm; deviations = gaps; otherwise no
requirement — no crying wolf), reads the docs and the governing specs, derives the **global norms**
from the corpus, and collapses everything to the reproducible PPI. The inference + the 6-dimension
framework + the published standards are ours; the witness is anyone's.
