continuous-refactoring 0.1.0__py3-none-any.whl

continuous_refactoring/artifacts.py

@@ -0,0 +1,431 @@
+from __future__ import annotations
+
+import json
+import os
+import tempfile
+from collections.abc import Mapping
+from dataclasses import asdict, dataclass, field
+from datetime import datetime
+from pathlib import Path
+
+
+__all__ = [
+    "AttemptStats",
+    "CommandCapture",
+    "ContinuousRefactorError",
+    "RunArtifacts",
+    "create_run_artifacts",
+    "default_artifacts_root",
+    "iso_timestamp",
+]
+
+
+class ContinuousRefactorError(RuntimeError):
+    pass
+
+
+_UNSET = object()
+
+
+@dataclass(frozen=True)
+class CommandCapture:
+    command: tuple[str, ...]
+    returncode: int
+    stdout: str
+    stderr: str
+    stdout_path: Path
+    stderr_path: Path
+
+
+@dataclass
+class AttemptStats:
+    attempt: int
+    target: str | None = None
+    retry: int | None = None
+    call_role: str | None = None
+    phase_reached: str | None = None
+    decision: str | None = None
+    retry_recommendation: str | None = None
+    failure_kind: str | None = None
+    failure_summary: str | None = None
+    reason_doc_path: str | None = None
+    commit_sha: str | None = None
+    commit_phase: str | None = None
+    requested_effort: str | None = None
+    effective_effort: str | None = None
+    max_allowed_effort: str | None = None
+    effort_source: str | None = None
+    effort_capped: bool | None = None
+    effort_reason: str | None = None
+
+
+@dataclass
+class RunArtifacts:
+    root: Path
+    run_id: str
+    repo_root: Path
+    agent: str
+    model: str
+    effort: str
+    test_command: str
+    events_path: Path
+    summary_path: Path
+    log_path: Path
+    started_at: str
+    default_effort: str | None = None
+    max_allowed_effort: str | None = None
+    finished_at: str | None = None
+    final_status: str = "running"
+    error_message: str | None = None
+    attempts: dict[int, AttemptStats] = field(default_factory=dict)
+    counts: dict[str, int] = field(
+        default_factory=lambda: {
+            "attempts_started": 0,
+            "commits_created": 0,
+        }
+    )
+
+    def attempt_dir(self, attempt: int, retry: int = 1) -> Path:
+        if attempt < 1:
+            raise ValueError(f"attempt must be >= 1, got {attempt}")
+        if retry < 1:
+            raise ValueError(f"retry must be >= 1, got {retry}")
+        base = self.root / f"attempt-{attempt:03d}"
+        path = base if retry == 1 else base / f"retry-{retry:02d}"
+        path.mkdir(parents=True, exist_ok=True)
+        return path
+
+    def baseline_dir(self, label: str) -> Path:
+        path = self.root / "baseline" / label
+        path.mkdir(parents=True, exist_ok=True)
+        return path
+
+    def ensure_attempt(self, attempt: int) -> AttemptStats:
+        if attempt not in self.attempts:
+            self.attempts[attempt] = AttemptStats(attempt=attempt)
+        return self.attempts[attempt]
+
+    def update_attempt(
+        self,
+        attempt: int,
+        *,
+        target: str | None | object = _UNSET,
+        retry: int | None | object = _UNSET,
+        call_role: str | None | object = _UNSET,
+        phase_reached: str | None | object = _UNSET,
+        decision: str | None | object = _UNSET,
+        retry_recommendation: str | None | object = _UNSET,
+        failure_kind: str | None | object = _UNSET,
+        failure_summary: str | None | object = _UNSET,
+        reason_doc_path: Path | None | object = _UNSET,
+        effort: Mapping[str, object] | None | object = _UNSET,
+    ) -> None:
+        stats = self.ensure_attempt(attempt)
+        if target is not _UNSET:
+            stats.target = target
+        if retry is not _UNSET:
+            stats.retry = retry
+        if call_role is not _UNSET:
+            stats.call_role = call_role
+        if phase_reached is not _UNSET:
+            stats.phase_reached = phase_reached
+        if decision is not _UNSET:
+            stats.decision = decision
+        if retry_recommendation is not _UNSET:
+            stats.retry_recommendation = retry_recommendation
+        if failure_kind is not _UNSET:
+            stats.failure_kind = failure_kind
+        if failure_summary is not _UNSET:
+            stats.failure_summary = failure_summary
+        if reason_doc_path is not _UNSET:
+            stats.reason_doc_path = (
+                str(reason_doc_path) if reason_doc_path is not None else None
+            )
+        if effort is not _UNSET:
+            _apply_effort_fields(stats, effort if effort is not None else None)
+        self.write_summary()
+
+    def log(self, level: str, message: str, **fields: object) -> None:
+        timestamp = iso_timestamp()
+        line = f"[{level}] {message}"
+        print(line)
+        with self.log_path.open("a", encoding="utf-8") as handle:
+            handle.write(f"[{timestamp}] {line}\n")
+        event = {"timestamp": timestamp, "level": level, "message": message, **fields}
+        _append_event(self.events_path, event)
+        self.write_summary()
+
+    def mark_attempt_started(self, attempt: int) -> None:
+        self.counts["attempts_started"] += 1
+        self.ensure_attempt(attempt)
+        self.write_summary()
+
+    def log_call_started(
+        self,
+        *,
+        attempt: int,
+        retry: int,
+        target: str,
+        display_target: str | None = None,
+        call_role: str,
+        phase_reached: str | None = None,
+        effort: Mapping[str, object] | None = None,
+    ) -> None:
+        self.update_attempt(
+            attempt,
+            target=target,
+            retry=retry,
+            call_role=call_role,
+            phase_reached=phase_reached or call_role,
+            effort=effort,
+        )
+        effort_fields = dict(effort or {})
+        human_target = display_target or target
+        self.log(
+            "INFO",
+            f"call start: {call_role} — {human_target}{_effort_log_suffix(effort)}",
+            event="call_started",
+            attempt=attempt,
+            retry=retry,
+            target=target,
+            call_role=call_role,
+            phase_reached=phase_reached or call_role,
+            **effort_fields,
+        )
+
+    def log_call_finished(
+        self,
+        *,
+        attempt: int,
+        retry: int,
+        target: str,
+        call_role: str,
+        display_target: str | None = None,
+        phase_reached: str | None = None,
+        status: str,
+        level: str = "INFO",
+        returncode: int | None = None,
+        summary: str | None = None,
+        effort: Mapping[str, object] | None = None,
+    ) -> None:
+        self.update_attempt(
+            attempt,
+            target=target,
+            retry=retry,
+            call_role=call_role,
+            phase_reached=phase_reached or call_role,
+            failure_summary=summary,
+            effort=effort,
+        )
+        effort_fields = dict(effort or {})
+        human_target = display_target or target
+        self.log(
+            level,
+            f"call {status}: {call_role} — {human_target}"
+            f"{_effort_log_suffix(effort)}",
+            event="call_finished",
+            attempt=attempt,
+            retry=retry,
+            target=target,
+            call_role=call_role,
+            phase_reached=phase_reached or call_role,
+            call_status=status,
+            returncode=returncode,
+            summary=summary,
+            **effort_fields,
+        )
+
+    def log_transition(
+        self,
+        *,
+        attempt: int,
+        retry: int,
+        target: str,
+        call_role: str,
+        phase_reached: str,
+        decision: str,
+        retry_recommendation: str,
+        failure_kind: str,
+        summary: str,
+        reason_doc_path: Path | None,
+    ) -> None:
+        self.update_attempt(
+            attempt,
+            target=target,
+            retry=retry,
+            call_role=call_role,
+            phase_reached=phase_reached,
+            decision=decision,
+            retry_recommendation=retry_recommendation,
+            failure_kind=failure_kind,
+            failure_summary=summary,
+            reason_doc_path=reason_doc_path,
+        )
+        self.log(
+            "WARN",
+            f"target transition: {decision}/{retry_recommendation} — {target}",
+            event="target_transition",
+            attempt=attempt,
+            retry=retry,
+            target=target,
+            call_role=call_role,
+            phase_reached=phase_reached,
+            decision=decision,
+            retry_recommendation=retry_recommendation,
+            failure_kind=failure_kind,
+            summary=summary,
+            reason_doc_path=str(reason_doc_path) if reason_doc_path else None,
+        )
+
+    def record_commit(self, attempt: int, phase: str, commit_sha: str) -> None:
+        stats = self.ensure_attempt(attempt)
+        stats.commit_sha = commit_sha
+        stats.commit_phase = phase
+        self.counts["commits_created"] += 1
+        self.write_summary()
+
+    def finish(self, status: str, error_message: str | None = None) -> None:
+        self.finished_at = iso_timestamp()
+        self.final_status = status
+        self.error_message = error_message
+        self.write_summary()
+
+    def write_summary(self) -> None:
+        summary = {
+            "run_id": self.run_id,
+            "artifact_root": str(self.root),
+            "repo_root": str(self.repo_root),
+            "agent": self.agent,
+            "model": self.model,
+            "effort": self.effort,
+            "default_effort": self.default_effort or self.effort,
+            "max_allowed_effort": self.max_allowed_effort or self.effort,
+            "test_command": self.test_command,
+            "started_at": self.started_at,
+            "finished_at": self.finished_at,
+            "final_status": self.final_status,
+            "error_message": self.error_message,
+            "counts": self.counts,
+            "attempts": [asdict(self.attempts[key]) for key in sorted(self.attempts)],
+        }
+        content = _serialize_summary(self.summary_path, summary)
+        _write_text_atomic(self.summary_path, content)
+
+
+def iso_timestamp() -> str:
+    return _now().isoformat(timespec="milliseconds")
+
+
+def _now() -> datetime:
+    return datetime.now().astimezone()
+
+
+def default_artifacts_root() -> Path:
+    return Path(os.environ.get("TMPDIR") or tempfile.gettempdir())
+
+
+def _append_event(path: Path, event: Mapping[str, object]) -> None:
+    try:
+        with path.open("a", encoding="utf-8") as handle:
+            handle.write(json.dumps(event, sort_keys=True) + "\n")
+    except OSError as exc:
+        raise ContinuousRefactorError(f"Could not append artifact event to {path}") from exc
+
+
+def _serialize_summary(path: Path, summary: Mapping[str, object]) -> str:
+    try:
+        return json.dumps(summary, indent=2, sort_keys=True) + "\n"
+    except (TypeError, ValueError) as exc:
+        raise ContinuousRefactorError(f"Could not serialize run summary for {path}") from exc
+
+
+def _write_text_atomic(path: Path, content: str) -> None:
+    tmp_path: Path | None = None
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        with tempfile.NamedTemporaryFile(
+            mode="w", encoding="utf-8", dir=path.parent, suffix=".tmp", delete=False
+        ) as tmp:
+            tmp_path = Path(tmp.name)
+            tmp.write(content)
+        os.replace(tmp_path, path)
+    except OSError as exc:
+        if tmp_path is not None:
+            tmp_path.unlink(missing_ok=True)
+        raise ContinuousRefactorError(f"Could not write artifact file {path}") from exc
+
+
+def create_run_artifacts(
+    repo_root: Path,
+    *,
+    agent: str,
+    model: str,
+    effort: str,
+    default_effort: str | None = None,
+    max_allowed_effort: str | None = None,
+    test_command: str,
+) -> RunArtifacts:
+    started_at_dt = _now()
+    started_at = started_at_dt.isoformat(timespec="milliseconds")
+    run_id = started_at_dt.strftime("%Y%m%dT%H%M%S-%f")
+    root = default_artifacts_root() / "continuous-refactoring" / run_id
+    root.mkdir(parents=True, exist_ok=False)
+    artifacts = RunArtifacts(
+        root=root,
+        run_id=run_id,
+        repo_root=repo_root,
+        agent=agent,
+        model=model,
+        effort=effort,
+        default_effort=default_effort or effort,
+        max_allowed_effort=max_allowed_effort or effort,
+        test_command=test_command,
+        events_path=root / "events.jsonl",
+        summary_path=root / "summary.json",
+        log_path=root / "run.log",
+        started_at=started_at,
+    )
+    artifacts.write_summary()
+    return artifacts
+
+
+def _apply_effort_fields(
+    stats: AttemptStats,
+    effort: Mapping[str, object] | None,
+) -> None:
+    if effort is None:
+        return
+    fields = {
+        "requested_effort",
+        "effective_effort",
+        "max_allowed_effort",
+        "effort_source",
+        "effort_capped",
+        "effort_reason",
+    }
+    for field_name in fields:
+        if field_name not in effort:
+            continue
+        value = effort[field_name]
+        setattr(stats, field_name, value if value is not None else None)
+
+
+def _effort_log_suffix(effort: Mapping[str, object] | None) -> str:
+    if not effort:
+        return ""
+    effective = _string_field(effort.get("effective_effort"))
+    requested = _string_field(effort.get("requested_effort"))
+    selected = effective or requested
+    if selected is None:
+        return ""
+    parts = [f"effort={selected}"]
+    if effective is not None and requested is not None and requested != effective:
+        parts.append(f"requested={requested}")
+    return f" ({' '.join(parts)})"
+
+
+def _string_field(value: object) -> str | None:
+    if value is None:
+        return None
+    text = str(value).strip()
+    return text or None