claude-dev-env 8.117.2 → 8.117.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (77) hide show
  1. package/_shared/pr-loop/scripts/pyproject.toml +1 -1
  2. package/_shared/process-tree/scripts/pyproject.toml +1 -1
  3. package/bin/cde.mjs +4 -3
  4. package/bin/cde.test.mjs +87 -1
  5. package/bin/codex-compat.mjs +4 -3
  6. package/bin/codex-compat.test.mjs +91 -1
  7. package/bin/install-plan.mjs +2 -1
  8. package/bin/install.mjs +24 -7
  9. package/bin/install.plan.test.mjs +15 -0
  10. package/bin/install.test.mjs +61 -0
  11. package/bin/python-probe.mjs +42 -0
  12. package/bin/python-probe.test.mjs +19 -2
  13. package/docs/rule-guides/features-start-with-an-eval.md +3 -3
  14. package/docs/rule-guides/proof-before-pull-request.md +2 -2
  15. package/hooks/blocking/bash_pre_tool_use_dispatcher.py +11 -4
  16. package/hooks/blocking/build_eval_before_eval_write_gate.py +10 -4
  17. package/hooks/blocking/followup_pr_dedupe.py +381 -64
  18. package/hooks/blocking/gate_child_process.py +187 -0
  19. package/hooks/blocking/gate_run_reads.py +116 -35
  20. package/hooks/blocking/merge_review_gate.py +93 -10
  21. package/hooks/blocking/merge_review_gate_parts/create_folders.py +346 -0
  22. package/hooks/blocking/merge_review_gate_parts/create_options.py +86 -0
  23. package/hooks/blocking/merge_review_gate_parts/folder_state.py +107 -0
  24. package/hooks/blocking/merge_review_gate_parts/open_request.py +199 -64
  25. package/hooks/blocking/merge_review_gate_parts/quoted_lines.py +283 -0
  26. package/hooks/blocking/merge_review_gate_parts/wrapped_creates.py +126 -0
  27. package/hooks/blocking/pr_lifecycle_skill_gate.py +61 -18
  28. package/hooks/blocking/pre_tool_use_dispatcher.py +25 -3
  29. package/hooks/blocking/pull_request_proof.py +5 -51
  30. package/hooks/blocking/pull_request_proof_edit_gate.py +19 -5
  31. package/hooks/blocking/test_bash_pre_tool_use_dispatcher.py +54 -0
  32. package/hooks/blocking/test_build_eval_before_eval_write_gate.py +64 -0
  33. package/hooks/blocking/test_followup_pr_dedupe.py +464 -1
  34. package/hooks/blocking/test_gate_child_process.py +64 -0
  35. package/hooks/blocking/test_gate_run_reads.py +364 -4
  36. package/hooks/blocking/test_merge_review_gate.py +832 -39
  37. package/hooks/blocking/test_pr_lifecycle_skill_gate.py +130 -4
  38. package/hooks/blocking/test_pre_tool_use_dispatcher.py +64 -0
  39. package/hooks/blocking/test_pull_request_proof.py +16 -0
  40. package/hooks/blocking/test_pull_request_proof_edit_gate.py +60 -0
  41. package/hooks/blocking/tests/test_create_folders.py +290 -0
  42. package/hooks/blocking/tests/test_create_options.py +34 -0
  43. package/hooks/blocking/tests/test_folder_state.py +40 -0
  44. package/hooks/blocking/tests/test_open_request.py +350 -44
  45. package/hooks/blocking/tests/test_quoted_lines.py +86 -0
  46. package/hooks/blocking/tests/test_wrapped_creates.py +42 -0
  47. package/hooks/features/bash-dispatchers.md +1 -1
  48. package/hooks/features/conduct-gates.md +7 -7
  49. package/hooks/features/write-edit-blocking.md +3 -3
  50. package/hooks/hooks_constants/build_eval_before_eval_write_gate_constants.py +5 -0
  51. package/hooks/hooks_constants/followup_pr_dedupe_constants.py +34 -1
  52. package/hooks/hooks_constants/gate_fault.py +52 -0
  53. package/hooks/hooks_constants/gate_fault_constants.py +13 -0
  54. package/hooks/hooks_constants/gate_run_reads_constants.py +9 -1
  55. package/hooks/hooks_constants/merge_review_gate_constants.py +94 -1
  56. package/hooks/hooks_constants/piped_pytest_blocker_constants.py +2 -0
  57. package/hooks/hooks_constants/pr_lifecycle_skill_gate_constants.py +6 -1
  58. package/hooks/hooks_constants/pre_tool_use_stdin.py +23 -3
  59. package/hooks/hooks_constants/shell_command_pipeline.py +68 -8
  60. package/hooks/hooks_constants/shell_command_segments.py +2 -2
  61. package/hooks/hooks_constants/shell_command_wrappers.py +3 -2
  62. package/hooks/hooks_constants/test_followup_pr_dedupe_constants.py +7 -0
  63. package/hooks/hooks_constants/test_gate_fault.py +41 -0
  64. package/hooks/hooks_constants/test_piped_pytest_blocker_constants.py +5 -0
  65. package/hooks/hooks_constants/test_pr_lifecycle_skill_gate_constants.py +10 -0
  66. package/hooks/hooks_constants/test_pre_tool_use_stdin.py +97 -0
  67. package/hooks/hooks_constants/test_shell_command_pipeline.py +55 -0
  68. package/hooks/hooks_constants/test_shell_command_segments.py +15 -0
  69. package/hooks/hooks_constants/test_shell_command_wrappers.py +6 -0
  70. package/hooks/hooks_constants/transcript_skill_scan_constants.py +6 -0
  71. package/hooks/pyproject.toml +2 -3
  72. package/hooks/test_python_floor.py +197 -0
  73. package/hooks/test_transcript_skill_scan.py +324 -0
  74. package/hooks/transcript_skill_scan.py +233 -2
  75. package/hooks/validators/code_quality_checks.py +119 -17
  76. package/hooks/validators/test_code_quality_checks.py +110 -4
  77. package/package.json +1 -1
