okstra 0.149.0 → 0.151.0

package/runtime/python/okstra_ctl/render_final_report.py

@@ -454,7 +454,7 @@ def _inject_index_and_anchors(markdown: str, dictionary: dict | None) -> str:
     return "\n".join(lines)
 
 
-def inject_index_into_file(md_path: Path, *, report_language: str = "en") -> int:
+def inject_index_into_file(md_path: Path) -> int:
     """Apply the legacy top-of-report index to an existing Markdown report.
 
     This remains for schema-v1 and quick compatibility artifacts. Schema-v2
@@ -463,12 +463,8 @@ def inject_index_into_file(md_path: Path, *, report_language: str = "en") -> int
     """
     if not md_path.is_file():
         raise FinalReportRenderError(f"report markdown not found: {md_path}")
-    if report_language not in SUPPORTED_LANGS:
-        raise FinalReportRenderError(
-            f"report_language must be one of {SUPPORTED_LANGS}, got {report_language!r}"
-        )
     try:
-        dictionary = load_dictionary(report_language)
+        dictionary = load_dictionary(MARKDOWN_LANG)
     except I18nError as exc:
         raise FinalReportRenderError(str(exc)) from exc
     injected = _inject_index_and_anchors(md_path.read_text(encoding="utf-8"), dictionary)
@@ -630,12 +626,20 @@ def _ai_markdown_context(data: dict) -> dict:
     return context
 
 
