oddrun 0.1.0__tar.gz

oddrun-0.1.0/LICENSE

@@ -0,0 +1,20 @@
+MIT License
+
+Copyright (c) 2026 OddRun Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO MECHANICAL FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE
+FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR
+THE USE OR OTHER DEALINGS IN THE SOFTWARE.

oddrun-0.1.0/PKG-INFO

@@ -0,0 +1,136 @@
+Metadata-Version: 2.4
+Name: oddrun
+Version: 0.1.0
+Summary: Investigates why the same Python program behaves differently across environments.
+Author: OddRun Contributors
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/oddrun/oddrun
+Project-URL: Documentation, https://github.com/oddrun/oddrun#readme
+Project-URL: Repository, https://github.com/oddrun/oddrun
+Project-URL: Issues, https://github.com/oddrun/oddrun/issues
+Keywords: debugging,environment,reproducibility,diff,snapshot,developer-tools
+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 Python developer tool that investigates why the same program behaves differently across environments.
+
+Traditional environment tools answer:
+> *"What is different between these environments?"*
+
+OddRun answers:
+> *"Which difference experimentally explains the observed failure?"*
+
+---
+
+## Core Product Model
+
+| Subcommand | Question | Input Artifact |
+| :--- | :--- | :--- |
+| `oddrun capture` | **What's different?** Captures environment state | `EnvironmentSnapshot` JSON |
+| `oddrun compare` | **What changed?** Compares two environment snapshots | Two `EnvironmentSnapshot` JSONs |
+| `oddrun record` | **What actually happened here?** Executes command 1x on target | `ExecutionRecord` JSON |
+| `oddrun why` | **Which difference explains the target behavior?** | `ExecutionRecord` JSON + `<command>` |
+
+---
+
+## Quickstart
+
+### Installation
+
+```bash
+pip install oddrun
+```
+
+### The Distributed Workflow (`record` → `why`)
+
+#### 1. On Target Environment (e.g. CI / Remote Server where code fails)
+Execute the failing command once to record the environment state and observed failure signature:
+
+```bash
+oddrun record -o target-run.json -- pytest tests/test_date.py
+```
+*(Generates `target-run.json` containing safe environment metadata and the observed failure `BehaviorSignature`)*
+
+#### 2. On Developer Machine (Baseline environment where code passes)
+Diagnose which environmental difference reproduces the target failure:
+
+```bash
+oddrun why target-run.json -- pytest tests/test_date.py
+```
+
+OddRun will:
+1. Verify baseline stability (3/3 identical passing runs in current environment).
+2. Rank environmental differences by safety tier (`TZ`, `LANG`, `LC_*`, application variables).
+3. Execute controlled perturbations (1x exploratory + 2x confirmation).
+4. Match structural behavior signatures (`exit_code`, `exception_type`, normalized diagnostic output).
+5. Report **Experimentally Supported Causal Factors** with remediation recommendations.
+
+---
+
+## Direct Environment Comparison (`capture` → `compare`)
+
+```bash
+# Capture local environment snapshot
+oddrun capture -o local.json
+
+# Compare local environment against target snapshot
+oddrun compare local.json target-run.json
+```
+
+---
+
+## Python API Usage
+
+```python
+from oddrun import (
+    capture_environment,
+    compare_snapshots,
+    record_execution,
+    diagnose_behavior,
+    load_record,
+)
+
+# 1. Record execution
+record = record_execution(["pytest", "tests/test_date.py"])
+print(f"Recorded outcome: {record.execution_result.behavior_signature.is_success}")
+
+# 2. Diagnose behavior against target record
+report = diagnose_behavior("target-run.json", ["pytest", "tests/test_date.py"])
+for factor in report.causal_factors:
+    print(f"Causal Factor: {factor.candidate.key} ({factor.evidence_level.value})")
+```
+
+---
+
+## Security & Privacy
+
+OddRun is strictly **local-first**:
+- Zero telemetry or analytics.
+- Zero network calls or cloud dependencies; operates 100% offline.
+- **Automatic Secret Redaction**: Sensitive environment keys (`API_KEY`, `SECRET`, `PASSWORD`, `TOKEN`, `CREDENTIAL`, `AUTH`, etc.) are automatically replaced with `"<present>"` before saving snapshots or execution records to disk.
+
+---
+
+## License
+
+[MIT License](LICENSE)

