polyctl 0.7.0__py3-none-any.whl
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.
- polyctl/__init__.py +7 -0
- polyctl/__main__.py +5 -0
- polyctl/a2a.py +226 -0
- polyctl/a2a_mcp.py +546 -0
- polyctl/acp.py +417 -0
- polyctl/adapters/README.md +101 -0
- polyctl/adapters/aider.json +32 -0
- polyctl/adapters/amazon-q.json +15 -0
- polyctl/adapters/amp.json +16 -0
- polyctl/adapters/antigravity.json +120 -0
- polyctl/adapters/claude-code.json +229 -0
- polyctl/adapters/cloud-generic.json +57 -0
- polyctl/adapters/codex.json +47 -0
- polyctl/adapters/command-code.json +45 -0
- polyctl/adapters/copilot.json +17 -0
- polyctl/adapters/cursor-agent.json +29 -0
- polyctl/adapters/deepseek.json +13 -0
- polyctl/adapters/droid.json +34 -0
- polyctl/adapters/gemini.json +30 -0
- polyctl/adapters/grok.json +22 -0
- polyctl/adapters/hermes.json +34 -0
- polyctl/adapters/kilocode.json +30 -0
- polyctl/adapters/kimi.json +23 -0
- polyctl/adapters/kiro.json +332 -0
- polyctl/adapters/ollama.json +29 -0
- polyctl/adapters/omp.json +34 -0
- polyctl/adapters/openai-api.json +68 -0
- polyctl/adapters/opencode.json +162 -0
- polyctl/adapters/pi.json +24 -0
- polyctl/adapters/pr-agent.json +54 -0
- polyctl/adapters/profiles.json +9 -0
- polyctl/adapters/qoder.json +163 -0
- polyctl/adapters/qwen.json +27 -0
- polyctl/adapters/reasonix.json +25 -0
- polyctl/adapters/rewriters/rtk.json +24 -0
- polyctl/adapters/trae.json +31 -0
- polyctl/adapters/vendors.json +42 -0
- polyctl/adapters/warp.json +88 -0
- polyctl/allowlist.py +1756 -0
- polyctl/api_review.py +920 -0
- polyctl/cli.py +835 -0
- polyctl/conformance_harness.py +9 -0
- polyctl/demo.py +503 -0
- polyctl/drivers.py +146 -0
- polyctl/email.py +160 -0
- polyctl/features.py +98 -0
- polyctl/journal.py +144 -0
- polyctl/language.py +945 -0
- polyctl/lib.py +1296 -0
- polyctl/matrix.py +660 -0
- polyctl/mcp.py +1362 -0
- polyctl/ntfy.py +169 -0
- polyctl/outbound.py +39 -0
- polyctl/parts/__init__.py +5 -0
- polyctl/parts/cli_authority.py +2615 -0
- polyctl/parts/cli_channels.py +1325 -0
- polyctl/parts/cli_checks.py +2293 -0
- polyctl/parts/cli_completion.py +686 -0
- polyctl/parts/cli_evidence.py +141 -0
- polyctl/parts/cli_gain.py +375 -0
- polyctl/parts/cli_harness.py +392 -0
- polyctl/parts/cli_hooks.py +1816 -0
- polyctl/parts/cli_install.py +638 -0
- polyctl/parts/cli_lanes.py +106 -0
- polyctl/parts/cli_maintenance.py +2536 -0
- polyctl/parts/cli_next.py +248 -0
- polyctl/parts/cli_pr.py +53 -0
- polyctl/parts/cli_project.py +2857 -0
- polyctl/parts/cli_review.py +5158 -0
- polyctl/parts/cli_status.py +898 -0
- polyctl/parts/lib_adapters.py +2933 -0
- polyctl/parts/lib_alarms.py +2106 -0
- polyctl/parts/lib_events.py +224 -0
- polyctl/parts/lib_evidence.py +412 -0
- polyctl/parts/lib_gates.py +2099 -0
- polyctl/parts/lib_lanes.py +829 -0
- polyctl/parts/lib_mail.py +1541 -0
- polyctl/parts/lib_next.py +652 -0
- polyctl/parts/lib_pr.py +331 -0
- polyctl/parts/lib_slices.py +3337 -0
- polyctl/parts/lib_state.py +2415 -0
- polyctl/parts/lib_transcript.py +4118 -0
- polyctl/pressure.py +325 -0
- polyctl/prices.json +47 -0
- polyctl/procs.py +1194 -0
- polyctl/settings.py +505 -0
- polyctl/skill/SKILL.md +365 -0
- polyctl/skillkit.py +503 -0
- polyctl/storage.py +2055 -0
- polyctl/telegram.py +327 -0
- polyctl/tiers.py +123 -0
- polyctl/verdicts.py +41 -0
- polyctl/watchdog.py +3887 -0
- polyctl/web.py +337 -0
- polyctl-0.7.0.dist-info/METADATA +235 -0
- polyctl-0.7.0.dist-info/RECORD +99 -0
- polyctl-0.7.0.dist-info/WHEEL +4 -0
- polyctl-0.7.0.dist-info/entry_points.txt +5 -0
- polyctl-0.7.0.dist-info/licenses/LICENSE +21 -0
|
@@ -0,0 +1,2099 @@
|
|
|
1
|
+
"""Measurement and gates: unfiltered git, size, gate coverage, review artefacts, merge checks.
|
|
2
|
+
|
|
3
|
+
A part of src/polyctl/lib.py (#44): moved out byte for byte and run in its namespace by `_part`,
|
|
4
|
+
where it stood; it is not importable on its own.
|
|
5
|
+
"""
|
|
6
|
+
|
|
7
|
+
|
|
8
|
+
# ---- polyctl's own measurements are not read through a filter (#51) ------------------------
|
|
9
|
+
|
|
10
|
+
# ELF, Mach-O (fat and thin, either byte order) and PE: a compiled program, not a script.
|
|
11
|
+
_NATIVE_MAGIC = (b"\x7fELF", b"\xca\xfe\xba\xbe", b"\xbe\xba\xfe\xca", b"\xcf\xfa\xed\xfe",
|
|
12
|
+
b"\xce\xfa\xed\xfe", b"\xfe\xed\xfa\xcf", b"\xfe\xed\xfa\xce", b"MZ")
|
|
13
|
+
# What polyctl treats as evidence; the doctor names them when something could filter them.
|
|
14
|
+
MEASUREMENTS = ("candidate size and paths", "git status", "rev-parse", "write-tree", "hash-object",
|
|
15
|
+
"gate output")
|
|
16
|
+
_REWRITING_HOOK = re.compile(r"\brtk\b|\bproxy\b|rewrit|compress|condens", re.I)
|
|
17
|
+
_GIT_BINARIES = {}
|
|
18
|
+
|
|
19
|
+
|
|
20
|
+
def _native_executable(path):
|
|
21
|
+
try:
|
|
22
|
+
with open(path, "rb") as fh:
|
|
23
|
+
head = fh.read(4)
|
|
24
|
+
except OSError:
|
|
25
|
+
return False
|
|
26
|
+
return any(head.startswith(magic) for magic in _NATIVE_MAGIC)
|
|
27
|
+
|
|
28
|
+
|
|
29
|
+
# The one git that is an xcrun stub: macOS's own. An xcrun beside any other compiled git was run once a process
|
|
30
|
+
# on every platform but Windows, a program polyctl had no reason to start (SUITE-SPEED-2).
|
|
31
|
+
_XCRUN_STUB = "/usr/bin/git"
|
|
32
|
+
|
|
33
|
+
|
|
34
|
+
def _xcrun_git(candidate):
|
|
35
|
+
"""The git an xcrun stub runs, or None when `candidate` is not such a stub.
|
|
36
|
+
|
|
37
|
+
/usr/bin/git on macOS is a compiled stub: on every call it asks xcrun for the
|
|
38
|
+
selected developer directory and runs the git there, which costs more than
|
|
39
|
+
git's own start, and a hook or a gate makes hundreds of git calls. The stub is
|
|
40
|
+
told from a real git by the xcrun beside it, and `xcrun --find git` names the
|
|
41
|
+
binary it would run. That answer is taken only when it is itself a compiled
|
|
42
|
+
git, so it can never put a script in front of git.
|
|
43
|
+
"""
|
|
44
|
+
stub = os.path.realpath(candidate)
|
|
45
|
+
if stub != _XCRUN_STUB:
|
|
46
|
+
return None
|
|
47
|
+
xcrun = os.path.join(os.path.dirname(stub), "xcrun")
|
|
48
|
+
if not (_native_executable(stub) and os.path.isfile(xcrun) and os.access(xcrun, os.X_OK)):
|
|
49
|
+
return None
|
|
50
|
+
import errno
|
|
51
|
+
result = None
|
|
52
|
+
for attempt in range(5):
|
|
53
|
+
try:
|
|
54
|
+
result = subprocess.run([xcrun, "--find", "git"], stdin=subprocess.DEVNULL, stdout=subprocess.PIPE,
|
|
55
|
+
stderr=subprocess.DEVNULL, timeout=60)
|
|
56
|
+
break
|
|
57
|
+
except subprocess.TimeoutExpired:
|
|
58
|
+
return None
|
|
59
|
+
except OSError as exc:
|
|
60
|
+
if attempt == 4 or exc.errno not in (errno.EAGAIN, errno.ENOMEM, getattr(errno, "ETXTBSY", None)):
|
|
61
|
+
return None
|
|
62
|
+
time.sleep(0.02)
|
|
63
|
+
found = result.stdout.decode(UTF8, "replace").strip()
|
|
64
|
+
if result.returncode == 0 and os.path.isabs(found) and os.path.basename(found) == "git" \
|
|
65
|
+
and os.path.isfile(found) and os.access(found, os.X_OK) \
|
|
66
|
+
and os.path.realpath(found) != stub and _native_executable(os.path.realpath(found)):
|
|
67
|
+
return found
|
|
68
|
+
return None
|
|
69
|
+
|
|
70
|
+
|
|
71
|
+
def _find_git_binary():
|
|
72
|
+
explicit = os.environ.get("POLYCTL_GIT")
|
|
73
|
+
if explicit and os.path.isfile(explicit) and os.access(explicit, os.X_OK):
|
|
74
|
+
return explicit
|
|
75
|
+
names = ("git.exe", "git") if os.name == "nt" else ("git",)
|
|
76
|
+
directories = search_directories()
|
|
77
|
+
installed = os.path.join(os.environ.get("ProgramFiles", r"C:\Program Files"), "Git", "cmd")
|
|
78
|
+
if os.name == "nt":
|
|
79
|
+
directories.append(installed)
|
|
80
|
+
else:
|
|
81
|
+
directories += ["/usr/bin", "/bin", "/usr/local/bin", "/opt/homebrew/bin"]
|
|
82
|
+
for directory in directories:
|
|
83
|
+
for name in names:
|
|
84
|
+
candidate = os.path.join(directory, name)
|
|
85
|
+
if os.path.isfile(candidate) and os.access(candidate, os.X_OK) \
|
|
86
|
+
and _native_executable(os.path.realpath(candidate)):
|
|
87
|
+
return _xcrun_git(candidate) or candidate
|
|
88
|
+
# With no compiled git, the git PATH holds, of whatever kind. Never the bare name: Windows looks for it in the
|
|
89
|
+
# current directory first, and POSIX's execvp through every PATH entry, an empty one - the current directory -
|
|
90
|
+
# among them. The last resort is where git is installed, which fails to start rather than start a git an agent
|
|
91
|
+
# left in the tree (WINDOWS-NO-CWD-EXEC, and its review for POSIX).
|
|
92
|
+
return program_path("git") or (os.path.join(installed, "git.exe") if os.name == "nt" else "/usr/bin/git")
|
|
93
|
+
|
|
94
|
+
|
|
95
|
+
def git_binary():
|
|
96
|
+
"""The git polyctl measures with (#51).
|
|
97
|
+
|
|
98
|
+
A token-saving proxy in an agent's shell reported a 5,844-line staged diff as
|
|
99
|
+
533 lines, and the number nearly sized a decision. polyctl reads its measurements
|
|
100
|
+
itself, never from an agent's terminal, and it does not take a wrapper for git
|
|
101
|
+
either: POLYCTL_GIT when that names an executable, otherwise the first git on PATH,
|
|
102
|
+
then in the system directories, that is a compiled program rather than a
|
|
103
|
+
script in front of one; the first git PATH holds of any kind only when there
|
|
104
|
+
is none, and where git is installed when PATH holds none either - never the
|
|
105
|
+
bare name, which Windows looks for in the current directory first and POSIX
|
|
106
|
+
through an empty PATH entry (WINDOWS-NO-CWD-EXEC).
|
|
107
|
+
When that git is macOS's xcrun stub, the git xcrun names instead, asked once
|
|
108
|
+
per process.
|
|
109
|
+
"""
|
|
110
|
+
key = (os.environ.get("POLYCTL_GIT"), os.environ.get("PATH", ""), os.name, os.environ.get("DEVELOPER_DIR"), _XCRUN_STUB)
|
|
111
|
+
found = _GIT_BINARIES.get(key)
|
|
112
|
+
if found is None or (found != "git" and not os.path.isfile(found)):
|
|
113
|
+
found = _GIT_BINARIES[key] = _find_git_binary()
|
|
114
|
+
return found
|
|
115
|
+
|
|
116
|
+
|
|
117
|
+
def measured_by():
|
|
118
|
+
"""How the measurements in a record were taken: which git, no shell, read by polyctl (#51)."""
|
|
119
|
+
return {"git": git_binary(), "candidate_via_shell": False, "captured_by": "polyctl"}
|
|
120
|
+
|
|
121
|
+
|
|
122
|
+
def command_hook_sources(root):
|
|
123
|
+
"""(settings file, the adapter's declaration, whether the file is user-level) for each hook file (#76, #52).
|
|
124
|
+
|
|
125
|
+
A user-level file is one an adapter names under `~`, outside every repository. The
|
|
126
|
+
project's own files are writable by the agents polyctl governs, so the filter probe runs
|
|
127
|
+
no command they name.
|
|
128
|
+
"""
|
|
129
|
+
out, seen = [], set()
|
|
130
|
+
for adapter in package_adapters().values():
|
|
131
|
+
hooks = (adapter.get("directives") or {}).get("command_hooks") or {}
|
|
132
|
+
if hooks.get("format") != "pre-tool-use":
|
|
133
|
+
continue
|
|
134
|
+
for rel in hooks.get("files") or []:
|
|
135
|
+
user = str(rel).startswith("~")
|
|
136
|
+
path = _home_path(rel) if user else os.path.join(root, *str(rel).split("/"))
|
|
137
|
+
if path not in seen:
|
|
138
|
+
seen.add(path)
|
|
139
|
+
out.append((path, hooks, user))
|
|
140
|
+
return out
|
|
141
|
+
|
|
142
|
+
|
|
143
|
+
def command_hook_files(root):
|
|
144
|
+
"""Settings files whose pre-tool-use hooks can rewrite an agent's shell commands, as adapters declare them (#76)."""
|
|
145
|
+
return [path for path, _, _ in command_hook_sources(root)]
|
|
146
|
+
|
|
147
|
+
|
|
148
|
+
def _matcher_matches(matcher, tool):
|
|
149
|
+
"""A hook matcher read as the harness reads it: empty or `*` is every tool, plain words exact names, else a regex."""
|
|
150
|
+
text = "" if matcher is None else str(matcher)
|
|
151
|
+
if text in ("", "*"):
|
|
152
|
+
return True
|
|
153
|
+
if re.fullmatch(r"[A-Za-z0-9_\- ,|]+", text):
|
|
154
|
+
return tool in {name.strip() for name in re.split(r"[|,]", text)}
|
|
155
|
+
try:
|
|
156
|
+
return re.search(text, tool) is not None
|
|
157
|
+
except re.error:
|
|
158
|
+
return True # a matcher polyctl cannot read is counted, not passed over
|
|
159
|
+
|
|
160
|
+
|
|
161
|
+
def _shell_hooks(path, declaration):
|
|
162
|
+
"""The command hooks a settings file runs before the harness's shell tool, in the order it declares them."""
|
|
163
|
+
try:
|
|
164
|
+
with open(path, encoding=UTF8) as fh:
|
|
165
|
+
hooks = json.load(fh).get("hooks")
|
|
166
|
+
except (OSError, ValueError, AttributeError):
|
|
167
|
+
return []
|
|
168
|
+
tool = str(declaration.get("shell_tool") or "Bash")
|
|
169
|
+
entries = hooks.get("PreToolUse") if isinstance(hooks, dict) else None
|
|
170
|
+
return [hook for entry in (entries if isinstance(entries, list) else [])
|
|
171
|
+
if isinstance(entry, dict) and _matcher_matches(entry.get("matcher"), tool)
|
|
172
|
+
for hook in (entry.get("hooks") if isinstance(entry.get("hooks"), list) else [])
|
|
173
|
+
if isinstance(hook, dict) and hook.get("type", "command") == "command"]
|
|
174
|
+
|
|
175
|
+
|
|
176
|
+
def _hook_text(hook):
|
|
177
|
+
"""A command hook as one line: its command, and its arguments when it declares them apart."""
|
|
178
|
+
args = hook.get("args") if isinstance(hook.get("args"), list) else []
|
|
179
|
+
return " ".join(word for word in [str(hook.get("command") or ""), *map(str, args)] if word)
|
|
180
|
+
|
|
181
|
+
|
|
182
|
+
def measurement_filters(root):
|
|
183
|
+
"""What could stand between a number and its source, one sentence each (#51).
|
|
184
|
+
|
|
185
|
+
A script named git ahead of any compiled git on PATH, POLYCTL_GIT naming no compiled
|
|
186
|
+
executable, and shell PreToolUse hooks. Unknown hooks are unverified: a command
|
|
187
|
+
without the recognised keywords used to disappear here (TRIAGE-2-LOW).
|
|
188
|
+
`probe_filters` asks eligible hooks what they do (#52).
|
|
189
|
+
"""
|
|
190
|
+
found = []
|
|
191
|
+
explicit = os.environ.get("POLYCTL_GIT")
|
|
192
|
+
if explicit and not (os.path.isfile(explicit) and os.access(explicit, os.X_OK)):
|
|
193
|
+
found.append(f"POLYCTL_GIT names {explicit}, which is not an executable file; polyctl measures with {git_binary()}")
|
|
194
|
+
elif explicit and not _native_executable(os.path.realpath(explicit)):
|
|
195
|
+
found.append(f"POLYCTL_GIT names {explicit}, which is not a compiled program; polyctl measures through it: "
|
|
196
|
+
"set POLYCTL_GIT to a compiled git for unfiltered measurements")
|
|
197
|
+
first = program_path("git")
|
|
198
|
+
if first and not _native_executable(os.path.realpath(first)):
|
|
199
|
+
chosen = git_binary()
|
|
200
|
+
found.append(f"git on PATH is {first}, a script in front of git; " + (
|
|
201
|
+
f"polyctl measures with {chosen}" if _native_executable(os.path.realpath(chosen)) else
|
|
202
|
+
"no compiled git was found, so polyctl's own measurements go through it too: set POLYCTL_GIT"))
|
|
203
|
+
for path, declaration, _ in command_hook_sources(root):
|
|
204
|
+
for hook in _shell_hooks(path, declaration):
|
|
205
|
+
command = _hook_text(hook)
|
|
206
|
+
if _REWRITING_HOOK.search(command):
|
|
207
|
+
found.append(f"{path}: the PreToolUse hook `{command}` can rewrite the shell commands an "
|
|
208
|
+
f"agent runs, so what an agent reads of {', '.join(MEASUREMENTS)} may be "
|
|
209
|
+
"compressed; take such numbers from polyctl's records, which do not pass through it")
|
|
210
|
+
else:
|
|
211
|
+
found.append(f"{path}: the PreToolUse shell hook `{command}` is unverified; inspect it before "
|
|
212
|
+
"trusting measurements read through the agent's shell")
|
|
213
|
+
return found
|
|
214
|
+
|
|
215
|
+
|
|
216
|
+
# ---- a filter's exclusions are proved by asking it, not read from its configuration (#52) --
|
|
217
|
+
|
|
218
|
+
# The shell commands through which an agent reads a measurement - candidate size and paths, git
|
|
219
|
+
# status, history, rev-parse, write-tree, hash-object and polyctl's own records - that a filter's
|
|
220
|
+
# exclusion list must leave alone. `measurement_commands` adds the project's gate commands.
|
|
221
|
+
MEASUREMENT_COMMANDS = ("git diff", "git diff --cached", "git diff --stat", "git diff --numstat",
|
|
222
|
+
"git diff --cached --numstat", "git diff --name-only", "git status",
|
|
223
|
+
"git status --porcelain", "git log", "git log --oneline", "git show --stat",
|
|
224
|
+
"git rev-parse HEAD", "git write-tree", "git hash-object --stdin",
|
|
225
|
+
"polyctl status", "polyctl verify", "polyctl review", "polyctl board")
|
|
226
|
+
# All a probed hook sees of polyctl's environment: where programs, its home and its own configuration
|
|
227
|
+
# are. No credential, no GIT_* binding, no loader or interpreter start-up variable.
|
|
228
|
+
_PROBE_ENVIRONMENT = ("PATH", "HOME", "USER", "LOGNAME", "USERNAME", "USERPROFILE", "APPDATA", "LOCALAPPDATA",
|
|
229
|
+
"XDG_CONFIG_HOME", "XDG_DATA_HOME", "TMPDIR", "TMP", "TEMP", "LANG", "LC_ALL",
|
|
230
|
+
"SYSTEMROOT", "WINDIR", "PATHEXT")
|
|
231
|
+
_PROBE_OUTPUT_BYTES = 65_536
|
|
232
|
+
_PROBE_GATE_COMMANDS = 12
|
|
233
|
+
# What makes a command more than words to split: expansion, substitution, redirection, globs,
|
|
234
|
+
# chaining and escapes. Such a command needs a shell, and the probe runs none.
|
|
235
|
+
_SHELL_SYNTAX = re.compile(r"[$`|&;<>(){}\[\]*?!#\\\r\n]")
|
|
236
|
+
|
|
237
|
+
|
|
238
|
+
def measurement_commands(root):
|
|
239
|
+
"""The commands the filter probe asks a hook about: MEASUREMENT_COMMANDS, then the project's gates (#52).
|
|
240
|
+
|
|
241
|
+
The gate commands are what an agent runs to read a count. They come from a file the
|
|
242
|
+
agents can write, so they are taken as data only - the payload a hook reads - and
|
|
243
|
+
at most _PROBE_GATE_COMMANDS of them.
|
|
244
|
+
"""
|
|
245
|
+
commands = list(MEASUREMENT_COMMANDS)
|
|
246
|
+
try:
|
|
247
|
+
with open(os.path.join(root, ".polyctl", "gates.json"), encoding=UTF8) as fh:
|
|
248
|
+
gates = json.load(fh).get("gates")
|
|
249
|
+
except (OSError, ValueError, AttributeError):
|
|
250
|
+
gates = None
|
|
251
|
+
for gate in (gates.values() if isinstance(gates, dict) else []):
|
|
252
|
+
run = gate.get("run").strip() if isinstance(gate, dict) and isinstance(gate.get("run"), str) else ""
|
|
253
|
+
if run and len(run) <= 1000 and run not in commands:
|
|
254
|
+
commands.append(run)
|
|
255
|
+
if len(commands) >= len(MEASUREMENT_COMMANDS) + _PROBE_GATE_COMMANDS:
|
|
256
|
+
break
|
|
257
|
+
return commands
|
|
258
|
+
|
|
259
|
+
|
|
260
|
+
def _within(path, root):
|
|
261
|
+
"""Whether a path, followed through its links, lies inside root."""
|
|
262
|
+
real, top = (os.path.normcase(os.path.realpath(p)) for p in (path, root))
|
|
263
|
+
try:
|
|
264
|
+
return os.path.commonpath([real, top]) == top
|
|
265
|
+
except ValueError:
|
|
266
|
+
return False # another drive
|
|
267
|
+
|
|
268
|
+
|
|
269
|
+
def _hook_argv(hook):
|
|
270
|
+
"""The argument vector a command hook runs as without a shell, or (None, why only a shell could run it)."""
|
|
271
|
+
import shlex
|
|
272
|
+
command = hook.get("command")
|
|
273
|
+
if not isinstance(command, str) or not command.strip():
|
|
274
|
+
return None, "it names no command"
|
|
275
|
+
if "args" in hook:
|
|
276
|
+
# Exec form: the harness runs `command` with `args`, no shell, placeholders filled in.
|
|
277
|
+
args = hook["args"]
|
|
278
|
+
if not isinstance(args, list) or not all(isinstance(arg, str) for arg in args):
|
|
279
|
+
return None, "its args are not a list of strings"
|
|
280
|
+
if any("${" in word for word in [command, *args]):
|
|
281
|
+
return None, "it names a placeholder only the harness fills in"
|
|
282
|
+
return [command, *args], None
|
|
283
|
+
if str(hook.get("shell") or "bash").lower() not in ("bash", "sh"):
|
|
284
|
+
return None, f"it runs under {hook['shell']}, which polyctl does not imitate"
|
|
285
|
+
words = None
|
|
286
|
+
if not _SHELL_SYNTAX.search(command):
|
|
287
|
+
try:
|
|
288
|
+
words = shlex.split(command)
|
|
289
|
+
except ValueError:
|
|
290
|
+
words = None
|
|
291
|
+
if not words or "=" in words[0] or any("~" in word and word != "~" and not word.startswith("~/")
|
|
292
|
+
for word in words):
|
|
293
|
+
return None, "it needs a shell to run, and polyctl runs none; declare it as command and args"
|
|
294
|
+
return [_home_path(word) for word in words], None
|
|
295
|
+
|
|
296
|
+
|
|
297
|
+
# A word that names a file whether or not it is there yet: a separator in it, or a name with an extension
|
|
298
|
+
# (FILTER-EXCLUSIONS-2). A decimal or a version - 1.5, v2 - is no file name.
|
|
299
|
+
_PATH_WORD = re.compile(r"[/\\]")
|
|
300
|
+
_FILE_WORD = re.compile(r"[\w.-]*\.[A-Za-z]\w*")
|
|
301
|
+
# An address on another host names no file here; a file: URL names the path after it.
|
|
302
|
+
_URL_WORD = re.compile(r"[A-Za-z][A-Za-z0-9+.-]*://")
|
|
303
|
+
# A file address with no authority, `file:/C:/x` or `file:x`, which Node and Rust read as a path (FILTER-EXCLUSIONS-5).
|
|
304
|
+
_FILE_URL_BARE = re.compile(r"file:(?!//)", re.I)
|
|
305
|
+
# What a URL reader drops before it reads the scheme, as the WHATWG URL standard says and Node, Rust's url and
|
|
306
|
+
# Python's urlsplit do: C0 controls and spaces at either end, and a tab, CR or LF anywhere (FILTER-EXCLUSIONS-8).
|
|
307
|
+
_URL_READER_DROPS = re.compile(r"\A[\x00-\x20]+|[\x00-\x20]+\Z|[\t\r\n]")
|
|
308
|
+
|
|
309
|
+
|
|
310
|
+
def _probe_program(argv, root, programs, search_path):
|
|
311
|
+
"""The argv polyctl may run for a user-level hook, its program resolved, or (None, the rule it fails) (#52).
|
|
312
|
+
|
|
313
|
+
A filter is itself a program that runs commands, so the rule is about who chose the
|
|
314
|
+
words as much as which program they name: the program must be one the machine
|
|
315
|
+
allows, found where the agents' PATH finds it, outside the project, and no argument
|
|
316
|
+
may name a path the agents can write.
|
|
317
|
+
"""
|
|
318
|
+
name = _program_name(argv[0])
|
|
319
|
+
if name not in programs:
|
|
320
|
+
return None, f"{name} is not in filters.probe_programs, the programs polyctl may run to ask"
|
|
321
|
+
if os.path.isabs(argv[0]):
|
|
322
|
+
found = argv[0] if os.path.isfile(argv[0]) and os.access(argv[0], os.X_OK) else None
|
|
323
|
+
elif "/" in argv[0] or os.sep in argv[0]:
|
|
324
|
+
return None, f"its program {argv[0]} is named relative to the directory it runs in, the project"
|
|
325
|
+
else:
|
|
326
|
+
found = program_path(argv[0], path=search_path)
|
|
327
|
+
if not found:
|
|
328
|
+
return None, f"{argv[0]} is not an executable on the agents' PATH"
|
|
329
|
+
if os.path.splitext(found)[1].lower() in (".bat", ".cmd"):
|
|
330
|
+
return None, f"{found} is a batch file, which only a shell runs"
|
|
331
|
+
for word in [found, *argv[1:]]:
|
|
332
|
+
for piece in {word, word.split("=", 1)[-1]}:
|
|
333
|
+
# `<TAB>file:///repo/.polyctl/filter.toml#/../..` is the project's file to a URL reader, and to polyctl it was a
|
|
334
|
+
# relative path climbing out of the project (FILTER-EXCLUSIONS-8).
|
|
335
|
+
read = _URL_READER_DROPS.sub("", piece)
|
|
336
|
+
if read != piece and (_URL_WORD.match(read) or _FILE_URL_BARE.match(read)):
|
|
337
|
+
return None, (f"{word!r} is an address once a URL reader drops its spaces and control characters, "
|
|
338
|
+
"and a path to a program that keeps them, which programs read differently")
|
|
339
|
+
url = _URL_WORD.match(piece) or _FILE_URL_BARE.match(piece)
|
|
340
|
+
if url and piece[:url.end()].lower() not in ("file://", "file:"):
|
|
341
|
+
continue
|
|
342
|
+
if url:
|
|
343
|
+
# The path a file address names, as a program opening it reads it: percent-decoded, and on
|
|
344
|
+
# Windows `/C:/x` as `C:\x`; the text after the scheme alone let an encoded project path pass
|
|
345
|
+
# (FILTER-EXCLUSIONS-3).
|
|
346
|
+
from urllib.request import url2pathname
|
|
347
|
+
address = piece[url.end():]
|
|
348
|
+
# A program reading the address as a URL - Node's fileURLToPath, Rust's url, url2pathname from
|
|
349
|
+
# Python 3.14 - drops a query and a fragment, reads a `\` as `/` and drops a tab, CR or LF; one
|
|
350
|
+
# decoding the text after the scheme, as url2pathname did before 3.14, keeps them as path, `?/../..`
|
|
351
|
+
# and all. polyctl cannot tell which reads it, and judged whichever its own Python is (FILTER-EXCLUSIONS-6).
|
|
352
|
+
# `file:x/y` names no root: a URL reader takes it from the root, and polyctl took it under the project
|
|
353
|
+
# (FILTER-EXCLUSIONS-7).
|
|
354
|
+
bare = piece[:url.end()].lower() == "file:"
|
|
355
|
+
if bare and not address.startswith("/") \
|
|
356
|
+
or any(mark in address for mark in ("?", "#", "\\", "\t", "\r", "\n")):
|
|
357
|
+
return None, (f"{word!r} is a file address with no root, or holding a query or fragment, a "
|
|
358
|
+
"backslash or a control character, which programs read differently")
|
|
359
|
+
if address[:10].lower() == "localhost/":
|
|
360
|
+
address = address[9:] # this machine, as a program reads it: no directory of the path
|
|
361
|
+
try:
|
|
362
|
+
piece = url2pathname(address)
|
|
363
|
+
except (OSError, ValueError):
|
|
364
|
+
return None, f"{word} is a file address polyctl cannot read as a path"
|
|
365
|
+
# url2pathname looks for a drive before it decodes: `/C%3A/x` is `\C:\x` to it and C:\x to Node's
|
|
366
|
+
# fileURLToPath and Rust's url, which decode first. A NUL ends the path a C program opens short of
|
|
367
|
+
# the one polyctl would judge (FILTER-EXCLUSIONS-4).
|
|
368
|
+
if os.name == "nt" and re.match(r"[\\/][A-Za-z]:", piece):
|
|
369
|
+
piece = piece[1:]
|
|
370
|
+
if "\0" in piece:
|
|
371
|
+
return None, f"{word} is a file address polyctl cannot read as a path"
|
|
372
|
+
candidate = piece if os.path.isabs(piece) else os.path.join(root, piece)
|
|
373
|
+
# A path inside the project counts whether or not it exists yet: an agent could write it between this
|
|
374
|
+
# check and the hook's run, once per command measured, and remove it again (FILTER-EXCLUSIONS-2). An
|
|
375
|
+
# option is read by its program, not opened: its value after `=` is the piece that can name a file.
|
|
376
|
+
looks = not piece.startswith("-") and bool(_PATH_WORD.search(piece) or _FILE_WORD.fullmatch(piece))
|
|
377
|
+
named = os.path.isabs(piece) or os.path.lexists(candidate) or looks
|
|
378
|
+
if not (piece and named):
|
|
379
|
+
continue
|
|
380
|
+
# A path that cannot be followed to an absolute one is not known to lie outside: Windows' realpath of
|
|
381
|
+
# `f::$DATA`, the stream of a file not yet written, came back relative to the drive (FILTER-EXCLUSIONS-5).
|
|
382
|
+
try:
|
|
383
|
+
followed = os.path.realpath(candidate)
|
|
384
|
+
except (OSError, ValueError):
|
|
385
|
+
followed = None
|
|
386
|
+
if not followed or not os.path.isabs(followed):
|
|
387
|
+
return None, f"{piece} names a path polyctl cannot follow to where it lies"
|
|
388
|
+
if _within(candidate, root):
|
|
389
|
+
return None, f"{piece} lies inside the project, where the agents polyctl governs can write"
|
|
390
|
+
return [found, *argv[1:]], None
|
|
391
|
+
|
|
392
|
+
|
|
393
|
+
def _probe_environment(root, declaration, search_path):
|
|
394
|
+
"""What a probed hook is given: _PROBE_ENVIRONMENT, the agents' PATH and the project directory variable."""
|
|
395
|
+
env = {name: os.environ[name] for name in _PROBE_ENVIRONMENT if os.environ.get(name)}
|
|
396
|
+
env["PATH"] = search_path
|
|
397
|
+
variable = declaration.get("project_dir_env")
|
|
398
|
+
if isinstance(variable, str) and re.fullmatch(r"[A-Za-z_][A-Za-z0-9_]*", variable):
|
|
399
|
+
env[variable] = root
|
|
400
|
+
return env
|
|
401
|
+
|
|
402
|
+
|
|
403
|
+
def _run_hook(argv, payload, cwd, env, timeout):
|
|
404
|
+
"""Run one hook with one payload as the harness would, inside a time and an output bound (#52).
|
|
405
|
+
|
|
406
|
+
Returns (exit code, stdout, stderr, None), or (None, b"", b"", what cut it off). The hook
|
|
407
|
+
leads its own process group, so a timeout ends whatever it started; a child still
|
|
408
|
+
holding its output open is still answering.
|
|
409
|
+
"""
|
|
410
|
+
import signal
|
|
411
|
+
import threading
|
|
412
|
+
group = ({"creationflags": getattr(subprocess, "CREATE_NEW_PROCESS_GROUP", 0)} if os.name == "nt"
|
|
413
|
+
else {"start_new_session": True})
|
|
414
|
+
try:
|
|
415
|
+
proc = subprocess.Popen(argv, cwd=cwd, env=env, stdin=subprocess.PIPE, stdout=subprocess.PIPE,
|
|
416
|
+
stderr=subprocess.PIPE, **group)
|
|
417
|
+
except OSError as exc:
|
|
418
|
+
return None, b"", b"", f"it could not be started ({exc.strerror or exc})"
|
|
419
|
+
output, flooded = {"out": bytearray(), "err": bytearray()}, threading.Event()
|
|
420
|
+
|
|
421
|
+
def feed():
|
|
422
|
+
try:
|
|
423
|
+
proc.stdin.write(payload)
|
|
424
|
+
except OSError:
|
|
425
|
+
pass # a hook may exit without reading what it was given
|
|
426
|
+
try:
|
|
427
|
+
proc.stdin.close()
|
|
428
|
+
except OSError:
|
|
429
|
+
pass
|
|
430
|
+
|
|
431
|
+
def drain(stream, into):
|
|
432
|
+
try:
|
|
433
|
+
for block in iter(lambda: stream.read1(65536), b""):
|
|
434
|
+
into.extend(block)
|
|
435
|
+
if len(into) > _PROBE_OUTPUT_BYTES:
|
|
436
|
+
flooded.set()
|
|
437
|
+
return
|
|
438
|
+
except (OSError, ValueError):
|
|
439
|
+
pass
|
|
440
|
+
|
|
441
|
+
readers = [threading.Thread(target=drain, args=(proc.stdout, output["out"]), daemon=True),
|
|
442
|
+
threading.Thread(target=drain, args=(proc.stderr, output["err"]), daemon=True)]
|
|
443
|
+
for thread in [threading.Thread(target=feed, daemon=True), *readers]:
|
|
444
|
+
thread.start()
|
|
445
|
+
deadline, cut = time.monotonic() + timeout, None
|
|
446
|
+
while cut is None and (proc.poll() is None or any(reader.is_alive() for reader in readers)):
|
|
447
|
+
if flooded.is_set():
|
|
448
|
+
cut = f"it wrote more than {_PROBE_OUTPUT_BYTES} bytes"
|
|
449
|
+
elif time.monotonic() >= deadline:
|
|
450
|
+
cut = f"it did not answer within {timeout}s"
|
|
451
|
+
else:
|
|
452
|
+
time.sleep(0.01)
|
|
453
|
+
if cut is None and flooded.is_set():
|
|
454
|
+
cut = f"it wrote more than {_PROBE_OUTPUT_BYTES} bytes"
|
|
455
|
+
if cut and (proc.poll() is None or any(reader.is_alive() for reader in readers)):
|
|
456
|
+
if os.name == "nt":
|
|
457
|
+
left = stop_windows_tree(proc.pid)
|
|
458
|
+
if left:
|
|
459
|
+
# What taskkill left of it is named, not taken as stopped (WINDOWS-STOP-PROVEN).
|
|
460
|
+
cut += f" - and {len(left)} process(es) of it still run after it was stopped, {left} -"
|
|
461
|
+
else:
|
|
462
|
+
try:
|
|
463
|
+
os.killpg(proc.pid, signal.SIGKILL)
|
|
464
|
+
except OSError:
|
|
465
|
+
pass
|
|
466
|
+
try:
|
|
467
|
+
proc.kill()
|
|
468
|
+
except OSError:
|
|
469
|
+
pass
|
|
470
|
+
try:
|
|
471
|
+
proc.wait(timeout=5)
|
|
472
|
+
except subprocess.TimeoutExpired:
|
|
473
|
+
pass
|
|
474
|
+
for reader in readers:
|
|
475
|
+
reader.join(1)
|
|
476
|
+
if not any(reader.is_alive() for reader in readers):
|
|
477
|
+
for stream in (proc.stdout, proc.stderr):
|
|
478
|
+
stream.close()
|
|
479
|
+
if cut:
|
|
480
|
+
return None, b"", b"", cut
|
|
481
|
+
return proc.returncode, bytes(output["out"]), bytes(output["err"]), None
|
|
482
|
+
|
|
483
|
+
|
|
484
|
+
def _hook_answer(command, code, out, err):
|
|
485
|
+
"""What a pre-tool-use hook's answer does to one command, read as the harness reads it (#52).
|
|
486
|
+
|
|
487
|
+
(None, None) passes it through unchanged. ("rewrites", the new command or None) and
|
|
488
|
+
("blocks", how) change what an agent reads; ("unreadable", why) is an answer polyctl can
|
|
489
|
+
vouch for neither way. A rewrite counts whether or not the answer also allows the
|
|
490
|
+
command: harness versions have differed on applying a rewrite that carries no decision,
|
|
491
|
+
and keeping measurements out of the filter is its exclusion list's job, not theirs.
|
|
492
|
+
"""
|
|
493
|
+
if code == 2:
|
|
494
|
+
lines = err.decode(UTF8, "replace").strip().splitlines()
|
|
495
|
+
return "blocks", "is blocked" + (f" ({lines[0][:160]})" if lines else "")
|
|
496
|
+
text = out.decode(UTF8, "replace").strip()
|
|
497
|
+
answer = None
|
|
498
|
+
if text.startswith("{") and text.endswith("}"):
|
|
499
|
+
try:
|
|
500
|
+
answer = json.loads(text)
|
|
501
|
+
except ValueError:
|
|
502
|
+
return "unreadable", "its answer is not JSON"
|
|
503
|
+
if isinstance(answer, dict):
|
|
504
|
+
specific = answer.get("hookSpecificOutput") if isinstance(answer.get("hookSpecificOutput"), dict) else {}
|
|
505
|
+
decision = specific.get("permissionDecision")
|
|
506
|
+
reason = str(specific.get("permissionDecisionReason") or answer.get("reason")
|
|
507
|
+
or answer.get("stopReason") or "")[:160]
|
|
508
|
+
why = f" ({reason})" if reason else ""
|
|
509
|
+
if answer.get("continue") is False:
|
|
510
|
+
return "blocks", "stops the agent before it runs" + why
|
|
511
|
+
if decision == "deny" or answer.get("decision") == "block":
|
|
512
|
+
return "blocks", "is blocked" + why
|
|
513
|
+
if "updatedInput" in specific:
|
|
514
|
+
updated = specific["updatedInput"]
|
|
515
|
+
rewritten = updated.get("command") if isinstance(updated, dict) else None
|
|
516
|
+
if rewritten != command:
|
|
517
|
+
return "rewrites", rewritten if isinstance(rewritten, str) else None
|
|
518
|
+
if decision == "ask":
|
|
519
|
+
return "blocks", "is held for a person's approval" + why
|
|
520
|
+
if code != 0:
|
|
521
|
+
return "unreadable", f"it exited {code}"
|
|
522
|
+
return None, None
|
|
523
|
+
|
|
524
|
+
|
|
525
|
+
def probe_filters(root):
|
|
526
|
+
"""Ask each hook that could filter an agent's shell what it does to every measurement command (#52).
|
|
527
|
+
|
|
528
|
+
#51 names such a hook by its command. #52 installs one on purpose, with an exclusion
|
|
529
|
+
list covering every measurement path, and asks the doctor to prove the list is in
|
|
530
|
+
force rather than trust it: a release of one such filter kept rewriting what its
|
|
531
|
+
exclusion list named, the list being read on only one of its two rewrite paths. So
|
|
532
|
+
each hook is run as the harness runs it, once per command in `measurement_commands`,
|
|
533
|
+
with the payload the harness sends, and its answer is read as the harness reads it.
|
|
534
|
+
The command it answers with is never run.
|
|
535
|
+
|
|
536
|
+
`polyctl doctor --check` runs unattended, and a settings file the agents can write would
|
|
537
|
+
make this a way to run anything. A hook is run only when it is declared in a
|
|
538
|
+
user-level file outside the project and `_probe_program` allows its program; then
|
|
539
|
+
without a shell, in the project directory as the harness runs it, with
|
|
540
|
+
`_probe_environment`, `filters.probe_timeout_seconds` for each answer and bounded
|
|
541
|
+
output. Any other hook that could filter is reported unverified, with the rule it
|
|
542
|
+
fails. Returns a dict per hook: file, user, command, program, verdict (in-force,
|
|
543
|
+
filters, unverified), changed [(command, "rewrites" or "blocks", detail)], why, asked.
|
|
544
|
+
"""
|
|
545
|
+
root = os.path.abspath(root)
|
|
546
|
+
programs = {_program_name(name) for name in settings.get(None, "filters.probe_programs")}
|
|
547
|
+
timeout = settings.get(None, "filters.probe_timeout_seconds")
|
|
548
|
+
results, search_path, commands = [], None, None
|
|
549
|
+
for path, declaration, user in command_hook_sources(root):
|
|
550
|
+
for hook in _shell_hooks(path, declaration):
|
|
551
|
+
shown = _hook_text(hook)
|
|
552
|
+
argv, why = _hook_argv(hook)
|
|
553
|
+
program = _program_name(argv[0] if argv else (shown.split() or ["hook"])[0])
|
|
554
|
+
if not (_REWRITING_HOOK.search(shown) or program in programs):
|
|
555
|
+
continue
|
|
556
|
+
result = {"file": path, "user": user, "command": shown, "program": program, "verdict": "unverified",
|
|
557
|
+
"changed": [], "why": None, "asked": 0}
|
|
558
|
+
results.append(result)
|
|
559
|
+
if not user or _within(path, root):
|
|
560
|
+
result["why"] = ("it is declared in the project's own settings, which the agents polyctl governs can "
|
|
561
|
+
"write, and polyctl runs no command such a file names")
|
|
562
|
+
continue
|
|
563
|
+
if argv:
|
|
564
|
+
if search_path is None:
|
|
565
|
+
from .watchdog import child_path
|
|
566
|
+
search_path = os.pathsep.join(d for d in child_path().split(os.pathsep)
|
|
567
|
+
if d and os.path.isabs(d) and not _within(d, root))
|
|
568
|
+
argv, why = _probe_program(argv, root, programs, search_path)
|
|
569
|
+
if why:
|
|
570
|
+
result["why"] = why
|
|
571
|
+
continue
|
|
572
|
+
env = _probe_environment(root, declaration, search_path)
|
|
573
|
+
tool = str(declaration.get("shell_tool") or "Bash")
|
|
574
|
+
commands = measurement_commands(root) if commands is None else commands
|
|
575
|
+
for index, command in enumerate(commands):
|
|
576
|
+
payload = json.dumps({
|
|
577
|
+
"session_id": "polyctl-filter-probe", "transcript_path": "", "cwd": root,
|
|
578
|
+
"permission_mode": "default", "hook_event_name": "PreToolUse", "tool_name": tool,
|
|
579
|
+
"tool_input": {"command": command, "description": "polyctl doctor: does a filter change this?"},
|
|
580
|
+
"tool_use_id": f"polyctl-filter-probe-{index}"}).encode(UTF8)
|
|
581
|
+
code, out, err, cut = _run_hook(argv, payload, root, env, timeout)
|
|
582
|
+
result["asked"] += 1
|
|
583
|
+
kind, detail = (None, cut) if cut else _hook_answer(command, code, out, err)
|
|
584
|
+
if cut or kind == "unreadable":
|
|
585
|
+
result["why"] = f"{detail} when asked about `{_clip(command)}`"
|
|
586
|
+
break
|
|
587
|
+
if kind:
|
|
588
|
+
result["changed"].append((command, kind, detail))
|
|
589
|
+
result["verdict"] = "filters" if result["changed"] else "unverified" if result["why"] else "in-force"
|
|
590
|
+
return results
|
|
591
|
+
|
|
592
|
+
|
|
593
|
+
def _clip(text, limit=200):
|
|
594
|
+
"""Text a settings file or a hook supplied, on one line and no longer than limit, for a doctor line."""
|
|
595
|
+
line = " ".join(str(text).split())
|
|
596
|
+
return line if len(line) <= limit else line[:limit - 3] + "..."
|
|
597
|
+
|
|
598
|
+
|
|
599
|
+
def filter_probe_text(result):
|
|
600
|
+
"""One sentence for one probed hook: in force, every measurement command it changes, or why it is unverified."""
|
|
601
|
+
where = f"`{_clip(result['command'])}` ({result['file']})"
|
|
602
|
+
if result["verdict"] == "in-force":
|
|
603
|
+
return f"{where} passes all {result['asked']} measurement commands through unchanged: its exclusions are in force"
|
|
604
|
+
changes = [(f"`{_clip(command)}` becomes `{_clip(detail)}`" if detail is not None
|
|
605
|
+
else f"`{_clip(command)}` loses its command")
|
|
606
|
+
if kind == "rewrites" else f"`{_clip(command)}` {detail}" for command, kind, detail in result["changed"]]
|
|
607
|
+
parts = [f"changes {len(changes)} of the {result['asked']} measurement commands it was asked about: "
|
|
608
|
+
+ "; ".join(changes)] if changes else []
|
|
609
|
+
if result["why"]:
|
|
610
|
+
parts.append(f"is not verified: {result['why']}")
|
|
611
|
+
return f"{where} " + ", and ".join(parts)
|
|
612
|
+
|
|
613
|
+
|
|
614
|
+
# A check holds one repository for its whole lifetime, including a nested call; no process-wide environment
|
|
615
|
+
# is changed and a planted project .git cannot move a later measurement (NESTED-GIT).
|
|
616
|
+
from contextlib import contextmanager as _git_contextmanager
|
|
617
|
+
from contextvars import ContextVar as _GitContextVar
|
|
618
|
+
|
|
619
|
+
_COMMIT_GIT_CONTEXT = _GitContextVar("polyctl_commit_git", default=None)
|
|
620
|
+
|
|
621
|
+
|
|
622
|
+
@_git_contextmanager
|
|
623
|
+
def bound_git_repository(top, git_dir, index):
|
|
624
|
+
"""Pin the hook's repository and active index until the check returns, even on failure (NESTED-GIT)."""
|
|
625
|
+
token = _COMMIT_GIT_CONTEXT.set((top, git_dir, index))
|
|
626
|
+
try:
|
|
627
|
+
yield
|
|
628
|
+
finally:
|
|
629
|
+
_COMMIT_GIT_CONTEXT.reset(token)
|
|
630
|
+
|
|
631
|
+
|
|
632
|
+
def bound_git_environment(env):
|
|
633
|
+
"""Git reads the pinned repository, never a .git rediscovered from the project cwd (NESTED-GIT)."""
|
|
634
|
+
binding = _COMMIT_GIT_CONTEXT.get()
|
|
635
|
+
if binding is None:
|
|
636
|
+
return env
|
|
637
|
+
top, git_dir, index = binding
|
|
638
|
+
clean = {name: value for name, value in env.items()
|
|
639
|
+
if name not in _GIT_BINDING and not name.startswith("GIT_CONFIG")}
|
|
640
|
+
clean.update(GIT_DIR=git_dir, GIT_WORK_TREE=top, GIT_INDEX_FILE=index)
|
|
641
|
+
return clean
|
|
642
|
+
|
|
643
|
+
|
|
644
|
+
def _git_output(root, *args, timeout=60, env=None):
|
|
645
|
+
"""Run git without a shell and return bytes, failing closed on an unreadable tree.
|
|
646
|
+
|
|
647
|
+
In a process group of its own, as every Git query of authority's is: a timeout stops git with what it started -
|
|
648
|
+
a hook or a filter a repository configures - where it stopped git alone (LEADS-GATE-RUNS).
|
|
649
|
+
"""
|
|
650
|
+
try:
|
|
651
|
+
merged = dict(os.environ, **env) if env else os.environ.copy()
|
|
652
|
+
result = run_as_group([git_binary(), *args], timeout, cwd=root, stdout=subprocess.PIPE,
|
|
653
|
+
stderr=subprocess.PIPE, env=bound_git_environment(merged))
|
|
654
|
+
except (OSError, subprocess.TimeoutExpired) as exc:
|
|
655
|
+
left, unasked = getattr(exc, "left", None), getattr(exc, "unasked", None)
|
|
656
|
+
raise RuntimeError(f"cannot measure git tree: {exc}"
|
|
657
|
+
+ (f"; {len(left)} process(es) it started still run after it was stopped: {left}"
|
|
658
|
+
if left else "") + (f"; {unasked}" if unasked else "")) from exc
|
|
659
|
+
if result.returncode:
|
|
660
|
+
detail = result.stderr.decode(UTF8, "replace").strip()[:240]
|
|
661
|
+
raise RuntimeError(f"cannot measure git tree: {detail or 'git failed'}")
|
|
662
|
+
return result.stdout
|
|
663
|
+
|
|
664
|
+
|
|
665
|
+
def _git_text(cwd, *args, timeout=20, env=None):
|
|
666
|
+
"""What `sh("git …", cwd=cwd)` returned, from the same git without a shell started in front of it.
|
|
667
|
+
|
|
668
|
+
A status read and every watchdog cycle asked the shell for their git queries, and each
|
|
669
|
+
paid for a shell before git ran. The answer is unchanged: standard output decoded as
|
|
670
|
+
UTF-8 with replacement, newlines normalised and stripped, whatever a failing git
|
|
671
|
+
printed there, and "" when git cannot be started or runs past the timeout.
|
|
672
|
+
"""
|
|
673
|
+
argv = [git_binary(), *args]
|
|
674
|
+
try:
|
|
675
|
+
# In a process group of its own, as every Git query is: a timeout stops git with what it started (LEADS-GATE-RUNS).
|
|
676
|
+
merged = dict(os.environ, **env) if env else os.environ.copy()
|
|
677
|
+
merged.setdefault("GIT_OPTIONAL_LOCKS", "0")
|
|
678
|
+
result = run_as_group(argv, timeout, cwd=cwd, capture_output=True, text=True, encoding=UTF8,
|
|
679
|
+
errors="replace", env=bound_git_environment(merged))
|
|
680
|
+
except Exception:
|
|
681
|
+
return ""
|
|
682
|
+
return result.stdout.strip()
|
|
683
|
+
|
|
684
|
+
|
|
685
|
+
def _digest_field(digest, label, value):
|
|
686
|
+
"""Length-frame one digest field so path/content boundaries cannot collide."""
|
|
687
|
+
digest.update(len(label).to_bytes(2, "big"))
|
|
688
|
+
digest.update(label)
|
|
689
|
+
digest.update(len(value).to_bytes(8, "big"))
|
|
690
|
+
digest.update(value)
|
|
691
|
+
|
|
692
|
+
|
|
693
|
+
def tree_digest(root, cfg=None):
|
|
694
|
+
"""A staging-independent fingerprint of tracked and untracked product state.
|
|
695
|
+
|
|
696
|
+
HEAD already identifies every unchanged tracked file. We therefore hash the
|
|
697
|
+
current bytes, type and executable bit of each path that differs from HEAD,
|
|
698
|
+
plus every non-ignored untracked path. The representation is identical before
|
|
699
|
+
and after `git add`, including for newly added files.
|
|
700
|
+
|
|
701
|
+
polyctl's own ledgers, reviews, mail and agent coordination directories are
|
|
702
|
+
deliberately excluded. Verification and review must be able to persist their
|
|
703
|
+
evidence without immediately making that evidence stale.
|
|
704
|
+
"""
|
|
705
|
+
cfg = load_config(root) if cfg is None else cfg
|
|
706
|
+
changed = _git_output(
|
|
707
|
+
root, "diff", "--name-only", "-z", "--no-renames", "HEAD", "--"
|
|
708
|
+
).split(b"\0")
|
|
709
|
+
untracked = _git_output(
|
|
710
|
+
root, "ls-files", "--others", "--exclude-standard", "-z", "--"
|
|
711
|
+
).split(b"\0")
|
|
712
|
+
paths = {
|
|
713
|
+
os.fsdecode(raw)
|
|
714
|
+
for raw in changed + untracked
|
|
715
|
+
if raw and not _is_coordination_path(os.fsdecode(raw), cfg)
|
|
716
|
+
}
|
|
717
|
+
|
|
718
|
+
digest = hashlib.sha256()
|
|
719
|
+
_digest_field(digest, b"format", b"polyctl-product-tree-v2")
|
|
720
|
+
_digest_field(digest, b"head", _git_output(root, "rev-parse", "HEAD").strip())
|
|
721
|
+
|
|
722
|
+
for rel in sorted(paths, key=os.fsencode):
|
|
723
|
+
full = os.path.join(root, rel)
|
|
724
|
+
_digest_field(digest, b"path", os.fsencode(rel))
|
|
725
|
+
try:
|
|
726
|
+
st = os.lstat(full)
|
|
727
|
+
except OSError:
|
|
728
|
+
_digest_field(digest, b"entry", b"missing")
|
|
729
|
+
continue
|
|
730
|
+
|
|
731
|
+
if os.path.islink(full):
|
|
732
|
+
_digest_field(digest, b"entry", b"symlink")
|
|
733
|
+
_digest_field(digest, b"target", os.fsencode(os.readlink(full)))
|
|
734
|
+
continue
|
|
735
|
+
if os.path.isfile(full):
|
|
736
|
+
content = hashlib.sha256()
|
|
737
|
+
with open(full, "rb") as fh:
|
|
738
|
+
for chunk in iter(lambda: fh.read(1024 * 1024), b""):
|
|
739
|
+
content.update(chunk)
|
|
740
|
+
_digest_field(digest, b"entry", b"file")
|
|
741
|
+
_digest_field(digest, b"executable", b"1" if st.st_mode & 0o111 else b"0")
|
|
742
|
+
_digest_field(digest, b"content", content.digest())
|
|
743
|
+
continue
|
|
744
|
+
if os.path.isdir(full):
|
|
745
|
+
# A directory here is normally a changed gitlink. Recurse so a dirty
|
|
746
|
+
# submodule is measured by content rather than by index state.
|
|
747
|
+
try:
|
|
748
|
+
sub = tree_digest(full, {})
|
|
749
|
+
except RuntimeError:
|
|
750
|
+
sub = "unreadable-directory"
|
|
751
|
+
_digest_field(digest, b"entry", b"directory")
|
|
752
|
+
_digest_field(digest, b"content", sub.encode(UTF8, "surrogateescape"))
|
|
753
|
+
continue
|
|
754
|
+
_digest_field(digest, b"entry", f"special:{st.st_mode}".encode())
|
|
755
|
+
|
|
756
|
+
return "sha256:" + digest.hexdigest()
|
|
757
|
+
|
|
758
|
+
|
|
759
|
+
CANDIDATE_FORMAT = "polyctl-index-candidate-v1"
|
|
760
|
+
REVIEW_EVIDENCE_PREFIX = "<!-- polyctl-evidence: "
|
|
761
|
+
|
|
762
|
+
|
|
763
|
+
def index_candidate(root):
|
|
764
|
+
"""Measure the exact tree Git would commit from the active index.
|
|
765
|
+
|
|
766
|
+
``git write-tree`` honors ``GIT_INDEX_FILE``, so this also measures the
|
|
767
|
+
temporary index exposed by ``git commit -a`` and path-limited commits. The
|
|
768
|
+
resulting tree object is immutable even if the live index changes later.
|
|
769
|
+
"""
|
|
770
|
+
head = _git_output(root, "rev-parse", "HEAD").strip()
|
|
771
|
+
index_tree = _git_output(root, "write-tree").strip()
|
|
772
|
+
if not head or not index_tree:
|
|
773
|
+
raise RuntimeError("cannot measure index candidate: missing object id")
|
|
774
|
+
head_s = head.decode("ascii", "strict")
|
|
775
|
+
tree_s = index_tree.decode("ascii", "strict")
|
|
776
|
+
status = _git_output(
|
|
777
|
+
root, "diff-tree", "-r", "--no-commit-id", "--name-status", "-z",
|
|
778
|
+
"--no-renames", head_s, tree_s, "--",
|
|
779
|
+
)
|
|
780
|
+
names = _git_output(
|
|
781
|
+
root, "diff-tree", "-r", "--no-commit-id", "--name-only", "-z",
|
|
782
|
+
"--no-renames", head_s, tree_s, "--",
|
|
783
|
+
)
|
|
784
|
+
changed_paths = sorted(
|
|
785
|
+
{os.fsdecode(raw) for raw in names.split(b"\0") if raw}, key=os.fsencode
|
|
786
|
+
)
|
|
787
|
+
digest = hashlib.sha256()
|
|
788
|
+
_digest_field(digest, b"format", CANDIDATE_FORMAT.encode("ascii"))
|
|
789
|
+
_digest_field(digest, b"head", head)
|
|
790
|
+
_digest_field(digest, b"index-tree", index_tree)
|
|
791
|
+
_digest_field(digest, b"status", status)
|
|
792
|
+
return {
|
|
793
|
+
"format": CANDIDATE_FORMAT,
|
|
794
|
+
"digest": "sha256:" + digest.hexdigest(),
|
|
795
|
+
"head": head_s,
|
|
796
|
+
"index_tree": tree_s,
|
|
797
|
+
"changed_paths": changed_paths,
|
|
798
|
+
"changed_count": len(changed_paths),
|
|
799
|
+
"status_digest": "sha256:" + hashlib.sha256(status).hexdigest(),
|
|
800
|
+
}
|
|
801
|
+
|
|
802
|
+
|
|
803
|
+
# ---- a tree written out of the repository, for a reader that must not run what it holds (REVIEW-TREE-3) ------------
|
|
804
|
+
|
|
805
|
+
def working_tree_snapshot(root, index):
|
|
806
|
+
"""The working tree as it stands, as a git tree object: each tracked file as it is now and each untracked one git
|
|
807
|
+
does not ignore, written through `index`, a file of the caller's, so the index git commits from is never touched
|
|
808
|
+
(CODEBASE-COPY).
|
|
809
|
+
|
|
810
|
+
A question about the code is about the code as it is, committed or not, and the index can hold a candidate the
|
|
811
|
+
implementer staged for review. The index's own entries are copied in first, so a tracked file that .gitignore
|
|
812
|
+
names is kept; `git add -A` then records every change, deletion and untracked file over them. Raises RuntimeError
|
|
813
|
+
naming the git step that failed.
|
|
814
|
+
"""
|
|
815
|
+
entries = _git_output(root, "ls-files", "--stage", "-z")
|
|
816
|
+
env = dict(os.environ, GIT_INDEX_FILE=index)
|
|
817
|
+
written = b""
|
|
818
|
+
for args, given in ((("update-index", "-z", "--index-info"), entries), (("add", "-A"), b""),
|
|
819
|
+
(("write-tree",), b"")):
|
|
820
|
+
try:
|
|
821
|
+
done = subprocess.run([git_binary(), *args], cwd=root, env=env, input=given, capture_output=True,
|
|
822
|
+
timeout=300)
|
|
823
|
+
except (OSError, subprocess.TimeoutExpired) as exc:
|
|
824
|
+
raise RuntimeError(f"git {args[0]} could not run: {exc}") from exc
|
|
825
|
+
if done.returncode:
|
|
826
|
+
detail = done.stderr.decode(UTF8, "replace").strip()[:240]
|
|
827
|
+
raise RuntimeError(f"git {args[0]} failed: {detail or 'exit ' + str(done.returncode)}")
|
|
828
|
+
written = done.stdout.strip()
|
|
829
|
+
return written.decode("ascii", "strict")
|
|
830
|
+
|
|
831
|
+
|
|
832
|
+
def _lands_inside(home, name, path=os.path):
|
|
833
|
+
"""Whether a tar member called `name` lands inside `home` once the platform has read its separators.
|
|
834
|
+
|
|
835
|
+
Judged by where the name resolves, never by its spelling: on Windows `..\\x` climbs out of the
|
|
836
|
+
directory, and a check that splits on '/' reads it as one harmless word.
|
|
837
|
+
"""
|
|
838
|
+
root = path.realpath(home)
|
|
839
|
+
return path.realpath(path.join(root, name)).startswith(root.rstrip(path.sep) + path.sep)
|
|
840
|
+
|
|
841
|
+
|
|
842
|
+
def unpack_tree(root, tree, target):
|
|
843
|
+
"""Write git tree `tree` of the repository at `root` into `target`, a folder this makes; `target` once the tree is
|
|
844
|
+
written whole, else None with nothing of `target` left (REVIEW-TREE-3).
|
|
845
|
+
|
|
846
|
+
`git archive` writes exactly the tree named, and what lands in `target` is a copy of it: no history, no index,
|
|
847
|
+
nothing a reader does there reaches the repository. A member naming an absolute path or a parent is dropped rather
|
|
848
|
+
than trusted, and so is a link, since what is unpacked comes from files an agent wrote. What any adapter declares
|
|
849
|
+
its harness reads from a project - `project_config` and its steering files - is not unpacked at all, wherever it
|
|
850
|
+
is: a harness started in a tree reads its hooks, plugins, MCP servers and instructions from there, and Claude Code
|
|
851
|
+
ran a SessionStart hook from a candidate's .claude/settings.json, agy the commands of its .agents/hooks.json and
|
|
852
|
+
OpenCode a plugin and an MCP server from .opencode/ and opencode.json, each though it only read. A member the
|
|
853
|
+
platform cannot write - a name longer than its file system takes, a name Windows reserves - can stop the
|
|
854
|
+
extraction after the members before it were written; `target` is then removed whole.
|
|
855
|
+
|
|
856
|
+
A review unpacks the candidate it pinned where its reviewer runs; `polyctl ask --codebase` unpacks the working tree
|
|
857
|
+
where its provider runs, and the unpacking moved here from the review's part so both make the same copy
|
|
858
|
+
(CODEBASE-COPY).
|
|
859
|
+
"""
|
|
860
|
+
import shutil
|
|
861
|
+
if not tree:
|
|
862
|
+
return None
|
|
863
|
+
made = False
|
|
864
|
+
try:
|
|
865
|
+
archive = subprocess.run([git_binary(), "archive", "--format=tar", str(tree)], cwd=root,
|
|
866
|
+
capture_output=True, timeout=120)
|
|
867
|
+
if archive.returncode != 0 or not archive.stdout:
|
|
868
|
+
return None
|
|
869
|
+
import io
|
|
870
|
+
import tarfile
|
|
871
|
+
names = project_config_names()
|
|
872
|
+
with tarfile.open(fileobj=io.BytesIO(archive.stdout)) as tar:
|
|
873
|
+
safe = [member for member in tar.getmembers()
|
|
874
|
+
if (member.isfile() or member.isdir()) and _lands_inside(target, member.name)
|
|
875
|
+
and project_config_member(member.name, names) is None]
|
|
876
|
+
os.mkdir(target)
|
|
877
|
+
made = True
|
|
878
|
+
extra = {"filter": "data"} if hasattr(tarfile, "data_filter") else {}
|
|
879
|
+
tar.extractall(target, members=safe, **extra)
|
|
880
|
+
except Exception:
|
|
881
|
+
if made:
|
|
882
|
+
shutil.rmtree(target, ignore_errors=True)
|
|
883
|
+
return None
|
|
884
|
+
return target
|
|
885
|
+
|
|
886
|
+
|
|
887
|
+
def _normal_scope_paths(paths):
|
|
888
|
+
out = []
|
|
889
|
+
for value in paths or []:
|
|
890
|
+
raw = str(value or "").replace("\\", "/")
|
|
891
|
+
if not raw or raw.startswith("/") or re.match(r"^[A-Za-z]:/", raw):
|
|
892
|
+
raise ValueError(f"scope path must be repository-relative: {value}")
|
|
893
|
+
normal = os.path.normpath(raw).replace("\\", "/")
|
|
894
|
+
if normal in ("", ".", "..") or normal.startswith("../"):
|
|
895
|
+
raise ValueError(f"scope path escapes the repository: {value}")
|
|
896
|
+
if normal not in out:
|
|
897
|
+
out.append(normal)
|
|
898
|
+
return sorted(out, key=os.fsencode)
|
|
899
|
+
|
|
900
|
+
|
|
901
|
+
def _path_in_scope(path, scope_paths):
|
|
902
|
+
return any(path == base or path.startswith(base.rstrip("/") + "/")
|
|
903
|
+
for base in scope_paths)
|
|
904
|
+
|
|
905
|
+
|
|
906
|
+
def candidate_scope(candidate, paths=None):
|
|
907
|
+
"""Bind a literal review scope to a candidate, rejecting staged extras."""
|
|
908
|
+
scope_paths = _normal_scope_paths(paths)
|
|
909
|
+
kind = "paths" if scope_paths else "full-index"
|
|
910
|
+
outside = [p for p in candidate["changed_paths"]
|
|
911
|
+
if scope_paths and not _path_in_scope(p, scope_paths)]
|
|
912
|
+
digest = hashlib.sha256()
|
|
913
|
+
_digest_field(digest, b"format", b"polyctl-candidate-scope-v1")
|
|
914
|
+
_digest_field(digest, b"candidate", candidate["digest"].encode("ascii"))
|
|
915
|
+
_digest_field(digest, b"kind", kind.encode("ascii"))
|
|
916
|
+
for path in scope_paths:
|
|
917
|
+
_digest_field(digest, b"path", os.fsencode(path))
|
|
918
|
+
return {
|
|
919
|
+
"kind": kind,
|
|
920
|
+
"paths": scope_paths,
|
|
921
|
+
"digest": "sha256:" + digest.hexdigest(),
|
|
922
|
+
"outside_paths": outside,
|
|
923
|
+
}
|
|
924
|
+
|
|
925
|
+
|
|
926
|
+
def candidate_diff(root, candidate, scope=None):
|
|
927
|
+
"""Render the immutable staged candidate, never the mutable worktree."""
|
|
928
|
+
scope = scope or candidate_scope(candidate)
|
|
929
|
+
args = [
|
|
930
|
+
"--literal-pathspecs", "diff-tree", "-p", "--binary", "--full-index",
|
|
931
|
+
"--no-ext-diff", "--no-renames", "--no-commit-id",
|
|
932
|
+
candidate["head"], candidate["index_tree"], "--",
|
|
933
|
+
]
|
|
934
|
+
args.extend(scope.get("paths") or [])
|
|
935
|
+
return _git_output(root, *args, timeout=60)
|
|
936
|
+
|
|
937
|
+
|
|
938
|
+
# ---- size is a tripwire that asks a question, not a gate that reshapes work (#34) ------
|
|
939
|
+
|
|
940
|
+
SIZE_KINDS = ("product", "tests", "fixtures", "generated", "deletion")
|
|
941
|
+
_GENERATED_PATH = re.compile(r"(^|/)(dist|build|generated|__generated__|vendor|node_modules)/|\.min\.(js|css)$|"
|
|
942
|
+
r"\.pb\.go$|_pb2\.py$|(^|/)(package-lock\.json|yarn\.lock|pnpm-lock\.yaml|"
|
|
943
|
+
r"poetry\.lock|Cargo\.lock|go\.sum|uv\.lock|Gemfile\.lock)$")
|
|
944
|
+
_FIXTURE_PATH = re.compile(r"(^|/)(fixtures?|testdata|__snapshots__|snapshots)/|\.snap$")
|
|
945
|
+
|
|
946
|
+
|
|
947
|
+
def size_kind(path):
|
|
948
|
+
"""What a changed path is, for counting: generated, fixtures, tests or product."""
|
|
949
|
+
path = str(path).replace("\\", "/")
|
|
950
|
+
if _GENERATED_PATH.search(path):
|
|
951
|
+
return "generated"
|
|
952
|
+
if _FIXTURE_PATH.search(path):
|
|
953
|
+
return "fixtures"
|
|
954
|
+
name = path.rsplit("/", 1)[-1]
|
|
955
|
+
if _is_test_path(path) or "__tests__" in path.split("/") or "spec" in path.split("/")[:-1] \
|
|
956
|
+
or re.search(r"_test\.go$|\.(test|spec)\.[cm]?[jt]sx?$", name):
|
|
957
|
+
return "tests"
|
|
958
|
+
return "product"
|
|
959
|
+
|
|
960
|
+
|
|
961
|
+
def candidate_size(root, candidate):
|
|
962
|
+
"""The staged candidate's size by kind and by path, never as one number (#34).
|
|
963
|
+
|
|
964
|
+
A single total conflated 400 lines of fixtures with 400 lines of concurrency.
|
|
965
|
+
Lines are what git counts between HEAD and the pinned index tree; a file
|
|
966
|
+
whose change only removes lines is a deletion, whatever its path.
|
|
967
|
+
"""
|
|
968
|
+
listed = _git_output(root, "diff-tree", "-r", "--numstat", "-z", "--no-renames",
|
|
969
|
+
candidate["head"], candidate["index_tree"])
|
|
970
|
+
kinds = {kind: {"paths": 0, "added": 0, "deleted": 0} for kind in SIZE_KINDS}
|
|
971
|
+
for entry in listed.split(b"\0"):
|
|
972
|
+
added, _, rest = entry.partition(b"\t")
|
|
973
|
+
deleted, _, path = rest.partition(b"\t")
|
|
974
|
+
if not path:
|
|
975
|
+
continue
|
|
976
|
+
plus = int(added) if added.isdigit() else 0
|
|
977
|
+
minus = int(deleted) if deleted.isdigit() else 0
|
|
978
|
+
kind = "deletion" if plus == 0 and minus > 0 else size_kind(os.fsdecode(path))
|
|
979
|
+
kinds[kind]["paths"] += 1
|
|
980
|
+
kinds[kind]["added"] += plus
|
|
981
|
+
kinds[kind]["deleted"] += minus
|
|
982
|
+
return {"paths": sum(k["paths"] for k in kinds.values()), "kinds": kinds}
|
|
983
|
+
|
|
984
|
+
|
|
985
|
+
def size_text(size):
|
|
986
|
+
"""One line naming each kind that changed: paths and lines, product first."""
|
|
987
|
+
parts = [f"{kind} {k['paths']} path(s) +{k['added']}/-{k['deleted']}"
|
|
988
|
+
for kind, k in size["kinds"].items() if k["paths"]]
|
|
989
|
+
return ", ".join(parts) or "nothing changed"
|
|
990
|
+
|
|
991
|
+
|
|
992
|
+
def size_tripwire(cfg, size):
|
|
993
|
+
"""Where a candidate's size stands against the guideline, and what that asks for (#34).
|
|
994
|
+
|
|
995
|
+
Within it, nothing. Over it, a question: the boundary must say why the slice
|
|
996
|
+
is one invariant that cannot be split without leaving a seam unreviewed, and
|
|
997
|
+
that statement goes to the reviewer. Only far above it, where no review is
|
|
998
|
+
credible at any length, a refusal. Generated files and pure deletions count
|
|
999
|
+
toward no limit.
|
|
1000
|
+
"""
|
|
1001
|
+
lines = size["kinds"]["product"]["added"] + size["kinds"]["product"]["deleted"]
|
|
1002
|
+
paths = sum(size["kinds"][kind]["paths"] for kind in ("product", "tests", "fixtures"))
|
|
1003
|
+
guide_lines = settings.get(cfg, "size.guideline_product_lines")
|
|
1004
|
+
guide_paths = settings.get(cfg, "size.guideline_paths")
|
|
1005
|
+
refuse_lines = settings.get(cfg, "size.refuse_product_lines")
|
|
1006
|
+
measured = f"{lines} product line(s) across {paths} path(s)"
|
|
1007
|
+
guideline = f"the guideline is {guide_lines} product lines and {guide_paths} paths"
|
|
1008
|
+
if lines > refuse_lines:
|
|
1009
|
+
return {"state": "refuse", "lines": lines, "paths": paths, "overshoot_pct": None,
|
|
1010
|
+
"text": f"{measured} is far above what a review can credibly judge ({refuse_lines} product "
|
|
1011
|
+
f"lines, size.refuse_product_lines); {guideline}. Split it."}
|
|
1012
|
+
if lines <= guide_lines and paths <= guide_paths:
|
|
1013
|
+
return {"state": "within", "lines": lines, "paths": paths, "overshoot_pct": 0, "text": measured}
|
|
1014
|
+
overshoot = max(100 * (lines - guide_lines) / guide_lines, 100 * (paths - guide_paths) / guide_paths)
|
|
1015
|
+
return {"state": "over", "lines": lines, "paths": paths, "overshoot_pct": round(overshoot),
|
|
1016
|
+
"text": f"{measured} is over the guideline ({guideline})"}
|
|
1017
|
+
|
|
1018
|
+
|
|
1019
|
+
def one_slice_statement(item, boundary=None):
|
|
1020
|
+
"""Why an oversized slice is one invariant, as its boundary states it (#34): a file section or `one slice:`."""
|
|
1021
|
+
if boundary and (boundary.get("sections") or {}).get("why one slice", "").strip():
|
|
1022
|
+
return boundary["sections"]["why one slice"].strip()
|
|
1023
|
+
return ((((item or {}).get("notes") or {}).get("one slice")) or "").strip()
|
|
1024
|
+
|
|
1025
|
+
|
|
1026
|
+
# What a review prompt's claims and context may take together, as review.context_bytes defaults to (REVIEW-BUDGET).
|
|
1027
|
+
REVIEW_CONTEXT_BUDGET = settings.default("review.context_bytes")
|
|
1028
|
+
|
|
1029
|
+
|
|
1030
|
+
def _is_test_path(path):
|
|
1031
|
+
parts = str(path).replace("\\", "/").split("/")
|
|
1032
|
+
name = parts[-1]
|
|
1033
|
+
return (any(part in ("tests", "test") for part in parts[:-1])
|
|
1034
|
+
or name.startswith("test_") or name.endswith("_test.py") or name == "conftest.py")
|
|
1035
|
+
|
|
1036
|
+
|
|
1037
|
+
def _review_definitions(root, rev, path, cache):
|
|
1038
|
+
"""Committed definitions and static part loads: (lines, name -> (start, end), parts)."""
|
|
1039
|
+
import ast
|
|
1040
|
+
if path not in cache:
|
|
1041
|
+
cache[path] = None
|
|
1042
|
+
try:
|
|
1043
|
+
source = _git_output(root, "show", f"{rev}:{path}", timeout=30).decode(UTF8, "replace")
|
|
1044
|
+
tree = ast.parse(source)
|
|
1045
|
+
except (RuntimeError, SyntaxError, ValueError):
|
|
1046
|
+
return None
|
|
1047
|
+
spans = {}
|
|
1048
|
+
for node in tree.body:
|
|
1049
|
+
if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)):
|
|
1050
|
+
spans[node.name] = (min([node.lineno] + [d.lineno for d in node.decorator_list]),
|
|
1051
|
+
node.end_lineno)
|
|
1052
|
+
elif isinstance(node, (ast.Assign, ast.AnnAssign)):
|
|
1053
|
+
for target in (node.targets if isinstance(node, ast.Assign) else [node.target]):
|
|
1054
|
+
if isinstance(target, ast.Name):
|
|
1055
|
+
spans[target.id] = (node.lineno, node.end_lineno)
|
|
1056
|
+
cache[path] = (source.splitlines(), spans, top_level_statements(source)[2])
|
|
1057
|
+
return cache[path]
|
|
1058
|
+
|
|
1059
|
+
|
|
1060
|
+
def review_context(root, paths, read_rev, context_rev, budget=REVIEW_CONTEXT_BUDGET):
|
|
1061
|
+
"""Committed source a test-only candidate exercises, for the reviewer to read (#97).
|
|
1062
|
+
|
|
1063
|
+
The candidate is what may land; this is what it is judged against. None of it
|
|
1064
|
+
enters the diff or the candidate digest, so supplying it widens the authority
|
|
1065
|
+
binding by nothing. Context is attached only when every Python file in the
|
|
1066
|
+
candidate is a test: a test cannot be judged without the code it runs, while
|
|
1067
|
+
a source change carries its own subject.
|
|
1068
|
+
|
|
1069
|
+
The tests are read at ``read_rev`` (the index tree for a staged candidate) and
|
|
1070
|
+
the source at ``context_rev``. A definition the tests name through an import -
|
|
1071
|
+
an attribute of an imported module, an imported name, or a name handed to
|
|
1072
|
+
``setattr`` as a string - is copied whole, in the order the tests first name
|
|
1073
|
+
it, while the budget lasts. What does not fit is named, never cut, and the
|
|
1074
|
+
whole text, including its header and names, stays within the budget. Python only.
|
|
1075
|
+
"""
|
|
1076
|
+
import ast
|
|
1077
|
+
if budget <= 0:
|
|
1078
|
+
return None
|
|
1079
|
+
py = [path for path in paths or [] if path.endswith(".py")]
|
|
1080
|
+
if not py or not all(_is_test_path(path) for path in py):
|
|
1081
|
+
return None
|
|
1082
|
+
try:
|
|
1083
|
+
listing = _git_output(root, "ls-tree", "-r", "--name-only", "-z", context_rev, "--")
|
|
1084
|
+
except RuntimeError:
|
|
1085
|
+
return None
|
|
1086
|
+
committed = {os.fsdecode(raw) for raw in listing.split(b"\0") if raw}
|
|
1087
|
+
refs = []
|
|
1088
|
+
for path in py:
|
|
1089
|
+
try:
|
|
1090
|
+
tree = ast.parse(_git_output(root, "show", f"{read_rev}:{path}", timeout=30))
|
|
1091
|
+
except (RuntimeError, SyntaxError, ValueError):
|
|
1092
|
+
continue
|
|
1093
|
+
modules, names = {}, {}
|
|
1094
|
+
for node in ast.walk(tree):
|
|
1095
|
+
if isinstance(node, ast.Import):
|
|
1096
|
+
for alias in node.names:
|
|
1097
|
+
modules[alias.asname or alias.name] = alias.name
|
|
1098
|
+
elif isinstance(node, ast.ImportFrom):
|
|
1099
|
+
package = path.split("/")[:-1]
|
|
1100
|
+
if package and package[0] == "src":
|
|
1101
|
+
package = package[1:]
|
|
1102
|
+
if node.level > len(package):
|
|
1103
|
+
continue
|
|
1104
|
+
relative = package[:len(package) - node.level + 1] if node.level else []
|
|
1105
|
+
module = ".".join(relative + ([node.module] if node.module else []))
|
|
1106
|
+
for alias in node.names:
|
|
1107
|
+
bound = alias.asname or alias.name
|
|
1108
|
+
modules[bound] = f"{module}.{alias.name}"
|
|
1109
|
+
names[bound] = (module, alias.name)
|
|
1110
|
+
for node in ast.walk(tree):
|
|
1111
|
+
at = (path, getattr(node, "lineno", 0), getattr(node, "col_offset", 0))
|
|
1112
|
+
if isinstance(node, ast.Attribute):
|
|
1113
|
+
parts, base = [], node
|
|
1114
|
+
while isinstance(base, ast.Attribute):
|
|
1115
|
+
parts.insert(0, base.attr)
|
|
1116
|
+
base = base.value
|
|
1117
|
+
if isinstance(base, ast.Name):
|
|
1118
|
+
parts.insert(0, base.id)
|
|
1119
|
+
for end in range(len(parts) - 1, 0, -1):
|
|
1120
|
+
prefix = ".".join(parts[:end])
|
|
1121
|
+
if prefix in modules:
|
|
1122
|
+
refs.append((at, modules[prefix], parts[end]))
|
|
1123
|
+
break
|
|
1124
|
+
elif isinstance(node, ast.Name) and isinstance(node.ctx, ast.Load) and node.id in names:
|
|
1125
|
+
refs.append((at, *names[node.id]))
|
|
1126
|
+
elif (isinstance(node, ast.Call) and len(node.args) >= 2
|
|
1127
|
+
and isinstance(node.args[0], ast.Name) and node.args[0].id in modules
|
|
1128
|
+
and isinstance(node.args[1], ast.Constant) and isinstance(node.args[1].value, str)):
|
|
1129
|
+
refs.append((at, modules[node.args[0].id], node.args[1].value))
|
|
1130
|
+
cache, seen, order, blocks = {}, set(), [], {}
|
|
1131
|
+
for _, module, name in sorted(refs):
|
|
1132
|
+
qualified = f"{module}.{name}"
|
|
1133
|
+
if qualified in seen:
|
|
1134
|
+
continue
|
|
1135
|
+
seen.add(qualified)
|
|
1136
|
+
base = module.replace(".", "/")
|
|
1137
|
+
path = next((candidate for candidate in (f"src/{base}.py", f"{base}.py",
|
|
1138
|
+
f"src/{base}/__init__.py", f"{base}/__init__.py")
|
|
1139
|
+
if candidate in committed), None)
|
|
1140
|
+
waiting, visited = [path] if path else [], set()
|
|
1141
|
+
while waiting:
|
|
1142
|
+
path = waiting.pop(0)
|
|
1143
|
+
if path in visited or path not in committed:
|
|
1144
|
+
continue
|
|
1145
|
+
visited.add(path)
|
|
1146
|
+
found = _review_definitions(root, context_rev, path, cache)
|
|
1147
|
+
if not found:
|
|
1148
|
+
continue
|
|
1149
|
+
if name in found[1]:
|
|
1150
|
+
break
|
|
1151
|
+
# polyctl's own public definitions live in statically named parts (TRIAGE-1-MEDIUM).
|
|
1152
|
+
waiting += [_part_file(path, part) for part in found[2]]
|
|
1153
|
+
else:
|
|
1154
|
+
continue
|
|
1155
|
+
start, end = found[1][name]
|
|
1156
|
+
order.append(qualified)
|
|
1157
|
+
blocks[qualified] = (path, f"# {path}:{start}-{end} {qualified}\n"
|
|
1158
|
+
+ "\n".join(found[0][start - 1:end]) + "\n")
|
|
1159
|
+
files = list(dict.fromkeys(blocks[qualified][0] for qualified in order))
|
|
1160
|
+
|
|
1161
|
+
def render(kept):
|
|
1162
|
+
omitted = [qualified for qualified in order if qualified not in kept]
|
|
1163
|
+
lines = [f"committed at {context_rev[:12]}; read-only; not under review",
|
|
1164
|
+
"files: " + (", ".join(files) or "none resolved from the tests' imports")]
|
|
1165
|
+
if omitted:
|
|
1166
|
+
shown = []
|
|
1167
|
+
for qualified in omitted:
|
|
1168
|
+
if sum(len(name) + 2 for name in shown) + len(qualified) > 2_000:
|
|
1169
|
+
break
|
|
1170
|
+
shown.append(qualified)
|
|
1171
|
+
more = len(omitted) - len(shown)
|
|
1172
|
+
lines.append("not inlined for size, read them from the committed tree: "
|
|
1173
|
+
+ ", ".join(shown) + (f" and {more} more" if more else ""))
|
|
1174
|
+
return {"rev": context_rev, "paths": files, "names": list(kept), "omitted": omitted,
|
|
1175
|
+
"text": "\n".join(lines) + "".join("\n\n" + blocks[q][1] for q in kept)}
|
|
1176
|
+
|
|
1177
|
+
kept, spent = [], 0
|
|
1178
|
+
for qualified in order:
|
|
1179
|
+
size = len(blocks[qualified][1].encode(UTF8)) + 2
|
|
1180
|
+
if spent + size <= budget:
|
|
1181
|
+
kept.append(qualified)
|
|
1182
|
+
spent += size
|
|
1183
|
+
result = render(kept)
|
|
1184
|
+
while kept and len(result["text"].encode(UTF8)) > budget:
|
|
1185
|
+
kept.pop()
|
|
1186
|
+
result = render(kept)
|
|
1187
|
+
if len(result["text"].encode(UTF8)) > budget:
|
|
1188
|
+
# Even the names can exceed a small remaining argument budget (TRIAGE-1-MEDIUM).
|
|
1189
|
+
result["text"] = f"committed at {context_rev[:12]}; read-only; not under review"
|
|
1190
|
+
if len(result["text"].encode(UTF8)) > budget:
|
|
1191
|
+
return None
|
|
1192
|
+
return result
|
|
1193
|
+
|
|
1194
|
+
|
|
1195
|
+
def range_end_tree(root, commits):
|
|
1196
|
+
"""The tree a retrospective range ends on, which its reviewer reads; None where there is none (REVIEW-RANGE-TREE)."""
|
|
1197
|
+
if ".." not in str(commits or ""):
|
|
1198
|
+
return None
|
|
1199
|
+
end = str(commits).split("..", 1)[1].lstrip(".") or "HEAD"
|
|
1200
|
+
if end.startswith("-"):
|
|
1201
|
+
return None
|
|
1202
|
+
try:
|
|
1203
|
+
return _git_output(root, "rev-parse", "--verify", "--quiet", end + "^{tree}").decode("ascii").strip() or None
|
|
1204
|
+
except (RuntimeError, UnicodeError):
|
|
1205
|
+
return None
|
|
1206
|
+
|
|
1207
|
+
|
|
1208
|
+
def review_range_context(root, commits, budget=REVIEW_CONTEXT_BUDGET):
|
|
1209
|
+
"""The same context for a retrospective range, read at the range's end commit."""
|
|
1210
|
+
if ".." not in commits:
|
|
1211
|
+
return None
|
|
1212
|
+
end = commits.split("..", 1)[1].lstrip(".") or "HEAD"
|
|
1213
|
+
if end.startswith("-"):
|
|
1214
|
+
return None
|
|
1215
|
+
try:
|
|
1216
|
+
rev = _git_output(root, "rev-parse", "--verify", "--quiet",
|
|
1217
|
+
end + "^{commit}").decode("ascii").strip()
|
|
1218
|
+
names = _git_output(root, "diff", "--name-only", "-z", "--no-renames", commits, "--")
|
|
1219
|
+
except (RuntimeError, UnicodeError):
|
|
1220
|
+
return None
|
|
1221
|
+
paths = sorted({os.fsdecode(raw) for raw in names.split(b"\0") if raw}, key=os.fsencode)
|
|
1222
|
+
return review_context(root, paths, rev, rev, budget)
|
|
1223
|
+
|
|
1224
|
+
|
|
1225
|
+
def review_context_line(context):
|
|
1226
|
+
files = review_header_value(", ".join(context["paths"])) \
|
|
1227
|
+
or "none resolved from the tests' imports"
|
|
1228
|
+
line = (f"- context: read-only at `{context['rev'][:12]}`: {files}; "
|
|
1229
|
+
f"{len(context['names'])} definitions")
|
|
1230
|
+
if context["omitted"]:
|
|
1231
|
+
line += f", {len(context['omitted'])} not inlined for size"
|
|
1232
|
+
return line
|
|
1233
|
+
|
|
1234
|
+
|
|
1235
|
+
REVIEW_CLAIMS_MAX_COMMITS = 500
|
|
1236
|
+
REVIEW_CLAIMS_INDENT = " "
|
|
1237
|
+
|
|
1238
|
+
|
|
1239
|
+
def review_range_claims(root, commits, budget=REVIEW_CONTEXT_BUDGET):
|
|
1240
|
+
"""What the commits of a landed range say they did, for its retrospective review to verify.
|
|
1241
|
+
|
|
1242
|
+
A waived range's boundary is the owner's reason for waiving it, the same for every
|
|
1243
|
+
slice, while each commit message states what was wrong, what changed and what the
|
|
1244
|
+
tests prove. Oldest first, a message goes in whole while the budget lasts; one that
|
|
1245
|
+
does not fit is named by its commit and subject, never cut. Each is scanned for
|
|
1246
|
+
credentials as evidence is (#48). A subject is written as a review header value is
|
|
1247
|
+
(#55) and every body line is indented, so no line of a message starts at the margin,
|
|
1248
|
+
where the prompt's markers stand. The newest REVIEW_CLAIMS_MAX_COMMITS are read.
|
|
1249
|
+
|
|
1250
|
+
Returns None when `commits` is not a two-dot range git can list, otherwise commits
|
|
1251
|
+
(how many the range holds), inlined, subjects, redacted (the rules that hit), text and
|
|
1252
|
+
its digest.
|
|
1253
|
+
"""
|
|
1254
|
+
commits = str(commits)
|
|
1255
|
+
if commits.startswith("-") or "..." in commits or ".." not in commits:
|
|
1256
|
+
return None
|
|
1257
|
+
try:
|
|
1258
|
+
total = int(_git_output(root, "rev-list", "--count", commits, "--").strip() or 0)
|
|
1259
|
+
raw = _git_output(root, "log", f"--max-count={REVIEW_CLAIMS_MAX_COMMITS}", "-z",
|
|
1260
|
+
"--format=%H%n%B", commits, "--")
|
|
1261
|
+
except (RuntimeError, ValueError):
|
|
1262
|
+
return None
|
|
1263
|
+
blocks, hits = [], set() # (commit, how a list names it, the message as the prompt holds it)
|
|
1264
|
+
for record in reversed(raw.split(b"\0")):
|
|
1265
|
+
ident, _, message = record.decode(UTF8, "replace").lstrip("\n").partition("\n")
|
|
1266
|
+
if not re.fullmatch(r"[0-9a-f]{40}|[0-9a-f]{64}", ident):
|
|
1267
|
+
continue
|
|
1268
|
+
message, found = scan_evidence(message)
|
|
1269
|
+
hits.update(found)
|
|
1270
|
+
lines = message.splitlines() or [""]
|
|
1271
|
+
body = lines[1:]
|
|
1272
|
+
while body and not body[0].strip():
|
|
1273
|
+
body.pop(0)
|
|
1274
|
+
while body and not body[-1].strip():
|
|
1275
|
+
body.pop()
|
|
1276
|
+
block = "\n".join([f"commit {ident[:12]} {review_header_value(lines[0])}"]
|
|
1277
|
+
+ [REVIEW_CLAIMS_INDENT + line if line.strip() else "" for line in body])
|
|
1278
|
+
blocks.append((ident, f"{ident[:12]} {review_header_value(lines[0][:120])}", block))
|
|
1279
|
+
|
|
1280
|
+
def render(kept, room=2_000):
|
|
1281
|
+
named = [name for ident, name, _ in blocks if ident not in kept]
|
|
1282
|
+
missing = len(named) + max(0, total - len(blocks))
|
|
1283
|
+
parts = [block for ident, _, block in blocks if ident in kept]
|
|
1284
|
+
shown = []
|
|
1285
|
+
for name in named:
|
|
1286
|
+
if sum(len(item) + 2 for item in shown) + len(name) > room:
|
|
1287
|
+
break
|
|
1288
|
+
shown.append(name)
|
|
1289
|
+
if shown:
|
|
1290
|
+
parts.append("not inlined for size: " + "; ".join(shown)
|
|
1291
|
+
+ (f" and {missing - len(shown)} more commit(s)" if missing > len(shown) else ""))
|
|
1292
|
+
elif missing:
|
|
1293
|
+
parts.append(f"not inlined for size: {missing} commit(s)")
|
|
1294
|
+
return "\n\n".join(parts)
|
|
1295
|
+
|
|
1296
|
+
def fits(text):
|
|
1297
|
+
return len(text.encode(UTF8)) <= budget
|
|
1298
|
+
|
|
1299
|
+
kept = {ident for ident, _, _ in blocks}
|
|
1300
|
+
if not fits(render(kept)):
|
|
1301
|
+
kept = set()
|
|
1302
|
+
for ident, _, _ in blocks:
|
|
1303
|
+
if fits(render(kept | {ident})):
|
|
1304
|
+
kept.add(ident)
|
|
1305
|
+
text = render(kept)
|
|
1306
|
+
if not fits(text):
|
|
1307
|
+
text = render(kept, room=0) # where even the names do not fit, their count stands for them
|
|
1308
|
+
return {"commits": total, "inlined": len(kept), "subjects": [name for _, name, _ in blocks],
|
|
1309
|
+
"redacted": sorted(hits), "text": text, "digest": "sha256:" + hashlib.sha256(text.encode(UTF8)).hexdigest()}
|
|
1310
|
+
|
|
1311
|
+
|
|
1312
|
+
def review_claims_line(claims):
|
|
1313
|
+
"""The header line of a review told what its range's commits claim: which, and what was left out."""
|
|
1314
|
+
shown = claims["subjects"][:3]
|
|
1315
|
+
line = (f"- claims: {claims['commits']} commit message(s), given to the reviewer as claims to verify: "
|
|
1316
|
+
+ "; ".join(shown))
|
|
1317
|
+
if claims["commits"] > len(shown):
|
|
1318
|
+
line += f" and {claims['commits'] - len(shown)} more"
|
|
1319
|
+
if claims["inlined"] < claims["commits"]:
|
|
1320
|
+
line += f"; {claims['commits'] - claims['inlined']} not inlined for size"
|
|
1321
|
+
if claims["redacted"]:
|
|
1322
|
+
line += "; redacted: " + ", ".join(claims["redacted"])
|
|
1323
|
+
return line
|
|
1324
|
+
|
|
1325
|
+
|
|
1326
|
+
# ---- gate coverage: a source tree no gate exercises (#5) ------------------------------
|
|
1327
|
+
|
|
1328
|
+
TOOLCHAINS = {
|
|
1329
|
+
"python": {"ext": (".py",), "runners": ("pytest", "python", "python3", "ruff", "mypy", "tox", "uv")},
|
|
1330
|
+
"node": {"ext": (".js", ".jsx", ".ts", ".tsx", ".mjs", ".cjs"),
|
|
1331
|
+
"runners": ("npm", "npx", "pnpm", "yarn", "node", "vitest", "jest", "tsc", "bun", "deno")},
|
|
1332
|
+
"dotnet": {"ext": (".cs", ".fs", ".vb"), "runners": ("dotnet", "msbuild")},
|
|
1333
|
+
"go": {"ext": (".go",), "runners": ("go",)},
|
|
1334
|
+
"rust": {"ext": (".rs",), "runners": ("cargo",)},
|
|
1335
|
+
"jvm": {"ext": (".java", ".kt", ".scala"), "runners": ("mvn", "gradle", "gradlew", "sbt")},
|
|
1336
|
+
"swift": {"ext": (".swift",), "runners": ("swift", "xcodebuild")},
|
|
1337
|
+
}
|
|
1338
|
+
|
|
1339
|
+
|
|
1340
|
+
def source_trees(root, minimum):
|
|
1341
|
+
"""{top-level tree: {toolchain: files}} for every tree holding at least `minimum` of one toolchain's files.
|
|
1342
|
+
|
|
1343
|
+
Tracked and untracked-but-not-ignored files, as git lists them; files at the top
|
|
1344
|
+
level count as the tree ".".
|
|
1345
|
+
"""
|
|
1346
|
+
try:
|
|
1347
|
+
listed = _git_output(root, "ls-files", "-z", "--cached", "--others", "--exclude-standard")
|
|
1348
|
+
except RuntimeError:
|
|
1349
|
+
return {}
|
|
1350
|
+
counts = {}
|
|
1351
|
+
for raw in listed.split(b"\0"):
|
|
1352
|
+
path = os.fsdecode(raw)
|
|
1353
|
+
if not path:
|
|
1354
|
+
continue
|
|
1355
|
+
tree = path.split("/", 1)[0] if "/" in path else "."
|
|
1356
|
+
chain = next((name for name, spec in TOOLCHAINS.items() if path.endswith(spec["ext"])), None)
|
|
1357
|
+
if chain:
|
|
1358
|
+
counts.setdefault(tree, {}).setdefault(chain, 0)
|
|
1359
|
+
counts[tree][chain] += 1
|
|
1360
|
+
return {tree: {chain: n for chain, n in chains.items() if n >= minimum}
|
|
1361
|
+
for tree, chains in counts.items() if any(n >= minimum for n in chains.values())}
|
|
1362
|
+
|
|
1363
|
+
|
|
1364
|
+
# A word of a gate's command line that launches the program after it: `python -m pytest`, `npx vitest`, `uv run pytest`.
|
|
1365
|
+
_GATE_LAUNCHERS = {"python": "-m", "python3": "-m", "py": "-m", "npx": None, "pnpx": None, "bunx": None, "uv": "run",
|
|
1366
|
+
"poetry": "run", "pipenv": "run"}
|
|
1367
|
+
|
|
1368
|
+
|
|
1369
|
+
def _gate_programs(run):
|
|
1370
|
+
"""The programs a gate's command line starts: the first word of each command in it - after `&&`, `||`, `;`, `|`
|
|
1371
|
+
or `&`, a `NAME=value` aside - and the one a launcher such as `python -m` or `npx` starts after it, each named as
|
|
1372
|
+
a runner is (TRIAGE-HIGHS).
|
|
1373
|
+
|
|
1374
|
+
A runner was matched anywhere in the line, so `echo pytest` read as running pytest and covered every Python
|
|
1375
|
+
tree."""
|
|
1376
|
+
import shlex
|
|
1377
|
+
# Tokenize before splitting commands: a quoted separator never starts a runner (TRIAGE-2-MEDIUM).
|
|
1378
|
+
try:
|
|
1379
|
+
lexer = shlex.shlex(str(run or ""), posix=False, punctuation_chars=";&|()\n")
|
|
1380
|
+
lexer.whitespace = " \t\r"
|
|
1381
|
+
lexer.whitespace_split = True
|
|
1382
|
+
tokens = list(lexer)
|
|
1383
|
+
except ValueError:
|
|
1384
|
+
return set()
|
|
1385
|
+
found = set()
|
|
1386
|
+
commands, words = [], []
|
|
1387
|
+
for token in tokens:
|
|
1388
|
+
if token and all(char in ";&|()\n" for char in token):
|
|
1389
|
+
commands.append(words)
|
|
1390
|
+
words = []
|
|
1391
|
+
else:
|
|
1392
|
+
words.append(token)
|
|
1393
|
+
commands.append(words)
|
|
1394
|
+
for words in commands:
|
|
1395
|
+
words = [word.strip("\"'") for word in words]
|
|
1396
|
+
while words and re.fullmatch(r"[A-Za-z_][A-Za-z0-9_]*=.*", words[0]):
|
|
1397
|
+
words.pop(0)
|
|
1398
|
+
names = [re.sub(r"\.(exe|cmd|bat)$", "", re.split(r"[\\/]", word)[-1].lower()) for word in words]
|
|
1399
|
+
if not names:
|
|
1400
|
+
continue
|
|
1401
|
+
# A wrapper is itself a runner, including when flags precede its package (TRIAGE-2-MEDIUM).
|
|
1402
|
+
found.add(names[0])
|
|
1403
|
+
after = _GATE_LAUNCHERS.get(names[0], "")
|
|
1404
|
+
if after is None and len(names) > 1:
|
|
1405
|
+
found.add(names[1])
|
|
1406
|
+
elif after and len(names) > 2 and names[1] == after:
|
|
1407
|
+
found.add(names[2])
|
|
1408
|
+
return found
|
|
1409
|
+
|
|
1410
|
+
|
|
1411
|
+
def _gate_covers(gate, tree, chain):
|
|
1412
|
+
"""Whether one gate exercises a toolchain's files in one tree: it runs that toolchain's
|
|
1413
|
+
runner where a command starts and, when it declares inputs, one of them reaches into the tree."""
|
|
1414
|
+
import fnmatch
|
|
1415
|
+
if not isinstance(gate, dict):
|
|
1416
|
+
return False # no gate polyctl reads; the doctor names the file (TRIAGE-HIGHS)
|
|
1417
|
+
if not _gate_programs(gate.get("run")) & set(TOOLCHAINS[chain]["runners"]):
|
|
1418
|
+
return False
|
|
1419
|
+
inputs = gate.get("inputs")
|
|
1420
|
+
if not isinstance(inputs, list) or not inputs:
|
|
1421
|
+
return True
|
|
1422
|
+
probe = "x" + TOOLCHAINS[chain]["ext"][0] if tree == "." else f"{tree}/x{TOOLCHAINS[chain]['ext'][0]}"
|
|
1423
|
+
return any(fnmatch.fnmatchcase(probe, str(glob)) or str(glob).startswith(f"{tree}/") for glob in inputs)
|
|
1424
|
+
|
|
1425
|
+
|
|
1426
|
+
def gate_coverage_gaps(root, spec, minimum, names=None):
|
|
1427
|
+
"""(tree, toolchain, files) for every tree's toolchain that no gate - or none of `names` - exercises."""
|
|
1428
|
+
gates = spec.get("gates") if isinstance(spec, dict) else None
|
|
1429
|
+
gates = gates if isinstance(gates, dict) else {}
|
|
1430
|
+
chosen = [gate for name, gate in gates.items() if isinstance(gate, dict)
|
|
1431
|
+
and (names is None or name in names)]
|
|
1432
|
+
gaps = []
|
|
1433
|
+
for tree, chains in sorted(source_trees(root, minimum).items()):
|
|
1434
|
+
for chain, files in sorted(chains.items()):
|
|
1435
|
+
if not any(_gate_covers(gate, tree, chain) for gate in chosen):
|
|
1436
|
+
gaps.append((tree, chain, files))
|
|
1437
|
+
return gaps
|
|
1438
|
+
|
|
1439
|
+
|
|
1440
|
+
def gate_inputs(root):
|
|
1441
|
+
"""The paths the declared gates read, as globs, or None for the whole tree (#16).
|
|
1442
|
+
|
|
1443
|
+
A gate may name its `inputs`. Only when every gate in `.polyctl/gates.json` does can
|
|
1444
|
+
a dirty path outside all of them be known not to reach a gate; one gate without
|
|
1445
|
+
inputs reads the whole tree, and so does a file that cannot be read.
|
|
1446
|
+
"""
|
|
1447
|
+
try:
|
|
1448
|
+
with open(os.path.join(root, ".polyctl", "gates.json"), encoding=UTF8) as fh:
|
|
1449
|
+
spec = json.load(fh)
|
|
1450
|
+
except (OSError, ValueError):
|
|
1451
|
+
return None
|
|
1452
|
+
return gate_inputs_of(spec)
|
|
1453
|
+
|
|
1454
|
+
|
|
1455
|
+
def gate_inputs_of(spec):
|
|
1456
|
+
"""gate_inputs of one reading of `.polyctl/gates.json`, `spec`: the one `polyctl verify` runs its gates from (TRIAGE-HIGHS).
|
|
1457
|
+
|
|
1458
|
+
Verify judged isolation by the file read again after it had waited for the machine lock: inputs narrowed
|
|
1459
|
+
in that wait, and put back once the run was recorded, left an untracked file a gate read out of the
|
|
1460
|
+
check, and the recorded digest still matched the file."""
|
|
1461
|
+
gates = spec.get("gates") if isinstance(spec, dict) else None
|
|
1462
|
+
if not isinstance(gates, dict) or not gates:
|
|
1463
|
+
return None
|
|
1464
|
+
globs = set()
|
|
1465
|
+
for gate in gates.values():
|
|
1466
|
+
declared = gate.get("inputs") if isinstance(gate, dict) else None
|
|
1467
|
+
if not isinstance(declared, list) or not declared \
|
|
1468
|
+
or not all(isinstance(item, str) and item.strip() for item in declared):
|
|
1469
|
+
return None
|
|
1470
|
+
globs.update(item.strip() for item in declared)
|
|
1471
|
+
return sorted(globs)
|
|
1472
|
+
|
|
1473
|
+
|
|
1474
|
+
def coordination_candidate(candidate, cfg):
|
|
1475
|
+
"""Whether a staged candidate holds only coordination paths (COORDINATION-COMMIT)."""
|
|
1476
|
+
paths = (candidate or {}).get("changed_paths") or []
|
|
1477
|
+
return bool(paths) and all(_is_coordination_path(path, cfg) for path in paths)
|
|
1478
|
+
|
|
1479
|
+
|
|
1480
|
+
def candidate_worktree_issues(root, cfg, candidate=None, inputs="declared"):
|
|
1481
|
+
"""State that would make gates execute bytes other than the staged candidate.
|
|
1482
|
+
|
|
1483
|
+
Only a dirty path that is part of the candidate or that a gate reads refuses (#16).
|
|
1484
|
+
On 2026-09-06 seven untracked files outside the slice withheld commit authority
|
|
1485
|
+
until a person moved them. A path no gate reads is listed as `worktree_noise`,
|
|
1486
|
+
never fatal; while any gate declares no inputs, every dirty path counts.
|
|
1487
|
+
A candidate that holds only coordination paths shares no product commit, so its
|
|
1488
|
+
staged coordination paths are not a product-isolation issue (COORDINATION-COMMIT).
|
|
1489
|
+
"""
|
|
1490
|
+
candidate = candidate or index_candidate(root)
|
|
1491
|
+
if inputs == "declared":
|
|
1492
|
+
inputs = gate_inputs(root)
|
|
1493
|
+
unstaged = {
|
|
1494
|
+
os.fsdecode(raw)
|
|
1495
|
+
for raw in _git_output(
|
|
1496
|
+
root, "diff", "--name-only", "-z", "--no-renames", "--"
|
|
1497
|
+
).split(b"\0")
|
|
1498
|
+
if raw and not _is_coordination_path(os.fsdecode(raw), cfg)
|
|
1499
|
+
}
|
|
1500
|
+
untracked = {
|
|
1501
|
+
os.fsdecode(raw)
|
|
1502
|
+
for raw in _git_output(
|
|
1503
|
+
root, "ls-files", "--others", "--exclude-standard", "-z", "--"
|
|
1504
|
+
).split(b"\0")
|
|
1505
|
+
if raw and not _is_coordination_path(os.fsdecode(raw), cfg)
|
|
1506
|
+
}
|
|
1507
|
+
coordination = set() if coordination_candidate(candidate, cfg) else {
|
|
1508
|
+
path for path in candidate["changed_paths"] if _is_coordination_path(path, cfg)
|
|
1509
|
+
}
|
|
1510
|
+
if inputs is None:
|
|
1511
|
+
noise = set()
|
|
1512
|
+
else:
|
|
1513
|
+
import fnmatch
|
|
1514
|
+
mine = set(candidate["changed_paths"])
|
|
1515
|
+
noise = {path for path in unstaged | untracked
|
|
1516
|
+
if path not in mine and not any(fnmatch.fnmatchcase(path, glob) for glob in inputs)}
|
|
1517
|
+
return {
|
|
1518
|
+
"unstaged": sorted(unstaged - noise, key=os.fsencode),
|
|
1519
|
+
"untracked": sorted(untracked - noise, key=os.fsencode),
|
|
1520
|
+
"staged_coordination": sorted(coordination, key=os.fsencode),
|
|
1521
|
+
"worktree_noise": sorted(noise, key=os.fsencode),
|
|
1522
|
+
}
|
|
1523
|
+
|
|
1524
|
+
|
|
1525
|
+
def candidate_issue_messages(issues):
|
|
1526
|
+
labels = (
|
|
1527
|
+
("unstaged", "unstaged product changes differ from the index"),
|
|
1528
|
+
("untracked", "untracked product files are outside the index"),
|
|
1529
|
+
("staged_coordination", "coordination paths must not share a product commit"),
|
|
1530
|
+
)
|
|
1531
|
+
return [f"{label}: {', '.join(issues[key])}" for key, label in labels
|
|
1532
|
+
if issues.get(key)]
|
|
1533
|
+
|
|
1534
|
+
|
|
1535
|
+
def review_evidence(body):
|
|
1536
|
+
"""Structured evidence embedded in a human-readable review artifact."""
|
|
1537
|
+
for line in str(body or "").splitlines():
|
|
1538
|
+
if line.startswith(REVIEW_EVIDENCE_PREFIX) and line.endswith(" -->"):
|
|
1539
|
+
try:
|
|
1540
|
+
value = json.loads(line[len(REVIEW_EVIDENCE_PREFIX):-4])
|
|
1541
|
+
except (TypeError, ValueError):
|
|
1542
|
+
return None
|
|
1543
|
+
return value if isinstance(value, dict) else None
|
|
1544
|
+
return None
|
|
1545
|
+
|
|
1546
|
+
|
|
1547
|
+
def review_evidence_line(value):
|
|
1548
|
+
return REVIEW_EVIDENCE_PREFIX + json.dumps(
|
|
1549
|
+
value, ensure_ascii=True, sort_keys=True, separators=(",", ":")
|
|
1550
|
+
) + " -->"
|
|
1551
|
+
|
|
1552
|
+
|
|
1553
|
+
def review_header_value(value):
|
|
1554
|
+
"""One header value on one line, whatever the implementer or the config supplied (#55).
|
|
1555
|
+
|
|
1556
|
+
A review artefact's header echoes the boundary, the commit range, labels and
|
|
1557
|
+
file names. A value holding a line break, or any other character
|
|
1558
|
+
``str.splitlines`` breaks on (``\\x1c``, ``\\x85``, ``\\u2028`` ...), would start a
|
|
1559
|
+
line of its own, and a line reading ``VERDICT: APPROVED`` there is a verdict to
|
|
1560
|
+
every reader. Such a value is written as a JSON string; a printable one as it is.
|
|
1561
|
+
"""
|
|
1562
|
+
text = str(value)
|
|
1563
|
+
return text if text.isprintable() else json.dumps(text, ensure_ascii=True)
|
|
1564
|
+
|
|
1565
|
+
|
|
1566
|
+
REVIEWER_OUTPUT_HEADING = "## Reviewer output, verbatim"
|
|
1567
|
+
REVIEWER_OUTPUT_INDENT = " "
|
|
1568
|
+
|
|
1569
|
+
|
|
1570
|
+
def review_verbatim_lines(text):
|
|
1571
|
+
"""The reviewer's own output for the artefact, below polyctl's adjudication (#54).
|
|
1572
|
+
|
|
1573
|
+
Indented, so none of its lines starts at the margin, where the verdict and the
|
|
1574
|
+
evidence line are read. It is split with the ``splitlines`` those readers use,
|
|
1575
|
+
so a separator inside a line cannot lift the rest of it back to the margin.
|
|
1576
|
+
"""
|
|
1577
|
+
return ["", REVIEWER_OUTPUT_HEADING, ""] + [
|
|
1578
|
+
REVIEWER_OUTPUT_INDENT + line if line else ""
|
|
1579
|
+
for line in str(text or "").splitlines()
|
|
1580
|
+
]
|
|
1581
|
+
|
|
1582
|
+
|
|
1583
|
+
def candidate_review_integrity(root, candidate, evidence):
|
|
1584
|
+
"""Return the canonical reviewed scope and any exact-candidate refusals."""
|
|
1585
|
+
reasons = []
|
|
1586
|
+
if not isinstance(evidence, dict):
|
|
1587
|
+
return None, ["review evidence is not a structured object"]
|
|
1588
|
+
if evidence.get("candidate") != candidate:
|
|
1589
|
+
reasons.append(
|
|
1590
|
+
"review evidence candidate does not exactly match the current index candidate"
|
|
1591
|
+
)
|
|
1592
|
+
|
|
1593
|
+
recorded_scope = evidence.get("scope")
|
|
1594
|
+
if not isinstance(recorded_scope, dict):
|
|
1595
|
+
reasons.append("review evidence has no structured candidate scope")
|
|
1596
|
+
return None, reasons
|
|
1597
|
+
paths = recorded_scope.get("paths")
|
|
1598
|
+
if not isinstance(paths, list):
|
|
1599
|
+
reasons.append("review evidence candidate scope paths must be a list")
|
|
1600
|
+
return None, reasons
|
|
1601
|
+
try:
|
|
1602
|
+
scope = candidate_scope(candidate, paths)
|
|
1603
|
+
except (KeyError, TypeError, ValueError, UnicodeError) as exc:
|
|
1604
|
+
reasons.append(f"review evidence has an invalid candidate scope: {exc}")
|
|
1605
|
+
return None, reasons
|
|
1606
|
+
|
|
1607
|
+
if scope["outside_paths"]:
|
|
1608
|
+
reasons.append(
|
|
1609
|
+
"review evidence scope excludes staged paths: "
|
|
1610
|
+
+ ", ".join(scope["outside_paths"])
|
|
1611
|
+
)
|
|
1612
|
+
if recorded_scope != scope:
|
|
1613
|
+
reasons.append(
|
|
1614
|
+
"review evidence scope does not exactly match the current candidate"
|
|
1615
|
+
)
|
|
1616
|
+
|
|
1617
|
+
try:
|
|
1618
|
+
diff_digest = "sha256:" + hashlib.sha256(
|
|
1619
|
+
candidate_diff(root, candidate, scope)
|
|
1620
|
+
).hexdigest()
|
|
1621
|
+
except (KeyError, OSError, RuntimeError, TypeError, ValueError, UnicodeError) as exc:
|
|
1622
|
+
reasons.append(f"review evidence candidate diff cannot be reproduced: {exc}")
|
|
1623
|
+
else:
|
|
1624
|
+
if evidence.get("diff_digest") != diff_digest:
|
|
1625
|
+
reasons.append(
|
|
1626
|
+
"review evidence diff digest does not match the exact candidate diff: "
|
|
1627
|
+
f"expected {diff_digest}, got {evidence.get('diff_digest') or '<missing>'}"
|
|
1628
|
+
)
|
|
1629
|
+
return scope, reasons
|
|
1630
|
+
|
|
1631
|
+
|
|
1632
|
+
# ---- a boundary's criteria, each with a verdict of its own (CRITERIA-VERDICTS) ---------
|
|
1633
|
+
|
|
1634
|
+
# The line a reviewer gives one criterion, spelled the same in every language because polyctl reads it back:
|
|
1635
|
+
# `CRITERION <n>: MET` or `CRITERION <n>: NOT MET`, then its evidence. A list bullet and bold are allowed.
|
|
1636
|
+
CRITERION_ANSWER = re.compile(r"""
|
|
1637
|
+
(?:[-*][ \t]+)? # a list bullet
|
|
1638
|
+
(?:\*\*)?CRITERION[ \t]+(\d{1,3})[ \t]*:(?:\*\*)?[ \t]*
|
|
1639
|
+
(?:\*\*)?(NOT[ \t]+MET|MET)(?:\*\*)?(?!\w)
|
|
1640
|
+
[ \t]*[—–:-]*[ \t]*(.*) # the evidence, after a dash or a colon
|
|
1641
|
+
""", re.I | re.X)
|
|
1642
|
+
CRITERION_EVIDENCE_CHARS = 300
|
|
1643
|
+
CRITERION_UNSUPPORTED = "it was said to be met with no evidence"
|
|
1644
|
+
|
|
1645
|
+
|
|
1646
|
+
def criterion_verdicts(criteria, answers):
|
|
1647
|
+
"""Each criterion with what a review's answers found of it: met, not met, or no verdict (None).
|
|
1648
|
+
|
|
1649
|
+
`answers` are the reviewer's own words: a review's one answer, or each of its
|
|
1650
|
+
sections'. A criterion's line counts only at the margin, where the verdict and the
|
|
1651
|
+
counts are read, so an indented line - a quotation, an example - decides nothing. A
|
|
1652
|
+
MET line that gives no evidence is no verdict, since the evidence is what the line is
|
|
1653
|
+
for, and the record says so. Across the sections of one review a criterion is met
|
|
1654
|
+
when a section judged it and none found it not met: a scenario's section judges its
|
|
1655
|
+
own, and one section's NOT MET stands however many others found it met.
|
|
1656
|
+
"""
|
|
1657
|
+
from .verdicts import CriterionVerdict
|
|
1658
|
+
said = {str(criterion.get("id")): [] for criterion in criteria}
|
|
1659
|
+
for answer in answers:
|
|
1660
|
+
for line in str(answer or "").splitlines():
|
|
1661
|
+
found = None if line[:1].isspace() else CRITERION_ANSWER.fullmatch(line.rstrip())
|
|
1662
|
+
if not found or str(int(found.group(1))) not in said:
|
|
1663
|
+
continue
|
|
1664
|
+
evidence = found.group(3).strip()[:CRITERION_EVIDENCE_CHARS]
|
|
1665
|
+
if found.group(2).upper() != "MET":
|
|
1666
|
+
verdict = CriterionVerdict.NOT_MET.value
|
|
1667
|
+
elif evidence:
|
|
1668
|
+
verdict = CriterionVerdict.MET.value
|
|
1669
|
+
else:
|
|
1670
|
+
verdict, evidence = None, CRITERION_UNSUPPORTED
|
|
1671
|
+
said[str(int(found.group(1)))].append((verdict, evidence))
|
|
1672
|
+
# Not met outranks met, and met outranks a line that was no verdict; among equals the first line said stands.
|
|
1673
|
+
rank = (CriterionVerdict.NOT_MET.value, CriterionVerdict.MET.value, None)
|
|
1674
|
+
out = []
|
|
1675
|
+
for criterion in criteria:
|
|
1676
|
+
heard = sorted(said[str(criterion.get("id"))], key=lambda entry: rank.index(entry[0]))
|
|
1677
|
+
verdict, evidence = heard[0] if heard else (None, "")
|
|
1678
|
+
out.append({"id": criterion.get("id"), "text": criterion.get("text"), "verdict": verdict,
|
|
1679
|
+
"evidence": evidence})
|
|
1680
|
+
return out
|
|
1681
|
+
|
|
1682
|
+
|
|
1683
|
+
def criteria_refusals(evidence):
|
|
1684
|
+
"""Each criterion of a review that keeps it from authorising, named: not met, or with no verdict.
|
|
1685
|
+
|
|
1686
|
+
What the review recorded is read, never worked out again from the boundary, which
|
|
1687
|
+
may have moved since. A review of a boundary that lists no criteria records none,
|
|
1688
|
+
and nothing is refused here: a single sentence grants as it always did.
|
|
1689
|
+
"""
|
|
1690
|
+
from .verdicts import CriterionVerdict
|
|
1691
|
+
criteria = evidence.get("criteria") if isinstance(evidence, dict) else None
|
|
1692
|
+
if criteria is None:
|
|
1693
|
+
return []
|
|
1694
|
+
if not isinstance(criteria, list) or not all(isinstance(criterion, dict) for criterion in criteria):
|
|
1695
|
+
return ["review evidence records criteria that are not a list of criteria"]
|
|
1696
|
+
out = []
|
|
1697
|
+
for criterion in criteria:
|
|
1698
|
+
verdict = criterion.get("verdict")
|
|
1699
|
+
if verdict == CriterionVerdict.MET.value:
|
|
1700
|
+
continue
|
|
1701
|
+
state = "is not met" if verdict == CriterionVerdict.NOT_MET.value else "has no verdict"
|
|
1702
|
+
why = f" — {criterion['evidence']}" if criterion.get("evidence") else ""
|
|
1703
|
+
out.append(review_header_value(f"criterion {criterion.get('id')} {state}: {criterion.get('text')}{why}"))
|
|
1704
|
+
return out
|
|
1705
|
+
|
|
1706
|
+
|
|
1707
|
+
def review_criteria_lines(criteria):
|
|
1708
|
+
"""The artefact's header line for each criterion: its number and words, its verdict, the reviewer's evidence."""
|
|
1709
|
+
return [f"- criterion {criterion['id']} ({review_header_value(criterion['text'])}): "
|
|
1710
|
+
+ review_header_value((criterion["verdict"] or "no verdict")
|
|
1711
|
+
+ (f" — {criterion['evidence']}" if criterion["evidence"] else ""))
|
|
1712
|
+
for criterion in criteria or []]
|
|
1713
|
+
|
|
1714
|
+
|
|
1715
|
+
REVIEW_CHAIN = "polyctl-review-row-v1"
|
|
1716
|
+
|
|
1717
|
+
|
|
1718
|
+
def review_requests_dir(root, key=None):
|
|
1719
|
+
"""Where a project's stand-in review requests are kept: ~/.polyctl/review-requests/<project>/, outside the tree an agent
|
|
1720
|
+
writes, named by `key` or the project's key (REVIEW-PATH-HIGHS).
|
|
1721
|
+
|
|
1722
|
+
A request binds a person's carried answer to the candidate it was made for, and holds the text the person carries
|
|
1723
|
+
to a session. In .polyctl/review-requests/ both were the implementer's to rewrite: a `candidate` turned to bytes it
|
|
1724
|
+
staged after had a person's genuine approval recorded for bytes no session was shown, emptied `criteria` let it
|
|
1725
|
+
land past a criterion the session found not met, and a text changed while a person copied it had the session judge
|
|
1726
|
+
another diff than the one polyctl bound.
|
|
1727
|
+
"""
|
|
1728
|
+
return os.path.join(HOME, ".polyctl", "review-requests", key or project_key(root))
|
|
1729
|
+
|
|
1730
|
+
|
|
1731
|
+
def tree_review_request(root, nonce):
|
|
1732
|
+
"""Whether the tree holds a request by this nonce where polyctl kept them before REVIEW-PATH-HIGHS; one found there is
|
|
1733
|
+
named, never read."""
|
|
1734
|
+
return bool(re.fullmatch(r"[0-9a-f]{32}", str(nonce or ""))) and os.path.lexists(
|
|
1735
|
+
os.path.join(root, ".polyctl", "review-requests", f"{nonce}.json"))
|
|
1736
|
+
|
|
1737
|
+
|
|
1738
|
+
STANDIN_LIMITS = (
|
|
1739
|
+
"polyctl cannot verify which model wrote this answer; it records the model the person declared",
|
|
1740
|
+
"a same-user actor could have written the answer; the nonce binds it to one candidate, nothing more",
|
|
1741
|
+
)
|
|
1742
|
+
|
|
1743
|
+
|
|
1744
|
+
def write_review_request(root, cfg, candidate, scope, diff_digest, boundary, slice_id, paths, prompt,
|
|
1745
|
+
criteria=None, threat_model=None, boundary_file=None):
|
|
1746
|
+
"""A review request a person can carry to a session polyctl cannot reach (#75).
|
|
1747
|
+
|
|
1748
|
+
Written when no reviewer could be reached for a staged candidate: the prompt the
|
|
1749
|
+
reviewer would have received - as `polyctl review` hands it here, without the note about
|
|
1750
|
+
a tree the session a person carries it to does not hold (REVIEW-TREE-2) - and a
|
|
1751
|
+
nonce the answer must lead with, asked for in the project's language
|
|
1752
|
+
(LANGUAGE-PROMPTS). The metadata beside it binds the request to that candidate, and
|
|
1753
|
+
keeps the criteria the prompt asks about, if any: the answer is read against those
|
|
1754
|
+
when it is collected, although the boundary kept beside them is only a boundary
|
|
1755
|
+
file's name (CRITERIA-VERDICTS).
|
|
1756
|
+
|
|
1757
|
+
Both are kept outside the tree (review_requests_dir), and the metadata holds the digest of the text: a collect
|
|
1758
|
+
reads the binding from there alone, and the text a person carries is the one polyctl wrote (REVIEW-PATH-HIGHS).
|
|
1759
|
+
"""
|
|
1760
|
+
import secrets
|
|
1761
|
+
from .storage import replace_file_durably
|
|
1762
|
+
nonce = secrets.token_hex(16)
|
|
1763
|
+
directory = review_requests_dir(root)
|
|
1764
|
+
text = (f"# polyctl review request {nonce}\n\n"
|
|
1765
|
+
"No reviewer could be reached for the staged candidate below. Paste everything\n"
|
|
1766
|
+
"under the line into a session running a different model family from the\n"
|
|
1767
|
+
"implementer's, save its whole answer to a file, and then a person runs:\n\n"
|
|
1768
|
+
f" polyctl collect-review {nonce} --response <file> --model <the model that answered> --by <your name>\n\n"
|
|
1769
|
+
f"The request binds to candidate `{candidate['digest']}`; if the staged bytes change,\n"
|
|
1770
|
+
"it no longer applies.\n\n---\n\n"
|
|
1771
|
+
+ language.text(cfg, "prompt.review-request", nonce=nonce) + f"\n\n{prompt}\n").encode(UTF8)
|
|
1772
|
+
meta = {"nonce": nonce, "at": int(time.time()), "candidate": candidate["digest"],
|
|
1773
|
+
"index_tree": candidate["index_tree"], "scope": scope, "diff_digest": diff_digest,
|
|
1774
|
+
"boundary": boundary, "slice": slice_id, "paths": paths, "collected": None,
|
|
1775
|
+
"text": "sha256:" + hashlib.sha256(text).hexdigest()}
|
|
1776
|
+
if boundary_file:
|
|
1777
|
+
meta["boundary_file"] = boundary_file
|
|
1778
|
+
if criteria:
|
|
1779
|
+
meta["criteria"] = criteria
|
|
1780
|
+
if threat_model:
|
|
1781
|
+
meta["threat_model"] = threat_model # the one its prompt carries, which an answer is judged under
|
|
1782
|
+
path = os.path.join(directory, f"{nonce}.md")
|
|
1783
|
+
replace_file_durably(os.path.join(directory, f"{nonce}.json"),
|
|
1784
|
+
json.dumps(meta, indent=1, sort_keys=True).encode(UTF8))
|
|
1785
|
+
replace_file_durably(path, text)
|
|
1786
|
+
return dict(meta, path=path)
|
|
1787
|
+
|
|
1788
|
+
|
|
1789
|
+
def review_request(root, nonce):
|
|
1790
|
+
"""A request's metadata by its nonce, or None."""
|
|
1791
|
+
if not re.fullmatch(r"[0-9a-f]{32}", str(nonce or "")):
|
|
1792
|
+
return None
|
|
1793
|
+
try:
|
|
1794
|
+
with open(os.path.join(review_requests_dir(root), f"{nonce}.json"), encoding=UTF8) as fh:
|
|
1795
|
+
data = json.load(fh)
|
|
1796
|
+
except (OSError, ValueError):
|
|
1797
|
+
return None
|
|
1798
|
+
return data if isinstance(data, dict) and data.get("nonce") == nonce else None
|
|
1799
|
+
|
|
1800
|
+
|
|
1801
|
+
def mark_review_request_collected(root, nonce, artefact, by):
|
|
1802
|
+
"""A request answers once: record which artefact its answer became and who carried it."""
|
|
1803
|
+
from .storage import replace_file_durably
|
|
1804
|
+
meta = review_request(root, nonce)
|
|
1805
|
+
if meta is None:
|
|
1806
|
+
return None
|
|
1807
|
+
meta["collected"] = {"at": int(time.time()), "artefact": artefact, "by": by}
|
|
1808
|
+
replace_file_durably(os.path.join(review_requests_dir(root), f"{nonce}.json"),
|
|
1809
|
+
json.dumps(meta, indent=1, sort_keys=True).encode(UTF8))
|
|
1810
|
+
return meta
|
|
1811
|
+
|
|
1812
|
+
|
|
1813
|
+
def review_ledger_path(root):
|
|
1814
|
+
return os.path.join(root, ".polyctl", "ledger", "reviews.jsonl")
|
|
1815
|
+
|
|
1816
|
+
|
|
1817
|
+
def review_artefact_name(root, reviews_dir, head):
|
|
1818
|
+
"""A review artefact name no earlier review has, so no record points at a rewritten file."""
|
|
1819
|
+
stem = f"{datetime.now():%Y-%m-%d-%H%M%S}-{head}"
|
|
1820
|
+
name, n = f"{stem}.md", 2
|
|
1821
|
+
while os.path.lexists(os.path.join(root, reviews_dir, name)):
|
|
1822
|
+
name, n = f"{stem}-{n}.md", n + 1
|
|
1823
|
+
return name
|
|
1824
|
+
|
|
1825
|
+
|
|
1826
|
+
def record_review(root, name, data, evidence, verdict, reviewer=None, fallback=False):
|
|
1827
|
+
"""Append one review to the chained review ledger: which file, which bytes, what it decided (#63)."""
|
|
1828
|
+
from .storage import append_chained_jsonl
|
|
1829
|
+
evidence = evidence if isinstance(evidence, dict) else {}
|
|
1830
|
+
candidate = evidence.get("candidate") if isinstance(evidence.get("candidate"), dict) else {}
|
|
1831
|
+
row = {
|
|
1832
|
+
"at": int(time.time()),
|
|
1833
|
+
"artefact": name,
|
|
1834
|
+
"sha256": "sha256:" + hashlib.sha256(data).hexdigest(),
|
|
1835
|
+
"kind": evidence.get("kind"),
|
|
1836
|
+
"candidate": candidate.get("digest"),
|
|
1837
|
+
"verdict": verdict,
|
|
1838
|
+
"authorizable": evidence.get("authorizable") is True,
|
|
1839
|
+
"fallback": bool(fallback),
|
|
1840
|
+
"reviewer": reviewer,
|
|
1841
|
+
"slice": evidence.get("slice"),
|
|
1842
|
+
}
|
|
1843
|
+
if row["kind"] == "commit-range":
|
|
1844
|
+
row["commits"] = evidence.get("commits")
|
|
1845
|
+
if evidence.get("author") is not None:
|
|
1846
|
+
# Whose range a catch-up reviewed it as, so its waiver closes on its own review (CATCHUP-READY-2).
|
|
1847
|
+
row["author"] = evidence["author"]
|
|
1848
|
+
if evidence.get("review_tier"):
|
|
1849
|
+
# The tier the review stands in, so a grant, `polyctl reviews` and `polyctl stats` label it (REVIEW-TIERS).
|
|
1850
|
+
row["tier"] = evidence["review_tier"]
|
|
1851
|
+
if evidence.get("nonce"):
|
|
1852
|
+
# The request a carried answer came back for, so a collect cut off before it marked the request finds
|
|
1853
|
+
# the review it already recorded (JOURNAL-7).
|
|
1854
|
+
row["nonce"] = evidence["nonce"]
|
|
1855
|
+
return append_chained_jsonl(review_ledger_path(root), row, REVIEW_CHAIN)
|
|
1856
|
+
|
|
1857
|
+
|
|
1858
|
+
def write_review_artefact(root, reviews_dir, name, text, *, evidence, verdict,
|
|
1859
|
+
reviewer=None, fallback=False):
|
|
1860
|
+
"""Record a review, then write exactly the recorded bytes, whole (#63, #65).
|
|
1861
|
+
|
|
1862
|
+
The row comes first. A write that dies after it leaves a newest review that
|
|
1863
|
+
cannot be read, and that refuses; written first, a file whose row was never
|
|
1864
|
+
appended left the older recorded approval of the candidate deciding (audit).
|
|
1865
|
+
|
|
1866
|
+
Returns the row as the ledger holds it, so the caller knows which review is its own: one found by
|
|
1867
|
+
counting the rows before it could be a review of the same bytes that ran beside it (LEADS-REVIEW).
|
|
1868
|
+
"""
|
|
1869
|
+
from .storage import replace_file_durably
|
|
1870
|
+
directory = os.path.join(root, reviews_dir)
|
|
1871
|
+
os.makedirs(directory, exist_ok=True)
|
|
1872
|
+
data = scan_evidence(text)[0].encode(UTF8) # scanned before it is recorded or written (#48)
|
|
1873
|
+
row = record_review(root, name, data, evidence, verdict, reviewer=reviewer, fallback=fallback)
|
|
1874
|
+
replace_file_durably(os.path.join(directory, name), data)
|
|
1875
|
+
return row
|
|
1876
|
+
|
|
1877
|
+
|
|
1878
|
+
# ---- review artefacts: kept while anything rests on them, pruned by age (#38) ----------
|
|
1879
|
+
|
|
1880
|
+
# Files whose text names the review artefacts they rest on, and what each one is.
|
|
1881
|
+
REVIEW_REFERENCE_FILES = (
|
|
1882
|
+
("grant", (".polyctl", "ledger", "authority.jsonl")),
|
|
1883
|
+
("verification", (".polyctl", "ledger", "verifications.jsonl")),
|
|
1884
|
+
("board", (".polyctl", "board.md")),
|
|
1885
|
+
("waiver", (".polyctl", "ledger", "waivers.jsonl")),
|
|
1886
|
+
("decision", (".polyctl", "ledger", "decisions.jsonl")),
|
|
1887
|
+
)
|
|
1888
|
+
|
|
1889
|
+
|
|
1890
|
+
# ---- a merge is verified on its result, before it is made (#39) ------------------------
|
|
1891
|
+
|
|
1892
|
+
MERGE_CHAIN = "polyctl-merge-check-row-v1"
|
|
1893
|
+
|
|
1894
|
+
|
|
1895
|
+
def merge_checks_path(root):
|
|
1896
|
+
return os.path.join(root, ".polyctl", "ledger", "merges.jsonl")
|
|
1897
|
+
|
|
1898
|
+
|
|
1899
|
+
def merge_checks(root):
|
|
1900
|
+
"""Recorded runs of merge results, oldest first; raises on a broken chain."""
|
|
1901
|
+
from .storage import read_chained_jsonl
|
|
1902
|
+
return [row for row in read_chained_jsonl(merge_checks_path(root), MERGE_CHAIN) if isinstance(row, dict)]
|
|
1903
|
+
|
|
1904
|
+
|
|
1905
|
+
def record_merge_check(root, row):
|
|
1906
|
+
from .storage import append_chained_jsonl
|
|
1907
|
+
return append_chained_jsonl(merge_checks_path(root), scan_record(row), MERGE_CHAIN)
|
|
1908
|
+
|
|
1909
|
+
|
|
1910
|
+
def merge_result_tree(root, into, branch):
|
|
1911
|
+
"""(tree, conflict): the tree `git merge` would make of two commits, computed without touching a worktree.
|
|
1912
|
+
|
|
1913
|
+
RuntimeError when git cannot compute it at all (merge-tree --write-tree needs git 2.38).
|
|
1914
|
+
"""
|
|
1915
|
+
try:
|
|
1916
|
+
# In a process group of its own, as every Git query of authority's is: a merge driver the repository
|
|
1917
|
+
# configures can start a worker that holds git's pipes past its time (LEADS-GATE).
|
|
1918
|
+
result = run_as_group([git_binary(), "merge-tree", "--write-tree", "--name-only", "--no-messages",
|
|
1919
|
+
into, branch], 120, cwd=root, stdout=subprocess.PIPE, stderr=subprocess.PIPE)
|
|
1920
|
+
except (OSError, subprocess.TimeoutExpired) as exc:
|
|
1921
|
+
unasked = getattr(exc, "unasked", None)
|
|
1922
|
+
raise RuntimeError(f"cannot compute the merge: {exc}" + (f"; {unasked}" if unasked else "")) from exc
|
|
1923
|
+
lines = result.stdout.decode(UTF8, "replace").splitlines()
|
|
1924
|
+
if result.returncode == 0 and lines:
|
|
1925
|
+
return lines[0].strip(), None
|
|
1926
|
+
if result.returncode == 1 and lines:
|
|
1927
|
+
return None, "conflicts in " + ", ".join(line.strip() for line in lines[1:] if line.strip())
|
|
1928
|
+
detail = result.stderr.decode(UTF8, "replace").strip()
|
|
1929
|
+
raise RuntimeError(f"cannot compute the merge: {detail or f'git merge-tree exit {result.returncode}'}")
|
|
1930
|
+
|
|
1931
|
+
|
|
1932
|
+
def unverified_merges(root, cfg):
|
|
1933
|
+
"""(merge commit, why) for each recent merge on HEAD's first-parent line no passing run vouches for (#39).
|
|
1934
|
+
|
|
1935
|
+
A run vouches for a merge only when it names both parents and the tree the
|
|
1936
|
+
merge made, so a run of an older pair, or of a result that was changed while
|
|
1937
|
+
merging, vouches for nothing.
|
|
1938
|
+
"""
|
|
1939
|
+
days = settings.get(cfg, "merge.check_days")
|
|
1940
|
+
log = git_text(root, "log", "--merges", "--first-parent", f"--since={days}.days", "--format=%H %T %P", "HEAD")
|
|
1941
|
+
runs = {(row.get("into"), row.get("branch"), row.get("tree")): row for row in merge_checks(root)}
|
|
1942
|
+
out = []
|
|
1943
|
+
for line in log.splitlines():
|
|
1944
|
+
parts = line.split()
|
|
1945
|
+
if len(parts) < 4:
|
|
1946
|
+
continue
|
|
1947
|
+
sha, tree, first, second = parts[:4]
|
|
1948
|
+
run = runs.get((first, second, tree))
|
|
1949
|
+
if run is None:
|
|
1950
|
+
out.append((sha, "no run of its merge result was recorded"))
|
|
1951
|
+
elif run.get("passed") is not True:
|
|
1952
|
+
out.append((sha, f"the recorded run of its merge result, {run.get('id')}, failed"))
|
|
1953
|
+
else:
|
|
1954
|
+
try:
|
|
1955
|
+
spec = json.loads(_git_output(root, "show", f"{tree}:.polyctl/gates.json"))
|
|
1956
|
+
digest = gate_definitions_digest_of(spec, run.get("profile"))
|
|
1957
|
+
except (OSError, ValueError, RuntimeError, TypeError, AttributeError) as exc:
|
|
1958
|
+
out.append((sha, f"the merge's gate definitions cannot be read: {exc}; run merge-check again"))
|
|
1959
|
+
continue
|
|
1960
|
+
if not digest or run.get("gates_digest") != digest:
|
|
1961
|
+
out.append((sha, "the recorded run used different gate definitions; run merge-check again"))
|
|
1962
|
+
return out
|
|
1963
|
+
|
|
1964
|
+
|
|
1965
|
+
def _review_artefact_directory(root, reviews_dir):
|
|
1966
|
+
"""Pruning follows no directory link and never leaves the project (TRIAGE-3-MEDIUM)."""
|
|
1967
|
+
base = os.path.abspath(root)
|
|
1968
|
+
directory = os.path.abspath(os.path.join(base, reviews_dir))
|
|
1969
|
+
if not _within(directory, base) or directory == base:
|
|
1970
|
+
raise RuntimeError("review directory leaves the project; configure a directory inside it before pruning")
|
|
1971
|
+
part = directory
|
|
1972
|
+
while part != base:
|
|
1973
|
+
if os.path.islink(part):
|
|
1974
|
+
raise RuntimeError("review directory contains a link; replace it with a directory before pruning")
|
|
1975
|
+
parent = os.path.dirname(part)
|
|
1976
|
+
if parent == part:
|
|
1977
|
+
raise RuntimeError("review directory leaves the project; correct it before pruning")
|
|
1978
|
+
part = parent
|
|
1979
|
+
return directory
|
|
1980
|
+
|
|
1981
|
+
|
|
1982
|
+
def review_artefact_names(root, reviews_dir):
|
|
1983
|
+
"""The regular review files on disk, excluding links (TRIAGE-3-MEDIUM)."""
|
|
1984
|
+
import stat
|
|
1985
|
+
directory = _review_artefact_directory(root, reviews_dir)
|
|
1986
|
+
try:
|
|
1987
|
+
return sorted(name for name in os.listdir(directory)
|
|
1988
|
+
if not name.startswith(".") and stat.S_ISREG(os.lstat(os.path.join(directory, name)).st_mode))
|
|
1989
|
+
except FileNotFoundError:
|
|
1990
|
+
return []
|
|
1991
|
+
|
|
1992
|
+
|
|
1993
|
+
def tracked_review_names(root, reviews_dir):
|
|
1994
|
+
"""The review artefacts git tracks, by name; RuntimeError when git cannot say."""
|
|
1995
|
+
listed = _git_output(root, "ls-files", "-z", "--", reviews_dir)
|
|
1996
|
+
return {os.path.basename(os.fsdecode(path)) for path in listed.split(b"\0") if path}
|
|
1997
|
+
|
|
1998
|
+
|
|
1999
|
+
def review_artefact_references(root, cfg):
|
|
2000
|
+
"""{artefact: [what rests on it]} for every review artefact polyctl must keep (#38).
|
|
2001
|
+
|
|
2002
|
+
A grant, a verification, the board, a waiver or a decision that names the
|
|
2003
|
+
file; a submitted review's state; a review of a slice that is neither done nor
|
|
2004
|
+
rejected, or of the candidate staged now; and a file git tracks, which moving
|
|
2005
|
+
would turn into a deletion in the tree. The review ledger is the catalogue of
|
|
2006
|
+
every review, not a reason to keep one. Whatever cannot be read raises, so
|
|
2007
|
+
nothing is pruned on a guess.
|
|
2008
|
+
"""
|
|
2009
|
+
from .storage import read_chained_history
|
|
2010
|
+
names = review_artefact_names(root, cfg["reviews"])
|
|
2011
|
+
kept = {}
|
|
2012
|
+
|
|
2013
|
+
def keep(name, why):
|
|
2014
|
+
reasons = kept.setdefault(name, [])
|
|
2015
|
+
if why not in reasons:
|
|
2016
|
+
reasons.append(why)
|
|
2017
|
+
|
|
2018
|
+
texts = []
|
|
2019
|
+
chains = {"grant": (AUTHORITY_CHAIN, False), "verification": (VERIFICATION_CHAIN, True),
|
|
2020
|
+
"waiver": (WAIVER_CHAIN, True), "decision": (DECISION_CHAIN, True)}
|
|
2021
|
+
for why, parts in REVIEW_REFERENCE_FILES:
|
|
2022
|
+
if why in chains:
|
|
2023
|
+
chain, legacy = chains[why]
|
|
2024
|
+
rows = read_chained_history(os.path.join(root, *parts), chain, legacy_prefix=legacy)
|
|
2025
|
+
texts.append((why, json.dumps(rows, ensure_ascii=False)))
|
|
2026
|
+
continue
|
|
2027
|
+
try:
|
|
2028
|
+
with open(os.path.join(root, *parts), encoding=UTF8, errors="replace") as fh:
|
|
2029
|
+
texts.append((why, fh.read()))
|
|
2030
|
+
except FileNotFoundError:
|
|
2031
|
+
continue
|
|
2032
|
+
states = os.path.join(root, ".polyctl", "reviews")
|
|
2033
|
+
for entry in sorted(os.listdir(states)) if os.path.isdir(states) else []:
|
|
2034
|
+
if entry.startswith("R-") and entry.endswith(".json"):
|
|
2035
|
+
with open(os.path.join(states, entry), encoding=UTF8, errors="replace") as fh:
|
|
2036
|
+
texts.append(("submitted review", fh.read()))
|
|
2037
|
+
for why, text in texts:
|
|
2038
|
+
for name in names:
|
|
2039
|
+
if name in text:
|
|
2040
|
+
keep(name, why)
|
|
2041
|
+
open_slices = {item["id"] for state, items in board(root).items() if state not in ("done", "rejected")
|
|
2042
|
+
for item in items}
|
|
2043
|
+
staged = index_candidate(root)["digest"]
|
|
2044
|
+
for row in read_chained_history(review_ledger_path(root), REVIEW_CHAIN):
|
|
2045
|
+
name = row.get("artefact") if isinstance(row, dict) else None
|
|
2046
|
+
if name not in names:
|
|
2047
|
+
continue
|
|
2048
|
+
if row.get("slice") in open_slices:
|
|
2049
|
+
keep(name, "open slice")
|
|
2050
|
+
if staged and row.get("candidate") == staged:
|
|
2051
|
+
keep(name, "staged candidate")
|
|
2052
|
+
tracked = tracked_review_names(root, cfg["reviews"])
|
|
2053
|
+
for name in names:
|
|
2054
|
+
if name in tracked:
|
|
2055
|
+
keep(name, "tracked in git")
|
|
2056
|
+
return kept
|
|
2057
|
+
|
|
2058
|
+
|
|
2059
|
+
def prune_review_artefacts(root, cfg, days, apply=False, now=None):
|
|
2060
|
+
"""Move the review artefacts nothing rests on, older than `days`, out of the repository (#38).
|
|
2061
|
+
|
|
2062
|
+
Age is the later of the file's time and its ledger row's, so neither alone
|
|
2063
|
+
makes a review old. They move to ~/.polyctl/archive/<project>/, not away: a review
|
|
2064
|
+
is evidence someone may still ask for. Returns what was kept and why, how many
|
|
2065
|
+
were recent, what was moved (or would be), its bytes and where it went.
|
|
2066
|
+
"""
|
|
2067
|
+
import shutil
|
|
2068
|
+
import stat
|
|
2069
|
+
from .storage import read_chained_history
|
|
2070
|
+
now = time.time() if now is None else now
|
|
2071
|
+
kept = review_artefact_references(root, cfg)
|
|
2072
|
+
written = {}
|
|
2073
|
+
for row in read_chained_history(review_ledger_path(root), REVIEW_CHAIN):
|
|
2074
|
+
if isinstance(row, dict) and row.get("artefact"):
|
|
2075
|
+
written[row["artefact"]] = max(written.get(row["artefact"], 0), int(row.get("at") or 0))
|
|
2076
|
+
directory = os.path.join(root, cfg["reviews"])
|
|
2077
|
+
cutoff = now - days * 86400
|
|
2078
|
+
recent, moving, size = 0, [], 0
|
|
2079
|
+
for name in review_artefact_names(root, cfg["reviews"]):
|
|
2080
|
+
if name in kept:
|
|
2081
|
+
continue
|
|
2082
|
+
path = os.path.join(directory, name)
|
|
2083
|
+
if max(os.path.getmtime(path), written.get(name, 0)) >= cutoff:
|
|
2084
|
+
recent += 1
|
|
2085
|
+
else:
|
|
2086
|
+
moving.append(name)
|
|
2087
|
+
size += os.path.getsize(path)
|
|
2088
|
+
folder = f"{os.path.basename(os.path.normpath(cfg['reviews']))}-{datetime.fromtimestamp(now):%Y%m%d-%H%M%S}"
|
|
2089
|
+
archive = os.path.join(HOME, ".polyctl", "archive", project_key(root), folder)
|
|
2090
|
+
if apply and moving:
|
|
2091
|
+
os.makedirs(archive, exist_ok=True)
|
|
2092
|
+
for name in moving:
|
|
2093
|
+
# Recheck after reading the references, before each move (TRIAGE-3-MEDIUM).
|
|
2094
|
+
directory = _review_artefact_directory(root, cfg["reviews"])
|
|
2095
|
+
if not stat.S_ISREG(os.lstat(os.path.join(directory, name)).st_mode):
|
|
2096
|
+
raise RuntimeError("review artefacts changed during pruning; inspect them and retry")
|
|
2097
|
+
shutil.move(os.path.join(directory, name), os.path.join(archive, name))
|
|
2098
|
+
record_archived(root, name, archive) # where it went stays on the record (#47)
|
|
2099
|
+
return {"kept": kept, "recent": recent, "moved": moving, "bytes": size, "archive": archive}
|