okstra 0.146.1 → 0.148.0

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

@@ -0,0 +1,139 @@
+"""Deterministic inline-SVG builders with table-compatible node IDs."""
+from __future__ import annotations
+
+import html
+from dataclasses import replace
+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]]:
+    """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:
+        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'<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)
+        label = html.escape(node.label)
+        status = html.escape(node.status)
+        detail = html.escape(node.detail)
+        parts.append(
+            f'<g data-node-id="{node_id}" class="node node-{status}">'
+            f"<title>{label}: {status}. {detail}</title>"
+            f'<rect x="{x}" y="{y}" width="180" height="50" rx="8"/>'
+            f'<text x="{x + 12}" y="{y + 30}">{label}</text></g>'
+        )
+    parts.append("</svg>")
+    return "".join(parts)
+
+
+def dependency_figure(*, nodes: Sequence[VisualNode], edges: Sequence[VisualEdge], title: str) -> FigureModel:
+    ordered_nodes = tuple(sorted(nodes, key=lambda node: node.id))
+    ordered_edges = tuple(sorted(edges, key=lambda edge: (edge.source, edge.target, edge.label)))
+    return FigureModel(
+        figure_id="dependency-graph",
+        kind="dependency",
+        title=title,
+        summary=f"{len(ordered_nodes)} nodes and {len(ordered_edges)} relationships",
+        nodes=ordered_nodes,
+        edges=ordered_edges,
+        svg=_svg_document(ordered_nodes, ordered_edges),
+    )
+
+
+def flow_figure(*, nodes: Sequence[VisualNode], edges: Sequence[VisualEdge], title: str) -> FigureModel:
+    return replace(dependency_figure(nodes=nodes, edges=edges, title=title), kind="flow", figure_id="flow-graph")
+
+
+def decision_flow_figure(*, nodes: Sequence[VisualNode], edges: Sequence[VisualEdge], title: str) -> FigureModel:
+    return replace(
+        dependency_figure(nodes=nodes, edges=edges, title=title),
+        kind="decision-flow",
+        figure_id="decision-flow",
+    )
+
+
+def cause_graph_figure(*, nodes: Sequence[VisualNode], edges: Sequence[VisualEdge], title: str) -> FigureModel:
+    return replace(
+        dependency_figure(nodes=nodes, edges=edges, title=title),
+        kind="cause-graph",
+        figure_id="cause-graph",
+    )
+
+
+def stage_map_figure(*, nodes: Sequence[VisualNode], edges: Sequence[VisualEdge], title: str) -> FigureModel:
+    return replace(
+        dependency_figure(nodes=nodes, edges=edges, title=title),
+        kind="stage-map",
+        figure_id="stage-map",
+    )
+
+
+def change_map_figure(*, nodes: Sequence[VisualNode], title: str) -> FigureModel:
+    return replace(
+        dependency_figure(nodes=nodes, edges=(), title=title),
+        kind="change-map",
+        figure_id="change-map",
+    )
+
+
+def matrix_figure(*, items: Iterable[VisualNode], title: str, x_label: str, y_label: str) -> FigureModel:
+    nodes = tuple(items)
+    summary = f"{len(nodes)} items compared by {x_label} and {y_label}"
+    return replace(dependency_figure(nodes=nodes, edges=(), title=title), kind="matrix", figure_id="matrix", summary=summary)
+
+
+def coverage_figure(*, rows: Iterable[VisualNode], title: str) -> FigureModel:
+    nodes = tuple(rows)
+    return replace(dependency_figure(nodes=nodes, edges=(), title=title), kind="coverage", figure_id="coverage")
+
+
+def timeline_figure(*, events: Iterable[VisualNode], title: str) -> FigureModel:
+    nodes = tuple(events)
+    edges = tuple(VisualEdge(nodes[i].id, nodes[i + 1].id, "next", "sequence") for i in range(len(nodes) - 1))
+    return replace(dependency_figure(nodes=nodes, edges=edges, title=title), kind="timeline", figure_id="timeline")

package/runtime/python/okstra_ctl/report_view_artifacts.py

@@ -5,7 +5,10 @@ from pathlib import Path
 
 
 def html_view_path(report_path: Path) -> Path:
-    """Return the self-contained HTML view path for a final-report markdown."""
+    """Return the HTML sibling for a final-report Markdown or data path."""
+    if report_path.name.endswith(".data.json"):
+        stem = report_path.name.removesuffix(".data.json")
+        return report_path.with_name(stem + ".html")
     return report_path.with_suffix(".html")
 
 

package/runtime/python/okstra_ctl/report_views.py

@@ -35,6 +35,11 @@ from pathlib import Path
 from typing import Iterable, Optional
 
 from .final_report_paths import final_report_data_path
+from .report_html.view_models.implementation_planning import (
+    PlanApprovalState,
+    plan_approval_state,
+    resolve_recommended_option,
+)
 from .report_view_artifacts import html_view_path, user_responses_dir_for_report
 
 
@@ -1142,16 +1147,7 @@ def report_has_clarification_items(src_md: str) -> bool:
     )
 
 
-@dataclass(frozen=True)
-class PlanApprovalContext:
-    """Plan Approval 위젯 렌더 입력. ``disabled_reason`` 이 비어 있지 않으면
-    위젯은 disabled 로 렌더된다 (run-prep 승인 게이트와 동일한 fail-closed 기준).
-    ``blocker_ids`` 는 §1 미해소 승인-차단 항목 ID 목록 — 화면 안내가 사용자에게
-    '어느 항목을 답해야 하는지' 를 보여주는 데 쓴다 (unreadable 사유면 빈 튜플)."""
-    option_names: tuple[str, ...]
-    recommended_option: str
-    disabled_reason: str
-    blocker_ids: tuple[str, ...]
+PlanApprovalContext = PlanApprovalState
 
 
 def _load_report_data(src_md_path: Path) -> dict | None:
@@ -1210,31 +1206,21 @@ def plan_approval_context(
     data = _load_report_data(src_md_path)
     if data is None:
         return None
-    planning = data.get("implementationPlanning")
-    if not isinstance(planning, dict):
+    state = plan_approval_state(data)
+    if state is None:
         return None
-    names = tuple(
-        c.get("name", "")
-        for c in (planning.get("optionCandidates") or [])
-        if isinstance(c, dict) and c.get("name")
-    )
-    if not names:
-        return None
-    rec = planning.get("recommendedOption")
-    rec_name = rec.get("name") or "" if isinstance(rec, dict) else ""
-    recommended = _resolve_recommended_option(rec_name, names)
     scan = scan_approval_gate(src_text)
-    blocker_ids: tuple[str, ...] = ()
+    blocker_ids = state.blocker_ids
+    reason = state.disabled_reason
     if scan.unreadable_reason:
+        blocker_ids = ()
         reason = "§1 승인 게이트를 읽을 수 없어 승인이 비활성화되었습니다 — 보고서를 재렌더하세요."
     elif scan.blockers:
         blocker_ids = tuple(b.row_id for b in scan.blockers)
         reason = f"§1 승인 차단 항목 {len(scan.blockers)}건 미해소"
-    else:
-        reason = ""
     return PlanApprovalContext(
-        option_names=names,
-        recommended_option=recommended,
+        option_names=state.option_names,
+        recommended_option=state.recommended_option,
         disabled_reason=reason,
         blocker_ids=blocker_ids,
     )
@@ -1318,22 +1304,8 @@ def _approval_label(data: dict, approval_ctx: PlanApprovalContext | None) -> str
 
 
 def _resolve_recommended_option(rec_name: str, names: tuple[str, ...]) -> str:
-    """``recommendedOption.name`` 을 후보 이름에 맞춘다. 정확 일치가 없으면
-    접두 일치(후보가 ``(RECOMMENDED)`` 같은 표식 접미를 더 달고 있는 흔한 경우)를
-    허용하되, 후보 이름이 서로의 접두여서 둘 이상이 매칭되면 모호하므로 채택하지
-    않고 첫 후보로 폴백한다 — 임의의 한 후보를 권장으로 잘못 표시하느니 결정적인
-    폴백이 낫다. 항상 정확히 한 옵션이 selected 가 되어 브라우저 자동선택분의 묵시
-    Export 를 차단한다."""
-    if rec_name in names:
-        return rec_name
-    if rec_name:
-        matches = [
-            name for name in names
-            if name.startswith(rec_name) or rec_name.startswith(name)
-        ]
-        if len(matches) == 1:
-            return matches[0]
-    return names[0]
+    """Compatibility wrapper for the shared v2 approval-state resolver."""
+    return resolve_recommended_option(rec_name, names)
 
 
 def _approval_blocked_guidance(ctx: PlanApprovalContext, run_meta: RunMeta) -> str: