repofail 0.1.2__tar.gz

repofail-0.1.2/.github/workflows/publish.yml

@@ -0,0 +1,26 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+      contents: read
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - run: pip install build
+
+      - run: python -m build
+
+      - uses: pypa/gh-action-pypi-publish@release/v1

repofail-0.1.2/.github/workflows/repofail.yml

@@ -0,0 +1,63 @@
+# repofail — CI guardrail for runtime compatibility
+#
+# In this repo: checks repofail itself.
+# To use in your repo: copy this file, change install step to:
+#   pip install git+https://github.com/youruser/repofail.git
+#   # or: pip install repofail  (when on PyPI)
+
+name: repofail
+
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+    branches: [main, master]
+
+jobs:
+  check:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python: ["3.10", "3.11", "3.12"]
+        exclude:
+          # Trim matrix: 3.11 on each OS is enough for quick CI
+          - os: ubuntu-latest
+            python: "3.10"
+          - os: ubuntu-latest
+            python: "3.12"
+          - os: macos-latest
+            python: "3.10"
+          - os: macos-latest
+            python: "3.12"
+          - os: windows-latest
+            python: "3.10"
+          - os: windows-latest
+            python: "3.12"
+    runs-on: ${{ matrix.os }}
+    env:
+      PYTHONUTF8: 1
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+
+      - name: Install repofail
+        run: pip install -e .
+
+      - name: Run repofail
+        run: repofail --ci
+
+      - name: Test all commands
+        run: |
+          repofail
+          repofail -j
+          repofail gen .
+          repofail s
+          repofail a .
+
+      - name: Run tests
+        run: pip install pytest && pytest tests/ -v

repofail-0.1.2/.gitignore

@@ -0,0 +1,8 @@
+dist/
+__pycache__/
+*.pyc
+.pytest_cache/
+*.egg-info/
+.eggs/
+VISION.md
+repofail-contract.json

repofail-0.1.2/CONTRIBUTING.md

@@ -0,0 +1,17 @@
+# Contributing
+
+repofail is opinionated and deterministic.
+
+We welcome:
+
+- New deterministic rules
+- Improvements to host inspection
+- Clearer error evidence
+- Performance improvements
+
+We do NOT accept:
+
+- Heuristic guesses
+- AI-based predictions
+- Cloud integrations
+- Non-deterministic scoring

repofail-0.1.2/PKG-INFO

