ref-agents 1.0.0__py3-none-any.whl

ref_agents/tools/validators/impact_architect.py

@@ -0,0 +1,181 @@
+"""Impact Architect output validator — validate_impact_reconciliation.
+
+Reconciles the CHANGE doc's "Direct Files Touched" with actual git diff and
+checks risk-level → gate-decision consistency.
+
+See SPEC-STORY-028.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+import structlog
+
+from ref_agents.core.validation_models import (
+    Gap,
+    ValidationReport,
+    Verdict,
+)
+from ref_agents.session import SessionManager
+from ref_agents.tools.validators import register_validator
+from ref_agents.utils.git_utils import get_changed_files, is_git_repo
+
+logger = structlog.get_logger(__name__)
+
+RISK_LEVELS = ("LOW", "MEDIUM", "HIGH", "CRITICAL")
+RISK_TO_GATE = {
+    "LOW": "APPROVED",
+    "MEDIUM": "APPROVED",
+    "HIGH": "REQUIRES_USER_APPROVAL",
+    "CRITICAL": "L3_HALT",
+}
+SCAN_PREFIXES = ("src/", "tests/")
+EXCLUDED_PREFIXES = ("codemap/", "docs/", "ref-reports/", ".ref_cache/", "ref_reports/")
+
+
+def _resolve_under_root(candidate: Path) -> Path | None:
+    root = SessionManager.get().project_root
+    candidate = candidate.resolve()
+    if root is not None:
+        try:
+            candidate.relative_to(root.resolve())
+        except ValueError:
+            return None
+    return candidate if candidate.exists() else None
+
+
+def _resolve_change(artifact_id: str, artifact_path: str) -> Path | None:
+    if artifact_path:
+        return _resolve_under_root(Path(artifact_path))
+    root = SessionManager.get().project_root
+    if artifact_id and root is not None:
+        return _resolve_under_root(
+            root / "docs" / "analysis" / f"CHANGE-{artifact_id}.md"
+        )
+    return None
+
+
+def _extract_listed_files(text: str) -> list[str]:
+    """Extract file paths listed under '## Direct Files Touched'."""
+    match = re.search(
+        r"##\s+Direct Files Touched\s*\n+(.*?)(?=\n##\s|\Z)",
+        text,
+        flags=re.DOTALL,
+    )
+    if not match:
+        return []
+    block = match.group(1)
+    files: list[str] = []
+    for line in block.splitlines():
+        stripped = line.strip().lstrip("-*0123456789. ")
+        # Strip backticks / inline bold markers
+        stripped = stripped.strip("`*_")
+        if not stripped:
+            continue
+        if "/" in stripped or stripped.endswith(".py") or stripped.endswith(".md"):
+            # Pick first whitespace-delimited token (path)
+            token = stripped.split()[0].rstrip(":,;")
+            files.append(token)
+    return files
+
+
+def _extract_risk(text: str) -> str | None:
+    block = re.search(
+        r"##\s+(?:Regression\s+)?Risk(?:\s+Assessment|\s+Score)?\s*\n+(.*?)(?=\n##\s|\Z)",
+        text,
+        flags=re.DOTALL,
+    )
+    body = block.group(1).upper() if block else text.upper()
+    for level in ("CRITICAL", "HIGH", "MEDIUM", "LOW"):
+        if re.search(rf"\bRISK[\s:_-]*\*{{0,2}}{level}\b", body) or re.search(
+            rf"\b{level}\b", body
+        ):
+            return level
+    return None
+
+
+def _extract_gate(text: str) -> str | None:
+    match = re.search(
+        r"gate\s+decision[:*\s_]*\*{0,2}(APPROVED|REQUIRES_USER_APPROVAL|L3_HALT)",
+        text,
+        flags=re.IGNORECASE,
+    )
+    if match:
+        return match.group(1).upper()
+    return None
+
+
+@register_validator("impact_architect")
+def validate_impact_reconciliation(
+    artifact_id: str = "", artifact_path: str = ""
+) -> ValidationReport:
+    log = logger.bind(role="impact_architect", artifact_id=artifact_id)
+
+    change_path = _resolve_change(artifact_id, artifact_path)
+    if change_path is None:
+        return ValidationReport(
+            verdict=Verdict.NEEDS_USER,
+            gaps=[
+                Gap(code="change_doc_unresolved", detail=artifact_id or artifact_path)
+            ],
+        )
+
+    text = change_path.read_text(encoding="utf-8")
+    gaps: list[Gap] = []
+
+    # FR-2: Listed files
+    listed = _extract_listed_files(text)
+    if not listed:
+        gaps.append(
+            Gap(
+                code="impact_files_empty",
+                detail="'Direct Files Touched' empty/missing.",
+            )
+        )
+
+    # FR-3: Reconciliation
+    root = SessionManager.get().project_root
+    if root is not None and is_git_repo(root):
+        changed = [str(p).replace("\\", "/") for p in get_changed_files(directory=root)]
+        for c in changed:
+            if any(c.startswith(p) for p in EXCLUDED_PREFIXES):
+                continue
+            if not any(c.startswith(p) for p in SCAN_PREFIXES):
+                continue
+            if not any(c in entry or entry in c for entry in listed):
+                gaps.append(
+                    Gap(
+                        code=f"impact_underpredicted:{c}",
+                        detail=f"{c} changed but not in 'Direct Files Touched'.",
+                        location=c,
+                    )
+                )
+
+    # FR-4 + FR-5: Risk + gate consistency
+    risk = _extract_risk(text)
+    gate = _extract_gate(text)
+    if risk is None:
+        gaps.append(
+            Gap(code="risk_missing", detail="No risk level found in CHANGE doc.")
+        )
+    elif gate is not None:
+        expected = RISK_TO_GATE[risk]
+        if gate != expected:
+            gaps.append(
+                Gap(
+                    code="gate_inconsistent",
+                    detail=f"Risk={risk} expects gate={expected}; doc has gate={gate}.",
+                )
+            )
+
+    verdict = Verdict.PASS if not gaps else Verdict.FAIL_AUTO
+    log.info(
+        "impact_validate_complete",
+        verdict=verdict.value,
+        gap_count=len(gaps),
+        risk=risk,
+        gate=gate,
+    )
+    return ValidationReport(verdict=verdict, gaps=gaps)

ref_agents/tools/validators/migration_planner.py

@@ -0,0 +1,166 @@
+"""Migration Planner output validator — validate_migration_plan.
+
+Checks strategy enum, batch DAG validity, feature-flag naming, and
+rollback completeness.
+
+See SPEC-STORY-036.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+import structlog
+
+from ref_agents.core.validation_models import (
+    Gap,
+    ValidationReport,
+    Verdict,
+)
+from ref_agents.core.validation_primitives import dag_validator
+from ref_agents.errors import CycleDetectedError
+from ref_agents.session import SessionManager
+from ref_agents.tools.validators import register_validator
+
+logger = structlog.get_logger(__name__)
+
+STRATEGIES = ("Strangler Fig", "Parallel Run", "Big Bang")
+FLAG_REGEX = re.compile(r"^ff-[a-z0-9][a-z0-9\-]*-v\d+$")
+
+
+def _resolve_under_root(candidate: Path) -> Path | None:
+    root = SessionManager.get().project_root
+    candidate = candidate.resolve()
+    if root is not None:
+        try:
+            candidate.relative_to(root.resolve())
+        except ValueError:
+            return None
+    return candidate if candidate.exists() else None
+
+
+def _resolve_plan(artifact_path: str) -> Path | None:
+    if artifact_path:
+        return _resolve_under_root(Path(artifact_path))
+    root = SessionManager.get().project_root
+    if root is not None:
+        return _resolve_under_root(root / "docs" / "MIGRATION_PLAN.md")
+    return None
+
+
+def _detect_strategy(text: str) -> str | None:
+    for s in STRATEGIES:
+        if re.search(rf"\b{re.escape(s)}\b", text, flags=re.IGNORECASE):
+            return s
+    return None
+
+
+def _parse_batches(text: str) -> tuple[list[str], list[tuple[str, str]]]:
+    """Return (batch_ids, prereq_edges) from a markdown table.
+
+    Expects table rows with first cell = batch id (Batch 0, B-1, etc.) and a
+    cell containing prerequisite batch ids comma-separated.
+    """
+    nodes: list[str] = []
+    edges: list[tuple[str, str]] = []
+    block = re.search(
+        r"##\s+Batch(?:\s+Schedule)?\s*\n+(.*?)(?=\n##\s|\Z)", text, flags=re.DOTALL
+    )
+    if not block:
+        return nodes, edges
+
+    header_seen = False
+    for line in block.group(1).splitlines():
+        if not line.startswith("|"):
+            continue
+        cells = [c.strip() for c in line.strip("|").split("|")]
+        if re.match(r"-+", cells[0]):
+            continue
+        if not header_seen:
+            header_seen = True
+            continue
+        batch_id = cells[0]
+        if not batch_id:
+            continue
+        nodes.append(batch_id)
+        if len(cells) >= 4:  # noqa: PLR2004  # TECH_DEBT: extract to named constant — G25
+            prereq_cell = cells[-1] or cells[3]
+            for prereq in re.split(r"[,;]", prereq_cell):
+                prereq = prereq.strip()
+                if prereq and prereq.lower() not in ("none", "n/a", "-"):
+                    edges.append((prereq, batch_id))
+    return nodes, edges
+
+
+def _extract_flag_names(text: str) -> list[str]:
+    return re.findall(r"\bff-[\w][\w\-]*\b", text, flags=re.IGNORECASE)
+
+
+def _has_rollback_protocol(text: str) -> bool:
+    return bool(re.search(r"##\s+Rollback Protocol", text, flags=re.IGNORECASE))
+
+
+@register_validator("migration_planner")
+def validate_migration_plan(
+    artifact_id: str = "", artifact_path: str = ""
+) -> ValidationReport:
+    log = logger.bind(role="migration_planner", artifact_id=artifact_id)
+
+    path = _resolve_plan(artifact_path)
+    if path is None:
+        return ValidationReport(
+            verdict=Verdict.NEEDS_USER,
+            gaps=[
+                Gap(code="migration_plan_unresolved", detail=artifact_path or "default")
+            ],
+        )
+
+    text = path.read_text(encoding="utf-8")
+    gaps: list[Gap] = []
+
+    if _detect_strategy(text) is None:
+        gaps.append(
+            Gap(
+                code="strategy_invalid",
+                detail=f"No strategy from {STRATEGIES} found.",
+            )
+        )
+
+    nodes, edges = _parse_batches(text)
+    if not nodes:
+        gaps.append(Gap(code="batches_empty", detail="No batches parsed."))
+    else:
+        try:
+            dag_validator(nodes, edges)
+        except CycleDetectedError as exc:
+            gaps.append(
+                Gap(
+                    code="batch_cycle",
+                    detail=f"Cycle in batch prerequisites: {' -> '.join(exc.path)}",
+                )
+            )
+
+    flags = _extract_flag_names(text)
+    for flag in flags:
+        if not FLAG_REGEX.match(flag):
+            gaps.append(
+                Gap(
+                    code=f"flag_name_invalid:{flag}",
+                    detail=f"Flag '{flag}' does not match ff-<kebab>-v<n>.",
+                )
+            )
+
+    if not _has_rollback_protocol(text):
+        gaps.append(
+            Gap(code="rollback_missing", detail="No 'Rollback Protocol' section.")
+        )
+
+    verdict = Verdict.PASS if not gaps else Verdict.FAIL_AUTO
+    log.info(
+        "migration_planner_validate_complete",
+        verdict=verdict.value,
+        gap_count=len(gaps),
+        batches=len(nodes),
+    )
+    return ValidationReport(verdict=verdict, gaps=gaps)