@@ -70,6 +70,7 @@ __all__ = [
70
70
  "all_wrapped_command_segments",
71
71
  "all_command_substitution_texts",
72
72
  "evaluated_inner_command",
73
+ "quoted_line_breaks_joined",
73
74
  ]
74
75
 
75
76
 
@@ -293,7 +294,7 @@ def evaluated_inner_command(all_segment_tokens: list[str]) -> str | None:
293
294
  return None
294
295
 
295
296
 
296
- def _quoted_line_breaks_joined(command: str) -> str:
297
+ def quoted_line_breaks_joined(command: str) -> str:
297
298
  """Return a copy of the command that holds a space at each quoted line break.
298
299
 
299
300
  The pipeline parser splits a command at every line break, so a quoted
@@ -320,7 +321,7 @@ def _inner_commands(command: str, all_command_segments: list[list[str]]) -> list
320
321
 
321
322
  A copy of the command with its quoted line breaks joined comes last when it differs.
322
323
  """
323
- joined_command = _quoted_line_breaks_joined(command)
324
+ joined_command = quoted_line_breaks_joined(command)
324
325
  all_inner_commands = [
325
326
  joined_command if joined_command != command else None,
326
327
  *(string_exec_inner_command(each_segment) for each_segment in all_command_segments),
@@ -6,3 +6,10 @@ from hooks_constants import followup_pr_dedupe_constants as constants
6
6
  def test_parent_pattern_reads_both_spellings_and_stops_at_the_number() -> None:
7
7
  assert re.search(constants.FOLLOWUP_PARENT_PATTERN, "followup to #12", re.IGNORECASE)
8
8
  assert re.search(constants.FOLLOWUP_PARENT_PATTERN, "Follow-up to #1731", re.IGNORECASE).group(1) == "1731"
9
+
10
+
11
+ def test_python_program_pattern_should_read_versioned_and_launcher_names_only() -> None:
12
+ for each_name in ("python", "python3", "python3.11", "python3.13", "pythonw", "py", "pyw"):
13
+ assert re.fullmatch(constants.PYTHON_PROGRAM_NAME_PATTERN, each_name)
14
+ for each_name in ("pytest", "pyright", "python-config", "ipython"):
15
+ assert re.fullmatch(constants.PYTHON_PROGRAM_NAME_PATTERN, each_name) is None
@@ -0,0 +1,41 @@
1
+ """Tests for the wording a gate gives when one of its checks raises."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from hooks_constants.gate_fault import gate_fault_reason, gate_fault_system_message
6
+ from hooks_constants.gate_fault_constants import GATE_FAULT_TEXT_CHARACTER_LIMIT
7
+
8
+
9
+ def test_reason_names_the_gate_the_error_type_and_the_text() -> None:
10
+ reason = gate_fault_reason("merge review", KeyError("head"))
11
+ assert reason.startswith("The merge review gate hit a fault")
12
+ assert "KeyError: 'head'" in reason
13
+ assert "refused" in reason
14
+
15
+
16
+ def test_reason_caps_the_error_text() -> None:
17
+ reason = gate_fault_reason(
18
+ "merge review", ValueError("x" * (GATE_FAULT_TEXT_CHARACTER_LIMIT * 3))
19
+ )
20
+ assert "x" * GATE_FAULT_TEXT_CHARACTER_LIMIT in reason
21
+ assert "x" * (GATE_FAULT_TEXT_CHARACTER_LIMIT + 1) not in reason
22
+
23
+
24
+ def test_system_message_names_the_script_the_error_and_that_the_call_was_not_checked() -> None:
25
+ message = gate_fault_system_message("verify_before_commit_gate.py", RuntimeError("probe broke"))
26
+ assert "verify_before_commit_gate.py" in message
27
+ assert "RuntimeError: probe broke" in message
28
+ assert "did not check this call" in message
29
+
30
+
31
+ def test_system_message_does_not_say_the_call_is_refused() -> None:
32
+ message = gate_fault_system_message("verify_before_commit_gate.py", RuntimeError("probe broke"))
33
+ assert "refused" not in message
34
+
35
+
36
+ def test_system_message_caps_the_error_text() -> None:
37
+ message = gate_fault_system_message(
38
+ "merge_review_gate.py", ValueError("y" * (GATE_FAULT_TEXT_CHARACTER_LIMIT * 3))
39
+ )
40
+ assert "y" * GATE_FAULT_TEXT_CHARACTER_LIMIT in message
41
+ assert "y" * (GATE_FAULT_TEXT_CHARACTER_LIMIT + 1) not in message
@@ -23,3 +23,8 @@ def test_shell_keywords_and_builtins_step_to_the_command_they_run() -> None:
23
23
  )
24
24
  assert "-a" in constants.ALL_WRAPPER_OPTION_GRAMMARS_BY_NAME["exec"].all_value_taking_options
25
25
  assert "-p" in constants.ALL_WRAPPER_OPTION_GRAMMARS_BY_NAME["command"].all_flag_options
26
+
27
+
28
+ def test_linear_time_lexer_starts_past_a_typed_command_length() -> None:
29
+ assert constants.LINEAR_TIME_LEXER_MINIMUM_LENGTH == 4096
30
+ assert constants.LINEAR_TIME_LEXER_MINIMUM_LENGTH > len("git push origin head " * 100)
@@ -10,3 +10,13 @@ def test_gate_targets_the_named_skill_and_pre_tool_use() -> None:
10
10
  def test_gate_covers_shells_and_pull_request_tools() -> None:
11
11
  assert constants.SHELL_TOOL_NAMES == {"Bash", "PowerShell"}
12
12
  assert len(constants.ALL_GITHUB_MCP_TOOL_SUFFIXES) == 4
13
+
14
+
15
+ def test_scan_sentence_should_join_a_deny_reason_and_name_both_repairs() -> None:
16
+ assert constants.SCAN_RAN_OUT_SENTENCE.startswith(" ")
17
+ assert "loading the skill again" in constants.SCAN_RAN_OUT_SENTENCE
18
+ assert "build-eval again" in constants.SCAN_RAN_OUT_SENTENCE
19
+
20
+
21
+ def test_gate_name_should_read_as_a_noun_phrase_in_the_fault_reason() -> None:
22
+ assert constants.GATE_NAME == "pull request lifecycle"
@@ -6,9 +6,11 @@ import inspect
6
6
  import io
7
7
  import json
8
8
  import sys
9
+ from collections.abc import Callable
9
10
  from unittest.mock import patch
10
11
 
11
12
  from hooks_constants import pre_tool_use_stdin
13
+ from hooks_constants.gate_fault_constants import GATE_FAULT_TEXT_CHARACTER_LIMIT
12
14
  from hooks_constants.pre_tool_use_stdin import read_hook_input_dictionary_from_stdin
13
15
 
14
16
 
@@ -101,3 +103,98 @@ def test_read_returns_none_for_an_integer_past_the_digit_limit() -> None:
101
103
  oversized_payload = '{"tool_name": "Bash", "tool_use_id": ' + "7" * 6000 + "}"
102
104
  with patch("sys.stdin", io.StringIO(oversized_payload)):
103
105
  assert read_hook_input_dictionary_from_stdin() is None
106
+
107
+
108
+ def _raise_from_check(payload: dict[str, object]) -> dict[str, object] | None:
109
+ raise RuntimeError("probe broke on " + str(payload["tool_name"]))
110
+
111
+
112
+ def _run_with_raising_check(
113
+ error_check: Callable[[dict[str, object]], dict[str, object] | None] = _raise_from_check,
114
+ ) -> tuple[int, str, str]:
115
+ captured_stdout = io.StringIO()
116
+ error_output = io.StringIO()
117
+ with (
118
+ patch("sys.stdin", io.StringIO('{"tool_name": "Bash"}')),
119
+ patch("sys.stdout", captured_stdout),
120
+ patch("sys.stderr", error_output),
121
+ patch("sys.argv", ["/plugin/hooks/blocking/verify_before_commit_gate.py"]),
122
+ ):
123
+ exit_code = pre_tool_use_stdin.print_decision_from_stdin(error_check)
124
+ return exit_code, captured_stdout.getvalue(), error_output.getvalue()
125
+
126
+
127
+ def test_print_decision_from_stdin_returns_zero_when_the_check_raises() -> None:
128
+ exit_code, _, _ = _run_with_raising_check()
129
+ assert exit_code == 0
130
+
131
+
132
+ def test_print_decision_from_stdin_prints_one_system_message_line_when_the_check_raises() -> None:
133
+ _, standard_output, _ = _run_with_raising_check()
134
+ all_lines = standard_output.splitlines()
135
+ assert len(all_lines) == 1
136
+ decision = json.loads(all_lines[0])
137
+ assert set(decision) == {"systemMessage"}
138
+ assert "hookSpecificOutput" not in decision
139
+ assert "permissionDecision" not in standard_output
140
+
141
+
142
+ def test_print_decision_from_stdin_fault_message_names_the_script_file_and_the_error() -> None:
143
+ _, standard_output, _ = _run_with_raising_check()
144
+ message = json.loads(standard_output)["systemMessage"]
145
+ assert "verify_before_commit_gate.py" in message
146
+ assert "/plugin/hooks/blocking" not in message
147
+ assert "RuntimeError: probe broke on Bash" in message
148
+ assert "did not check this call" in message
149
+
150
+
151
+ def test_print_decision_from_stdin_fault_message_caps_the_error_text() -> None:
152
+ long_text = "z" * (GATE_FAULT_TEXT_CHARACTER_LIMIT * 3)
153
+
154
+ def raise_long_error(payload: dict[str, object]) -> dict[str, object] | None:
155
+ raise ValueError(long_text)
156
+
157
+ _, standard_output, _ = _run_with_raising_check(raise_long_error)
158
+ message = json.loads(standard_output)["systemMessage"]
159
+ assert "z" * GATE_FAULT_TEXT_CHARACTER_LIMIT in message
160
+ assert "z" * (GATE_FAULT_TEXT_CHARACTER_LIMIT + 1) not in message
161
+
162
+
163
+ def test_print_decision_from_stdin_writes_the_traceback_to_standard_error() -> None:
164
+ _, _, standard_error = _run_with_raising_check()
165
+ assert "Traceback" in standard_error
166
+ assert standard_error.rstrip().splitlines()[-1] == "RuntimeError: probe broke on Bash"
167
+
168
+
169
+ def test_print_decision_from_stdin_writes_a_returned_deny_unchanged() -> None:
170
+ deny_decision = {
171
+ "hookSpecificOutput": {
172
+ "hookEventName": "PreToolUse",
173
+ "permissionDecision": "deny",
174
+ "permissionDecisionReason": "blocked",
175
+ }
176
+ }
177
+ captured_stdout = io.StringIO()
178
+ error_output = io.StringIO()
179
+ with (
180
+ patch("sys.stdin", io.StringIO('{"tool_name": "Bash"}')),
181
+ patch("sys.stdout", captured_stdout),
182
+ patch("sys.stderr", error_output),
183
+ ):
184
+ exit_code = pre_tool_use_stdin.print_decision_from_stdin(lambda payload: deny_decision)
185
+ assert exit_code == 0
186
+ assert captured_stdout.getvalue().splitlines() == [json.dumps(deny_decision)]
187
+ assert error_output.getvalue() == ""
188
+
189
+
190
+ def test_print_decision_from_stdin_stays_silent_on_both_streams_for_none() -> None:
191
+ captured_stdout = io.StringIO()
192
+ error_output = io.StringIO()
193
+ with (
194
+ patch("sys.stdin", io.StringIO('{"tool_name": "Bash"}')),
195
+ patch("sys.stdout", captured_stdout),
196
+ patch("sys.stderr", error_output),
197
+ ):
198
+ assert pre_tool_use_stdin.print_decision_from_stdin(lambda payload: None) == 0
199
+ assert captured_stdout.getvalue() == ""
200
+ assert error_output.getvalue() == ""
@@ -6,8 +6,13 @@ compound shells. No pytest-specific classification runs here.
6
6
 
7
7
  from __future__ import annotations
8
8
 
9
+ import itertools
9
10
  import pathlib
11
+ import shlex
10
12
  import sys
13
+ import time
14
+
15
+ import pytest
11
16
 
12
17
  _HOOKS_ROOT = pathlib.Path(__file__).resolve().parent.parent
13
18
  if str(_HOOKS_ROOT) not in sys.path:
@@ -17,6 +22,7 @@ from hooks_constants.shell_command_pipeline import ( # noqa: E402
17
22
  all_operator_aware_tokenizations,
18
23
  join_line_continuations,
19
24
  live_command_lines,
25
+ operator_aware_tokens,
20
26
  pipeline_segments_for_command,
21
27
  scannable_command_lines,
22
28
  segments_with_following_operator,
@@ -133,3 +139,52 @@ def test_compound_shell_if_fi_tokens_survive_tokenization() -> None:
133
139
  assert "if" in flat_tokens
134
140
  assert "then" in flat_tokens
135
141
  assert "fi" in flat_tokens
142
+
143
+
144
+ def test_operator_aware_tokens_should_read_one_mode_at_a_time() -> None:
145
+ command = 'cd "a b" && git push'
146
+ assert operator_aware_tokens(command, True) == ["cd", "a b", "&&", "git", "push"]
147
+ assert operator_aware_tokens(command, False) == ["cd", '"a b"', "&&", "git", "push"]
148
+ assert operator_aware_tokens('echo "open', True) is None
149
+ assert operator_aware_tokens('echo "open', False) is None
150
+
151
+
152
+ def _fastest_tokenizing_seconds(command: str, is_posix: bool) -> float:
153
+ all_seconds = []
154
+ for _each_attempt in range(3):
155
+ started = time.perf_counter()
156
+ operator_aware_tokens(command, is_posix)
157
+ all_seconds.append(time.perf_counter() - started)
158
+ return min(all_seconds)
159
+
160
+
161
+ @pytest.mark.parametrize("is_posix", [True, False])
162
+ def test_operator_aware_tokens_should_take_linear_time_on_a_long_quoted_word(is_posix: bool) -> None:
163
+ short_command = "tool --body '" + "ab cd; " * 8_000 + "'"
164
+ long_command = "tool --body '" + "ab cd; " * 32_000 + "'"
165
+ _fastest_tokenizing_seconds(short_command, is_posix)
166
+ growth = _fastest_tokenizing_seconds(long_command, is_posix) / _fastest_tokenizing_seconds(short_command, is_posix)
167
+ assert growth < 8
168
+
169
+
170
+ @pytest.mark.parametrize(
171
+ "command",
172
+ [
173
+ "tool --body '" + "ab cd; " * 2_000 + "' && next \"x\\\"y\" ; z",
174
+ 'a "b c"d \'e f\' g\\ h|i&&j||k;l(m)n>o<p',
175
+ "a ''b \"\" c$'d' \\",
176
+ "cut 'open",
177
+ ],
178
+ )
179
+ def test_operator_aware_tokens_should_give_the_words_shlex_gives(command: str) -> None:
180
+ for each_command, each_is_posix in itertools.product([command, "w" * 5_000 + " " + command], (True, False)):
181
+ lexer = shlex.shlex(each_command, posix=each_is_posix, punctuation_chars=True)
182
+ lexer.whitespace_split = True
183
+ lexer.commenters = ""
184
+ try:
185
+ expected = list(lexer)
186
+ except ValueError:
187
+ expected = None
188
+ all_tokens = operator_aware_tokens(each_command, each_is_posix)
189
+ assert all_tokens == expected
190
+ assert all(type(each_token) is str for each_token in all_tokens or [])
@@ -27,3 +27,18 @@ def test_should_return_the_subcommand_tokens_past_global_options(
27
27
  all_arguments: list[str], all_expected_tokens: list[str]
28
28
  ) -> None:
29
29
  assert shell_command_segments.git_subcommand_tokens(all_arguments) == all_expected_tokens
30
+
31
+
32
+ @pytest.mark.parametrize(
33
+ ("all_segment_tokens", "expected_program"),
34
+ [
35
+ (["GIT_TRACE=1", "git", "push"], "git"),
36
+ (["GIT_TRACE+=1", "git", "push"], "git"),
37
+ (["GIT_TRACE+=1"], None),
38
+ (["a+b=1", "git", "push"], "a+b=1"),
39
+ ],
40
+ )
41
+ def test_should_step_over_set_and_append_assignments_to_the_program(
42
+ all_segment_tokens: list[str], expected_program: str | None
43
+ ) -> None:
44
+ assert shell_command_segments.effective_leading_program(all_segment_tokens) == expected_program
@@ -89,6 +89,7 @@ def test_should_return_the_segments_of_every_wrapped_command_text(command: str)
89
89
  (["command", "git", "push"], ("git", ["push"])),
90
90
  (["command", "-p", "git", "push"], ("git", ["push"])),
91
91
  (["exec", "-a", "name", "git", "push"], ("git", ["push"])),
92
+ (["GIT_TRACE+=1", "git", "push"], ("git", ["push"])),
92
93
  ],
93
94
  )
94
95
  def test_should_return_the_program_past_its_wrappers(
@@ -191,3 +192,8 @@ def test_should_parse_a_repeated_inner_command_once() -> None:
191
192
  'bash -c "git push"; bash -c "git push"'
192
193
  )
193
194
  assert all_command_texts.count("git push") == 1
195
+
196
+
197
+ def test_quoted_line_breaks_joined_should_join_only_quoted_line_breaks() -> None:
198
+ command = 'echo "a\nb"\ngit push'
199
+ assert shell_command_wrappers.quoted_line_breaks_joined(command) == 'echo "a b"\ngit push'
@@ -10,3 +10,9 @@ META_ENTRY_FIELD = "isMeta"
10
10
  TOOL_RESULT_BLOCK_TYPE = "tool_result"
11
11
  IS_ERROR_FIELD = "is_error"
12
12
  TOOL_USE_ID_FIELD = "tool_use_id"
13
+ NEWLINE_BYTE = b"\n"
14
+ CARRIAGE_RETURN_BYTE = b"\r"
15
+ ALL_LINE_BREAK_BYTES = (NEWLINE_BYTE, CARRIAGE_RETURN_BYTE)
16
+ TRANSCRIPT_BLOCK_BYTES = 1 << 20
17
+ TRANSCRIPT_LINE_BYTE_CAP = 16 * 1024 * 1024
18
+ FORWARD_COPY_BYTE_CAP = 64 * 1024 * 1024
@@ -7,7 +7,7 @@
7
7
 
8
8
  [tool.mypy]
9
9
  mypy_path = "."
10
- python_version = "3.13"
10
+ python_version = "3.11"
11
11
  ignore_missing_imports = true
12
12
  warn_unused_ignores = false
13
13
  warn_redundant_casts = true
@@ -32,7 +32,7 @@ disallow_untyped_defs = false
32
32
 
33
33
  [tool.ruff]
34
34
  line-length = 100
35
- target-version = "py313"
35
+ target-version = "py311"
36
36
  extend-exclude = [
37
37
  ".audit-trail",
38
38
  ".claude",
@@ -94,7 +94,6 @@ ignore = [
94
94
  # Residual production carve-outs re-homed on #57 (gate friction on multi-line touch).
95
95
  "validators/run_all_validators.py" = ["PLW1510"]
96
96
  "validators/exempt_paths.py" = ["F401"]
97
- "blocking/gate_run_reads.py" = ["UP047"]
98
97
  "test_*.py" = ["B011", "PLR2004", "F401", "F841", "PLW1510", "B905", "B033", "SIM115", "B007", "B018", "B904"]
99
98
  "*_test.py" = ["B011", "PLR2004", "F401", "F841", "PLW1510", "B905", "B033", "SIM115", "B007", "B018", "B904"]
100
99
  "conftest.py" = ["B011", "F401", "F841", "PLW1510"]
@@ -0,0 +1,197 @@
1
+ """The package's Python floor holds for the hooks, their checkers, and the install prose.
2
+
3
+ The floor is the ``requires-python`` bound in the package ``pyproject.toml``. Every
4
+ other statement of it must name the same version, and every hook module must parse
5
+ under that version's grammar, so a hook that cannot start on the floor fails here.
6
+ """
7
+
8
+ import ast
9
+ import importlib.util
10
+ import os
11
+ import re
12
+ import shutil
13
+ import subprocess
14
+ import sys
15
+ import tomllib
16
+ from pathlib import Path
17
+
18
+ import pytest
19
+
20
+ HOOKS_ROOT = Path(__file__).resolve().parent
21
+ PACKAGE_ROOT = HOOKS_ROOT.parent
22
+ REPOSITORY_ROOT = PACKAGE_ROOT.parent.parent
23
+ PACKAGE_PYPROJECT = PACKAGE_ROOT / "pyproject.toml"
24
+ HOOKS_PYPROJECT = HOOKS_ROOT / "pyproject.toml"
25
+ ALL_SHARED_MYPY_PYPROJECTS = (
26
+ PACKAGE_ROOT / "_shared" / "pr-loop" / "scripts" / "pyproject.toml",
27
+ PACKAGE_ROOT / "_shared" / "process-tree" / "scripts" / "pyproject.toml",
28
+ )
29
+ README_PATH = REPOSITORY_ROOT / "README.md"
30
+ INSTALL_PLAN_PATH = PACKAGE_ROOT / "bin" / "install-plan.mjs"
31
+ PYTHON_PROBE_PATH = PACKAGE_ROOT / "bin" / "python-probe.mjs"
32
+
33
+ REQUIRES_PYTHON_PATTERN = re.compile(r"^>=\s*(\d+)\.(\d+)$")
34
+ README_FLOOR_PATTERN = re.compile(r"Python (\d+)\.(\d+)\+")
35
+ INSTALLER_FLOOR_PATTERN = re.compile(r"MINIMUM_PYTHON_VERSION = '(\d+)\.(\d+)'")
36
+ INSTALLER_MESSAGE_FLOOR_REFERENCE = "Install Python ${MINIMUM_PYTHON_VERSION}+"
37
+
38
+ TYPE_PARAMETER_SOURCE = "def first[T](all_items: list[T]) -> T:\n return all_items[0]\n"
39
+ NESTED_QUOTE_FSTRING_SOURCE = (
40
+ 'all_names = ["first", "second"]\njoined_names = f"{", ".join(all_names)}"\n'
41
+ )
42
+ NEWER_TARGET_VERSION = "py312"
43
+
44
+
45
+ def _read_toml(toml_path: Path) -> dict:
46
+ with toml_path.open("rb") as toml_file:
47
+ return tomllib.load(toml_file)
48
+
49
+
50
+ def _package_floor() -> tuple[int, int]:
51
+ requires_python = _read_toml(PACKAGE_PYPROJECT)["project"]["requires-python"]
52
+ floor_match = REQUIRES_PYTHON_PATTERN.match(requires_python.strip())
53
+ assert floor_match, f"requires-python must read '>=X.Y', found {requires_python!r}"
54
+ return int(floor_match.group(1)), int(floor_match.group(2))
55
+
56
+
57
+ def _floor_text(floor: tuple[int, int]) -> str:
58
+ return f"{floor[0]}.{floor[1]}"
59
+
60
+
61
+ def _ruff_excluded_entries() -> list[str]:
62
+ return list(_read_toml(HOOKS_PYPROJECT)["tool"]["ruff"]["extend-exclude"])
63
+
64
+
65
+ def _is_excluded(relative_path: Path, all_excluded_entries: list[str]) -> bool:
66
+ relative_text = relative_path.as_posix()
67
+ return any(
68
+ relative_text.startswith(each_entry + "/") or each_entry in relative_path.parts
69
+ for each_entry in all_excluded_entries
70
+ )
71
+
72
+
73
+ def _all_hook_modules() -> list[Path]:
74
+ all_excluded_entries = _ruff_excluded_entries()
75
+ return sorted(
76
+ each_path
77
+ for each_path in HOOKS_ROOT.rglob("*.py")
78
+ if not _is_excluded(each_path.relative_to(HOOKS_ROOT), all_excluded_entries)
79
+ )
80
+
81
+
82
+ def _parse_at_floor(source: str, source_name: str, floor: tuple[int, int]) -> None:
83
+ ast.parse(source, filename=source_name, feature_version=floor)
84
+
85
+
86
+ def _floor_parse_failures(
87
+ all_module_paths: list[Path], modules_root: Path, floor: tuple[int, int]
88
+ ) -> list[str]:
89
+ all_failures: list[str] = []
90
+ for each_path in all_module_paths:
91
+ try:
92
+ _parse_at_floor(each_path.read_text(encoding="utf-8"), str(each_path), floor)
93
+ except SyntaxError as parse_error:
94
+ relative_path = each_path.relative_to(modules_root).as_posix()
95
+ all_failures.append(f"{relative_path}:{parse_error.lineno}: {parse_error.msg}")
96
+ return all_failures
97
+
98
+
99
+ def _run_ruff_on(
100
+ module_path: Path, all_extra_arguments: list[str]
101
+ ) -> subprocess.CompletedProcess[str]:
102
+ return subprocess.run(
103
+ [
104
+ sys.executable,
105
+ "-m",
106
+ "ruff",
107
+ "check",
108
+ "--no-cache",
109
+ "--config",
110
+ str(HOOKS_PYPROJECT),
111
+ *all_extra_arguments,
112
+ str(module_path),
113
+ ],
114
+ capture_output=True,
115
+ text=True,
116
+ check=False,
117
+ )
118
+
119
+
120
+ def test_hooks_ruff_target_should_equal_the_package_floor() -> None:
121
+ floor = _package_floor()
122
+ ruff_target = _read_toml(HOOKS_PYPROJECT)["tool"]["ruff"]["target-version"]
123
+ assert ruff_target == f"py{floor[0]}{floor[1]}"
124
+
125
+
126
+ @pytest.mark.parametrize(
127
+ "mypy_pyproject",
128
+ [HOOKS_PYPROJECT, *ALL_SHARED_MYPY_PYPROJECTS],
129
+ ids=lambda each_path: each_path.parent.relative_to(PACKAGE_ROOT).as_posix(),
130
+ )
131
+ def test_mypy_python_version_should_equal_the_package_floor(mypy_pyproject: Path) -> None:
132
+ mypy_version = _read_toml(mypy_pyproject)["tool"]["mypy"]["python_version"]
133
+ assert mypy_version == _floor_text(_package_floor())
134
+
135
+
136
+ def test_every_hook_module_should_parse_at_the_package_floor() -> None:
137
+ all_module_paths = _all_hook_modules()
138
+ assert all_module_paths
139
+ all_failures = _floor_parse_failures(all_module_paths, HOOKS_ROOT, _package_floor())
140
+ assert not all_failures, "\n".join(all_failures)
141
+
142
+
143
+ def test_floor_parse_should_reject_a_type_parameter_list() -> None:
144
+ with pytest.raises(SyntaxError):
145
+ _parse_at_floor(TYPE_PARAMETER_SOURCE, "planted_type_parameters.py", _package_floor())
146
+
147
+
148
+ def test_floor_parse_should_name_the_file_and_line_of_a_newer_module(tmp_path: Path) -> None:
149
+ planted_module = tmp_path / "planted_type_parameters.py"
150
+ planted_module.write_text("import os\n\n" + TYPE_PARAMETER_SOURCE, encoding="utf-8")
151
+ all_failures = _floor_parse_failures([planted_module], tmp_path, _package_floor())
152
+ assert len(all_failures) == 1
153
+ assert all_failures[0].startswith("planted_type_parameters.py:3: ")
154
+
155
+
156
+ def test_hooks_ruff_config_should_reject_a_nested_quote_fstring(tmp_path: Path) -> None:
157
+ if importlib.util.find_spec("ruff") is None:
158
+ pytest.skip("the ruff module is not installed")
159
+ planted_module = tmp_path / "planted_nested_quote_fstring.py"
160
+ planted_module.write_text(NESTED_QUOTE_FSTRING_SOURCE, encoding="utf-8")
161
+ newer_target_run = _run_ruff_on(planted_module, ["--target-version", NEWER_TARGET_VERSION])
162
+ assert newer_target_run.returncode == 0, newer_target_run.stdout + newer_target_run.stderr
163
+ floor_run = _run_ruff_on(planted_module, [])
164
+ assert floor_run.returncode != 0
165
+ assert "syntax was added in Python 3.12" in floor_run.stdout + floor_run.stderr
166
+
167
+
168
+ def test_hooks_should_compile_under_the_floor_interpreter(tmp_path: Path) -> None:
169
+ floor_interpreter = shutil.which(f"python{_floor_text(_package_floor())}")
170
+ if floor_interpreter is None:
171
+ pytest.skip("no interpreter for the floor version on PATH")
172
+ compile_environment = {**os.environ, "PYTHONPYCACHEPREFIX": str(tmp_path)}
173
+ compile_run = subprocess.run(
174
+ [floor_interpreter, "-m", "compileall", "-q", str(HOOKS_ROOT)],
175
+ capture_output=True,
176
+ text=True,
177
+ check=False,
178
+ env=compile_environment,
179
+ )
180
+ assert compile_run.returncode == 0, compile_run.stdout + compile_run.stderr
181
+
182
+
183
+ def test_readme_should_name_the_package_floor() -> None:
184
+ all_readme_floors = README_FLOOR_PATTERN.findall(README_PATH.read_text(encoding="utf-8"))
185
+ assert all_readme_floors
186
+ floor = _package_floor()
187
+ assert {(int(major), int(minor)) for major, minor in all_readme_floors} == {floor}
188
+
189
+
190
+ def test_installer_should_name_the_package_floor() -> None:
191
+ python_probe_source = PYTHON_PROBE_PATH.read_text(encoding="utf-8")
192
+ installer_floor_match = INSTALLER_FLOOR_PATTERN.search(python_probe_source)
193
+ assert installer_floor_match, "python-probe.mjs must export MINIMUM_PYTHON_VERSION"
194
+ install_plan_source = INSTALL_PLAN_PATH.read_text(encoding="utf-8")
195
+ installer_floor = (int(installer_floor_match.group(1)), int(installer_floor_match.group(2)))
196
+ assert installer_floor == _package_floor()
197
+ assert INSTALLER_MESSAGE_FLOOR_REFERENCE in install_plan_source