-def resolve_report_language(data: dict, *, override: str | None) -> str:
-    """우선순위: override > data.meta.reportLanguage > 'en'."""
-    if override is not None:
-        candidate = override
-    else:
-        candidate = (data.get("meta") or {}).get("reportLanguage") or "en"
+# The Markdown is the AI handoff sibling of the data.json — same content, same
+# audience, so it renders in the SSOT's language and nothing else. The field
+# still has to be well-formed here because it decides whether Phase 7 pays for
+# a translator, and a malformed one would surface at the very end of the run.
+MARKDOWN_LANG = "en"
+
+
+def validate_report_language(data: dict) -> str:
+    """Check `meta.reportLanguage` and return the Markdown's own language.
+
+    The value names the language the *human HTML* renders in; it never
+    selects this renderer's dictionary.
+    """
+    candidate = (data.get("meta") or {}).get("reportLanguage") or "en"
     if candidate == "auto":
         raise FinalReportRenderError(
             "reportLanguage 'auto' must be resolved by the lead before "
@@ -646,7 +650,7 @@ def resolve_report_language(data: dict, *, override: str | None) -> str:
         raise FinalReportRenderError(
             f"reportLanguage must be one of {SUPPORTED_LANGS}, got {candidate!r}"
         )
-    return candidate
+    return MARKDOWN_LANG
 
 
 # Schema-optional top-level arrays, and the value a template may assume when
@@ -685,7 +689,6 @@ def render(
     data: dict,
     *,
     template_path: Path,
-    report_language: str | None = None,
 ) -> str:
     """Render ``data`` through the Jinja2 ``template_path`` and return the
     final markdown as a string. Caller writes it to disk.
@@ -699,7 +702,7 @@ def render(
 
     _enforce_schema(data)
 
-    lang = resolve_report_language(data, override=report_language)
+    lang = validate_report_language(data)
     try:
         dictionary = load_dictionary(lang)
     except I18nError as exc:
@@ -834,7 +837,6 @@ def render_to_file(
     output_path: Path,
     *,
     template_path: Path | None = None,
-    report_language: str | None = None,
 ) -> int:
     """Read ``data_path`` (JSON), render through Jinja2, write to
     ``output_path``. Returns the number of bytes written.
@@ -859,7 +861,6 @@ def render_to_file(
         rendered = render(
             data,
             template_path=resolved_template,
-            report_language=report_language,
         )
     except FinalReportRenderError as exc:
         raise _with_excerpt_drift_hint(exc, data_path) from exc

package/runtime/python/okstra_ctl/report_finalize.py

@@ -24,12 +24,17 @@ from .final_report_paths import final_report_data_path, final_report_markdown_pa
 from .paths import task_dir, task_manifest_file
 
 
+STEP_CHECK_SOURCE = "check-source"
 STEP_TOKEN_USAGE = "token-usage"
 STEP_RENDER_VIEWS = "render-views"
 STEP_SPAWN_FOLLOWUPS = "spawn-followups"
 STEP_VALIDATE_RUN = "validate-run"
 
 STEP_ORDER = (
+    # First, because everything after it derives from the data.json: rendering
+    # a Korean SSOT into English chrome, spawning follow-ups from it, and
+    # validating it all succeed on a record the next phase cannot read.
+    STEP_CHECK_SOURCE,
     STEP_TOKEN_USAGE,
     STEP_RENDER_VIEWS,
     STEP_SPAWN_FOLLOWUPS,
@@ -205,6 +210,19 @@ def build_commands(ctx: FinalizeContext) -> list[tuple[str, list[str]]]:
     """Assemble the ordered Phase 7 argv list. Order is contractual."""
     markdown_path = ctx.markdown_path
     return [
+        (
+            STEP_CHECK_SOURCE,
+            [
+                sys.executable,
+                str(
+                    resolve_workspace_script(
+                        ctx.workspace_root, "okstra-report-translate.py"
+                    )
+                ),
+                "check-source",
+                str(ctx.data_path),
+            ],
+        ),
         (
             STEP_TOKEN_USAGE,
             [

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

@@ -97,90 +97,28 @@ def evidence_refs(refs: object, anchors: object) -> Markup:
 
 # Schema enums a reader has to decode. Each vocabulary is named so a value can
 # mean different things in different fields without one table flattening them.
-# A value with no entry renders as itself — a new enum member shows up raw
-# rather than silently reading as something it is not.
-ENUM_LABELS: dict[str, dict[str, str]] = {
-    "coverage": {
-        "covered": "A break fails a test",
-        "partial": "Partly covered",
-        "gap": "No test",
-        "risk": "Passes without proving",
-    },
-    "effort": {"S": "Small", "M": "Medium", "L": "Large", "XL": "Very large"},
-    "versionSource": {
-        "manifest-range": "Manifest range",
-        "lockfile-pinned": "Lockfile pin",
-        "container-image": "Container image",
-        "runtime-config": "Runtime config",
-        "declared-doc": "Declared in docs",
-    },
-    "interfaceKind": {
-        "port": "Port",
-        "adapter": "Adapter",
-        "service-api": "Service API",
-        "module-export": "Module export",
-        "event": "Event",
-    },
-    "toolKind": {
-        "packageManager": "Package manager",
-        "build": "Build",
-        "test": "Test",
-        "lint": "Lint",
-        "typecheck": "Type check",
-        "format": "Format",
-        "ci": "CI",
-        "container": "Container",
-    },
-    "lens": {"candidate-found": "Candidate found", "no-candidate": "Nothing found"},
-    "rejectionSource": {
-        "brief-desired-outcome": "Brief · desired outcome",
-        "brief-out-of-scope": "Brief · out of scope",
-        "brief-source-material": "Brief · source material",
-        "clarification-raised": "Raised as a question",
-        "absent-not-material": "Absent · does not change the call",
-    },
-    "termSource": {
-        "glossary": "Glossary",
-        "decision-record": "Decision record",
-        "brief": "Brief",
-        "clarification": "Your answer",
-    },
-    "handoffMode": {"whole-task": "Whole task", "stage-group": "Selected stages"},
-}
-
-
-# What each member of a vocabulary actually claims. A two-word label fits a
-# table cell but cannot carry a definition, and a reader meeting "Passes
-# without proving" for the first time has nowhere to look it up. Only
-# vocabularies whose members are judgements need one; a kind names itself.
-ENUM_HINTS: dict[str, dict[str, str]] = {
-    "coverage": {
-        "covered": "Break this area and a test fails.",
-        "partial": "Tests exist, but part of the area runs through none of them.",
-        "gap": "No test runs through this area at all.",
-        "risk": (
-            "Tests run and pass, but they skip or assert nothing, so passing "
-            "is not evidence that the area works. More dangerous than "
-            "'No test', because the suite reports success."
-        ),
-    },
-}
-
-
-def enum_label(value: object, vocabulary: str) -> str:
+# The tables live in `templates/reports/html/i18n/<lang>.json` beside the rest
+# of the page's fixed strings — a label is chrome, not data, so it follows the
+# reader's language rather than the SSOT's. A value with no entry renders as
+# itself: a new enum member shows up raw rather than silently reading as
+# something it is not.
+def enum_label(value: object, vocabulary: str, chrome: dict) -> str:
     """Render a schema enum as the words it stands for."""
     raw = "" if value is None else str(value)
-    return ENUM_LABELS.get(vocabulary, {}).get(raw, raw)
+    return (chrome.get("enum") or {}).get(vocabulary, {}).get(raw, raw)
 
 
-def enum_legend(vocabulary: str) -> list[tuple[str, str]]:
+def enum_legend(vocabulary: str, chrome: dict) -> list[tuple[str, str]]:
     """Pair each label with what it claims, for a legend beside the table.
 
-    Built from the same two tables the cells render from, so a legend cannot
-    drift from the labels it explains.
+    A two-word label fits a table cell but cannot carry a definition, and a
+    reader meeting "Passes without proving" for the first time has nowhere to
+    look it up. Built from the same dictionary the cells render from, so a
+    legend cannot drift from the labels it explains.
     """
-    labels = ENUM_LABELS.get(vocabulary, {})
-    return [(labels.get(value, value), hint) for value, hint in ENUM_HINTS.get(vocabulary, {}).items()]
+    labels = (chrome.get("enum") or {}).get(vocabulary, {})
+    hints = (chrome.get("enumHint") or {}).get(vocabulary, {})
+    return [(labels.get(value, value), hint) for value, hint in hints.items()]
 
 
 def code_evidence(rows: object) -> Markup:

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

@@ -3,12 +3,16 @@ from __future__ import annotations
 
 import hashlib
 import json
+import sys
 from pathlib import Path
 
 import okstra_vendor  # noqa: F401  # registers vendored dependency aliases
 from jinja2 import Environment, FileSystemLoader, StrictUndefined, select_autoescape
 
+from ..final_report_paths import translation_sidecar_path
 from ..final_report_schema import load_schema_for_data, validate
+from ..i18n import HTML_DICTIONARY_REL, load_dictionary, make_jinja_global
+from ..report_translation import overlay
 from ..report_view_artifacts import user_responses_dir_for_report
 from .common import anchor_index
 from .filters import (
@@ -64,6 +68,39 @@ def _report_meta(data: dict, run_meta: HtmlRunMeta) -> dict[str, object]:
     }
 
 
+def _localize(data: dict, data_path: Path) -> tuple[dict, str]:
+    """Apply the translation sidecar for this report's language, if there is one.
+
+    The data.json is the English SSOT and is never rewritten — the sidecar is
+    read here and overlaid onto an in-memory copy, so only this HTML document
+    speaks the reader's language. A pointer the sidecar left untranslated
+    renders in English; that keeps a half-finished translation readable, and
+    the counts are printed because a silently half-empty sidecar otherwise
+    ships looking finished.
+    """
+    lang = str((data.get("meta") or {}).get("reportLanguage") or "en")
+    if lang == "en":
+        return data, lang
+    sidecar_file = translation_sidecar_path(data_path, lang)
+    if not sidecar_file.is_file():
+        sys.stdout.write(
+            f"note: no {lang} translation sidecar at {sidecar_file.name}; "
+            "rendering the English source\n"
+        )
+        return data, lang
+    payload = json.loads(sidecar_file.read_text(encoding="utf-8"))
+    strings = payload.get("strings")
+    if not isinstance(strings, dict):
+        raise HtmlRenderError(f"translation sidecar has no 'strings' object: {sidecar_file}")
+    localized, report = overlay(data, strings)
+    sys.stdout.write(
+        f"translated {report.applied} string(s) into {lang}"
+        f" ({len(report.untranslated)} left in English"
+        f", {len(report.unresolved)} unresolved)\n"
+    )
+    return localized, lang
+
+
 def _html_path(data_path: Path) -> Path:
     suffix = ".data.json"
     if not data_path.name.endswith(suffix):
@@ -84,6 +121,9 @@ def render_v2_html_view(
         raise HtmlRenderError("invalid v2 final-report data: " + "; ".join(errors[:5]))
     if not markdown_path.is_file():
         raise HtmlRenderError(f"v2 markdown sibling not found: {markdown_path}")
+    # Validate the SSOT, then localize — the sidecar carries presentation and
+    # has no say in whether the report is well-formed.
+    data, lang = _localize(data, data_path)
     route = resolve_html_route(run_meta.task_type)
     view = route.view_builder(data)
     root = _templates_root(templates_root)
@@ -92,9 +132,11 @@ def render_v2_html_view(
     # Binding the index here is what lets a template cite an id without
     # threading the index through every macro and call site.
     anchors = anchor_index(data)
+    chrome = load_dictionary(lang, HTML_DICTIONARY_REL)
+    env.globals["t"] = make_jinja_global(chrome)
     env.filters["code_evidence"] = code_evidence
-    env.filters["enum_label"] = enum_label
-    env.filters["enum_legend"] = enum_legend
+    env.filters["enum_label"] = lambda value, vocabulary: enum_label(value, vocabulary, chrome)
+    env.filters["enum_legend"] = lambda vocabulary: enum_legend(vocabulary, chrome)
     env.filters["evidence_refs"] = lambda refs: evidence_refs(refs, anchors)
     env.filters["inline_code"] = lambda value: inline_code(value, anchors)
     env.filters["paragraphs"] = lambda value: paragraphs(value, anchors)