okstra 0.31.0 → 0.32.1

package/runtime/python/okstra_ctl/render_final_report.py

@@ -0,0 +1,201 @@
+"""Render `final-report-<task-type>-<seq>.md` from its JSON SSOT.
+
+The JSON SSOT lives next to the rendered markdown as
+``final-report-<task-type>-<seq>.data.json``. The schema for that file is
+``schemas/final-report-v1.0.schema.json``. Report-writer-worker writes the
+data.json in Phase 6; this renderer + the Jinja2 template at
+``templates/reports/final-report.template.md`` deterministically produce
+the canonical user-facing markdown.
+
+Why this exists: prior to v0.32, report-writer-worker wrote the markdown
+directly. Free-form authoring led to silent contract violations — missing
+columns in the Execution Status table, omitted §7 phase-continuation
+rows, invented ``## Index`` sections. Routing everything through one
+template + schema cuts those failure modes to zero.
+
+Phase 7 mutation flow: ``okstra-token-usage.py --substitute-data`` fills
+the ``tokenUsage`` and ``executionStatus[].totalTokens`` etc. cells in
+data.json, then re-invokes this renderer so the markdown stays in sync.
+The markdown is never hand-edited.
+"""
+from __future__ import annotations
+
+import json
+import os
+import sys
+from pathlib import Path
+from typing import Any
+
+# Vendored jinja2 must be importable. The installer (``src/install.mjs``)
+# drops ``okstra_vendor/`` under ``~/.okstra/lib/python/``; in-repo runs
+# rely on ``scripts/`` being on PYTHONPATH. Either way the package
+# registers ``markupsafe`` and ``jinja2`` aliases in ``sys.modules`` so
+# downstream ``from jinja2 import ...`` resolves to the vendored copy.
+import okstra_vendor  # noqa: F401 — side effect: sys.modules aliases
+from jinja2 import ChainableUndefined, Environment, FileSystemLoader
+from jinja2 import select_autoescape  # noqa: F401 — kept for future HTML use
+
+
+DEFAULT_TEMPLATE_REL = ("templates", "reports", "final-report.template.md")
+
+
+class RenderError(RuntimeError):
+    """Raised when the data.json cannot be rendered. Wraps jinja2 errors
+    and IO errors with a single user-facing message so the CLI / Phase 6
+    surface one consistent failure shape.
+    """
+
+
+def _format_int(value: Any) -> str:
+    if value is None:
+        return "--"
+    try:
+        return f"{int(value):,}"
+    except (TypeError, ValueError):
+        return "--"
+
+
+def _format_usd(value: Any) -> str:
+    if value is None:
+        return "--"
+    try:
+        return f"${float(value):.2f}"
+    except (TypeError, ValueError):
+        return "--"
+
+
+def _format_duration_ms(value: Any) -> str:
+    if value is None:
+        return "--"
+    try:
+        ms = int(value)
+    except (TypeError, ValueError):
+        return "--"
+    total_seconds = ms // 1000
+    minutes, seconds = divmod(total_seconds, 60)
+    return f"{minutes}m {seconds:02d}s"
+
+
+def _yaml_scalar(value: Any) -> str:
+    """Serialize a scalar for the YAML frontmatter block.
+
+    Strings: wrap in double quotes and escape embedded double-quote /
+    backslash so the YAML parser at consumer side (Obsidian / okstra
+    runtime) does not choke on accidental colons or square brackets in
+    the value. Bools / numbers / None: render as-is.
+    """
+    if value is None:
+        return ""
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if isinstance(value, (int, float)):
+        return str(value)
+    text = str(value)
+    escaped = text.replace("\\", "\\\\").replace('"', '\\"')
+    return f'"{escaped}"'
+
+
+def _yaml_inline_list(values: list[str]) -> str:
+    """Render a list of strings as a YAML flow-style sequence on one line."""
+    return "[" + ", ".join(_yaml_scalar(v) for v in values) + "]"
+
+
+def _build_environment(template_dir: Path) -> Environment:
+    # ChainableUndefined lets optional fields (e.g.
+    # ``clarificationCarryIn``, ``ticketCoverage.omit``) silently evaluate
+    # to false in `{% if %}` tests instead of raising. Strict presence
+    # checking is the schema validator's job, not the renderer's — and
+    # the renderer can't tell "the writer forgot this required field"
+    # from "this field is intentionally absent on this task-type".
+    env = Environment(
+        loader=FileSystemLoader(str(template_dir)),
+        undefined=ChainableUndefined,
+        trim_blocks=True,
+        lstrip_blocks=True,
+        keep_trailing_newline=True,
+    )
+    env.filters["format_int"] = _format_int
+    env.filters["format_usd"] = _format_usd
+    env.filters["format_duration_ms"] = _format_duration_ms
+    env.filters["yaml_scalar"] = _yaml_scalar
+    env.filters["yaml_inline_list"] = _yaml_inline_list
+    return env
+
+
+def render(data: dict, *, template_path: Path) -> str:
+    """Render ``data`` through the Jinja2 ``template_path`` and return the
+    final markdown as a string. Caller writes it to disk.
+
+    Raises ``RenderError`` on any template / IO / data structural failure
+    so the surface is one exception type rather than the broad jinja2
+    hierarchy.
+    """
+    if not template_path.is_file():
+        raise RenderError(f"template not found: {template_path}")
+
+    env = _build_environment(template_path.parent)
+    try:
+        template = env.get_template(template_path.name)
+        return template.render(**data)
+    except Exception as exc:  # jinja2.TemplateError, KeyError, etc.
+        raise RenderError(
+            f"render failed for template {template_path.name}: {exc}"
+        ) from exc
+
+
+def find_default_template(start: Path | None = None) -> Path:
+    """Locate the bundled final-report template.
+
+    Resolution order:
+      1. ``$OKSTRA_HOME/templates/reports/final-report.template.md`` (installed runtime).
+      2. ``<repo>/templates/reports/final-report.template.md`` (in-repo dev runs).
+         Repo root is detected by walking up from this file until a
+         ``templates/reports/final-report.template.md`` exists.
+
+    Raises ``RenderError`` if neither path is present.
+    """
+    okstra_home = os.environ.get("OKSTRA_HOME")
+    if okstra_home:
+        candidate = Path(okstra_home).joinpath(*DEFAULT_TEMPLATE_REL)
+        if candidate.is_file():
+            return candidate
+
+    here = Path(start or __file__).resolve()
+    for parent in [here, *here.parents]:
+        candidate = parent.joinpath(*DEFAULT_TEMPLATE_REL)
+        if candidate.is_file():
+            return candidate
+
+    raise RenderError(
+        "could not locate final-report.template.md. Set OKSTRA_HOME or "
+        "run from a checkout that contains templates/reports/."
+    )
+
+
+def render_to_file(
+    data_path: Path,
+    output_path: Path,
+    *,
+    template_path: Path | None = None,
+) -> int:
+    """Read ``data_path`` (JSON), render through Jinja2, write to
+    ``output_path``. Returns the number of bytes written.
+
+    The output is written atomically (write-then-rename) so a partial
+    write never produces a half-corrupt final-report on disk.
+    """
+    if not data_path.is_file():
+        raise RenderError(f"data file not found: {data_path}")
+    try:
+        data = json.loads(data_path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as exc:
+        raise RenderError(f"invalid JSON in {data_path}: {exc}") from exc
+
+    resolved_template = template_path or find_default_template(data_path)
+    rendered = render(data, template_path=resolved_template)
+
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    tmp = output_path.with_suffix(output_path.suffix + f".tmp.{os.getpid()}")
+    tmp.write_text(rendered, encoding="utf-8")
+    tmp.replace(output_path)
+    return len(rendered.encode("utf-8"))