okstra 0.147.0 → 0.148.0

package/runtime/python/okstra_ctl/report_html/filters.py

@@ -0,0 +1,104 @@
+"""Jinja filters for the task-specific HTML report."""
+from __future__ import annotations
+
+import html
+import json
+import re
+
+import okstra_vendor  # noqa: F401  # registers vendored dependency aliases
+from markupsafe import Markup, escape
+
+_INLINE_CODE = re.compile(r"`([^`]+)`")
+_SENTENCE_END = re.compile(r"(?<=[.!?])\s+")
+_SENTENCES_PER_PARAGRAPH = 2
+
+
+def audit_json(value: object) -> Markup:
+    """Serialize an audit payload for reading inside a ``<pre>`` text node.
+
+    Jinja's ``tojson`` guards a ``<script>`` context, so it escapes quotes and
+    angle brackets as ``\\uXXXX`` and leaves shell commands and non-ASCII
+    evidence unreadable. A text node only needs ``&``, ``<`` and ``>`` escaped,
+    hence ``quote=False`` — quotes carry no meaning outside an attribute value.
+    """
+    rendered = json.dumps(value, indent=2, ensure_ascii=False, sort_keys=True)
+    return Markup(html.escape(rendered, quote=False))
+
+
+def inline_code(value: object) -> Markup:
+    """Convert paired backticks to ``<code>``, escaping everything else.
+
+    Workers author report prose with Markdown conventions, so an identifier
+    arrives wrapped in backticks. ``escape`` also covers quotes, unlike
+    ``audit_json`` above, which is text-node only.
+    """
+    text = "" if value is None else str(value)
+    out: list[str] = []
+    cursor = 0
+    for match in _INLINE_CODE.finditer(text):
+        out.append(str(escape(text[cursor:match.start()])))
+        out.append(f"<code>{escape(match.group(1))}</code>")
+        cursor = match.end()
+    out.append(str(escape(text[cursor:])))
+    return Markup("".join(out))
+
+
+def _grouped_paragraphs(text: str) -> list[str]:
+    explicit = [block.strip() for block in re.split(r"\n\s*\n", text) if block.strip()]
+    if len(explicit) > 1:
+        return explicit
+    sentences = [s.strip() for s in _SENTENCE_END.split(text.strip()) if s.strip()]
+    if len(sentences) <= _SENTENCES_PER_PARAGRAPH:
+        return [text.strip()] if text.strip() else []
+    return [
+        " ".join(sentences[i:i + _SENTENCES_PER_PARAGRAPH])
+        for i in range(0, len(sentences), _SENTENCES_PER_PARAGRAPH)
+    ]
+
+
+def paragraphs(value: object) -> Markup:
+    """Split prose into ``<p>`` blocks, converting inline code inside each.
+
+    ``userNarrative`` prose arrives as one unbroken run of sentences, so the
+    reader gets no paragraph boundary anywhere in the document. An author who
+    did supply blank lines keeps their own boundaries.
+    """
+    text = "" if value is None else str(value)
+    return Markup("".join(f"<p>{inline_code(block)}</p>" for block in _grouped_paragraphs(text)))
+
+
+def evidence_refs(refs: object, index: object) -> Markup:
+    """Render evidence ids as anchors when the ledger defines them.
+
+    A citation whose id has no ledger row would link to a missing anchor, so it
+    stays text. No schema behind this filter constrains that text to an id —
+    most of it is prose citing a ``path:line``, so it takes ``inline_code`` like
+    every other prose cell. An anchor's own text is the id it links to and gets
+    no ``<code>`` wrapper.
+    """
+    rows = index if isinstance(index, dict) else {}
+    items = refs if isinstance(refs, (list, tuple)) else []
+    out: list[str] = []
+    for ref in items:
+        if str(ref) not in rows:
+            out.append(str(inline_code(ref)))
+            continue
+        text = escape(str(ref))
+        out.append(f'<a href="#ev-{text}">{text}</a>')
+    return Markup(", ".join(out))
+
+
+def code_evidence(rows: object) -> Markup:
+    """Render ``currentCodeEvidence`` entries as ``path:line`` code spans."""
+    items = rows if isinstance(rows, (list, tuple)) else []
+    out: list[str] = []
+    for row in items:
+        if not isinstance(row, dict):
+            continue
+        path = str(row.get("path", "")).strip()
+        if not path:
+            continue
+        line = row.get("line")
+        ref = f"{path}:{line}" if line else path
+        out.append(f"<code>{escape(ref)}</code>")
+    return Markup(", ".join(out))