@@ -0,0 +1,244 @@
+Metadata-Version: 2.4
+Name: repofail
+Version: 0.1.2
+Summary: Predict why a repository will fail on your machine before you run it.
+Author: Jayanth
+Requires-Python: >=3.10
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: tomli>=2.0; python_version < '3.11'
+Requires-Dist: typer>=0.9.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="docs/logo.png" width="180" alt="repofail logo">
+</p>
+
+<h1 align="center">repofail</h1>
+
+<p align="center">
+  Deterministic runtime compatibility analyzer
+</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/repofail/"><img src="https://img.shields.io/pypi/v/repofail"></a>
+  <img src="https://img.shields.io/badge/ci-passing-brightgreen">
+  <img src="https://img.shields.io/badge/python-3.10+-blue">
+  <img src="https://img.shields.io/badge/runtime-validated-success">
+  <img src="https://img.shields.io/badge/rules-20+-informational">
+</p>
+
+<p align="center">
+  Predict why a repository will fail on your machine before you run it.
+</p>
+
+<p align="center">
+  <em>repofail answers one question: <strong>Will this repository actually run here?</strong><br>
+  It inspects both the repo and your machine — then reports deterministic incompatibilities before you install anything.</em>
+</p>
+
+<p align="center">
+  <a href="#why-this-exists">Why</a> ·
+  <a href="#example-output">Example</a> ·
+  <a href="#works-on">Works on</a> ·
+  <a href="#install">Install</a> ·
+  <a href="#usage">Usage</a> ·
+  <a href="#rules">Rules</a> ·
+  <a href="#ci-integration">CI</a> ·
+  <a href="#contracts">Contracts</a>
+</p>
+
+---
+
+## Why This Exists
+
+Most tools install dependencies.
+
+Few tools tell you:
+
+- Your Node version violates `engines.node`.
+- Docker targets the wrong architecture.
+- CUDA is hard-coded with no fallback.
+- CI and local Python versions drifted.
+
+repofail inspects both the repository and your machine — then reports deterministic incompatibilities before install or runtime.
+
+---
+
+## Works on
+
+repofail works on:
+
+- Python projects
+- Node projects
+- Dockerized repos
+- ML repositories
+- Monorepos
+
+Run it against any local clone.
+
+---
+
+## Example output
+
+<p align="center">
+  <img src="docs/screenshots/high_failure.png" width="850" alt="repofail output">
+</p>
+
+repofail surfaces deterministic failures before install or runtime. No heuristics. No AI guesses. Evidence only.
+
+---
+
+## Install
+
+**From PyPI (recommended)**
+
+```bash
+pip install repofail
+```
+
+Or with pipx (isolated CLI install):
+
+```bash
+pipx install repofail
+```
+
+**From source (development)**
+
+```bash
+git clone https://github.com/jayvenn21/repofail.git
+cd repofail
+pip install -e .
+```
+
+## Usage
+
+```bash
+# Scan
+repofail                    # Scan current dir
+repofail -p /path/to/repo   # Scan specific repo
+repofail -j                 # JSON output (machine-readable)
+repofail -m                 # Markdown output
+repofail -v                 # Verbose: rule IDs and low-confidence hints
+repofail --ci               # CI mode: exit 1 if HIGH rules fire
+repofail --fail-on MEDIUM   # CI: fail on MEDIUM or higher (default: HIGH)
+repofail -r                 # Save failure report when rules fire (opt-in telemetry)
+
+# Rules
+repofail -e list            # List all rules
+repofail -e spec_drift      # Explain a rule
+
+# Contracts
+repofail gen .              # Generate env contract to stdout
+repofail gen . -o contract.json
+repofail check contract.json
+
+# Fleet
+repofail a /path            # Audit: scan all repos in directory
+repofail a /path -j         # Audit with JSON output
+repofail sim . -H host.json # Simulate: would this work on target host?
+repofail s                  # Stats: local failure counts (from -r reports)
+repofail s -j               # Stats with JSON output
+```
+
+---
+
+## CI integration
+
+```yaml
+- uses: actions/checkout@v4
+- uses: actions/setup-python@v5
+  with:
+    python-version: "3.12"
+- run: pip install repofail
+- run: repofail --ci
+```
+
+Exits 1 if HIGH rules fire. Use `--fail-on MEDIUM` to be stricter.
+
+## Contracts
+
+```bash
+repofail gen . -o contract.json
+repofail check contract.json
+```
+
+Versioned runtime expectations. Teams share contracts. CI checks drift.
+
+---
+
+## Rules
+
+| Tool | Reads Repo | Inspects Host | Predicts Failure | CI Enforceable |
+|------|------------|---------------|------------------|----------------|
+| pip | ✅ | ❌ | ❌ | ❌ |
+| Docker | ✅ | ❌ | ❌ | ❌ |
+| **repofail** | ✅ | ✅ | ✅ | ✅ |
+
+**Deterministic rule coverage** — repofail includes checks across:
+
+- **Spec violations** — version ranges, engines.node, requires-python
+- **Architecture mismatches** — Apple Silicon vs amd64 Docker
+- **Hardware constraints** — CUDA requirements, GPU memory
+- **Toolchain gaps** — missing compilers, Rust, node-gyp
+- **Runtime drift** — CI vs Docker vs local inconsistencies
+- **Environment shape** — multi-service RAM pressure, port collisions
+
+See all rules: `repofail -e list` · Explain one: `repofail -e <rule_id>`
+
+<details>
+<summary>Rule reference</summary>
+
+| Rule | Severity | When |
+|------|----------|------|
+| Torch CUDA mismatch | HIGH | Hard-coded CUDA, host has no GPU |
+| Python version violation | HIGH | Host outside `requires-python` range |
+| Spec drift | HIGH | pyproject vs Docker vs CI — inconsistent Python |
+| Node engine mismatch | HIGH | package.json engines.node vs host |
+| Lock file missing | HIGH | package.json has deps, no lock file |
+| Apple Silicon wheel mismatch | MEDIUM/HIGH | arm64 + x86-only packages or Docker amd64 |
+| … | | `repofail -e list` |
+
+</details>
+
+<details>
+<summary>Scoring model</summary>
+
+**Compatibility Score** = `100 − Σ(weight × confidence × determinism)`
+
+| Severity | Weight | Determinism |
+|----------|--------|-------------|
+| HIGH | 45 | 1.0 for spec violations |
+| MEDIUM | 20 | 0.8–1.0 |
+| LOW | 7 | 0.5–1.0 |
+| INFO | 5 | structural only |
+
+**Determinism scale:** `1.0` = guaranteed failure · `0.75` = high likelihood · `0.6` = probabilistic (spec drift) · `0.5` = structural risk
+
+Score floors at 10%. When score ≤15% with HIGH rules: "— fatal deterministic violations present".
+
+</details>
+
+---
+
+## Architecture
+
+```
+repofail/
+  cli.py
+  engine.py
+  scanner/         # Repo + host inspection
+  rules/           # Deterministic rule implementations
+  fleet.py         # Audit, simulate
+```
+
+Extensible via `.repofail/rules.yaml`.
+
+---
+
+## Testing
+
+```bash
+pytest tests/ -v
+```

