okstra 0.186.7 → 0.187.0

package/runtime/python/okstra_ctl/code_review_target.py

@@ -19,11 +19,14 @@ from pathlib import Path
 from okstra_project import (
     ResolverError,
     StateError,
-    code_review_target_snapshot,
     resolve_project_root,
+    resolve_task_identity,
 )
 
+from . import code_review_paths, stage_targets, worktree_registry
 from .code_review_paths import branch_review_dir, next_branch_review
+from .paths import RunRef
+from .stage_map import StageMapError, load_latest_plan_stage_map
 from .fixed_text import line
 
 DEFAULT_BRANCH_CANDIDATES = ("main", "master")
@@ -95,10 +98,29 @@ def _branch_snapshot(repo: Path, branch: str, base: str, review_date: str) -> di
     }
 
 
+_CLI_EPILOG = r"""Usage:
+  okstra code-review target --task-key <k> --stage <N> [--project-root <dir>] [--cwd <dir>] --json
+  okstra code-review target --branch <name> [--base <ref>] [--date <YYYY-MM-DD>] [--project-root <dir>] --json
+
+Output: JSON { ok, mode, worktreePath, branch, baseCommit, headCommit,
+reviewPath, round }. Stage mode reads the base commit from the stage
+registry row; branch mode falls back to the merge-base with the default
+branch. An empty worktreePath means the review reads the branch ref
+instead of a checked-out tree. This is read-only — it never creates
+directories or files.
+"""
+
+
 def _build_parser() -> argparse.ArgumentParser:
     parser = argparse.ArgumentParser(
+        epilog=_CLI_EPILOG,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        prog="okstra code-review",
         description="Resolve a code review's diff range and result file path."
     )
+    # 서브커맨드는 하나뿐이지만 공개 명령이 `okstra code-review target` 이므로
+    # 그 토큰을 파서가 직접 받는다.
+    parser.add_argument("command", choices=("target",))
     parser.add_argument("--task-key", default="", help="project-id:task-group:task-id")
     parser.add_argument("--stage", type=int, default=0, help="stage number to review")
     parser.add_argument("--branch", default="", help="branch to review")
@@ -174,5 +196,145 @@ def main(argv: list[str] | None = None) -> int:
     return 0
 
 