package/runtime/python/okstra_ctl/report_html/render.py

@@ -9,6 +9,7 @@ import okstra_vendor  # noqa: F401  # registers vendored dependency aliases
 from jinja2 import Environment, FileSystemLoader, StrictUndefined, select_autoescape
 
 from ..final_report_schema import load_schema_for_data, validate
+from .filters import audit_json, code_evidence, evidence_refs, inline_code, paragraphs
 from .models import HtmlRunMeta
 from .router import HtmlRenderError, resolve_html_route
 
@@ -52,6 +53,12 @@ def render_v2_html_view(
     view = route.view_builder(data)
     root = _templates_root(templates_root)
     env = Environment(loader=FileSystemLoader(str(root)), autoescape=select_autoescape(("html",)), undefined=StrictUndefined)
+    env.policies["json.dumps_kwargs"] = {"sort_keys": True, "ensure_ascii": False}
+    env.filters["audit_json"] = audit_json
+    env.filters["code_evidence"] = code_evidence
+    env.filters["evidence_refs"] = evidence_refs
+    env.filters["inline_code"] = inline_code
+    env.filters["paragraphs"] = paragraphs
     response_js = (root / "report.js").read_text(encoding="utf-8")
     base_js = (root / "html/assets/base.js").read_text(encoding="utf-8")
     context = {

package/runtime/python/okstra_ctl/report_html/view_models/change_impact_analysis.py

@@ -1,7 +1,7 @@
 """Human-first change-impact-analysis view model."""
 from __future__ import annotations
 
-from ..common import analysis_review_ids, audit_context
+from ..common import analysis_review_ids, audit_context, evidence_index
 from ..models import HumanReportView, VisualEdge, VisualNode
 from ..visualizations import flow_figure
 
@@ -28,6 +28,7 @@ def build_change_impact_analysis_view(data: dict) -> HumanReportView:
         "narrative": change["userNarrative"],
         "blastRadiusFigure": figure,
         "analysisReviewIds": analysis_review_ids(data),
+        "evidenceIndex": evidence_index(data),
         "audit": audit_context(data),
     }
     return HumanReportView(

package/runtime/python/okstra_ctl/report_html/view_models/error_analysis.py

@@ -1,7 +1,7 @@
 """Human-first error-analysis view model."""
 from __future__ import annotations
 
-from ..common import audit_context
+from ..common import audit_context, evidence_index
 from ..models import HumanReportView, VisualEdge, VisualNode
 from ..visualizations import cause_graph_figure
 
@@ -38,6 +38,7 @@ def build_error_analysis_view(data: dict) -> HumanReportView:
         "error": error,
         "narrative": error["userNarrative"],
         "causeFigure": figure,
+        "evidenceIndex": evidence_index(data),
         "audit": audit_context(data),
     }
     return HumanReportView(

package/runtime/python/okstra_ctl/report_html/view_models/feature_analysis.py

@@ -1,7 +1,7 @@
 """Human-first feature-analysis view model."""
 from __future__ import annotations
 
-from ..common import analysis_review_ids, audit_context
+from ..common import analysis_review_ids, audit_context, evidence_index
 from ..models import HumanReportView, VisualNode
 from ..visualizations import flow_figure
 
@@ -28,6 +28,7 @@ def build_feature_analysis_view(data: dict) -> HumanReportView:
         "narrative": feature["userNarrative"],
         "flowFigure": figure,
         "analysisReviewIds": analysis_review_ids(data),
+        "evidenceIndex": evidence_index(data),
         "audit": audit_context(data),
     }
     return HumanReportView(

package/runtime/python/okstra_ctl/report_html/view_models/final_verification.py

@@ -1,7 +1,7 @@
 """Human-first final-verification view model."""
 from __future__ import annotations
 
-from ..common import audit_context
+from ..common import audit_context, evidence_index
 from ..models import HumanReportView, VisualNode
 from ..visualizations import coverage_figure
 
@@ -36,6 +36,7 @@ def build_final_verification_view(data: dict) -> HumanReportView:
         "narrative": final["userNarrative"],
         "coverageFigure": figure,
         "releaseAllowed": data["verdictCard"]["verdictToken"] == "accepted",
+        "evidenceIndex": evidence_index(data),
         "audit": audit,
     }
     return HumanReportView(

package/runtime/python/okstra_ctl/report_html/view_models/implementation.py

@@ -1,7 +1,7 @@
 """Human-first implementation delivery view model."""
 from __future__ import annotations
 
-from ..common import audit_context
+from ..common import audit_context, evidence_index
 from ..models import HumanReportView, VisualNode
 from ..visualizations import change_map_figure
 
@@ -36,6 +36,7 @@ def build_implementation_view(data: dict) -> HumanReportView:
         "implementation": implementation,
         "narrative": implementation["userNarrative"],
         "changeFigure": figure,
+        "evidenceIndex": evidence_index(data),
         "audit": audit,
     }
     return HumanReportView(

package/runtime/python/okstra_ctl/report_html/view_models/implementation_planning.py

@@ -4,7 +4,7 @@ from __future__ import annotations
 import re
 from dataclasses import dataclass
 
-from ..common import audit_context
+from ..common import audit_context, evidence_index
 from ..models import HumanReportView, VisualEdge, VisualNode
 from ..visualizations import stage_map_figure
 
@@ -92,6 +92,7 @@ def build_implementation_planning_view(data: dict) -> HumanReportView:
             if row.get("blocks") == "approval"
             and row.get("status") in {"open", "answered"}
         ],
+        "evidenceIndex": evidence_index(data),
         "audit": audit,
     }
     return HumanReportView(

package/runtime/python/okstra_ctl/report_html/view_models/improvement_discovery.py

@@ -1,7 +1,7 @@
 """Human-first improvement-discovery view model."""
 from __future__ import annotations
 
-from ..common import audit_context
+from ..common import audit_context, evidence_index
 from ..models import HumanReportView, VisualNode
 from ..visualizations import matrix_figure
 
@@ -32,6 +32,7 @@ def build_improvement_discovery_view(data: dict) -> HumanReportView:
         "improvement": improvement,
         "narrative": improvement["userNarrative"],
         "matrixFigure": figure,
+        "evidenceIndex": evidence_index(data),
         "audit": audit_context(data),
     }
     return HumanReportView(

package/runtime/python/okstra_ctl/report_html/view_models/release_handoff.py

@@ -3,7 +3,7 @@ from __future__ import annotations
 
 from urllib.parse import urlparse
 
-from ..common import audit_context
+from ..common import audit_context, evidence_index
 from ..models import HumanReportView, VisualNode
 from ..visualizations import timeline_figure
 
@@ -43,6 +43,7 @@ def build_release_handoff_view(data: dict) -> HumanReportView:
         "narrative": handoff["userNarrative"],
         "handoffFigure": figure,
         "prUrl": _safe_http_url(handoff["pullRequestOutcome"].get("url", "")),
+        "evidenceIndex": evidence_index(data),
         "audit": audit,
     }
     return HumanReportView(

package/runtime/python/okstra_ctl/report_html/view_models/requirements_discovery.py

@@ -1,7 +1,7 @@
 """Human-first requirements-discovery view model."""
 from __future__ import annotations
 
-from ..common import audit_context
+from ..common import audit_context, evidence_index
 from ..models import HumanReportView, VisualEdge, VisualNode
 from ..visualizations import decision_flow_figure
 
@@ -44,6 +44,7 @@ def build_requirements_discovery_view(data: dict) -> HumanReportView:
         "narrative": requirements["userNarrative"],
         "routingFigure": figure,
         "clarificationItems": data.get("clarificationItems", []),
+        "evidenceIndex": evidence_index(data),
         "audit": audit_context(data),
     }
     return HumanReportView(

package/runtime/python/okstra_ctl/report_html/visualizations.py

@@ -8,28 +8,54 @@ from typing import Iterable, Sequence
 from .models import FigureModel, VisualEdge, VisualNode
 
 
+_ROWS_PER_COLUMN = 8
+_COLUMN_WIDTH = 260
+_ROW_HEIGHT = 100
+
+
 def _node_positions(nodes: Sequence[VisualNode]) -> dict[str, tuple[int, int]]:
-    groups = {group: index for index, group in enumerate(sorted({n.group for n in nodes}))}
-    rows: dict[str, int] = {}
+    """Lay out one column per group, wrapping tall groups into extra columns."""
+    groups = sorted({n.group for n in nodes})
+    counts: dict[str, int] = {}
+    column_offset: dict[str, int] = {}
+    offset = 0
+    for group in groups:
+        column_offset[group] = offset
+        size = sum(1 for n in nodes if n.group == group)
+        offset += max(1, -(-size // _ROWS_PER_COLUMN))
     positions: dict[str, tuple[int, int]] = {}
     for node in nodes:
-        row = rows.get(node.group, 0)
-        rows[node.group] = row + 1
-        positions[node.id] = (50 + groups[node.group] * 260, 55 + row * 100)
+        index = counts.get(node.group, 0)
+        counts[node.group] = index + 1
+        column = column_offset[node.group] + index // _ROWS_PER_COLUMN
+        row = index % _ROWS_PER_COLUMN
+        positions[node.id] = (50 + column * _COLUMN_WIDTH, 55 + row * _ROW_HEIGHT)
     return positions
 
 
+_ARROW_MARKER = (
+    '<defs><marker id="edge-arrow" viewBox="0 0 10 10" refX="9" refY="5" '
+    'markerWidth="6" markerHeight="6" orient="auto-start-reverse">'
+    '<path d="M 0 0 L 10 5 L 0 10 z" class="edge-arrow-head" /></marker></defs>'
+)
+
+
 def _svg_document(nodes: Sequence[VisualNode], edges: Sequence[VisualEdge]) -> str:
     positions = _node_positions(nodes)
     width = max((x for x, _ in positions.values()), default=50) + 230
     height = max((y for _, y in positions.values()), default=55) + 90
     parts = [f'<svg viewBox="0 0 {width} {height}" role="img" xmlns="http://www.w3.org/2000/svg">']
+    parts.append(_ARROW_MARKER)
     for edge in edges:
         if edge.source not in positions or edge.target not in positions:
             continue
         x1, y1 = positions[edge.source]
         x2, y2 = positions[edge.target]
-        parts.append(f'<line x1="{x1 + 90}" y1="{y1 + 25}" x2="{x2 + 90}" y2="{y2 + 25}" class="edge edge-{html.escape(edge.kind)}" />')
+        parts.append(
+            f'<g class="edge-group"><title>{html.escape(edge.label)}</title>'
+            f'<line x1="{x1 + 90}" y1="{y1 + 25}" x2="{x2 + 90}" y2="{y2 + 25}" '
+            f'class="edge edge-{html.escape(edge.kind)}" marker-end="url(#edge-arrow)" /></g>'
+        )
     for node in nodes:
         x, y = positions[node.id]
         node_id = html.escape(node.id)