oddrun-0.1.0/README.md

@@ -0,0 +1,106 @@
+# OddRun
+
+> When the same code doesn't behave the same.
+
+OddRun is a Python developer tool that investigates why the same program behaves differently across environments.
+
+Traditional environment tools answer:
+> *"What is different between these environments?"*
+
+OddRun answers:
+> *"Which difference experimentally explains the observed failure?"*
+
+---
+
+## Core Product Model
+
+| Subcommand | Question | Input Artifact |
+| :--- | :--- | :--- |
+| `oddrun capture` | **What's different?** Captures environment state | `EnvironmentSnapshot` JSON |
+| `oddrun compare` | **What changed?** Compares two environment snapshots | Two `EnvironmentSnapshot` JSONs |
+| `oddrun record` | **What actually happened here?** Executes command 1x on target | `ExecutionRecord` JSON |
+| `oddrun why` | **Which difference explains the target behavior?** | `ExecutionRecord` JSON + `<command>` |
+
+---
+
+## Quickstart
+
+### Installation
+
+```bash
+pip install oddrun
+```
+
+### The Distributed Workflow (`record` → `why`)
+
+#### 1. On Target Environment (e.g. CI / Remote Server where code fails)
+Execute the failing command once to record the environment state and observed failure signature:
+
+```bash
+oddrun record -o target-run.json -- pytest tests/test_date.py
+```
+*(Generates `target-run.json` containing safe environment metadata and the observed failure `BehaviorSignature`)*
+
+#### 2. On Developer Machine (Baseline environment where code passes)
+Diagnose which environmental difference reproduces the target failure:
+
+```bash
+oddrun why target-run.json -- pytest tests/test_date.py
+```
+
+OddRun will:
+1. Verify baseline stability (3/3 identical passing runs in current environment).
+2. Rank environmental differences by safety tier (`TZ`, `LANG`, `LC_*`, application variables).
+3. Execute controlled perturbations (1x exploratory + 2x confirmation).
+4. Match structural behavior signatures (`exit_code`, `exception_type`, normalized diagnostic output).
+5. Report **Experimentally Supported Causal Factors** with remediation recommendations.
+
+---
+
+## Direct Environment Comparison (`capture` → `compare`)
+
+```bash
+# Capture local environment snapshot
+oddrun capture -o local.json
+
+# Compare local environment against target snapshot
+oddrun compare local.json target-run.json
+```
+
+---
+
+## Python API Usage
+
+```python
+from oddrun import (
+    capture_environment,
+    compare_snapshots,
+    record_execution,
+    diagnose_behavior,
+    load_record,
+)
+
+# 1. Record execution
+record = record_execution(["pytest", "tests/test_date.py"])
+print(f"Recorded outcome: {record.execution_result.behavior_signature.is_success}")
+
+# 2. Diagnose behavior against target record
+report = diagnose_behavior("target-run.json", ["pytest", "tests/test_date.py"])
+for factor in report.causal_factors:
+    print(f"Causal Factor: {factor.candidate.key} ({factor.evidence_level.value})")
+```
+
+---
+
+## Security & Privacy
+
+OddRun is strictly **local-first**:
+- Zero telemetry or analytics.
+- Zero network calls or cloud dependencies; operates 100% offline.
+- **Automatic Secret Redaction**: Sensitive environment keys (`API_KEY`, `SECRET`, `PASSWORD`, `TOKEN`, `CREDENTIAL`, `AUTH`, etc.) are automatically replaced with `"<present>"` before saving snapshots or execution records to disk.
+
+---
+
+## License
+
+[MIT License](LICENSE)

oddrun-0.1.0/pyproject.toml

