claude-dev-env 8.115.0 → 8.116.1

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 (44) hide show
  1. package/bin/install.prompt-context.test.mjs +5 -6
  2. package/docs/rule-guides/verified-work.md +1 -1
  3. package/hooks/advisory/commit_and_pull_request_words.py +346 -0
  4. package/hooks/advisory/piece_clauses.py +248 -0
  5. package/hooks/advisory/pieces_per_level_analysis.py +192 -0
  6. package/hooks/advisory/pieces_per_level_note.py +265 -0
  7. package/hooks/advisory/test_commit_and_pull_request_words.py +126 -0
  8. package/hooks/advisory/test_piece_clauses.py +183 -0
  9. package/hooks/advisory/test_pieces_per_level_note.py +389 -0
  10. package/hooks/advisory/test_pieces_per_level_note_bounds.py +215 -0
  11. package/hooks/advisory/test_pieces_per_level_note_deadline.py +282 -0
  12. package/hooks/blocking/final_reply_gate.py +7 -29
  13. package/hooks/blocking/test_final_reply_gate.py +4 -196
  14. package/hooks/features/README.md +1 -1
  15. package/hooks/features/conduct-gates.md +5 -12
  16. package/hooks/features/session-context.md +4 -1
  17. package/hooks/hooks.json +10 -41
  18. package/hooks/hooks_constants/background_silence_prompt_constants.py +2 -0
  19. package/hooks/hooks_constants/pieces_per_level_note_constants.py +255 -0
  20. package/hooks/hooks_constants/resolve_thread_reply_gate_constants.py +0 -8
  21. package/hooks/hooks_constants/shell_command_wrappers.py +20 -8
  22. package/hooks/hooks_constants/test_shell_command_wrappers.py +7 -0
  23. package/hooks/session/background_silence_prompt.py +1 -1
  24. package/hooks/test_context_budget_hooks.py +0 -1
  25. package/package.json +1 -1
  26. package/scripts/durable_post_lint.py +0 -12
  27. package/scripts/durable_post_lint_config/config/constants.py +1 -2
  28. package/scripts/policy_lint/adapter_configuration.py +0 -2
  29. package/scripts/policy_lint/config/constants.py +0 -2
  30. package/scripts/test_durable_post_lint.py +0 -53
  31. package/scripts/tests/test_adapter_configuration.py +0 -16
  32. package/scripts/tests/test_verified_work_rule.py +13 -0
  33. package/hooks/blocking/chat_reply_gate.py +0 -260
  34. package/hooks/blocking/reply_length_gate.py +0 -804
  35. package/hooks/blocking/test_chat_reply_gate.py +0 -302
  36. package/hooks/blocking/test_reply_length_gate.py +0 -1324
  37. package/hooks/hooks_constants/chat_reply_gate_constants.py +0 -60
  38. package/hooks/hooks_constants/reply_length_gate_constants.py +0 -203
  39. package/hooks/hooks_constants/test_reply_length_gate_constants.py +0 -81
  40. package/hooks/hooks_constants/test_visual_reply_rules_constants.py +0 -50
  41. package/hooks/hooks_constants/visual_reply_rules_constants.py +0 -106
  42. package/hooks/test_visual_reply_rules.py +0 -362
  43. package/hooks/visual_reply_rules.py +0 -478
  44. package/rules/visual-reply-rules.json +0 -56
