bmad-module-ultracode-goal 3.0.0-rc.1 → 3.0.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/.claude-plugin/marketplace.json +1 -1
- package/docs/cross-session-recall.md +2 -2
- package/package.json +1 -1
- package/skills/ultracode-goal/references/ingest-and-scope.md +1 -1
- package/skills/ultracode-goal/references/preflight.md +1 -1
- package/skills/ultracode-goal/scripts/claim_check.py +37 -27
- package/skills/ultracode-goal/scripts/hooks/guard_pretooluse.py +472 -131
- package/skills/ultracode-goal/scripts/lib/mem_common.py +71 -24
- package/skills/ultracode-goal/scripts/link_worktree_deps.py +33 -21
|
@@ -19,7 +19,7 @@
|
|
|
19
19
|
"name": "bmad-module-ultracode-goal",
|
|
20
20
|
"source": "./",
|
|
21
21
|
"description": "Supercharges BMAD with Claude Code's Auto Mode, Auto Memory, and hooks: autonomous Epic execution to a machine-checked, TEA-gated Definition-of-Done. Execute Epics. Accumulate Knowledge. Deliver Outcomes.",
|
|
22
|
-
"version": "3.0.0
|
|
22
|
+
"version": "3.0.0",
|
|
23
23
|
"author": {
|
|
24
24
|
"name": "Armel"
|
|
25
25
|
},
|
|
@@ -103,7 +103,7 @@ Each recall call is attempted once and never retried. A run whose recall turned
|
|
|
103
103
|
|
|
104
104
|
The latch is how the guard knows a run is active. Only `mem_recall.py` changes it: `latch` writes or replaces it at Stage 1, and `unlatch` removes it at each exit (Finalize, a preflight STOP, or any other stop before Finalize, attended or headless), only when it carries that run's id.
|
|
105
105
|
|
|
106
|
-
The latch never belongs in git. `latch` adds
|
|
106
|
+
The latch never belongs in git. `latch` adds a line for the latch to the repository's `.git/info/exclude`, a local file git never commits: `/<artifacts folder>/.mem-state*`, anchored to the implementation artifacts folder so no other file is hidden. So on a project that tracks its artifacts folder, the latch does not show in `git status`, does not trip preflight's clean-tree check, and is not staged by a `git add -A`. A latch git already tracks, which a run on an earlier release could commit, still shows as a change: `latch` then prints `NOTE recall-latch-visible`, and you untrack it once by hand, from a terminal of your own once no run is active: while a latch is present, the guard denies a command that names it.
|
|
107
107
|
|
|
108
108
|
While a latch is present, whatever it records, the guard:
|
|
109
109
|
|
|
@@ -163,7 +163,7 @@ Each recall problem leaves a line in `.decision-log.md` and the run report: one
|
|
|
163
163
|
| `NOTE recall-store-unset` | Stage 1: recall is `on` but the store key is unset, or is not a `~`, absolute or `{project-root}` path. | Set `cross_session_recall_store` in `[workflow]`. |
|
|
164
164
|
| Red latch, `reason` `store-unwritable: <error>` | Stage 1: recall is `on` but the store folder could not be created or written. Recall is off for the run, and the run report repeats the reason. | Fix the folder (permissions, disk space, sandbox) or set the key to another folder. |
|
|
165
165
|
| Red latch, `reason` `no-fingerprint` | Stage 1: the repo has no commit yet, or the session's working folder is not inside it, so its records have no folder. Recall is off for the run. | Make a first commit, or start the session from the project folder. |
|
|
166
|
-
| `NOTE recall-latch-visible` | Stage 1: git can still see the latch, so it shows as a change and preflight's clean-tree check reads it. Either git already tracks it, committed by a run on an earlier release, or the repository's `.git/info/exclude` could not be written; the NOTE says which. |
|
|
166
|
+
| `NOTE recall-latch-visible` | Stage 1: git can still see the latch, so it shows as a change and preflight's clean-tree check reads it. Either git already tracks it, committed by a run on an earlier release, or the repository's `.git/info/exclude` could not be written; the NOTE says which. | Once no run is active, untrack it from a terminal of your own with `git rm --cached <the latch path>` and commit that, or fix the exclude file the NOTE names. While a latch is present, the guard denies a command that names it. |
|
|
167
167
|
| A latch call that exits non-zero | Stage 1: the latch call failed (for example, the implementation artifacts folder cannot be written). It writes no latch, so Finalize also logs `NOTE recall-latch-missing`; the log holds what it printed. | Fix what the log names. |
|
|
168
168
|
| A filter, drain or write call that exits non-zero | Stage 1 or Finalize: the call failed. The log and the run report hold what it printed, and the run goes on: a failed filter surfaces no advisories, a failed drain still lets the write run, and a failed write may leave no record. | Fix what the log names. |
|
|
169
169
|
| `NOTE recall-read-refused` | Stage 1: the permission layer refused the latch or filter call. A refused latch call leaves no latch, so recall is off for the run and Finalize also logs `NOTE recall-latch-missing`. A refused filter call only skips the read: Finalize still writes the record. | Let the recall scripts' `uv run` calls through your permission mode. |
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"$schema": "https://json.schemastore.org/package.json",
|
|
3
3
|
"name": "bmad-module-ultracode-goal",
|
|
4
|
-
"version": "3.0.0
|
|
4
|
+
"version": "3.0.0",
|
|
5
5
|
"description": "BMAD module — Run a BMAD Epic autonomously to a machine-checked, TEA-gated Definition-of-Done.",
|
|
6
6
|
"keywords": [
|
|
7
7
|
"bmad",
|
|
@@ -69,7 +69,7 @@ uv run {skill-root}/scripts/mem_recall.py latch --impl-artifacts {workflow.imple
|
|
|
69
69
|
|
|
70
70
|
The store value stays in single quotes, here and in every recall command, so the shell passes it as configured: a path with a space stays one argument, and a `$VAR` reaches the script unexpanded, where it counts as unset. The script itself expands a leading `~`, and resolves a project-root token against `--project-root`.
|
|
71
71
|
|
|
72
|
-
It checks the knob, that the store key names a folder, this repo's fingerprint, and that the store can be written, then writes the latch in one atomic step, keeps it out of git (it adds
|
|
72
|
+
It checks the knob, that the store key names a folder, this repo's fingerprint, and that the store can be written, then writes the latch in one atomic step, keeps it out of git (it adds a line for the latch, `/<artifacts folder>/.mem-state*`, to the repository's `.git/info/exclude`, so a tracked artifacts folder stays clean and a `git add -A` never stages the latch), and prints one JSON object, `{"latch": ..., "notes": [...], "reason": ...}`. The latch is **green** only when its `store_ok` is `true`, which takes recall `"on"`; with recall `"off"` it is written red on purpose. Log whether it is green, a red latch's `reason` and every line in `notes` to `.decision-log.md`. With `"on"` and no usable store key that line is `NOTE recall-store-unset`, naming the key, and Finalize's run report repeats it. With either knob, a `NOTE recall-latch-visible` line says git can still see the latch (git already tracks it, or the exclude file could not be written), so it reads as a change to preflight's `git_clean` check: carry it into the run report too, and leave the fix to the person, since untracking the latch is a change the run never makes. A red latch with recall `"on"` and no NOTE (its `reason` is `store-unwritable: ...` or `no-fingerprint`) is logged by that `reason`, which Finalize's run report repeats too. A latch call that exits non-zero writes no latch: log what it printed and go on with recall off. A latch another run left behind is replaced by this command and only by it: never delete the file, which the guard refuses while a latch is present.
|
|
73
73
|
|
|
74
74
|
While the latch is present the guard denies every claude-mem call, and every tool call that names the store or would change the latch other than these two scripts; reading the latch stays allowed. If the guard denies a call, do not route it another way and do not try to remove the latch: the deny names the latch and says what the person, not the run, should do about it.
|
|
75
75
|
|
|
@@ -206,7 +206,7 @@ Do these in order; each must be asserted, not assumed:
|
|
|
206
206
|
- `ULTRACODE_TEST_ARTIFACTS=<the resolved TEA test-artifacts root>` — deliberately **not** a `{workflow.…}` scalar: no such workflow key exists, and a `{workflow.test_artifacts}` placeholder would never be filled by config resolution. Inject the same root TEA config resolution yields (`scripts/preflight_check.py`, `_tea_artifacts_root`): the tea-config `test_artifacts` value with `{project-root}` substituted (a relative value resolves under the project root), defaulting to `{project-root}/_bmad-output/test-artifacts` when tea config names none. This is the directory the guard reads the story's `atdd-checklist-<story-id>.md` from; leave it unset and the un-skip proof below is out of scope and silently enforces nothing.
|
|
207
207
|
- The same PreToolUse guard also enforces the Cross-Session Recall latch from `{workflow.implementation_artifacts}/.mem-state.json`: the merged hook reads it automatically, fail-closed, with no new env var to inject. While a latch is present, whatever its version or colour, it denies every claude-mem call; every tool call that names the recall store, except the two pinned recall scripts (`scripts/mem_recall.py` and `scripts/mem_observation.py` under `uv run` or python); and every tool call that would change the latch itself, except those same scripts. Reading the latch stays allowed. **It enforces nothing unless the matcher above covers every tool**, because most of what it denies is a file-tool or MCP call, and a group matched on `Bash` is never invoked for one. This is the invariant that makes the all-tools matcher load-bearing rather than tidy.
|
|
208
208
|
- **Un-skip proof (production only).** With `ULTRACODE_TEST_ARTIFACTS` injected, the guard reads the **staged post-image** of every acceptance-test file the story's `atdd-checklist-<story-id>.md` enumerates (`git show :<path>`) and denies the commit while any of them still contains `test.skip(`. It proves the marker is absent from the blob being committed, so it fires on a story's *first* commit too, where there is no prior blob to diff against. Caveat worth stating plainly: **`test.skip(` is a JS/Vitest-specific token** (the Playwright/Vitest form TEA's ATDD generates today, which is web/JS-only) — a pytest (`@pytest.mark.skip`) or Go (`t.Skip()`) stack marks skips differently and this check would not see them. Under `--light` there is no atdd-checklist, so the check stays inert.
|
|
209
|
-
- **The commit/push guard anchors on each segment's leading token (`fp-7ac2643`).** The guard splits the command into shell segments and flags one only when `git` is that segment's **leading** token, once leading `VAR=val` assignments, shell keywords and group openers (`if`/`then`/`else`/`fi`, `for`/`while`/`until`/`do`/`done`, `case`/`esac`, `!`, and `(`/`{`, whether spaced or glued to the command name), and known exec wrappers (`env`, `command`, `sudo`, `time`, `nice`, `nohup`, `timeout`, `setsid`, `stdbuf`, `ionice`, `doas`, plus the string payload of a `sh|bash|zsh|dash` invoked with any `-c`-bearing flag cluster, `-lc` and `-cx` included) are stripped, and the subcommand it would then run is exactly `commit` or `push`, or
|
|
209
|
+
- **The commit/push guard anchors on each segment's leading token (`fp-7ac2643`).** The guard splits the command into shell segments and flags one only when `git` is that segment's **leading** token, once leading `VAR=val` assignments, shell keywords and group openers (`if`/`then`/`else`/`fi`, `for`/`while`/`until`/`do`/`done`, `case`/`esac`, `!`, and `(`/`{`, whether spaced or glued to the command name), and known exec wrappers (`env`, `command`, `sudo`, `time`, `nice`, `nohup`, `timeout`, `setsid`, `stdbuf`, `ionice`, `doas`, plus the string payload of a `sh|bash|zsh|dash` invoked with any `-c`-bearing flag cluster, `-lc` and `-cx` included) are stripped, and the subcommand it would then run is exactly `commit` or `push`, or any subcommand that is not one of git's built-in commands (spelled as git spells them), which counts as both, since what an alias runs, or whether an external `git-<name>` command shadows it, cannot be read from the command: so a git alias, even a read-only one (an alias `st` for `status`), and an external command run through git meet the commit and push gates, and the deny says to run the git command an alias stands for, or the external command by its own name. The keyword strip is what keeps a commit inside a compound command (`if true; then git commit …; fi`, `for … do git commit … done`, `( git commit … )`) reachable by the gates: without it a keyword sits in the leading position, the segment classifies as carrying no git write, and the protected-branch, tests-ran, freshness and empty-index gates are all skipped at once. Segment splitting covers `&&`, `||`, `;`, `|`, a newline, **and a lone `&`** (`npm run build & git commit …` is two segments, not one); those separator sets are applied as a **union** rather than merged into one regex, because splitting on `&` or a newline is quote-blind and a lone set would tear `git -c alias.x='a&b' commit` into fragments that each escape detection. So a verb merely *mentioned* inside an `echo`, a log line, or a here-string in a verification command is no longer denied, while a real `FOO=bar git commit`, `sudo git commit` or `timeout 30 git commit` still is: on a `{workflow.protected_branches}` branch both verbs are denied, and on the epic branch, before the story's `.tests-ran-<story_id>` marker exists, a real `git commit` is denied (the marker gate is commit-only: a real `git push` is never marker-gated). Residual, stated rather than hidden: a wrapper **not** on that list (`xargs git commit`, say) leaves a non-`git` leading token and is allowed through, so the tests-ran marker and the remote's branch protection are the nets behind this one. Three shapes still take the older matches-anywhere path and deny on a mention: a segment whose quoting cannot be parsed, one that hides its command inside a `$(…)` substitution or backticks, and, the newest, a **listed** shell wrapper (`sh|bash|zsh|dash`) whose command-string payload cannot be located at all, meaning no `-c`-bearing flag cluster with an operand after it, or nesting deeper than the shell-recursion cap. That third lane exists because locating the payload by the bare token `-c` alone missed every combined form (`bash -lc`, `sh -lc`, `bash -cx`, `zsh -ic`), and a wrapper whose payload went unread classified as carrying no git write and skipped all four commit gates. It is fail-closed in the same direction as the other two, and it has the same cost: `bash <script> "…git commit…"` now denies on the mention, so a verification command's own arguments must not spell a write verb. **Do not read the anchoring as having eliminated the false-positive class: it narrowed it, and the remainder bites prose about commits in particular.** Markdown prose names identifiers in backticks, and an apostrophe (`don't`) is unbalanced quoting, so a run-log line describing a commit denial routinely hits both fallbacks; a line that *leads* with the verb is a real verb-leading segment and denies on its own, and so does a line that leads with `git` and a word that is not one of git's commands. The rule that avoids all of it: **write prose with Write/Edit, never a Bash heredoc.** The guard's git gates read **Bash command strings alone**, so a decision-log append made with the file tools reaches none of them and no phrasing of the log can trip a gate. Now that the group is armed for every tool, the hook IS invoked for a `Write`, and it does decide on file tools, but only through its Cross-Session Recall rules: it denies a file-tool call that names the recall store or would change the run latch, and a decision-log append is neither, so it passes. Do not narrow the matcher back to `Bash` on the strength of this clause: that would leave those rules enforcing nothing. Reserve Bash for commands you actually mean to run. (execute.md step 4 covers the narrower marker-written-in-the-same-compound-command trap.)
|
|
210
210
|
- **Allowlist.** Pre-populate the tool allowlist with `{workflow.allowlist_commands}` so the unattended run can run tests/lint/build/commit without a permission prompt that no one is there to approve. Write one `Bash(<entry>:*)` allow rule per entry, with the entry exactly as it stands (`Bash(git worktree:*)` for `git worktree`). That rule matches the entry alone, or the entry, a space and anything after it, which is how `git worktree` covers the gate's `git worktree add <tmp-path> <commit>`. A rule without `:*` matches one exact command, so the stage's own calls would stop for approval. The entries land in the same `settings.local.json`, so a refused write here follows the same rule.
|
|
211
211
|
|
|
212
212
|
### Launch briefing (interactive only)
|
|
@@ -33,8 +33,7 @@ staged path exactly, or be a directory holding one: `README.md` does not match
|
|
|
33
33
|
a staged `docs/README.md` when a root `README.md` exists, and below the top
|
|
34
34
|
level it does not match the top level's `README.md` when the project root
|
|
35
35
|
holds one. On a filesystem that ignores case (Windows, macOS by default), the
|
|
36
|
-
match
|
|
37
|
-
a staged `src/guard.py`. A named path that exists nowhere matches by its trailing segments
|
|
36
|
+
match ignores case too, so `Src/Guard.py` names a staged `src/guard.py`. A named path that exists nowhere matches by its trailing segments
|
|
38
37
|
or as a directory anywhere in a staged path, so `guard.py` or `hooks/` still
|
|
39
38
|
match `src/hooks/guard.py`.
|
|
40
39
|
|
|
@@ -186,30 +185,34 @@ def _project_relative(staged: list[str], prefix: str) -> list[str]:
|
|
|
186
185
|
return [path[len(prefix) :] for path in staged if path.startswith(prefix)]
|
|
187
186
|
|
|
188
187
|
|
|
189
|
-
def
|
|
190
|
-
"""
|
|
188
|
+
def _ignores_case(path: Path, project_root: Path) -> bool:
|
|
189
|
+
"""Whether the filesystem holding `path`, which exists, ignores case.
|
|
191
190
|
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
191
|
+
True when the same path with one segment's case swapped is the same file,
|
|
192
|
+
as on Windows and on macOS by default. The last segment below the project
|
|
193
|
+
root that holds a letter is swapped (`docs` for `docs/2024`); the root and
|
|
194
|
+
the folders above it, which can sit on another filesystem, are never
|
|
195
|
+
probed. A path with no such segment, or one that cannot be checked, reads
|
|
196
|
+
as case-sensitive, which keeps the exact match.
|
|
197
197
|
"""
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
198
|
+
root = project_root.resolve()
|
|
199
|
+
try:
|
|
200
|
+
path = path.resolve()
|
|
201
|
+
except (OSError, RuntimeError):
|
|
202
|
+
return False
|
|
203
|
+
if not path.is_relative_to(root):
|
|
204
|
+
return False # `../x` names a path outside the project
|
|
205
|
+
for current in (path, *path.parents):
|
|
206
|
+
if current == root:
|
|
207
|
+
return False
|
|
208
|
+
swapped = current.name.swapcase()
|
|
209
|
+
if swapped == current.name:
|
|
210
|
+
continue
|
|
201
211
|
try:
|
|
202
|
-
|
|
203
|
-
except OSError:
|
|
204
|
-
return
|
|
205
|
-
|
|
206
|
-
folded = [name for name in names if name.casefold() == part.casefold()]
|
|
207
|
-
if len(folded) != 1:
|
|
208
|
-
return bare
|
|
209
|
-
part = folded[0]
|
|
210
|
-
parts.append(part)
|
|
211
|
-
current = current / part
|
|
212
|
-
return "/".join(parts)
|
|
212
|
+
return os.path.samefile(current, current.with_name(swapped))
|
|
213
|
+
except (OSError, ValueError):
|
|
214
|
+
return False
|
|
215
|
+
return False
|
|
213
216
|
|
|
214
217
|
|
|
215
218
|
def _matches(named: str, staged: list[str], project_root: Path, prefix: str = "") -> bool:
|
|
@@ -218,10 +221,17 @@ def _matches(named: str, staged: list[str], project_root: Path, prefix: str = ""
|
|
|
218
221
|
if any(path == bare or path.startswith(bare + "/") for path in local):
|
|
219
222
|
return True
|
|
220
223
|
if _known(bare, project_root, set(local)):
|
|
221
|
-
# It names a real path: only that path, or a file under it, will do
|
|
222
|
-
#
|
|
223
|
-
|
|
224
|
-
|
|
224
|
+
# It names a real path: only that path, or a file under it, will do.
|
|
225
|
+
# Where the filesystem ignores case, any spelling of it does, the work
|
|
226
|
+
# tree's and the index's alike (they differ after a case-only rename
|
|
227
|
+
# made without `git mv`).
|
|
228
|
+
full = project_root / bare
|
|
229
|
+
if not (full.exists() and _ignores_case(full, project_root)):
|
|
230
|
+
return False
|
|
231
|
+
folded = bare.casefold()
|
|
232
|
+
return any(
|
|
233
|
+
path.casefold() == folded or path.casefold().startswith(folded + "/") for path in local
|
|
234
|
+
)
|
|
225
235
|
if prefix and any(path == bare or path.startswith(bare + "/") for path in staged):
|
|
226
236
|
# Named from the top level (`app/src/a.py`).
|
|
227
237
|
return True
|
|
@@ -145,7 +145,8 @@ def _allow() -> NoReturn:
|
|
|
145
145
|
sys.exit(0)
|
|
146
146
|
|
|
147
147
|
|
|
148
|
-
def _deny(reason: str) -> NoReturn:
|
|
148
|
+
def _deny(reason: str, hint: str = "") -> NoReturn:
|
|
149
|
+
reason += hint
|
|
149
150
|
print(
|
|
150
151
|
json.dumps(
|
|
151
152
|
{
|
|
@@ -287,8 +288,8 @@ def _current_story(impl: Path | None) -> str | None:
|
|
|
287
288
|
# keeps a verb merely MENTIONED (inside an `echo`, a log line, a here-string)
|
|
288
289
|
# from being read as a real commit; matching the verb by exact token equality is
|
|
289
290
|
# what keeps `git commit-tree`-style near-misses out, which a trailing `\b`
|
|
290
|
-
# never did (`-` is itself a word boundary). A subcommand that is
|
|
291
|
-
# counts as
|
|
291
|
+
# never did (`-` is itself a word boundary). A subcommand that is not one git
|
|
292
|
+
# runs before any alias counts as both verbs (_unknown_subcommand_verbs).
|
|
292
293
|
|
|
293
294
|
_WRITE_VERBS = frozenset({"commit", "push"})
|
|
294
295
|
|
|
@@ -317,6 +318,8 @@ _EXEC_WRAPPERS = frozenset(
|
|
|
317
318
|
"stdbuf",
|
|
318
319
|
"ionice",
|
|
319
320
|
"doas",
|
|
321
|
+
"exec",
|
|
322
|
+
"builtin",
|
|
320
323
|
}
|
|
321
324
|
)
|
|
322
325
|
|
|
@@ -359,6 +362,10 @@ _SHELL_KEYWORDS = frozenset(
|
|
|
359
362
|
# of their own.
|
|
360
363
|
_GROUP_OPENERS = "({"
|
|
361
364
|
|
|
365
|
+
# A redirection operator, with its descriptor, at the start of a word; what
|
|
366
|
+
# follows it in the same word is its target.
|
|
367
|
+
_REDIRECTION = re.compile(r"^\d*(?:&>>|&>|>>|>&|>\||<<<|<<-|<<|<>|<&|>|<)")
|
|
368
|
+
|
|
362
369
|
# Global `git` options taking a SEPARATE value. The value must be skipped along
|
|
363
370
|
# with the option, or `git -C <path> commit` would read <path> as the
|
|
364
371
|
# subcommand and wave a real commit through.
|
|
@@ -372,6 +379,8 @@ _GIT_VALUE_OPTIONS = frozenset(
|
|
|
372
379
|
"--exec-path",
|
|
373
380
|
"--config-env",
|
|
374
381
|
"--super-prefix",
|
|
382
|
+
"--attr-source",
|
|
383
|
+
"--shallow-file",
|
|
375
384
|
}
|
|
376
385
|
)
|
|
377
386
|
|
|
@@ -382,7 +391,9 @@ _ASSIGNMENT = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*=")
|
|
|
382
391
|
_SUBSTITUTION_MARKERS = ("$(", "`", "<(")
|
|
383
392
|
|
|
384
393
|
# Depth cap on `sh -c` recursion: a bound, not a behavior anyone should rely on.
|
|
394
|
+
# Past it, a `git` the guard cannot read deeper counts as both verbs.
|
|
385
395
|
_MAX_SHELL_DEPTH = 4
|
|
396
|
+
_GIT_WORD = re.compile(r"\bgit\b")
|
|
386
397
|
|
|
387
398
|
# A short-option cluster that carries `-c`, whose operand is the command string.
|
|
388
399
|
# Matching only the bare `-c` token was a fail-open: every real combined form
|
|
@@ -396,53 +407,77 @@ _MAX_SHELL_DEPTH = 4
|
|
|
396
407
|
_PAYLOAD_FLAG = re.compile(r"^-[A-Za-z]*c[A-Za-z]*$")
|
|
397
408
|
|
|
398
409
|
|
|
399
|
-
# --- git
|
|
400
|
-
# `git ci` runs `git commit` when `alias.ci = commit`,
|
|
401
|
-
#
|
|
402
|
-
#
|
|
403
|
-
#
|
|
404
|
-
#
|
|
410
|
+
# --- git subcommands that are not git's own --------------------------------
|
|
411
|
+
# `git ci` runs `git commit` when `alias.ci = commit`, and nothing in the
|
|
412
|
+
# command says what an alias runs: git reads it from configuration the command
|
|
413
|
+
# can change before git starts. Whether `git <name>` is an external
|
|
414
|
+
# `git-<name>` command instead depends on PATH, which can differ between this
|
|
415
|
+
# hook and the shell that runs the command, or change inside it. So the guard
|
|
416
|
+
# reads neither. A git subcommand counts as no write only when it is one of
|
|
417
|
+
# git's built-in commands, which git runs before any alias and which nothing
|
|
418
|
+
# can move or shadow, spelled as git spells it (git matches its command names
|
|
419
|
+
# case-sensitively, so `git LOG` runs `alias.log`), or one of the commands git
|
|
420
|
+
# ships as scripts in its exec-path, while the command does not mention that
|
|
421
|
+
# path. Every other subcommand (an alias, an external command such as `git
|
|
422
|
+
# lfs`, a typo) counts as both verbs, so the commit and push gates judge it,
|
|
423
|
+
# and the deny names it (_unknown_hint). A built-in whose job is to run another
|
|
424
|
+
# git subcommand stays off the list (`for-each-repo`). Only commands built in on every
|
|
425
|
+
# supported build belong on the first list: none newer than Git 2.30, and no
|
|
426
|
+
# `whatchanged`, which Git 3.0 drops. A test checks both lists on both CI legs.
|
|
405
427
|
_GIT_COMMANDS = frozenset(
|
|
406
428
|
{
|
|
407
429
|
"add", "am", "annotate", "apply", "archive", "bisect", "blame",
|
|
408
|
-
"branch", "bundle", "cat-file", "check-attr",
|
|
409
|
-
"check-mailmap", "check-ref-format", "checkout",
|
|
410
|
-
"cherry", "cherry-pick", "clean", "clone", "column",
|
|
411
|
-
"commit-tree", "config", "count-objects", "credential",
|
|
412
|
-
"diff", "diff-files", "diff-index", "diff-tree",
|
|
413
|
-
"
|
|
414
|
-
"
|
|
415
|
-
"
|
|
416
|
-
"
|
|
417
|
-
"
|
|
418
|
-
"
|
|
419
|
-
"
|
|
420
|
-
"
|
|
421
|
-
"
|
|
422
|
-
"
|
|
423
|
-
"
|
|
424
|
-
"
|
|
425
|
-
"
|
|
430
|
+
"branch", "bugreport", "bundle", "cat-file", "check-attr",
|
|
431
|
+
"check-ignore", "check-mailmap", "check-ref-format", "checkout",
|
|
432
|
+
"checkout-index", "cherry", "cherry-pick", "clean", "clone", "column",
|
|
433
|
+
"commit-graph", "commit-tree", "config", "count-objects", "credential",
|
|
434
|
+
"describe", "diff", "diff-files", "diff-index", "diff-tree",
|
|
435
|
+
"difftool", "fast-export", "fast-import", "fetch", "fetch-pack",
|
|
436
|
+
"fmt-merge-msg", "for-each-ref", "format-patch",
|
|
437
|
+
"fsck", "gc", "grep", "hash-object", "help", "index-pack", "init",
|
|
438
|
+
"init-db", "interpret-trailers", "log", "ls-files", "ls-remote",
|
|
439
|
+
"ls-tree", "mailinfo", "mailsplit", "maintenance", "merge",
|
|
440
|
+
"merge-base", "merge-file", "merge-index", "merge-tree", "mktag",
|
|
441
|
+
"mktree", "multi-pack-index", "mv", "name-rev", "notes",
|
|
442
|
+
"pack-objects", "pack-refs", "patch-id", "prune", "prune-packed",
|
|
443
|
+
"pull", "range-diff", "read-tree", "rebase", "receive-pack", "reflog",
|
|
444
|
+
"remote", "repack", "replace", "rerere", "reset", "restore",
|
|
445
|
+
"rev-list", "rev-parse", "revert", "rm", "send-pack", "shortlog",
|
|
446
|
+
"show", "show-branch", "show-index", "show-ref", "sparse-checkout",
|
|
447
|
+
"stage", "stash", "status", "stripspace", "switch", "symbolic-ref",
|
|
448
|
+
"tag", "unpack-objects", "update-index", "update-ref",
|
|
449
|
+
"update-server-info", "upload-archive", "upload-pack", "var",
|
|
450
|
+
"verify-commit", "verify-pack", "verify-tag", "version", "worktree",
|
|
426
451
|
"write-tree",
|
|
427
452
|
}
|
|
428
453
|
)
|
|
429
|
-
|
|
430
|
-
#
|
|
454
|
+
# Commands git ships as scripts in its exec-path, which it also runs before an
|
|
455
|
+
# alias of the name, unless the command moves that path (`--exec-path`,
|
|
456
|
+
# `GIT_EXEC_PATH`): a mention of it anywhere in the command, a nested shell's
|
|
457
|
+
# included, makes them count as both verbs too.
|
|
458
|
+
_GIT_SCRIPT_COMMANDS = frozenset({"filter-branch", "mergetool", "quiltimport", "request-pull", "submodule"})
|
|
459
|
+
_EXEC_PATH_TEXT = re.compile(r"exec[-_]path", re.IGNORECASE)
|
|
460
|
+
|
|
461
|
+
# What a git subcommand that is not git's own counts as: both verbs, so the
|
|
431
462
|
# commit and push gates judge it, which is where the doubt belongs.
|
|
432
463
|
_UNRESOLVED_VERBS = frozenset(_WRITE_VERBS)
|
|
433
464
|
|
|
434
|
-
# A
|
|
435
|
-
#
|
|
436
|
-
|
|
437
|
-
# configuration on disk does not show when the guard looks.
|
|
438
|
-
_CONFIG_IN_COMMAND = re.compile(r"(?i:alias\.)|\bGIT_[A-Z0-9_]*=")
|
|
465
|
+
# A subcommand the deny's hint may quote: the shape of a command or alias name,
|
|
466
|
+
# so a fragment torn from a quoted argument never reaches the reason.
|
|
467
|
+
_NAME_SHAPE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$")
|
|
439
468
|
|
|
440
469
|
|
|
441
|
-
class
|
|
442
|
-
"""
|
|
470
|
+
class _CommandScope:
|
|
471
|
+
"""What classifying one command collects and reuses along the way."""
|
|
443
472
|
|
|
444
|
-
|
|
445
|
-
|
|
473
|
+
def __init__(self, command: str = "") -> None:
|
|
474
|
+
self.moves_exec_path = bool(_EXEC_PATH_TEXT.search(command))
|
|
475
|
+
# The subcommands counted as both verbs, in the order first met.
|
|
476
|
+
self.unknown: dict[str, None] = {}
|
|
477
|
+
# Each substitution body's verbs at a depth, so the four readings of a
|
|
478
|
+
# command, and their own readings of a nested body, classify it once
|
|
479
|
+
# there (a body met at the depth cap is read more shallowly elsewhere).
|
|
480
|
+
self.bodies: dict[tuple[str, int], set[str]] = {}
|
|
446
481
|
|
|
447
482
|
|
|
448
483
|
def _tokenize(segment: str) -> list[str]:
|
|
@@ -462,8 +497,8 @@ def _strip_assignments(tokens: list[str]) -> list[str]:
|
|
|
462
497
|
return tokens[index:]
|
|
463
498
|
|
|
464
499
|
|
|
465
|
-
def
|
|
466
|
-
"""
|
|
500
|
+
def _git_subcommand_index(tokens: list[str]) -> int | None:
|
|
501
|
+
"""Where the subcommand `git` would run sits among the tokens after `git`."""
|
|
467
502
|
index = 0
|
|
468
503
|
while index < len(tokens):
|
|
469
504
|
token = tokens[index]
|
|
@@ -473,76 +508,262 @@ def _git_subcommand(tokens: list[str]) -> str | None:
|
|
|
473
508
|
if token.startswith("-"):
|
|
474
509
|
index += 1
|
|
475
510
|
continue
|
|
476
|
-
return
|
|
511
|
+
return index
|
|
477
512
|
return None
|
|
478
513
|
|
|
479
514
|
|
|
480
|
-
|
|
481
|
-
|
|
482
|
-
"""`alias.<name>` as (answered, value); (True, None) when there is no alias.
|
|
515
|
+
def _unknown_subcommand_verbs(name: str, scope: _CommandScope | None) -> set[str]:
|
|
516
|
+
"""Both verbs for `git <name> ...` when `name` is not one of git's own commands.
|
|
483
517
|
|
|
484
|
-
|
|
485
|
-
|
|
486
|
-
|
|
487
|
-
|
|
488
|
-
"""
|
|
489
|
-
try:
|
|
490
|
-
out = subprocess.run(
|
|
491
|
-
["git", "config", "--get", f"alias.{name}"],
|
|
492
|
-
cwd=cwd or None,
|
|
493
|
-
capture_output=True,
|
|
494
|
-
text=True,
|
|
495
|
-
errors="replace",
|
|
496
|
-
timeout=10,
|
|
497
|
-
)
|
|
498
|
-
except (OSError, subprocess.SubprocessError):
|
|
499
|
-
return False, None
|
|
500
|
-
if out.returncode == 0:
|
|
501
|
-
return True, out.stdout.rstrip("\r\n")
|
|
502
|
-
if out.returncode == 1:
|
|
503
|
-
return True, None
|
|
504
|
-
return False, None
|
|
505
|
-
|
|
506
|
-
|
|
507
|
-
def _alias_write_verbs(
|
|
508
|
-
args: list[str], verb: str | None, depth: int, scope: _AliasScope | None
|
|
509
|
-
) -> set[str]:
|
|
510
|
-
"""The write verbs `git <args>` runs when its subcommand is an alias.
|
|
511
|
-
|
|
512
|
-
Empty for a git command of its own, and for a name that is no alias (an
|
|
513
|
-
external `git-<name>` command, or a typo git will refuse). An alias to
|
|
514
|
-
another git command is classified as that command, alias chains included;
|
|
515
|
-
a `!` alias as the shell command it runs, read both by segment and by the
|
|
516
|
-
matches-anywhere scan, since a shell alias is often a function definition
|
|
517
|
-
(`!f() { git commit "$@"; }; f`) whose segments lead with no `git`. Doubt
|
|
518
|
-
resolves to both verbs: an option ahead of the subcommand (`-C`, `-c`,
|
|
519
|
-
`--git-dir` can each change which configuration git reads), a command that
|
|
520
|
-
itself defines an alias or sets git configuration (_CONFIG_IN_COMMAND), a
|
|
521
|
-
lookup that does not answer, and a chain past the recursion cap.
|
|
518
|
+
Empty for a built-in command (_GIT_COMMANDS) and, while the command does
|
|
519
|
+
not mention git's exec-path, for one git ships as a script there
|
|
520
|
+
(_GIT_SCRIPT_COMMANDS). Anything else counts as both verbs and is recorded
|
|
521
|
+
on the scope, when it has a name's shape, for the deny's hint.
|
|
522
522
|
"""
|
|
523
|
-
if
|
|
523
|
+
if name in _GIT_COMMANDS:
|
|
524
524
|
return set()
|
|
525
|
-
|
|
526
|
-
if scope.unsure or args[0].lower() != verb or depth >= _MAX_SHELL_DEPTH:
|
|
527
|
-
return set(_UNRESOLVED_VERBS)
|
|
528
|
-
answered, value = _git_alias(verb, scope.cwd)
|
|
529
|
-
if not answered:
|
|
530
|
-
return set(_UNRESOLVED_VERBS)
|
|
531
|
-
if value is None:
|
|
525
|
+
if name in _GIT_SCRIPT_COMMANDS and not (scope and scope.moves_exec_path):
|
|
532
526
|
return set()
|
|
533
|
-
if
|
|
534
|
-
|
|
535
|
-
|
|
527
|
+
if scope is not None and _NAME_SHAPE.match(name):
|
|
528
|
+
scope.unknown.setdefault(name, None)
|
|
529
|
+
return set(_UNRESOLVED_VERBS)
|
|
530
|
+
|
|
531
|
+
|
|
532
|
+
def _substitution_bodies(text: str) -> list[str]:
|
|
533
|
+
"""The commands inside each `$(...)`, `<(...)`, `>(...)` and backtick pair.
|
|
534
|
+
|
|
535
|
+
Text in single quotes is skipped, since the shell substitutes nothing
|
|
536
|
+
there (`echo 'run `git ci` later'`), and so is a backslash-escaped
|
|
537
|
+
character; double quotes do not stop a substitution. Parentheses are
|
|
538
|
+
counted, not parsed, and a heredoc is read as plain text: a body that comes
|
|
539
|
+
out wrong is classified anyway, which can only add verbs.
|
|
540
|
+
"""
|
|
541
|
+
bodies: list[str] = []
|
|
542
|
+
index = 0
|
|
543
|
+
in_double = False
|
|
544
|
+
while index < len(text):
|
|
545
|
+
char = text[index]
|
|
546
|
+
if char == "\\":
|
|
547
|
+
index += 2
|
|
548
|
+
elif char == "'" and not in_double:
|
|
549
|
+
end = text.find("'", index + 1)
|
|
550
|
+
index = len(text) if end == -1 else end + 1
|
|
551
|
+
elif char == '"':
|
|
552
|
+
in_double = not in_double
|
|
553
|
+
index += 1
|
|
554
|
+
elif text.startswith(("$(", "<(", ">("), index):
|
|
555
|
+
start = index = index + 2
|
|
556
|
+
level = 1
|
|
557
|
+
while index < len(text) and level:
|
|
558
|
+
if text[index] == "(":
|
|
559
|
+
level += 1
|
|
560
|
+
elif text[index] == ")":
|
|
561
|
+
level -= 1
|
|
562
|
+
index += 1
|
|
563
|
+
bodies.append(text[start : index - 1 if level == 0 else index])
|
|
564
|
+
elif char == "`":
|
|
565
|
+
end = text.find("`", index + 1)
|
|
566
|
+
end = len(text) if end == -1 else end
|
|
567
|
+
bodies.append(text[index + 1 : end])
|
|
568
|
+
index = end + 1
|
|
569
|
+
else:
|
|
570
|
+
index += 1
|
|
571
|
+
return bodies
|
|
572
|
+
|
|
573
|
+
|
|
574
|
+
# shlex's punctuation mode yields a run of these characters as one token (a
|
|
575
|
+
# newline is one of them, so it ends a segment as it does in bash). The run is
|
|
576
|
+
# split into bash's own operators, longest first: a control operator ends a
|
|
577
|
+
# segment (`;`, `&&`, `|&`, a newline, the `()` of a function definition, a
|
|
578
|
+
# process substitution's `<(` or `>(`, so `true;>(git commit)` reads its
|
|
579
|
+
# body), and a redirection (`>&`, `>|`, `<<`) stays in the segment it opens,
|
|
580
|
+
# where _strip_leading_noise reads it.
|
|
581
|
+
_PUNCTUATION = "();<>|&\n"
|
|
582
|
+
_OPERATORS = (
|
|
583
|
+
";;&", "&>>", "<<<", "<<-", ";;", ";&", "&&", "||", "|&", "&>", ">>", ">&",
|
|
584
|
+
"<&", ">|", "<>", "<<", "<(", ">(", ";", "&", "|", "<", ">", "(", ")", "\n",
|
|
585
|
+
) # fmt: skip
|
|
586
|
+
_CONTROL_OPERATORS = frozenset(
|
|
587
|
+
{";;&", ";;", ";&", "&&", "||", "|&", ";", "&", "|", "(", ")", "\n", "<(", ">("}
|
|
588
|
+
)
|
|
589
|
+
|
|
590
|
+
|
|
591
|
+
# Punctuation inside quotes, or escaped, is a word's text, not an operator, but
|
|
592
|
+
# shlex hands a quoted `')>'` back as `)>`, which reads as one. So it is masked
|
|
593
|
+
# before lexing, with a quote scan that follows shlex's own posix rules (a
|
|
594
|
+
# backslash escapes outside single quotes; single quotes take everything up to
|
|
595
|
+
# the next one; double quotes take an escaped character as it is), and unmasked
|
|
596
|
+
# in the tokens after.
|
|
597
|
+
_MASK_BASE = 0xE000
|
|
598
|
+
|
|
599
|
+
|
|
600
|
+
def _mask_quoted(text: str) -> str:
|
|
601
|
+
"""`text` with each punctuation character inside quotes or escaped masked.
|
|
602
|
+
|
|
603
|
+
Unbalanced quotes leave the text as it is, for shlex to refuse.
|
|
604
|
+
"""
|
|
605
|
+
out: list[str] = []
|
|
606
|
+
index = 0
|
|
607
|
+
size = len(text)
|
|
608
|
+
|
|
609
|
+
def masked(char: str) -> str:
|
|
610
|
+
return chr(_MASK_BASE + ord(char)) if char in _PUNCTUATION else char
|
|
611
|
+
|
|
612
|
+
while index < size:
|
|
613
|
+
char = text[index]
|
|
614
|
+
if char == "\\" and index + 1 < size:
|
|
615
|
+
out.append(char + masked(text[index + 1]))
|
|
616
|
+
index += 2
|
|
617
|
+
elif char == "'":
|
|
618
|
+
end = text.find("'", index + 1)
|
|
619
|
+
if end == -1:
|
|
620
|
+
return text
|
|
621
|
+
out.append("'" + "".join(masked(c) for c in text[index + 1 : end]) + "'")
|
|
622
|
+
index = end + 1
|
|
623
|
+
elif char == '"':
|
|
624
|
+
end = index + 1
|
|
625
|
+
body: list[str] = []
|
|
626
|
+
while end < size and text[end] != '"':
|
|
627
|
+
if text[end] == "\\" and end + 1 < size:
|
|
628
|
+
body.append(text[end] + masked(text[end + 1]))
|
|
629
|
+
end += 2
|
|
630
|
+
else:
|
|
631
|
+
body.append(masked(text[end]))
|
|
632
|
+
end += 1
|
|
633
|
+
if end >= size:
|
|
634
|
+
return text
|
|
635
|
+
out.append('"' + "".join(body) + '"')
|
|
636
|
+
index = end + 1
|
|
637
|
+
else:
|
|
638
|
+
out.append(char)
|
|
639
|
+
index += 1
|
|
640
|
+
return "".join(out)
|
|
641
|
+
|
|
642
|
+
|
|
643
|
+
def _unmask(token: str) -> str:
|
|
644
|
+
return "".join(
|
|
645
|
+
chr(ord(c) - _MASK_BASE) if _MASK_BASE <= ord(c) < _MASK_BASE + 128 else c for c in token
|
|
646
|
+
)
|
|
647
|
+
|
|
648
|
+
|
|
649
|
+
def _operators(token: str) -> list[str] | None:
|
|
650
|
+
"""A run of punctuation as bash's operators, longest first; None for a word."""
|
|
651
|
+
if not token or not set(token) <= set(_PUNCTUATION):
|
|
652
|
+
return None
|
|
653
|
+
found: list[str] = []
|
|
654
|
+
index = 0
|
|
655
|
+
while index < len(token):
|
|
656
|
+
operator = next(op for op in _OPERATORS if token.startswith(op, index))
|
|
657
|
+
found.append(operator)
|
|
658
|
+
index += len(operator)
|
|
659
|
+
return found
|
|
660
|
+
|
|
661
|
+
# A heredoc's start, with its delimiter, quoted or not.
|
|
662
|
+
_HEREDOC_START = re.compile(r"<<-?[ \t]*(['\"]?)([A-Za-z_][A-Za-z0-9_]*)\1")
|
|
663
|
+
|
|
664
|
+
|
|
665
|
+
def _lexable(command: str) -> str:
|
|
666
|
+
"""The command with what shlex reads unlike bash taken out, for a reading
|
|
667
|
+
of its own.
|
|
668
|
+
|
|
669
|
+
A comment (a `#` that starts a word, outside quotes, up to its line's end),
|
|
670
|
+
an ANSI-C string `$'...'`, whose backslash escapes shlex does not know and
|
|
671
|
+
in which nothing is substituted (it becomes an empty word), and a heredoc's
|
|
672
|
+
body (the lines up to its delimiter, which may hold any text, apostrophes
|
|
673
|
+
included). The rest is copied as it is, quotes and escapes included, for
|
|
674
|
+
shlex to read. Its reading of comments and heredocs is rough (a `#` after
|
|
675
|
+
`$(...)`, a `<<` in arithmetic), and a misread takes out text bash runs, so
|
|
676
|
+
this text is only ever read beside the command as it is
|
|
677
|
+
(_command_write_verbs): it can add a reading, never replace one.
|
|
678
|
+
"""
|
|
679
|
+
out: list[str] = []
|
|
680
|
+
pending: list[str] = [] # heredoc delimiters whose bodies start at the next newline
|
|
681
|
+
index = 0
|
|
682
|
+
size = len(command)
|
|
683
|
+
word_start = True
|
|
684
|
+
while index < size:
|
|
685
|
+
char = command[index]
|
|
686
|
+
if char == "\\":
|
|
687
|
+
out.append(command[index : index + 2])
|
|
688
|
+
index += 2
|
|
689
|
+
word_start = False
|
|
690
|
+
elif command.startswith("$'", index):
|
|
691
|
+
end = index + 2
|
|
692
|
+
while end < size and command[end] != "'":
|
|
693
|
+
end += 2 if command[end] == "\\" else 1
|
|
694
|
+
out.append("''")
|
|
695
|
+
index = end + 1
|
|
696
|
+
word_start = False
|
|
697
|
+
elif char in "'\"":
|
|
698
|
+
end = index + 1
|
|
699
|
+
while end < size and command[end] != char:
|
|
700
|
+
end += 2 if char == '"' and command[end] == "\\" else 1
|
|
701
|
+
out.append(command[index : end + 1])
|
|
702
|
+
index = end + 1
|
|
703
|
+
word_start = False
|
|
704
|
+
elif char == "#" and word_start:
|
|
705
|
+
end = command.find("\n", index)
|
|
706
|
+
index = size if end == -1 else end
|
|
707
|
+
elif command.startswith("<<", index) and not command.startswith("<<<", index):
|
|
708
|
+
match = _HEREDOC_START.match(command, index)
|
|
709
|
+
if match:
|
|
710
|
+
pending.append(match.group(2))
|
|
711
|
+
out.append(command[index : match.end()])
|
|
712
|
+
index = match.end()
|
|
713
|
+
else:
|
|
714
|
+
out.append("<<")
|
|
715
|
+
index += 2
|
|
716
|
+
word_start = False
|
|
717
|
+
elif char == "\n":
|
|
718
|
+
out.append("\n")
|
|
719
|
+
index += 1
|
|
720
|
+
word_start = True
|
|
721
|
+
for delimiter in pending:
|
|
722
|
+
while index < size:
|
|
723
|
+
end = command.find("\n", index)
|
|
724
|
+
line = command[index : size if end == -1 else end]
|
|
725
|
+
index = size if end == -1 else end + 1
|
|
726
|
+
if line.lstrip("\t") == delimiter:
|
|
727
|
+
break
|
|
728
|
+
pending.clear()
|
|
729
|
+
else:
|
|
730
|
+
out.append(char)
|
|
731
|
+
index += 1
|
|
732
|
+
word_start = char in " \t;&|()<>"
|
|
733
|
+
return "".join(out)
|
|
734
|
+
|
|
735
|
+
|
|
736
|
+
def _quoted_segments(command: str) -> list[list[str]]:
|
|
737
|
+
"""The command's segments as quote-aware tokens, or none when it cannot be read.
|
|
738
|
+
|
|
739
|
+
The quote-blind splits in _command_write_verbs tear a quoted `;`, `&&` or
|
|
740
|
+
`|` apart (`git ci -m 'fix: a; b'`), and each fragment then tokenizes to
|
|
741
|
+
nothing. shlex in punctuation mode keeps it inside its word.
|
|
742
|
+
"""
|
|
743
|
+
lexer = shlex.shlex(_mask_quoted(command), posix=True, punctuation_chars=_PUNCTUATION)
|
|
744
|
+
lexer.whitespace = " \t\r" # a newline is punctuation, so it ends a segment
|
|
745
|
+
lexer.whitespace_split = True
|
|
746
|
+
lexer.commenters = "" # shlex would start one mid-word; bash does not
|
|
536
747
|
try:
|
|
537
|
-
|
|
748
|
+
tokens = list(lexer)
|
|
538
749
|
except ValueError:
|
|
539
|
-
return
|
|
540
|
-
|
|
541
|
-
|
|
750
|
+
return []
|
|
751
|
+
segments: list[list[str]] = [[]]
|
|
752
|
+
for token in tokens:
|
|
753
|
+
operators = _operators(token)
|
|
754
|
+
if operators is None:
|
|
755
|
+
segments[-1].append(_unmask(token))
|
|
756
|
+
continue
|
|
757
|
+
for operator in operators:
|
|
758
|
+
if operator in _CONTROL_OPERATORS:
|
|
759
|
+
segments.append([])
|
|
760
|
+
else:
|
|
761
|
+
segments[-1].append(operator)
|
|
762
|
+
return [segment for segment in segments if segment]
|
|
542
763
|
|
|
543
764
|
|
|
544
765
|
def _shell_payload_verbs(
|
|
545
|
-
tokens: list[str], depth: int, scope:
|
|
766
|
+
tokens: list[str], depth: int, scope: _CommandScope | None = None
|
|
546
767
|
) -> set[str] | None:
|
|
547
768
|
"""Verbs written by the string payload of a `sh -c '…'`-style invocation.
|
|
548
769
|
|
|
@@ -556,8 +777,10 @@ def _shell_payload_verbs(
|
|
|
556
777
|
"""
|
|
557
778
|
if depth >= _MAX_SHELL_DEPTH:
|
|
558
779
|
# The cap is a recursion bound, not a verdict: refusing to look deeper
|
|
559
|
-
# is exactly the "cannot read it" case, so it fails closed too
|
|
560
|
-
|
|
780
|
+
# is exactly the "cannot read it" case, so it fails closed too, and a
|
|
781
|
+
# `git` in what it cannot read counts as both verbs (the
|
|
782
|
+
# matches-anywhere scan knows only the literal verbs, not an alias).
|
|
783
|
+
return set(_UNRESOLVED_VERBS) if any(_GIT_WORD.search(t) for t in tokens) else None
|
|
561
784
|
for index, token in enumerate(tokens):
|
|
562
785
|
if _PAYLOAD_FLAG.match(token) and index + 1 < len(tokens):
|
|
563
786
|
return _command_write_verbs(tokens[index + 1], depth + 1, scope)
|
|
@@ -565,30 +788,49 @@ def _shell_payload_verbs(
|
|
|
565
788
|
|
|
566
789
|
|
|
567
790
|
def _strip_leading_noise(tokens: list[str]) -> list[str]:
|
|
568
|
-
"""Drop leading `VAR=val` assignments, shell keywords
|
|
791
|
+
"""Drop leading `VAR=val` assignments, shell keywords, group openers and
|
|
792
|
+
redirections.
|
|
569
793
|
|
|
570
794
|
Applied repeatedly because they nest: `if ! FOO=1 git commit …` puts three
|
|
571
|
-
different kinds of noise ahead of the verb.
|
|
572
|
-
|
|
573
|
-
|
|
795
|
+
different kinds of noise ahead of the verb. A name after `function`, or
|
|
796
|
+
after `coproc` ahead of a group, names the function, not a command; a
|
|
797
|
+
redirection ahead of the command (`>/dev/null git commit`, `2>&1 git
|
|
798
|
+
commit`, `> out git commit`) is no command either. Every strip here can
|
|
799
|
+
only turn an unclassifiable segment into a classifiable one, so this
|
|
800
|
+
direction is fail-closed by construction.
|
|
574
801
|
"""
|
|
575
802
|
while True:
|
|
576
803
|
stripped = _strip_assignments(tokens)
|
|
577
804
|
if stripped:
|
|
578
805
|
head = stripped[0]
|
|
579
806
|
bare = head.lstrip(_GROUP_OPENERS)
|
|
807
|
+
redirect = _REDIRECTION.match(head)
|
|
580
808
|
if bare != head:
|
|
581
809
|
# `(git commit …)` — opener glued to the command name.
|
|
582
810
|
stripped = ([bare] + stripped[1:]) if bare else stripped[1:]
|
|
811
|
+
elif head == "function" and len(stripped) > 1:
|
|
812
|
+
stripped = stripped[2:]
|
|
813
|
+
elif head == "coproc" and len(stripped) > 2 and stripped[2] in ("{", "("):
|
|
814
|
+
stripped = stripped[2:]
|
|
583
815
|
elif head.lower() in _SHELL_KEYWORDS:
|
|
584
816
|
stripped = stripped[1:]
|
|
817
|
+
elif redirect:
|
|
818
|
+
# An operator alone (`>`, `2>&`) takes the next word as its
|
|
819
|
+
# target, unless that word is `git`: a quoted punctuation word
|
|
820
|
+
# (`exec -a ')>' git ci`) reads as an operator here, and the
|
|
821
|
+
# git after it must not be taken for its target.
|
|
822
|
+
alone = redirect.end() == len(head)
|
|
823
|
+
target_is_git = alone and len(stripped) > 1 and os.path.basename(stripped[1]).lower() == "git"
|
|
824
|
+
stripped = stripped[2:] if alone and not target_is_git else stripped[1:]
|
|
825
|
+
elif head.isdigit() and len(stripped) > 1 and _REDIRECTION.match(stripped[1]):
|
|
826
|
+
stripped = stripped[1:] # the descriptor of `2 >&1`, split by the quote-aware reading
|
|
585
827
|
if stripped == tokens:
|
|
586
828
|
return stripped
|
|
587
829
|
tokens = stripped
|
|
588
830
|
|
|
589
831
|
|
|
590
832
|
def _token_write_verbs(
|
|
591
|
-
tokens: list[str], depth: int, scope:
|
|
833
|
+
tokens: list[str], depth: int, scope: _CommandScope | None = None
|
|
592
834
|
) -> set[str] | None:
|
|
593
835
|
"""Classify one tokenized segment: which write verbs would it actually run?
|
|
594
836
|
|
|
@@ -600,12 +842,21 @@ def _token_write_verbs(
|
|
|
600
842
|
return set()
|
|
601
843
|
head = os.path.basename(tokens[0]).lower()
|
|
602
844
|
if head == "git":
|
|
603
|
-
|
|
604
|
-
if
|
|
605
|
-
return
|
|
606
|
-
|
|
845
|
+
index = _git_subcommand_index(tokens[1:])
|
|
846
|
+
if index is None:
|
|
847
|
+
return set()
|
|
848
|
+
if tokens[1 + index].lower() in _WRITE_VERBS:
|
|
849
|
+
return {tokens[1 + index].lower()}
|
|
850
|
+
return _unknown_subcommand_verbs(tokens[1 + index], scope)
|
|
607
851
|
if head in _SHELL_WRAPPERS:
|
|
608
852
|
return _shell_payload_verbs(tokens[1:], depth, scope)
|
|
853
|
+
if head == "eval":
|
|
854
|
+
# `eval` runs its arguments, joined, as a command of its own, after a
|
|
855
|
+
# `--` it skips.
|
|
856
|
+
if depth >= _MAX_SHELL_DEPTH:
|
|
857
|
+
return set(_UNRESOLVED_VERBS) if any(_GIT_WORD.search(t) for t in tokens) else None
|
|
858
|
+
args = tokens[2:] if tokens[1:2] == ["--"] else tokens[1:]
|
|
859
|
+
return _command_write_verbs(" ".join(args), depth + 1, scope)
|
|
609
860
|
if head in _EXEC_WRAPPERS:
|
|
610
861
|
# Every wrapper has its own option grammar (`timeout 30 …`, `nice -n 10
|
|
611
862
|
# …`, `sudo -u u …`, `stdbuf -oL …`), and modelling them one by one is
|
|
@@ -615,7 +866,7 @@ def _token_write_verbs(
|
|
|
615
866
|
# parsing the wrapper.
|
|
616
867
|
for index in range(1, len(tokens)):
|
|
617
868
|
name = os.path.basename(tokens[index]).lower()
|
|
618
|
-
if name
|
|
869
|
+
if name in ("git", "eval") or name in _SHELL_WRAPPERS or name in _EXEC_WRAPPERS:
|
|
619
870
|
return _token_write_verbs(tokens[index:], depth, scope)
|
|
620
871
|
return set()
|
|
621
872
|
|
|
@@ -626,29 +877,82 @@ def _anywhere_write_verbs(segment: str) -> set[str]:
|
|
|
626
877
|
return {match.group("verb").lower()} if match else set()
|
|
627
878
|
|
|
628
879
|
|
|
629
|
-
def
|
|
880
|
+
def _body_verbs(segment: str, depth: int, scope: _CommandScope | None) -> set[str]:
|
|
881
|
+
"""The write verbs of each substitution body in the segment, each read as a
|
|
882
|
+
command of its own, once per body and depth; past the depth cap, both verbs
|
|
883
|
+
for a `git` the guard cannot read deeper."""
|
|
884
|
+
if depth >= _MAX_SHELL_DEPTH:
|
|
885
|
+
return set(_UNRESOLVED_VERBS) if _GIT_WORD.search(segment) else set()
|
|
886
|
+
verbs: set[str] = set()
|
|
887
|
+
for body in _substitution_bodies(segment):
|
|
888
|
+
if scope is None:
|
|
889
|
+
verbs |= _command_write_verbs(body, depth + 1, scope)
|
|
890
|
+
continue
|
|
891
|
+
key = (body, depth)
|
|
892
|
+
if key not in scope.bodies:
|
|
893
|
+
scope.bodies[key] = set() # a body that holds itself stops here
|
|
894
|
+
scope.bodies[key] = _command_write_verbs(body, depth + 1, scope)
|
|
895
|
+
verbs |= scope.bodies[key]
|
|
896
|
+
return verbs
|
|
897
|
+
|
|
898
|
+
|
|
899
|
+
def _without_comments(segment: str) -> str:
|
|
900
|
+
"""The segment with its line continuations joined and each line's trailing
|
|
901
|
+
`#` comment, and a trailing backslash, taken out. Read quote-blind, so it
|
|
902
|
+
can cut a quoted `#` too: it is only ever an extra reading."""
|
|
903
|
+
lines = segment.replace("\\\n", " ").split("\n")
|
|
904
|
+
return "\n".join(re.sub(r"(^|\s)#.*$", r"\1", line) for line in lines).rstrip().rstrip("\\")
|
|
905
|
+
|
|
906
|
+
|
|
907
|
+
def _uncommented_verbs(segment: str, depth: int, scope: _CommandScope | None) -> set[str]:
|
|
908
|
+
"""The verbs of the segment read without its comments, when it does not
|
|
909
|
+
tokenize as it is: an apostrophe in a trailing comment (`git ci # it's`)
|
|
910
|
+
leaves no tokens, and the matches-anywhere scan knows no alias."""
|
|
911
|
+
stripped = _without_comments(segment)
|
|
912
|
+
if stripped == segment:
|
|
913
|
+
return set()
|
|
914
|
+
try:
|
|
915
|
+
tokens = _tokenize(stripped)
|
|
916
|
+
except ValueError:
|
|
917
|
+
return set()
|
|
918
|
+
return _token_write_verbs(tokens, depth, scope) or set()
|
|
919
|
+
|
|
920
|
+
|
|
921
|
+
def _segment_write_verbs(segment: str, depth: int, scope: _CommandScope | None = None) -> set[str]:
|
|
630
922
|
if any(marker in segment for marker in _SUBSTITUTION_MARKERS):
|
|
631
923
|
# The real command hides inside the substitution; anchoring would read
|
|
632
|
-
# the outer word and allow it. Fall back rather than fail open.
|
|
633
|
-
|
|
924
|
+
# the outer word and allow it. Fall back rather than fail open. Each
|
|
925
|
+
# substitution's body is classified as a command of its own, and the
|
|
926
|
+
# outer words too where they tokenize, so a git alias inside one
|
|
927
|
+
# (`echo "$(git ci)"`) or around one (`git ci -m "$(date)"`) is seen.
|
|
928
|
+
verbs = _anywhere_write_verbs(segment) | _body_verbs(segment, depth, scope)
|
|
929
|
+
try:
|
|
930
|
+
tokens = _tokenize(segment)
|
|
931
|
+
except ValueError:
|
|
932
|
+
return verbs | _uncommented_verbs(segment, depth, scope)
|
|
933
|
+
return verbs | (_token_write_verbs(tokens, depth, scope) or set())
|
|
934
|
+
# An output process substitution's body is a command too. It is read on its
|
|
935
|
+
# own, not through the matches-anywhere scan, which would deny a read whose
|
|
936
|
+
# words name a verb (`git log --grep=push > >(cat)`).
|
|
937
|
+
verbs = _body_verbs(segment, depth, scope) if ">(" in segment else set()
|
|
634
938
|
try:
|
|
635
939
|
tokens = _tokenize(segment)
|
|
636
940
|
except ValueError:
|
|
637
941
|
# Unbalanced quotes: there are no trustworthy tokens, so fall back to
|
|
638
|
-
# the legacy scan rather than wave the segment through
|
|
639
|
-
#
|
|
640
|
-
# nor a clean deny.
|
|
641
|
-
return _anywhere_write_verbs(segment)
|
|
642
|
-
|
|
643
|
-
if
|
|
942
|
+
# the legacy scan rather than wave the segment through, and read the
|
|
943
|
+
# segment once more without its comments. Letting the exception escape
|
|
944
|
+
# would exit non-zero, which is neither a clean allow nor a clean deny.
|
|
945
|
+
return verbs | _anywhere_write_verbs(segment) | _uncommented_verbs(segment, depth, scope)
|
|
946
|
+
found = _token_write_verbs(tokens, depth, scope)
|
|
947
|
+
if found is None:
|
|
644
948
|
# A listed shell wrapper whose payload could not be located. Same
|
|
645
949
|
# treatment as the two lanes above: scan the raw segment rather than
|
|
646
950
|
# let an unreadable invocation classify as carrying no write.
|
|
647
|
-
return _anywhere_write_verbs(segment)
|
|
648
|
-
return verbs
|
|
951
|
+
return verbs | _anywhere_write_verbs(segment)
|
|
952
|
+
return verbs | found
|
|
649
953
|
|
|
650
954
|
|
|
651
|
-
def _command_write_verbs(command: str, depth: int, scope:
|
|
955
|
+
def _command_write_verbs(command: str, depth: int, scope: _CommandScope | None = None) -> set[str]:
|
|
652
956
|
verbs: set[str] = set()
|
|
653
957
|
# Classified under BOTH separator sets, unioned. Neither alone is safe:
|
|
654
958
|
#
|
|
@@ -691,18 +995,51 @@ def _command_write_verbs(command: str, depth: int, scope: _AliasScope | None = N
|
|
|
691
995
|
):
|
|
692
996
|
for segment in re.split(separators, command):
|
|
693
997
|
verbs |= _segment_write_verbs(segment, depth, scope)
|
|
998
|
+
# Quote-aware readings join the union: they keep a quoted separator inside
|
|
999
|
+
# its word (`git ci -m 'fix: a; b'`), which the three quote-blind splits
|
|
1000
|
+
# tear into fragments that classify as nothing, and like them they can
|
|
1001
|
+
# only add verbs. One reads the command as it is; the other reads it with
|
|
1002
|
+
# what shlex cannot lex taken out (_lexable: a comment holding an
|
|
1003
|
+
# apostrophe, `$'...'`, a heredoc body), and adds to the first, never
|
|
1004
|
+
# replaces it. A text shlex cannot read adds none.
|
|
1005
|
+
lexable = _lexable(command)
|
|
1006
|
+
for text in (command,) if lexable == command else (command, lexable):
|
|
1007
|
+
for tokens in _quoted_segments(text):
|
|
1008
|
+
verbs |= _token_write_verbs(tokens, depth, scope) or set()
|
|
694
1009
|
return verbs
|
|
695
1010
|
|
|
696
1011
|
|
|
697
|
-
def
|
|
1012
|
+
def _classify(command: str) -> tuple[set[str], list[str]]:
|
|
1013
|
+
"""The {'commit','push'} subset the command would perform, and the git
|
|
1014
|
+
subcommands that are not git's own it counted as both, for the git gates'
|
|
1015
|
+
deny hint (_unknown_hint)."""
|
|
1016
|
+
scope = _CommandScope(command)
|
|
1017
|
+
return _command_write_verbs(command, 0, scope), list(scope.unknown)
|
|
1018
|
+
|
|
1019
|
+
|
|
1020
|
+
def _git_writes(command: str) -> set[str]:
|
|
698
1021
|
"""Return the {'commit','push'} subset the command would perform.
|
|
699
1022
|
|
|
700
1023
|
Classifies each shell segment independently, so a chained
|
|
701
|
-
`git add && git commit` is still caught. A git
|
|
702
|
-
|
|
1024
|
+
`git add && git commit` is still caught. A git subcommand that is not one
|
|
1025
|
+
of git's own counts as both (_unknown_subcommand_verbs).
|
|
703
1026
|
"""
|
|
704
|
-
|
|
705
|
-
|
|
1027
|
+
return _classify(command)[0]
|
|
1028
|
+
|
|
1029
|
+
|
|
1030
|
+
def _unknown_hint(names: list[str]) -> str:
|
|
1031
|
+
"""The note a git gate's deny adds when the command runs a subcommand that
|
|
1032
|
+
is not git's own: it may be why the command was denied, and what to do."""
|
|
1033
|
+
if not names:
|
|
1034
|
+
return ""
|
|
1035
|
+
shown = ", ".join(f"`git {name}`" for name in names[:3])
|
|
1036
|
+
return (
|
|
1037
|
+
f" Note: this command runs {shown}, which is not one of git's built-in "
|
|
1038
|
+
"commands, so this guard counts it as a commit and a push: it cannot tell "
|
|
1039
|
+
"what an alias runs. If that is why it was denied, run the git command an "
|
|
1040
|
+
"alias stands for, or an external command by its own name (`git-lfs pull` "
|
|
1041
|
+
"for `git lfs pull`)."
|
|
1042
|
+
)
|
|
706
1043
|
|
|
707
1044
|
|
|
708
1045
|
# --- Marker freshness -------------------------------------------------------
|
|
@@ -2225,9 +2562,10 @@ def main() -> None:
|
|
|
2225
2562
|
if not isinstance(command, str):
|
|
2226
2563
|
_allow()
|
|
2227
2564
|
|
|
2228
|
-
verbs =
|
|
2565
|
+
verbs, unknown = _classify(command)
|
|
2229
2566
|
if not verbs:
|
|
2230
2567
|
_allow()
|
|
2568
|
+
hint = _unknown_hint(unknown)
|
|
2231
2569
|
|
|
2232
2570
|
protected = _protected_branches()
|
|
2233
2571
|
branch = _current_branch(cwd)
|
|
@@ -2237,7 +2575,8 @@ def main() -> None:
|
|
|
2237
2575
|
f"Protected-branch guard: refusing `git {'/'.join(sorted(verbs))}` "
|
|
2238
2576
|
f"on '{branch}'. UltraCode-Goal commits one green story per commit "
|
|
2239
2577
|
f"on an epic branch ('{os.environ.get('ULTRACODE_EPIC_BRANCH_PREFIX', 'ultracode/epic-')}<id>'), "
|
|
2240
|
-
f"never on {protected}. Switch to the epic branch first."
|
|
2578
|
+
f"never on {protected}. Switch to the epic branch first.",
|
|
2579
|
+
hint,
|
|
2241
2580
|
)
|
|
2242
2581
|
|
|
2243
2582
|
if "commit" in verbs:
|
|
@@ -2253,7 +2592,8 @@ def main() -> None:
|
|
|
2253
2592
|
"Tests-ran guard: refusing `git commit` — no tests-ran marker "
|
|
2254
2593
|
f"for the current story ({story or 'unknown'}). Run the story's "
|
|
2255
2594
|
f"test/lint/build to green and write {target} before committing. "
|
|
2256
|
-
"Commit only at a verified-green story boundary."
|
|
2595
|
+
"Commit only at a verified-green story boundary.",
|
|
2596
|
+
hint,
|
|
2257
2597
|
)
|
|
2258
2598
|
_marker_freshness_gate(marker, baseline)
|
|
2259
2599
|
if not _staged_index_nonempty(cwd):
|
|
@@ -2265,7 +2605,8 @@ def main() -> None:
|
|
|
2265
2605
|
"distinct tool call. `git commit -a` and commit-time pathspecs "
|
|
2266
2606
|
"are unsupported inside a story loop: the guard evaluates the "
|
|
2267
2607
|
"command string before it runs, so anything they would stage "
|
|
2268
|
-
"does not exist yet at that point."
|
|
2608
|
+
"does not exist yet at that point.",
|
|
2609
|
+
hint,
|
|
2269
2610
|
)
|
|
2270
2611
|
_unskip_gate(cwd, story)
|
|
2271
2612
|
|
|
@@ -119,19 +119,27 @@ def utc_now_iso() -> str:
|
|
|
119
119
|
_SCHEME_RE = re.compile(r"^[a-zA-Z][a-zA-Z0-9+.\-]*://")
|
|
120
120
|
|
|
121
121
|
|
|
122
|
-
def _git(cwd: Path, *args: str) -> tuple[int, str]:
|
|
123
|
-
"""Run git in cwd, returning (returncode, stdout
|
|
122
|
+
def _git(cwd: Path, *args: str, strip: bool = True, errors: str = "replace") -> tuple[int, str]:
|
|
123
|
+
"""Run git in cwd, returning (returncode, stdout). Never raises.
|
|
124
|
+
|
|
125
|
+
The output is stripped; with ``strip=False`` only its line ending goes, so
|
|
126
|
+
a leading space in a path it prints survives. It is read as UTF-8, as git
|
|
127
|
+
prints paths, not in the locale's encoding (a Windows code page would turn
|
|
128
|
+
`été` into another name); ``errors="surrogateescape"`` keeps the bytes of
|
|
129
|
+
a name that is not UTF-8, so it can be written back as git printed it.
|
|
130
|
+
"""
|
|
124
131
|
try:
|
|
125
132
|
proc = subprocess.run(
|
|
126
133
|
["git", *args],
|
|
127
134
|
cwd=str(cwd),
|
|
128
135
|
capture_output=True,
|
|
129
|
-
|
|
136
|
+
encoding="utf-8",
|
|
137
|
+
errors=errors,
|
|
130
138
|
check=False,
|
|
131
139
|
)
|
|
132
140
|
except (OSError, ValueError):
|
|
133
141
|
return 1, ""
|
|
134
|
-
return proc.returncode, proc.stdout.strip()
|
|
142
|
+
return proc.returncode, (proc.stdout.strip() if strip else proc.stdout.rstrip("\r\n"))
|
|
135
143
|
|
|
136
144
|
|
|
137
145
|
def normalize_remote(url: str) -> str:
|
|
@@ -399,28 +407,48 @@ def write_state(impl_artifacts: str | os.PathLike[str], state: dict) -> Path:
|
|
|
399
407
|
return path
|
|
400
408
|
|
|
401
409
|
|
|
402
|
-
# The line
|
|
403
|
-
#
|
|
404
|
-
#
|
|
405
|
-
#
|
|
406
|
-
#
|
|
407
|
-
#
|
|
408
|
-
|
|
410
|
+
# The latch's line in the repository's .git/info/exclude, which
|
|
411
|
+
# exclude_state() adds: the latch's file name with a `*`, so it matches the
|
|
412
|
+
# latch and the temporary file write_state() renames into it, anchored to the
|
|
413
|
+
# artifacts folder so no other file of that name is hidden. Neither then shows
|
|
414
|
+
# in `git status` on a tracked artifacts folder (where the latch would trip
|
|
415
|
+
# preflight's git_clean blocker on every run), and a `git add -A` never stages
|
|
416
|
+
# them (the latch committed, then a tracked deletion once unlatch removes it).
|
|
417
|
+
_STATE_EXCLUDE_NAME = ".mem-state*"
|
|
409
418
|
_STATE_EXCLUDE_COMMENT = "# UltraCode Goal run latch (mem_recall.py latch)"
|
|
419
|
+
# The unanchored line 3.0.0-rc.1 wrote under the same comment, which hid every
|
|
420
|
+
# `.mem-state*` file in the repository; exclude_state() replaces it.
|
|
421
|
+
_STATE_EXCLUDE_UNANCHORED = _STATE_EXCLUDE_NAME
|
|
422
|
+
# The characters an ignore pattern reads as a glob or an escape.
|
|
423
|
+
_IGNORE_SPECIAL = re.compile(r"([\\*?\[])")
|
|
424
|
+
|
|
425
|
+
|
|
426
|
+
def state_exclude_line(prefix: str) -> str:
|
|
427
|
+
"""The exclude line for a latch whose folder sits at ``prefix`` in the work tree.
|
|
428
|
+
|
|
429
|
+
``prefix`` is ``git rev-parse --show-prefix`` run in the artifacts folder:
|
|
430
|
+
its path from the work tree's top, with a trailing ``/``, or ``""`` at the
|
|
431
|
+
top itself. Glob characters in it are escaped, so a folder named
|
|
432
|
+
``art[1]`` matches only itself.
|
|
433
|
+
"""
|
|
434
|
+
return "/" + _IGNORE_SPECIAL.sub(r"\\\1", prefix) + _STATE_EXCLUDE_NAME
|
|
410
435
|
|
|
411
436
|
|
|
412
437
|
def exclude_state(impl_artifacts: str | os.PathLike[str]) -> list[str]:
|
|
413
438
|
"""Keep the latch out of git; return the notes to print (none when it is out).
|
|
414
439
|
|
|
415
|
-
Adds
|
|
440
|
+
Adds state_exclude_line() to the exclude file of the repository holding
|
|
416
441
|
``impl_artifacts`` (``git rev-parse --git-path info/exclude``, so a linked
|
|
417
|
-
worktree writes its main repository's file), once: a
|
|
418
|
-
is left alone
|
|
419
|
-
|
|
442
|
+
worktree writes its main repository's file), once: a line already there
|
|
443
|
+
is left alone, and the unanchored line 3.0.0-rc.1 wrote under the same
|
|
444
|
+
comment is removed. A folder git does not see (no repository, or outside
|
|
445
|
+
the work tree) needs nothing and gets nothing. Exclusion cannot hide a latch
|
|
420
446
|
git already tracks, as a run on an older release could commit it: that one
|
|
421
447
|
gets ``NOTE recall-latch-visible``, since untracking it is a change to the
|
|
422
|
-
repository for the person to make
|
|
423
|
-
|
|
448
|
+
repository for the person to make, from their own terminal once no run is
|
|
449
|
+
active (while a latch is present the guard denies a command that names it).
|
|
450
|
+
An exclude file that cannot be read or written gets the same note with its
|
|
451
|
+
error. Never raises.
|
|
424
452
|
"""
|
|
425
453
|
impl = Path(impl_artifacts)
|
|
426
454
|
code, inside = _git(impl, "rev-parse", "--is-inside-work-tree")
|
|
@@ -432,24 +460,43 @@ def exclude_state(impl_artifacts: str | os.PathLike[str]) -> list[str]:
|
|
|
432
460
|
if code == 0 and tracked:
|
|
433
461
|
notes.append(
|
|
434
462
|
f"{NOTE_RECALL_LATCH_VISIBLE}: git tracks the run latch {latch}, so it shows "
|
|
435
|
-
"as a change in every run; untrack it
|
|
436
|
-
f"`git rm --cached {latch}` and commit that"
|
|
463
|
+
"as a change in every run; once no run is active, untrack it from a "
|
|
464
|
+
f"terminal of your own with `git rm --cached {latch}` and commit that "
|
|
465
|
+
"(while a latch is present, the guard denies a command that names it)"
|
|
437
466
|
)
|
|
467
|
+
# Unstripped: a strip() would drop a leading space from the folder name.
|
|
468
|
+
# The folder's bytes as git printed them, even where they are not UTF-8.
|
|
469
|
+
code, prefix = _git(impl, "rev-parse", "--show-prefix", strip=False, errors="surrogateescape")
|
|
470
|
+
if code != 0:
|
|
471
|
+
return notes
|
|
472
|
+
line = state_exclude_line(prefix)
|
|
438
473
|
code, rel = _git(impl, "rev-parse", "--git-path", "info/exclude")
|
|
439
474
|
if code != 0 or not rel:
|
|
440
475
|
return notes
|
|
441
476
|
exclude = Path(rel) if os.path.isabs(rel) else impl / rel
|
|
442
477
|
try:
|
|
443
|
-
text = exclude.read_text(encoding="utf-8") if exclude.is_file() else ""
|
|
444
|
-
|
|
478
|
+
text = exclude.read_text(encoding="utf-8", errors="surrogateescape") if exclude.is_file() else ""
|
|
479
|
+
lines = text.splitlines()
|
|
480
|
+
kept: list[str] = []
|
|
481
|
+
for entry in lines:
|
|
482
|
+
if entry == _STATE_EXCLUDE_UNANCHORED and kept and kept[-1] == _STATE_EXCLUDE_COMMENT:
|
|
483
|
+
kept.pop() # 3.0.0-rc.1's line, and its comment
|
|
484
|
+
continue
|
|
485
|
+
kept.append(entry)
|
|
486
|
+
if kept != lines:
|
|
487
|
+
if line not in kept:
|
|
488
|
+
kept += [_STATE_EXCLUDE_COMMENT, line]
|
|
489
|
+
exclude.write_text("\n".join(kept) + "\n", encoding="utf-8", errors="surrogateescape")
|
|
490
|
+
return notes
|
|
491
|
+
if line in lines:
|
|
445
492
|
return notes
|
|
446
493
|
lead = "" if not text or text.endswith("\n") else "\n"
|
|
447
494
|
exclude.parent.mkdir(parents=True, exist_ok=True)
|
|
448
|
-
with open(exclude, "a", encoding="utf-8") as handle:
|
|
449
|
-
handle.write(f"{lead}{_STATE_EXCLUDE_COMMENT}\n{
|
|
495
|
+
with open(exclude, "a", encoding="utf-8", errors="surrogateescape") as handle:
|
|
496
|
+
handle.write(f"{lead}{_STATE_EXCLUDE_COMMENT}\n{line}\n")
|
|
450
497
|
except (OSError, ValueError) as exc: # ValueError: not UTF-8
|
|
451
498
|
notes.append(
|
|
452
|
-
f"{NOTE_RECALL_LATCH_VISIBLE}: could not add {
|
|
499
|
+
f"{NOTE_RECALL_LATCH_VISIBLE}: could not add {line} to "
|
|
453
500
|
f"{exclude} ({exc}), so git can see the run latch {latch}"
|
|
454
501
|
)
|
|
455
502
|
return notes
|
|
@@ -15,12 +15,19 @@ drive_epic's default mode would have it refused. This script runs under
|
|
|
15
15
|
|
|
16
16
|
Which folders. Every `node_modules` folder in the main tree, the root's and
|
|
17
17
|
the nested ones (a workspace package's), but never one inside another
|
|
18
|
-
`node_modules`: linking the outer one carries it. The walk
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
18
|
+
`node_modules`: linking the outer one carries it. The walk does not enter
|
|
19
|
+
`.git`, `__pycache__`, a repository or worktree nested in the tree (a folder
|
|
20
|
+
holding a `.git`: the gate worktrees under the implementation artifacts
|
|
21
|
+
folder, an agent worktree, a submodule, whose files the gate's worktree does
|
|
22
|
+
not check out), a Python virtual environment
|
|
23
|
+
(a folder holding `pyvenv.cfg`) or a cache folder (one holding `CACHEDIR.TAG`,
|
|
24
|
+
such as Cargo's `target`). None holds the project's own dependencies, and some
|
|
25
|
+
are large. A folder is judged by what it holds, not by its name, so a
|
|
26
|
+
workspace package named `target` or a JavaScript action under `.github/` is
|
|
27
|
+
still walked.
|
|
28
|
+
`--dir` names a folder to link instead, relative to the project root, for a
|
|
29
|
+
dependency folder of another name (`vendor`); repeat it for several. Given
|
|
30
|
+
any `--dir`, nothing is discovered.
|
|
24
31
|
|
|
25
32
|
How each link is made. A directory symlink to the main tree's folder, at the
|
|
26
33
|
same relative path in the worktree. On Windows, where a symlink needs a
|
|
@@ -48,26 +55,31 @@ import sys
|
|
|
48
55
|
from pathlib import Path
|
|
49
56
|
|
|
50
57
|
DEPENDENCY_DIR = "node_modules"
|
|
51
|
-
|
|
58
|
+
# Folders the walk never enters, by name.
|
|
59
|
+
_UNWALKED = frozenset({".git", "__pycache__"})
|
|
60
|
+
# A folder holding one of these is another repository or worktree (`.git`), a
|
|
61
|
+
# Python virtual environment, or a cache (the Cache Directory Tagging spec).
|
|
62
|
+
_UNWALKED_MARKERS = frozenset({".git", "pyvenv.cfg", "CACHEDIR.TAG"})
|
|
52
63
|
|
|
53
64
|
|
|
54
|
-
def discover(project_root: Path
|
|
55
|
-
"""Every `node_modules` folder under project_root, outermost only, sorted.
|
|
56
|
-
|
|
65
|
+
def discover(project_root: Path) -> list[str]:
|
|
66
|
+
"""Every `node_modules` folder under project_root, outermost only, sorted.
|
|
67
|
+
|
|
68
|
+
The gate's own worktree, like every git worktree, holds a `.git` file, so
|
|
69
|
+
the marker check skips it with the other nested trees.
|
|
70
|
+
"""
|
|
57
71
|
found: list[str] = []
|
|
58
|
-
for current, dirs,
|
|
72
|
+
for current, dirs, files in os.walk(project_root):
|
|
73
|
+
if current != str(project_root) and any(
|
|
74
|
+
marker in dirs or marker in files for marker in _UNWALKED_MARKERS
|
|
75
|
+
):
|
|
76
|
+
dirs[:] = [] # a nested repository or worktree, a virtual environment, a cache
|
|
77
|
+
continue
|
|
59
78
|
kept = []
|
|
60
79
|
for name in dirs:
|
|
61
|
-
full = os.path.join(current, name)
|
|
62
80
|
if name == DEPENDENCY_DIR:
|
|
63
|
-
found.append(Path(os.path.relpath(
|
|
64
|
-
elif
|
|
65
|
-
name == ".git"
|
|
66
|
-
or name.startswith(_GATE_WORKTREE_PREFIX)
|
|
67
|
-
or os.path.normcase(os.path.realpath(full)) == skip
|
|
68
|
-
):
|
|
69
|
-
continue
|
|
70
|
-
else:
|
|
81
|
+
found.append(Path(os.path.relpath(os.path.join(current, name), project_root)).as_posix())
|
|
82
|
+
elif name not in _UNWALKED:
|
|
71
83
|
kept.append(name)
|
|
72
84
|
dirs[:] = kept
|
|
73
85
|
return sorted(found)
|
|
@@ -152,7 +164,7 @@ def main(argv: list[str] | None = None) -> int:
|
|
|
152
164
|
return 2
|
|
153
165
|
rel_dirs.append(rel)
|
|
154
166
|
else:
|
|
155
|
-
rel_dirs = discover(project_root
|
|
167
|
+
rel_dirs = discover(project_root)
|
|
156
168
|
result = link_all(project_root, worktree, rel_dirs)
|
|
157
169
|
print(json.dumps(result, indent=2, ensure_ascii=False))
|
|
158
170
|
return 1 if result["failed"] else 0
|