Metadata-Version: 2.4
Name: oddrun
Version: 0.2.0
Summary: Experimental diagnosis of Python behavior differences across environments.
Author: Dharmit Kunal Shah
Maintainer: Dharmit Kunal Shah
License-Expression: MIT
Project-URL: Homepage, https://github.com/dkshah25/oddrun
Project-URL: Documentation, https://github.com/dkshah25/oddrun#readme
Project-URL: Repository, https://github.com/dkshah25/oddrun
Project-URL: Issues, https://github.com/dkshah25/oddrun/issues
Project-URL: Changelog, https://github.com/dkshah25/oddrun/blob/main/CHANGELOG.md
Keywords: python,debugging,reproducibility,environment,diagnostics,testing
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Debuggers
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: build>=1.0.0; extra == "dev"
Dynamic: license-file

# OddRun

> When the same code doesn't behave the same.

OddRun is a systematic causal diagnostic engine for Python that experimentally investigates and explains why code behaves differently across environments.

## Why OddRun?

Traditional environment tools answer:
> *"What is different between these environments?"*

OddRun experimentally investigates:
> *"Which difference (or combination of differences) actually caused the program's behavior to change?"*

### Environment Diff vs. Causal Investigation

- **Environment Diff**: *"TZ and LANG differ between local machine and server."*
- **OddRun Causal Diagnosis**: *"Neither `TZ` nor `LANG` alone reproduced failure, but perturbing both together (`TZ=UTC + LANG=C`) consistently reproduced target failure (3/3 runs)."*

---

## Quickstart

```bash
pip install oddrun
```

OddRun runs locally with zero external runtime dependencies.

---

## The Workflow: `record` → `diagnose` → `reproduce`

### 1. On Target Environment (Where code fails)

Record host environment snapshot and failure behavior signature:

```bash
oddrun record -o target-run.json -- python app.py
```

### 2. On Baseline Environment (Where code passes)

Perform systematic causal diagnosis:

```bash
oddrun diagnose --target target-run.json --interactions -- python app.py
```

#### Output Demonstration

```text
OddRun Causal Diagnosis
============================================================
Command         : python app.py
Target Record   : target-run.json
Differences     : 4 total (4 candidates tested)

[1/3] Baseline Stability ... PASS (3/3 identical runs)
[2/3] Testing Single-Factor Candidates...
  (No single candidate factor reproduced the target failure)

Testing Pairwise Interactions...
  TZ + LANG .................... REPRODUCED FAILURE (3/3)

[3/3] Evaluating Causal Evidence...

EXPERIMENTALLY SUPPORTED INTERACTION FACTOR(S)
============================================================
Interaction Factors : TZ + LANG
Factor 1            : TZ (Asia/Kolkata -> UTC)
Factor 2            : LANG (en_US.UTF-8 -> C)
Forward Test        : 3/3
Evidence            : STRONG (Interaction Verified)

Interpretation:
  Neither 'TZ' nor 'LANG' alone reproduced failure, but perturbing both together (TZ + LANG) consistently reproduced target failure.

Recommendation:
  Avoid coupling application behavior across environmental factors 'TZ' and 'LANG'.
------------------------------------------------------------

Note: This is strong causal evidence, not proof that these are the unique possible causes.
```

### 3. Generate Minimal Reproduction Bundle

Generate a self-contained reproduction directory containing shell scripts and environment settings:

```bash
oddrun reproduce target-run.json -o reproduction/
```

Produces:
- `reproduction/environment.json` (Structured environmental overrides)
- `reproduction/reproduce.sh` (POSIX Bash reproduction script with escaping)
- `reproduction/reproduce.ps1` (Windows PowerShell reproduction script)
- `reproduction/README.md` (Self-contained instructions)

---

## Core Features (v0.2.0)

- **Systematic Causal Diagnosis (`oddrun diagnose`)**: High-level workflow engine for baseline verification, single-factor perturbation, and interaction testing.
- **Pairwise Interaction Testing (`--interactions`)**: Detects environmental bugs caused by 2-factor interactions ($A \rightarrow \text{PASS}, B \rightarrow \text{PASS}, A+B \rightarrow \text{FAIL}$) with bounded candidate cap (`--max-interaction-factors 5`).
- **Flakiness Detection & Repeatability (`--runs N`)**: Confirms baseline stability across $N$ repetitions. Strictly aborts causal attribution on non-deterministic baselines (`UNSTABLE_BASELINE`).
- **Richer Behavioral Fingerprints**: Categorizes match levels (`EXACT_MATCH`, `DIFFERENT_FAILURE`, `PARTIAL_CHANGE`, `DISTINCT`) based on exit code, exception type, and diagnostic output normalization.
- **Structured JSON Output (`--format json`)**: Emits valid JSON to `sys.stdout` for CI and automation scripts.
- **Runtime Provenance**: Captures Python `sys.path`, interpreter executable, and package install locations.

---

## Commands

| Command | Action | Output / Artifact |
| :--- | :--- | :--- |
| `oddrun capture` | Captures host environment snapshot | `EnvironmentSnapshot` JSON |
| `oddrun record` | Executes command 1x under observation | `ExecutionRecord` JSON |
| `oddrun compare` | Structural comparison of 2 snapshots | Diff text or JSON |
| `oddrun diagnose` / `why` | Systematic causal environment diagnosis | Terminal report or JSON |
| `oddrun reproduce` | Generates self-contained reproduction bundle | Reproduction bundle directory |

---

## Security & Privacy

- **Local-First & Zero Telemetry**: Runs locally without cloud dependencies or telemetry.
- **Subprocess Isolation**: Executes commands in isolated process trees (`shell=False`) without mutating parent environment.
- **Automatic Secret Redaction**: Sensitive environment keys (`API_KEY`, `SECRET`, `PASSWORD`, `TOKEN`, `CREDENTIAL`, etc.) are automatically redacted to `"<present>"`.

---

## Development

```bash
# Install package in editable mode
pip install -e ".[dev]"

# Run full test suite
python -m pytest

# Run linter
python -m ruff check .
```

---

## License

[MIT License](https://github.com/dkshah25/oddrun/blob/main/LICENSE)