@@ -35,15 +35,14 @@ test('reinstall drops the retired style reminder and keeps one skill reminder ho
35
35
  mergeHooksIntoSettings(settings, hooksConfig, 'C:/Users/example/.claude', 'python');
36
36
 
37
37
  const userPromptHooks = settings.hooks.UserPromptSubmit.flatMap(eachGroup => eachGroup.hooks);
38
- assert.equal(userPromptHooks.length, 8);
38
+ assert.equal(userPromptHooks.length, 7);
39
39
  assert.equal(userPromptHooks[0].command, userCommand);
40
40
  assert.match(userPromptHooks[1].command, /session\/skill_loaded_reminder\.py$/);
41
41
  assert.match(userPromptHooks[2].command, /lifecycle\/nested_project_hooks\.py$/);
42
- assert.match(userPromptHooks[3].command, /blocking\/chat_reply_gate\.py$/);
43
- assert.match(userPromptHooks[4].command, /session\/tracking_nudge\.py$/);
44
- assert.match(userPromptHooks[5].command, /session\/plugin_change_warning\.py$/);
45
- assert.match(userPromptHooks[6].command, /blocking\/turn_review_gate\.py$/);
46
- assert.match(userPromptHooks[7].command, /session\/background_silence_prompt\.py$/);
42
+ assert.match(userPromptHooks[3].command, /session\/tracking_nudge\.py$/);
43
+ assert.match(userPromptHooks[4].command, /session\/plugin_change_warning\.py$/);
44
+ assert.match(userPromptHooks[5].command, /blocking\/turn_review_gate\.py$/);
45
+ assert.match(userPromptHooks[6].command, /session\/background_silence_prompt\.py$/);
47
46
  assert.ok(userPromptHooks.every(eachHook => !eachHook.command.includes('style_reminder_prompt')));
48
47
 
49
48
  const firstMerge = JSON.stringify(settings);
@@ -58,4 +58,4 @@ Report only what a verifier passed. Name the verifier's verdict and the evidence
58
58
 
59
59
  ## Enforcement
60
60
 
61
- `hooks/routing/spawn_oversight_hook.py` adds the six steps, the separate verifier, the reproduce-first check, the one-piece-per-level delivery where the brief allows commits, the scope ask, and the reporting rule to the first passing spawn of each agent in the tree, and again after a compaction. A passing brief has an `Outcome:` line and an `On a blocker:` line; the hook denies a brief without them on every spawn, and the verifier brief template carries both. The flow itself adds context only. No hook refuses a report, a commit, or a spawn for a missing verifier run, so the flow never blocks work the user asked for.
61
+ `hooks/routing/spawn_oversight_hook.py` adds the six steps, the separate verifier, the reproduce-first check, the one-piece-per-level delivery where the brief allows commits, the scope ask, and the reporting rule to the first passing spawn of each agent in the tree, and again after a compaction. A passing brief has an `Outcome:` line and an `On a blocker:` line; the hook denies a brief without them on every spawn, and the verifier brief template carries both. The flow itself adds context only. No hook refuses a report, a commit, or a spawn for a missing verifier run, so the flow never blocks work the user asked for. `hooks/advisory/pieces_per_level_note.py` adds a context note when a commit subject or a pull request opened by an agent names several pieces, and it never denies or exits non-zero. [Session context](../../hooks/features/session-context.md) describes what the note reads and what bounds its run.
@@ -0,0 +1,346 @@
1
+ """Read the author's own words out of a ``git commit`` or a pull request create command.
2
+
3
+ ::
4
+
5
+ git commit -m "fix(x): a, b" -m body -> subject "fix(x): a, b"
6
+ git commit -F msg.txt -> the first line of msg.txt
7
+ gh pr create --title "t" --body-file body.md -> ("t", the text of body.md)
8
+ python pull_request.py create --title "t" ... -> ("t", the text of the body file)
9
+
10
+ A text the command passes on standard input, a missing file, a path that is not
11
+ a regular file (a folder, a named pipe, a device such as ``NUL``), and a quote
12
+ that never closes give no words. The module opens only a regular file a
13
+ ``-F``, ``--file``, or ``--body-file`` option names, and reads at most
14
+ ``MAXIMUM_FILE_BYTES`` bytes of it. It reads no network and starts no process.
15
+ """
16
+
17
+ from __future__ import annotations
18
+
19
+ import bisect
20
+ import functools
21
+ import itertools
22
+ import os
23
+ import shlex
24
+ import stat
25
+ import sys
26
+ from collections.abc import Iterable, Iterator
27
+ from pathlib import Path
28
+
29
+ hooks_root_directory = str(Path(__file__).resolve().parent.parent)
30
+ if hooks_root_directory not in sys.path:
31
+ sys.path.insert(0, hooks_root_directory)
32
+
33
+ from hooks_constants.followup_pr_dedupe_constants import (
34
+ ALL_BODY_FILE_OPTIONS,
35
+ ALL_BODY_OPTIONS,
36
+ ALL_TITLE_OPTIONS,
37
+ )
38
+ from hooks_constants.pieces_per_level_note_constants import (
39
+ ALL_FILE_LONG_OPTIONS,
40
+ ALL_GH_CREATE_WORDS,
41
+ ALL_MESSAGE_LONG_OPTIONS,
42
+ ALL_SHELL_CONTROL_TOKENS,
43
+ ALL_SUBSTITUTION_MARKERS,
44
+ BACKSLASH,
45
+ CARRIAGE_RETURN,
46
+ CARRIAGE_RETURN_LINE_FEED,
47
+ COMMIT_WORD_PATTERN,
48
+ DOUBLED_BACKSLASH,
49
+ EXECUTABLE_SUFFIX,
50
+ FILE_KIND,
51
+ FILE_SHORT_OPTION,
52
+ GH_PROGRAM_NAME,
53
+ GIT_COMMIT_WORD,
54
+ GIT_PROGRAM_NAME,
55
+ GIT_WORD_PATTERN,
56
+ HEREDOC_MESSAGE_PATTERN,
57
+ HEREDOC_START_PATTERN,
58
+ HEREDOC_TAG_GROUP,
59
+ HEREDOC_TEXT_GROUP,
60
+ LINE_LEADING_WORD_PATTERN,
61
+ LINE_SEPARATOR,
62
+ LONG_OPTION_PREFIX,
63
+ MAXIMUM_FILE_BYTES,
64
+ MAXIMUM_PROGRAM_MENTIONS,
65
+ MAXIMUM_SUBSTITUTION_MARKERS,
66
+ MAXIMUM_WRAPPED_TEXTS,
67
+ PARSE_CACHE_SIZE,
68
+ MESSAGE_KIND,
69
+ MESSAGE_SHORT_FLAG,
70
+ MINIMUM_HEREDOC_BODY_LINE_OFFSET,
71
+ OPTION_VALUE_SEPARATOR,
72
+ SHORT_OPTION_PREFIX,
73
+ STANDARD_INPUT_PATH,
74
+ )
75
+ from hooks_constants.pull_request_proof_constants import (
76
+ PULL_REQUEST_SCRIPT_CREATE_WORD,
77
+ PULL_REQUEST_SCRIPT_NAME,
78
+ )
79
+ from hooks_constants.setup_project_paths_constants import DECODE_ERRORS_POLICY, UTF8_ENCODING
80
+ from hooks_constants.shell_command_segments import git_subcommand_tokens, token_basename
81
+ from hooks_constants.shell_command_wrappers import all_wrapped_command_texts
82
+
83
+
84
+ def _tokens_or_none(text: str) -> list[str] | None:
85
+ try:
86
+ return shlex.split(text, posix=True)
87
+ except ValueError:
88
+ return None
89
+
90
+
91
+ def _command_texts(command: str) -> list[str]:
92
+ marker_count = sum(command.count(each_marker) for each_marker in ALL_SUBSTITUTION_MARKERS)
93
+ if marker_count > MAXIMUM_SUBSTITUTION_MARKERS:
94
+ return [command]
95
+ return all_wrapped_command_texts(command, MAXIMUM_WRAPPED_TEXTS)
96
+
97
+
98
+ @functools.lru_cache(maxsize=PARSE_CACHE_SIZE)
99
+ def _all_token_lists(command: str) -> tuple[list[str], ...]:
100
+ all_variants = (
101
+ each_variant
102
+ for each_text in _command_texts(command)
103
+ for each_variant in (each_text, each_text.replace(BACKSLASH, DOUBLED_BACKSLASH))
104
+ )
105
+ return tuple(
106
+ all_tokens
107
+ for each_variant in all_variants
108
+ if (all_tokens := _tokens_or_none(each_variant)) is not None
109
+ )
110
+
111
+
112
+ def clear_parse_cache() -> None:
113
+ """Forget the parsed commands, so the next read parses its command again."""
114
+ _all_token_lists.cache_clear()
115
+
116
+
117
+ def _arguments_after(all_tokens: list[str], start_index: int) -> list[str]:
118
+ all_arguments: list[str] = []
119
+ for each_token in all_tokens[start_index:]:
120
+ if each_token in ALL_SHELL_CONTROL_TOKENS:
121
+ break
122
+ all_arguments.append(each_token)
123
+ return all_arguments
124
+
125
+
126
+ def _first_mentions(all_indexes: Iterable[int]) -> Iterator[int]:
127
+ return itertools.islice(all_indexes, MAXIMUM_PROGRAM_MENTIONS)
128
+
129
+
130
+ def _program_indexes(all_tokens: list[str], program_name: str) -> Iterator[int]:
131
+ return _first_mentions(
132
+ each_index
133
+ for each_index, each_token in enumerate(all_tokens)
134
+ if token_basename(each_token).removesuffix(EXECUTABLE_SUFFIX) == program_name
135
+ )
136
+
137
+
138
+ def _script_indexes(all_tokens: list[str]) -> Iterator[int]:
139
+ return _first_mentions(
140
+ each_index
141
+ for each_index, each_token in enumerate(all_tokens)
142
+ if token_basename(each_token) == PULL_REQUEST_SCRIPT_NAME
143
+ )
144
+
145
+
146
+ def _all_commit_arguments(all_tokens: list[str]) -> Iterator[list[str]]:
147
+ for each_index in _program_indexes(all_tokens, GIT_PROGRAM_NAME):
148
+ all_subcommand_tokens = git_subcommand_tokens(_arguments_after(all_tokens, each_index + 1))
149
+ if all_subcommand_tokens[:1] == [GIT_COMMIT_WORD]:
150
+ yield all_subcommand_tokens[1:]
151
+
152
+
153
+ def _all_commit_argument_lists(command: str) -> Iterator[list[str]]:
154
+ return (
155
+ each_arguments
156
+ for each_tokens in _all_token_lists(command)
157
+ for each_arguments in _all_commit_arguments(each_tokens)
158
+ )
159
+
160
+
161
+ def _message_text(message: str) -> str:
162
+ heredoc_match = HEREDOC_MESSAGE_PATTERN.match(message)
163
+ return heredoc_match.group(HEREDOC_TEXT_GROUP) if heredoc_match else message
164
+
165
+
166
+ def _file_text(path_text: str, working_directory: str) -> str | None:
167
+ if path_text == STANDARD_INPUT_PATH:
168
+ return None
169
+ file_path = Path(working_directory) / path_text
170
+ try:
171
+ if not stat.S_ISREG(os.stat(file_path).st_mode):
172
+ return None
173
+ with file_path.open("rb") as file_handle:
174
+ all_file_bytes = file_handle.read(MAXIMUM_FILE_BYTES)
175
+ except (OSError, ValueError):
176
+ return None
177
+ return (
178
+ all_file_bytes.decode(UTF8_ENCODING, errors=DECODE_ERRORS_POLICY)
179
+ .replace(CARRIAGE_RETURN_LINE_FEED, LINE_SEPARATOR)
180
+ .replace(CARRIAGE_RETURN, LINE_SEPARATOR)
181
+ )
182
+
183
+
184
+ def _is_message_flag_cluster(argument: str) -> bool:
185
+ return (
186
+ argument.startswith(SHORT_OPTION_PREFIX)
187
+ and not argument.startswith(LONG_OPTION_PREFIX)
188
+ and argument[1:].isalpha()
189
+ and argument.endswith(MESSAGE_SHORT_FLAG)
190
+ )
191
+
192
+
193
+ def _option_kind(option_name: str) -> str | None:
194
+ if option_name in ALL_MESSAGE_LONG_OPTIONS or _is_message_flag_cluster(option_name):
195
+ return MESSAGE_KIND
196
+ if option_name in ALL_FILE_LONG_OPTIONS or option_name == FILE_SHORT_OPTION:
197
+ return FILE_KIND
198
+ return None
199
+
200
+
201
+ def _option_at(all_arguments: list[str], index: int) -> tuple[str, str] | None:
202
+ option_name, separator, inline_text = all_arguments[index].partition(OPTION_VALUE_SEPARATOR)
203
+ option_kind = _option_kind(option_name)
204
+ if option_kind is None:
205
+ return None
206
+ if separator:
207
+ return option_kind, inline_text
208
+ if index + 1 < len(all_arguments):
209
+ return option_kind, all_arguments[index + 1]
210
+ return None
211
+
212
+
213
+ def _option_message(option_kind: str, option_text: str, working_directory: str) -> str | None:
214
+ if option_kind == MESSAGE_KIND:
215
+ return _message_text(option_text)
216
+ return _file_text(option_text, working_directory)
217
+
218
+
219
+ def _commit_messages(all_arguments: list[str], working_directory: str) -> list[str]:
220
+ all_options = [
221
+ each_option
222
+ for each_index in range(len(all_arguments))
223
+ if (each_option := _option_at(all_arguments, each_index)) is not None
224
+ ]
225
+ all_messages = [
226
+ _option_message(each_kind, each_text, working_directory)
227
+ for each_kind, each_text in all_options
228
+ ]
229
+ return [each_message for each_message in all_messages if each_message is not None]
230
+
231
+
232
+ def _heredoc_start_tag(line: str) -> str | None:
233
+ git_match = GIT_WORD_PATTERN.search(line)
234
+ commit_match = None if git_match is None else COMMIT_WORD_PATTERN.search(line, git_match.end())
235
+ if commit_match is None:
236
+ return None
237
+ start_match = HEREDOC_START_PATTERN.search(line, commit_match.end())
238
+ return None if start_match is None else start_match.group(HEREDOC_TAG_GROUP)
239
+
240
+
241
+ def _line_numbers_by_leading_word(all_lines: list[str]) -> dict[str, list[int]]:
242
+ all_line_numbers: dict[str, list[int]] = {}
243
+ for each_number, each_line in enumerate(all_lines):
244
+ leading_word = LINE_LEADING_WORD_PATTERN.match(each_line)
245
+ if leading_word is not None:
246
+ all_line_numbers.setdefault(leading_word.group(1), []).append(each_number)
247
+ return all_line_numbers
248
+
249
+
250
+ def _all_heredoc_commit_texts(command: str) -> Iterator[str]:
251
+ all_lines = command.split(LINE_SEPARATOR)
252
+ all_line_numbers: dict[str, list[int]] | None = None
253
+ line_number = 0
254
+ while line_number < len(all_lines):
255
+ tag = _heredoc_start_tag(all_lines[line_number])
256
+ if tag is None:
257
+ line_number += 1
258
+ continue
259
+ if all_line_numbers is None:
260
+ all_line_numbers = _line_numbers_by_leading_word(all_lines)
261
+ all_closing_numbers = all_line_numbers.get(tag, [])
262
+ closing_slot = bisect.bisect_left(
263
+ all_closing_numbers, line_number + MINIMUM_HEREDOC_BODY_LINE_OFFSET
264
+ )
265
+ if closing_slot == len(all_closing_numbers):
266
+ line_number += 1
267
+ continue
268
+ closing_number = all_closing_numbers[closing_slot]
269
+ yield LINE_SEPARATOR.join(all_lines[line_number + 1 : closing_number])
270
+ line_number = closing_number + 1
271
+
272
+
273
+ def _first_line(message: str) -> str:
274
+ return next((each_line.strip() for each_line in message.splitlines() if each_line.strip()), "")
275
+
276
+
277
+ def commit_subjects(command: str, working_directory: str) -> list[str]:
278
+ """Return the subject line of each ``git commit`` the command runs.
279
+
280
+ The first message of a commit is its subject, so a repeated ``-m`` adds
281
+ body paragraphs. A message in a heredoc inside ``-m "$(cat <<'EOF' ...)"``
282
+ is read even when its text holds a double quote.
283
+
284
+ Args:
285
+ command: The shell command text the agent ran.
286
+ working_directory: The folder a relative ``-F`` path resolves against.
287
+ """
288
+ all_subjects = []
289
+ for each_arguments in _all_commit_argument_lists(command):
290
+ all_messages = _commit_messages(each_arguments, working_directory)
291
+ if all_messages:
292
+ all_subjects.append(_first_line(all_messages[0]))
293
+ all_subjects.extend(_first_line(each_text) for each_text in _all_heredoc_commit_texts(command))
294
+ return list(dict.fromkeys(all_subjects))
295
+
296
+
297
+ def _named_option_text(all_arguments: list[str], all_option_names: frozenset[str]) -> str | None:
298
+ for each_index, each_argument in enumerate(all_arguments):
299
+ option_name, separator, inline_text = each_argument.partition(OPTION_VALUE_SEPARATOR)
300
+ if option_name not in all_option_names:
301
+ continue
302
+ if separator:
303
+ return inline_text
304
+ return all_arguments[each_index + 1] if each_index + 1 < len(all_arguments) else None
305
+ return None
306
+
307
+
308
+ def _all_pull_request_arguments(all_tokens: list[str]) -> Iterator[list[str]]:
309
+ for each_index in _program_indexes(all_tokens, GH_PROGRAM_NAME):
310
+ all_arguments = _arguments_after(all_tokens, each_index + 1)
311
+ if all_arguments[: len(ALL_GH_CREATE_WORDS)] == list(ALL_GH_CREATE_WORDS):
312
+ yield all_arguments[len(ALL_GH_CREATE_WORDS) :]
313
+ for each_index in _script_indexes(all_tokens):
314
+ all_arguments = _arguments_after(all_tokens, each_index + 1)
315
+ if all_arguments[:1] == [PULL_REQUEST_SCRIPT_CREATE_WORD]:
316
+ yield all_arguments[1:]
317
+
318
+
319
+ def _pull_request_body(all_arguments: list[str], working_directory: str) -> str | None:
320
+ inline_body = _named_option_text(all_arguments, ALL_BODY_OPTIONS)
321
+ if inline_body is not None:
322
+ return inline_body
323
+ body_path = _named_option_text(all_arguments, ALL_BODY_FILE_OPTIONS)
324
+ return None if body_path is None else _file_text(body_path, working_directory)
325
+
326
+
327
+ def pull_request_words(command: str, working_directory: str) -> list[tuple[str | None, str | None]]:
328
+ """Return the title and body of each pull request create call the command runs.
329
+
330
+ Args:
331
+ command: The shell command text the agent ran.
332
+ working_directory: The folder a relative ``--body-file`` path resolves against.
333
+
334
+ Returns:
335
+ One ``(title, body)`` pair per call. A part the call does not pass, or
336
+ a body file the hook cannot read, is None.
337
+ """
338
+ all_words = [
339
+ (
340
+ _named_option_text(each_arguments, ALL_TITLE_OPTIONS),
341
+ _pull_request_body(each_arguments, working_directory),
342
+ )
343
+ for each_tokens in _all_token_lists(command)
344
+ for each_arguments in _all_pull_request_arguments(each_tokens)
345
+ ]
346
+ return list(dict.fromkeys(all_words))
@@ -0,0 +1,248 @@
1
+ """Find the pieces an author's own words name in a subject, a title, or a pull request body.
2
+
3
+ Three readers, each pure text in and pieces out::
4
+
5
+ subject_pieces("fix(x): publish icons, put Tips on the tray") -> ["publish icons", "put Tips on the tray"]
6
+ subject_pieces("fix(x): darken or lighten the video") -> []
7
+ topic_bullets(body) -> bold-led bullets under "What this does"
8
+ proof_pair_count(body) -> without/with pairs under "Proof in practice"
9
+
10
+ A subject names several pieces when its description joins two or more verb-led
11
+ clauses with commas, semicolons, or "and". An "and" or a comma inside a
12
+ "with ..." phrase joins objects, so it opens no clause. "or" never separates.
13
+ """
14
+
15
+ from __future__ import annotations
16
+
17
+ import re
18
+ import sys
19
+ from pathlib import Path
20
+
21
+ hooks_root_directory = str(Path(__file__).resolve().parent.parent)
22
+ if hooks_root_directory not in sys.path:
23
+ sys.path.insert(0, hooks_root_directory)
24
+
25
+ from blocking.body_flowchart import fenced_line_flags
26
+ from hooks_constants.pull_request_proof_constants import (
27
+ NEXT_HEADING_PATTERN,
28
+ PROOF_HEADING_PATTERN,
29
+ WHAT_THIS_DOES_HEADING_PATTERN,
30
+ )
31
+ from hooks_constants.pieces_per_level_note_constants import (
32
+ ALL_ADJUNCT_WORDS,
33
+ ALL_LABEL_TOPICS,
34
+ ALL_LEADING_ADVERBS,
35
+ ALL_PIECE_VERBS,
36
+ CLAUSE_SEPARATOR_PATTERN,
37
+ CODE_SPAN_PATTERN,
38
+ CONVENTIONAL_SUBJECT_PATTERN,
39
+ DESCRIPTION_GROUP,
40
+ MASKED_TEXT,
41
+ MAXIMUM_BODY_CHARACTERS,
42
+ MAXIMUM_LINE_CHARACTERS,
43
+ MAXIMUM_PIECE_CHARACTERS,
44
+ MAXIMUM_TITLE_CHARACTERS,
45
+ MINIMUM_CLAUSE_WORD_COUNT,
46
+ MINIMUM_PIECE_COUNT,
47
+ PARENTHESIS_PATTERN,
48
+ PIECE_TRUNCATION_SUFFIX,
49
+ PROOF_LEAD_CHARACTERS,
50
+ PROOF_NUMBER_PATTERN,
51
+ QUOTED_TEXT_PATTERN,
52
+ REMOVED_TEXT,
53
+ TOPIC_BULLET_PATTERN,
54
+ TOPIC_EDGE_CHARACTERS,
55
+ TOPIC_GROUP,
56
+ WITH_LINE_PATTERN,
57
+ WITH_SAME_LINE_PATTERN,
58
+ WITHOUT_LINE_PATTERN,
59
+ WORD_EDGE_CHARACTERS,
60
+ )
61
+
62
+
63
+ def _masked_description(description: str) -> str:
64
+ masked_description = CODE_SPAN_PATTERN.sub(MASKED_TEXT, description)
65
+ masked_description = PARENTHESIS_PATTERN.sub(REMOVED_TEXT, masked_description)
66
+ return QUOTED_TEXT_PATTERN.sub(MASKED_TEXT, masked_description)
67
+
68
+
69
+ def _all_clauses(description: str) -> list[str]:
70
+ all_clauses: list[str] = []
71
+ for each_part in CLAUSE_SEPARATOR_PATTERN.split(_masked_description(description)):
72
+ each_clause = each_part.strip()
73
+ if not each_clause:
74
+ continue
75
+ if all_clauses and _is_unfinished(all_clauses[-1]):
76
+ all_clauses[-1] = f"{all_clauses[-1]} {each_clause}"
77
+ continue
78
+ all_clauses.append(each_clause)
79
+ return all_clauses
80
+
81
+
82
+ def _holds_adjunct(clause: str) -> bool:
83
+ return any(each_word in ALL_ADJUNCT_WORDS for each_word in clause.lower().split())
84
+
85
+
86
+ def _has_only_verb_objects(clause: str) -> bool:
87
+ all_words = [each_word.strip(WORD_EDGE_CHARACTERS) for each_word in clause.lower().split()]
88
+ all_words_after_adverbs = all_words[_adverb_prefix_length(all_words) :]
89
+ return (
90
+ len(all_words_after_adverbs) > 1
91
+ and all_words_after_adverbs[0] in ALL_PIECE_VERBS
92
+ and all(each_word in ALL_PIECE_VERBS for each_word in all_words_after_adverbs[1:])
93
+ )
94
+
95
+
96
+ def _is_unfinished(clause: str) -> bool:
97
+ return _holds_adjunct(clause) or _has_only_verb_objects(clause)
98
+
99
+
100
+ def _is_verb_led(clause: str) -> bool:
101
+ all_words = [each_word.strip(WORD_EDGE_CHARACTERS) for each_word in clause.lower().split()]
102
+ first_index = _adverb_prefix_length(all_words)
103
+ if first_index >= len(all_words) or all_words[first_index] not in ALL_PIECE_VERBS:
104
+ return False
105
+ return len(all_words) > MINIMUM_CLAUSE_WORD_COUNT or first_index > 0
106
+
107
+
108
+ def _adverb_prefix_length(all_words: list[str]) -> int:
109
+ prefix_length = 0
110
+ for each_word in all_words:
111
+ if each_word not in ALL_LEADING_ADVERBS:
112
+ break
113
+ prefix_length += 1
114
+ return prefix_length
115
+
116
+
117
+ def _shortened(piece: str) -> str:
118
+ if len(piece) <= MAXIMUM_PIECE_CHARACTERS:
119
+ return piece
120
+ keep_length = MAXIMUM_PIECE_CHARACTERS - len(PIECE_TRUNCATION_SUFFIX)
121
+ return piece[:keep_length].rstrip() + PIECE_TRUNCATION_SUFFIX
122
+
123
+
124
+ def subject_pieces(subject: str) -> list[str]:
125
+ """Return the verb-led clauses of a conventional subject, or an empty list.
126
+
127
+ ::
128
+
129
+ "fix(x): always publish icons, put Tips on the tray" -> ["always publish icons", "put Tips on the tray"]
130
+ "feat: add evals with frozen dataset and rerun runs" -> []
131
+ "publish icons, draw the label" -> []
132
+
133
+ Args:
134
+ subject: A commit subject line or a pull request title.
135
+
136
+ Returns:
137
+ Each verb-led clause in the author's words when there are at least
138
+ two, else an empty list. A subject over ``MAXIMUM_TITLE_CHARACTERS``
139
+ names no pieces.
140
+ """
141
+ if len(subject) > MAXIMUM_TITLE_CHARACTERS:
142
+ return []
143
+ subject_match = CONVENTIONAL_SUBJECT_PATTERN.match(subject.strip())
144
+ if subject_match is None:
145
+ return []
146
+ all_pieces = [
147
+ _shortened(each_clause)
148
+ for each_clause in _all_clauses(subject_match.group(DESCRIPTION_GROUP))
149
+ if _is_verb_led(each_clause)
150
+ ]
151
+ return all_pieces if len(all_pieces) >= MINIMUM_PIECE_COUNT else []
152
+
153
+
154
+ def _heading_level(line: str, heading_pattern: str) -> int | None:
155
+ heading_match = re.match(heading_pattern, line.strip(), re.IGNORECASE)
156
+ return None if heading_match is None else len(heading_match.group(1))
157
+
158
+
159
+ def _is_section_end(line: str, heading_level: int) -> bool:
160
+ next_level = _heading_level(line, NEXT_HEADING_PATTERN)
161
+ return next_level is not None and next_level <= heading_level
162
+
163
+
164
+ def _section_lines(body: str, heading_pattern: str) -> list[str]:
165
+ all_lines = [
166
+ each_line[:MAXIMUM_LINE_CHARACTERS]
167
+ for each_line in body[:MAXIMUM_BODY_CHARACTERS].splitlines()
168
+ ]
169
+ all_fenced_flags = fenced_line_flags(all_lines)
170
+ all_heading_levels = [
171
+ None if is_fenced else _heading_level(each_line, heading_pattern)
172
+ for each_line, is_fenced in zip(all_lines, all_fenced_flags, strict=True)
173
+ ]
174
+ heading_index = next(
175
+ (each_index for each_index, each_level in enumerate(all_heading_levels) if each_level),
176
+ None,
177
+ )
178
+ if heading_index is None:
179
+ return []
180
+ heading_level = all_heading_levels[heading_index] or 0
181
+ all_section_lines: list[str] = []
182
+ for each_line, each_fenced_flag in zip(
183
+ all_lines[heading_index + 1 :], all_fenced_flags[heading_index + 1 :], strict=True
184
+ ):
185
+ if each_fenced_flag:
186
+ continue
187
+ if _is_section_end(each_line, heading_level):
188
+ break
189
+ all_section_lines.append(each_line)
190
+ return all_section_lines
191
+
192
+
193
+ def topic_bullets(body: str) -> list[str]:
194
+ """Return the bold lead of each top-level bullet under "What this does".
195
+
196
+ ::
197
+
198
+ "## What this does\\n- **Always publish.** x\\n- **Tips.** y" -> ["Always publish", "Tips"]
199
+ "## What this does\\n- **Before:** x\\n- **After:** y" -> []
200
+
201
+ Args:
202
+ body: The pull request body.
203
+
204
+ Returns:
205
+ The topic of each bold-led bullet, with labels such as Before and
206
+ After left out. Indented bullets and fenced text do not count.
207
+ """
208
+ all_topics = []
209
+ for each_line in _section_lines(body, WHAT_THIS_DOES_HEADING_PATTERN):
210
+ topic_match = TOPIC_BULLET_PATTERN.match(each_line)
211
+ if topic_match is None:
212
+ continue
213
+ each_topic = topic_match.group(TOPIC_GROUP).strip(TOPIC_EDGE_CHARACTERS)
214
+ if each_topic and each_topic.lower() not in ALL_LABEL_TOPICS:
215
+ all_topics.append(each_topic)
216
+ return all_topics
217
+
218
+
219
+ def _proof_line_text(line: str) -> str:
220
+ stripped_line = line.strip(PROOF_LEAD_CHARACTERS)
221
+ return PROOF_NUMBER_PATTERN.sub("", stripped_line).strip(PROOF_LEAD_CHARACTERS).lower()
222
+
223
+
224
+ def _proof_step(line_text: str, is_without_open: bool) -> tuple[int, bool]:
225
+ if WITHOUT_LINE_PATTERN.match(line_text):
226
+ is_pair_on_one_line = WITH_SAME_LINE_PATTERN.search(line_text) is not None
227
+ return (1, False) if is_pair_on_one_line else (0, True)
228
+ if is_without_open and WITH_LINE_PATTERN.match(line_text):
229
+ return 1, False
230
+ return 0, is_without_open
231
+
232
+
233
+ def proof_pair_count(body: str) -> int:
234
+ """Return how many without/with pairs the "Proof in practice" section holds.
235
+
236
+ A pair is a line that opens with "without" and the next line that opens
237
+ with "with", or one line that holds both, such as "Without it x; with it y".
238
+ Fenced text is quoted output and does not count.
239
+
240
+ Args:
241
+ body: The pull request body.
242
+ """
243
+ pair_count = 0
244
+ is_without_open = False
245
+ for each_line in _section_lines(body, PROOF_HEADING_PATTERN):
246
+ added_pairs, is_without_open = _proof_step(_proof_line_text(each_line), is_without_open)
247
+ pair_count += added_pairs
248
+ return pair_count