okstra 0.152.0 → 0.154.0

package/runtime/python/okstra_ctl/mutation_probe.py

@@ -61,16 +61,22 @@ branches and would pass by falling between them.
 
 `ADAPTERS` is keyed by the `self_mock_signals.EXT_TO_LANG` vocabulary — the same
 lang names gate A resolves a changed file to — so both gates answer to one set
-of language keys: `ts_js` (Stryker), `rust` (cargo-mutants), and `java`/`kotlin`
-(PIT, whose diff scoping is not wired up yet — see `PitAdapter`).
+of language keys: `ts_js` (Stryker), `python` (Cosmic Ray), `rust`
+(cargo-mutants), and `java`/`kotlin` (PIT, whose diff scoping is not wired up
+yet — see `PitAdapter`).
 """
 from __future__ import annotations
 
+import fnmatch
 import json
+import os
 import re
 import shutil
+import stat
 import subprocess
 import sys
+import tempfile
+import tomllib
 from pathlib import Path
 from typing import NamedTuple, Protocol
 
@@ -413,6 +419,414 @@ class StrykerAdapter:
             return None
 
 
+COSMIC_RAY_CONFIG_PATH = Path("cosmic-ray.toml")
+
+_COSMIC_WORKER_OUTCOMES = (
+    "normal",
+    "abnormal",
+    "exception",
+    "no-test",
+    "skipped",
+)
+_COSMIC_TEST_OUTCOMES = ("killed", "survived", "incompetent", None)
+_COSMIC_CONCLUSIVE = ("killed", "survived")
+_COSMIC_SESSION_FAILURES = (
+    "init-failed",
+    "baseline-failed",
+    "exec-failed",
+    "dump-failed",
+)
+
+
+class SourceState(NamedTuple):
+    """Bytes and permissions Cosmic Ray must leave unchanged."""
+
+    data: bytes
+    mode: int
+
+
+class CosmicRayScope(NamedTuple):
+    """Validated configuration and every Python source it may mutate."""
+
+    config_path: Path
+    sources: tuple[Path, ...]
+
+
+class CosmicRayConfig(NamedTuple):
+    """The source roots and exclusions declared by ``cosmic-ray.toml``."""
+
+    module_paths: tuple[Path, ...]
+    excluded_patterns: tuple[str, ...]
+
+
+class CosmicRaySession(NamedTuple):
+    """The external CLI's dump, or the command that prevented one."""
+
+    dump_text: str | None
+    failure_reason: str | None
+
+
+class CosmicRayScopeError(ValueError):
+    """A stable unsupported reason for an unsafe or incomplete config scope."""
+
+    def __init__(self, reason: str):
+        super().__init__(reason)
+        self.reason = reason
+
+
+def _cosmic_ray_executable(worktree: Path | None) -> Path | None:
+    """Find an installed Cosmic Ray executable without starting a process."""
+    if worktree is None:
+        return None
+    root = Path(worktree)
+    local_paths = (
+        Path(".venv/bin/cosmic-ray"),
+        Path("venv/bin/cosmic-ray"),
+        Path(".venv/Scripts/cosmic-ray.exe"),
+        Path("venv/Scripts/cosmic-ray.exe"),
+    )
+    for relative in local_paths:
+        candidate = root / relative
+        if candidate.is_file() and os.access(candidate, os.X_OK):
+            return candidate
+    found = shutil.which("cosmic-ray")
+    return Path(found) if found else None
+
+
+def _is_within(path: Path, parent: Path) -> bool:
+    try:
+        path.relative_to(parent)
+        return True
+    except ValueError:
+        return False
+
+
+def _cosmic_config(config_path: Path, root: Path) -> CosmicRayConfig:
+    try:
+        data = tomllib.loads(config_path.read_text(encoding="utf-8"))
+    except (OSError, tomllib.TOMLDecodeError) as exc:
+        raise CosmicRayScopeError("config-unreadable") from exc
+    config = data.get("cosmic-ray")
+    raw = config.get("module-path") if isinstance(config, dict) else None
+    values = [raw] if isinstance(raw, str) else raw
+    if not isinstance(values, list) or not values:
+        raise CosmicRayScopeError("config-unreadable")
+    if any(not isinstance(value, str) or not value.strip() for value in values):
+        raise CosmicRayScopeError("config-unreadable")
+    paths = tuple(
+        (root / value).resolve()
+        if not Path(value).is_absolute()
+        else Path(value).resolve()
+        for value in values
+    )
+    if any(not _is_within(path, root) for path in paths):
+        raise CosmicRayScopeError("config-unreadable")
+    exclusions: list[str] = []
+    for key in ("excluded-modules", "exclude-modules"):
+        raw_exclusions = config.get(key, [])
+        if not isinstance(raw_exclusions, list) or any(
+            not isinstance(pattern, str) or not pattern.strip()
+            for pattern in raw_exclusions
+        ):
+            raise CosmicRayScopeError("config-unreadable")
+        exclusions.extend(raw_exclusions)
+    return CosmicRayConfig(paths, tuple(exclusions))
+
+
+def _cosmic_target_is_excluded(
+    target: Path,
+    root: Path,
+    patterns: tuple[str, ...],
+) -> bool:
+    relative = target.relative_to(root).as_posix()
+    return any(
+        fnmatch.fnmatchcase(relative, pattern) or Path(relative).match(pattern)
+        for pattern in patterns
+    )
+
+
+def _configured_cosmic_sources(
+    module_paths: tuple[Path, ...],
+    root: Path,
+) -> tuple[Path, ...]:
+    sources: set[Path] = set()
+    for module_path in module_paths:
+        if module_path.is_file() and module_path.suffix == ".py":
+            candidates = (module_path,)
+        elif module_path.is_dir():
+            candidates = tuple(module_path.rglob("*.py"))
+        else:
+            raise CosmicRayScopeError("config-unreadable")
+        for candidate in candidates:
+            if candidate.is_symlink():
+                raise CosmicRayScopeError("config-unreadable")
+            resolved = candidate.resolve()
+            if not _is_within(resolved, root) or not resolved.is_file():
+                raise CosmicRayScopeError("config-unreadable")
+            sources.add(resolved)
+    return tuple(sorted(sources))
+
+
+def _read_cosmic_ray_scope(worktree: Path, targets: list[Path]) -> CosmicRayScope:
+    root = Path(worktree).resolve()
+    config_path = root / COSMIC_RAY_CONFIG_PATH
+    config = _cosmic_config(config_path, root)
+    resolved_targets = tuple(
+        (root / target).resolve() if not target.is_absolute() else target.resolve()
+        for target in targets
+    )
+    if any(
+        not _is_within(target, root)
+        or _cosmic_target_is_excluded(target, root, config.excluded_patterns)
+        for target in resolved_targets
+    ):
+        raise CosmicRayScopeError("config-target-mismatch")
+    if any(
+        not any(
+            target == module_path
+            or (module_path.is_dir() and _is_within(target, module_path))
+            for module_path in config.module_paths
+        )
+        for target in resolved_targets
+    ):
+        raise CosmicRayScopeError("config-target-mismatch")
+    sources = _configured_cosmic_sources(config.module_paths, root)
+    if any(target not in sources for target in resolved_targets):
+        raise CosmicRayScopeError("config-target-mismatch")
+    return CosmicRayScope(config_path, sources)
+
+
+def _snapshot_source_state(sources: tuple[Path, ...]) -> dict[Path, SourceState]:
+    return {
+        path: SourceState(
+            path.read_bytes(),
+            stat.S_IMODE(path.stat(follow_symlinks=False).st_mode),
+        )
+        for path in sources
+    }
+
+
+def _restore_source_state(states: dict[Path, SourceState]) -> bool:
+    restored = True
+    for path, expected in states.items():
+        try:
+            if path.is_symlink() or (path.exists() and not path.is_file()):
+                restored = False
+                continue
+            if not path.exists() or path.read_bytes() != expected.data:
+                path.write_bytes(expected.data)
+            path.chmod(expected.mode)
+            actual = SourceState(
+                path.read_bytes(),
+                stat.S_IMODE(path.stat(follow_symlinks=False).st_mode),
+            )
+            restored = restored and actual == expected
+        except OSError:
+            restored = False
+    return restored
+
+
+def _run_cosmic_ray_session(
+    executable: Path,
+    config_path: Path,
+    session_path: Path,
+    worktree: Path,
+) -> CosmicRaySession:
+    root = Path(worktree)
+    try:
+        config_arg = str(config_path.relative_to(root))
+    except ValueError:
+        config_arg = str(config_path)
+    commands = (
+        ("init", [str(executable), "init", config_arg, str(session_path)]),
+        (
+            "baseline",
+            [str(executable), "baseline", "--report", config_arg, str(session_path)],
+        ),
+        ("exec", [str(executable), "exec", config_arg, str(session_path)]),
+        ("dump", [str(executable), "dump", str(session_path)]),
+    )
+    for verb, argv in commands:
+        try:
+            completed = subprocess.run(
+                argv,
+                cwd=str(root),
+                capture_output=True,
+                text=True,
+                check=False,
+            )
+        except OSError:
+            return CosmicRaySession(None, f"{verb}-failed")
+        if completed.returncode != 0:
+            return CosmicRaySession(None, f"{verb}-failed")
+        if verb == "dump":
+            return CosmicRaySession(completed.stdout, None)
+    return CosmicRaySession(None, "dump-failed")
+
+
+def _cosmic_diff_file(diff: object, worktree: Path) -> str | None:
+    if not isinstance(diff, list) or any(not isinstance(line, str) for line in diff):
+        return None
+    new_paths = [line[4:].split("\t", 1)[0] for line in diff if line.startswith("+++ ")]
+    if len(new_paths) != 1 or new_paths[0] == "/dev/null":
+        return None
+    raw = new_paths[0]
+    if raw.startswith("b/"):
+        raw = raw[2:]
+    candidate = Path(raw)
+    root = Path(worktree).resolve()
+    if candidate.is_absolute():
+        resolved = candidate.resolve()
+    else:
+        if ".." in candidate.parts:
+            return None
+        absolute_style = (Path("/") / candidate).resolve()
+        resolved = (
+            absolute_style if _is_within(absolute_style, root) else root / candidate
+        )
+    if not _is_within(resolved, root):
+        return None
+    return str(resolved.relative_to(root))
+
+
+def _parse_cosmic_ray_dump(
+    dump_text: str,
+    diff_path: Path | None,
+    worktree: Path,
+) -> ParsedReport | None:
+    scope = read_diff(diff_path)
+    if scope is None:
+        return None
+    survivors: list[dict] = []
+    observed = 0
+    conclusive = 0
+    for raw in dump_text.splitlines():
+        if not raw.strip():
+            continue
+        try:
+            row = json.loads(raw)
+        except json.JSONDecodeError:
+            return None
+        if not isinstance(row, dict):
+            return None
+        worker = row.get("worker_outcome")
+        outcome = row.get("test_outcome")
+        file = _cosmic_diff_file(row.get("diff"), worktree)
+        line = _coerce_line(row.get("line_number"))
+        operator = row.get("operator")
+        occurrence = row.get("occurrence")
+        if (
+            worker not in _COSMIC_WORKER_OUTCOMES
+            or outcome not in _COSMIC_TEST_OUTCOMES
+        ):
+            return None
+        if worker == "normal" and outcome is None:
+            return None
+        if file is None or line is None or line < 1:
+            return None
+        if not isinstance(operator, str) or not operator.strip():
+            return None
+        if not isinstance(occurrence, int) or isinstance(occurrence, bool):
+            return None
+        if line not in scope.touched.get(selfmock_path_key(file), ()):
+            continue
+        observed += 1
+        if worker == "normal" and outcome in _COSMIC_CONCLUSIVE:
+            conclusive += 1
+        if worker == "normal" and outcome == "survived":
+            survivors.append(
+                {
+                    "file": file,
+                    "line": line,
+                    "mutant": f"{operator}#{occurrence}",
+                    "status": outcome,
+                }
+            )
+    return ParsedReport(survivors, conclusive, observed)
+
+
+def _cosmic_session_verdict(
+    session: CosmicRaySession,
+    diff_path: Path | None,
+    worktree: Path,
+    tool: str,
+) -> ProbeResult:
+    if not isinstance(session, CosmicRaySession):
+        return unsupported("report-unparsed", tool=tool)
+    if session.failure_reason is not None:
+        if session.failure_reason not in _COSMIC_SESSION_FAILURES:
+            return unsupported("report-unparsed", tool=tool)
+        return unsupported(session.failure_reason, tool=tool)
+    if not isinstance(session.dump_text, str):
+        return unsupported("report-unparsed", tool=tool)
+    parsed = _parse_cosmic_ray_dump(session.dump_text, diff_path, worktree)
+    if parsed is None:
+        return unsupported("report-unparsed", tool=tool)
+    if parsed.observed == 0:
+        return unsupported("no-mutable-changed-lines", tool=tool)
+    return _verdict_from_parsed(parsed, diff_path, worktree, tool)
+
+
+class CosmicRayAdapter:
+    """Gate B for Python, wrapping an explicitly configured Cosmic Ray CLI."""
+
+    name = "cosmic-ray"
+
+    def __init__(self, runner=_run_cosmic_ray_session):
+        self._runner = runner
+
+    def is_declared(self, worktree: Path | None) -> bool:
+        if worktree is None:
+            return False
+        root = Path(worktree)
+        return (root / COSMIC_RAY_CONFIG_PATH).is_file() and (
+            _cosmic_ray_executable(root) is not None
+        )
+
+    def run(
+        self,
+        targets: list[Path],
+        diff_path: Path | None,
+        worktree: Path | None,
+    ) -> ProbeResult:
+        if worktree is None:
+            return unsupported("config-unreadable", tool=self.name)
+        root = Path(worktree)
+        executable = _cosmic_ray_executable(root)
+        if executable is None:
+            return unsupported("tool-not-declared", tool=self.name)
+        try:
+            scope = _read_cosmic_ray_scope(root, targets)
+            states = _snapshot_source_state(scope.sources)
+        except CosmicRayScopeError as exc:
+            return unsupported(exc.reason, tool=self.name)
+        except OSError:
+            return unsupported("source-integrity-failed", tool=self.name)
+        result: ProbeResult
+        try:
+            with tempfile.TemporaryDirectory(prefix="okstra-cosmic-ray-") as temp_dir:
+                session_path = Path(temp_dir) / "session.sqlite"
+                session = self._runner(
+                    executable,
+                    scope.config_path,
+                    session_path,
+                    root,
+                )
+                result = _cosmic_session_verdict(
+                    session,
+                    diff_path,
+                    root,
+                    self.name,
+                )
+        except OSError:
+            result = unsupported("exec-failed", tool=self.name)
+        finally:
+            sources_restored = _restore_source_state(states)
+        if not sources_restored:
+            return unsupported("source-integrity-failed", tool=self.name)
+        return result
+
+
 CARGO_OUTCOMES_PATH = Path("mutants.out/outcomes.json")
 
 # cargo-mutants' own vocabulary: `caught` (a test failed, good), `missed` (no