@@ -0,0 +1,75 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "oddrun"
+version = "0.1.0"
+description = "Investigates why the same Python program behaves differently across environments."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [
+    { name = "OddRun Contributors" }
+]
+keywords = [
+    "debugging",
+    "environment",
+    "reproducibility",
+    "diff",
+    "snapshot",
+    "developer-tools"
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Software Development :: Debuggers",
+    "Topic :: Software Development :: Testing",
+]
+dependencies = []
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0.0",
+    "ruff>=0.1.0",
+    "build>=1.0.0",
+]
+
+[project.scripts]
+oddrun = "oddrun.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/oddrun/oddrun"
+Documentation = "https://github.com/oddrun/oddrun#readme"
+Repository = "https://github.com/oddrun/oddrun"
+Issues = "https://github.com/oddrun/oddrun/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.ruff]
+line-length = 88
+target-version = "py310"
+
+[tool.ruff.lint]
+select = [
+    "E",   # pycodestyle errors
+    "W",   # pycodestyle warnings
+    "F",   # pyflakes
+    "I",   # isort
+    "B",   # flake8-bugbear
+    "C4",  # flake8-comprehensions
+    "UP",  # pyupgrade
+]
+ignore = []
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+addopts = "-v"

oddrun-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

oddrun-0.1.0/src/oddrun/__init__.py

@@ -0,0 +1,34 @@
+"""OddRun - When the same code doesn't behave the same."""
+
+from oddrun.compare import compare_snapshots
+from oddrun.diagnose import diagnose_behavior
+from oddrun.execution import ExecutionRecord, record_execution
+from oddrun.io import load_record, load_snapshot, save_record, save_snapshot
+from oddrun.models import (
+    DiffItem,
+    EnvironmentSnapshot,
+    PythonInfo,
+    SnapshotDiff,
+    SystemInfo,
+)
+from oddrun.snapshot import capture_environment
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "__version__",
+    "EnvironmentSnapshot",
+    "ExecutionRecord",
+    "PythonInfo",
+    "SystemInfo",
+    "SnapshotDiff",
+    "DiffItem",
+    "capture_environment",
+    "compare_snapshots",
+    "diagnose_behavior",
+    "load_record",
+    "load_snapshot",
+    "record_execution",
+    "save_record",
+    "save_snapshot",
+]

oddrun-0.1.0/src/oddrun/cli.py

