codeframe-ai 0.9.0__py3-none-any.whl

codeframe/core/proof/models.py

@@ -0,0 +1,162 @@
+"""PROOF9 data models.
+
+Defines the requirement, obligation, evidence, and waiver data structures.
+Uses dataclasses following the pattern in core/gates.py.
+"""
+
+from dataclasses import dataclass, field
+from datetime import date, datetime
+from enum import Enum
+from typing import Optional
+
+
+# Shared filename for the per-workspace PROOF9 config (issue #556).
+# Lives under workspace.state_dir.
+PROOF_CONFIG_FILENAME = "proof_config.json"
+
+
+class Gate(str, Enum):
+    """The 9 proof gates."""
+
+    UNIT = "unit"
+    CONTRACT = "contract"
+    E2E = "e2e"
+    VISUAL = "visual"
+    A11Y = "a11y"
+    PERF = "perf"
+    SEC = "sec"
+    DEMO = "demo"
+    MANUAL = "manual"
+
+
+# Canonical PROOF9 gate order (matches the Gate enum declaration).
+PROOF9_GATE_ORDER: tuple[str, ...] = tuple(g.value for g in Gate)
+
+
+class GlitchType(str, Enum):
+    """Classification of the glitch that produced a requirement."""
+
+    LOGIC_BUG = "logic_bug"
+    INTEGRATION_BUG = "integration_bug"
+    UI_WIRING_BUG = "ui_wiring_bug"
+    UI_LAYOUT_BUG = "ui_layout_bug"
+    A11Y_BUG = "a11y_bug"
+    PERF_REGRESSION = "perf_regression"
+    SECURITY_ISSUE = "security_issue"
+
+
+class ReqStatus(str, Enum):
+    """Lifecycle status of a requirement."""
+
+    OPEN = "open"
+    SATISFIED = "satisfied"
+    WAIVED = "waived"
+
+
+class Source(str, Enum):
+    """Where the glitch was discovered."""
+
+    PRODUCTION = "production"
+    QA = "qa"
+    DOGFOODING = "dogfooding"
+    MONITORING = "monitoring"
+    USER_REPORT = "user_report"
+
+
+class Severity(str, Enum):
+    """Requirement severity level."""
+
+    CRITICAL = "critical"
+    HIGH = "high"
+    MEDIUM = "medium"
+    LOW = "low"
+
+
+@dataclass
+class RequirementScope:
+    """What code areas a requirement applies to."""
+
+    routes: list[str] = field(default_factory=list)
+    components: list[str] = field(default_factory=list)
+    apis: list[str] = field(default_factory=list)
+    files: list[str] = field(default_factory=list)
+    tags: list[str] = field(default_factory=list)
+
+
+@dataclass
+class Obligation:
+    """A single proof obligation attached to a requirement."""
+
+    gate: Gate
+    status: str = "pending"  # pending, satisfied, failed
+
+
+@dataclass
+class EvidenceRule:
+    """What counts as satisfying an obligation."""
+
+    test_id: str
+    must_pass: bool = True
+
+
+@dataclass
+class Waiver:
+    """Temporary exemption from an obligation."""
+
+    reason: str
+    expires: Optional[date] = None
+    manual_checklist: list[str] = field(default_factory=list)
+    approved_by: str = ""
+    waived_at: Optional[datetime] = None
+
+
+@dataclass
+class Evidence:
+    """Proof that an obligation was checked."""
+
+    req_id: str
+    gate: Gate
+    satisfied: bool
+    artifact_path: str
+    artifact_checksum: str
+    timestamp: datetime
+    run_id: str
+
+
+@dataclass
+class ProofRun:
+    """A single proof gate run record."""
+
+    run_id: str
+    workspace_id: str
+    started_at: datetime
+    completed_at: Optional[datetime]
+    triggered_by: str  # 'human' | 'auto'
+    overall_passed: bool
+    duration_ms: Optional[int]
+
+
+@dataclass
+class Requirement:
+    """A proof obligation born from a glitch.
+
+    The core data unit of PROOF9. Created by `cf proof capture`,
+    enforced by `cf proof run`, persisted in the ledger.
+    """
+
+    id: str
+    title: str
+    description: str
+    severity: Severity
+    source: Source
+    scope: RequirementScope
+    obligations: list[Obligation]
+    evidence_rules: list[EvidenceRule]
+    status: ReqStatus = ReqStatus.OPEN
+    waiver: Optional[Waiver] = None
+    created_at: Optional[datetime] = None
+    satisfied_at: Optional[datetime] = None
+    created_by: str = ""
+    source_issue: Optional[str] = None
+    related_reqs: list[str] = field(default_factory=list)
+    glitch_type: Optional[GlitchType] = None