@@ -665,6 +1079,7 @@ class PitAdapter:
 _PIT = PitAdapter()
 ADAPTERS: dict[str, Adapter] = {
     "ts_js": StrykerAdapter(),
+    "python": CosmicRayAdapter(),
     "rust": CargoMutantsAdapter(),
     "java": _PIT,
     "kotlin": _PIT,
@@ -1107,6 +1522,7 @@ CAPABILITY_GAP_REASONS = frozenset(
 NOTHING_TO_VERIFY_REASONS = frozenset(
     {
         "no-mutants-generated",
+        "no-mutable-changed-lines",
         "diff-adds-no-line",
     }
 )
@@ -1127,6 +1543,13 @@ INTEGRITY_INSPECTION_REASONS = frozenset(
         "report-unparsed",
         "adapter-malformed-status",
         "no-conclusive-mutants",
+        "config-unreadable",
+        "config-target-mismatch",
+        "init-failed",
+        "baseline-failed",
+        "exec-failed",
+        "dump-failed",
+        "source-integrity-failed",
     }
 )
 

package/runtime/python/okstra_ctl/plan_run_root.py

@@ -26,6 +26,17 @@ class PlanRun(NamedTuple):
     approved_plan_path: str
 
 
+def list_implementation_planning_reports(reports_dir: Path) -> list[Path]:
+    """Return numbered implementation-planning reports in latest-first order."""
+    numbered: list[tuple[int, Path]] = []
+    for report in reports_dir.glob("final-report-implementation-planning-*.md"):
+        match = _FINAL_REPORT_RE.fullmatch(report.name)
+        if match:
+            numbered.append((int(match.group(1)), report))
+    numbered.sort(key=lambda item: item[0], reverse=True)
+    return [report for _, report in numbered]
+
+
 def plan_run_root_from_approved_plan(approved_plan_path: str | Path) -> Path:
     """approved-plan(final-report) 경로에서 plan_run_root 를 역산한다.
 
@@ -58,21 +69,17 @@ def resolve_plan_run_root_by_task_key(
             f"({reports_dir} 없음). 먼저 implementation-planning 을 완료하거나 "
             "approved-plan 경로를 직접 지정하세요."
         )
-    candidates: list[tuple[int, Path, Path]] = []
-    for report in reports_dir.glob("final-report-implementation-planning-*.md"):
-        m = _FINAL_REPORT_RE.search(report.name)
-        if not m:
-            continue
+    candidates: list[tuple[Path, Path]] = []
+    for report in list_implementation_planning_reports(reports_dir):
         run_root = plan_run_root_from_approved_plan(report)
         done = [r for r in read_consumers(run_root) if r.get("status") == "done"]
         if done:
-            candidates.append((int(m.group(1)), run_root, report))
+            candidates.append((run_root, report))
     if not candidates:
         raise PrepareError(
             "container up: done 상태의 implementation-planning run 이 없습니다. "
             "stage 를 완료(implementation done)한 뒤 다시 시도하거나 approved-plan "
             "경로를 직접 지정하세요."
         )
-    candidates.sort(key=lambda c: c[0])
-    _, run_root, report = candidates[-1]
+    run_root, report = candidates[0]
     return PlanRun(run_root=run_root, approved_plan_path=str(report))

package/runtime/python/okstra_ctl/run.py

@@ -15,7 +15,6 @@ state passing, and are read once at the start.
 """
 from __future__ import annotations
 
-import importlib.util
 import hashlib
 import json
 import os
@@ -475,62 +474,17 @@ def _validate_stage_structure(plan_path: str) -> None:
 RUN_STEP_BUDGET = _stage_targets.RUN_STEP_BUDGET
 
 
-def _stage_map_reject_detail(stages, errs):
-    """빈/손상 Stage Map 의 거부 사유 문자열을 돌려준다. 정상이면 None.
-
-    빈/손상 Stage Map 을 흘려보내면 whole-task 완료 게이트
-    (`_resolve_whole_task_target`의 `for stage in stage_map`)가 0회 순회로 vacuous
-    통과해 미완 task 를 '완성'으로 배포·검증한다. 빈 파싱(heading rename·표 손상)과
-    stage 번호 비단조(중간 행 누락 → S2)의 판정을 한 곳에 모아, run.py 의 prepare
-    게이트와 wizard 의 stage picker 가 같은 기준을 상속하게 한다(single-reference)."""
-    if stages and not errs:
-        return None
-    return (
-        "; ".join(e.message for e in errs) if errs
-        else "'## 5.5 Stage Map' heading 이 없거나 표가 비었습니다")
-
-
-def _load_parsed_stage_map(text: str):
-    """validator 모듈을 로드해 `_parse_stage_map(text)` 의 (stages, errs) 를 돌려준다.
+def _parse_stage_map_into_ctx(plan_path: str) -> list:
+    """Parse the approved plan into context records for execution consumers."""
+    from .stage_map import StageMapError, parse_stage_map_file, stage_map_records
 
-    run.py 와 wizard 가 공유하는 단일 validator-load 경로 — 둘 다 `_STAGE_VALIDATOR_PATH`
-    (설치 시 `~/.okstra/lib/validators` 로 배치돼 `parents[2]/validators` 로 해소)로
-    수렴해 경로 해소가 갈라지지 않게 한다."""
-    spec = importlib.util.spec_from_file_location(
-        "_ip_stage_validator", _STAGE_VALIDATOR_PATH
-    )
-    if spec is None or spec.loader is None:
-        raise PrepareError(f"cannot load stage validator at {_STAGE_VALIDATOR_PATH}")
-    mod = importlib.util.module_from_spec(spec)
-    # Register before exec_module so dataclass field-type resolution can find
-    # the module in sys.modules (required on Python 3.9).
-    sys.modules["_ip_stage_validator"] = mod
     try:
-        spec.loader.exec_module(mod)
-        return mod._parse_stage_map(text)
-    finally:
-        sys.modules.pop("_ip_stage_validator", None)
-
-
-def _parse_stage_map_into_ctx(plan_path: str) -> list:
-    """Reuse the validator's parser to extract StageMeta dicts for the ctx."""
-    text = Path(plan_path).read_text(encoding="utf-8")
-    stages, errs = _load_parsed_stage_map(text)
-    detail = _stage_map_reject_detail(stages, errs)
-    if detail is not None:
+        return stage_map_records(parse_stage_map_file(Path(plan_path)))
+    except StageMapError as exc:
         raise PrepareError(
-            f"approved-plan 의 Stage Map 을 신뢰할 수 없어 거부합니다 ({plan_path}): "
-            f"{detail}. plan 의 Stage Map 을 점검하세요.")
-    return [
-        {
-            "stage_number": s.stage_number,
-            "title": s.title,
-            "depends_on": list(s.depends_on),
-            "step_count": s.step_count,
-            "exit_contract_summary": s.exit_contract_summary,
-        }
-        for s in stages
-    ]
+            "approved-plan 의 Stage Map 을 신뢰할 수 없어 거부합니다 "
+            f"({plan_path}): {exc.reason}. plan 의 Stage Map 을 점검하세요."
+        ) from exc
 
 
 def _apply_cli_approval(path: str) -> str: