repofail 0.1.2__py3-none-any.whl

repofail/fleet.py

@@ -0,0 +1,116 @@
+"""Stage 5 — Fleet/enterprise: audit, simulate."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import asdict
+from pathlib import Path
+
+from .models import HostProfile, RepoProfile
+from .scanner import scan_repo, inspect_host
+from .engine import run_rules
+
+
+SKIP_AUDIT_DIRS = {".git", "__pycache__", ".venv", "venv", "node_modules", ".tox", "build", "dist", "eggs"}
+
+
+def _is_repo(p: Path) -> bool:
+    """Check if path looks like a repo (has .git or deps file)."""
+    return (
+        (p / ".git").exists()
+        or (p / "pyproject.toml").exists()
+        or (p / "requirements.txt").exists()
+        or (p / "package.json").exists()
+        or (p / "Cargo.toml").exists()
+    )
+
+
+def _find_repos(base_path: Path, max_depth: int = 4, max_repos: int = 50) -> list[Path]:
+    """Find repo roots recursively (nested repos)."""
+    found: list[Path] = []
+    base = Path(base_path).resolve()
+
+    def walk(d: Path, depth: int) -> None:
+        if depth > max_depth or len(found) >= max_repos:
+            return
+        if not d.is_dir():
+            return
+        if d.name.startswith(".") or d.name in SKIP_AUDIT_DIRS:
+            return
+        try:
+            rel = d.relative_to(base) if d != base else Path(".")
+            if any(part in SKIP_AUDIT_DIRS for part in rel.parts):
+                return
+        except ValueError:
+            return
+        if _is_repo(d):
+            found.append(d)
+            return  # Don't descend — this dir is the repo root
+        for child in sorted(d.iterdir()):
+            if child.is_dir():
+                walk(child, depth + 1)
+
+    for child in sorted(base.iterdir()):
+        if child.is_dir():
+            walk(child, 1)
+    if _is_repo(base):
+        found.insert(0, base)
+    return list(dict.fromkeys(found))  # dedupe
+
+
+def audit(base_path: Path) -> list[dict]:
+    """Scan all repo-like subdirs (including nested), return aggregated report."""
+    base_path = Path(base_path).resolve()
+    if not base_path.is_dir():
+        return []
+    dirs = _find_repos(base_path)
+    results = []
+    host = inspect_host()
+    for d in dirs:
+        try:
+            repo = scan_repo(d)
+            rule_results = run_rules(repo, host)
+            high_count = sum(1 for r in rule_results if r.severity.value == "HIGH")
+            med_count = sum(1 for r in rule_results if r.severity.value in ("MEDIUM", "LOW"))
+            results.append({
+                "path": str(d),
+                "name": repo.name or d.name,
+                "rule_count": len(rule_results),
+                "rules": [r.rule_id for r in rule_results],
+                "has_high": high_count > 0,
+                "high_count": high_count,
+                "medium_count": med_count,
+                "score": __import__("repofail.risk", fromlist=["estimate_success_probability"]).estimate_success_probability(rule_results),
+            })
+        except Exception:
+            pass
+    return results
+
+
+def host_from_dict(data: dict) -> HostProfile:
+    """Build HostProfile from dict (e.g. from JSON file)."""
+    return HostProfile(
+        os=data.get("os", "linux"),
+        arch=data.get("arch", "x86_64"),
+        cuda_available=data.get("cuda_available", False),
+        cuda_version=data.get("cuda_version"),
+        python_version=data.get("python_version"),
+        node_version=data.get("node_version"),
+        rust_version=data.get("rust_version"),
+        has_compiler=data.get("has_compiler", True),
+        has_metal=data.get("has_metal", False),
+        has_libgl=data.get("has_libgl", False),
+        has_ffmpeg=data.get("has_ffmpeg", False),
+        ram_gb=data.get("ram_gb"),
+    )
+
+
+def simulate(repo_path: Path, host_path: Path) -> tuple[RepoProfile, HostProfile, list]:
+    """Run rules against repo with a target host profile from file."""
+    repo = scan_repo(repo_path)
+    data = json.loads(host_path.read_text())
+    if "host" in data:
+        data = data["host"]
+    host = host_from_dict(data)
+    results = run_rules(repo, host)
+    return repo, host, results

repofail/format.py

@@ -0,0 +1,306 @@
+"""Terminal output formatting — box layout, colors, width control."""
+
+import shutil
+from typing import List
+
+import click
+
+from .rules.base import RuleResult, Severity
+
+
+def _fix_lines_for_rule(r: RuleResult) -> List[str]:
+    """Actionable fix commands for HIGH rules."""
+    try:
+        from .rules.registry import RULE_FIX_COMMANDS
+        return RULE_FIX_COMMANDS.get(r.rule_id, [])
+    except ImportError:
+        return []
+
+
+def _executive_summary(results: List[RuleResult], hard: List[RuleResult]) -> str | None:
+    """One-line summary: primary blocker or no blockers. Screenshot-ready."""
+    if not hard:
+        return "No deterministic blockers detected."
+    r = hard[0]
+    ev = r.evidence or {}
+    if r.rule_id == "node_engine_mismatch":
+        eng = ev.get("engines_node", "?")
+        host = ev.get("host_node", "?")
+        return f"Primary blocker: Node {eng} required, host is Node {host}."
+    if r.rule_id == "lock_file_missing":
+        return "Primary blocker: No lock file — npm ci will fail."
+    if r.rule_id == "torch_cuda_mismatch":
+        return "Primary blocker: Hard-coded CUDA path, host has no GPU."
+    if r.rule_id == "spec_drift":
+        vers = ev.get("versions", [])
+        return f"Primary blocker: Spec drift — {len(vers)} distinct Python targets across configs."
+    if r.rule_id == "python_version_mismatch":
+        return f"Primary blocker: Host Python outside requires-python range."
+    return f"Primary blocker: {r.message}"
+
+
+def _get_width() -> int:
+    try:
+        return min(72, shutil.get_terminal_size((72, 24)).columns)
+    except OSError:
+        return 72
+
+
+def _wrap(text: str, indent: int = 0, width: int = 72) -> List[str]:
+    """Wrap text to width, first line has indent, following lines +2."""
+    prefix = " " * indent
+    extra = "  "
+    lines = []
+    rest = text
+    first = True
+    while rest:
+        max_len = width - (indent if first else indent + len(extra))
+        if len(rest) <= max_len:
+            lines.append(prefix + rest)
+            break
+        break_at = rest.rfind(" ", 0, max_len + 1)
+        if break_at <= 0:
+            break_at = max_len
+        chunk = rest[:break_at].strip()
+        rest = rest[break_at:].strip()
+        lines.append(prefix + chunk)
+        prefix = " " * indent + extra
+        first = False
+    return lines
+
+
+def _score_color(score: int) -> str:
+    if score >= 90:
+        return "green"
+    if score >= 70:
+        return "yellow"
+    return "red"
+
+
+def _group_by_severity(results: List[RuleResult]) -> tuple[List[RuleResult], List[RuleResult], List[RuleResult]]:
+    """Split into: hard_failures (HIGH), runtime_risks (MEDIUM/LOW), observations (INFO)."""
+    hard = [r for r in results if r.severity == Severity.HIGH]
+    risks = [r for r in results if r.severity in (Severity.MEDIUM, Severity.LOW)]
+    obs = [r for r in results if r.severity == Severity.INFO]
+    return hard, risks, obs
+
+
+def _bullet_text(r: RuleResult, verbose: bool, bullet: str = "○") -> str:
+    """One-line bullet for a result. ● = hard failure, ○ = risk/observation."""
+    base = r.message.rstrip(".")
+    if verbose and r.rule_id:
+        base = f"{base} [{r.rule_id}]"
+    return f"{bullet} {base}"
+
+
+def _evidence_to_lines(r: RuleResult) -> List[str]:
+    """Convert evidence dict to human-readable lines for HARD FAILURES."""
+    ev = r.evidence or {}
+    lines: List[str] = []
+
+    if r.rule_id == "torch_cuda_mismatch":
+        for s in ev.get("repo_cuda_usage", [])[:5]:
+            lines.append(f"  {s}")
+        if not ev.get("has_is_available_guard") and ev.get("cuda_mandatory"):
+            lines.append("  No torch.cuda.is_available() guard detected")
+        if ev.get("host_cuda") is False:
+            lines.append("  Host has no CUDA device")
+        if ev.get("determinism") is not None:
+            lines.append(f"  Determinism: {ev['determinism']} (code-level execution path)")
+        if ev.get("breakage_likelihood"):
+            lines.append(f"  Breakage likelihood: {ev['breakage_likelihood']}")
+        if ev.get("likely_error"):
+            lines.append(f"  Likely error: {ev['likely_error']}")
+        return lines
+
+    if r.rule_id == "apple_silicon_wheels":
+        if ev.get("docker_platform"):
+            lines.append("  Dockerfile uses --platform=linux/amd64")
+        if ev.get("host"):
+            lines.append(f"  Host: {ev['host']}")
+        if ev.get("determinism") is not None:
+            lines.append(f"  Determinism: {ev['determinism']}")
+        if ev.get("likely_error"):
+            lines.append(f"  Likely error: {ev['likely_error']}")
+        return lines
+
+    if r.rule_id == "node_engine_mismatch":
+        eng = ev.get("engines_node")
+        host = ev.get("host_node")
+        if eng:
+            lines.append(f"  package.json requires: node {eng}")
+        if host:
+            lines.append(f"  Host: node {host}")
+        if ev.get("determinism") is not None:
+            lines.append(f"  Determinism: {ev['determinism']} (spec violation)")
+        if ev.get("likely_error"):
+            lines.append(f"  Likely error: {ev['likely_error']}")
+        return lines
+
+    if r.rule_id == "abi_wheel_mismatch":
+        lines.append(f"  Detected: {ev.get('host_os_arch', 'macOS arm64')}, Python {ev.get('host_python', '?')}")
+        for p in ev.get("problematic_packages", [])[:3]:
+            lines.append(f"  Dependency: {p}")
+        if ev.get("breakage_likelihood"):
+            lines.append(f"  Breakage likelihood: {ev['breakage_likelihood']}")
+        if ev.get("likely_error"):
+            lines.append(f"  Likely error: {ev['likely_error']}")
+        return lines
+
+    if r.rule_id == "lock_file_missing":
+        lines.append("  package.json has dependencies")
+        lines.append("  No package-lock.json or yarn.lock found")
+        fail = ev.get("expected_failure")
+        if fail:
+            lines.append(f"  {fail}")
+        return lines
+
+    if r.rule_id == "node_eol":
+        lines.append(f"  engines.node: {ev.get('engines_node', '?')}")
+        lines.append(f"  Node {ev.get('eol_major', '?')} is end-of-life")
+        return lines
+
+    if r.rule_id == "spec_drift":
+        vers = ev.get("versions", [])
+        lines.append(f"  Drift entropy: {ev.get('drift_entropy', len(vers))} distinct interpreter targets")
+        lines.append(f"  Versions found: {', '.join(vers)}")
+        for s in ev.get("sources", [])[:4]:
+            lines.append(f"  {s}")
+        lines.append("  CI and local runtime definitions diverge.")
+        if ev.get("likely_error"):
+            lines.append(f"  Likely error: {ev['likely_error']}")
+        return lines
+
+    if r.rule_id == "python_eol":
+        lines.append(f"  requires-python: {ev.get('requires_python', '?')}")
+        lines.append(f"  Python {ev.get('eol_version', '?')} is end-of-life")
+        return lines
+
+    # Generic: requires_python, host_python, etc.
+    labels = {
+        "requires_python": "requires-python",
+        "host_python": "Host Python",
+        "engines_node": "engines.node",
+        "host_node": "Host Node",
+        "problematic_packages": "Packages",
+        "port": "Port",
+    }
+    for k, v in ev.items():
+        if v is None or k in ("host_cuda", "cuda_mandatory", "has_is_available_guard", "repo_cuda_usage", "versions", "sources"):
+            continue
+        if isinstance(v, list):
+            v = ", ".join(str(x) for x in v[:5])
+        label = labels.get(k, k.replace("_", " ").title())
+        lines.append(f"  {label}: {v}")
+    return lines[:6]  # Cap generic evidence
+
+
+def _explanation_summary(results: List[RuleResult]) -> str | None:
+    """Multi-line summary: deterministic vs structural. Feels analytical."""
+    if not results:
+        return None
+    hard, risks, obs = _group_by_severity(results)
+    parts = []
+    if hard:
+        n = len(hard)
+        parts.append(f"{n} deterministic violation{'s' if n != 1 else ''} detected.")
+    if risks:
+        parts.append(f"{len(risks)} runtime risk(s) detected.")
+    if obs:
+        parts.append(f"{len(obs)} structural profile note(s).")
+    return " ".join(parts) if parts else None
+
+
+def _score_context(results: List[RuleResult], prob: int) -> str:
+    """Short context for score line, e.g. '(5 informational)'."""
+    if not results:
+        return ""
+    by_sev = {}
+    for r in results:
+        by_sev[r.severity] = by_sev.get(r.severity, 0) + 1
+    parts = []
+    for sev in [Severity.INFO, Severity.LOW, Severity.MEDIUM, Severity.HIGH]:
+        n = by_sev.get(sev, 0)
+        if n:
+            label = "informational" if sev == Severity.INFO else sev.value.lower()
+            parts.append(f"{n} {label}")
+    return " (" + ", ".join(parts) + ")" if parts else ""
+
+
+def format_human(
+    repo_name: str,
+    prob: int,
+    results: List[RuleResult],
+    verbose: bool = False,
+    confidence: str = "high",
+    low_confidence_rules: List[str] | None = None,
+) -> str:
+    """Build the human terminal output as a single string."""
+    width = _get_width()
+    lines = []
+
+    lines.append("┌" + "─" * (width - 2) + "┐")
+    lines.append(" repofail · environment risk")
+    lines.append("─" * width)
+
+    ctx = _score_context(results, prob)
+    if verbose and confidence != "high":
+        ctx = f"{ctx} (confidence: {confidence})".strip() or f"(confidence: {confidence})"
+    if verbose and low_confidence_rules:
+        ctx = f"{ctx} — low-confidence: {', '.join(low_confidence_rules[:3])}".strip()
+    fatal_note = ""
+    hard, _, _ = _group_by_severity(results)
+    if prob <= 15 and hard:
+        fatal_note = " — fatal deterministic violations present"
+    score_str = f" Score    {prob}%{fatal_note}{ctx}"
+    score_color = _score_color(prob)
+    lines.append(click.style(score_str, fg=score_color))
+    summary = _explanation_summary(results)
+    if summary:
+        lines.append(click.style(f" {summary}", dim=True))
+    exec_sum = _executive_summary(results, hard)
+    if exec_sum:
+        lines.append(click.style(f" Summary  {exec_sum}", dim=True))
+    if hard:
+        lines.append(click.style(" Execution likelihood: low unless constraints are resolved.", dim=True))
+    lines.append("─" * width)
+
+    if results:
+        hard, risks, obs = _group_by_severity(results)
+        if hard:
+            lines.append(" HARD FAILURES")
+            for r in hard:
+                bullet = _bullet_text(r, verbose, bullet="●")
+                for ln in _wrap(bullet, indent=2, width=width):
+                    lines.append(click.style(ln, fg="red"))
+                ev_lines = _evidence_to_lines(r)
+                for el in ev_lines:
+                    lines.append(click.style(el, fg="red", dim=True))
+                fix_lines = _fix_lines_for_rule(r)
+                if fix_lines:
+                    lines.append(click.style("  Suggested fix:", dim=True))
+                    for fl in fix_lines:
+                        lines.append(click.style(f"    {fl}", dim=True))
+        if risks:
+            lines.append(" RUNTIME RISKS")
+            for r in risks:
+                bullet = _bullet_text(r, verbose, bullet="○")
+                for ln in _wrap(bullet, indent=2, width=width):
+                    lines.append(click.style(ln, dim=True))
+        if obs:
+            lines.append(" STRUCTURAL PROFILE")
+            for r in obs:
+                bullet = _bullet_text(r, verbose, bullet="○")
+                for ln in _wrap(bullet, indent=2, width=width):
+                    lines.append(click.style(ln, dim=True))
+    else:
+        lines.append(" No high-confidence incompatibilities detected.")
+
+    lines.append("─" * width)
+    footer = " Run with --json for machine output  ·  --ci for exit codes"
+    if len(footer) > width:
+        footer = " --json  ·  --ci  ·  --help"
+    lines.append(click.style(footer, dim=True))
+    lines.append("└" + "─" * (width - 2) + "┘")
+
+    return "\n".join(lines)

repofail/models.py

@@ -0,0 +1,75 @@
+"""Structured profiles for repo and host."""
+
+from dataclasses import dataclass, field
+from typing import Optional
+
+
+@dataclass
+class HostProfile:
+    """Structured output from host inspection."""
+
+    os: str  # "macos", "linux", "windows"
+    arch: str  # "arm64", "x86_64"
+    cuda_available: bool = False
+    cuda_version: Optional[str] = None
+    python_version: Optional[str] = None
+    node_version: Optional[str] = None
+    rust_version: Optional[str] = None
+    has_compiler: bool = False  # gcc/clang for native builds
+    has_metal: bool = False  # macOS Metal / MLX
+    has_libgl: bool = False
+    has_ffmpeg: bool = False
+    ram_gb: Optional[float] = None
+
+
+@dataclass
+class RepoProfile:
+    """Structured output from repo scanning."""
+
+    path: str
+    name: str = ""
+
+    # Python
+    python_version: Optional[str] = None  # e.g. ">=3.10,<3.12"
+    has_requirements_txt: bool = False
+    has_pyproject: bool = False
+    has_setup_py: bool = False
+
+    # ML / GPU
+    uses_torch: bool = False
+    uses_tensorflow: bool = False
+    requires_cuda: bool = False  # explicit CUDA in code/config
+    cuda_optional: bool = True  # has CPU fallback
+    cuda_mandatory_packages: list[str] = field(default_factory=list)  # bitsandbytes, flash-attn, etc.
+    frameworks: list[str] = field(default_factory=list)  # PEFT, diffusers, etc.
+
+    # Other ecosystems
+    has_package_json: bool = False
+    node_engine_spec: str | None = None  # engines.node from package.json, e.g. ">=18"
+    node_lock_file_missing: bool = False  # package.json has deps but no package-lock.json/yarn.lock
+    node_native_modules: list[str] = field(default_factory=list)
+    has_cargo_toml: bool = False
+    rust_system_libs: list[str] = field(default_factory=list)
+
+    # System libs (detected from deps)
+    requires_libgl: bool = False
+    requires_ffmpeg: bool = False
+
+    # Infra
+    has_dockerfile: bool = False
+    dockerfile_has_cuda: bool = False  # FROM nvidia/cuda or cuda in Dockerfile
+    has_devcontainer: bool = False  # .devcontainer/ or devcontainer.json
+    docker_platform_amd64: bool = False  # FROM --platform=linux/amd64
+    required_ports: list[int] = field(default_factory=list)  # from docker-compose, .env
+    github_workflows: list[str] = field(default_factory=list)
+    os_specific: bool = False
+
+    # For rule output — where CUDA usage was found
+    cuda_files: list[str] = field(default_factory=list)
+    cuda_usages: list[dict] = field(default_factory=list)  # [{"file": str, "line": int, "kind": str}]
+
+    # Monorepo: discovered subprojects (path rel to repo, type, key fields)
+    subprojects: list[dict] = field(default_factory=list)
+
+    # Raw data for rule engine
+    raw: dict = field(default_factory=dict)

repofail/risk.py

@@ -0,0 +1,97 @@
+"""Probabilistic failure risk estimation — deterministic, explainable."""
+
+from .rules.base import RuleResult, Severity
+
+
+# Confidence levels (rule-driven, defensible):
+# HIGH  = Deterministic spec violation or hardcoded mismatch (direct read from config/code)
+# MEDIUM = Structural inference (monorepo, multiple subprojects, context-dependent)
+# LOW   = Heuristic / incomplete signals (minimal evidence, guess from layout)
+#
+# Per-rule confidence multiplies severity penalty: high=1.0, medium=0.75, low=0.5
+
+# Severity weights: reduction in success probability per finding
+# 0% reserved for: CUDA hardcoded, engine mismatch, python version violation, docker amd64 on arm64
+SEVERITY_WEIGHTS = {
+    Severity.HIGH: 45,
+    Severity.MEDIUM: 20,
+    Severity.LOW: 7,
+    Severity.INFO: 5,
+}
+
+# Per-rule weight override (calibrated: deterministic = higher, probabilistic = lower)
+RULE_WEIGHTS = {
+    "node_engine_mismatch": 50,
+    "lock_file_missing": 40,
+    "spec_drift": 25,
+}
+
+# Per-rule determinism (1.0 = will break, 0.6 = probabilistic)
+RULE_DETERMINISM = {
+    "spec_drift": 0.6,
+}
+
+# Confidence multiplier: reduces penalty when evidence is heuristic
+# high=1.0 (full penalty), medium=0.75, low=0.5
+CONFIDENCE_MULTIPLIER = {"high": 1.0, "medium": 0.75, "low": 0.5}
+
+
+def run_confidence(results: list[RuleResult]) -> tuple[str, list[str]]:
+    """
+    Per-run confidence from results.
+    High if at least one HIGH or many deterministic rules.
+    Medium if mixed heuristics. Low if minimal evidence.
+    Returns (aggregate, low_confidence_rule_ids).
+    """
+    if not results:
+        return "high", []
+    has_high = any(r.severity == Severity.HIGH for r in results)
+    high_conf_count = sum(1 for r in results if getattr(r, "confidence", "high") == "high")
+    if has_high or high_conf_count >= len(results) * 0.8:
+        agg = "high"
+    elif len(results) >= 3 or high_conf_count >= 1:
+        agg = "medium"
+    else:
+        agg = "low"
+    low = [r.rule_id for r in results if getattr(r, "confidence", "high") == "low"]
+    return agg, low
+
+
+# Cap total penalty so score doesn't flatten across 3 vs 7 HIGH
+MAX_PENALTY = 90
+
+
+def _all_high_rules_deterministic(results: list[RuleResult]) -> bool:
+    """True if every HIGH rule has determinism = 1.0. Else floor at 10%."""
+    from .rules.base import Severity
+    high_rules = [r for r in results if r.severity == Severity.HIGH]
+    if not high_rules:
+        return True
+    for r in high_rules:
+        det = RULE_DETERMINISM.get(r.rule_id, 1.0)
+        if det < 1.0:
+            return False
+    return True
+
+
+def estimate_success_probability(results: list[RuleResult]) -> int:
+    """
+    Estimate run success probability (0-100) from rule results.
+    penalty = weight × confidence × determinism.
+    If ALL HIGH rules are determinism=1.0 → allow 0% (rare, powerful).
+    If ANY HIGH has determinism<1.0 (e.g. spec_drift) → cap penalty, floor at 10%.
+    """
+    if not results:
+        return 100
+    total_penalty = 0
+    for r in results:
+        weight = RULE_WEIGHTS.get(r.rule_id) or SEVERITY_WEIGHTS.get(r.severity, 0)
+        conf = CONFIDENCE_MULTIPLIER.get(getattr(r, "confidence", "high"), 1.0)
+        det = RULE_DETERMINISM.get(r.rule_id, 1.0)
+        total_penalty += weight * conf * det
+    if not _all_high_rules_deterministic(results):
+        total_penalty = min(total_penalty, MAX_PENALTY)
+    raw = round(100 - total_penalty)
+    if not _all_high_rules_deterministic(results):
+        raw = max(10, raw)
+    return max(0, min(100, raw))

repofail/rules/__init__.py

@@ -0,0 +1,5 @@
+"""Five high-confidence incompatibility rules. No YAML. No plugins."""
+
+from .base import RuleResult, Severity
+
+__all__ = ["RuleResult", "Severity"]

repofail/rules/abi_wheel_mismatch.py

@@ -0,0 +1,80 @@
+"""Rule: Python ABI / wheel mismatch — arm64 + Python 3.12 + packages that lag wheels."""
+
+import re
+
+from ..models import HostProfile, RepoProfile
+from .base import RuleResult, Severity
+
+# Packages with unstable binary wheel availability on arm64 + Python 3.12
+# Likely: Symbol not found, undefined symbol, or build-from-source fallback
+ARM64_PY312_UNSTABLE = {
+    "bitsandbytes",
+    "torchvision",
+    "opencv-python",
+    "opencv-contrib-python",
+    "opencv",
+    "xformers",
+    "pytorch3d",
+    "triton",
+    "onnxruntime-gpu",
+}
+
+
+def _parse_python_minor(ver: str | None) -> tuple[int, int] | None:
+    """'3.12.1' -> (3, 12). None if unparseable."""
+    if not ver:
+        return None
+    m = re.search(r"(\d+)\.(\d+)", str(ver))
+    return (int(m.group(1)), int(m.group(2))) if m else None
+
+
+def _get_repo_packages(repo: RepoProfile) -> set[str]:
+    """Extract package names from repo."""
+    packages: set[str] = set()
+    raw = repo.raw or {}
+    if "requirements" in raw:
+        for p in raw["requirements"].get("packages", []):
+            packages.add(str(p).lower().replace("_", "-"))
+    if "pyproject" in raw:
+        for p in raw["pyproject"].get("packages", []):
+            packages.add(str(p).lower().replace("_", "-"))
+    return packages
+
+
+def check(repo: RepoProfile, host: HostProfile) -> RuleResult | None:
+    """
+    Trigger when: macOS arm64 + Python >= 3.12 + deps that lag arm64 3.12 wheels.
+    HIGH: deterministic pip install or import failure risk.
+    """
+    if host.os != "macos" or host.arch != "arm64":
+        return None
+    py = _parse_python_minor(host.python_version)
+    if not py or py < (3, 12):
+        return None
+
+    packages = _get_repo_packages(repo)
+    found = [p for p in packages if any(u in p for u in ARM64_PY312_UNSTABLE)]
+    if not found:
+        return None
+
+    return RuleResult(
+        rule_id="abi_wheel_mismatch",
+        severity=Severity.HIGH,
+        message="Binary wheel availability unstable (arm64 + Python 3.12).",
+        reason=(
+            f"macOS arm64, Python 3.12+, dependency: {found[0]}. "
+            "Likely to hit: Symbol not found, undefined symbol, or build-from-source fallback."
+        ),
+        host_summary=f"macOS arm64, Python {host.python_version}",
+        evidence={
+            "host_os_arch": "macOS arm64",
+            "host_python": host.python_version,
+            "problematic_packages": found[:5],
+            "expected_failure": "Symbol not found, undefined symbol, or build-from-source fallback",
+            "determinism": 1.0,
+            "breakage_likelihood": "~90%",
+            "likely_error": "pip install: No matching distribution / import: undefined symbol",
+        },
+        category="architecture_mismatch",
+        confidence="high",
+    )