claude-dev-env 8.17.1 → 8.19.0

package/scripts/review_closure_model.py

@@ -2,7 +2,8 @@
 
 A review bot posts a finding, the agent driving the pull request answers it or
 pushes the fix, and the thread closes. Until then the finding waits. These
-functions read the threads and the approvals conclusion, and name what waits.
+functions read the review threads, the top-level comments on the pull request,
+and the approvals conclusion, and name what waits.
 
 ::
 
@@ -10,6 +11,9 @@ functions read the threads and the approvals conclusion, and name what waits.
     thread: a bot comment, then an agent reply  -> closed
     thread: a bot comment, code since replaced  -> closed
     thread: a red circle, resolved in silence   -> open
+    top-level: a bot comment, no agent comment  -> open
+    top-level: a bot comment, then an agent one -> closed
+    top-level: the bot edits after that reply   -> open
 
 A red circle marks a finding a review states as blocking, so resolution alone
 leaves it open. The reply says what changed, or why the finding stands.
@@ -19,6 +23,7 @@ from __future__ import annotations
 
 from collections.abc import Iterable, Mapping, Sequence
 from dataclasses import dataclass
+from datetime import datetime
 
 from dev_env_scripts_constants.review_closure_constants import (
     ALL_BLOCKING_CONCLUSIONS,
@@ -37,7 +42,9 @@ from dev_env_scripts_constants.review_closure_constants import (
     COMMENT_IDENTIFIER_KEY,
     COMMENT_IDS_KEY,
     COMMENT_NODES_KEY,
+    CREATED_AT_KEY,
     HEAD_KEY,
+    HTML_URL_KEY,
     NUMBER_KEY,
     OPEN_DETAIL_TEMPLATE,
     OPEN_VERDICT_LABEL,
@@ -46,8 +53,10 @@ from dev_env_scripts_constants.review_closure_constants import (
     SHA_KEY,
     SHORT_SHA_LENGTH,
     THREAD_PATH_KEY,
+    TOP_LEVEL_OPEN_REASON_TEMPLATE,
     UNANSWERED_OPEN_REASON,
     UNNAMED_THREAD_SUBJECT,
+    UPDATED_AT_KEY,
     USER_KEY,
     VERDICT_LINE_TEMPLATE,
 )
@@ -71,6 +80,17 @@ class ReviewThread:
     all_comments: tuple[ReviewComment, ...]
 
 
+@dataclass(frozen=True)
+class TopLevelComment:
+    """One comment on the pull request itself, outside any review thread."""
+
+    identifier: object
+    author_login: str
+    created_at: datetime
+    updated_at: datetime
+    url: str
+
+
 @dataclass(frozen=True)
 class OpenFinding:
     """One finding that still waits on the agent driving the pull request."""
@@ -150,8 +170,91 @@ def thread_finding(
     return OpenFinding(subject=thread.subject, reason=UNANSWERED_OPEN_REASON)
 
 
+def latest_driver_comment_time(
+    all_comments: Iterable[TopLevelComment],
+    all_driver_logins: frozenset[str],
+) -> datetime | None:
+    """Find when the driving agent last posted a top-level comment.
+
+    Args:
+        all_comments: The top-level comments on the pull request.
+        all_driver_logins: The logins that count as the driving agent.
+
+    Returns:
+        The creation time of the driving agent's latest top-level comment, or
+        None when it posted none.
+    """
+    return max(
+        (
+            each_comment.created_at
+            for each_comment in all_comments
+            if each_comment.author_login in all_driver_logins
+        ),
+        default=None,
+    )
+
+
+def top_level_finding(
+    comment: TopLevelComment,
+    all_driver_logins: frozenset[str],
+    latest_driver_time: datetime | None,
+) -> OpenFinding | None:
+    """Decide whether one top-level comment still waits on the driving agent.
+
+    Args:
+        comment: The top-level comment to judge.
+        all_driver_logins: The logins whose comments count as the answer.
+        latest_driver_time: When the driving agent last posted a top-level
+            comment, or None when it posted none.
+
+    Returns:
+        The finding this comment leaves open, or None when it is answered.
+    """
+    if comment.author_login in all_driver_logins:
+        return None
+    if latest_driver_time is not None and comment.updated_at <= latest_driver_time:
+        return None
+    return OpenFinding(
+        subject=comment.url,
+        reason=TOP_LEVEL_OPEN_REASON_TEMPLATE.format(author=comment.author_login),
+    )
+
+
+def top_level_findings(
+    all_comments: Iterable[TopLevelComment],
+    all_driver_logins: frozenset[str],
+) -> tuple[OpenFinding, ...]:
+    """Decide which top-level comments still wait on the driving agent.
+
+    The driving agent answers a top-level comment by posting a top-level
+    comment of its own. Its latest one answers every comment last touched
+    before it, and a comment edited after it waits again.
+
+    Args:
+        all_comments: The top-level comments on the pull request.
+        all_driver_logins: The logins whose comments count as the answer.
+
+    Returns:
+        One finding per comment from another account that was posted or
+        edited after the driving agent's latest top-level comment.
+    """
+    all_listed_comments = tuple(all_comments)
+    latest_driver_time = latest_driver_comment_time(
+        all_listed_comments, all_driver_logins
+    )
+    return tuple(
+        each_finding
+        for each_finding in (
+            top_level_finding(each_comment, all_driver_logins, latest_driver_time)
+            for each_comment in all_listed_comments
+        )
+        if each_finding is not None
+    )
+
+
 def all_open_findings(
     all_threads: Iterable[ReviewThread],
+    all_top_level_comments: Iterable[TopLevelComment],
     all_driver_logins: frozenset[str],
     approvals_conclusion_text: str | None,
 ) -> tuple[OpenFinding, ...]:
@@ -159,13 +262,15 @@ def all_open_findings(
 
     Args:
         all_threads: The review threads on the pull request.
+        all_top_level_comments: The comments on the pull request itself.
         all_driver_logins: The logins whose comments count as the answer.
         approvals_conclusion_text: What the Claude Approvals check run on the
             head concluded, or None where that check does not run.
 
     Returns:
-        One finding per open review thread, then the approvals finding when
-        that check reports a blocking row on this commit.
+        One finding per open review thread, then one per waiting top-level
+        comment, then the approvals finding when that check reports a
+        blocking row on this commit.
     """
     all_findings = [
         each_finding
@@ -175,6 +280,7 @@ def all_open_findings(
         )
         if each_finding is not None
     ]
+    all_findings.extend(top_level_findings(all_top_level_comments, all_driver_logins))
     if approvals_conclusion_text in ALL_BLOCKING_CONCLUSIONS:
         all_findings.append(
             OpenFinding(subject=APPROVALS_CHECK_NAME, reason=APPROVALS_OPEN_REASON)
@@ -301,6 +407,29 @@ def comment_records_by_id(
     }
 
 
+def parse_top_level_comment(
+    all_comment_fields: Mapping[str, object],
+) -> TopLevelComment:
+    """Read one top-level comment from the REST answer.
+
+    Args:
+        all_comment_fields: The comment as the issue comments route reports it.
+
+    Returns:
+        The comment in the shape the closure decision reads.
+
+    Raises:
+        ValueError: A timestamp is missing or does not parse.
+    """
+    return TopLevelComment(
+        identifier=all_comment_fields.get(COMMENT_IDENTIFIER_KEY),
+        author_login=_comment_author_login(all_comment_fields),
+        created_at=datetime.fromisoformat(str(all_comment_fields.get(CREATED_AT_KEY))),
+        updated_at=datetime.fromisoformat(str(all_comment_fields.get(UPDATED_AT_KEY))),
+        url=str(all_comment_fields.get(HTML_URL_KEY) or ""),
+    )
+
+
 def approvals_conclusion(all_check_runs: Iterable[object]) -> str | None:
     """Find what the Claude Approvals check reports on a commit.
 

package/scripts/test_digest_check.py

@@ -0,0 +1,147 @@
+"""Tests for the digest page check."""
+
+from __future__ import annotations
+
+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 digest_check
+from dev_env_scripts_constants.digest_check_constants import (
+    CARD_WORD_BUDGET,
+    LEAD_WORD_BUDGET,
+)
+
+PICTURE = '<svg viewBox="0 0 10 10"><rect width="10" height="10"/></svg>'
+
+
+def _card(card_id: str, words: str, picture: str = PICTURE) -> str:
+    return f'<section data-digest-card="{card_id}">{picture}<p>{words}</p></section>'
+
+
+def _page(*all_parts: str, lead: str = "Merged today") -> str:
+    body = "".join(all_parts)
+    return (
+        "<!doctype html><html><head><title>Digest</title>"
+        "<style>p{margin:0}</style></head>"
+        f"<body><h1>{lead}</h1>{body}"
+        "<script>const words = 'one two three four five';</script></body></html>"
+    )
+
+
+def _findings(page_html: str, all_expected_ids: list[str]) -> list[str]:
+    page = digest_check.read_digest_page(page_html)
+    return digest_check.digest_findings(page, all_expected_ids)
+
+
+def test_page_covering_every_card_briefly_with_pictures_passes() -> None:
+    page_html = _page(
+        _card("4701", "Search now keeps your filters."),
+        _card("4702", "Exports finish twice as fast."),
+    )
+    assert _findings(page_html, ["4701", "4702"]) == []
+
+
+def test_page_leaving_out_an_expected_card_reports_it() -> None:
+    page_html = _page(_card("4701", "Search now keeps your filters."))
+    assert _findings(page_html, ["4701", "4715"]) == [
+        "missing card 4715: the page leaves it out"
+    ]
+
+
+def test_card_over_the_word_budget_reports_its_count() -> None:
+    long_words = " ".join(["word"] * (CARD_WORD_BUDGET + 1))
+    page_html = _page(_card("4701", long_words))
+    assert _findings(page_html, ["4701"]) == [
+        f"card 4701 carries {CARD_WORD_BUDGET + 1} words; "
+        f"the budget is {CARD_WORD_BUDGET}"
+    ]
+
+
+def test_card_at_the_word_budget_passes() -> None:
+    page_html = _page(_card("4701", " ".join(["word"] * CARD_WORD_BUDGET)))
+    assert _findings(page_html, ["4701"]) == []
+
+
+def test_card_without_a_picture_reports_it() -> None:
+    page_html = _page(_card("4701", "Search now keeps your filters.", picture=""))
+    assert _findings(page_html, ["4701"]) == ["card 4701 has no picture"]
+
+
+def test_self_closing_image_counts_as_a_picture() -> None:
+    page_html = _page(
+        _card("4701", "Search now keeps your filters.", picture='<img src="a.png"/>')
+    )
+    assert _findings(page_html, ["4701"]) == []
+
+
+def test_lead_text_over_its_budget_reports_the_count() -> None:
+    long_lead = " ".join(["word"] * (LEAD_WORD_BUDGET + 1))
+    page_html = _page(_card("4701", "Search now keeps your filters."), lead=long_lead)
+    assert _findings(page_html, ["4701"]) == [
+        f"text outside the cards carries {LEAD_WORD_BUDGET + 1} words; "
+        f"the budget is {LEAD_WORD_BUDGET}"
+    ]
+
+
+def test_head_script_and_style_text_stay_out_of_the_count() -> None:
+    page = digest_check.read_digest_page(_page(lead="Merged today"))
+    assert page.lead_word_count == 2
+
+
+def test_picture_label_text_counts_toward_its_card() -> None:
+    labelled_picture = "<svg><text>before after</text></svg>"
+    page = digest_check.read_digest_page(
+        _page(_card("4701", "one two", picture=labelled_picture))
+    )
+    assert [each_card.word_count for each_card in page.all_cards] == [4]
+
+
+def test_card_marked_twice_reports_the_duplicate() -> None:
+    page_html = _page(
+        _card("4701", "Search now keeps your filters."),
+        _card("4701", "Search now keeps your filters."),
+    )
+    assert _findings(page_html, ["4701"]) == ["card 4701 appears 2 times"]
+
+
+def test_main_exits_one_and_prints_findings_for_a_missing_card(
+    tmp_path: Path, capsys: pytest.CaptureFixture[str]
+) -> None:
+    page_path = tmp_path / "digest.html"
+    page_path.write_text(_page(_card("4701", "Search keeps filters.")), encoding="utf-8")
+    exit_code = digest_check.main([str(page_path), "--expect", "4701", "4702"])
+    assert exit_code == 1
+    assert capsys.readouterr().out == "missing card 4702: the page leaves it out\n"
+
+
+def test_main_exits_zero_and_names_the_count_for_a_clean_page(
+    tmp_path: Path, capsys: pytest.CaptureFixture[str]
+) -> None:
+    page_path = tmp_path / "digest.html"
+    page_path.write_text(_page(_card("4701", "Search keeps filters.")), encoding="utf-8")
+    exit_code = digest_check.main([str(page_path), "--expect", "4701"])
+    assert exit_code == 0
+    assert capsys.readouterr().out == "CLEAN: 1 cards, every one present\n"
+
+
+def test_markup_inside_a_script_leaves_the_cards_intact() -> None:
+    page_html = _page(
+        "<script>if (a<b) { x = '<div data-digest-card=\"9\">'; }</script>",
+        _card("4701", "Search keeps filters."),
+    )
+    assert _findings(page_html, ["4701"]) == []
+
+
+def test_single_quoted_card_marker_and_entities_parse() -> None:
+    page = digest_check.read_digest_page(
+        f"<div data-digest-card='4701'>{PICTURE}<p>Fish &amp; chips</p></div>"
+    )
+    assert [(each_card.card_id, each_card.word_count) for each_card in page.all_cards] == [
+        ("4701", 2)
+    ]

package/scripts/tests/test_adapter_configuration.py

@@ -50,6 +50,14 @@ def test_new_bash_pre_tool_use_dispatcher_registration_is_clean(tmp_path: Path)
     assert adapters.hook_configuration_diagnostics(current_document, tmp_path) == ()
 
 
+def test_new_step_note_gate_registration_is_clean(tmp_path: Path) -> None:
+    current_document = _hook_document(
+        ["hooks/blocking/step_note_gate.py"],
+        '{"hooks": {}}',
+    )
+    assert adapters.hook_configuration_diagnostics(current_document, tmp_path) == ()
+
+
 def test_new_blocker_in_staged_change_is_rejected(tmp_path: Path) -> None:
     current_document = _hook_document(
         ["hooks/blocking/new.py"],

package/scripts/tests/test_policy_lint_rules_callers.py

@@ -23,10 +23,12 @@ def _write(repository_root: Path, relative_path: str, text: str) -> None:
     target.write_text(text, "utf-8")
 
 
-def _added(relative_path: str, prior_text: str | None = None) -> Document:
+def _added(
+    relative_path: str, prior_text: str | None = None, text: str = "print('hi')\n"
+) -> Document:
     return Document(
         PurePosixPath(relative_path),
-        "print('hi')\n",
+        text,
         prior_text,
         None,
         ContentOrigin.REVISION_DIFF,
@@ -138,3 +140,30 @@ def test_should_report_new_ci_and_tools_helpers_only_tests_name(
     all_messages = _messages(tmp_path, (_added(ci_helper), _added(tools_helper)))
 
     assert len(all_messages) == 2
+
+
+def test_should_pass_a_new_module_that_a_called_new_script_imports(
+    tmp_path: Path,
+) -> None:
+    constants_path = f"{_PACKAGE}/scripts/constants/lonely_watcher_constants.py"
+    script_text = "from constants.lonely_watcher_constants import LIMIT\n"
+    _write(tmp_path, _NEW_SCRIPT, script_text)
+    _write(tmp_path, constants_path, "LIMIT = 3\n")
+    _write(tmp_path, ".github/workflows/ci.yml", f"run: python {_NEW_SCRIPT}\n")
+
+    all_documents = (_added(_NEW_SCRIPT, text=script_text), _added(constants_path))
+
+    assert _messages(tmp_path, all_documents) == ()
+
+
+def test_should_report_a_new_module_only_an_uncalled_new_script_imports(
+    tmp_path: Path,
+) -> None:
+    constants_path = f"{_PACKAGE}/scripts/constants/lonely_watcher_constants.py"
+    script_text = "from constants.lonely_watcher_constants import LIMIT\n"
+    _write(tmp_path, _NEW_SCRIPT, script_text)
+    _write(tmp_path, constants_path, "LIMIT = 3\n")
+
+    all_documents = (_added(_NEW_SCRIPT, text=script_text), _added(constants_path))
+
+    assert len(_messages(tmp_path, all_documents)) == 2

package/scripts/tests/test_review_closure.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import sys
+from datetime import datetime
 from pathlib import Path
 
 import pytest
@@ -51,10 +52,14 @@ def stub_reads(
     monkeypatch: pytest.MonkeyPatch,
     all_threads: tuple[model.ReviewThread, ...],
     conclusion: str | None = "success",
+    all_top_level_comments: tuple[model.TopLevelComment, ...] = (),
 ) -> None:
     monkeypatch.setattr(command, "github_token", lambda: "a-token")
     monkeypatch.setattr(command, "read_pull_request", lambda *_: PULL_REQUEST)
     monkeypatch.setattr(command, "read_review_threads", lambda *_: all_threads)
+    monkeypatch.setattr(
+        command, "read_top_level_comments", lambda *_: all_top_level_comments
+    )
     monkeypatch.setattr(command, "read_approvals_conclusion", lambda *_: conclusion)
 
 
@@ -124,3 +129,23 @@ def should_exit_two_when_the_state_could_not_be_read(
 
     assert status == 2
     assert "refused" in capsys.readouterr().err
+
+
+def should_print_the_url_of_a_waiting_top_level_comment(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    summary_url = "https://github.com/jl-cmd/claude-dev-env/pull/7#issuecomment-1"
+    posted = datetime.fromisoformat("2026-09-26T12:00:00+00:00")
+    bot_summary = model.TopLevelComment(
+        identifier=1,
+        author_login="qodo-merge-pro[bot]",
+        created_at=posted,
+        updated_at=posted,
+        url=summary_url,
+    )
+    stub_reads(monkeypatch, (answered_thread(),), all_top_level_comments=(bot_summary,))
+
+    status = command.main([SLUG, "7"])
+
+    assert status == 1
+    assert summary_url in capsys.readouterr().out

package/scripts/tests/test_review_closure_github.py

@@ -238,3 +238,54 @@ def should_report_a_check_run_answer_of_the_wrong_shape(
 
     with pytest.raises(GitHubError):
         reader.read_approvals_conclusion("jl-cmd/claude-dev-env", "ab845eb", TOKEN)
+
+
+def top_level_record(identifier: int) -> dict[str, object]:
+    return {
+        "id": identifier,
+        "user": {"login": "qodo-merge-pro[bot]"},
+        "created_at": "2026-09-26T12:00:00Z",
+        "updated_at": "2026-09-26T12:00:00Z",
+        "html_url": (
+            f"https://github.com/jl-cmd/claude-dev-env/pull/7#issuecomment-{identifier}"
+        ),
+    }
+
+
+def should_read_the_second_page_of_top_level_comments(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    all_requested_urls = answer_with(
+        monkeypatch,
+        {
+            "issues/7/comments?per_page=100&page=1": (
+                200,
+                [top_level_record(each) for each in range(100)],
+            ),
+            "issues/7/comments?per_page=100&page=2": (200, [top_level_record(100)]),
+        },
+    )
+
+    all_comments = reader.read_top_level_comments("jl-cmd/claude-dev-env", 7, TOKEN)
+
+    assert len(all_comments) == 101
+    assert all_comments[-1].identifier == 100
+    assert len(all_requested_urls) == 2
+
+
+def should_report_a_top_level_comment_page_of_the_wrong_shape(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    answer_with(monkeypatch, {"issues/7/comments": (200, {"message": "not a list"})})
+
+    with pytest.raises(GitHubError):
+        reader.read_top_level_comments("jl-cmd/claude-dev-env", 7, TOKEN)
+
+
+def should_report_a_top_level_comment_without_timestamps(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    answer_with(monkeypatch, {"issues/7/comments": (200, [{"id": 1}])})
+
+    with pytest.raises(GitHubError):
+        reader.read_top_level_comments("jl-cmd/claude-dev-env", 7, TOKEN)