okstra 0.27.0 → 0.29.0

package/runtime/validators/validate-report-views.py

@@ -0,0 +1,283 @@
+#!/usr/bin/env python3
+"""Validate the two derived final-report views produced by Phase 7 step
+1.5 (``scripts/okstra-render-report-views.py``).
+
+Checks, for a given final-report MD path:
+  1. ``*.slim.md`` and ``*.html`` siblings both exist.
+  2. Slim preserves every phase-required substring from ``validate-run.py``
+     byte-identically (drift fence vs the report_views module).
+  3. HTML body (``<main>`` slice) contains the same plain-text
+     substrings (after html.unescape and the markdown ``#`` prefix is
+     stripped).
+  4. HTML's §4.6 / §4.7 / §4.8 deliverable regions contain no
+     ``<textarea>`` / ``<input>`` / ``<select>`` (form-attach is
+     restricted to §5 clarification rows).
+  5. HTML has no external URLs in ``<script src=>`` / ``<link href=>`` /
+     ``<img src=>`` — self-contained guarantee.
+  6. Every Response ID in HTML matches the §5 Clarification Items table
+     of the source MD (1:1).
+
+Exit codes: 0 on success, 1 on any failure. Failures are printed one
+per line to stderr.
+"""
+from __future__ import annotations
+
+import argparse
+import html as html_lib
+import importlib.util
+import re
+import sys
+from pathlib import Path
+from typing import Iterable
+
+REPO_ROOT = Path(__file__).resolve().parents[1]
+SCRIPTS_DIR = REPO_ROOT / "scripts"
+if str(SCRIPTS_DIR) not in sys.path:
+    sys.path.insert(0, str(SCRIPTS_DIR))
+
+from okstra_ctl.clarification_items import parse_clarification_items  # noqa: E402
+from okstra_ctl.report_views import (  # noqa: E402
+    _strip_leading_digest_comment,
+    extract_html_digest,
+    extract_slim_digest,
+    preserved_substrings,
+    slim_markdown,
+    source_digest,
+)
+
+
+def _load_validate_run() -> object:
+    """Dynamically load validate-run.py — it's a stand-alone script
+    with a hyphenated name, not an importable module. We snapshot the
+    substring lists from it so drift between the two files surfaces
+    here rather than silently in production."""
+    path = REPO_ROOT / "validators" / "validate-run.py"
+    spec = importlib.util.spec_from_file_location("_okstra_validate_run", path)
+    assert spec and spec.loader, f"cannot load {path}"
+    mod = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(mod)
+    return mod
+
+
+def _detect_task_type(md: str) -> str | None:
+    m = re.search(r"^- Task Type:\s*(\S+)", md, re.MULTILINE)
+    return m.group(1).strip() if m else None
+
+
+def _main_body(html_text: str) -> str:
+    start = html_text.find("<main>")
+    end = html_text.find("</main>", start) if start >= 0 else -1
+    if start < 0 or end < 0:
+        return html_text
+    return html_text[start + len("<main>"): end]
+
+
+def _strip_md_prefix(sub: str) -> str:
+    s = sub
+    while s.startswith("#"):
+        s = s[1:]
+    return s.strip()
+
+
+_EXTERNAL_URL_RE = re.compile(
+    r'<(?:script|link|img|iframe|source|video|audio)\s[^>]*?(?:src|href)\s*=\s*["\']https?://',
+    re.IGNORECASE,
+)
+
+_RESPONSE_ID_ATTR_RE = re.compile(r'data-response-id="(C-\d+)"')
+
+_NO_FORM_HEADING_RE = re.compile(
+    r"<h[23][^>]*>\s*(?:4\.6|4\.7|4\.8)[\s\S]*?</h[23]>"
+)
+
+
+def _no_form_sections(html_body: str) -> list[str]:
+    """Return a list of strings, each being the rendered chunk of a
+    no-form section (4.6 / 4.7 / 4.8) up to the next h2/h3. Used to
+    check that no form controls live inside them.
+    """
+    chunks: list[str] = []
+    headings = [
+        m for m in re.finditer(
+            r'<h([23])[^>]*>([^<]*?)</h[23]>', html_body
+        )
+    ]
+    for i, m in enumerate(headings):
+        text = m.group(2).strip()
+        if not text.startswith(("4.6", "4.7", "4.8")):
+            continue
+        start = m.end()
+        end = headings[i + 1].start() if i + 1 < len(headings) else len(html_body)
+        chunks.append(html_body[start:end])
+    return chunks
+
+
+def validate(report_path: Path) -> list[str]:
+    failures: list[str] = []
+    if not report_path.is_file():
+        return [f"final-report not found: {report_path}"]
+
+    md = report_path.read_text(encoding="utf-8")
+    task_type = _detect_task_type(md)
+    slim_path = report_path.with_name(report_path.stem + ".slim.md")
+    html_path = report_path.with_name(report_path.stem + ".html")
+
+    # (1) sibling artifacts exist
+    if not slim_path.is_file():
+        failures.append(f"missing slim artifact: {slim_path}")
+    if not html_path.is_file():
+        failures.append(f"missing html artifact: {html_path}")
+    if failures:
+        return failures
+
+    slim = slim_path.read_text(encoding="utf-8")
+    html_text = html_path.read_text(encoding="utf-8")
+    html_body = _main_body(html_text)
+    html_body_text = html_lib.unescape(html_body)
+
+    # (2a) source-digest staleness — both derived views must carry the
+    # sha256 of the artifact derived from the *current* MD. A mismatch
+    # means the views were rendered against an older MD body and Phase
+    # 7 step 1.5 was not re-run.
+    #   - HTML digest is over the MD body (after stripping any stale
+    #     leading digest comment), so the expected value is the digest
+    #     of the current MD itself.
+    #   - slim digest is over the slim BODY (so any byte-difference
+    #     between expected and actual slim shows up as a digest
+    #     mismatch). We recompute the expected slim and extract its
+    #     embedded digest for comparison — equivalent to but cheaper
+    #     than diffing the full body.
+    expected_md_digest = source_digest(_strip_leading_digest_comment(md))
+    expected_slim_digest = extract_slim_digest(
+        slim_markdown(md, task_type=task_type)
+    )
+    slim_digest = extract_slim_digest(slim)
+    html_digest = extract_html_digest(html_text)
+    if slim_digest is None:
+        failures.append(
+            "slim missing source-sha256 header — re-render with okstra render-views"
+        )
+    elif slim_digest != expected_slim_digest:
+        failures.append(
+            f"stale slim: body sha256 {slim_digest[:12]}… does not match "
+            f"current MD's rendered slim {str(expected_slim_digest)[:12]}…"
+        )
+    if html_digest is None:
+        failures.append(
+            "html missing source-sha256 in run-meta — re-render with okstra render-views"
+        )
+    elif html_digest != expected_md_digest:
+        failures.append(
+            f"stale html: source-sha256 {html_digest[:12]}… does not match "
+            f"current MD {expected_md_digest[:12]}…"
+        )
+
+    # (2b) drift fence: report_views.preserved_substrings(task_type)
+    #      must agree with validate-run.py's tuples for the same task_type.
+    vr = _load_validate_run()
+    drift = _diff_substring_lists(task_type, vr)
+    failures.extend(drift)
+
+    # (3) slim preserves every required substring byte-identically
+    for sub in preserved_substrings(task_type):
+        if sub in md and sub not in slim:
+            failures.append(f"slim dropped required substring: {sub!r}")
+        # Also forward-check against validate-run.py's tuples so a
+        # future addition there fails this validator immediately.
+    for sub in _validate_run_substrings(task_type, vr):
+        if sub in md and sub not in slim:
+            failures.append(f"slim dropped validate-run substring: {sub!r}")
+
+    # (4) html preserves the same set (modulo md prefix + html.escape)
+    for sub in preserved_substrings(task_type):
+        if sub not in md:
+            continue
+        needle = _strip_md_prefix(sub)
+        if needle not in html_body_text:
+            failures.append(f"html body dropped substring: {needle!r}")
+
+    # (5) deliverable sections contain no form controls
+    for chunk in _no_form_sections(html_body):
+        if "<textarea" in chunk or "<input" in chunk or "<select" in chunk:
+            failures.append(
+                "html §4.6/§4.7/§4.8 deliverable section contains a form control"
+            )
+            break
+
+    # (6) no external URLs in <script src> / <link href> / etc.
+    if _EXTERNAL_URL_RE.search(html_text):
+        failures.append("html contains external URL in script/link/img — must be self-contained")
+
+    # (7) Response ID parity: HTML form rows ↔ §5 C-* rows in MD.
+    # Bidirectional — catches both "MD has C-* the HTML lost" AND
+    # "HTML has stale C-* that the current MD no longer declares".
+    md_ids = _md_response_ids(md)
+    html_ids = sorted(set(_RESPONSE_ID_ATTR_RE.findall(html_text)))
+    if md_ids != html_ids:
+        failures.append(
+            f"Response ID mismatch: MD §5 has {md_ids}, HTML has {html_ids}"
+        )
+
+    return failures
+
+
+def _validate_run_substrings(task_type: str | None, vr) -> Iterable[str]:
+    if task_type == "implementation":
+        return getattr(vr, "IMPLEMENTATION_REQUIRED_SECTIONS", ())
+    if task_type == "final-verification":
+        return getattr(vr, "FINAL_VERIFICATION_REQUIRED_SECTIONS", ())
+    return ()
+
+
+def _diff_substring_lists(task_type: str | None, vr) -> list[str]:
+    """Surface drift between report_views and validate-run substring
+    tuples. The two MUST stay in lock-step."""
+    failures: list[str] = []
+    from okstra_ctl.report_views import (
+        PRESERVED_SUBSTRINGS_IMPLEMENTATION,
+        PRESERVED_SUBSTRINGS_FINAL_VERIFICATION,
+    )
+    impl_vr = set(getattr(vr, "IMPLEMENTATION_REQUIRED_SECTIONS", ()))
+    impl_rv = set(PRESERVED_SUBSTRINGS_IMPLEMENTATION)
+    if impl_vr != impl_rv:
+        missing_in_views = impl_vr - impl_rv
+        extra_in_views = impl_rv - impl_vr
+        failures.append(
+            "drift: PRESERVED_SUBSTRINGS_IMPLEMENTATION vs validate-run "
+            f"IMPLEMENTATION_REQUIRED_SECTIONS — missing in views {missing_in_views or '∅'}, "
+            f"extra in views {extra_in_views or '∅'}"
+        )
+    fv_vr = set(getattr(vr, "FINAL_VERIFICATION_REQUIRED_SECTIONS", ()))
+    fv_rv = set(PRESERVED_SUBSTRINGS_FINAL_VERIFICATION)
+    if fv_vr != fv_rv:
+        failures.append(
+            "drift: PRESERVED_SUBSTRINGS_FINAL_VERIFICATION vs validate-run "
+            f"FINAL_VERIFICATION_REQUIRED_SECTIONS — missing in views {fv_vr - fv_rv or '∅'}, "
+            f"extra in views {fv_rv - fv_vr or '∅'}"
+        )
+    return failures
+
+
+def _md_response_ids(md: str) -> list[str]:
+    items = parse_clarification_items(md) or []
+    return sorted({it.row_id for it in items if re.fullmatch(r"C-\d+", it.row_id)})
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        description="Validate slim/html derived views of an okstra final-report."
+    )
+    parser.add_argument(
+        "report_path",
+        type=Path,
+        help="Path to the original final-report markdown.",
+    )
+    args = parser.parse_args(argv)
+    failures = validate(args.report_path)
+    for f in failures:
+        print(f, file=sys.stderr)
+    return 1 if failures else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())