repofail-0.1.2/README.md

@@ -0,0 +1,231 @@
+<p align="center">
+  <img src="docs/logo.png" width="180" alt="repofail logo">
+</p>
+
+<h1 align="center">repofail</h1>
+
+<p align="center">
+  Deterministic runtime compatibility analyzer
+</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/repofail/"><img src="https://img.shields.io/pypi/v/repofail"></a>
+  <img src="https://img.shields.io/badge/ci-passing-brightgreen">
+  <img src="https://img.shields.io/badge/python-3.10+-blue">
+  <img src="https://img.shields.io/badge/runtime-validated-success">
+  <img src="https://img.shields.io/badge/rules-20+-informational">
+</p>
+
+<p align="center">
+  Predict why a repository will fail on your machine before you run it.
+</p>
+
+<p align="center">
+  <em>repofail answers one question: <strong>Will this repository actually run here?</strong><br>
+  It inspects both the repo and your machine — then reports deterministic incompatibilities before you install anything.</em>
+</p>
+
+<p align="center">
+  <a href="#why-this-exists">Why</a> ·
+  <a href="#example-output">Example</a> ·
+  <a href="#works-on">Works on</a> ·
+  <a href="#install">Install</a> ·
+  <a href="#usage">Usage</a> ·
+  <a href="#rules">Rules</a> ·
+  <a href="#ci-integration">CI</a> ·
+  <a href="#contracts">Contracts</a>
+</p>
+
+---
+
+## Why This Exists
+
+Most tools install dependencies.
+
+Few tools tell you:
+
+- Your Node version violates `engines.node`.
+- Docker targets the wrong architecture.
+- CUDA is hard-coded with no fallback.
+- CI and local Python versions drifted.
+
+repofail inspects both the repository and your machine — then reports deterministic incompatibilities before install or runtime.
+
+---
+
+## Works on
+
+repofail works on:
+
+- Python projects
+- Node projects
+- Dockerized repos
+- ML repositories
+- Monorepos
+
+Run it against any local clone.
+
+---
+
+## Example output
+
+<p align="center">
+  <img src="docs/screenshots/high_failure.png" width="850" alt="repofail output">
+</p>
+
+repofail surfaces deterministic failures before install or runtime. No heuristics. No AI guesses. Evidence only.
+
+---
+
+## Install
+
+**From PyPI (recommended)**
+
+```bash
+pip install repofail
+```
+
+Or with pipx (isolated CLI install):
+
+```bash
+pipx install repofail
+```
+
+**From source (development)**
+
+```bash
+git clone https://github.com/jayvenn21/repofail.git
+cd repofail
+pip install -e .
+```
+
+## Usage
+
+```bash
+# Scan
+repofail                    # Scan current dir
+repofail -p /path/to/repo   # Scan specific repo
+repofail -j                 # JSON output (machine-readable)
+repofail -m                 # Markdown output
+repofail -v                 # Verbose: rule IDs and low-confidence hints
+repofail --ci               # CI mode: exit 1 if HIGH rules fire
+repofail --fail-on MEDIUM   # CI: fail on MEDIUM or higher (default: HIGH)
+repofail -r                 # Save failure report when rules fire (opt-in telemetry)
+
+# Rules
+repofail -e list            # List all rules
+repofail -e spec_drift      # Explain a rule
+
+# Contracts
+repofail gen .              # Generate env contract to stdout
+repofail gen . -o contract.json
+repofail check contract.json
+
+# Fleet
+repofail a /path            # Audit: scan all repos in directory
+repofail a /path -j         # Audit with JSON output
+repofail sim . -H host.json # Simulate: would this work on target host?
+repofail s                  # Stats: local failure counts (from -r reports)
+repofail s -j               # Stats with JSON output
+```
+
+---
+
+## CI integration
+
+```yaml
+- uses: actions/checkout@v4
+- uses: actions/setup-python@v5
+  with:
+    python-version: "3.12"
+- run: pip install repofail
+- run: repofail --ci
+```
+
+Exits 1 if HIGH rules fire. Use `--fail-on MEDIUM` to be stricter.
+
+## Contracts
+
+```bash
+repofail gen . -o contract.json
+repofail check contract.json
+```
+
+Versioned runtime expectations. Teams share contracts. CI checks drift.
+
+---
+
+## Rules
+
+| Tool | Reads Repo | Inspects Host | Predicts Failure | CI Enforceable |
+|------|------------|---------------|------------------|----------------|
+| pip | ✅ | ❌ | ❌ | ❌ |
+| Docker | ✅ | ❌ | ❌ | ❌ |
+| **repofail** | ✅ | ✅ | ✅ | ✅ |
+
+**Deterministic rule coverage** — repofail includes checks across:
+
+- **Spec violations** — version ranges, engines.node, requires-python
+- **Architecture mismatches** — Apple Silicon vs amd64 Docker
+- **Hardware constraints** — CUDA requirements, GPU memory
+- **Toolchain gaps** — missing compilers, Rust, node-gyp
+- **Runtime drift** — CI vs Docker vs local inconsistencies
+- **Environment shape** — multi-service RAM pressure, port collisions
+
+See all rules: `repofail -e list` · Explain one: `repofail -e <rule_id>`
+
+<details>
+<summary>Rule reference</summary>
+
+| Rule | Severity | When |
+|------|----------|------|
+| Torch CUDA mismatch | HIGH | Hard-coded CUDA, host has no GPU |
+| Python version violation | HIGH | Host outside `requires-python` range |
+| Spec drift | HIGH | pyproject vs Docker vs CI — inconsistent Python |
+| Node engine mismatch | HIGH | package.json engines.node vs host |
+| Lock file missing | HIGH | package.json has deps, no lock file |
+| Apple Silicon wheel mismatch | MEDIUM/HIGH | arm64 + x86-only packages or Docker amd64 |
+| … | | `repofail -e list` |
+
+</details>
+
+<details>
+<summary>Scoring model</summary>
+
+**Compatibility Score** = `100 − Σ(weight × confidence × determinism)`
+
+| Severity | Weight | Determinism |
+|----------|--------|-------------|
+| HIGH | 45 | 1.0 for spec violations |
+| MEDIUM | 20 | 0.8–1.0 |
+| LOW | 7 | 0.5–1.0 |
+| INFO | 5 | structural only |
+
+**Determinism scale:** `1.0` = guaranteed failure · `0.75` = high likelihood · `0.6` = probabilistic (spec drift) · `0.5` = structural risk
+
+Score floors at 10%. When score ≤15% with HIGH rules: "— fatal deterministic violations present".
+
+</details>
+
+---
+
+## Architecture
+
+```
+repofail/
+  cli.py
+  engine.py
+  scanner/         # Repo + host inspection
+  rules/           # Deterministic rule implementations
+  fleet.py         # Audit, simulate
+```
+
+Extensible via `.repofail/rules.yaml`.
+
+---
+
+## Testing
+
+```bash
+pytest tests/ -v
+```

