Metadata-Version: 2.4
Name: driftscope-runtime
Version: 0.2.1
Summary: Runtime API drift and source blast-radius detector
Author: Viraj Sabhaya
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/virajsabhaya23/driftscope
Project-URL: Repository, https://github.com/virajsabhaya23/driftscope
Project-URL: Issues, https://github.com/virajsabhaya23/driftscope/issues
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# DriftScope

**Runtime API drift + source blast-radius detector.**

DriftScope complements OpenAPI diff tools by using **observed JSON responses** as the evidence source and mapping risky changes into consuming Python/JavaScript/TypeScript code.

## Quick start

Python 3.10+. Runtime dependencies: none.

```bash
python -m pip install driftscope-runtime

python -m driftscope compare \
  --endpoint "GET /rate_limit" \
  --baseline examples/baseline.json \
  --current examples/current.json \
  --source-dir examples/app \
  --out out/report.json \
  --junit out/report.junit.xml \
  --sarif out/report.sarif.json \
  --fixture-out out/regression-fixture.json
```

High-severity drift returns exit code `2` for CI.

## Probe a public JSON endpoint

```bash
python -m driftscope probe https://api.example.com/resource --out snapshots/current.json
```

Only HTTP(S) is allowed and responses are capped at 5 MB by default.

## Benchmark

```bash
python -m driftscope benchmark benchmark/corpus.json --out benchmark/results.json
```

The corpus contains 50 minimal runtime fixtures mapped to officially documented GitHub REST API 2026 breaking changes/affected endpoints. It measures runtime detectability and source-impact mapping and includes a **stale-spec counterfactual replay** where the old spec is intentionally held unchanged while runtime payloads change. That replay demonstrates the no-spec/stale-spec coverage gap; it is not a claim about historical wall-clock detection timing. It **does not** claim the fixtures are archived production traffic.

## What is implemented

- runtime JSON structural fingerprints;
- removed/type/nullability/presence drift;
- bounded observed scalar-domain and numeric-range drift;
- Python AST source usage mapping;
- JS/TS property/destructuring usage mapping;
- impacted-file and risk scoring;
- deterministic SHA-256 report certificates;
- generated regression-fixture manifests;
- JSON/JUnit/SARIF output;
- safe bounded HTTP JSON probe;
- GitHub Actions CI;
- 50-case provenance-backed benchmark.

## Security

DriftScope performs no shell execution. The probe restricts schemes and response size. Source scanning is read-only and ignores common dependency/build directories.

## Limits

- Runtime sampling cannot prove behavior for unseen payload variants.
- Source mapping is conservative static evidence, not a full call graph.
- The included spec-only benchmark metadata is not an `oasdiff` run.
- Wall-clock 'earlier than spec update' claims require archived runtime traffic and timestamped historical spec snapshots; this build does not invent those timestamps.
