okstra 0.149.0 → 0.150.0

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)

package/runtime/python/okstra_ctl/report_translation.py

@@ -0,0 +1,440 @@
+"""Which final-report strings a translator may rewrite, and how to apply them.
+
+The data.json is authored in English and is the SSOT for every downstream
+consumer. The human HTML is the one artifact that renders in the reader's
+language, so a translation arrives as a sidecar keyed by JSON Pointer and is
+overlaid at render time. Nothing here mutates the SSOT.
+
+Classification is by leaf key name, and the split is not "prose vs. term" —
+the translator is told to leave a term in English when English reads better.
+The line drawn here is **load-bearing vs. displayed**: a value the renderer
+feeds into a CSS class, a label-table lookup, or an anchor id cannot change
+without breaking the page, so it never reaches the translator. Everything a
+reader merely reads is offered, and the translator decides.
+
+When a key name carries load-bearing values in even one place, it counts as
+structural everywhere. Missing a translation leaves English on the page;
+translating an anchor id breaks the link.
+"""
+from __future__ import annotations
+
+import re
+from typing import Any, Iterator, Mapping, NamedTuple
+
+# Values the renderer reads as text and nothing else.
+PROSE_KEYS = frozenset({
+    "acceptance",
+    "alternativesConsidered",
+    "approach",
+    "approvalDisposition",
+    "approvalEvidence",
+    "behavior",
+    "blastRadius",
+    "blockReason",
+    "blockedReason",
+    "body",
+    "briefEvidence",
+    "carryIn",
+    "causeSummary",
+    "change",
+    "check",
+    "claim",
+    "condition",
+    "confirmingSignal",
+    "conformanceExemption",
+    "consequences",
+    "constraint",
+    "context",
+    "coreReason",
+    "decision",
+    "declinedFixRecommendations",
+    "description",
+    "details",
+    "disagreement",
+    "discrepancy",
+    "disproveWith",
+    "environmentSetup",
+    "escalationTrigger",
+    "evidence",
+    "evidenceRequired",
+    "exemptionReaffirm",
+    "exemptionReason",
+    "exitContract",
+    "exitContractSummary",
+    "expected",
+    "expectedBehaviorAfter",
+    "expectedForm",
+    "expectedOutcome",
+    "expectedResult",
+    "failureHandling",
+    "finalConclusion",
+    "headline",
+    "howToStart",
+    "hypothesis",
+    "item",
+    "justification",
+    "label",
+    "mitigation",
+    "motivation",
+    "name",
+    "need",
+    "nextStep",
+    "noVariationRationale",
+    "notApplicableReason",
+    "note",
+    "observableFailure",
+    "observed",
+    "option",
+    "outcome",
+    "outputSummary",
+    "performed",
+    "planItem",
+    "position",
+    "problem",
+    "question",
+    "rationale",
+    "readyWhen",
+    "reason",
+    "rejectedSummary",
+    "rejectingSignal",
+    "requiredDecision",
+    "requiredWork",
+    "requirement",
+    "resolution",
+    "responsibility",
+    "rolloutCost",
+    "routingRecommendation",
+    "selfFixNote",
+    "stageTitle",
+    "stageValidation",
+    "statement",
+    "suggestedAction",
+    "summary",
+    "supersededStatement",
+    "symptom",
+    "systemInterpretation",
+    "testCaseBoundary",
+    "testCaseFailure",
+    "testCaseSuccess",
+    "testCoverageCost",
+    "text",
+    "title",
+    "topic",
+    "trigger",
+    "triggerSignal",
+    "userChoice",
+    "userInput",
+    "verification",
+    "verificationMethod",
+    "verificationSignal",
+    "workingAssumption",
+})
+
+# Values something other than the reader depends on: a CSS class, a label-table
+# key, an anchor id, a path the reader clicks, a command they paste, or a quote
+# that must stay verbatim to be evidence at all.
+STRUCTURAL_KEYS = frozenset({
+    "action",             # implementation.py: _FILE_ACTIONS lookup key
+    "adapter",
+    "affectedId",
+    "affectedTarget",
+    "area",               # slug-shaped ('scan-coverage')
+    "artifact",
+    "baseBranch",
+    "baseRefSha",
+    "baseSha",
+    "boundary",
+    "branchName",
+    "canonical",
+    "capturedHeadSha",
+    "carriedForwardFromSeq",
+    "carryJson",
+    "clarificationId",
+    "claudeCode",
+    "collectorBranch",
+    "command",
+    "commandOrObservation",
+    "commandOrTest",
+    "commitListQuote",
+    "complexity",
+    "componentId",
+    "confidence",
+    "conformanceTests",
+    "coveredBy",
+    "createdAt",
+    "cycle",
+    "dataStore",
+    "date",
+    "dependsOn",
+    "diffSummaryQuote",
+    "direction",
+    "dispatches",
+    "executorWorktreePath",
+    "existingPrUrl",
+    "externalSystem",
+    "featureId",
+    "field",
+    "file",
+    "files",
+    "followUpPhase",
+    "fromComponentId",
+    "fromTaskKey",
+    "fullSha",
+    "gitDiffStat",
+    "gitStatusShort",
+    "h1c",
+    "h2",
+    "id",
+    "impact",             # 'high' / 'medium' alongside prose
+    "impactKind",
+    "implementationBaseRef",
+    "implementationOption",
+    "independentValidationRerun",
+    "injectedAs",
+    "input",
+    "interfaceKind",
+    "interfaces",
+    "itemId",
+    "kind",               # feature_analysis.py: _FLOW_KINDS lookup key
+    "leadModel",
+    "leadingCauseId",
+    "lens",               # enum_label("lens")
+    "lines",
+    "linkedWork",
+    "match",
+    "model",
+    "newTaskId",
+    "number",
+    "okstraVersion",
+    "output",
+    "outputTail",
+    "owner",
+    "ownerComponentId",
+    "path",
+    "planFile",
+    "planStep",
+    "prepItemId",
+    "project",
+    "projectId",
+    "raw",
+    "rawStat",
+    "readBoundary",
+    "readOnlyCommandLog",
+    "relatedIds",
+    "relation",
+    "replacedInTest",
+    "replacedWith",
+    "reportPath",
+    "requestKind",
+    "requestPath",
+    "requestVerbatim",    # the user's own words, quoted as evidence
+    "requestedValue",
+    "reversibility",
+    "risk",               # tone-{{ row.risk }} class; an enum on ProjectHotspot
+    "role",
+    "rollbackCommand",
+    "runManifest",
+    "runSeq",
+    "scope",              # 'PF-001' alongside prose
+    "sections",
+    "shortSha",
+    "signature",
+    "singleTicket",
+    "skippedWorkers",
+    "sliceValue",
+    "slug",
+    "source",             # enum_label("rejectionSource") and evidence ids
+    "sourceCommit",
+    "sourceFile",
+    "sourceImpactId",
+    "sourceSection",
+    "status",             # CSS class + enum_label("coverage")
+    "styleLintTypecheck",
+    "subject",            # commit subject, must stay verbatim
+    "symbol",
+    "symptomVerbatim",
+    "target",
+    "targetReport",
+    "taskGroup",
+    "taskId",
+    "taskKey",
+    "taskType",
+    "tddEvidence",
+    "tddExemption",
+    "terminal",
+    "toComponentId",
+    "toTaskKey",
+    "url",
+    "verdictTokenQuote",
+    "verifier",
+    "version",
+    "worker",
+    "workerRole",
+    "worktreePath",
+    "writeBoundary",
+})
+
+
+class UnclassifiedKeys(ValueError):
+    """A schema string field belongs to neither set."""
+
+
+# A key name says what a field is *for*; these say what one value actually is.
+# `evidence` is the largest prose bucket in a real report and also holds bare
+# `src/server.ts:33` citations — the key cannot separate them, the value can.
+_MACHINE_CHARS = re.compile(r"^[A-Za-z0-9_.:@/\\#-]+$")
+_LOWER_TOKEN = re.compile(r"^[a-z][a-z0-9]*([-_][a-z0-9]+)*$")
+_FILE_EXTENSION = re.compile(r"\.[A-Za-z0-9]{1,6}$")
+_LINE_NUMBER = re.compile(r":\d+$")
+
+
+def is_translatable_value(text: str) -> bool:
+    """Whether one value is prose rather than a citation or a token.
+
+    Anything with whitespace is prose. A single run of ASCII path characters
+    is not, once it carries a directory separator, a file extension, or a line
+    number — and neither is a bare lowercase token, which is how an enum reads.
+    """
+    value = text.strip()
+    if not value:
+        return False
+    if any(char.isspace() for char in value):
+        return True
+    if not _MACHINE_CHARS.match(value):
+        return True
+    if "/" in value or "\\" in value:
+        return False
+    if _FILE_EXTENSION.search(value) or _LINE_NUMBER.search(value):
+        return False
+    return _LOWER_TOKEN.match(value) is None
+
+
+def escape_token(token: str) -> str:
+    """Escape one JSON Pointer reference token (RFC 6901)."""
+    return token.replace("~", "~0").replace("/", "~1")
+
+
+def unescape_token(token: str) -> str:
+    return token.replace("~1", "/").replace("~0", "~")
+
+
+def _walk(node: Any, pointer: str, key: str) -> Iterator[tuple[str, str]]:
+    if isinstance(node, Mapping):
+        for child_key, value in node.items():
+            yield from _walk(value, f"{pointer}/{escape_token(str(child_key))}", str(child_key))
+    elif isinstance(node, (list, tuple)):
+        for index, value in enumerate(node):
+            # An array element inherits the key that named the array, so
+            # `evidence: [...]` translates each entry.
+            yield from _walk(value, f"{pointer}/{index}", key)
+    elif isinstance(node, str) and key in PROSE_KEYS and is_translatable_value(node):
+        yield pointer, node
+
+
+def extract(data: Mapping[str, Any]) -> dict[str, str]:
+    """Map every translatable pointer to the English text at it.
+
+    The translator fills in this map rather than authoring pointers, so a
+    sidecar cannot cite a path the document does not have.
+    """
+    return dict(_walk(data, "", ""))
+
+
+class OverlayReport(NamedTuple):
+    applied: int
+    # Pointers the extractor offered that the sidecar left untranslated. They
+    # render in English — a partial translation is a readable page, not a
+    # failure — but a silent fallback is how a half-empty sidecar ships
+    # unnoticed, so the count is reported.
+    untranslated: tuple[str, ...]
+    # Pointers the sidecar carries that do not resolve to a string here. A
+    # sidecar written against a different report.
+    unresolved: tuple[str, ...]
+
+
+def _resolve_parent(data: Any, pointer: str) -> tuple[Any, str | int] | None:
+    tokens = [unescape_token(t) for t in pointer.split("/")[1:]]
+    if not tokens:
+        return None
+    node = data
+    for token in tokens[:-1]:
+        if isinstance(node, Mapping) and token in node:
+            node = node[token]
+        elif isinstance(node, list) and token.isdigit() and int(token) < len(node):
+            node = node[int(token)]
+        else:
+            return None
+    last = tokens[-1]
+    if isinstance(node, Mapping) and isinstance(node.get(last), str):
+        return node, last
+    if isinstance(node, list) and last.isdigit() and int(last) < len(node):
+        return (node, int(last)) if isinstance(node[int(last)], str) else None
+    return None
+
+
+def overlay(
+    data: Mapping[str, Any], strings: Mapping[str, str]
+) -> tuple[dict[str, Any], OverlayReport]:
+    """Return a deep copy of ``data`` with the sidecar's strings substituted."""
+    import copy
+
+    out = copy.deepcopy(dict(data))
+    applied = 0
+    unresolved: list[str] = []
+    for pointer, text in strings.items():
+        target = _resolve_parent(out, pointer)
+        if target is None or not isinstance(text, str) or not text:
+            unresolved.append(pointer)
+            continue
+        parent, key = target
+        parent[key] = text
+        applied += 1
+    untranslated = tuple(sorted(set(extract(data)) - set(strings)))
+    return out, OverlayReport(applied, untranslated, tuple(sorted(unresolved)))
+
+
+def _schema_string_keys(schema: Mapping[str, Any], *, enums: bool) -> set[str]:
+    found: set[str] = set()
+
+    def walk(node: Any) -> None:
+        if not isinstance(node, Mapping):
+            return
+        if node.get("type") == "object":
+            for key, child in (node.get("properties") or {}).items():
+                if isinstance(child, Mapping) and child.get("type") == "string":
+                    if ("enum" in child) == enums:
+                        found.add(str(key))
+                elif isinstance(child, Mapping) and enums and "enum" in child:
+                    # An enum with no declared type is still an enum.
+                    found.add(str(key))
+                walk(child)
+        elif node.get("type") == "array":
+            walk(node.get("items") or {})
+        for combinator in ("oneOf", "anyOf", "allOf"):
+            for branch in node.get(combinator) or []:
+                walk(branch)
+
+    for definition in (schema.get("$defs") or {}).values():
+        walk(definition)
+    walk(schema)
+    return found
+
+
+def schema_string_keys(schema: Mapping[str, Any]) -> set[str]:
+    """Every leaf key in the schema whose value is a free-form string.
+
+    The drift guard compares this against the two sets above, so adding a
+    report field forces a decision about whether a translator may touch it.
+    """
+    return _schema_string_keys(schema, enums=False)
+
+
+def schema_enum_keys(schema: Mapping[str, Any]) -> set[str]:
+    """Every leaf key the schema constrains to an enum, anywhere.
+
+    A name can be an enum in one definition and free prose in another —
+    `risk` is `high|medium|low` on a hotspot and a sentence on a risk row.
+    The renderer reaches for the same name either way (`tone-{{ row.risk }}`),
+    so one enum occurrence makes the name structural everywhere.
+    """
+    return _schema_string_keys(schema, enums=True)