codeframe/core/proof/obligations.py

@@ -0,0 +1,103 @@
+"""PROOF9 obligation mapping engine.
+
+Maps glitch types to the minimal set of proof gates that would have
+caught the issue. Uses keyword heuristics for classification (no LLM
+dependency for MVP).
+"""
+
+import re
+
+from codeframe.core.proof.models import (
+    EvidenceRule,
+    Gate,
+    GlitchType,
+    Obligation,
+)
+
+OBLIGATION_MAP: dict[GlitchType, list[Gate]] = {
+    GlitchType.LOGIC_BUG: [Gate.UNIT, Gate.CONTRACT],
+    GlitchType.INTEGRATION_BUG: [Gate.CONTRACT, Gate.E2E],
+    GlitchType.UI_WIRING_BUG: [Gate.E2E, Gate.DEMO],
+    GlitchType.UI_LAYOUT_BUG: [Gate.VISUAL, Gate.E2E],
+    GlitchType.A11Y_BUG: [Gate.A11Y, Gate.E2E],
+    GlitchType.PERF_REGRESSION: [Gate.PERF, Gate.E2E],
+    GlitchType.SECURITY_ISSUE: [Gate.SEC],
+}
+
+# Keywords for heuristic classification
+_KEYWORDS: dict[GlitchType, list[str]] = {
+    GlitchType.SECURITY_ISSUE: [
+        "security", "xss", "injection", "auth", "csrf", "vulnerability",
+        "exploit", "credential", "password", "token", "permission",
+    ],
+    GlitchType.PERF_REGRESSION: [
+        "slow", "performance", "latency", "timeout", "memory", "cpu",
+        "regression", "benchmark", "load", "throughput",
+    ],
+    GlitchType.A11Y_BUG: [
+        "accessibility", "a11y", "screen reader", "aria", "wcag",
+        "contrast", "keyboard", "focus", "alt text",
+    ],
+    GlitchType.UI_LAYOUT_BUG: [
+        "layout", "css", "style", "render", "display", "overlap",
+        "truncat", "responsive", "mobile", "visual",
+    ],
+    GlitchType.UI_WIRING_BUG: [
+        "click", "button", "form", "submit", "navigation", "redirect",
+        "event", "handler", "callback", "ui",
+    ],
+    GlitchType.INTEGRATION_BUG: [
+        "api", "endpoint", "integration", "contract", "schema",
+        "request", "response", "http", "grpc", "webhook",
+    ],
+    GlitchType.LOGIC_BUG: [
+        "wrong", "incorrect", "error", "bug", "crash", "exception",
+        "null", "undefined", "logic", "calculation",
+    ],
+}
+
+
+def classify_glitch(description: str) -> GlitchType:
+    """Classify a glitch description into a GlitchType using keyword heuristics.
+
+    Scans the description for keywords associated with each glitch type.
+    Returns the type with the most keyword matches, defaulting to LOGIC_BUG.
+    """
+    text = description.lower()
+    scores: dict[GlitchType, int] = {}
+
+    for glitch_type, keywords in _KEYWORDS.items():
+        score = sum(1 for kw in keywords if re.search(r"\b" + re.escape(kw) + r"\b", text))
+        if score > 0:
+            scores[glitch_type] = score
+
+    if not scores:
+        return GlitchType.LOGIC_BUG
+
+    return max(scores, key=scores.get)  # type: ignore[arg-type]
+
+
+def get_obligations(glitch_type: GlitchType) -> list[Obligation]:
+    """Return the minimal gate set for a glitch type as Obligation objects."""
+    gates = OBLIGATION_MAP.get(glitch_type, [Gate.UNIT])
+    return [Obligation(gate=g) for g in gates]
+
+
+def suggest_evidence_rules(gate: Gate, description: str) -> list[EvidenceRule]:
+    """Generate starter evidence rules for an obligation gate."""
+    # Create a sensible test ID from the description
+    slug = re.sub(r"[^a-z0-9]+", "_", description.lower().strip())[:60].strip("_")
+
+    prefix_map = {
+        Gate.UNIT: "test_unit_",
+        Gate.CONTRACT: "test_contract_",
+        Gate.E2E: "test_e2e_",
+        Gate.VISUAL: "test_visual_",
+        Gate.A11Y: "test_a11y_",
+        Gate.PERF: "test_perf_",
+        Gate.SEC: "test_sec_",
+        Gate.DEMO: "test_demo_",
+        Gate.MANUAL: "manual_check_",
+    }
+    prefix = prefix_map.get(gate, "test_")
+    return [EvidenceRule(test_id=f"{prefix}{slug}", must_pass=True)]