+# ---- stage 모드 해소 -------------------------------------------------------
+# 모듈 도크스트링이 "stage 규칙은 code_review_target_snapshot 이 소유한다" 고
+# 적어 두었지만 실제 함수는 okstra_project.state 에 있었고, 거기서 okstra_ctl 을
+# 함수 본문에서 지연 import 했다. 선언대로 소유자를 여기로 옮긴다.
+# 옮기면서 state.py 가 따로 갖고 있던 _git_out 사본(본문 동일)은 이 파일의
+# 것으로 합쳐진다.
+
+def code_review_target_snapshot(
+    project_root: Path, task_key: str, stage: int
+) -> dict:
+    """stage 코드 리뷰가 무엇을 읽고 결과를 어디에 쓰는지 해소한다.
+
+    stage_map_read_side_snapshot 과 같은 결: caller 는 registry 행도, run-root
+    레이아웃도, stage base 규칙도 보지 않는다. stage_targets 의
+    StageTargetError 도 StateError 로 바꿔 던진다 — caller 가 그 예외를 잡으려고
+    okstra_ctl 을 import 하지 않도록.
+
+    base 는 stage worktree 를 만들 때 registry 행에 적힌 `base_ref` 다 — 그
+    stage 가 실제로 갈라져 나온 커밋. 리뷰 시점에 규칙으로 다시 계산하면
+    표류한다: 다중의존 stage 는 오늘의 task-key worktree HEAD 를 받게 되어
+    whole-task final-verification 이 stage 들을 병합한 뒤에는 base..head 구간이
+    비거나 뒤집히고, 단일의존 stage 는 선행 stage 가 재실행되면 어긋난다.
+    """
+    identity = resolve_task_identity(project_root, task_key)
+    task_root = Path(identity["taskRoot"])
+    try:
+        stage_snapshot = load_latest_plan_stage_map(task_root)
+    except StageMapError as exc:
+        raise StateError(str(exc), stage=exc.code) from exc
+    if stage_snapshot.state != "ready":
+        raise StateError(
+            "implementation-planning Stage Map is missing",
+            stage="missing",
+        )
+    stages = stage_snapshot.stages
+    selected = next((s for s in stages if s["stage_number"] == stage), None)
+    if selected is None:
+        raise StateError(
+            f"stage {stage} is not in the Stage Map for {task_key}",
+            stage="stage_missing",
+        )
+
+    coords = (identity["projectId"], identity["taskGroup"], identity["taskId"])
+    stage_row = worktree_registry.get_stage_row(*coords, stage) or {}
+    worktree_view = _stage_worktree_view(project_root, stage_row, stage)
+    base_commit = stage_row.get("base_ref") or _legacy_stage_base_commit(
+        identity, stages, selected
+    )
+    review_path, round_no = code_review_paths.next_stage_review(
+        code_review_paths.stage_review_dir(
+            project_root, identity["taskGroup"], identity["taskId"]
+        ),
+        stage,
+    )
+    return {
+        "mode": "stage",
+        "taskKey": identity["taskKey"],
+        "taskRoot": identity["taskRoot"],
+        "stage": stage,
+        **worktree_view,
+        "baseCommit": base_commit,
+        "reviewPath": str(review_path),
+        "round": round_no,
+    }
+
+
+def _legacy_stage_base_commit(
+    identity: dict, stages: list[dict], selected: dict
+) -> str:
+    """`base_ref` 를 남기지 않은 옛 registry 행의 base 를 규칙에서 되살린다.
+
+    provision 이 base_ref 를 기록하기 전에 만들어진 stage 행에만 쓰인다. 규칙
+    자체는 stage_targets 가 소유하며 여기서 다시 유도하지 않는다.
+    """
+    coords = (identity["projectId"], identity["taskGroup"], identity["taskId"])
+    plan_run_root = RunRef.from_task_root(
+        Path(identity["taskRoot"]), "implementation-planning"
+    ).run_dir
+    lifecycle = stage_targets.read_stage_lifecycle_snapshot(
+        stages, plan_run_root, recover_from_carry=True
+    )
+    # The anchor and the multi-dep candidate base must come from the task-key
+    # worktree HEAD, where stage work accumulates — not from the invocation
+    # cwd, which may sit on an older or unrelated commit.
+    task_entry = worktree_registry.lookup(*coords)
+    task_worktree = Path(
+        (task_entry.worktree_path if task_entry else "") or identity["projectRoot"]
+    )
+    anchor = worktree_registry.get_implementation_base(*coords) or ""
+    try:
+        return stage_targets.resolve_stage_base_commit(
+            selected,
+            lifecycle.done_rows,
+            anchor_base_commit=anchor,
+            candidate_base=_git_out(task_worktree, "rev-parse", "HEAD"),
+            project_root=task_worktree,
+            plan_run_root=plan_run_root,
+        )
+    except stage_targets.StageTargetError as exc:
+        raise StateError(
+            f"stage {selected['stage_number']} has no recorded base_ref and its "
+            f"base could not be derived: {exc}",
+            stage="stage_base_unresolved",
+        ) from exc
+
+
+def _stage_worktree_view(project_root: Path, stage_row: dict, stage: int) -> dict:
+    """한 stage 의 worktree 경로 / 브랜치 / head 커밋.
+
+    철거된 stage worktree 는 오류가 아니다: whole-task final-verification 이
+    디렉터리를 지워도 브랜치는 남고, 리뷰가 필요한 커밋은 그 브랜치에 그대로
+    있다.
+    """
+    branch = stage_row.get("branch") or ""
+    if not branch:
+        raise StateError(
+            f"stage {stage} has no registry branch — review it in branch mode",
+            stage="stage_branch_missing",
+        )
+    worktree_path = ""
+    if stage_row.get("status") == "active" and stage_row.get("worktree_path"):
+        candidate = Path(stage_row["worktree_path"])
+        if candidate.is_dir():
+            worktree_path = str(candidate)
+    head_source = Path(worktree_path) if worktree_path else Path(project_root)
+    head_ref = "HEAD" if worktree_path else branch
+    head_commit = _git_out(head_source, "rev-parse", head_ref)
+    if not head_commit:
+        raise StateError(
+            f"stage {stage} head could not be resolved: branch {branch!r} is "
+            f"not readable from {head_source}",
+            stage="stage_head_unresolved",
+        )
+    return {
+        "worktreePath": worktree_path,
+        "branch": branch,
+        "headCommit": head_commit,
+    }
+
+
 if __name__ == "__main__":
     raise SystemExit(main(sys.argv[1:]))

package/runtime/python/okstra_ctl/conformance.py

@@ -48,6 +48,29 @@ def normalize_conformance_script(script: str) -> str:
     return script[len(prefix):] if script.startswith(prefix) else script
 
 
+# 계획 서사의 정본 줄은 `Conformance tests: stage-<N> — <나머지>` 이고 data.json
+# `conformanceTests` 는 그 나머지만 담는다. writer 가 `stage-<N> — ` 라벨까지
+# 옮겨 적는 실측 실패가 있어(dev-10341 stage 1) 조립이 게시 전에 이 라벨을
+# 뗀다. 파서(`parse_conformance_tests`)는 라벨을 용인하지 않는다 — 용인하면
+# 정본 형식이 두 개가 된다.
+_STAGE_DECLARATION_LABEL_RE = re.compile(
+    r"^stage-(?P<stage>[1-9]\d*)[ \t]+[—–-][ \t]+"
+)
+
+
+def strip_stage_declaration_label(stage: int, value: str) -> str:
+    """자기 stage 의 `stage-<N> — ` 라벨 접두를 뗀 나머지를 돌려준다.
+
+    라벨이 없거나 다른 stage 번호를 달고 있으면 원문을 그대로 둔다 — 그런 값은
+    뒤따르는 검증이 판정할 몫이다.
+    """
+    stripped = value.strip()
+    match = _STAGE_DECLARATION_LABEL_RE.match(stripped)
+    if match is None or int(match.group("stage")) != stage:
+        return value
+    return stripped[match.end():]
+
+
 def missing_declared_scripts(entries: object, task_root: Path) -> list[str]:
     """승인 계획이 가리키는 script 파일이 task_root 아래에 없으면 오류.