repofail-0.1.2/RULES.md

@@ -0,0 +1,95 @@
+# repofail Rules
+
+High-confidence incompatibility rules. Deterministic, no AI. Extensible via YAML.
+
+## List rules
+
+```bash
+repofail --explain list
+repofail --explain torch_cuda_mismatch
+```
+
+## The rules
+
+### 1. torch_cuda_mismatch (HIGH)
+
+**When:** Repo imports `torch.cuda` or uses `device="cuda"` but host has no NVIDIA GPU.
+
+**Fix:** Run on a machine with CUDA, or use CPU-only PyTorch.
+
+---
+
+### 2. apple_silicon_wheels (MEDIUM/HIGH)
+
+**When:** Host is macOS arm64 and repo depends on packages with x86-only wheels: `nvidia-cuda-*`, `cuda-python`, `horovod`, etc.
+
+**Fix:** Use Rosetta, conda-forge, or verify ARM wheels exist.
+
+---
+
+### 3. python_version_mismatch (HIGH)
+
+**When:** Repo's `requires-python` (pyproject.toml/setup.py) doesn't include host's Python version.
+
+**Fix:** Install the required Python (pyenv, conda, asdf).
+
+---
+
+### 4. native_toolchain_missing (MEDIUM)
+
+**When:** Repo has Node native modules (node-gyp) or Rust/Cargo, but host has no gcc/clang.
+
+**Fix:** Install Xcode CLI tools (macOS) or `build-essential` (Linux).
+
+---
+
+### 5. gpu_memory_risk (LOW/MEDIUM)
+
+**When:** Repo uses torch + diffusers/transformers and host RAM < 16 GB.
+
+**Fix:** Use smaller models, add swap, or run on a machine with more RAM.
+
+---
+
+### 6. node_native_windows (MEDIUM)
+
+**When:** Host is Windows and repo has Node native modules (node-gyp).
+
+**Fix:** Use WSL, or install Visual Studio Build Tools.
+
+---
+
+### 7. missing_system_libs (MEDIUM)
+
+**When:** Repo requires libGL (opencv) or ffmpeg but host doesn't have them.
+
+**Fix:** Install libgl1-mesa-glx (Linux) or ffmpeg.
+
+---
+
+## YAML Rules (Step 3 — Extensible)
+
+Add `.repofail/rules.yaml` or `repofail-rules.yaml` in your repo:
+
+```yaml
+- id: custom_cuda_check
+  when:
+    repo.uses_torch: true
+    host.cuda_available: false
+  severity: HIGH
+  explanation: "Custom CUDA check for this project"
+```
+
+---
+
+## Contributing rules
+
+Rules are in `repofail/rules/`. Each rule is a module with:
+
+1. `check(repo: RepoProfile, host: HostProfile) -> RuleResult | None`
+2. Returns `None` if the rule doesn't apply
+3. Returns `RuleResult` with `rule_id`, `severity`, `message`, `reason`, `host_summary`
+
+Add metadata to `repofail/rules/registry.py` for `--explain`. Add the check to `repofail/engine.py`.
+
+Keep rules deterministic. No network. No guessing.

repofail-0.1.2/contract.json

@@ -0,0 +1,9 @@
+{
+  "repofail_contract": "1",
+  "generated_by": "repofail 0.1.0",
+  "repo": "repofail",
+  "requires": {
+    "python": ">=3.10"
+  },
+  "optional": {}
+}