okstra 0.144.0 → 0.145.0

package/runtime/python/okstra_ctl/user_response.py

@@ -3,8 +3,8 @@
 The sidecar format is documented in ``templates/reports/user-response.template.md``
 and produced byte-identically by ``report_views.serialize_user_response`` (Python)
 and ``templates/reports/report.js`` (browser). This module owns the read side of
-the ``## APPROVAL`` block — the implementation wizard consumes it to offer
-"승인 + 옵션 적용" at the approve-confirm step.
+the ``## APPROVAL`` block used by the implementation wizard and the optional
+``## ANALYSIS REVIEW`` block used by analysis reruns.
 """
 from __future__ import annotations
 
@@ -12,6 +12,7 @@ import argparse
 import datetime as dt
 import json
 import re
+import stat
 import sys
 from dataclasses import dataclass
 from pathlib import Path
@@ -31,6 +32,19 @@ from okstra_ctl.clarification_items import (
 
 _APPROVAL_HEADING_RE = re.compile(r"^## APPROVAL\s*$", re.MULTILINE)
 _NEXT_RESPONSE_HEADING_RE = re.compile(r"^## ", re.MULTILINE)
+_ANALYSIS_REVIEW_HEADING_RE = re.compile(r"^## ANALYSIS REVIEW\s*$", re.MULTILINE)
+_ANALYSIS_SIDECAR_HEADING_RE = re.compile(
+    r"^## (?P<filename>user-response-[^\n]+\.md)\s*$", re.MULTILINE
+)
+_YAML_FRONTMATTER_RE = re.compile(
+    r"\A---[ \t]*\r?\n(?P<body>.*?)(?:\r?\n)---[ \t]*(?:\r?\n|\Z)",
+    re.DOTALL,
+)
+_FRONTMATTER_DELIMITER_RE = re.compile(r"^---[ \t]*$", re.MULTILINE)
+
+
+class UserResponseError(ValueError):
+    """Raised when a user-response sidecar violates its supported format."""
 
 
 @dataclass(frozen=True)
@@ -42,6 +56,296 @@ class UserResponseApprovalRecord:
     seq: str
 
 
+@dataclass(frozen=True)
+class AnalysisReviewRecord:
+    """Validated user review of an analysis report."""
+
+    status: str
+    affected_ids: tuple[str, ...]
+    reason: str
+    additional_evidence: str
+    requested_scope_change: str
+    task_key: str
+    task_type: str
+    source_report: str
+    seq: str
+
+
+_ANALYSIS_REVIEW_STATUSES = frozenset({
+    "accepted",
+    "revision-requested",
+    "rejected",
+})
+_ANALYSIS_REPORT_RE = re.compile(
+    r"^final-report-(?P<task_type>project-analysis|feature-analysis|"
+    r"change-impact-analysis)-(?P<seq>\d{3})\.md$"
+)
+
+
+def _quoted_review_value(block: str, key: str) -> str:
+    match = re.search(
+        rf"^- {re.escape(key)}:\s*\n((?:\s*>.*\n?)+)", block, re.MULTILINE
+    )
+    if not match:
+        return ""
+    return "\n".join(
+        re.sub(r"^\s*>\s?", "", line)
+        for line in match.group(1).splitlines()
+    ).strip()
+
+
+def _sidecar_metadata_value(sidecar_text: str, key: str) -> str:
+    frontmatter = _YAML_FRONTMATTER_RE.match(sidecar_text)
+    if frontmatter is None:
+        return ""
+    match = re.search(
+        rf"^{re.escape(key)}:[ \t]*(\S.*?)[ \t]*$",
+        frontmatter.group("body"),
+        re.MULTILINE,
+    )
+    return match.group(1) if match else ""
+
+
+def _nearest_frontmatter_value(
+    sidecar_text: str, key: str, before_offset: int
+) -> str:
+    delimiters = [
+        match
+        for match in _FRONTMATTER_DELIMITER_RE.finditer(sidecar_text)
+        if match.start() < before_offset
+    ]
+    for opening, closing in reversed(list(zip(delimiters, delimiters[1:]))):
+        body = sidecar_text[opening.end():closing.start()]
+        match = re.search(
+            rf"^{re.escape(key)}:[ \t]*(\S.*?)[ \t]*$",
+            body,
+            re.MULTILINE,
+        )
+        if match:
+            return match.group(1)
+    return _sidecar_metadata_value(sidecar_text, key)
+
+
+def _parsed_created_at(value: str) -> dt.datetime | None:
+    if re.fullmatch(
+        r"\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z",
+        value,
+    ) is None:
+        return None
+    try:
+        parsed = dt.datetime.fromisoformat(value[:-1] + "+00:00")
+    except ValueError:
+        return None
+    if parsed.tzinfo is None:
+        return None
+    return parsed.astimezone(dt.timezone.utc)
+
+
+def _nearest_sidecar_filename(sidecar_text: str, before_offset: int) -> str:
+    headings = [
+        match
+        for match in _ANALYSIS_SIDECAR_HEADING_RE.finditer(sidecar_text)
+        if match.start() < before_offset
+    ]
+    return headings[-1].group("filename") if headings else ""
+
+
+def _authoritative_analysis_review_match(
+    sidecar_text: str, matches: list[re.Match[str]]
+) -> re.Match[str]:
+    candidates: list[tuple[dt.datetime, str, int, re.Match[str]]] = []
+    for match in matches:
+        created_at = _parsed_created_at(
+            _nearest_frontmatter_value(sidecar_text, "created-at", match.start())
+        )
+        if created_at is None:
+            continue
+        candidates.append((
+            created_at,
+            _nearest_sidecar_filename(sidecar_text, match.start()),
+            match.start(),
+            match,
+        ))
+    if not candidates:
+        raise UserResponseError(
+            "ANALYSIS REVIEW requires a valid canonical created-at"
+        )
+    return max(candidates, key=lambda candidate: candidate[:3])[3]
+
+
+def parse_analysis_review(sidecar_text: str) -> AnalysisReviewRecord | None:
+    """Parse the bounded ``## ANALYSIS REVIEW`` block from a sidecar.
+
+    A sidecar without this optional block is not a review.  Once the block is
+    present, status and the fields that make a rejection actionable are
+    validated fail-closed.
+    """
+    matches = list(_ANALYSIS_REVIEW_HEADING_RE.finditer(sidecar_text))
+    if not matches:
+        return None
+    match = _authoritative_analysis_review_match(sidecar_text, matches)
+    block = sidecar_text[match.end():]
+    next_heading = _NEXT_RESPONSE_HEADING_RE.search(block)
+    if next_heading:
+        block = block[:next_heading.start()]
+    status = _field(block, "Status")
+    if status not in _ANALYSIS_REVIEW_STATUSES:
+        raise UserResponseError("ANALYSIS REVIEW Status is invalid")
+    affected = _field(block, "Affected-IDs") or ""
+    affected_ids = tuple(item.strip() for item in affected.split(",") if item.strip())
+    reason = _quoted_review_value(block, "Reason")
+    if status in {"revision-requested", "rejected"} and (not affected_ids or not reason):
+        raise UserResponseError(
+            f"ANALYSIS REVIEW {status} requires Affected-IDs and Reason"
+        )
+    return AnalysisReviewRecord(
+        status=status,
+        affected_ids=affected_ids,
+        reason=reason,
+        additional_evidence=_quoted_review_value(block, "Additional-Evidence"),
+        requested_scope_change=_quoted_review_value(block, "Requested-Scope-Change"),
+        task_key=_nearest_frontmatter_value(
+            sidecar_text, "task-key", match.start()
+        ),
+        task_type=_nearest_frontmatter_value(
+            sidecar_text, "task-type", match.start()
+        ),
+        source_report=_nearest_frontmatter_value(
+            sidecar_text, "source-report", match.start()
+        ),
+        seq=_nearest_frontmatter_value(sidecar_text, "seq", match.start()),
+    )
+
+
+def _matching_analysis_review_sidecars(
+    report_path: Path,
+    sidecar_name: re.Pattern[str],
+) -> tuple[Path, tuple[Path, ...]]:
+    run_dir = report_path.parent.parent
+    responses_dir = run_dir / "user-responses"
+    try:
+        responses_mode = responses_dir.lstat().st_mode
+    except FileNotFoundError:
+        return responses_dir, ()
+    except OSError as exc:
+        raise UserResponseError(
+            f"analysis user-responses directory is unreadable under {run_dir}"
+        ) from exc
+    if not stat.S_ISDIR(responses_mode):
+        raise UserResponseError(
+            f"analysis user-responses must be a real directory under {run_dir}"
+        )
+    try:
+        resolved_run_dir = run_dir.resolve(strict=True)
+        resolved_responses_dir = responses_dir.resolve(strict=True)
+    except OSError as exc:
+        raise UserResponseError(
+            f"analysis user-responses directory is unreadable under {run_dir}"
+        ) from exc
+    if resolved_responses_dir != resolved_run_dir / "user-responses":
+        raise UserResponseError(
+            f"analysis user-responses must stay under {resolved_run_dir}"
+        )
+    try:
+        sidecars = tuple(
+            sorted(
+                (
+                    entry
+                    for entry in responses_dir.iterdir()
+                    if sidecar_name.fullmatch(entry.name)
+                ),
+                key=lambda entry: entry.name,
+            )
+        )
+    except OSError as exc:
+        raise UserResponseError(
+            f"analysis user-responses directory is unreadable under {run_dir}"
+        ) from exc
+    return responses_dir, sidecars
+
+
+def _read_analysis_review_sidecar(sidecar: Path, responses_dir: Path) -> str:
+    try:
+        sidecar_mode = sidecar.lstat().st_mode
+        if not stat.S_ISREG(sidecar_mode):
+            raise OSError("not a regular file")
+        resolved = sidecar.resolve(strict=True)
+        if resolved.parent != responses_dir.resolve(strict=True):
+            raise OSError("outside user-responses")
+        return sidecar.read_text(encoding="utf-8")
+    except (OSError, UnicodeError) as exc:
+        raise UserResponseError(
+            "analysis review sidecar must be a readable regular file under "
+            f"{responses_dir}"
+        ) from exc
+
+
+def _analysis_review_matches_with_valid_created_at(
+    sidecar_text: str,
+) -> list[re.Match[str]]:
+    matches = list(_ANALYSIS_REVIEW_HEADING_RE.finditer(sidecar_text))
+    for match in matches:
+        created_at = _nearest_frontmatter_value(
+            sidecar_text, "created-at", match.start()
+        )
+        if _parsed_created_at(created_at) is None:
+            raise UserResponseError(
+                "ANALYSIS REVIEW requires a valid canonical created-at"
+            )
+    return matches
+
+
+def load_authoritative_analysis_review(
+    report_path: Path,
+    *,
+    expected_task_key: str,
+    expected_task_type: str,
+) -> AnalysisReviewRecord | None:
+    """Load the created-at-latest review attached to one analysis report."""
+    report_match = _ANALYSIS_REPORT_RE.fullmatch(report_path.name)
+    if report_match is None:
+        raise UserResponseError("analysis review source is not an analysis report")
+    sidecar_name = re.compile(
+        rf"^user-response-{re.escape(report_match.group('task_type'))}-"
+        rf"{re.escape(report_match.group('seq'))}(?:-.+)?\.md$"
+    )
+    responses_dir, sidecars = _matching_analysis_review_sidecars(
+        report_path, sidecar_name
+    )
+    if not sidecars:
+        return None
+    attached: list[str] = []
+    for sidecar in sidecars:
+        text = _read_analysis_review_sidecar(sidecar, responses_dir)
+        if _analysis_review_matches_with_valid_created_at(text):
+            attached.append(f"\n## {sidecar.name}\n\n{text.strip()}\n")
+    if not attached:
+        raise UserResponseError(
+            "existing review sidecar has no ANALYSIS REVIEW block"
+        )
+    review = parse_analysis_review("".join(attached))
+    if review is None:
+        raise UserResponseError("analysis review sidecar is unreadable")
+    expected_source = (
+        f"runs/{report_match.group('task_type')}/reports/{report_path.name}"
+    )
+    if review.task_key != expected_task_key:
+        raise UserResponseError(
+            "analysis review task-key does not match report taskKey"
+        )
+    if review.task_type != expected_task_type:
+        raise UserResponseError(
+            "analysis review task-type does not match report taskType"
+        )
+    if review.source_report != expected_source:
+        raise UserResponseError(
+            "analysis review source-report does not match report path"
+        )
+    if review.seq != report_match.group("seq"):
+        raise UserResponseError("analysis review seq does not match report runSeq")
+    return review
+
+
 def parse_user_response_approval(
     sidecar_text: str,
 ) -> Optional[UserResponseApprovalRecord]:
@@ -76,7 +380,9 @@ _RESPONSE_HEADING_RE = re.compile(r"^## (?P<id>[A-Za-z][A-Za-z0-9]*-\d+)\s*$", r
 
 
 def _field(block: str, key: str) -> Optional[str]:
-    m = re.search(rf"^- {re.escape(key)}:\s*(\S.*?)\s*$", block, re.MULTILINE)
+    m = re.search(
+        rf"^- {re.escape(key)}:[ \t]*(\S.*?)[ \t]*$", block, re.MULTILINE
+    )
     return m.group(1) if m else None