claude-dev-env 4.2.0 → 4.3.0

package/.agents/skills/_shared/pr-loop/scripts/durable_post_lint.py

@@ -0,0 +1,242 @@
+"""Validate durable GitHub post inputs before publication."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from collections.abc import Sequence
+from dataclasses import dataclass
+from pathlib import Path
+
+from skills_pr_loop_constants.durable_post_lint_constants import (
+    ACTION_PR_CREATE,
+    ACTION_PR_EDIT,
+    ALL_BARE_VOLATILE_PATH_MARKERS,
+    ALL_BODY_REQUIRED_ACTIONS,
+    ALL_PATH_ANCHORED_VOLATILE_PATH_MARKERS,
+    ALL_POST_ACTIONS,
+    ALL_PR_DESCRIPTION_ACTIONS,
+    ALL_REQUIRED_PR_DESCRIPTION_HEADINGS,
+    ALL_TITLE_ACTIONS,
+    BODY_FILE_ENCODING,
+    BODY_FILE_UNREADABLE_MESSAGE,
+    BODY_MUST_NOT_BE_EMPTY_MESSAGE,
+    BODY_REQUIRED_MESSAGE,
+    CLEAN_EXIT_CODE,
+    CONTENT_FINDING_EXIT_CODE,
+    CONVENTIONAL_TITLE_PATTERN,
+    EDIT_INPUT_REQUIRED_MESSAGE,
+    EMPTY_BODY_CODE,
+    INPUT_ERROR_EXIT_CODE,
+    INVALID_ACTION_MESSAGE,
+    INVALID_TITLE_CODE,
+    INVALID_TITLE_MESSAGE,
+    MISSING_HEADING_CODE,
+    MISSING_HEADING_MESSAGE_TEMPLATE,
+    PATH_ANCHOR_CHARACTER,
+    PATH_SEGMENT_START_CHARACTERS,
+    TITLE_NOT_ALLOWED_MESSAGE,
+    TITLE_REQUIRED_MESSAGE,
+    VOLATILE_PATH_CODE,
+    VOLATILE_PATH_MESSAGE,
+)
+
+
+class DurablePostUsageError(ValueError):
+    """Report an invalid GitHub post request shape."""
+
+
+class DurablePostInputError(OSError):
+    """Report an unreadable GitHub post input file."""
+
+
+@dataclass(frozen=True)
+class DurablePostFinding:
+    """One GitHub post content finding."""
+
+    code: str
+    message: str
+
+
+def _character_starts_path_segment(character: str) -> bool:
+    return bool(character) and (
+        character.isalnum() or character in PATH_SEGMENT_START_CHARACTERS
+    )
+
+
+def _text_has_anchored_marker(normalized_text: str, marker: str) -> bool:
+    search_start = 0
+    while True:
+        found_index = normalized_text.find(marker, search_start)
+        if found_index < 0:
+            return False
+        preceding_character = normalized_text[found_index - 1 : found_index]
+        following_index = found_index + len(marker)
+        following_character = normalized_text[following_index : following_index + 1]
+        if (
+            preceding_character == PATH_ANCHOR_CHARACTER
+            or _character_starts_path_segment(following_character)
+        ):
+            return True
+        search_start = found_index + 1
+
+
+def find_volatile_path_marker(body_text: str) -> str | None:
+    """Return the first volatile path marker in a GitHub post body.
+
+    Args:
+        body_text: Post body text to scan.
+
+    Returns:
+        The matched marker, or None when the body names no volatile path.
+    """
+    normalized_text = body_text.replace("\\", PATH_ANCHOR_CHARACTER).lower()
+    for each_marker in ALL_PATH_ANCHORED_VOLATILE_PATH_MARKERS:
+        if _text_has_anchored_marker(normalized_text, each_marker):
+            return each_marker
+    for each_marker in ALL_BARE_VOLATILE_PATH_MARKERS:
+        if each_marker in normalized_text:
+            return each_marker
+    return None
+
+
+def read_body_file(body_file: Path) -> str:
+    """Read one UTF-8 body file without exposing its contents on failure.
+
+    Args:
+        body_file: Local post body file.
+
+    Returns:
+        Decoded body text.
+
+    Raises:
+        DurablePostInputError: The file is missing, unreadable, or invalid UTF-8.
+    """
+    try:
+        return body_file.read_text(encoding=BODY_FILE_ENCODING)
+    except (OSError, UnicodeError) as error:
+        raise DurablePostInputError(BODY_FILE_UNREADABLE_MESSAGE) from error
+
+
+def _validate_request_shape(
+    action: str,
+    title: str | None,
+    body_text: str | None,
+) -> None:
+    if action not in ALL_POST_ACTIONS:
+        raise DurablePostUsageError(INVALID_ACTION_MESSAGE)
+    if action in ALL_BODY_REQUIRED_ACTIONS and body_text is None:
+        raise DurablePostUsageError(BODY_REQUIRED_MESSAGE)
+    if action == ACTION_PR_CREATE and not title:
+        raise DurablePostUsageError(TITLE_REQUIRED_MESSAGE)
+    if action == ACTION_PR_EDIT and title is None and body_text is None:
+        raise DurablePostUsageError(EDIT_INPUT_REQUIRED_MESSAGE)
+    if title is not None and action not in ALL_TITLE_ACTIONS:
+        raise DurablePostUsageError(TITLE_NOT_ALLOWED_MESSAGE)
+
+
+def _description_heading_findings(body_text: str) -> list[DurablePostFinding]:
+    all_body_lines = {each_line.strip() for each_line in body_text.splitlines()}
+    return [
+        DurablePostFinding(
+            code=MISSING_HEADING_CODE,
+            message=MISSING_HEADING_MESSAGE_TEMPLATE.format(heading=each_heading),
+        )
+        for each_heading in ALL_REQUIRED_PR_DESCRIPTION_HEADINGS
+        if f"## {each_heading}" not in all_body_lines
+    ]
+
+
+def _title_findings(title: str | None) -> list[DurablePostFinding]:
+    if title is None or CONVENTIONAL_TITLE_PATTERN.fullmatch(title) is not None:
+        return []
+    return [DurablePostFinding(code=INVALID_TITLE_CODE, message=INVALID_TITLE_MESSAGE)]
+
+
+def _body_findings(
+    action: str,
+    body_text: str | None,
+) -> list[DurablePostFinding]:
+    if body_text is None:
+        return []
+    all_findings: list[DurablePostFinding] = []
+    if not body_text.strip():
+        all_findings.append(
+            DurablePostFinding(
+                code=EMPTY_BODY_CODE,
+                message=BODY_MUST_NOT_BE_EMPTY_MESSAGE,
+            )
+        )
+    if action in ALL_PR_DESCRIPTION_ACTIONS:
+        all_findings.extend(_description_heading_findings(body_text))
+    if find_volatile_path_marker(body_text) is not None:
+        all_findings.append(
+            DurablePostFinding(
+                code=VOLATILE_PATH_CODE,
+                message=VOLATILE_PATH_MESSAGE,
+            )
+        )
+    return all_findings
+
+
+def lint_durable_post(
+    action: str,
+    title: str | None,
+    body_text: str | None,
+) -> tuple[DurablePostFinding, ...]:
+    """Return content findings for one locally valid GitHub post request.
+
+    Args:
+        action: GitHub post action name.
+        title: Pull request title when the action accepts one.
+        body_text: Decoded body text when the action accepts a body.
+
+    Returns:
+        Content findings in stable rule order.
+
+    Raises:
+        DurablePostUsageError: The action and supplied fields are not a valid request.
+    """
+    _validate_request_shape(action, title, body_text)
+    return (*_title_findings(title), *_body_findings(action, body_text))
+
+
+def _parse_arguments(all_arguments: Sequence[str]) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description=__doc__, allow_abbrev=False)
+    parser.add_argument("--action", required=True)
+    parser.add_argument("--title")
+    parser.add_argument("--body-file", type=Path)
+    return parser.parse_args(list(all_arguments))
+
+
+def main(all_arguments: Sequence[str]) -> int:
+    """Validate one GitHub post and return its result status.
+
+    Args:
+        all_arguments: Command arguments after the script name.
+
+    Returns:
+        Zero when clean, one for content findings, or two for invalid input.
+    """
+    arguments = _parse_arguments(all_arguments)
+    try:
+        body_text = (
+            read_body_file(arguments.body_file)
+            if arguments.body_file is not None
+            else None
+        )
+        all_findings = lint_durable_post(
+            action=arguments.action,
+            title=arguments.title,
+            body_text=body_text,
+        )
+    except (DurablePostInputError, DurablePostUsageError) as error:
+        sys.stderr.write(f"{error}\n")
+        return INPUT_ERROR_EXIT_CODE
+    for each_finding in all_findings:
+        sys.stderr.write(f"{each_finding.message}\n")
+    return CONTENT_FINDING_EXIT_CODE if all_findings else CLEAN_EXIT_CODE
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))

package/.agents/skills/_shared/pr-loop/scripts/skills_pr_loop_constants/durable_post_lint_constants.py

@@ -0,0 +1,106 @@
+"""Configuration constants for durable GitHub post validation."""
+
+import re
+
+ACTION_GITHUB_MCP_POST = "github-mcp-post"
+ACTION_ISSUE_COMMENT = "issue-comment"
+ACTION_ISSUE_CREATE = "issue-create"
+ACTION_ISSUE_EDIT = "issue-edit"
+ACTION_PR_COMMENT = "pr-comment"
+ACTION_PR_CREATE = "pr-create"
+ACTION_PR_EDIT = "pr-edit"
+ACTION_PR_REVIEW = "pr-review"
+
+ALL_POST_ACTIONS: frozenset[str] = frozenset(
+    {
+        ACTION_GITHUB_MCP_POST,
+        ACTION_ISSUE_COMMENT,
+        ACTION_ISSUE_CREATE,
+        ACTION_ISSUE_EDIT,
+        ACTION_PR_COMMENT,
+        ACTION_PR_CREATE,
+        ACTION_PR_EDIT,
+        ACTION_PR_REVIEW,
+    }
+)
+
+ALL_BODY_REQUIRED_ACTIONS: frozenset[str] = frozenset(
+    {
+        ACTION_GITHUB_MCP_POST,
+        ACTION_ISSUE_COMMENT,
+        ACTION_ISSUE_CREATE,
+        ACTION_ISSUE_EDIT,
+        ACTION_PR_COMMENT,
+        ACTION_PR_CREATE,
+        ACTION_PR_REVIEW,
+    }
+)
+
+ALL_PR_DESCRIPTION_ACTIONS: frozenset[str] = frozenset(
+    {ACTION_PR_CREATE, ACTION_PR_EDIT}
+)
+
+ALL_TITLE_ACTIONS: frozenset[str] = frozenset({ACTION_PR_CREATE, ACTION_PR_EDIT})
+
+ALL_CONVENTIONAL_TITLE_TYPES: tuple[str, ...] = (
+    "build",
+    "chore",
+    "ci",
+    "docs",
+    "feat",
+    "fix",
+    "perf",
+    "refactor",
+    "revert",
+    "style",
+    "test",
+)
+
+CONVENTIONAL_TITLE_PATTERN: re.Pattern[str] = re.compile(
+    rf"^(?:{'|'.join(ALL_CONVENTIONAL_TITLE_TYPES)})(?:\([^)\r\n]+\))?!?: [^\s].*$"
+)
+
+ALL_REQUIRED_PR_DESCRIPTION_HEADINGS: tuple[str, ...] = (
+    "Summary",
+    "Description",
+    "Why",
+    "How",
+    "Verification",
+)
+
+ALL_PATH_ANCHORED_VOLATILE_PATH_MARKERS: tuple[str, ...] = (
+    ".claude-profile-a/jobs/",
+    ".claude/worktrees/",
+)
+
+ALL_BARE_VOLATILE_PATH_MARKERS: tuple[str, ...] = (
+    "appdata/local/temp",
+    "/tmp/",
+    "%temp%",
+    "$env:temp",
+    "$claude_job_dir",
+)
+
+BODY_FILE_ENCODING = "utf-8"
+CLEAN_EXIT_CODE = 0
+CONTENT_FINDING_EXIT_CODE = 1
+EMPTY_BODY_CODE = "empty-body"
+INPUT_ERROR_EXIT_CODE = 2
+PATH_ANCHOR_CHARACTER = "/"
+PATH_SEGMENT_START_CHARACTERS = "_-"
+
+BODY_FILE_UNREADABLE_MESSAGE = "body file is not readable UTF-8 text"
+BODY_REQUIRED_MESSAGE = "this action requires a body file"
+BODY_MUST_NOT_BE_EMPTY_MESSAGE = "body file must contain text"
+EDIT_INPUT_REQUIRED_MESSAGE = "pr-edit requires a title or body file"
+INVALID_ACTION_MESSAGE = "unsupported durable post action"
+INVALID_TITLE_CODE = "invalid-pr-title"
+INVALID_TITLE_MESSAGE = (
+    "pull request title does not use the repository Conventional Commit form"
+)
+MISSING_HEADING_CODE = "missing-pr-description-heading"
+MISSING_HEADING_MESSAGE_TEMPLATE = "body is missing required heading: {heading}"
+TITLE_NOT_ALLOWED_MESSAGE = "this action does not accept a title"
+TITLE_REQUIRED_MESSAGE = "pr-create requires a title"
+VOLATILE_PATH_CODE = "volatile-local-path"
+VOLATILE_PATH_MESSAGE = "body contains a volatile local artifact path"

package/.agents/skills/_shared/pr-loop/scripts/test_durable_post_lint.py

@@ -0,0 +1,332 @@
+"""Tests for action-aware durable GitHub post linting."""
+
+from __future__ import annotations
+
+import subprocess
+import sys
+from pathlib import Path
+
+import pytest
+
+_SCRIPTS_DIRECTORY = Path(__file__).resolve().parent
+if str(_SCRIPTS_DIRECTORY) not in sys.path:
+    sys.path.insert(0, str(_SCRIPTS_DIRECTORY))
+
+import durable_post_lint
+
+SCRIPT_PATH = _SCRIPTS_DIRECTORY / "durable_post_lint.py"
+VALID_PR_BODY = """## Summary
+
+Summary text.
+
+## Description
+
+Description text.
+
+## Why
+
+Why text.
+
+## How
+
+How text.
+
+## Verification
+
+Verification text.
+"""
+
+
+@pytest.mark.parametrize(
+    ("action", "title", "body_text"),
+    [
+        ("pr-create", "feat: add durable post linting", VALID_PR_BODY),
+        ("pr-edit", "fix(cli): validate post input", None),
+        ("pr-comment", None, "Comment body."),
+        ("pr-review", None, "Review body."),
+        ("issue-create", None, "Issue body."),
+        ("issue-edit", None, "Updated issue body."),
+        ("issue-comment", None, "Issue comment."),
+        ("github-mcp-post", None, "MCP body."),
+    ],
+)
+def test_all_actions_accept_valid_inputs(
+    action: str, title: str | None, body_text: str | None
+) -> None:
+    all_findings = durable_post_lint.lint_durable_post(
+        action=action,
+        title=title,
+        body_text=body_text,
+    )
+    assert all_findings == ()
+
+
+def test_unknown_action_raises_usage_error() -> None:
+    with pytest.raises(durable_post_lint.DurablePostUsageError):
+        durable_post_lint.lint_durable_post(
+            action="release-create",
+            title=None,
+            body_text="Release body.",
+        )
+
+
+@pytest.mark.parametrize(
+    ("title", "body_text"),
+    [
+        (None, VALID_PR_BODY),
+        ("feat: add durable post linting", None),
+    ],
+)
+def test_pr_create_requires_title_and_body(
+    title: str | None, body_text: str | None
+) -> None:
+    with pytest.raises(durable_post_lint.DurablePostUsageError):
+        durable_post_lint.lint_durable_post(
+            action="pr-create",
+            title=title,
+            body_text=body_text,
+        )
+
+
+def test_pr_edit_requires_one_edit_field() -> None:
+    with pytest.raises(durable_post_lint.DurablePostUsageError):
+        durable_post_lint.lint_durable_post(
+            action="pr-edit",
+            title=None,
+            body_text=None,
+        )
+
+
+@pytest.mark.parametrize(
+    "action",
+    [
+        "pr-comment",
+        "pr-review",
+        "issue-create",
+        "issue-edit",
+        "issue-comment",
+        "github-mcp-post",
+    ],
+)
+def test_body_actions_require_body(action: str) -> None:
+    with pytest.raises(durable_post_lint.DurablePostUsageError):
+        durable_post_lint.lint_durable_post(
+            action=action,
+            title=None,
+            body_text=None,
+        )
+
+
+@pytest.mark.parametrize(
+    "title",
+    [
+        "feat: add durable post linting",
+        "fix(cli): validate body files",
+        "refactor!: replace post validation",
+        "docs(skill)!: explain durable posts",
+    ],
+)
+def test_pr_titles_accept_repository_conventional_forms(title: str) -> None:
+    all_findings = durable_post_lint.lint_durable_post(
+        action="pr-edit",
+        title=title,
+        body_text=None,
+    )
+    assert all_findings == ()
+
+
+@pytest.mark.parametrize(
+    "title",
+    [
+        "Add durable post linting",
+        "feature: add durable post linting",
+        "fix(): add durable post linting",
+        "fix:add durable post linting",
+        "fix: ",
+    ],
+)
+def test_pr_titles_reject_nonconventional_forms(title: str) -> None:
+    all_findings = durable_post_lint.lint_durable_post(
+        action="pr-edit",
+        title=title,
+        body_text=None,
+    )
+    assert [each_finding.code for each_finding in all_findings] == ["invalid-pr-title"]
+
+
+@pytest.mark.parametrize(
+    "missing_heading",
+    ["Summary", "Description", "Why", "How", "Verification"],
+)
+def test_pr_body_reports_each_missing_heading(missing_heading: str) -> None:
+    body_text = VALID_PR_BODY.replace(f"## {missing_heading}\n", "")
+    all_findings = durable_post_lint.lint_durable_post(
+        action="pr-create",
+        title="feat: add durable post linting",
+        body_text=body_text,
+    )
+    assert [each_finding.message for each_finding in all_findings] == [
+        f"body is missing required heading: {missing_heading}"
+    ]
+
+
+def test_non_pr_body_needs_no_pr_headings() -> None:
+    all_findings = durable_post_lint.lint_durable_post(
+        action="issue-comment",
+        title=None,
+        body_text="A concise issue comment.",
+    )
+    assert all_findings == ()
+
+
+@pytest.mark.parametrize(
+    ("body_text", "expected_marker"),
+    [
+        (
+            r"See C:\Users\example\.claude-profile-a\jobs\job-1\artifact.png",
+            ".claude-profile-a/jobs/",
+        ),
+        (
+            r"Edited C:\Users\example\.claude\worktrees\feature\file.py",
+            ".claude/worktrees/",
+        ),
+        (
+            r"Saved in C:\Users\example\AppData\Local\Temp\report.txt",
+            "appdata/local/temp",
+        ),
+        ("Saved in /tmp/report.txt", "/tmp/"),
+        (r"Saved in %TEMP%\report.txt", "%temp%"),
+        (r"Saved in $env:TEMP\report.txt", "$env:temp"),
+        ("Saved in $CLAUDE_JOB_DIR/report.txt", "$claude_job_dir"),
+    ],
+)
+def test_volatile_path_markers_match_hook_behavior(
+    body_text: str, expected_marker: str
+) -> None:
+    assert durable_post_lint.find_volatile_path_marker(body_text) == expected_marker
+
+
+@pytest.mark.parametrize(
+    "body_text",
+    [
+        "the `.claude/worktrees/` prefix is a manifest key",
+        ".claude/worktrees/ entries are skipped by the manifest",
+        "(.claude-profile-a/jobs/) is a directory name",
+        "worktrees live under `.claude/worktrees/<name>`",
+        "the constant is `.claude/worktrees/`. Next.",
+    ],
+)
+def test_anchored_marker_near_misses_remain_allowed(body_text: str) -> None:
+    assert durable_post_lint.find_volatile_path_marker(body_text) is None
+
+
+def test_volatile_body_returns_content_finding() -> None:
+    all_findings = durable_post_lint.lint_durable_post(
+        action="issue-comment",
+        title=None,
+        body_text="Saved in /tmp/report.txt",
+    )
+    assert [each_finding.code for each_finding in all_findings] == [
+        "volatile-local-path"
+    ]
+
+
+def test_read_body_file_accepts_utf8(tmp_path: Path) -> None:
+    body_file = tmp_path / "body.md"
+    body_file.write_text("Café", encoding="utf-8")
+    assert durable_post_lint.read_body_file(body_file) == "Café"
+
+
+def test_read_body_file_rejects_missing_file(tmp_path: Path) -> None:
+    missing_file = tmp_path / "missing.md"
+    with pytest.raises(durable_post_lint.DurablePostInputError):
+        durable_post_lint.read_body_file(missing_file)
+
+
+def test_read_body_file_rejects_invalid_utf8(tmp_path: Path) -> None:
+    body_file = tmp_path / "body.md"
+    body_file.write_bytes(b"\xff\xfe")
+    with pytest.raises(durable_post_lint.DurablePostInputError):
+        durable_post_lint.read_body_file(body_file)
+
+
+def test_cli_returns_clean_exit_for_valid_pr_create(tmp_path: Path) -> None:
+    body_file = tmp_path / "body.md"
+    body_file.write_text(VALID_PR_BODY, encoding="utf-8")
+    completed_process = subprocess.run(
+        [
+            sys.executable,
+            str(SCRIPT_PATH),
+            "--action",
+            "pr-create",
+            "--title",
+            "feat: add durable post linting",
+            "--body-file",
+            str(body_file),
+        ],
+        check=False,
+        capture_output=True,
+        text=True,
+    )
+    assert completed_process.returncode == 0
+    assert completed_process.stdout == ""
+    assert completed_process.stderr == ""
+
+
+def test_cli_returns_content_exit_without_echoing_body(tmp_path: Path) -> None:
+    body_text = "private body words saved in /tmp/report.txt"
+    body_file = tmp_path / "body.md"
+    body_file.write_text(body_text, encoding="utf-8")
+    completed_process = subprocess.run(
+        [
+            sys.executable,
+            str(SCRIPT_PATH),
+            "--action",
+            "issue-comment",
+            "--body-file",
+            str(body_file),
+        ],
+        check=False,
+        capture_output=True,
+        text=True,
+    )
+    assert completed_process.returncode == 1
+    assert "volatile local artifact path" in completed_process.stderr
+    assert body_text not in completed_process.stderr
+
+
+def test_cli_returns_usage_exit_for_missing_body_file(tmp_path: Path) -> None:
+    missing_file = tmp_path / "missing.md"
+    completed_process = subprocess.run(
+        [
+            sys.executable,
+            str(SCRIPT_PATH),
+            "--action",
+            "issue-comment",
+            "--body-file",
+            str(missing_file),
+        ],
+        check=False,
+        capture_output=True,
+        text=True,
+    )
+    assert completed_process.returncode == 2
+    assert "body file is not readable" in completed_process.stderr
+
+
+def test_cli_has_no_inline_body_flag() -> None:
+    completed_process = subprocess.run(
+        [
+            sys.executable,
+            str(SCRIPT_PATH),
+            "--action",
+            "issue-comment",
+            "--body",
+            "Inline body.",
+        ],
+        check=False,
+        capture_output=True,
+        text=True,
+    )
+    assert completed_process.returncode == 2
+    assert "unrecognized arguments" in completed_process.stderr

package/.agents/skills/_shared/pr-loop/scripts/test_durable_post_lint_constants.py

@@ -0,0 +1,25 @@
+"""Tests for durable GitHub post linter constants."""
+
+from skills_pr_loop_constants.durable_post_lint_constants import (
+    ALL_CONVENTIONAL_TITLE_TYPES,
+    ALL_POST_ACTIONS,
+    CONVENTIONAL_TITLE_PATTERN,
+)
+
+
+def test_action_inventory_covers_pull_request_issue_and_tool_posts() -> None:
+    assert ALL_POST_ACTIONS == {
+        "github-mcp-post",
+        "issue-comment",
+        "issue-create",
+        "issue-edit",
+        "pr-comment",
+        "pr-create",
+        "pr-edit",
+        "pr-review",
+    }
+
+
+def test_title_pattern_uses_every_configured_type() -> None:
+    for each_title_type in ALL_CONVENTIONAL_TITLE_TYPES:
+        assert CONVENTIONAL_TITLE_PATTERN.fullmatch(f"{each_title_type}: one change")