@@ -0,0 +1,325 @@
+"""Command-line interface for OddRun."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from collections.abc import Sequence
+
+from oddrun import __version__
+from oddrun.compare import compare_snapshots
+from oddrun.diagnose import diagnose_behavior, format_diagnosis_text
+from oddrun.execution import ExecutionStatus, record_execution
+from oddrun.io import SnapshotIOError, load_snapshot, save_record, save_snapshot
+from oddrun.models import SnapshotDiff
+from oddrun.snapshot import capture_environment
+
+
+def format_diff_text(diff: SnapshotDiff) -> str:
+    """Format a SnapshotDiff into readable text lines."""
+    if not diff.has_differences:
+        return "No differences found between snapshots."
+
+    lines: list[str] = [
+        f"OddRun Environment Comparison: {diff.left_label} vs {diff.right_label}",
+        f"Total Differences: {len(diff.differences)}",
+        "-" * 60,
+    ]
+
+    current_cat = ""
+    for item in diff.differences:
+        if item.category != current_cat:
+            current_cat = item.category
+            lines.append(f"\n[{current_cat.upper()}]")
+
+        if item.change_type == "added":
+            lines.append(f"  + {item.key}: {item.right_value}")
+        elif item.change_type == "removed":
+            lines.append(f"  - {item.key}: (was: {item.left_value})")
+        else:
+            lines.append(f"  ~ {item.key}: {item.left_value} -> {item.right_value}")
+
+    return "\n".join(lines)
+
+
+def run_capture(args: argparse.Namespace) -> int:
+    """Execute 'oddrun capture' subcommand."""
+    snapshot = capture_environment()
+    output_path = args.output or "oddrun-snapshot.json"
+
+    try:
+        save_snapshot(snapshot, output_path)
+        print(f"Successfully captured environment snapshot: {output_path}")
+        return 0
+    except SnapshotIOError as exc:
+        print(f"ERROR: Could not write snapshot: {output_path}", file=sys.stderr)
+        print(f"Reason: {exc}", file=sys.stderr)
+        return 1
+    except Exception as exc:
+        if args.debug:
+            raise
+        print(f"ERROR: Unexpected failure during capture: {exc}", file=sys.stderr)
+        return 1
+
+
+def run_record(args: argparse.Namespace) -> int:
+    """Execute 'oddrun record' subcommand."""
+    command_argv = args.command
+    if not command_argv:
+        print("ERROR: No command specified for recording.", file=sys.stderr)
+        msg = "Usage: oddrun record --output RECORD.json -- COMMAND [ARGUMENTS...]"
+        print(msg, file=sys.stderr)
+        return 1
+
+    output_path = args.output or "oddrun-record.json"
+
+    try:
+        record = record_execution(command_argv, timeout_seconds=args.timeout)
+        if record.execution_result.status == ExecutionStatus.EXEC_ERROR:
+            err_msg = record.execution_result.error_message or "Execution failed"
+            print(f"ERROR: Could not execute command: {err_msg}", file=sys.stderr)
+            return 1
+
+        save_record(record, output_path)
+        outcome = "PASS" if record.execution_result.exit_code == 0 else "FAIL"
+        code = record.execution_result.exit_code
+        print(
+            f"Successfully recorded execution "
+            f"(Outcome: {outcome}, Exit Code: {code}): {output_path}"
+        )
+        return 0
+    except SnapshotIOError as exc:
+        print(f"ERROR: Could not write record file: {output_path}", file=sys.stderr)
+        print(f"Reason: {exc}", file=sys.stderr)
+        return 1
+    except Exception as exc:
+        if args.debug:
+            raise
+        print(f"ERROR: Unexpected failure during recording: {exc}", file=sys.stderr)
+        return 1
+
+
+def run_compare(args: argparse.Namespace) -> int:
+    """Execute 'oddrun compare' subcommand."""
+    left_file = args.snapshot1
+    right_file = args.snapshot2
+
+    try:
+        left_snap = load_snapshot(left_file)
+    except SnapshotIOError as exc:
+        print(f"ERROR: Could not read snapshot: {left_file}", file=sys.stderr)
+        print(f"Reason: {exc}", file=sys.stderr)
+        return 1
+    except Exception as exc:
+        if args.debug:
+            raise
+        print(f"ERROR: Failed loading snapshot '{left_file}': {exc}", file=sys.stderr)
+        return 1
+
+    try:
+        right_snap = load_snapshot(right_file)
+    except SnapshotIOError as exc:
+        print(f"ERROR: Could not read snapshot: {right_file}", file=sys.stderr)
+        print(f"Reason: {exc}", file=sys.stderr)
+        return 1
+    except Exception as exc:
+        if args.debug:
+            raise
+        print(f"ERROR: Failed loading snapshot '{right_file}': {exc}", file=sys.stderr)
+        return 1
+
+    diff = compare_snapshots(
+        left_snap, right_snap, left_label=str(left_file), right_label=str(right_file)
+    )
+
+    if args.json:
+        print(json.dumps(diff.to_dict(), indent=2))
+    else:
+        print(format_diff_text(diff))
+
+    return 0
+
+
+def run_why(args: argparse.Namespace) -> int:
+    """Execute 'oddrun why' subcommand."""
+    target_record = args.target_record
+    command_argv = args.command
+
+    if not command_argv:
+        print("ERROR: No command specified for diagnosis.", file=sys.stderr)
+        msg = "Usage: oddrun why TARGET_RECORD.json -- COMMAND [ARGUMENTS...]"
+        print(msg, file=sys.stderr)
+        return 1
+
+    try:
+        report = diagnose_behavior(
+            target_record=target_record,
+            command=command_argv,
+            allow_path_perturbation=args.allow_path_perturbation,
+            max_experiments=args.max_experiments,
+            timeout_seconds=args.timeout,
+        )
+        print(format_diagnosis_text(report))
+        return 0 if not report.error_message else 1
+    except SnapshotIOError as exc:
+        print(f"ERROR: Could not read target record: {target_record}", file=sys.stderr)
+        print(f"Reason: {exc}", file=sys.stderr)
+        return 1
+    except Exception as exc:
+        if args.debug:
+            raise
+        print(f"ERROR: Causal diagnosis failed: {exc}", file=sys.stderr)
+        return 1
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Construct the main argument parser for OddRun CLI."""
+    parser = argparse.ArgumentParser(
+        prog="oddrun",
+        description="OddRun - When the same code doesn't behave the same.",
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"%(prog)s {__version__}",
+    )
+    parser.add_argument(
+        "--debug",
+        action="store_true",
+        help="Enable full exception tracebacks on error.",
+    )
+
+    subparsers = parser.add_subparsers(dest="subcommand", help="Subcommands")
+
+    # Command: capture
+    capture_parser = subparsers.add_parser(
+        "capture",
+        help="Capture a privacy-aware snapshot of the current environment.",
+    )
+    capture_parser.add_argument(
+        "-o",
+        "--output",
+        default="oddrun-snapshot.json",
+        help="Path to output JSON file (default: oddrun-snapshot.json).",
+    )
+
+    # Command: record
+    record_parser = subparsers.add_parser(
+        "record",
+        help="Execute a command and record environment snapshot + behavior signature.",
+    )
+    record_parser.add_argument(
+        "-o",
+        "--output",
+        default="oddrun-record.json",
+        help="Path to output JSON record file (default: oddrun-record.json).",
+    )
+    record_parser.add_argument(
+        "--timeout",
+        type=float,
+        default=30.0,
+        help="Timeout in seconds for recording command execution (default: 30.0).",
+    )
+    record_parser.add_argument(
+        "command",
+        nargs=argparse.REMAINDER,
+        help="Command and arguments to execute after '--' separator.",
+    )
+
+    # Command: compare
+    compare_parser = subparsers.add_parser(
+        "compare",
+        help="Compare two environment snapshot files.",
+    )
+    compare_parser.add_argument(
+        "snapshot1",
+        help="Path to first snapshot JSON file.",
+    )
+    compare_parser.add_argument(
+        "snapshot2",
+        help="Path to second snapshot JSON file.",
+    )
+    compare_parser.add_argument(
+        "--json",
+        action="store_true",
+        help="Output comparison results in structured JSON format.",
+    )
+
+    # Command: why
+    why_parser = subparsers.add_parser(
+        "why",
+        help="Diagnose which environmental difference causes a program to fail.",
+    )
+    why_parser.add_argument(
+        "target_record",
+        help="Path to target ExecutionRecord JSON file.",
+    )
+    why_parser.add_argument(
+        "--allow-path-perturbation",
+        action="store_true",
+        help=(
+            "Allow testing Tier-2 executable/import factors "
+            "(PATH, PYTHONPATH, PYTHONHOME)."
+        ),
+    )
+    why_parser.add_argument(
+        "--max-experiments",
+        type=int,
+        default=10,
+        help="Maximum candidate perturbation experiments to test (default: 10).",
+    )
+    why_parser.add_argument(
+        "--timeout",
+        type=float,
+        default=30.0,
+        help="Timeout in seconds per perturbation experiment (default: 30.0).",
+    )
+    why_parser.add_argument(
+        "command",
+        nargs=argparse.REMAINDER,
+        help="Command and arguments to execute after '--' separator.",
+    )
+
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    """CLI entry point."""
+    parser = build_parser()
+
+    raw_argv = list(argv) if argv is not None else sys.argv[1:]
+    command_argv: list[str] = []
+
+    if "--" in raw_argv:
+        split_idx = raw_argv.index("--")
+        oddrun_args = raw_argv[:split_idx]
+        command_argv = raw_argv[split_idx + 1 :]
+    else:
+        oddrun_args = raw_argv
+
+    args = parser.parse_args(oddrun_args)
+    if command_argv:
+        args.command = command_argv
+    elif hasattr(args, "command") and args.command and args.command[0] == "--":
+        args.command = args.command[1:]
+
+    if not args.subcommand:
+        parser.print_help()
+        return 0
+
+    if args.subcommand == "capture":
+        return run_capture(args)
+    elif args.subcommand == "record":
+        return run_record(args)
+    elif args.subcommand == "compare":
+        return run_compare(args)
+    elif args.subcommand == "why":
+        return run_why(args)
+
+    parser.print_help()
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())