codeframe/core/proof/runner.py

@@ -0,0 +1,233 @@
+"""PROOF9 runner — executes obligations and collects evidence.
+
+Determines which requirements apply to the current changes,
+runs their obligations via the existing gates infrastructure,
+and attaches evidence artifacts.
+"""
+
+import json
+import logging
+import uuid
+from datetime import datetime, timezone
+from typing import Optional
+
+from codeframe.core.proof import ledger
+from codeframe.core.proof.evidence import attach_evidence
+from codeframe.core.proof.models import (
+    PROOF_CONFIG_FILENAME,
+    Gate,
+    ProofRun,
+    ReqStatus,
+)
+from codeframe.core.proof.scope import get_changed_scope, intersects
+from codeframe.core.workspace import Workspace
+
+logger = logging.getLogger(__name__)
+
+
+def _load_proof_config(workspace: Workspace) -> tuple[Optional[set[Gate]], str]:
+    """Load (enabled_gates, strictness) from .codeframe/proof_config.json.
+
+    Returns:
+        (enabled_gates, strictness). enabled_gates is None when no config file
+        exists (meaning "all gates allowed"); a set of Gate enums otherwise.
+        strictness defaults to 'strict' when missing or invalid.
+    """
+    path = workspace.state_dir / PROOF_CONFIG_FILENAME
+    if not path.exists():
+        return None, "strict"
+    try:
+        data = json.loads(path.read_text())
+    except (OSError, json.JSONDecodeError) as exc:
+        logger.warning("Invalid %s — using defaults: %s", PROOF_CONFIG_FILENAME, exc)
+        return None, "strict"
+
+    enabled: Optional[set[Gate]] = None
+    gates_raw = data.get("enabled_gates")
+    if isinstance(gates_raw, list):
+        enabled = set()
+        valid_values = {g.value for g in Gate}
+        for name in gates_raw:
+            if name in valid_values:
+                enabled.add(Gate(name))
+            else:
+                logger.warning(
+                    "Unknown gate name '%s' in %s — skipped (valid: %s)",
+                    name,
+                    PROOF_CONFIG_FILENAME,
+                    valid_values,
+                )
+
+    strictness = data.get("strictness", "strict")
+    if strictness not in ("strict", "warn"):
+        strictness = "strict"
+    return enabled, strictness
+
+
+# Map PROOF9 gates to existing core/gates.py gate names
+_GATE_TO_CORE: dict[Gate, str] = {
+    Gate.UNIT: "pytest",
+    Gate.CONTRACT: "pytest",
+    Gate.SEC: "ruff",
+}
+
+
+def _run_gate(workspace: Workspace, gate: Gate) -> tuple[bool, str]:
+    """Execute a single gate and return (passed, output).
+
+    Uses core/gates.py for gates that have direct tool support.
+    Returns (True, "") for gates without automated tooling yet.
+    """
+    core_gate_name = _GATE_TO_CORE.get(gate)
+    if not core_gate_name:
+        return False, f"Gate {gate.value} has no automated runner — cannot verify"
+
+    try:
+        from codeframe.core.gates import run as run_gates
+        result = run_gates(workspace, gates=[core_gate_name], verbose=False)
+        output_parts = [
+            f"{check.name}: {check.status.value}" for check in result.checks
+        ]
+        return result.passed, "\n".join(output_parts)
+    except Exception as exc:
+        logger.warning("Gate %s failed to run: %s", gate.value, exc)
+        return False, str(exc)
+
+
+def run_proof(
+    workspace: Workspace,
+    *,
+    full: bool = False,
+    gate_filter: Optional[Gate] = None,
+    run_id: Optional[str] = None,
+) -> dict[str, list[tuple[Gate, bool]]]:
+    """Execute proof obligations and collect evidence.
+
+    Args:
+        workspace: Target workspace
+        full: If True, run ALL obligations regardless of scope
+        gate_filter: If set, only run this specific gate
+        run_id: Unique run identifier (auto-generated if not provided)
+
+    Returns:
+        Dict mapping req_id → list of (Gate, satisfied) tuples
+    """
+    if not run_id:
+        run_id = str(uuid.uuid4())[:8]
+
+    started_at = datetime.now(timezone.utc)
+
+    # Load PROOF9 config (enabled gates + strictness)
+    enabled_gates, strictness = _load_proof_config(workspace)
+
+    # Expire any stale waivers
+    expired = ledger.check_expired_waivers(workspace)
+    if expired:
+        logger.info("Expired %d waivers", len(expired))
+
+    # Get all open requirements
+    reqs = ledger.list_requirements(workspace, status=ReqStatus.OPEN)
+    if not reqs:
+        completed_at = datetime.now(timezone.utc)
+        ledger.save_run(
+            workspace,
+            ProofRun(
+                run_id=run_id,
+                workspace_id=workspace.id,
+                started_at=started_at,
+                completed_at=completed_at,
+                triggered_by="human",
+                overall_passed=True,
+                duration_ms=int((completed_at - started_at).total_seconds() * 1000),
+            ),
+        )
+        return {}
+
+    # Warn loudly when config disables every gate — a "vacuous pass" is
+    # easy to overlook: nothing runs, overall_passed=True, no evidence.
+    if enabled_gates is not None and not enabled_gates:
+        logger.warning(
+            "Proof run %s: all 9 gates are disabled by proof_config.json — "
+            "no obligations will run and the run will pass vacuously",
+            run_id,
+        )
+
+    # Get changed scope (skip if running full)
+    changed_scope = None
+    if not full:
+        changed_scope = get_changed_scope(workspace)
+
+    results: dict[str, list[tuple[Gate, bool]]] = {}
+    artifact_dir = workspace.state_dir / "proof_artifacts"
+    artifact_dir.mkdir(exist_ok=True)
+
+    for req in reqs:
+        # Check scope intersection (unless full mode or scope detection failed)
+        # None changed_scope means "failed to detect" → run everything (fail closed)
+        if not full and changed_scope is not None:
+            if not intersects(req.scope, changed_scope):
+                continue
+
+        req_results: list[tuple[Gate, bool]] = []
+
+        for obl in req.obligations:
+            # Apply gate filter
+            if gate_filter and obl.gate != gate_filter:
+                continue
+
+            # Apply config-driven gate filter (None means "all allowed")
+            if enabled_gates is not None and obl.gate not in enabled_gates:
+                continue
+
+            # Run the gate
+            passed, output = _run_gate(workspace, obl.gate)
+
+            # Write artifact
+            artifact_path = artifact_dir / f"{req.id}_{obl.gate.value}_{run_id}.txt"
+            artifact_path.write_text(output)
+
+            # Attach evidence
+            attach_evidence(
+                workspace, req.id, obl.gate,
+                str(artifact_path), passed, run_id,
+            )
+
+            # Update obligation status
+            obl.status = "satisfied" if passed else "failed"
+            req_results.append((obl.gate, passed))
+
+        if req_results:
+            results[req.id] = req_results
+
+            # Always persist obligation status updates
+            all_satisfied = all(passed for _, passed in req_results)
+            if all_satisfied and len(req_results) == len(req.obligations):
+                req.status = ReqStatus.SATISFIED
+            ledger.save_requirement(workspace, req)
+
+    completed_at = datetime.now(timezone.utc)
+    duration_ms = int((completed_at - started_at).total_seconds() * 1000)
+    executed = [passed for gate_results in results.values() for _, passed in gate_results]
+    all_passed = all(executed) if executed else True
+    if not all_passed and strictness == "warn":
+        logger.warning(
+            "Proof run %s had gate failures but strictness='warn' — overall_passed=True",
+            run_id,
+        )
+        overall_passed = True
+    else:
+        overall_passed = all_passed
+    ledger.save_run(
+        workspace,
+        ProofRun(
+            run_id=run_id,
+            workspace_id=workspace.id,
+            started_at=started_at,
+            completed_at=completed_at,
+            triggered_by="human",
+            overall_passed=overall_passed,
+            duration_ms=duration_ms,
+        ),
+    )
+
+    return results

