@trac3r/oh-my-god 2.2.11

package/runtime/api_twin.py

@@ -0,0 +1,450 @@
+"""Fixture-based API twin state and replay helpers."""
+from __future__ import annotations
+
+import json
+import re
+from pathlib import Path
+import time
+from typing import Any
+
+
+STATE_REL_PATH = Path(".omg") / "state" / "api_twin.json"
+
+DEFAULT_FRESHNESS_WINDOW_HOURS = 24
+
+_SENSITIVE_KEY_PATTERNS = re.compile(
+    r"(authorization|auth|token|api[_-]?key|password|passwd|secret|bearer|credential)",
+    re.IGNORECASE,
+)
+
+_METHOD_COST_WEIGHTS: dict[str, float] = {
+    "GET": 1.0,
+    "POST": 2.0,
+    "PUT": 1.5,
+    "PATCH": 1.5,
+    "DELETE": 1.0,
+    "HEAD": 0.5,
+    "OPTIONS": 0.5,
+}
+
+_BASE_CALL_COST = 0.002
+
+
+def ingest_contract(project_dir: str, *, name: str, source_path: str) -> dict[str, Any]:
+    state = _load_state(project_dir)
+    contract_path = Path(source_path)
+    contract = {
+        "name": name,
+        "source_path": str(contract_path),
+        "content": contract_path.read_text(encoding="utf-8"),
+        "fidelity": "schema-only",
+    }
+    state.setdefault("contracts", {})[name] = contract
+    _save_state(project_dir, state)
+    return {
+        "schema": "ApiTwinContract",
+        "name": name,
+        "fidelity": "schema-only",
+        "source_path": str(contract_path),
+    }
+
+
+def record_fixture(
+    project_dir: str,
+    *,
+    name: str,
+    endpoint: str = "default",
+    cassette_version: str = "v1",
+    request: dict[str, Any],
+    response: dict[str, Any],
+    validated: bool,
+    redactions: dict[str, str] | None = None,
+    freshness_window_hours: float = DEFAULT_FRESHNESS_WINDOW_HOURS,
+    schema: dict[str, Any] | None = None,
+    endpoint_metadata: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    state = _load_state(project_dir)
+
+    redacted_request = redact_sensitive(request)
+    redacted_response = redact_sensitive(response)
+
+    now = time.time()
+    freshness_metadata = {
+        "recorded_at": now,
+        "freshness_window_hours": freshness_window_hours,
+        "is_stale": False,
+    }
+
+    recorded_schema = schema if schema else _derive_schema(response)
+    ep_meta = endpoint_metadata or _parse_endpoint_metadata(endpoint)
+
+    fixture = {
+        "name": name,
+        "endpoint": endpoint,
+        "cassette_version": cassette_version,
+        "request": redacted_request,
+        "response": redacted_response,
+        "fidelity": "recorded-validated" if validated else "recorded",
+        "validated": validated,
+        "redactions": redactions or {},
+        "freshness_metadata": freshness_metadata,
+        "schema": recorded_schema,
+        "endpoint_metadata": ep_meta,
+        "schema_drifted": False,
+        "proof_chain": {},
+    }
+    fixtures = state.setdefault("fixtures", {}).setdefault(name, {})
+    fixtures[_fixture_key(endpoint, cassette_version)] = fixture
+    _save_state(project_dir, state)
+    return {
+        "schema": "ApiTwinFixture",
+        "name": name,
+        "endpoint": endpoint,
+        "cassette_version": cassette_version,
+        "fidelity": fixture["fidelity"],
+        "freshness_metadata": freshness_metadata,
+    }
+
+
+def serve_fixture(
+    project_dir: str,
+    *,
+    name: str,
+    endpoint: str = "default",
+    cassette_version: str = "v1",
+    latency_ms: int = 0,
+    failure_mode: str = "",
+    schema_drift: bool = False,
+) -> dict[str, Any]:
+    state = _load_state(project_dir)
+    fixture = _fixture(state, name, endpoint=endpoint, cassette_version=cassette_version)
+    response = dict(fixture.get("response", {}))
+    fidelity = str(fixture.get("fidelity", "recorded"))
+
+    freshness = fixture.get("freshness_metadata", {})
+    if freshness and _is_stale(freshness):
+        fidelity = "stale"
+
+    if latency_ms > 0:
+        time.sleep(max(latency_ms, 0) / 1000)
+    if schema_drift:
+        response["__schema_drift__"] = True
+        fidelity = "stale"
+    if failure_mode:
+        response = {"error": failure_mode}
+        fidelity = "stale"
+
+    ep_meta = fixture.get("endpoint_metadata", {})
+    cost_report = _compute_saved_cost(ep_meta)
+
+    return {
+        "schema": "ApiTwinServeResult",
+        "name": name,
+        "endpoint": endpoint,
+        "cassette_version": cassette_version,
+        "latency_ms": latency_ms,
+        "failure_mode": failure_mode,
+        "fidelity": fidelity,
+        "response": response,
+        "report": {
+            "saved_live_calls": 1,
+            "saved_cost_estimate": cost_report["saved_cost_estimate"],
+            "cost_method": "endpoint_metadata",
+            "redactions": fixture.get("redactions", {}),
+        },
+    }
+
+
+def verify_fixture(
+    project_dir: str,
+    *,
+    name: str,
+    endpoint: str = "default",
+    cassette_version: str = "v1",
+    live_response: dict[str, Any],
+) -> dict[str, Any]:
+    state = _load_state(project_dir)
+    fixture = _fixture(state, name, endpoint=endpoint, cassette_version=cassette_version)
+    matches_live = fixture.get("response", {}) == live_response
+
+    freshness = fixture.get("freshness_metadata", {})
+    is_stale = _is_stale(freshness) if freshness else False
+
+    fidelity = "recorded-validated" if (matches_live and not is_stale) else "stale"
+
+    fixture["fidelity"] = fidelity
+    fixture["validated"] = matches_live
+
+    if matches_live and not is_stale and freshness:
+        freshness["recorded_at"] = time.time()
+        freshness["is_stale"] = False
+        fixture["freshness_metadata"] = freshness
+
+    state.setdefault("fixtures", {}).setdefault(name, {})[_fixture_key(endpoint, cassette_version)] = fixture
+    _save_state(project_dir, state)
+    return {
+        "schema": "ApiTwinVerifyResult",
+        "name": name,
+        "endpoint": endpoint,
+        "cassette_version": cassette_version,
+        "fidelity": fidelity,
+        "matches_live": matches_live,
+        "live_verification_required": True,
+    }
+
+
+def verify_endpoint(
+    project_dir: str,
+    *,
+    name: str,
+    endpoint: str = "default",
+    cassette_version: str = "v1",
+    live_response: dict[str, Any],
+    schema: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    state = _load_state(project_dir)
+    fixture = _fixture(state, name, endpoint=endpoint, cassette_version=cassette_version)
+
+    recorded_response = fixture.get("response", {})
+    matches_live = recorded_response == live_response
+
+    check_schema = schema or fixture.get("schema", {})
+    schema_drifted = False
+    drift_details: list[str] = []
+
+    if check_schema and isinstance(check_schema, dict):
+        required_fields = check_schema.get("required_fields", [])
+        for field in required_fields:
+            if field not in live_response:
+                schema_drifted = True
+                drift_details.append(f"missing_field:{field}")
+
+        expected_types = check_schema.get("field_types", {})
+        for field, expected_type in expected_types.items():
+            if field in live_response:
+                actual_type = type(live_response[field]).__name__
+                if actual_type != expected_type:
+                    schema_drifted = True
+                    drift_details.append(f"type_mismatch:{field}:{expected_type}->{actual_type}")
+
+    freshness = fixture.get("freshness_metadata", {})
+    is_stale = _is_stale(freshness) if freshness else False
+
+    if schema_drifted:
+        fidelity = "schema-drifted"
+    elif is_stale:
+        fidelity = "stale"
+    elif matches_live:
+        fidelity = "recorded-validated"
+    else:
+        fidelity = "stale"
+
+    production_proven = matches_live and not schema_drifted and not is_stale
+
+    fixture["fidelity"] = fidelity
+    fixture["validated"] = matches_live and not schema_drifted
+    fixture["schema_drifted"] = schema_drifted
+
+    if matches_live and not schema_drifted and freshness:
+        freshness["recorded_at"] = time.time()
+        freshness["is_stale"] = False
+        fixture["freshness_metadata"] = freshness
+
+    state.setdefault("fixtures", {}).setdefault(name, {})[_fixture_key(endpoint, cassette_version)] = fixture
+    _save_state(project_dir, state)
+
+    ep_meta = fixture.get("endpoint_metadata", {})
+
+    return {
+        "schema": "ApiTwinEndpointVerifyResult",
+        "name": name,
+        "endpoint": endpoint,
+        "cassette_version": cassette_version,
+        "fidelity": fidelity,
+        "matches_live": matches_live,
+        "schema_drifted": schema_drifted,
+        "drift_details": drift_details,
+        "is_stale": is_stale,
+        "production_proven": production_proven,
+        "live_verification_required": True,
+        "endpoint_metadata": ep_meta,
+        "report": {
+            "endpoint": endpoint,
+            "fidelity": fidelity,
+            "production_proven": production_proven,
+            "schema_drifted": schema_drifted,
+            "drift_details": drift_details,
+            "freshness": freshness,
+            "saved_cost": _compute_saved_cost(ep_meta),
+        },
+    }
+
+
+def redact_sensitive(payload: dict[str, Any]) -> dict[str, Any]:
+    if not isinstance(payload, dict):
+        return payload
+
+    redacted: dict[str, Any] = {}
+    for key, value in payload.items():
+        if _SENSITIVE_KEY_PATTERNS.search(key):
+            redacted[key] = "[REDACTED]"
+        elif isinstance(value, dict):
+            redacted[key] = redact_sensitive(value)
+        elif isinstance(value, list):
+            redacted[key] = [redact_sensitive(item) if isinstance(item, dict) else item for item in value]
+        else:
+            redacted[key] = value
+    return redacted
+
+
+def saved_cost_report(
+    project_dir: str,
+    *,
+    name: str,
+    endpoint: str = "default",
+    cassette_version: str = "v1",
+) -> dict[str, Any]:
+    state = _load_state(project_dir)
+    fixture = _fixture(state, name, endpoint=endpoint, cassette_version=cassette_version)
+    ep_meta = fixture.get("endpoint_metadata", {})
+    cost = _compute_saved_cost(ep_meta)
+    return {
+        "schema": "ApiTwinSavedCostReport",
+        "name": name,
+        "endpoint": endpoint,
+        "cassette_version": cassette_version,
+        "endpoint_metadata": ep_meta,
+        **cost,
+    }
+
+
+def link_proof_chain(
+    project_dir: str,
+    *,
+    name: str,
+    endpoint: str = "default",
+    cassette_version: str = "v1",
+    trace_id: str,
+    eval_id: str = "",
+) -> dict[str, Any]:
+    state = _load_state(project_dir)
+    fixture = _fixture(state, name, endpoint=endpoint, cassette_version=cassette_version)
+    proof_chain = {
+        "trace_id": trace_id,
+        "eval_id": eval_id,
+        "linked_at": time.time(),
+    }
+    fixture["proof_chain"] = proof_chain
+    state.setdefault("fixtures", {}).setdefault(name, {})[_fixture_key(endpoint, cassette_version)] = fixture
+    _save_state(project_dir, state)
+    return {
+        "schema": "ApiTwinProofChainLink",
+        "name": name,
+        "endpoint": endpoint,
+        "cassette_version": cassette_version,
+        "proof_chain": proof_chain,
+    }
+
+
+def _state_path(project_dir: str) -> Path:
+    return Path(project_dir) / STATE_REL_PATH
+
+
+def _load_state(project_dir: str) -> dict[str, Any]:
+    path = _state_path(project_dir)
+    if not path.exists():
+        return {"schema": "ApiTwinState", "version": "2.0.8", "contracts": {}, "fixtures": {}}
+    try:
+        payload = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return {"schema": "ApiTwinState", "version": "2.0.8", "contracts": {}, "fixtures": {}}
+    if not isinstance(payload, dict):
+        return {"schema": "ApiTwinState", "version": "2.0.8", "contracts": {}, "fixtures": {}}
+    payload.setdefault("schema", "ApiTwinState")
+    payload.setdefault("version", "2.0.8")
+    payload.setdefault("contracts", {})
+    payload.setdefault("fixtures", {})
+    return payload
+
+
+def _save_state(project_dir: str, payload: dict[str, Any]) -> None:
+    path = _state_path(project_dir)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(payload, indent=2, ensure_ascii=True) + "\n", encoding="utf-8")
+
+
+def _fixture_key(endpoint: str, cassette_version: str) -> str:
+    return f"{endpoint}::{cassette_version}"
+
+
+def _fixture(
+    state: dict[str, Any],
+    name: str,
+    *,
+    endpoint: str = "default",
+    cassette_version: str = "v1",
+) -> dict[str, Any]:
+    fixtures = state.get("fixtures", {})
+    if not isinstance(fixtures, dict) or name not in fixtures:
+        raise ValueError(f"Unknown API twin fixture: {name}")
+    fixture_group = fixtures[name]
+    if not isinstance(fixture_group, dict):
+        raise ValueError(f"Invalid API twin fixture: {name}")
+    fixture = fixture_group.get(_fixture_key(endpoint, cassette_version))
+    if not isinstance(fixture, dict):
+        raise ValueError(f"Unknown API twin cassette: {name} {endpoint} {cassette_version}")
+    return fixture
+
+
+def _is_stale(freshness: dict[str, Any]) -> bool:
+    recorded_at = freshness.get("recorded_at", 0)
+    window_hours = freshness.get("freshness_window_hours", DEFAULT_FRESHNESS_WINDOW_HOURS)
+    if not recorded_at:
+        return True
+    age_hours = (time.time() - recorded_at) / 3600
+    return age_hours > window_hours
+
+
+def _derive_schema(response: dict[str, Any]) -> dict[str, Any]:
+    if not isinstance(response, dict):
+        return {}
+    required_fields = list(response.keys())
+    field_types = {k: type(v).__name__ for k, v in response.items()}
+    return {
+        "required_fields": required_fields,
+        "field_types": field_types,
+    }
+
+
+def _parse_endpoint_metadata(endpoint: str) -> dict[str, Any]:
+    parts = endpoint.strip().split(None, 1)
+    if len(parts) == 2:
+        method, path = parts
+    elif len(parts) == 1:
+        method, path = "GET", parts[0]
+    else:
+        method, path = "GET", endpoint
+
+    method = method.upper()
+    path_segments = [s for s in path.split("/") if s]
+    avg_tokens = max(50, len(path_segments) * 100)
+
+    return {
+        "method": method,
+        "path": path,
+        "avg_tokens": avg_tokens,
+    }
+
+
+def _compute_saved_cost(ep_meta: dict[str, Any]) -> dict[str, Any]:
+    method = ep_meta.get("method", "GET").upper()
+    avg_tokens = ep_meta.get("avg_tokens", 50)
+    method_weight = _METHOD_COST_WEIGHTS.get(method, 1.0)
+    token_cost = avg_tokens * 0.00001
+    saved_cost_estimate = round(_BASE_CALL_COST * method_weight + token_cost, 6)
+    return {
+        "saved_cost_estimate": saved_cost_estimate,
+        "cost_method": "endpoint_metadata",
+        "method_weight": method_weight,
+        "avg_tokens": avg_tokens,
+    }

package/runtime/architecture_signal.py

@@ -0,0 +1,226 @@
+"""Bounded architecture signal artifacts for context-engine consumers.
+
+Produces a compact summary of dependency graph and LSP diagnostics.
+Raw data stays in artifact files; only bounded summaries plus artifact
+pointers enter later context-engine consumers.
+
+Crash-isolated: ``build_architecture_signal`` never raises.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import time
+from pathlib import Path
+from typing import Any
+
+_SUMMARY_MAX_CHARS = 500
+_STATE_REL = Path(".omg") / "state" / "architecture_signal"
+
+
+# ---------------------------------------------------------------------------
+# Feature flag helper
+# ---------------------------------------------------------------------------
+
+def _get_feature_flag(name: str, default: bool = False) -> bool:
+    """Check feature flag via env var first, then hooks._common."""
+    env_key = f"OMG_{name.upper()}_ENABLED"
+    env_val = os.environ.get(env_key, "").lower()
+    if env_val in ("1", "true", "yes"):
+        return True
+    if env_val in ("0", "false", "no"):
+        return False
+    try:
+        from hooks._common import get_feature_flag as _gff
+        return _gff(name, default)
+    except Exception:
+        return default
+
+
+# ---------------------------------------------------------------------------
+# Graph summary (reads graph_builder output, never modifies it)
+# ---------------------------------------------------------------------------
+
+def _build_graph_summary(project_dir: str) -> tuple[str | None, dict[str, Any], float]:
+    """Build dependency graph summary when CODEBASE_VIZ is enabled.
+
+    Returns ``(artifact_path_or_none, metrics_dict, elapsed_ms)``.
+    """
+    t0 = time.monotonic()
+
+    if not _get_feature_flag("CODEBASE_VIZ", default=False):
+        return None, {}, (time.monotonic() - t0) * 1000
+
+    try:
+        from plugins.viz.graph_builder import build_project_graph
+        result = build_project_graph(project_dir)
+    except Exception:
+        return None, {}, (time.monotonic() - t0) * 1000
+
+    raw_metrics = result.get("metrics", {})
+    metrics: dict[str, Any] = raw_metrics if isinstance(raw_metrics, dict) else {}
+
+    # Persist raw graph as a side artifact (never injected into prompts)
+    artifact_path = Path(project_dir) / _STATE_REL / "dependency-graph-raw.json"
+    try:
+        artifact_path.parent.mkdir(parents=True, exist_ok=True)
+        tmp = artifact_path.with_suffix(".json.tmp")
+        tmp.write_text(json.dumps(result, indent=2, ensure_ascii=True), encoding="utf-8")
+        os.rename(tmp, artifact_path)
+    except Exception:
+        pass  # crash isolation
+
+    elapsed = (time.monotonic() - t0) * 1000
+    return str(artifact_path), metrics, elapsed
+
+
+# ---------------------------------------------------------------------------
+# LSP diagnostics summary (file-path scan, no live LSP required)
+# ---------------------------------------------------------------------------
+
+def _build_lsp_summary(project_dir: str) -> tuple[str | None, dict[str, int], float]:
+    """Collect LSP diagnostic counts from evidence artifact if available.
+
+    Returns ``(artifact_path_or_none, severity_counts, elapsed_ms)``.
+    """
+    t0 = time.monotonic()
+
+    lsp_path = Path(project_dir) / ".omg" / "evidence" / "lsp-diagnostics.json"
+    if not lsp_path.exists():
+        return None, {}, (time.monotonic() - t0) * 1000
+
+    try:
+        data = json.loads(lsp_path.read_text(encoding="utf-8"))
+    except Exception:
+        return None, {}, (time.monotonic() - t0) * 1000
+
+    # Normalize: accept both list-of-diagnostics and {diagnostics: [...]}
+    diagnostics: list[Any] = data if isinstance(data, list) else (
+        data.get("diagnostics", []) if isinstance(data, dict) else []
+    )
+
+    counts: dict[str, int] = {"error": 0, "warning": 0, "info": 0, "hint": 0, "total": 0}
+    if isinstance(diagnostics, list):
+        for d in diagnostics:
+            if isinstance(d, dict):
+                sev = str(d.get("severity", "info")).lower()
+                if sev in counts:
+                    counts[sev] += 1
+                counts["total"] += 1
+
+    elapsed = (time.monotonic() - t0) * 1000
+    return str(lsp_path), counts, elapsed
+
+
+# ---------------------------------------------------------------------------
+# Summary formatter
+# ---------------------------------------------------------------------------
+
+def _format_summary(
+    graph_metrics: dict[str, Any],
+    lsp_counts: dict[str, int],
+    fallback: bool,
+) -> str:
+    """Format a bounded summary string (max ``_SUMMARY_MAX_CHARS`` chars)."""
+    if fallback:
+        return "no architecture signals available"
+
+    parts: list[str] = []
+
+    if graph_metrics:
+        mc = graph_metrics.get("module_count", 0)
+        ec = graph_metrics.get("edge_count", 0)
+        md = graph_metrics.get("max_depth", 0)
+        cs = graph_metrics.get("coupling_score", 0.0)
+        cycles = graph_metrics.get("circular_deps", [])
+        parts.append(f"graph: {mc} modules, {ec} edges, depth={md}, coupling={cs:.2f}")
+        if cycles:
+            parts.append(f"  cycles: {len(cycles)}")
+
+    if lsp_counts and lsp_counts.get("total", 0) > 0:
+        parts.append(
+            f"lsp: {lsp_counts.get('error', 0)} errors, "
+            f"{lsp_counts.get('warning', 0)} warnings, "
+            f"{lsp_counts.get('total', 0)} total"
+        )
+
+    if not parts:
+        return "no architecture signals available"
+
+    return "\n".join(parts)[:_SUMMARY_MAX_CHARS]
+
+
+# ---------------------------------------------------------------------------
+# State persistence (follows runtime_contracts.write_run_state pattern)
+# ---------------------------------------------------------------------------
+
+def _write_state(project_dir: str, payload: dict[str, Any]) -> None:
+    """Write state atomically to ``latest.json`` under architecture_signal."""
+    state_dir = Path(project_dir) / _STATE_REL
+    try:
+        state_dir.mkdir(parents=True, exist_ok=True)
+        latest = state_dir / "latest.json"
+        tmp = latest.with_name("latest.json.tmp")
+        tmp.write_text(json.dumps(payload, indent=2, ensure_ascii=True), encoding="utf-8")
+        os.rename(tmp, latest)
+    except Exception:
+        pass  # crash isolation
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+_FALLBACK_RESULT: dict[str, Any] = {
+    "summary": "no architecture signals available",
+    "artifacts": {
+        "dependency_graph": None,
+        "lsp_diagnostics": None,
+    },
+    "perf": {
+        "graph_ms": 0.0,
+        "lsp_ms": 0.0,
+    },
+    "fallback": True,
+}
+
+
+def build_architecture_signal(project_dir: str) -> dict[str, Any]:
+    """Build bounded architecture signal for context-engine consumers.
+
+    Always returns a dict with keys:
+      - ``summary``: bounded text (<=500 chars)
+      - ``artifacts``: ``{dependency_graph: path|None, lsp_diagnostics: path|None}``
+      - ``perf``: ``{graph_ms: float, lsp_ms: float}``
+      - ``fallback``: ``bool`` — True when no signals were available
+
+    Degrades gracefully when graph plugin or LSP evidence is unavailable.
+    Never raises.
+    """
+    try:
+        graph_path, graph_metrics, graph_ms = _build_graph_summary(project_dir)
+        lsp_path, lsp_counts, lsp_ms = _build_lsp_summary(project_dir)
+
+        fallback = graph_path is None and lsp_path is None
+        summary = _format_summary(graph_metrics, lsp_counts, fallback)
+
+        result: dict[str, Any] = {
+            "summary": summary,
+            "artifacts": {
+                "dependency_graph": graph_path,
+                "lsp_diagnostics": lsp_path,
+            },
+            "perf": {
+                "graph_ms": round(graph_ms, 3),
+                "lsp_ms": round(lsp_ms, 3),
+            },
+            "fallback": fallback,
+        }
+
+        _write_state(project_dir, result)
+        return result
+
+    except Exception:
+        # Crash isolation: never raise to caller
+        return dict(_FALLBACK_RESULT)