ref_agents/tools/validators/parity_tester.py

@@ -0,0 +1,155 @@
+"""Parity Tester output validator — validate_parity_artifacts.
+
+Checks golden master symbol coverage, ≥2 input categories per symbol, and
+verdict ↔ divergence consistency.
+
+See SPEC-STORY-037.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+import structlog
+
+from ref_agents.core.validation_models import (
+    Gap,
+    ValidationReport,
+    Verdict,
+)
+from ref_agents.session import SessionManager
+from ref_agents.tools.validators import register_validator
+
+logger = structlog.get_logger(__name__)
+
+INPUT_CATEGORIES = ("Happy Path", "Boundary", "Error Path", "Side Effects")
+
+
+def _resolve_under_root(candidate: Path) -> Path | None:
+    root = SessionManager.get().project_root
+    candidate = candidate.resolve()
+    if root is not None:
+        try:
+            candidate.relative_to(root.resolve())
+        except ValueError:
+            return None
+    return candidate if candidate.exists() else None
+
+
+def _resolve_gate(batch_id: str, artifact_path: str) -> Path | None:
+    if artifact_path:
+        return _resolve_under_root(Path(artifact_path))
+    root = SessionManager.get().project_root
+    if batch_id and root is not None:
+        return _resolve_under_root(
+            root / "docs" / "parity" / f"PARITY-{batch_id}-gate.md"
+        )
+    return None
+
+
+def _resolve_golden(batch_id: str) -> Path | None:
+    root = SessionManager.get().project_root
+    if batch_id and root is not None:
+        return _resolve_under_root(
+            root / "docs" / "parity" / f"PARITY-{batch_id}-golden.md"
+        )
+    return None
+
+
+def _extract_verdict(text: str) -> str | None:
+    match = re.search(
+        r"(?:Gate\s+)?Verdict[:*\s_]*\*{0,2}(PASS|FAIL)\*{0,2}",
+        text,
+        flags=re.IGNORECASE,
+    )
+    if match:
+        return match.group(1).upper()
+    return None
+
+
+def _golden_symbols_and_categories(text: str) -> dict[str, set[str]]:
+    """Parse golden contracts table: first col symbol, subsequent col category."""
+    result: dict[str, set[str]] = {}
+    header_seen = False
+    headers: list[str] = []
+    for line in text.splitlines():
+        if not line.startswith("|"):
+            continue
+        cells = [c.strip() for c in line.strip("|").split("|")]
+        if re.match(r"-+", cells[0]):
+            continue
+        if not header_seen:
+            headers = [h.lower() for h in cells]
+            header_seen = True
+            continue
+        symbol = cells[0]
+        if not symbol:
+            continue
+        cats = result.setdefault(symbol, set())
+        for idx, value in enumerate(cells[1:], start=1):
+            header = headers[idx] if idx < len(headers) else ""
+            for cat in INPUT_CATEGORIES:
+                if cat.lower() in header or cat.lower() in value.lower():
+                    cats.add(cat)
+    return result
+
+
+def _has_unacceptable_divergence(text: str) -> bool:
+    return bool(re.search(r"unacceptable\s+divergence", text, flags=re.IGNORECASE))
+
+
+@register_validator("parity_tester")
+def validate_parity_artifacts(
+    artifact_id: str = "", artifact_path: str = ""
+) -> ValidationReport:
+    """Validate parity gate report; artifact_id should be the batch_id."""
+    log = logger.bind(role="parity_tester", artifact_id=artifact_id)
+
+    gate_path = _resolve_gate(artifact_id, artifact_path)
+    if gate_path is None:
+        return ValidationReport(
+            verdict=Verdict.NEEDS_USER,
+            gaps=[
+                Gap(code="parity_gate_unresolved", detail=artifact_id or artifact_path)
+            ],
+        )
+
+    gate_text = gate_path.read_text(encoding="utf-8")
+    gaps: list[Gap] = []
+
+    verdict = _extract_verdict(gate_text)
+    if verdict is None:
+        gaps.append(Gap(code="verdict_missing", detail="No PASS/FAIL verdict."))
+    elif verdict == "PASS" and _has_unacceptable_divergence(gate_text):
+        gaps.append(
+            Gap(
+                code="verdict_inconsistent",
+                detail="Verdict PASS forbidden with unacceptable divergence present.",
+            )
+        )
+
+    golden_path = _resolve_golden(artifact_id)
+    if golden_path is None:
+        gaps.append(Gap(code="golden_missing", detail="Golden master file missing."))
+    else:
+        golden = _golden_symbols_and_categories(golden_path.read_text(encoding="utf-8"))
+        if not golden:
+            gaps.append(Gap(code="golden_empty", detail="No symbols in golden master."))
+        for symbol, cats in golden.items():
+            if len(cats) < 2:  # noqa: PLR2004  # TECH_DEBT: extract to named constant — G25
+                gaps.append(
+                    Gap(
+                        code=f"symbol_input_cats_lt_2:{symbol}",
+                        detail=f"Symbol '{symbol}' has {len(cats)} input categories; need ≥2.",
+                    )
+                )
+
+    out_verdict = Verdict.PASS if not gaps else Verdict.FAIL_AUTO
+    log.info(
+        "parity_validate_complete",
+        verdict=out_verdict.value,
+        gap_count=len(gaps),
+        gate_verdict=verdict,
+    )
+    return ValidationReport(verdict=out_verdict, gaps=gaps)

ref_agents/tools/validators/platform_engineer.py

@@ -0,0 +1,134 @@
+"""Platform Engineer output validator — health report freshness.
+
+Validates ref-reports/health_report.json has a recent `generated_at`
+timestamp and required summary structure. HMAC signing is intentionally
+deferred to backend infrastructure; this validator catches replay /
+staleness via timestamp.
+
+See SPEC-STORY-033.
+"""
+
+from __future__ import annotations
+
+import json
+from datetime import datetime, timezone
+from pathlib import Path
+
+import structlog
+
+from ref_agents.core.validation_models import (
+    Gap,
+    ValidationReport,
+    Verdict,
+)
+from ref_agents.session import SessionManager
+from ref_agents.tools.validators import register_validator
+
+logger = structlog.get_logger(__name__)
+
+DEFAULT_MAX_AGE_SECONDS = 2 * 60 * 60  # 2 hours
+
+
+def _resolve_under_root(candidate: Path) -> Path | None:
+    root = SessionManager.get().project_root
+    candidate = candidate.resolve()
+    if root is not None:
+        try:
+            candidate.relative_to(root.resolve())
+        except ValueError:
+            return None
+    return candidate if candidate.exists() else None
+
+
+def _resolve_report(artifact_path: str) -> Path | None:
+    if artifact_path:
+        return _resolve_under_root(Path(artifact_path))
+    root = SessionManager.get().project_root
+    if root is not None:
+        return _resolve_under_root(root / "ref-reports" / "health_report.json")
+    return None
+
+
+def _parse_iso8601(value: str) -> datetime | None:
+    try:
+        # Accept both naive and Z-suffix
+        normalized = value.replace("Z", "+00:00")
+        return datetime.fromisoformat(normalized)
+    except ValueError:
+        return None
+
+
+@register_validator("platform_engineer")
+def validate_health_freshness(
+    artifact_id: str = "", artifact_path: str = ""
+) -> ValidationReport:
+    """Validate ref-reports/health_report.json freshness + schema."""
+    log = logger.bind(role="platform_engineer", artifact_id=artifact_id)
+
+    path = _resolve_report(artifact_path)
+    if path is None:
+        return ValidationReport(
+            verdict=Verdict.NEEDS_USER,
+            gaps=[
+                Gap(code="health_report_unresolved", detail=artifact_path or "default")
+            ],
+        )
+
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as exc:
+        return ValidationReport(
+            verdict=Verdict.FAIL_AUTO,
+            gaps=[Gap(code="health_report_unreadable", detail=str(exc))],
+        )
+
+    gaps: list[Gap] = []
+
+    generated_at = data.get("generated_at") if isinstance(data, dict) else None
+    if not generated_at:
+        gaps.append(
+            Gap(
+                code="generated_at_missing",
+                detail="health_report.json missing 'generated_at' timestamp.",
+            )
+        )
+    else:
+        ts = _parse_iso8601(str(generated_at))
+        if ts is None:
+            gaps.append(
+                Gap(
+                    code="generated_at_unparseable",
+                    detail=f"Could not parse '{generated_at}' as ISO8601.",
+                )
+            )
+        else:
+            now = datetime.now(timezone.utc)
+            if ts.tzinfo is None:
+                ts = ts.replace(tzinfo=timezone.utc)
+            age = (now - ts).total_seconds()
+            if age > DEFAULT_MAX_AGE_SECONDS:
+                gaps.append(
+                    Gap(
+                        code="report_stale",
+                        detail=(
+                            f"health_report.json is {int(age)}s old "
+                            f"(max {DEFAULT_MAX_AGE_SECONDS}s)."
+                        ),
+                    )
+                )
+
+    if isinstance(data, dict) and "summary" not in data:
+        gaps.append(
+            Gap(
+                code="summary_missing",
+                detail="health_report.json missing 'summary' object.",
+            )
+        )
+
+    verdict = Verdict.PASS if not gaps else Verdict.FAIL_AUTO
+    log.info(
+        "platform_validate_complete",
+        verdict=verdict.value,
+        gap_count=len(gaps),
+    )
+    return ValidationReport(verdict=verdict, gaps=gaps)