codeframe/core/proof/scope.py

@@ -0,0 +1,81 @@
+"""PROOF9 scope intersection engine.
+
+Determines which requirements apply to the current set of changes
+by matching requirement scopes against changed files/routes.
+"""
+
+import logging
+import re
+
+from codeframe.core.proof.models import RequirementScope
+from codeframe.core.workspace import Workspace
+
+logger = logging.getLogger(__name__)
+
+
+def build_scope_from_capture(where: str) -> RequirementScope:
+    """Parse a user-provided location string into a RequirementScope.
+
+    Heuristics:
+    - Starts with / and contains path segments → route
+    - Contains file extension → file
+    - Contains HTTP method (GET, POST, etc.) → api
+    - Otherwise → tag
+    """
+    scope = RequirementScope()
+    parts = [p.strip() for p in where.split(",")]
+
+    for part in parts:
+        if not part:
+            continue
+        if re.match(r"^(GET|POST|PUT|DELETE|PATCH)\s+", part, re.IGNORECASE):
+            scope.apis.append(part)
+        elif re.match(r"^/[\w/\-.*]+$", part):
+            scope.routes.append(part)
+        elif "." in part and "/" in part:
+            scope.files.append(part)
+        elif re.match(r"^[\w/]+\.\w+$", part):
+            scope.files.append(part)
+        else:
+            scope.tags.append(part)
+
+    return scope
+
+
+def get_changed_scope(workspace: Workspace) -> "RequirementScope | None":
+    """Detect changed files from git and build a scope.
+
+    Uses gitpython via core/git.py patterns to get modified files.
+    """
+    try:
+        from codeframe.core.git import get_status
+        status = get_status(workspace)
+        all_files = status.modified_files + status.staged_files + status.untracked_files
+        scope = RequirementScope(files=list(set(all_files)))
+        return scope
+    except Exception as exc:
+        logger.warning("Could not detect changed files: %s — failing closed (match all)", exc)
+        return None  # Caller must treat None as "match everything"
+
+
+def intersects(req_scope: RequirementScope, changed_scope: RequirementScope) -> bool:
+    """Check if a requirement scope overlaps with changed scope.
+
+    Returns True if any field has common elements. File matching
+    supports prefix matching (req file "src/auth/" matches changed
+    file "src/auth/login.py").
+    """
+    # Direct set intersection for routes, apis, components, tags
+    for field_name in ("routes", "apis", "components", "tags"):
+        req_items = set(getattr(req_scope, field_name))
+        changed_items = set(getattr(changed_scope, field_name))
+        if req_items & changed_items:
+            return True
+
+    # File matching — exact match only (no directory expansion)
+    req_files = set(req_scope.files)
+    changed_files = set(changed_scope.files)
+    if req_files & changed_files:
+        return True
+
+    return False