claude-dev-env 8.114.10 → 8.116.0
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.
- package/docs/rule-guides/verified-work.md +1 -1
- package/hooks/advisory/commit_and_pull_request_words.py +346 -0
- package/hooks/advisory/piece_clauses.py +248 -0
- package/hooks/advisory/pieces_per_level_analysis.py +192 -0
- package/hooks/advisory/pieces_per_level_note.py +265 -0
- package/hooks/advisory/test_commit_and_pull_request_words.py +126 -0
- package/hooks/advisory/test_piece_clauses.py +183 -0
- package/hooks/advisory/test_pieces_per_level_note.py +389 -0
- package/hooks/advisory/test_pieces_per_level_note_bounds.py +215 -0
- package/hooks/advisory/test_pieces_per_level_note_deadline.py +282 -0
- package/hooks/features/README.md +1 -1
- package/hooks/features/session-context.md +4 -1
- package/hooks/features/spawn-routing.md +1 -1
- package/hooks/hooks.json +10 -0
- package/hooks/hooks_constants/pieces_per_level_note_constants.py +255 -0
- package/hooks/hooks_constants/shell_command_wrappers.py +20 -8
- package/hooks/hooks_constants/spawn_oversight_hook_constants.py +5 -1
- package/hooks/hooks_constants/test_shell_command_wrappers.py +7 -0
- package/hooks/routing/test_spawn_oversight_hook.py +15 -0
- package/package.json +1 -1
- package/scripts/tests/test_verified_work_rule.py +13 -0
|
@@ -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 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
|