claude-dev-env 1.94.0 → 2.0.0

package/skills/codex-review/scripts/parse_codex_findings.py

@@ -0,0 +1,207 @@
+"""Parse Codex reviewer text into stable internal finding records.
+
+::
+
+    all_findings = parse_codex_findings(reviewer_text)
+    all_findings[0].title      # structured or freeform title
+    all_findings[0].structured # True only for fenced JSON findings
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import dataclass
+
+from codex_review_scripts_constants.findings_constants import (
+    EMPTY_STRING,
+    FENCED_JSON_BLOCK_PATTERN,
+    FINDING_KEY_BODY,
+    FINDING_KEY_FILE,
+    FINDING_KEY_LINE_RANGE,
+    FINDING_KEY_PRIORITY,
+    FINDING_KEY_TITLE,
+    FREEFORM_BULLET_PREFIX,
+    FREEFORM_FINDING_LINE_PATTERN,
+    NEWLINE,
+)
+
+
+@dataclass(frozen=True)
+class CodexFinding:
+    """One review finding in the skill's stable internal shape.
+
+    ::
+
+        CodexFinding(
+            title="Restore empty-input handling",
+            priority="P1",
+            file="src/stats.py",
+            line_range="2-2",
+            body="Divides by zero on empty input.",
+            structured=True,
+        )
+
+    Attributes:
+        title: Short finding title.
+        priority: Priority tag such as ``P1``.
+        file: Path the finding points at.
+        line_range: Inclusive line span as ``start-end``.
+        body: Explanation text for the finding.
+        structured: True when the finding came from fenced JSON.
+    """
+
+    title: str
+    priority: str
+    file: str
+    line_range: str
+    body: str
+    structured: bool
+
+
+def _string_field(all_finding_fields: dict[str, object], field_name: str) -> str:
+    field_payload = all_finding_fields.get(field_name, EMPTY_STRING)
+    if isinstance(field_payload, str):
+        return field_payload
+    return EMPTY_STRING
+
+
+def _finding_from_structured_fields(
+    all_finding_fields: dict[str, object],
+) -> CodexFinding:
+    return CodexFinding(
+        title=_string_field(all_finding_fields, FINDING_KEY_TITLE),
+        priority=_string_field(all_finding_fields, FINDING_KEY_PRIORITY),
+        file=_string_field(all_finding_fields, FINDING_KEY_FILE),
+        line_range=_string_field(all_finding_fields, FINDING_KEY_LINE_RANGE),
+        body=_string_field(all_finding_fields, FINDING_KEY_BODY),
+        structured=True,
+    )
+
+
+def _has_usable_structured_fields(finding: CodexFinding) -> bool:
+    has_title = bool(finding.title.strip())
+    has_body = bool(finding.body.strip())
+    return has_title or has_body
+
+
+def _try_parse_structured_findings(reviewer_text: str) -> list[CodexFinding] | None:
+    fenced_json_block = re.compile(
+        FENCED_JSON_BLOCK_PATTERN,
+        re.DOTALL | re.IGNORECASE,
+    )
+    for each_match in fenced_json_block.finditer(reviewer_text):
+        block_body = each_match.group(1).strip()
+        try:
+            parsed_payload = json.loads(block_body)
+        except json.JSONDecodeError:
+            continue
+        if not isinstance(parsed_payload, list):
+            continue
+        if not parsed_payload:
+            return []
+        all_findings: list[CodexFinding] = []
+        for each_entry in parsed_payload:
+            if not isinstance(each_entry, dict):
+                continue
+            candidate_finding = _finding_from_structured_fields(each_entry)
+            if not _has_usable_structured_fields(candidate_finding):
+                continue
+            all_findings.append(candidate_finding)
+        if all_findings:
+            return all_findings
+    return None
+
+
+def _collect_freeform_body(
+    all_lines: list[str],
+    *,
+    from_index: int,
+) -> tuple[str, int]:
+    all_body_lines: list[str] = []
+    current_index = from_index
+    while current_index < len(all_lines):
+        current_line = all_lines[current_index]
+        stripped_line = current_line.strip()
+        if stripped_line.startswith(FREEFORM_BULLET_PREFIX):
+            break
+        if stripped_line:
+            all_body_lines.append(stripped_line)
+        current_index += 1
+    return NEWLINE.join(all_body_lines), current_index
+
+
+def _parse_freeform_findings(reviewer_text: str) -> list[CodexFinding]:
+    freeform_finding_line = re.compile(FREEFORM_FINDING_LINE_PATTERN)
+    all_lines = reviewer_text.splitlines()
+    all_findings: list[CodexFinding] = []
+    line_index = 0
+    while line_index < len(all_lines):
+        line_match = freeform_finding_line.match(all_lines[line_index].strip())
+        if line_match is None:
+            line_index += 1
+            continue
+        body_text, next_index = _collect_freeform_body(
+            all_lines,
+            from_index=line_index + 1,
+        )
+        all_findings.append(
+            CodexFinding(
+                title=line_match.group("title").strip(),
+                priority=line_match.group("priority"),
+                file=line_match.group("file_path").strip(),
+                line_range=line_match.group("line_range"),
+                body=body_text,
+                structured=False,
+            )
+        )
+        line_index = next_index
+    return all_findings
+
+
+def _floor_finding(reviewer_text: str) -> list[CodexFinding]:
+    return [
+        CodexFinding(
+            title=EMPTY_STRING,
+            priority=EMPTY_STRING,
+            file=EMPTY_STRING,
+            line_range=EMPTY_STRING,
+            body=reviewer_text,
+            structured=False,
+        )
+    ]
+
+
+def parse_codex_findings(reviewer_text: str) -> list[CodexFinding]:
+    """Parse reviewer text into findings; never drop non-empty text.
+
+    ::
+
+        parse_codex_findings("```json\\n[]\\n```")  # ok: []
+        parse_codex_findings("loose note")          # ok: one unstructured finding
+        parse_codex_findings('```json\\n["x"]\\n```\\n- [P1] T — a.py:1-1')
+        # ok: freeform finding (non-dict JSON list is not structured clean)
+
+    Tries fenced JSON first (the custom-instructions contract). An empty
+    array ``[]`` is structured clean. A non-empty array that yields no
+    usable object findings (non-dicts, empty shells, wrong keys) is not
+    accepted; freeform and floor paths run instead. Freeform is the
+    ``- [P1] title — path:start-end`` shape. Floor carries the raw text.
+
+    Args:
+        reviewer_text: Agent message text from a completed Codex review.
+
+    Returns:
+        Parsed findings. Empty only when the text is blank, or when a
+        fenced structured payload is exactly the empty array ``[]``.
+        Non-blank text never returns empty for any other structured shape.
+    """
+    if not reviewer_text.strip():
+        return []
+    maybe_structured = _try_parse_structured_findings(reviewer_text)
+    if maybe_structured is not None:
+        return maybe_structured
+    all_freeform_findings = _parse_freeform_findings(reviewer_text)
+    if all_freeform_findings:
+        return all_freeform_findings
+    return _floor_finding(reviewer_text)

package/skills/codex-review/scripts/run_codex_review.py

@@ -0,0 +1,415 @@
+"""Headless wrapper that runs one Codex review and captures its outputs.
+
+::
+
+    review_outcome = run_codex_review(
+        repository_directory=Path("/path/to/repo"),
+        run_state_directory=Path("/path/to/run_state"),
+        is_uncommitted=True,
+    )
+    review_outcome.outcome_class  # "completed" or "codex_down"
+    review_outcome.jsonl_path     # path to captured JSONL stream
+    review_outcome.agent_message  # final agent_message text
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import shutil
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+
+from codex_review_scripts_constants.codex_usage_probe_constants import (
+    ALL_WINDOWS_SCRIPT_SUFFIXES,
+    WINDOWS_COMMAND_SHELL,
+    WINDOWS_COMMAND_SHELL_RUN_FLAG,
+    WINDOWS_OS_NAME,
+)
+from codex_review_scripts_constants.run_constants import (
+    ALL_SHAPE_PROBE_REQUIRED_FLAGS,
+    BASE_TARGET_FLAG,
+    CODEX_BINARY_NAME,
+    CODEX_MODEL_PIN,
+    COMMIT_TARGET_FLAG,
+    CUSTOM_INSTRUCTIONS_PROMPT,
+    DEFAULT_TIMEOUT_SECONDS,
+    EXEC_SUBCOMMAND,
+    HELP_FLAG,
+    JSON_FLAG,
+    JSONL_AGENT_MESSAGE_TEXT_KEY,
+    JSONL_AGENT_MESSAGE_TYPE,
+    JSONL_CAPTURE_FILENAME,
+    JSONL_CAPTURE_NEWLINE,
+    JSONL_ENTRY_COMPLETED_TYPE,
+    JSONL_ENTRY_KEY,
+    JSONL_EVENT_TYPE_KEY,
+    MISSING_BINARY_EXIT_CODE,
+    MODEL_FLAG,
+    OUTCOME_CLASS_CODEX_DOWN,
+    OUTCOME_CLASS_COMPLETED,
+    REVIEW_SUBCOMMAND,
+    SHAPE_FLAG_TOKEN_TAIL_PATTERN,
+    SUBPROCESS_DECODE_EXIT_CODE,
+    TIMEOUT_EXIT_CODE,
+    UNCOMMITTED_TARGET_FLAG,
+    UTF8_ENCODING,
+    VERSION_FLAG,
+    VERSION_PROBE_PATTERN,
+)
+
+codex_subprocess_runner = subprocess.run
+
+
+@dataclass(frozen=True)
+class CodexReviewOutcome:
+    """Captured result of one probe-plus-review attempt.
+
+    ::
+
+        CodexReviewOutcome(
+            outcome_class="completed",
+            exit_code=0,
+            binary_version="0.144.3",
+            jsonl_path=Path("run_state/codex-review.jsonl"),
+            agent_message="No issues found.",
+        )
+
+    Attributes:
+        outcome_class: Capture-boundary class ``completed`` or ``codex_down``.
+            Callers treat this field as the success signal; ``exit_code`` alone
+            is not enough (a shape probe can exit 0 while flags are missing).
+        exit_code: Last process exit code, or a sentinel when none ran.
+        binary_version: Parsed ``codex --version`` string, or empty.
+        jsonl_path: Captured JSONL path, or None when review did not run.
+        agent_message: Last JSONL ``agent_message`` text when present; on a
+            non-zero review exit, falls back to stderr text when JSONL has no
+            agent message (config and argument errors land on stderr).
+    """
+
+    outcome_class: str
+    exit_code: int
+    binary_version: str
+    jsonl_path: Path | None
+    agent_message: str
+
+
+def _down(*, exit_code: int, binary_version: str) -> CodexReviewOutcome:
+    return CodexReviewOutcome(
+        outcome_class=OUTCOME_CLASS_CODEX_DOWN,
+        exit_code=exit_code,
+        binary_version=binary_version,
+        jsonl_path=None,
+        agent_message="",
+    )
+
+
+def _resolve_codex_command_prefix() -> list[str]:
+    """Resolve the codex launch prefix, wrapping a Windows ``.cmd``/``.bat`` shim.
+
+    ::
+
+        POSIX codex on PATH   ->  ["/usr/local/bin/codex"]
+        Windows codex.cmd     ->  ["cmd", "/c", "C:\\...\\codex.cmd"]
+        codex not on PATH     ->  ["codex"]      (downstream FileNotFoundError)
+
+    ``CreateProcess`` resolves a bare name only against ``.exe``, so a bare
+    ``codex`` never finds the npm shim; the ``cmd /c`` wrap runs it.
+    """
+    codex_path = shutil.which(CODEX_BINARY_NAME)
+    if codex_path is None:
+        return [CODEX_BINARY_NAME]
+    if os.name == WINDOWS_OS_NAME and codex_path.lower().endswith(
+        ALL_WINDOWS_SCRIPT_SUFFIXES
+    ):
+        return [WINDOWS_COMMAND_SHELL, WINDOWS_COMMAND_SHELL_RUN_FLAG, codex_path]
+    return [codex_path]
+
+
+def _run_command(
+    all_arguments: list[str],
+    *,
+    working_directory: Path | None,
+    timeout_seconds: int,
+) -> subprocess.CompletedProcess[str]:
+    return codex_subprocess_runner(
+        all_arguments,
+        cwd=str(working_directory) if working_directory is not None else None,
+        capture_output=True,
+        text=True,
+        encoding=UTF8_ENCODING,
+        check=False,
+        timeout=timeout_seconds,
+        env=dict(os.environ),
+    )
+
+
+def _safe_run(
+    all_arguments: list[str],
+    *,
+    working_directory: Path | None,
+    timeout_seconds: int,
+) -> subprocess.CompletedProcess[str] | int:
+    try:
+        return _run_command(
+            all_arguments,
+            working_directory=working_directory,
+            timeout_seconds=timeout_seconds,
+        )
+    except FileNotFoundError:
+        if working_directory is not None and not working_directory.is_dir():
+            raise
+        return MISSING_BINARY_EXIT_CODE
+    except subprocess.TimeoutExpired:
+        return TIMEOUT_EXIT_CODE
+    except UnicodeDecodeError:
+        return SUBPROCESS_DECODE_EXIT_CODE
+
+
+def _parse_binary_version(version_stdout: str) -> str:
+    version_match = re.search(VERSION_PROBE_PATTERN, version_stdout)
+    if version_match is None:
+        return version_stdout.strip()
+    return version_match.group(1)
+
+
+def _probe_binary_version(timeout_seconds: int) -> tuple[str, int | None]:
+    completion_or_exit = _safe_run(
+        [*_resolve_codex_command_prefix(), VERSION_FLAG],
+        working_directory=None,
+        timeout_seconds=timeout_seconds,
+    )
+    if isinstance(completion_or_exit, int):
+        return "", completion_or_exit
+    if completion_or_exit.returncode != 0:
+        return "", completion_or_exit.returncode
+    return _parse_binary_version(completion_or_exit.stdout), None
+
+
+def _probe_review_shape(timeout_seconds: int) -> tuple[bool, int]:
+    completion_or_exit = _safe_run(
+        [*_resolve_codex_command_prefix(), EXEC_SUBCOMMAND, REVIEW_SUBCOMMAND, HELP_FLAG],
+        working_directory=None,
+        timeout_seconds=timeout_seconds,
+    )
+    if isinstance(completion_or_exit, int):
+        return False, completion_or_exit
+    if completion_or_exit.returncode != 0:
+        return False, completion_or_exit.returncode
+    help_text = f"{completion_or_exit.stdout}{completion_or_exit.stderr}"
+    has_required_flags = all(
+        _help_text_contains_flag(help_text, each_flag)
+        for each_flag in ALL_SHAPE_PROBE_REQUIRED_FLAGS
+    )
+    return has_required_flags, completion_or_exit.returncode
+
+
+def _help_text_contains_flag(help_text: str, flag_name: str) -> bool:
+    flag_token_pattern = re.compile(
+        re.escape(flag_name) + SHAPE_FLAG_TOKEN_TAIL_PATTERN
+    )
+    return flag_token_pattern.search(help_text) is not None
+
+
+def _require_single_target(
+    *,
+    base_branch: str | None,
+    is_uncommitted: bool,
+    commit_sha: str | None,
+    is_prompt_target: bool,
+) -> None:
+    selected_target_count = sum(
+        [
+            base_branch is not None,
+            is_uncommitted,
+            commit_sha is not None,
+            is_prompt_target,
+        ]
+    )
+    if selected_target_count != 1:
+        raise ValueError(
+            "exactly one of base_branch, is_uncommitted, commit_sha, "
+            "or is_prompt_target must be selected"
+        )
+
+
+def _require_existing_directory(directory_path: Path, parameter_name: str) -> None:
+    if not directory_path.is_dir():
+        raise ValueError(
+            f"{parameter_name} is not an existing directory: {directory_path}"
+        )
+
+
+def _build_review_arguments(
+    *,
+    base_branch: str | None,
+    is_uncommitted: bool,
+    commit_sha: str | None,
+    is_prompt_target: bool,
+) -> list[str]:
+    all_arguments = [*_resolve_codex_command_prefix(), EXEC_SUBCOMMAND]
+    if CODEX_MODEL_PIN:
+        all_arguments.extend([MODEL_FLAG, CODEX_MODEL_PIN])
+    all_arguments.extend([REVIEW_SUBCOMMAND, JSON_FLAG])
+    if is_uncommitted:
+        all_arguments.append(UNCOMMITTED_TARGET_FLAG)
+    elif base_branch is not None:
+        all_arguments.extend([BASE_TARGET_FLAG, base_branch])
+    elif commit_sha is not None:
+        all_arguments.extend([COMMIT_TARGET_FLAG, commit_sha])
+    elif is_prompt_target:
+        all_arguments.append(CUSTOM_INSTRUCTIONS_PROMPT)
+    return all_arguments
+
+
+def _extract_agent_message(jsonl_text: str) -> str:
+    agent_message_text = ""
+    for each_line in jsonl_text.splitlines():
+        stripped_line = each_line.strip()
+        if not stripped_line:
+            continue
+        try:
+            event_payload = json.loads(stripped_line)
+        except json.JSONDecodeError:
+            continue
+        if not isinstance(event_payload, dict):
+            continue
+        if event_payload.get(JSONL_EVENT_TYPE_KEY) != JSONL_ENTRY_COMPLETED_TYPE:
+            continue
+        entry_payload = event_payload.get(JSONL_ENTRY_KEY)
+        if not isinstance(entry_payload, dict):
+            continue
+        if entry_payload.get(JSONL_EVENT_TYPE_KEY) != JSONL_AGENT_MESSAGE_TYPE:
+            continue
+        message_text = entry_payload.get(JSONL_AGENT_MESSAGE_TEXT_KEY)
+        if isinstance(message_text, str):
+            agent_message_text = message_text
+    return agent_message_text
+
+
+def _probe_or_down(timeout_seconds: int) -> CodexReviewOutcome | str:
+    binary_version, version_failure_exit_code = _probe_binary_version(timeout_seconds)
+    if version_failure_exit_code is not None:
+        return _down(
+            exit_code=version_failure_exit_code,
+            binary_version=binary_version,
+        )
+    is_shape_supported, shape_exit_code = _probe_review_shape(timeout_seconds)
+    if not is_shape_supported:
+        return _down(exit_code=shape_exit_code, binary_version=binary_version)
+    return binary_version
+
+
+def _capture_review_run(
+    *,
+    repository_directory: Path,
+    run_state_directory: Path,
+    all_review_arguments: list[str],
+    timeout_seconds: int,
+    binary_version: str,
+) -> CodexReviewOutcome:
+    completion_or_exit = _safe_run(
+        all_review_arguments,
+        working_directory=repository_directory,
+        timeout_seconds=timeout_seconds,
+    )
+    if isinstance(completion_or_exit, int):
+        return _down(exit_code=completion_or_exit, binary_version=binary_version)
+    jsonl_text = completion_or_exit.stdout or ""
+    stderr_text = completion_or_exit.stderr or ""
+    jsonl_path = run_state_directory / JSONL_CAPTURE_FILENAME
+    run_state_directory.mkdir(parents=True, exist_ok=True)
+    jsonl_path.write_text(
+        jsonl_text,
+        encoding=UTF8_ENCODING,
+        newline=JSONL_CAPTURE_NEWLINE,
+    )
+    review_returncode = completion_or_exit.returncode
+    if review_returncode != 0:
+        return CodexReviewOutcome(
+            outcome_class=OUTCOME_CLASS_CODEX_DOWN,
+            exit_code=review_returncode,
+            binary_version=binary_version,
+            jsonl_path=jsonl_path,
+            agent_message=_extract_agent_message(jsonl_text) or stderr_text,
+        )
+    return CodexReviewOutcome(
+        outcome_class=OUTCOME_CLASS_COMPLETED,
+        exit_code=review_returncode,
+        binary_version=binary_version,
+        jsonl_path=jsonl_path,
+        agent_message=_extract_agent_message(jsonl_text),
+    )
+
+
+def run_codex_review(
+    *,
+    repository_directory: Path,
+    run_state_directory: Path,
+    base_branch: str | None = None,
+    is_uncommitted: bool = False,
+    commit_sha: str | None = None,
+    is_prompt_target: bool = False,
+    timeout_seconds: int | None = None,
+) -> CodexReviewOutcome:
+    """Run one Codex review against a single target and capture its outputs.
+
+    Capture-only boundary: returns ``completed`` or ``codex_down`` plus raw
+    capture fields. Skill-level classes ``down`` / ``clean`` / ``findings``
+    come from a later classifier that reads this outcome.
+
+    ::
+
+        ok:   outcome_class == "completed" and exit_code == 0
+        flag: outcome_class == "codex_down" even when exit_code == 0
+              (shape probe ran, required flags missing)
+
+    Args:
+        repository_directory: Repository root used as the process cwd.
+        run_state_directory: Existing directory that receives the JSONL stream
+            file. The caller creates this directory before the call.
+        base_branch: Base branch for ``--base``; exclusive with other targets.
+        is_uncommitted: When True, uses ``--uncommitted``.
+        commit_sha: Commit SHA for ``--commit``; exclusive with other targets.
+        is_prompt_target: When True, uses the custom-instructions PROMPT target.
+        timeout_seconds: Per-invocation timeout; defaults from constants.
+
+    Returns:
+        Capture outcome (``completed`` / ``codex_down``), process exit code,
+        binary version, JSONL path, and agent text (JSONL agent_message, or
+        stderr on a failed review when JSONL has no agent message).
+
+    Raises:
+        ValueError: When zero targets or more than one target is selected, or
+            when ``repository_directory`` or ``run_state_directory`` is not an
+            existing directory. Both directories are checked before any Codex
+            process starts, so a bad path costs no review run.
+    """
+    _require_single_target(
+        base_branch=base_branch,
+        is_uncommitted=is_uncommitted,
+        commit_sha=commit_sha,
+        is_prompt_target=is_prompt_target,
+    )
+    _require_existing_directory(repository_directory, "repository_directory")
+    _require_existing_directory(run_state_directory, "run_state_directory")
+    resolved_timeout_seconds = (
+        DEFAULT_TIMEOUT_SECONDS if timeout_seconds is None else timeout_seconds
+    )
+    probe_outcome = _probe_or_down(resolved_timeout_seconds)
+    if isinstance(probe_outcome, CodexReviewOutcome):
+        return probe_outcome
+    return _capture_review_run(
+        repository_directory=repository_directory,
+        run_state_directory=run_state_directory,
+        all_review_arguments=_build_review_arguments(
+            base_branch=base_branch,
+            is_uncommitted=is_uncommitted,
+            commit_sha=commit_sha,
+            is_prompt_target=is_prompt_target,
+        ),
+        timeout_seconds=resolved_timeout_seconds,
+        binary_version=probe_outcome,
+    )