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
@@ -1,9 +1,8 @@
1
- """Read the pull request open a PreToolUse payload asks for, and the head it opens with."""
1
+ """Read each pull request open a PreToolUse payload asks for, and the head each opens with."""
2
2
 
3
3
  from __future__ import annotations
4
4
 
5
5
  import os
6
- import subprocess
7
6
  import sys
8
7
  import tempfile
9
8
  from dataclasses import dataclass
@@ -13,6 +12,14 @@ hooks_directory = str(Path(__file__).resolve().parent.parent.parent)
13
12
  if hooks_directory not in sys.path:
14
13
  sys.path.insert(0, hooks_directory)
15
14
 
15
+ from blocking.followup_pr_dedupe import named_repository, prefix_repository, sets_gh_repository
16
+ from blocking.merge_review_gate_parts.create_folders import PlacedCreate, all_placed_creates
17
+ from blocking.merge_review_gate_parts.create_options import all_option_values
18
+ from blocking.gate_run_reads import (
19
+ ReadSlice,
20
+ answer_once,
21
+ child_stdout,
22
+ )
16
23
  from hooks_constants.merge_review_gate_constants import (
17
24
  ALL_NON_INTERACTIVE_GIT_SETTINGS,
18
25
  ALL_ORIGIN_URL_ARGUMENTS,
@@ -23,12 +30,17 @@ from hooks_constants.merge_review_gate_constants import (
23
30
  CURRENT_HEAD_REFERENCE,
24
31
  CWD_FIELD,
25
32
  GH_PR_CREATE_PATTERN,
33
+ GH_PROGRAM_NAME,
26
34
  GITHUB_REMOTE_URL_TEMPLATE,
27
35
  GIT_TIMEOUT_SECONDS,
28
36
  HEAD_BRANCH_FIELD,
29
37
  HEAD_OPTION_PATTERN,
38
+ HEAD_SHORT_LETTER,
39
+ LONG_HEAD_OPTION,
40
+ LONG_REPOSITORY_OPTION,
30
41
  LS_REMOTE_FIELD_SEPARATOR,
31
42
  ORIGIN_URL_PATTERN,
43
+ ORIGIN_URL_QUESTION,
32
44
  OWNER_FIELD,
33
45
  PULL_REQUEST_SCRIPT_CREATE_PATTERN,
34
46
  REMOTE_BRANCH_PREFIX,
@@ -36,7 +48,9 @@ from hooks_constants.merge_review_gate_constants import (
36
48
  REMOTE_LOOKUP_TIMEOUT_SECONDS,
37
49
  REPO_FIELD,
38
50
  REPO_OPTION_PATTERN,
51
+ REPOSITORY_SHORT_LETTER,
39
52
  )
53
+ from hooks_constants.shell_command_wrappers import segment_program_and_arguments
40
54
 
41
55
 
42
56
  @dataclass(frozen=True)
@@ -59,54 +73,185 @@ class OpenRequest:
59
73
  return f"{self.owner}/{self.repo}"
60
74
 
61
75
 
62
- def open_request_from(all_payload_fields: dict[str, object]) -> OpenRequest | None:
63
- """Read the pull request open a PreToolUse payload asks for.
76
+ @dataclass(frozen=True)
77
+ class ToolOpenCall:
78
+ """A create pull request tool call, before the gate reads its head.
79
+
80
+ Attributes:
81
+ owner: Repository owner the call names, or empty.
82
+ repo: Repository name the call names, or empty.
83
+ branch: The head branch the call names, or None.
84
+ folder: The payload's folder, or None.
85
+ """
86
+
87
+ owner: str
88
+ repo: str
89
+ branch: str | None
90
+ folder: str | None
91
+
92
+
93
+ @dataclass(frozen=True)
94
+ class ShellOpenCall:
95
+ """One create in a shell command, before the gate reads its repository and head.
96
+
97
+ Attributes:
98
+ repository: The ``(owner, repo)`` its ``--repo``, root ``-R`` or ``GH_REPO`` names, or None to read ``origin``.
99
+ branch: The branch its ``--head`` names, or ``HEAD``.
100
+ folder: The folder in effect at the create, after each folder change before it.
101
+ is_folder_followed: False when a folder change before it could not be followed,
102
+ or when the create names no repository in a command that sets ``GH_REPO``.
103
+ """
104
+
105
+ repository: tuple[str, str] | None
106
+ branch: str
107
+ folder: str | None
108
+ is_folder_followed: bool = True
109
+
64
110
 
65
- ::
111
+ OpenCall = ToolOpenCall | ShellOpenCall
66
112
 
67
- mcp__github__create_pull_request {owner, repo, head}
68
- gh pr create --repo o/r --head branch
69
- python pull_request.py create --repo o/r --head branch
70
113
 
71
- A tool call reads its head branch from GitHub first. A fork head
72
- ``user:branch`` reads the repository of ``user``. A branch GitHub does not
73
- list, and every branch of a shell command, resolves in the payload's folder
74
- as ``origin/<branch>`` first. A ``cd`` target names the folder. No head
75
- means ``HEAD``; no repository, ``origin``.
114
+ def open_calls_from(all_payload_fields: dict[str, object]) -> list[OpenCall]:
115
+ """Return every pull request open a PreToolUse payload asks for, in command order.
116
+
117
+ This reads the payload only. No git or GitHub read runs here::
118
+
119
+ mcp__github__create_pull_request {owner, repo, head} -> [ToolOpenCall]
120
+ gh pr create --head a && cd x && pull_request.py create -> [ShellOpenCall a, ShellOpenCall HEAD in x]
121
+ gh pr merge 12 -> []
122
+
123
+ Each walked create gives one call per head it names, in its own folder.
124
+ The pattern reading of the first create adds one call no walk call equals.
76
125
 
77
126
  Args:
78
127
  all_payload_fields: The parsed PreToolUse input.
79
128
 
80
129
  Returns:
81
- The open request, or None when the call opens no pull request.
130
+ One call per create, empty when the call opens no pull request.
82
131
  """
83
132
  tool_name = all_payload_fields.get("tool_name")
84
133
  tool_input = all_payload_fields.get("tool_input")
85
134
  if not isinstance(tool_name, str) or not isinstance(tool_input, dict):
86
- return None
87
- working_folder = all_payload_fields.get(CWD_FIELD)
88
- folder = working_folder if isinstance(working_folder, str) and working_folder else None
135
+ return []
136
+ folder = _payload_folder(all_payload_fields)
89
137
  if tool_name.endswith(CREATE_TOOL_SUFFIX):
90
- return _tool_open_request(tool_input, folder)
138
+ return [_tool_open_call(tool_input, folder)]
91
139
  command = tool_input.get("command")
92
140
  if tool_name not in ALL_SHELL_TOOL_NAMES or not isinstance(command, str):
93
- return None
94
- return _shell_open_request(command, folder)
141
+ return []
142
+ return _shell_open_calls(command, folder)
95
143
 
96
144
 
97
- def _tool_open_request(all_tool_input: dict[object, object], folder: str | None) -> OpenRequest:
98
- owner = str(all_tool_input.get(OWNER_FIELD, ""))
99
- repo = str(all_tool_input.get(REPO_FIELD, ""))
100
- branch = all_tool_input.get(HEAD_BRANCH_FIELD)
145
+ def _payload_folder(all_payload_fields: dict[str, object]) -> str | None:
146
+ working_folder = all_payload_fields.get(CWD_FIELD)
147
+ return working_folder if isinstance(working_folder, str) and working_folder else None
148
+
149
+
150
+ def open_request_for(call: OpenCall) -> OpenRequest:
151
+ """Read the repository and the head commit one open would use.
152
+
153
+ A tool call reads its head branch from GitHub first::
154
+
155
+ ToolOpenCall acme/tools, head feature pushed at abc123 -> OpenRequest(acme, tools, abc123)
156
+ ShellOpenCall, no --repo, origin names acme/tools -> OpenRequest(acme, tools, <HEAD commit>)
157
+ a read that failed or ran out of time -> that part empty, or head None
158
+ ShellOpenCall whose folder change was not followed -> head None, no read
159
+
160
+ A fork head ``user:branch`` reads the repository of ``user``. A branch
161
+ GitHub does not list, and every branch of a shell create, resolves in the
162
+ call's folder as ``origin/<branch>`` first.
163
+
164
+ Args:
165
+ call: One open from ``open_calls_from``.
166
+
167
+ Returns:
168
+ The open request with the commit it would open with.
169
+ """
170
+ if isinstance(call, ToolOpenCall):
171
+ return _tool_open_request(call)
172
+ return _shell_open_request(call)
173
+
174
+
175
+ def _tool_open_request(call: ToolOpenCall) -> OpenRequest:
101
176
  head = (
102
- _pushed_commit(owner, repo, branch) or _branch_commit(branch, folder)
103
- if isinstance(branch, str) and branch
177
+ _pushed_commit(call.owner, call.repo, call.branch)
178
+ or _branch_commit(call.branch, call.folder)
179
+ if call.branch
104
180
  else None
105
181
  )
106
- return OpenRequest(owner=owner, repo=repo, head=head)
182
+ return OpenRequest(owner=call.owner, repo=call.repo, head=head)
183
+
184
+
185
+ def _shell_open_request(call: ShellOpenCall) -> OpenRequest:
186
+ if not call.is_folder_followed:
187
+ owner, repo = call.repository or ("", "")
188
+ return OpenRequest(owner=owner, repo=repo, head=None)
189
+ owner, repo = call.repository or _origin_repository(call.folder)
190
+ return OpenRequest(owner=owner, repo=repo, head=_branch_commit(call.branch, call.folder))
191
+
192
+
193
+ def _tool_open_call(all_tool_input: dict[object, object], folder: str | None) -> ToolOpenCall:
194
+ branch = all_tool_input.get(HEAD_BRANCH_FIELD)
195
+ return ToolOpenCall(
196
+ owner=str(all_tool_input.get(OWNER_FIELD, "")),
197
+ repo=str(all_tool_input.get(REPO_FIELD, "")),
198
+ branch=branch if isinstance(branch, str) and branch else None,
199
+ folder=folder,
200
+ )
201
+
202
+
203
+ def _shell_open_calls(command: str, folder: str | None) -> list[OpenCall]:
204
+ all_calls: list[OpenCall] = []
205
+ is_gh_repository_set = sets_gh_repository(command)
206
+ for each_create in all_placed_creates(command, folder):
207
+ all_calls.extend(_placed_open_calls(each_create, is_gh_repository_set))
208
+ floor_call = _floor_open_call(command, folder)
209
+ if floor_call is not None:
210
+ all_calls.append(floor_call)
211
+ return list(dict.fromkeys(all_calls))
212
+
213
+
214
+ def _placed_open_calls(placed_create: PlacedCreate, is_gh_repository_set: bool) -> list[ShellOpenCall]:
215
+ repository = _placed_repository(placed_create)
216
+ is_repository_read = repository is not None or not is_gh_repository_set
217
+ return [
218
+ ShellOpenCall(
219
+ repository=repository,
220
+ branch=each_head,
221
+ folder=placed_create.folder,
222
+ is_folder_followed=placed_create.is_folder_followed and is_repository_read,
223
+ )
224
+ for each_head in _placed_heads(placed_create) or [CURRENT_HEAD_REFERENCE]
225
+ ]
226
+
227
+
228
+ def _option_words(placed_create: PlacedCreate) -> list[str]:
229
+ program, all_gh_words = segment_program_and_arguments(list(placed_create.all_command_words))
230
+ return all_gh_words if program == GH_PROGRAM_NAME else list(placed_create.all_arguments)
231
+
107
232
 
233
+ def _placed_repository(placed_create: PlacedCreate) -> tuple[str, str] | None:
234
+ all_values = all_option_values(_option_words(placed_create), LONG_REPOSITORY_OPTION, REPOSITORY_SHORT_LETTER)
235
+ flag_value = all_values[-1] if all_values else prefix_repository(list(placed_create.all_command_words))
236
+ return named_repository(flag_value) if flag_value is not None else None
108
237
 
109
- def _shell_open_request(command: str, folder: str | None) -> OpenRequest | None:
238
+
239
+ def _placed_heads(placed_create: PlacedCreate) -> list[str]:
240
+ all_heads = all_option_values(_option_words(placed_create), LONG_HEAD_OPTION, HEAD_SHORT_LETTER)
241
+ return list(dict.fromkeys(each_head for each_head in all_heads if each_head))
242
+
243
+
244
+ def _floor_open_call(command: str, folder: str | None) -> ShellOpenCall | None:
245
+ """Read the first create the way the gate read it before it walked every create.
246
+
247
+ The repository comes from a ``--repo`` flag or the origin remote, never
248
+ from a ``GH_REPO=`` prefix::
249
+
250
+ GH_REPO=o/r env -u GH_REPO gh pr create --fill -> origin, HEAD
251
+
252
+ There gh opens in origin and the walk reads ``o/r``, so this call is the
253
+ one that asks for a clean pass on origin.
254
+ """
110
255
  options_only = CREATE_TEXT_OPTION_PATTERN.sub(" ", command)
111
256
  create_match = GH_PR_CREATE_PATTERN.search(
112
257
  options_only
@@ -116,12 +261,12 @@ def _shell_open_request(command: str, folder: str | None) -> OpenRequest | None:
116
261
  folder = _folder_after_changes(options_only[: create_match.start()], folder)
117
262
  rest = create_match["rest"]
118
263
  repo_match = REPO_OPTION_PATTERN.search(rest)
119
- owner, repo = (
120
- (repo_match["owner"], repo_match["repo"]) if repo_match else _origin_repository(folder)
121
- )
122
264
  head_match = HEAD_OPTION_PATTERN.search(rest)
123
- branch = head_match["head"] if head_match else CURRENT_HEAD_REFERENCE
124
- return OpenRequest(owner=owner, repo=repo, head=_branch_commit(branch, folder))
265
+ return ShellOpenCall(
266
+ repository=(repo_match["owner"], repo_match["repo"]) if repo_match else None,
267
+ branch=head_match["head"] if head_match else CURRENT_HEAD_REFERENCE,
268
+ folder=folder,
269
+ )
125
270
 
126
271
 
127
272
  def _folder_after_changes(command_before_create: str, folder: str | None) -> str | None:
@@ -135,20 +280,10 @@ def _folder_after_changes(command_before_create: str, folder: str | None) -> str
135
280
 
136
281
 
137
282
  def _run_git(all_arguments: list[str], folder: str | None) -> str | None:
138
- try:
139
- completed = subprocess.run(
140
- ["git", *all_arguments],
141
- cwd=folder,
142
- capture_output=True,
143
- text=True,
144
- timeout=GIT_TIMEOUT_SECONDS,
145
- check=False,
146
- )
147
- except (OSError, subprocess.SubprocessError):
148
- return None
149
- if completed.returncode != 0:
150
- return None
151
- return completed.stdout.strip() or None
283
+ printed_text = child_stdout(
284
+ ["git", *all_arguments], GIT_TIMEOUT_SECONDS, ReadSlice.FOLLOWUP, folder
285
+ )
286
+ return (printed_text or "").strip() or None
152
287
 
153
288
 
154
289
  def _branch_commit(branch: str, folder: str | None) -> str | None:
@@ -175,22 +310,19 @@ def _pushed_commit(owner: str, repo: str, branch: str) -> str | None:
175
310
  return None
176
311
  reference = REMOTE_BRANCH_REFERENCE_TEMPLATE.format(branch=head_branch)
177
312
  remote_url = GITHUB_REMOTE_URL_TEMPLATE.format(owner=head_owner, repo=repo)
178
- with tempfile.TemporaryDirectory() as empty_folder, tempfile.TemporaryFile() as listing:
179
- try:
180
- subprocess.run(
181
- ["git", "ls-remote", remote_url, reference],
182
- cwd=empty_folder,
183
- stdin=subprocess.DEVNULL,
184
- stdout=listing,
185
- stderr=subprocess.DEVNULL,
186
- timeout=REMOTE_LOOKUP_TIMEOUT_SECONDS,
187
- check=False,
188
- env={**os.environ, **ALL_NON_INTERACTIVE_GIT_SETTINGS},
189
- )
190
- except (OSError, subprocess.SubprocessError):
191
- return None
192
- listing.seek(0)
193
- return _listed_commit(listing.read().decode("utf-8", "replace"), reference)
313
+ listing = _remote_listing(remote_url, reference)
314
+ return _listed_commit(listing, reference) if listing is not None else None
315
+
316
+
317
+ def _remote_listing(remote_url: str, reference: str) -> str | None:
318
+ with tempfile.TemporaryDirectory(ignore_cleanup_errors=True) as empty_folder:
319
+ return child_stdout(
320
+ ["git", "ls-remote", remote_url, reference],
321
+ REMOTE_LOOKUP_TIMEOUT_SECONDS,
322
+ ReadSlice.FOLLOWUP,
323
+ empty_folder,
324
+ {**os.environ, **ALL_NON_INTERACTIVE_GIT_SETTINGS},
325
+ )
194
326
 
195
327
 
196
328
  def _listed_commit(listing: str, reference: str) -> str | None:
@@ -202,7 +334,10 @@ def _listed_commit(listing: str, reference: str) -> str | None:
202
334
 
203
335
 
204
336
  def _origin_repository(folder: str | None) -> tuple[str, str]:
205
- origin_url = _run_git(list(ALL_ORIGIN_URL_ARGUMENTS), folder)
337
+ origin_url = answer_once(
338
+ (ORIGIN_URL_QUESTION, folder),
339
+ lambda: _run_git(list(ALL_ORIGIN_URL_ARGUMENTS), folder),
340
+ )
206
341
  origin_match = ORIGIN_URL_PATTERN.search(origin_url) if origin_url else None
207
342
  if not origin_match:
208
343
  return "", ""
@@ -0,0 +1,283 @@
1
+ """Cut shell text into the logical lines bash reads, with each quoted region kept whole.
2
+
3
+ ::
4
+
5
+ gh pr create --body $'it\\'s' ; gh pr create -> one line, $'it\\'s' as 'it'\\''s'
6
+ bash -c "true<line break>gh pr create" -> one line; the line break stays in the word
7
+ gh pr create --body "$(echo '"')" -> one line; the inner quote is escaped
8
+ echo 'open -> None
9
+
10
+ A line break ends a logical line only outside every quote, subshell and
11
+ substitution. Inside a subshell or a substitution outside quotes it becomes
12
+ ``;``. A ``$'...'`` word becomes a single-quoted word. An escaped
13
+ ``\\$(`` outside quotes keeps its ``(`` in the word. Inside a substitution
14
+ in a double-quoted word, each quote and backslash gets a backslash. So a POSIX
15
+ ``shlex`` split of each line gives the words bash gives. Comments and heredoc
16
+ bodies are dropped.
17
+ """
18
+
19
+ from __future__ import annotations
20
+
21
+ import sys
22
+ from dataclasses import dataclass, field
23
+ from pathlib import Path
24
+
25
+ hooks_directory = str(Path(__file__).resolve().parent.parent.parent)
26
+ if hooks_directory not in sys.path:
27
+ sys.path.insert(0, hooks_directory)
28
+
29
+ from hooks_constants.merge_review_gate_constants import (
30
+ ALL_ANSI_C_ESCAPES,
31
+ ANSI_C_QUOTE_OPENER,
32
+ CARRIAGE_RETURN,
33
+ CARRIAGE_RETURN_LINE_BREAK,
34
+ COMMENT_START_CHARACTER,
35
+ DOUBLE_QUOTED_ESCAPE_PATTERN,
36
+ DOUBLE_QUOTED_ESCAPE_REPLACEMENT,
37
+ DOUBLE_QUOTED_SPECIAL_PATTERN,
38
+ ESCAPED_PAIR_LENGTH,
39
+ ESCAPED_SUBSTITUTION_OPENER,
40
+ ESCAPED_SUBSTITUTION_WORD,
41
+ GROUP_CLOSE_CHARACTER,
42
+ GROUP_OPEN_CHARACTER,
43
+ HEREDOC_START_CHARACTER,
44
+ LINE_FEED,
45
+ NESTED_LINE_BREAK_JOIN,
46
+ SINGLE_QUOTE_INSIDE_SINGLE_QUOTES,
47
+ )
48
+ from hooks_constants.piped_pytest_blocker_constants import HEREDOC_OPENER_PATTERN
49
+ from hooks_constants.shell_command_evaluation_constants import ALL_LINE_BREAK_CHARACTERS
50
+ from hooks_constants.shell_command_pipeline import (
51
+ PendingHeredoc,
52
+ closes_the_heredoc,
53
+ pending_heredoc_opened_by,
54
+ )
55
+ from hooks_constants.shell_command_substitution_constants import (
56
+ COMMAND_SUBSTITUTION_OPENER,
57
+ DOUBLE_QUOTE,
58
+ SHELL_ESCAPE_CHARACTER,
59
+ SINGLE_QUOTE,
60
+ )
61
+
62
+
63
+ @dataclass
64
+ class _Frame:
65
+ quote: str = ""
66
+ group_depth: int = 0
67
+
68
+
69
+ @dataclass
70
+ class _Scan:
71
+ text: str
72
+ index: int = 0
73
+ line_start: int = 0
74
+ all_frames: list[_Frame] = field(default_factory=lambda: [_Frame()])
75
+ all_characters: list[str] = field(default_factory=list)
76
+ all_lines: list[str] = field(default_factory=list)
77
+ all_heredoc_starts: list[int] = field(default_factory=list)
78
+
79
+
80
+ def quote_aware_lines(text: str) -> list[str] | None:
81
+ """Return the logical lines of shell text, ready for a POSIX split, or None.
82
+
83
+ ::
84
+
85
+ "a ; b<line break>c" -> ["a ; b", "c"]
86
+ "x=$(a<line break>b)" -> ["x=$(a;b)"]
87
+ "echo 'it<line break>s'" -> ["echo 'it<line break>s'"]
88
+ "echo \\"open" -> None
89
+
90
+ Args:
91
+ text: Shell text, such as a Bash tool command or a ``bash -c`` script.
92
+
93
+ Returns:
94
+ The non-blank logical lines in order, or None when a quote, group or
95
+ substitution is still open at the end of the text.
96
+ """
97
+ scan = _Scan(text)
98
+ while scan.index < len(text):
99
+ _step(scan)
100
+ _end_line(scan)
101
+ return scan.all_lines if scan.all_frames == [_Frame()] else None
102
+
103
+
104
+ def _step(scan: _Scan) -> None:
105
+ frame = scan.all_frames[-1]
106
+ if frame.quote == SINGLE_QUOTE:
107
+ _step_in_single_quotes(scan, frame)
108
+ return
109
+ if frame.quote == ANSI_C_QUOTE_OPENER:
110
+ _step_in_ansi_c_quotes(scan, frame)
111
+ return
112
+ if frame.quote == DOUBLE_QUOTE:
113
+ _step_in_double_quotes(scan, frame)
114
+ return
115
+ _step_unquoted(scan, frame)
116
+
117
+
118
+ def _is_inside_double_quoted_word(scan: _Scan) -> bool:
119
+ return any(each_frame.quote == DOUBLE_QUOTE for each_frame in scan.all_frames[:-1])
120
+
121
+
122
+ def _emit(scan: _Scan, piece: str, length: int) -> None:
123
+ if _is_inside_double_quoted_word(scan):
124
+ piece = DOUBLE_QUOTED_ESCAPE_PATTERN.sub(DOUBLE_QUOTED_ESCAPE_REPLACEMENT, piece)
125
+ scan.all_characters.append(piece)
126
+ scan.index += length
127
+
128
+
129
+ def _source(scan: _Scan, length: int) -> str:
130
+ return scan.text[scan.index : scan.index + length]
131
+
132
+
133
+ def _step_in_single_quotes(scan: _Scan, frame: _Frame) -> None:
134
+ close_index = scan.text.find(SINGLE_QUOTE, scan.index)
135
+ if close_index < 0:
136
+ _emit(scan, scan.text[scan.index :], len(scan.text) - scan.index)
137
+ return
138
+ frame.quote = ""
139
+ _emit(scan, scan.text[scan.index : close_index + 1], close_index + 1 - scan.index)
140
+
141
+
142
+ def _step_in_ansi_c_quotes(scan: _Scan, frame: _Frame) -> None:
143
+ character = _source(scan, 1)
144
+ if character == SINGLE_QUOTE:
145
+ frame.quote = ""
146
+ _emit(scan, SINGLE_QUOTE, 1)
147
+ return
148
+ if character != SHELL_ESCAPE_CHARACTER:
149
+ _emit(scan, character, 1)
150
+ return
151
+ if _is_inside_double_quoted_word(scan):
152
+ _emit(scan, _source(scan, ESCAPED_PAIR_LENGTH), ESCAPED_PAIR_LENGTH)
153
+ return
154
+ escaped = _source(scan, ESCAPED_PAIR_LENGTH)[1:]
155
+ decoded = ALL_ANSI_C_ESCAPES.get(escaped, SHELL_ESCAPE_CHARACTER + escaped)
156
+ _emit(scan, decoded.replace(SINGLE_QUOTE, SINGLE_QUOTE_INSIDE_SINGLE_QUOTES), ESCAPED_PAIR_LENGTH)
157
+
158
+
159
+ def _step_in_double_quotes(scan: _Scan, frame: _Frame) -> None:
160
+ special_match = DOUBLE_QUOTED_SPECIAL_PATTERN.search(scan.text, scan.index)
161
+ if special_match is None or special_match.start() > scan.index:
162
+ run_end = len(scan.text) if special_match is None else special_match.start()
163
+ _emit(scan, scan.text[scan.index : run_end], run_end - scan.index)
164
+ return
165
+ if _source(scan, 1) == SHELL_ESCAPE_CHARACTER:
166
+ _step_past_escape(scan)
167
+ return
168
+ if scan.text.startswith(COMMAND_SUBSTITUTION_OPENER, scan.index):
169
+ _emit(scan, COMMAND_SUBSTITUTION_OPENER, len(COMMAND_SUBSTITUTION_OPENER))
170
+ scan.all_frames.append(_Frame())
171
+ return
172
+ frame.quote = ""
173
+ _emit(scan, DOUBLE_QUOTE, 1)
174
+
175
+
176
+ def _step_past_escape(scan: _Scan) -> None:
177
+ if _source(scan, ESCAPED_PAIR_LENGTH)[1:] in ALL_LINE_BREAK_CHARACTERS:
178
+ scan.index += ESCAPED_PAIR_LENGTH
179
+ return
180
+ _emit(scan, _source(scan, ESCAPED_PAIR_LENGTH), ESCAPED_PAIR_LENGTH)
181
+
182
+
183
+ def _step_unquoted(scan: _Scan, frame: _Frame) -> None:
184
+ character = _source(scan, 1)
185
+ if character in ALL_LINE_BREAK_CHARACTERS:
186
+ _step_past_line_break(scan)
187
+ return
188
+ if scan.text.startswith(ESCAPED_SUBSTITUTION_OPENER, scan.index):
189
+ _emit(scan, ESCAPED_SUBSTITUTION_WORD, len(ESCAPED_SUBSTITUTION_OPENER))
190
+ return
191
+ if character == SHELL_ESCAPE_CHARACTER:
192
+ _step_past_escape(scan)
193
+ return
194
+ if scan.text.startswith(ANSI_C_QUOTE_OPENER, scan.index):
195
+ _open_ansi_c_quotes(scan, frame)
196
+ return
197
+ if scan.text.startswith(COMMAND_SUBSTITUTION_OPENER, scan.index):
198
+ _emit(scan, COMMAND_SUBSTITUTION_OPENER, len(COMMAND_SUBSTITUTION_OPENER))
199
+ scan.all_frames.append(_Frame())
200
+ return
201
+ if character in (SINGLE_QUOTE, DOUBLE_QUOTE):
202
+ frame.quote = character
203
+ _emit(scan, character, 1)
204
+ return
205
+ if character == COMMENT_START_CHARACTER and _is_word_start(scan):
206
+ _skip_to_line_end(scan)
207
+ return
208
+ _step_plain_character(scan, frame, character)
209
+
210
+
211
+ def _open_ansi_c_quotes(scan: _Scan, frame: _Frame) -> None:
212
+ frame.quote = ANSI_C_QUOTE_OPENER
213
+ opener = ANSI_C_QUOTE_OPENER if _is_inside_double_quoted_word(scan) else SINGLE_QUOTE
214
+ _emit(scan, opener, len(ANSI_C_QUOTE_OPENER))
215
+
216
+
217
+ def _is_word_start(scan: _Scan) -> bool:
218
+ return scan.index == 0 or scan.text[scan.index - 1].isspace()
219
+
220
+
221
+ def _skip_to_line_end(scan: _Scan) -> None:
222
+ while scan.index < len(scan.text) and _source(scan, 1) not in ALL_LINE_BREAK_CHARACTERS:
223
+ scan.index += 1
224
+
225
+
226
+ def _step_plain_character(scan: _Scan, frame: _Frame, character: str) -> None:
227
+ _emit(scan, character, 1)
228
+ if character == HEREDOC_START_CHARACTER:
229
+ scan.all_heredoc_starts.append(scan.index - 1)
230
+ return
231
+ if character == GROUP_OPEN_CHARACTER:
232
+ frame.group_depth += 1
233
+ return
234
+ if character != GROUP_CLOSE_CHARACTER:
235
+ return
236
+ if frame.group_depth:
237
+ frame.group_depth -= 1
238
+ return
239
+ if len(scan.all_frames) > 1:
240
+ scan.all_frames.pop()
241
+
242
+
243
+ def _step_past_line_break(scan: _Scan) -> None:
244
+ pending_heredoc = _pending_heredoc(scan)
245
+ is_crlf = scan.text.startswith(CARRIAGE_RETURN_LINE_BREAK, scan.index)
246
+ length = len(CARRIAGE_RETURN_LINE_BREAK) if is_crlf else 1
247
+ if scan.all_frames == [_Frame()]:
248
+ _end_line(scan)
249
+ scan.index += length
250
+ elif _is_inside_double_quoted_word(scan):
251
+ _emit(scan, _source(scan, length), length)
252
+ else:
253
+ _emit(scan, NESTED_LINE_BREAK_JOIN, length)
254
+ scan.line_start = scan.index
255
+ scan.all_heredoc_starts.clear()
256
+ if pending_heredoc is not None:
257
+ _skip_heredoc_body(scan, pending_heredoc)
258
+
259
+
260
+ def _pending_heredoc(scan: _Scan) -> PendingHeredoc | None:
261
+ for each_start in scan.all_heredoc_starts:
262
+ opener_text = scan.text[each_start : scan.index]
263
+ if HEREDOC_OPENER_PATTERN.match(opener_text):
264
+ return pending_heredoc_opened_by(opener_text)
265
+ return None
266
+
267
+
268
+ def _skip_heredoc_body(scan: _Scan, pending_heredoc: PendingHeredoc) -> None:
269
+ while scan.index < len(scan.text):
270
+ line_end = scan.text.find(LINE_FEED, scan.index)
271
+ line_end = len(scan.text) if line_end < 0 else line_end
272
+ body_line = scan.text[scan.index : line_end].rstrip(CARRIAGE_RETURN)
273
+ scan.index = line_end + 1
274
+ if closes_the_heredoc(body_line, pending_heredoc):
275
+ break
276
+ scan.line_start = scan.index
277
+
278
+
279
+ def _end_line(scan: _Scan) -> None:
280
+ line = "".join(scan.all_characters)
281
+ if line.strip():
282
+ scan.all_lines.append(line)
283
+ scan.all_characters.clear()