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
polyctl/lib.py
ADDED
|
@@ -0,0 +1,1296 @@
|
|
|
1
|
+
"""Shared library for the polyctl reference scripts.
|
|
2
|
+
|
|
3
|
+
Standard library only, by design — see docs/surfaces.md. Nothing here writes to a
|
|
4
|
+
vendor's session store; observation is strictly read-only.
|
|
5
|
+
"""
|
|
6
|
+
import hashlib
|
|
7
|
+
import json
|
|
8
|
+
import os
|
|
9
|
+
import re
|
|
10
|
+
import subprocess
|
|
11
|
+
import sys
|
|
12
|
+
import time
|
|
13
|
+
from datetime import datetime
|
|
14
|
+
UTF8 = "utf-8" # every text file polyctl writes or reads; Windows would otherwise use cp1252
|
|
15
|
+
|
|
16
|
+
HOME = os.path.expanduser("~")
|
|
17
|
+
from . import settings # noqa: E402 (reads HOME through this module, lazily)
|
|
18
|
+
from . import language # noqa: E402 (what polyctl writes into a project, in its language; what it reads, in any)
|
|
19
|
+
# Adapters ship with the package, but the documented install is still a git
|
|
20
|
+
# clone plus an alias — both have to resolve. Look beside this module first, then
|
|
21
|
+
# at the repository root, so neither path depends on the other existing.
|
|
22
|
+
# A module split into parts keeps one namespace (#44). A part is a contiguous run of a
|
|
23
|
+
# module's own definitions, moved out byte for byte and run here, in the module's
|
|
24
|
+
# globals: every name stays where callers, tests and monkeypatches look for it, so a
|
|
25
|
+
# split moves text and never behaviour. `polyctl split-check` proves a move is only that.
|
|
26
|
+
_PARTS_DIR = os.path.join(os.path.dirname(os.path.abspath(__file__)), "parts")
|
|
27
|
+
|
|
28
|
+
|
|
29
|
+
def _parts_folder(folder, path=os.path):
|
|
30
|
+
"""Where a module in `folder` keeps its parts: parts/ beside it, or `folder` itself when it is a parts
|
|
31
|
+
folder, as a part that loads one is. `_part` runs a part from here and `polyctl split-check` takes the moved
|
|
32
|
+
definitions to be here, by this one rule, so the proof never reads a file the loader does not run
|
|
33
|
+
(SPLIT-CHECK-4)."""
|
|
34
|
+
return folder if path.basename(folder) == "parts" else path.join(folder, "parts")
|
|
35
|
+
|
|
36
|
+
|
|
37
|
+
def _part(name, namespace):
|
|
38
|
+
"""Run the part `name` in `namespace` - the globals of the module it was moved out of.
|
|
39
|
+
|
|
40
|
+
The part is read from the parts folder beside the file whose code calls this - the module, or a
|
|
41
|
+
part that loads one - as it was compiled: a module in any folder runs the file the move proof read,
|
|
42
|
+
where every call read lib.py's own parts/ (SPLIT-CHECK-4). It was read beside `namespace["__file__"]`,
|
|
43
|
+
which the module's own code - an earlier part, an import alias, `globals().update` - could bind to
|
|
44
|
+
another place than the proof read (SPLIT-CHECK-6). Only the module's own code loads its parts: a
|
|
45
|
+
caller whose globals are not `namespace` - a forwarding loader in another module - is refused, and so
|
|
46
|
+
is code compiled from no file, which read lib.py's parts/ in place of the proved one (SPLIT-CHECK-7).
|
|
47
|
+
|
|
48
|
+
Compiled through the import system's own loader, so a part's bytecode is cached like
|
|
49
|
+
any module's and a `polyctl` hook does not recompile thousands of lines on every run.
|
|
50
|
+
"""
|
|
51
|
+
from importlib.machinery import SourceFileLoader
|
|
52
|
+
frame = sys._getframe(1)
|
|
53
|
+
if frame.f_globals is not namespace:
|
|
54
|
+
raise RuntimeError(f"_part({name!r}) is called from code outside the module it loads into; a module loads "
|
|
55
|
+
"its own parts")
|
|
56
|
+
caller = frame.f_code.co_filename
|
|
57
|
+
if not caller or caller.startswith("<"):
|
|
58
|
+
raise RuntimeError(f"_part({name!r}) is called from code compiled from no file ({caller}); a part is read "
|
|
59
|
+
"beside the file that loads it")
|
|
60
|
+
folder = _parts_folder(os.path.dirname(os.path.abspath(caller)))
|
|
61
|
+
path = os.path.join(folder, f"{name}.py")
|
|
62
|
+
module = sys.modules.get(namespace.get("__name__"))
|
|
63
|
+
if type(module) is type(sys) and module.__dict__ is namespace:
|
|
64
|
+
module.__class__ = _KeepsItsLoader # what binds its loader is kept from here on (#111)
|
|
65
|
+
exec(SourceFileLoader(f"polyctl.parts.{name}", path).get_code(f"polyctl.parts.{name}"), namespace)
|
|
66
|
+
|
|
67
|
+
|
|
68
|
+
def _keeper(loader):
|
|
69
|
+
"""The class of a module whose parts `loader` loads: a name of the module that holds polyctl's lib or its loader is not
|
|
70
|
+
rebound from outside it (#111).
|
|
71
|
+
|
|
72
|
+
The move proof takes a module's loads to run polyctl's loader. Code that already landed could rebind it through an
|
|
73
|
+
expression the proof does not read as the name it binds - `globals()["A"]._part = ...`, `setattr(A, "_part", ...)`,
|
|
74
|
+
a function's `A=A` default, a module reached through `sys.modules` - and every load after that ran another loader.
|
|
75
|
+
Set or deleted on the module, however it is reached, such a name is refused, and so are the class that refuses it
|
|
76
|
+
and the module's class itself. What it refuses by is held here, not in a module's names: a check read through
|
|
77
|
+
the lib's globals was itself a name to rebind (the review of SPLIT-CHECK-12). What writes a namespace without
|
|
78
|
+
asking its module - `globals()`, `__dict__` - the proof reads instead.
|
|
79
|
+
"""
|
|
80
|
+
def keep(module, name, how):
|
|
81
|
+
held = getattr(module, name, None)
|
|
82
|
+
try:
|
|
83
|
+
# polyctl's lib is the module whose `_part` is polyctl's loader, read off the module itself: an entry in
|
|
84
|
+
# `sys.modules` can be taken away by any code that runs (the review of SPLIT-CHECK-12).
|
|
85
|
+
lib = getattr(held, "_part", None) is loader
|
|
86
|
+
except Exception: # an object that raises for a missing attribute is no module of polyctl's
|
|
87
|
+
lib = False
|
|
88
|
+
if name == "__class__" or held is loader or held is Keeper or lib:
|
|
89
|
+
raise AttributeError(f"{module.__name__}.{name} binds polyctl's loader and is not {how} from outside its "
|
|
90
|
+
"module (#111)")
|
|
91
|
+
|
|
92
|
+
class Keeper(type(sys)):
|
|
93
|
+
def __setattr__(self, name, value):
|
|
94
|
+
keep(self, name, "set")
|
|
95
|
+
super().__setattr__(name, value)
|
|
96
|
+
|
|
97
|
+
def __delattr__(self, name):
|
|
98
|
+
keep(self, name, "deleted")
|
|
99
|
+
super().__delattr__(name)
|
|
100
|
+
|
|
101
|
+
Keeper.__qualname__ = Keeper.__name__ = "_KeepsItsLoader"
|
|
102
|
+
return Keeper
|
|
103
|
+
|
|
104
|
+
|
|
105
|
+
_KeepsItsLoader = _keeper(_part)
|
|
106
|
+
|
|
107
|
+
|
|
108
|
+
_HERE = os.path.dirname(os.path.abspath(__file__))
|
|
109
|
+
REPO = os.path.dirname(os.path.dirname(_HERE))
|
|
110
|
+
|
|
111
|
+
|
|
112
|
+
def adapters_dir():
|
|
113
|
+
for cand in (os.path.join(_HERE, "adapters"), os.path.join(REPO, "adapters")):
|
|
114
|
+
if os.path.isdir(cand):
|
|
115
|
+
return cand
|
|
116
|
+
return os.path.join(_HERE, "adapters")
|
|
117
|
+
|
|
118
|
+
# ── what a person sees and types: colour, and time arguments (CLI-ROBUST) ─────
|
|
119
|
+
|
|
120
|
+
def terminal(stream=None):
|
|
121
|
+
"""Whether `stream`, stdout unless named, is a terminal that draws escape codes.
|
|
122
|
+
|
|
123
|
+
A pipe, a file or a log is none, and neither is a terminal that says it is dumb
|
|
124
|
+
(`TERM=dumb`): what polyctl writes there is read by a program, or scrolled back through,
|
|
125
|
+
so a code in it is noise.
|
|
126
|
+
"""
|
|
127
|
+
if os.environ.get("TERM") == "dumb":
|
|
128
|
+
return False
|
|
129
|
+
try:
|
|
130
|
+
return bool((sys.stdout if stream is None else stream).isatty())
|
|
131
|
+
except (AttributeError, OSError, ValueError): # no stdout at all, or a closed one
|
|
132
|
+
return False
|
|
133
|
+
|
|
134
|
+
|
|
135
|
+
def colour_enabled(stream=None):
|
|
136
|
+
"""Whether ANSI colour may be written: to a terminal, and never while NO_COLOR is set, to any value."""
|
|
137
|
+
return "NO_COLOR" not in os.environ and terminal(stream)
|
|
138
|
+
|
|
139
|
+
|
|
140
|
+
# The error handler Python's UTF-8 mode gives each standard stream.
|
|
141
|
+
UTF8_MODE_ERRORS = (("stdin", "surrogateescape"), ("stdout", "surrogateescape"), ("stderr", "backslashreplace"))
|
|
142
|
+
|
|
143
|
+
|
|
144
|
+
def utf8_streams():
|
|
145
|
+
"""Read and write the standard streams in UTF-8, as Python's UTF-8 mode does, whatever the locale (#71).
|
|
146
|
+
|
|
147
|
+
Each of polyctl's entry points calls this before anything else. Every file polyctl writes is UTF-8, and so
|
|
148
|
+
is what it prints: an MCP client, a hook, a scheduled job's log and a program reading a pipe all
|
|
149
|
+
read it as UTF-8. A default Windows install reads and writes a pipe in the ANSI code page
|
|
150
|
+
instead, and there an arrow, a box line or a Turkish letter ended the command - the MCP server
|
|
151
|
+
with it - and a body piped in as UTF-8 was read as the code page's characters. A stream already
|
|
152
|
+
in UTF-8 is left as it is. One that cannot be reconfigured keeps what it had, whatever it
|
|
153
|
+
raised: there is none (pythonw), a caller replaced it with an object that has no encoding or
|
|
154
|
+
raises for one, or it was already read from. That is no worse than before, and there is no
|
|
155
|
+
other stream to say so on; nothing here may stop polyctl from starting.
|
|
156
|
+
"""
|
|
157
|
+
import codecs
|
|
158
|
+
streams = {"stdin": sys.stdin, "stdout": sys.stdout, "stderr": sys.stderr}
|
|
159
|
+
for name, errors in UTF8_MODE_ERRORS:
|
|
160
|
+
stream = streams.get(name)
|
|
161
|
+
try:
|
|
162
|
+
if codecs.lookup(stream.encoding).name != "utf-8":
|
|
163
|
+
stream.reconfigure(encoding=UTF8, errors=errors)
|
|
164
|
+
except Exception:
|
|
165
|
+
continue
|
|
166
|
+
|
|
167
|
+
|
|
168
|
+
class _Palette(dict):
|
|
169
|
+
"""ANSI codes by name, each read as "" wherever colour is off.
|
|
170
|
+
|
|
171
|
+
Decided at every lookup rather than once at import: one process prints to a terminal,
|
|
172
|
+
to a pipe a hook reads and to the log a scheduled job keeps, and a test swaps stdout
|
|
173
|
+
under it. Every `C[...]` passes through here, so no command decides colour on its own.
|
|
174
|
+
"""
|
|
175
|
+
|
|
176
|
+
def __getitem__(self, name):
|
|
177
|
+
return dict.__getitem__(self, name) if colour_enabled() else ""
|
|
178
|
+
|
|
179
|
+
def get(self, name, default=None):
|
|
180
|
+
return self[name] if name in self else default
|
|
181
|
+
|
|
182
|
+
|
|
183
|
+
C = _Palette({
|
|
184
|
+
"reset": "\033[0m", "dim": "\033[2m", "b": "\033[1m", "green": "\033[32m",
|
|
185
|
+
"red": "\033[31m", "yellow": "\033[33m", "cyan": "\033[36m",
|
|
186
|
+
"mag": "\033[35m", "blue": "\033[34m",
|
|
187
|
+
})
|
|
188
|
+
|
|
189
|
+
TIME_UNITS = {"m": 60, "h": 3600, "d": 86400, "w": 7 * 86400}
|
|
190
|
+
TIME_FORMS = "30m, 2h, 1d, 1w, today, yesterday or a date such as 2026-09-17"
|
|
191
|
+
_TIME_NUMBER = re.compile(r"\d+(?:\.\d+)?|\.\d+") # 7, 0.5 and .5, as float() read them
|
|
192
|
+
_TIME_SPAN = re.compile(rf"({_TIME_NUMBER.pattern})([mhdw])")
|
|
193
|
+
_TIME_DATE = re.compile(r"\d{4}-\d{2}-\d{2}(?:[T ]\d{2}:\d{2}(?::\d{2})?(?:Z|[+-]\d{2}:\d{2})?)?")
|
|
194
|
+
|
|
195
|
+
|
|
196
|
+
class When:
|
|
197
|
+
"""A time a `polyctl` command was given: a span back from now, or the moment a date names.
|
|
198
|
+
|
|
199
|
+
`text` is what was typed, so a report names its window the way it was asked for.
|
|
200
|
+
Exactly one of `seconds` (a span) and `at` (an epoch) is set.
|
|
201
|
+
"""
|
|
202
|
+
|
|
203
|
+
def __init__(self, text, seconds=None, at=None):
|
|
204
|
+
self.text, self.seconds, self.at = text, seconds, at
|
|
205
|
+
|
|
206
|
+
def __str__(self):
|
|
207
|
+
return self.text
|
|
208
|
+
|
|
209
|
+
def __repr__(self):
|
|
210
|
+
return f"When({self.text!r})"
|
|
211
|
+
|
|
212
|
+
def moment(self, ahead=False, now=None):
|
|
213
|
+
"""The epoch named: a date's own, or the span back from now, or forward from it with `ahead`."""
|
|
214
|
+
if self.at is not None:
|
|
215
|
+
return self.at
|
|
216
|
+
now = time.time() if now is None else now
|
|
217
|
+
return now + self.seconds if ahead else now - self.seconds
|
|
218
|
+
|
|
219
|
+
def span(self, unit, now=None):
|
|
220
|
+
"""How far back from now this reaches, counted in `unit`, a key of TIME_UNITS."""
|
|
221
|
+
seconds = self.seconds if self.at is None else (time.time() if now is None else now) - self.at
|
|
222
|
+
return seconds / TIME_UNITS[unit]
|
|
223
|
+
|
|
224
|
+
def label(self):
|
|
225
|
+
"""How a report names the window: `last 24h` for a span, `since today` for a date."""
|
|
226
|
+
return f"last {self.text}" if self.at is None else f"since {self.text}"
|
|
227
|
+
|
|
228
|
+
|
|
229
|
+
def parse_time(text, bare=None, now=None):
|
|
230
|
+
"""What a time argument names, as a When; ValueError saying which forms it takes.
|
|
231
|
+
|
|
232
|
+
Every command reads one syntax, where there were nine: `30m`, `2h`, `1d` and `1w` are
|
|
233
|
+
spans back from now; `today` and `yesterday` the local midnight that began them;
|
|
234
|
+
`2026-09-17` or `2026-09-17T14:30` a local moment unless it carries `Z` or an offset.
|
|
235
|
+
A bare number counts in `bare`, the unit its option always took (`--days 7`,
|
|
236
|
+
`--window 24`), and is refused where the option never took one: `7` alone says
|
|
237
|
+
neither minutes nor days.
|
|
238
|
+
"""
|
|
239
|
+
if isinstance(text, When):
|
|
240
|
+
return text
|
|
241
|
+
word = str("" if text is None else text).strip()
|
|
242
|
+
span = _TIME_SPAN.fullmatch(word.lower())
|
|
243
|
+
if span:
|
|
244
|
+
return When(word, seconds=float(span.group(1)) * TIME_UNITS[span.group(2)])
|
|
245
|
+
if _TIME_NUMBER.fullmatch(word):
|
|
246
|
+
if bare:
|
|
247
|
+
return When(word, seconds=float(word) * TIME_UNITS[bare])
|
|
248
|
+
raise ValueError(f"{word} needs a unit: {word}m, {word}h or {word}d")
|
|
249
|
+
if word.lower() in ("today", "yesterday"):
|
|
250
|
+
# Calendar days, not 24 hours: across a clock change yesterday's midnight is 23 or 25 hours back.
|
|
251
|
+
day = datetime.fromtimestamp(time.time() if now is None else now).toordinal()
|
|
252
|
+
return When(word, at=datetime.fromordinal(day - (word.lower() == "yesterday")).timestamp())
|
|
253
|
+
if _TIME_DATE.fullmatch(word):
|
|
254
|
+
try:
|
|
255
|
+
return When(word, at=datetime.fromisoformat(word.replace("Z", "+00:00")).timestamp())
|
|
256
|
+
except ValueError:
|
|
257
|
+
pass # 2026-02-30 has the shape of a date and is none
|
|
258
|
+
raise ValueError(f"{word!r} is not a time: give {TIME_FORMS}")
|
|
259
|
+
|
|
260
|
+
|
|
261
|
+
def time_span(text, unit, now=None):
|
|
262
|
+
"""How far back a time argument reaches, in `unit`, a bare number counting in that unit.
|
|
263
|
+
|
|
264
|
+
ValueError for what is no time, and for a moment still ahead: a window reaching into the
|
|
265
|
+
future is no window, and `polyctl mail compact` given one would have compacted every message.
|
|
266
|
+
"""
|
|
267
|
+
when = parse_time(text, bare=unit, now=now)
|
|
268
|
+
span = when.span(unit, now=now)
|
|
269
|
+
if span < 0:
|
|
270
|
+
raise ValueError(f"{when} is in the future")
|
|
271
|
+
return span
|
|
272
|
+
|
|
273
|
+
|
|
274
|
+
def time_arg(unit=None):
|
|
275
|
+
"""The argparse type= of every time a `polyctl` option takes.
|
|
276
|
+
|
|
277
|
+
Without `unit`, a When, for an option that names a moment (`--since`, `--until`); with
|
|
278
|
+
one, the span back from now in that unit, the number `--days` and `--window` always held.
|
|
279
|
+
Anything else exits 2 naming the forms, where it used to reach a command and end in a
|
|
280
|
+
traceback.
|
|
281
|
+
"""
|
|
282
|
+
import argparse
|
|
283
|
+
|
|
284
|
+
def time_value(text):
|
|
285
|
+
try:
|
|
286
|
+
return time_span(text, unit) if unit else parse_time(text)
|
|
287
|
+
except ValueError as exc:
|
|
288
|
+
raise argparse.ArgumentTypeError(str(exc)) from None
|
|
289
|
+
|
|
290
|
+
return time_value
|
|
291
|
+
|
|
292
|
+
|
|
293
|
+
# ── config ────────────────────────────────────────────────────────────────────
|
|
294
|
+
|
|
295
|
+
def find_root(start=None):
|
|
296
|
+
"""Nearest ancestor containing .polyctl/, else the git root, else cwd.
|
|
297
|
+
|
|
298
|
+
An explicit path is taken at face value — asking for a directory and being
|
|
299
|
+
given its parent is never what the caller meant. And $HOME/.polyctl is the global
|
|
300
|
+
state directory, not a project marker, so the walk never treats home as a
|
|
301
|
+
project root.
|
|
302
|
+
"""
|
|
303
|
+
if start:
|
|
304
|
+
return os.path.abspath(os.path.expanduser(start))
|
|
305
|
+
d = os.path.abspath(os.getcwd())
|
|
306
|
+
while True:
|
|
307
|
+
if d != HOME and os.path.isdir(os.path.join(d, ".polyctl")):
|
|
308
|
+
return d
|
|
309
|
+
parent = os.path.dirname(d)
|
|
310
|
+
if parent == d:
|
|
311
|
+
break
|
|
312
|
+
d = parent
|
|
313
|
+
top = _git_text(start or os.getcwd(), "rev-parse", "--show-toplevel")
|
|
314
|
+
return top or os.path.abspath(start or os.getcwd())
|
|
315
|
+
|
|
316
|
+
|
|
317
|
+
def _has_top_level_json_key(raw, wanted):
|
|
318
|
+
"""Recognize a top-level JSON object key even when the document is truncated.
|
|
319
|
+
|
|
320
|
+
Config parse failure cannot be allowed to erase an opt-in authority boundary.
|
|
321
|
+
Scan only complete depth-one string tokens followed by ``:``; decoding each
|
|
322
|
+
token with the JSON decoder also recognizes escaped spellings such as
|
|
323
|
+
``capability\\u005fmatrix`` without mistaking nested keys or string values for
|
|
324
|
+
a top-level declaration. Invalid UTF-8 elsewhere is retained as surrogate
|
|
325
|
+
text and does not hide an ASCII key.
|
|
326
|
+
"""
|
|
327
|
+
if not isinstance(raw, (bytes, bytearray)):
|
|
328
|
+
return False
|
|
329
|
+
text = bytes(raw).decode(UTF8, "surrogateescape")
|
|
330
|
+
length = len(text)
|
|
331
|
+
index = 1 if text.startswith("\ufeff") else 0
|
|
332
|
+
while index < length and text[index].isspace():
|
|
333
|
+
index += 1
|
|
334
|
+
if index >= length or text[index] != "{":
|
|
335
|
+
return False
|
|
336
|
+
depth = 1
|
|
337
|
+
index += 1
|
|
338
|
+
while index < length and depth:
|
|
339
|
+
char = text[index]
|
|
340
|
+
if char == '"':
|
|
341
|
+
start = index
|
|
342
|
+
index += 1
|
|
343
|
+
escaped = False
|
|
344
|
+
while index < length:
|
|
345
|
+
current = text[index]
|
|
346
|
+
if escaped:
|
|
347
|
+
escaped = False
|
|
348
|
+
elif current == "\\":
|
|
349
|
+
escaped = True
|
|
350
|
+
elif current == '"':
|
|
351
|
+
index += 1
|
|
352
|
+
break
|
|
353
|
+
index += 1
|
|
354
|
+
else:
|
|
355
|
+
return False
|
|
356
|
+
if depth == 1:
|
|
357
|
+
after = index
|
|
358
|
+
while after < length and text[after].isspace():
|
|
359
|
+
after += 1
|
|
360
|
+
if after < length and text[after] == ":":
|
|
361
|
+
try:
|
|
362
|
+
key = json.loads(text[start:index])
|
|
363
|
+
except (TypeError, ValueError, UnicodeError):
|
|
364
|
+
key = None
|
|
365
|
+
if key == wanted:
|
|
366
|
+
return True
|
|
367
|
+
continue
|
|
368
|
+
if char in "[{":
|
|
369
|
+
depth += 1
|
|
370
|
+
elif char in "]}":
|
|
371
|
+
depth -= 1
|
|
372
|
+
index += 1
|
|
373
|
+
return False
|
|
374
|
+
|
|
375
|
+
|
|
376
|
+
PROJECT_CONFIG_MAX_BYTES = 1_048_576
|
|
377
|
+
PROJECT_CONFIG_MAX_CONTAINER_DEPTH = 64
|
|
378
|
+
|
|
379
|
+
|
|
380
|
+
def _json_container_depth_problem(raw, max_depth=PROJECT_CONFIG_MAX_CONTAINER_DEPTH):
|
|
381
|
+
"""Return a bounded lexical depth error before the recursive JSON decoder.
|
|
382
|
+
|
|
383
|
+
JSON structural characters are ASCII, so scanning bytes is sufficient and
|
|
384
|
+
avoids decoding or recursively parsing a document whose container nesting is
|
|
385
|
+
already outside the project-state contract. Braces inside strings and escaped
|
|
386
|
+
quotes do not affect depth; all other syntax validation remains json.loads's
|
|
387
|
+
job.
|
|
388
|
+
"""
|
|
389
|
+
depth = 0
|
|
390
|
+
in_string = False
|
|
391
|
+
escaped = False
|
|
392
|
+
for byte in raw:
|
|
393
|
+
if in_string:
|
|
394
|
+
if escaped:
|
|
395
|
+
escaped = False
|
|
396
|
+
elif byte == 0x5C: # backslash
|
|
397
|
+
escaped = True
|
|
398
|
+
elif byte == 0x22: # quote
|
|
399
|
+
in_string = False
|
|
400
|
+
continue
|
|
401
|
+
if byte == 0x22:
|
|
402
|
+
in_string = True
|
|
403
|
+
elif byte in (0x5B, 0x7B): # [ {
|
|
404
|
+
depth += 1
|
|
405
|
+
if depth > max_depth:
|
|
406
|
+
return (
|
|
407
|
+
f".polyctl/config.json exceeds the {max_depth}-level "
|
|
408
|
+
"container depth"
|
|
409
|
+
)
|
|
410
|
+
elif byte in (0x5D, 0x7D): # ] }
|
|
411
|
+
depth -= 1
|
|
412
|
+
return None
|
|
413
|
+
|
|
414
|
+
|
|
415
|
+
def project_config_document(root):
|
|
416
|
+
"""Read one bounded, regular, non-empty-object project config document.
|
|
417
|
+
|
|
418
|
+
The returned raw prefix is always at most PROJECT_CONFIG_MAX_BYTES. Keeping
|
|
419
|
+
the parse result and its problem together gives pre-dispatch loading and
|
|
420
|
+
commit enforcement one state table instead of two subtly different readers.
|
|
421
|
+
"""
|
|
422
|
+
import stat
|
|
423
|
+
|
|
424
|
+
path = os.path.join(root, ".polyctl", "config.json")
|
|
425
|
+
raw = b""
|
|
426
|
+
try:
|
|
427
|
+
listed = os.lstat(path)
|
|
428
|
+
except OSError as exc:
|
|
429
|
+
return {
|
|
430
|
+
"config": None,
|
|
431
|
+
"raw": raw,
|
|
432
|
+
"problem": f".polyctl/config.json is missing or unreadable ({exc})",
|
|
433
|
+
}
|
|
434
|
+
if not stat.S_ISREG(listed.st_mode):
|
|
435
|
+
return {
|
|
436
|
+
"config": None,
|
|
437
|
+
"raw": raw,
|
|
438
|
+
"problem": ".polyctl/config.json is not a regular file",
|
|
439
|
+
}
|
|
440
|
+
|
|
441
|
+
try:
|
|
442
|
+
with open(path, "rb") as fh:
|
|
443
|
+
opened = os.fstat(fh.fileno())
|
|
444
|
+
if not stat.S_ISREG(opened.st_mode) or (
|
|
445
|
+
listed.st_dev,
|
|
446
|
+
listed.st_ino,
|
|
447
|
+
) != (opened.st_dev, opened.st_ino):
|
|
448
|
+
return {
|
|
449
|
+
"config": None,
|
|
450
|
+
"raw": raw,
|
|
451
|
+
"problem": ".polyctl/config.json changed before it could be read",
|
|
452
|
+
}
|
|
453
|
+
raw = fh.read(PROJECT_CONFIG_MAX_BYTES)
|
|
454
|
+
finished = os.fstat(fh.fileno())
|
|
455
|
+
except OSError as exc:
|
|
456
|
+
return {
|
|
457
|
+
"config": None,
|
|
458
|
+
"raw": raw,
|
|
459
|
+
"problem": f".polyctl/config.json is missing or unreadable ({exc})",
|
|
460
|
+
}
|
|
461
|
+
|
|
462
|
+
if max(opened.st_size, finished.st_size) > PROJECT_CONFIG_MAX_BYTES:
|
|
463
|
+
return {
|
|
464
|
+
"config": None,
|
|
465
|
+
"raw": raw,
|
|
466
|
+
"problem": (
|
|
467
|
+
".polyctl/config.json exceeds the "
|
|
468
|
+
f"{PROJECT_CONFIG_MAX_BYTES:,}-byte limit"
|
|
469
|
+
),
|
|
470
|
+
}
|
|
471
|
+
if opened.st_size != finished.st_size or len(raw) != finished.st_size:
|
|
472
|
+
return {
|
|
473
|
+
"config": None,
|
|
474
|
+
"raw": raw,
|
|
475
|
+
"problem": ".polyctl/config.json changed while it was being read",
|
|
476
|
+
}
|
|
477
|
+
|
|
478
|
+
problem = _json_container_depth_problem(raw)
|
|
479
|
+
if problem:
|
|
480
|
+
return {"config": None, "raw": raw, "problem": problem}
|
|
481
|
+
try:
|
|
482
|
+
parsed = json.loads(raw.decode(UTF8))
|
|
483
|
+
except (UnicodeError, ValueError, RecursionError) as exc:
|
|
484
|
+
return {
|
|
485
|
+
"config": None,
|
|
486
|
+
"raw": raw,
|
|
487
|
+
"problem": f".polyctl/config.json is not readable valid JSON ({exc})",
|
|
488
|
+
}
|
|
489
|
+
if not isinstance(parsed, dict) or not parsed:
|
|
490
|
+
return {
|
|
491
|
+
"config": None,
|
|
492
|
+
"raw": raw,
|
|
493
|
+
"problem": ".polyctl/config.json must be a non-empty top-level JSON object",
|
|
494
|
+
}
|
|
495
|
+
return {"config": parsed, "raw": raw, "problem": None}
|
|
496
|
+
|
|
497
|
+
|
|
498
|
+
def load_config(root, record=True):
|
|
499
|
+
"""Load bounded project config; malformed legacy state degrades explicitly.
|
|
500
|
+
|
|
501
|
+
Missing config remains optional for discovery and ``polyctl init``. When a config
|
|
502
|
+
path exists but cannot satisfy the project-state contract, callers receive
|
|
503
|
+
defaults plus ``_config_problem`` instead of an exception or unbounded parse.
|
|
504
|
+
Enrollment enforcement consumes the same ``project_config_document`` result.
|
|
505
|
+
"""
|
|
506
|
+
p = os.path.join(root, ".polyctl", "config.json")
|
|
507
|
+
document = project_config_document(root)
|
|
508
|
+
cfg = document["config"] or {}
|
|
509
|
+
if document["problem"] is not None and os.path.lexists(p):
|
|
510
|
+
cfg["_config_problem"] = document["problem"]
|
|
511
|
+
# Legacy malformed config has historically degraded to discovery. Once
|
|
512
|
+
# the strict key is present, however, a parse failure must not erase the
|
|
513
|
+
# opt-in and silently reactivate legacy authority. ``raw`` is bounded.
|
|
514
|
+
if _has_top_level_json_key(document["raw"], "capability_matrix"):
|
|
515
|
+
cfg["_capability_matrix_error"] = True
|
|
516
|
+
cfg.setdefault("root", root)
|
|
517
|
+
cfg.setdefault("mailbox", "agent-mail")
|
|
518
|
+
cfg.setdefault("reviews", "semantic-review")
|
|
519
|
+
resolve_roles(root, cfg)
|
|
520
|
+
if "implementer" not in cfg:
|
|
521
|
+
architect = cfg.get("architect") if isinstance(cfg.get("architect"), dict) else {}
|
|
522
|
+
pinned = _concrete_session(architect.get("session"))
|
|
523
|
+
found = discover_session(root, exclude={pinned} if pinned else ())
|
|
524
|
+
if found:
|
|
525
|
+
# Beside an architect on the same harness, the newest session may be the architect's own.
|
|
526
|
+
beside = bool(architect) and block_adapter(architect) == found["adapter"]
|
|
527
|
+
found["_session"] = {"how": "discovered", "trusted": not beside, "count": None,
|
|
528
|
+
"why": "no implementer is configured: the newest session for this workspace"
|
|
529
|
+
+ (", where the architect's are kept too: read, but not resumed until an "
|
|
530
|
+
"implementer is configured" if beside else "")}
|
|
531
|
+
cfg["implementer"] = found
|
|
532
|
+
# `auto` names no session: each role's is resolved here, once, for every reader (SESSION-IDENTITY).
|
|
533
|
+
cfg = resolve_sessions(root, cfg, record=record)
|
|
534
|
+
# What a review or a hunt would start is judged as it was read here, before anything can put the file back
|
|
535
|
+
# (ROUTE-ARGV); noted only, so loading writes nothing.
|
|
536
|
+
return note_routes_read(cfg)
|
|
537
|
+
|
|
538
|
+
|
|
539
|
+
# ---- a split moves text, never behaviour (#44) ------------------------------------------
|
|
540
|
+
|
|
541
|
+
_PART_CALL = re.compile(r"""^(?:\w+\.)?_part\(\s*["']([\w-]+)["']\s*,\s*globals\(\)\s*\)\s*$""")
|
|
542
|
+
|
|
543
|
+
|
|
544
|
+
def top_level_statements(source, filename="<source>"):
|
|
545
|
+
"""(definitions, others, loads, order) of one Python source: {name: [text]} for each top-level def,
|
|
546
|
+
class and simple assignment, decorators included; [text] for every other top-level statement
|
|
547
|
+
except a part being loaded and a leading docstring; the name of each part a top-level
|
|
548
|
+
`_part(name, globals())` call loads, which a mention in a docstring is not (SPLIT-CHECK-2); and
|
|
549
|
+
every statement but the docstring in the order it runs, ("load", name) or ("text", text)
|
|
550
|
+
(SPLIT-CHECK-3)."""
|
|
551
|
+
import ast
|
|
552
|
+
tree = ast.parse(source, filename)
|
|
553
|
+
lines = source.splitlines(keepends=True)
|
|
554
|
+
definitions, others, loads, order = {}, [], [], []
|
|
555
|
+
for index, node in enumerate(tree.body):
|
|
556
|
+
start = min([node.lineno] + [d.lineno for d in getattr(node, "decorator_list", [])])
|
|
557
|
+
text = "".join(lines[start - 1:node.end_lineno])
|
|
558
|
+
# The call's own source, not its lines: a comment after it is no other statement (SPLIT-CHECK-3).
|
|
559
|
+
load = _PART_CALL.match(ast.get_source_segment(source, node) or "") if isinstance(node, ast.Expr) else None
|
|
560
|
+
if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)):
|
|
561
|
+
names = [node.name]
|
|
562
|
+
elif isinstance(node, ast.Assign) and all(isinstance(t, ast.Name) for t in node.targets):
|
|
563
|
+
names = [t.id for t in node.targets]
|
|
564
|
+
elif isinstance(node, ast.AnnAssign) and isinstance(node.target, ast.Name):
|
|
565
|
+
names = [node.target.id]
|
|
566
|
+
else:
|
|
567
|
+
names = []
|
|
568
|
+
if names:
|
|
569
|
+
for name in names:
|
|
570
|
+
definitions.setdefault(name, []).append(text)
|
|
571
|
+
order.append(("text", text))
|
|
572
|
+
elif load:
|
|
573
|
+
loads.append(load.group(1))
|
|
574
|
+
order.append(("load", load.group(1)))
|
|
575
|
+
elif index == 0 and isinstance(node, ast.Expr) and isinstance(node.value, ast.Constant) \
|
|
576
|
+
and isinstance(node.value.value, str):
|
|
577
|
+
continue
|
|
578
|
+
else:
|
|
579
|
+
others.append(text)
|
|
580
|
+
order.append(("text", text))
|
|
581
|
+
return definitions, others, loads, order
|
|
582
|
+
|
|
583
|
+
|
|
584
|
+
# A load as a line of a module holds it: the call alone, and a comment after it, which is text of its own.
|
|
585
|
+
_PART_LOAD_LINE = re.compile(r"""^(?:\w+\.)?_part\(\s*["']([\w-]+)["']\s*,\s*globals\(\)\s*\)\s*(#.*)?$""")
|
|
586
|
+
|
|
587
|
+
|
|
588
|
+
def _folder_modules(root, rev, folder):
|
|
589
|
+
"""The Python files directly in `folder` at `rev`, the index where `rev` is empty."""
|
|
590
|
+
import posixpath
|
|
591
|
+
listing = ("ls-files", "-z", "--", f"{folder}/" if folder else ".") if not rev else \
|
|
592
|
+
("ls-tree", "--name-only", "-z", rev, "--", f"{folder}/" if folder else ".")
|
|
593
|
+
try:
|
|
594
|
+
names = _git_output(root, *listing).decode(UTF8, "replace").split("\0")
|
|
595
|
+
except RuntimeError:
|
|
596
|
+
return []
|
|
597
|
+
return [name for name in names if name.endswith(".py") and posixpath.dirname(name) == folder]
|
|
598
|
+
|
|
599
|
+
|
|
600
|
+
def _loading_modules(root, read, before, after, paths):
|
|
601
|
+
"""The modules whose text a candidate's files are: each changed file that is no part, and for a changed part the
|
|
602
|
+
module that runs it - found by its load in the folder above the parts folder or, for a part another part loads,
|
|
603
|
+
in the parts folder itself, up to the module at the top (SPLIT-DOCSTRING)."""
|
|
604
|
+
import posixpath
|
|
605
|
+
is_part = lambda path: posixpath.basename(posixpath.dirname(path)) == "parts" # noqa: E731
|
|
606
|
+
modules = {path for path in paths if not is_part(path)}
|
|
607
|
+
waiting, asked = [path for path in paths if is_part(path)], set()
|
|
608
|
+
while waiting:
|
|
609
|
+
path = waiting.pop()
|
|
610
|
+
if path in asked:
|
|
611
|
+
continue
|
|
612
|
+
asked.add(path)
|
|
613
|
+
folder = posixpath.dirname(path)
|
|
614
|
+
name = posixpath.splitext(posixpath.basename(path))[0]
|
|
615
|
+
for rev in (before, after):
|
|
616
|
+
for candidate in _folder_modules(root, rev, posixpath.dirname(folder)) + \
|
|
617
|
+
_folder_modules(root, rev, folder):
|
|
618
|
+
text = read(f"{rev}:{candidate}") or ""
|
|
619
|
+
if candidate != path and any(_PART_LOAD_LINE.match(line) and
|
|
620
|
+
_PART_LOAD_LINE.match(line).group(1) == name
|
|
621
|
+
for line in text.splitlines()):
|
|
622
|
+
(waiting.append if is_part(candidate) else modules.add)(candidate)
|
|
623
|
+
return modules
|
|
624
|
+
|
|
625
|
+
|
|
626
|
+
def _inlined_lines(read, rev, path, seen=()):
|
|
627
|
+
"""The lines of `path` at `rev` as its module runs them, each part it loads read in place of its load and every
|
|
628
|
+
blank line left out; None where the file is not there (SPLIT-DOCSTRING).
|
|
629
|
+
|
|
630
|
+
A pure move leaves this text as it was: a definition moved into a part comes back where its load stands, with the
|
|
631
|
+
comments beside it, and anything else - a module's docstring, a comment added, dropped or carried elsewhere, a
|
|
632
|
+
docstring a new part brings - is a line that differs. A module's text is read whole, as the reader of the code
|
|
633
|
+
is handed it, where comparing its statements set the rest aside.
|
|
634
|
+
"""
|
|
635
|
+
text = read(f"{rev}:{path}")
|
|
636
|
+
if text is None:
|
|
637
|
+
return None
|
|
638
|
+
out = []
|
|
639
|
+
for line in text.splitlines():
|
|
640
|
+
found = _PART_LOAD_LINE.match(line)
|
|
641
|
+
part = _part_file(path, found.group(1)) if found else None
|
|
642
|
+
inner = _inlined_lines(read, rev, part, seen + (path,)) if part and part not in seen else None
|
|
643
|
+
if inner is not None:
|
|
644
|
+
out.extend(inner)
|
|
645
|
+
if found.group(2):
|
|
646
|
+
out.append(found.group(2))
|
|
647
|
+
elif line.strip():
|
|
648
|
+
out.append(line.rstrip())
|
|
649
|
+
return out
|
|
650
|
+
|
|
651
|
+
|
|
652
|
+
def _part_file(module, name):
|
|
653
|
+
"""The file `_part(name, globals())` in `module` runs: parts/<name>.py beside the module, or beside a part
|
|
654
|
+
that loads one: `_parts_folder`, the rule `_part` itself reads by (SPLIT-CHECK-4)."""
|
|
655
|
+
import posixpath
|
|
656
|
+
return posixpath.join(_parts_folder(posixpath.dirname(module), posixpath), f"{name}.py")
|
|
657
|
+
|
|
658
|
+
|
|
659
|
+
def _module_level(nodes):
|
|
660
|
+
"""The nodes of a module's own namespace: its statements and what they hold, not the bodies of its functions,
|
|
661
|
+
classes and comprehensions, which bind names of their own."""
|
|
662
|
+
import ast
|
|
663
|
+
stack = list(nodes)
|
|
664
|
+
while stack:
|
|
665
|
+
node = stack.pop()
|
|
666
|
+
yield node
|
|
667
|
+
if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef, ast.Lambda, ast.ListComp,
|
|
668
|
+
ast.SetComp, ast.DictComp, ast.GeneratorExp)):
|
|
669
|
+
continue
|
|
670
|
+
stack.extend(ast.iter_child_nodes(node))
|
|
671
|
+
|
|
672
|
+
|
|
673
|
+
def _scope_tables(top):
|
|
674
|
+
"""({(line, name): table} of each function and class body under the module's symbol table `top`, {id(table): the
|
|
675
|
+
table it is nested in}): the compiler's own reading of which names a body binds, and which it reads from the module
|
|
676
|
+
(SPLIT-CHECK-10), and where a name a body closes over is bound (SPLIT-CHECK-11)."""
|
|
677
|
+
tables, parents, stack = {}, {}, [top]
|
|
678
|
+
while stack:
|
|
679
|
+
table = stack.pop()
|
|
680
|
+
if table.get_type() in ("function", "class"):
|
|
681
|
+
tables[(table.get_lineno(), table.get_name())] = table
|
|
682
|
+
for child in table.get_children():
|
|
683
|
+
parents[id(child)] = table
|
|
684
|
+
stack.append(child)
|
|
685
|
+
return tables, parents
|
|
686
|
+
|
|
687
|
+
|
|
688
|
+
def _closure_binding(table, name, parents):
|
|
689
|
+
"""The symbol of the function body that binds `name`, which `table` closes over; None when none does: a class
|
|
690
|
+
body's names are no function's to close over (SPLIT-CHECK-11)."""
|
|
691
|
+
scope = parents.get(id(table))
|
|
692
|
+
while scope is not None and scope.get_type() != "module":
|
|
693
|
+
if scope.get_type() == "function":
|
|
694
|
+
try:
|
|
695
|
+
symbol = scope.lookup(name)
|
|
696
|
+
except KeyError:
|
|
697
|
+
symbol = None
|
|
698
|
+
if symbol is not None and not symbol.is_free() and not symbol.is_global():
|
|
699
|
+
return symbol
|
|
700
|
+
scope = parents.get(id(scope))
|
|
701
|
+
return None
|
|
702
|
+
|
|
703
|
+
|
|
704
|
+
def _class_binds_first(scope, name, write):
|
|
705
|
+
"""Whether a class body binds `name` of its own before the statement that holds `write` runs, whatever runs: a def
|
|
706
|
+
or class at its own level with no decorator or keyword, or an assignment there whose value does not read the name,
|
|
707
|
+
and no `del` of it anywhere in the body (SPLIT-CHECK-11). A class body reads the module's name until it binds its
|
|
708
|
+
own, so a write before that, or after a binding that may not run, sets the module's."""
|
|
709
|
+
import ast
|
|
710
|
+
if any(isinstance(node, ast.Name) and node.id == name and isinstance(node.ctx, ast.Del) for node in ast.walk(scope)):
|
|
711
|
+
return False
|
|
712
|
+
for statement in scope.body:
|
|
713
|
+
if any(node is write for node in ast.walk(statement)):
|
|
714
|
+
return False
|
|
715
|
+
if isinstance(statement, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)) and statement.name == name:
|
|
716
|
+
if not statement.decorator_list and not getattr(statement, "keywords", None):
|
|
717
|
+
return True
|
|
718
|
+
elif isinstance(statement, (ast.Assign, ast.AnnAssign)) and statement.value is not None:
|
|
719
|
+
targets = statement.targets if isinstance(statement, ast.Assign) else [statement.target]
|
|
720
|
+
stored = any(isinstance(node, ast.Name) and node.id == name and isinstance(node.ctx, ast.Store)
|
|
721
|
+
for target in targets for node in ast.walk(target))
|
|
722
|
+
if stored and not any(isinstance(node, ast.Name) and node.id == name for node in ast.walk(statement.value)):
|
|
723
|
+
return True
|
|
724
|
+
return False
|
|
725
|
+
|
|
726
|
+
|
|
727
|
+
def _module_walruses(tree):
|
|
728
|
+
"""The names a walrus binds in the module's own namespace: one at module level, in a comprehension there, or in a
|
|
729
|
+
default, decorator, annotation or base the module evaluates - not in a function's, a lambda's or a class's body,
|
|
730
|
+
whose walrus binds a name of its own (SPLIT-CHECK-11)."""
|
|
731
|
+
import ast
|
|
732
|
+
names, stack = set(), list(tree.body)
|
|
733
|
+
while stack:
|
|
734
|
+
node = stack.pop()
|
|
735
|
+
if isinstance(node, ast.NamedExpr):
|
|
736
|
+
names.add(node.target.id)
|
|
737
|
+
if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef, ast.Lambda)):
|
|
738
|
+
arguments = node.args
|
|
739
|
+
stack.extend(arguments.defaults + [default for default in arguments.kw_defaults if default is not None])
|
|
740
|
+
if not isinstance(node, ast.Lambda):
|
|
741
|
+
stack.extend(node.decorator_list + ([node.returns] if node.returns else []))
|
|
742
|
+
stack.extend(arg.annotation for arg in arguments.posonlyargs + arguments.args + arguments.kwonlyargs
|
|
743
|
+
+ [arg for arg in (arguments.vararg, arguments.kwarg) if arg] if arg.annotation)
|
|
744
|
+
continue
|
|
745
|
+
if isinstance(node, ast.ClassDef):
|
|
746
|
+
stack.extend(node.decorator_list + node.bases + [keyword.value for keyword in node.keywords])
|
|
747
|
+
continue
|
|
748
|
+
stack.extend(ast.iter_child_nodes(node))
|
|
749
|
+
return names
|
|
750
|
+
|
|
751
|
+
|
|
752
|
+
def _loader_names(tree):
|
|
753
|
+
"""The names a module's `_part` loads call through: `_part`, or `A` in `A._part`."""
|
|
754
|
+
import ast
|
|
755
|
+
called = set()
|
|
756
|
+
for node in ast.walk(tree):
|
|
757
|
+
if isinstance(node, ast.Call):
|
|
758
|
+
func = node.func
|
|
759
|
+
if isinstance(func, ast.Name) and func.id == "_part":
|
|
760
|
+
called.add("_part")
|
|
761
|
+
elif isinstance(func, ast.Attribute) and func.attr == "_part" and isinstance(func.value, ast.Name):
|
|
762
|
+
called.add(func.value.id)
|
|
763
|
+
return called
|
|
764
|
+
|
|
765
|
+
|
|
766
|
+
def _loader_rebound(source, path, called=None):
|
|
767
|
+
"""The names a module's `_part` loads call through - `_part`, or `A` in `A._part` - that it binds to anything but
|
|
768
|
+
polyctl's own loader (SPLIT-CHECK-7). A part runs in its module's namespace, so the names its module's loads call
|
|
769
|
+
through, `called`, are read in it as in the module's own file (#111).
|
|
770
|
+
|
|
771
|
+
The move proof takes a module's loads to run polyctl's `_part`. One that imported `_part` from a module of its own,
|
|
772
|
+
or bound `A` to one, ran a loader the proof never read. The bindings allowed are `from . import lib as A`,
|
|
773
|
+
`from polyctl import lib as A`, `import polyctl.lib as A`, `from .lib import _part`, `from polyctl.lib import _part`, and
|
|
774
|
+
polyctl's lib defining `_part` itself; a function's own variable binds nothing of the module's.
|
|
775
|
+
|
|
776
|
+
Which names a body binds is the compiler's answer, from `symtable`, not a list of the statements that bind: the
|
|
777
|
+
list missed a nested def, an `except` name, a pattern's capture, a closure's name and a walrus in a default, and
|
|
778
|
+
read a class body as a function's, where a class body reads the module's name until it binds its own
|
|
779
|
+
(SPLIT-CHECK-10).
|
|
780
|
+
"""
|
|
781
|
+
import ast
|
|
782
|
+
import symtable
|
|
783
|
+
tree = ast.parse(source)
|
|
784
|
+
called = _loader_names(tree) | set(called or ())
|
|
785
|
+
if not called:
|
|
786
|
+
return []
|
|
787
|
+
where = path.replace("\\", "/")
|
|
788
|
+
# A relative `lib` is polyctl's only in polyctl's own package: `from .lib import _part` in another package imports
|
|
789
|
+
# that package's lib (SPLIT-CHECK-8).
|
|
790
|
+
# polyctl's own package is src/polyctl itself, not a folder that ends so - vendor/src/polyctl holds another package's lib
|
|
791
|
+
# (SPLIT-CHECK-9), and the `_part` that lib defines is no loader of polyctl's (SPLIT-CHECK-10).
|
|
792
|
+
in_polyctl = where.rpartition("/")[0] == "src/polyctl"
|
|
793
|
+
own_lib = where == "src/polyctl/lib.py"
|
|
794
|
+
top = symtable.symtable(source, path, "exec")
|
|
795
|
+
rebound = set()
|
|
796
|
+
# `nonlocal` names an enclosing function's variable, never the module's.
|
|
797
|
+
for node in ast.walk(tree):
|
|
798
|
+
if isinstance(node, ast.Global):
|
|
799
|
+
rebound.update(called & set(node.names))
|
|
800
|
+
# Anything but an import that binds the name in the module's namespace - a statement, or a walrus in a default or
|
|
801
|
+
# a comprehension - binds it to something else; the compiler marks the comprehension's as declared global. polyctl's lib
|
|
802
|
+
# defining `_part` is read by its statements below, and a walrus anywhere that names `_part` there is taken for one
|
|
803
|
+
# at module level.
|
|
804
|
+
for name in called:
|
|
805
|
+
try:
|
|
806
|
+
symbol = top.lookup(name)
|
|
807
|
+
except KeyError:
|
|
808
|
+
continue
|
|
809
|
+
assigned = symbol.is_assigned() or symbol.is_declared_global()
|
|
810
|
+
if assigned and not (own_lib and name == "_part"):
|
|
811
|
+
rebound.add(name)
|
|
812
|
+
if own_lib and "_part" in _module_walruses(tree):
|
|
813
|
+
rebound.add("_part")
|
|
814
|
+
# `A._part = ...` sets the loader's attribute wherever `A` is the module's name for it. A function's own `A` - a
|
|
815
|
+
# parameter, a nested def or class, an `except` name, a capture, or one it closes over - is another object,
|
|
816
|
+
# unless an import bound it, which may be polyctl's lib; a class body reads the module's `A` until it binds its own
|
|
817
|
+
# (SPLIT-CHECK-9, SPLIT-CHECK-10). Whether an import bound it is asked of the body that binds it, where an import in
|
|
818
|
+
# any function counted for every one, and a class body's own `A` counts from the statement that surely binds it
|
|
819
|
+
# (SPLIT-CHECK-11).
|
|
820
|
+
tables, parents = _scope_tables(top)
|
|
821
|
+
scopes = [(tree, None)] + [(node, tables.get((node.lineno, node.name))) for node in ast.walk(tree)
|
|
822
|
+
if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef))]
|
|
823
|
+
for scope, table in scopes:
|
|
824
|
+
for node in _module_level(scope.body):
|
|
825
|
+
if not (isinstance(node, ast.Attribute) and node.attr == "_part" and isinstance(node.ctx, (ast.Store, ast.Del))
|
|
826
|
+
and isinstance(node.value, ast.Name) and node.value.id in called):
|
|
827
|
+
continue
|
|
828
|
+
name = node.value.id
|
|
829
|
+
try:
|
|
830
|
+
symbol = table.lookup(name) if table is not None else None
|
|
831
|
+
except KeyError:
|
|
832
|
+
symbol = None
|
|
833
|
+
if symbol is None or symbol.is_global():
|
|
834
|
+
own = False
|
|
835
|
+
elif symbol.is_free():
|
|
836
|
+
binding = _closure_binding(table, name, parents)
|
|
837
|
+
own = binding is not None and not binding.is_imported()
|
|
838
|
+
elif table.get_type() == "function":
|
|
839
|
+
own = not symbol.is_imported()
|
|
840
|
+
else:
|
|
841
|
+
own = not symbol.is_imported() and _class_binds_first(scope, name, node)
|
|
842
|
+
if not own:
|
|
843
|
+
rebound.add(name)
|
|
844
|
+
for node in _module_level(tree.body):
|
|
845
|
+
if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)):
|
|
846
|
+
if node.name in called and not (own_lib and node.name == "_part" and isinstance(node, ast.FunctionDef)):
|
|
847
|
+
rebound.add(node.name)
|
|
848
|
+
elif isinstance(node, ast.Name) and isinstance(node.ctx, (ast.Store, ast.Del)) and node.id in called:
|
|
849
|
+
rebound.add(node.id)
|
|
850
|
+
elif isinstance(node, ast.Import):
|
|
851
|
+
for alias in node.names:
|
|
852
|
+
bound = alias.asname or alias.name.split(".")[0]
|
|
853
|
+
if bound in called and not (alias.name == "polyctl.lib" and alias.asname == bound):
|
|
854
|
+
rebound.add(bound)
|
|
855
|
+
elif isinstance(node, ast.ImportFrom):
|
|
856
|
+
for alias in node.names:
|
|
857
|
+
if alias.name == "*":
|
|
858
|
+
# A star import may bind any of them from anywhere: `A` as a public name, `_part` by `__all__`.
|
|
859
|
+
rebound.update(called)
|
|
860
|
+
continue
|
|
861
|
+
bound = alias.asname or alias.name
|
|
862
|
+
ours = (((node.module, node.level) == ("polyctl", 0) or in_polyctl and (node.module, node.level) == (None, 1))
|
|
863
|
+
and alias.name == "lib"
|
|
864
|
+
or ((node.module, node.level) == ("polyctl.lib", 0) or in_polyctl and (node.module, node.level) == ("lib", 1))
|
|
865
|
+
and alias.name == "_part")
|
|
866
|
+
if bound in called and not ours:
|
|
867
|
+
rebound.add(bound)
|
|
868
|
+
elif not isinstance(node, ast.alias):
|
|
869
|
+
for value in (getattr(node, "name", None), getattr(node, "rest", None)): # `except E as A`, a capture
|
|
870
|
+
if isinstance(value, str) and value in called:
|
|
871
|
+
rebound.add(value)
|
|
872
|
+
return sorted(rebound)
|
|
873
|
+
|
|
874
|
+
|
|
875
|
+
# What reaches a module's namespace, a frame's or an object's internals other than a statement that names what it binds
|
|
876
|
+
# (#111). The files that run in a module's namespace are read as a closed world for reflection: the builtins that hand a
|
|
877
|
+
# namespace over, run code or import by a name, reached from anything; getattr and its kin by a name the proof cannot
|
|
878
|
+
# read, by one of those names, or handed on; every dunder but the few that reach nothing; the attributes that hold a
|
|
879
|
+
# namespace, a frame or a module table, or make code from bytes or run a file's lines; and the modules that import by a
|
|
880
|
+
# name, unpickle or evaluate a string.
|
|
881
|
+
_NAMESPACE_BUILTINS = ("globals", "vars", "locals", "exec", "eval", "compile", "__import__", "__builtins__",
|
|
882
|
+
"breakpoint")
|
|
883
|
+
_REFLECTION = ("getattr", "setattr", "delattr", "hasattr")
|
|
884
|
+
_NAMESPACE_ATTRIBUTES = ("f_globals", "f_locals", "f_builtins", "_getframe", "modules", "import_module",
|
|
885
|
+
"load_module", "exec_module", "CodeType", "FunctionType", "LambdaType", "addpackage",
|
|
886
|
+
"addsitedir", "load_extension", "enable_load_extension")
|
|
887
|
+
_NAMESPACE_MODULES = ("builtins", "importlib", "inspect", "ctypes", "gc", "pickle", "_pickle", "marshal", "copyreg",
|
|
888
|
+
"shelve", "runpy", "code", "codeop", "operator", "string", "typing", "dataclasses", "pydoc",
|
|
889
|
+
"pkgutil", "timeit", "doctest", "cProfile", "profile", "pdb", "bdb", "trace", "logging",
|
|
890
|
+
"unittest", "multiprocessing", "zipimport")
|
|
891
|
+
# The dunders that reach nothing: a name, the file, a constructor, an exception's links, the protocols a class defines,
|
|
892
|
+
# and the folder names that are data - the compiled copies Python keeps beside a module among them (PYTHON-ENV).
|
|
893
|
+
_PLAIN_DUNDERS = ("__name__", "__file__", "__doc__", "__init__", "__main__", "__cause__", "__context__", "__getitem__",
|
|
894
|
+
"__version__", "__qualname__", "__module__", "__all__", "__enter__", "__exit__", "__len__",
|
|
895
|
+
"__iter__", "__next__", "__contains__", "__eq__", "__hash__", "__repr__", "__str__", "__bool__",
|
|
896
|
+
"__slots__", "__tests__", "__pycache__")
|
|
897
|
+
# polyctl's loader and what keeps it reach the namespace by design, and this proof names what it looks for: each is read as
|
|
898
|
+
# the loader is, as polyctl's own code.
|
|
899
|
+
_NAMESPACE_OWN = ("_part", "_keeper", "_KeepsItsLoader", "_namespace_writes", "_compiles_a_pattern", "_internal",
|
|
900
|
+
"_NAMESPACE_BUILTINS", "_REFLECTION", "_NAMESPACE_ATTRIBUTES", "_NAMESPACE_MODULES",
|
|
901
|
+
"_PLAIN_DUNDERS")
|
|
902
|
+
|
|
903
|
+
|
|
904
|
+
def _internal(name):
|
|
905
|
+
"""Whether a name is a dunder that reaches an object's internals: every one but the few that reach nothing."""
|
|
906
|
+
return len(name) > 4 and name.startswith("__") and name.endswith("__") and name not in _PLAIN_DUNDERS
|
|
907
|
+
|
|
908
|
+
|
|
909
|
+
def _namespace_writes(source, path):
|
|
910
|
+
"""What in one file that runs in a module's namespace can bind a name there that no statement names (#111).
|
|
911
|
+
|
|
912
|
+
The move proof reads which names a statement binds. `globals()["A"] = ...`, code that `exec` or `compile` runs -
|
|
913
|
+
under any file's name - a dict reached through `__dict__`, a function's `__globals__`, a frame or `sys.modules`, or
|
|
914
|
+
the builtins reached by a name - `getattr(builtins, "globals")`, or a name built at run time - binds one no statement
|
|
915
|
+
names, so the proof cannot say the module's loads run polyctl's loader. Reflection is read as a closed world, so a name
|
|
916
|
+
computed at run time reaches nothing unread: what is refused is listed above. The `globals()` a load hands its part
|
|
917
|
+
is the namespace it loads into, no write; polyctl's own loader and what keeps it are polyctl's code.
|
|
918
|
+
|
|
919
|
+
What the proof reads is what a candidate changes and what runs where its parts load; it judges no code by what that
|
|
920
|
+
code does. Code that already landed and runs code of its own choosing by other means - writes a part's file before
|
|
921
|
+
it loads, starts a process - was reviewed when it landed, as the threat model has it; the proof is no review."""
|
|
922
|
+
import ast
|
|
923
|
+
tree = ast.parse(source)
|
|
924
|
+
skipped, calls = set(), set()
|
|
925
|
+
for node in ast.walk(tree):
|
|
926
|
+
if not isinstance(node, ast.Call):
|
|
927
|
+
continue
|
|
928
|
+
calls.add(id(node.func))
|
|
929
|
+
func = node.func
|
|
930
|
+
if (isinstance(func, ast.Name) and func.id == "_part" or isinstance(func, ast.Attribute) and func.attr == "_part") \
|
|
931
|
+
and len(node.args) == 2 and isinstance(node.args[1], ast.Call) and not node.args[1].args \
|
|
932
|
+
and isinstance(node.args[1].func, ast.Name) and node.args[1].func.id == "globals":
|
|
933
|
+
skipped.update((id(node.args[1]), id(node.args[1].func)))
|
|
934
|
+
if path.replace("\\", "/") == "src/polyctl/lib.py":
|
|
935
|
+
for node in tree.body:
|
|
936
|
+
names = [node.name] if isinstance(node, (ast.FunctionDef, ast.ClassDef)) else \
|
|
937
|
+
[target.id for target in getattr(node, "targets", []) if isinstance(target, ast.Name)]
|
|
938
|
+
if any(name in _NAMESPACE_OWN for name in names):
|
|
939
|
+
skipped.update(id(inner) for inner in ast.walk(node))
|
|
940
|
+
found = []
|
|
941
|
+
for node in ast.walk(tree):
|
|
942
|
+
if id(node) in skipped:
|
|
943
|
+
continue
|
|
944
|
+
line = getattr(node, "lineno", "?")
|
|
945
|
+
if isinstance(node, ast.Name):
|
|
946
|
+
if node.id in _NAMESPACE_BUILTINS or _internal(node.id):
|
|
947
|
+
found.append(f"`{node.id}` at line {line}")
|
|
948
|
+
elif node.id in _REFLECTION and id(node) not in calls:
|
|
949
|
+
found.append(f"`{node.id}` handed on at line {line}")
|
|
950
|
+
elif isinstance(node, ast.Attribute):
|
|
951
|
+
# on any object: `import sys as s; s.modules`, `importlib.import_module("builtins").globals()`
|
|
952
|
+
if node.attr in _NAMESPACE_ATTRIBUTES or node.attr in _REFLECTION or _internal(node.attr) \
|
|
953
|
+
or node.attr in _NAMESPACE_BUILTINS and not _compiles_a_pattern(node):
|
|
954
|
+
found.append(f"`.{node.attr}` at line {line}")
|
|
955
|
+
elif isinstance(node, ast.Constant) and isinstance(node.value, str):
|
|
956
|
+
if _internal(node.value) or node.value in _NAMESPACE_ATTRIBUTES:
|
|
957
|
+
found.append(f"`{node.value!r}` at line {line}")
|
|
958
|
+
elif isinstance(node, ast.Call) and isinstance(node.func, ast.Name) and node.func.id in _REFLECTION:
|
|
959
|
+
name = node.args[1] if len(node.args) > 1 else None
|
|
960
|
+
if not (isinstance(name, ast.Constant) and isinstance(name.value, str)):
|
|
961
|
+
found.append(f"`{node.func.id}` by a name computed at run time at line {line}")
|
|
962
|
+
elif name.value in _NAMESPACE_BUILTINS or name.value in _REFLECTION:
|
|
963
|
+
found.append(f"`{node.func.id}` of {name.value!r} at line {line}")
|
|
964
|
+
elif isinstance(node, ast.Import):
|
|
965
|
+
found.extend(f"`import {alias.name}` at line {line}" for alias in node.names
|
|
966
|
+
if alias.name.split(".")[0] in _NAMESPACE_MODULES)
|
|
967
|
+
elif isinstance(node, ast.ImportFrom):
|
|
968
|
+
top = (node.module or "").split(".")[0] if not node.level else ""
|
|
969
|
+
if top in _NAMESPACE_MODULES or any(alias.name in _NAMESPACE_BUILTINS + _REFLECTION + _NAMESPACE_ATTRIBUTES
|
|
970
|
+
or _internal(alias.name) or alias.name == "*" and top == "sys"
|
|
971
|
+
for alias in node.names):
|
|
972
|
+
found.append(f"`from {'.' * node.level}{node.module or ''} import` at line {line}")
|
|
973
|
+
return found
|
|
974
|
+
|
|
975
|
+
|
|
976
|
+
def _compiles_a_pattern(node):
|
|
977
|
+
"""Whether an attribute is `re.compile`, read off the `re` module by its name: `import builtins as re` is found by
|
|
978
|
+
its import, and `re` bound to another module by what reached it."""
|
|
979
|
+
import ast
|
|
980
|
+
base = node.value
|
|
981
|
+
return node.attr == "compile" and (isinstance(base, ast.Name) and base.id == "re"
|
|
982
|
+
or isinstance(base, ast.Attribute) and base.attr == "re")
|
|
983
|
+
|
|
984
|
+
|
|
985
|
+
# The names polyctl's loads go through, `_part` and lib's `A`: read in a file whose module the proof did not reach.
|
|
986
|
+
_LOADER_NAMES = ("_part", "A")
|
|
987
|
+
|
|
988
|
+
|
|
989
|
+
def _namespace_findings(loaders, read, touched=None):
|
|
990
|
+
"""([(path, name)] bound to something else than polyctl's loader, [(path, what)] that writes the namespace unnamed) of
|
|
991
|
+
every file that runs where a module's parts load: each module of `loaders`, {path: text}, each part it loads and
|
|
992
|
+
each part those load, as `read(path)` gives them. Touched by the candidate or not: code that already landed runs
|
|
993
|
+
there as surely as the candidate's (#111). And every file of `touched`, {path: text}, the candidate changes: a part
|
|
994
|
+
whose module the candidate leaves alone is read with the names polyctl's loads go through."""
|
|
995
|
+
import ast
|
|
996
|
+
rebound, writes, seen = [], [], set()
|
|
997
|
+
queue = [(path, text, set()) for path, text in sorted(loaders.items())]
|
|
998
|
+
queue += [(path, text, set(_LOADER_NAMES)) for path, text in sorted((touched or {}).items())
|
|
999
|
+
if path not in loaders]
|
|
1000
|
+
while queue:
|
|
1001
|
+
path, text, inherited = queue.pop(0)
|
|
1002
|
+
if path in seen or text is None:
|
|
1003
|
+
continue
|
|
1004
|
+
seen.add(path)
|
|
1005
|
+
try:
|
|
1006
|
+
tree = ast.parse(text)
|
|
1007
|
+
except SyntaxError as exc:
|
|
1008
|
+
writes.append((path, f"code that does not parse ({exc.msg})"))
|
|
1009
|
+
continue
|
|
1010
|
+
names = _loader_names(tree) | inherited
|
|
1011
|
+
rebound.extend((path, name) for name in _loader_rebound(text, path, names))
|
|
1012
|
+
writes.extend((path, what) for what in _namespace_writes(text, path))
|
|
1013
|
+
for part in top_level_statements(text, path)[2]:
|
|
1014
|
+
target = _part_file(path, part)
|
|
1015
|
+
queue.append((target, read(target), names))
|
|
1016
|
+
return rebound, writes
|
|
1017
|
+
|
|
1018
|
+
|
|
1019
|
+
def split_moves(root, start=None, end=None):
|
|
1020
|
+
"""What the staged candidate moves between Python files, and everything that is not a pure move (#44).
|
|
1021
|
+
|
|
1022
|
+
A definition moves when it leaves one file and arrives in another; it must arrive
|
|
1023
|
+
byte for byte, into a part the module it left loads with a top-level
|
|
1024
|
+
`_part(name, globals())` call: a rename, or a part another module loads, runs in
|
|
1025
|
+
another namespace (SPLIT-CHECK-2). In a candidate that moves, nothing else may
|
|
1026
|
+
change: no definition edited in place, lost or added, no other top-level statement
|
|
1027
|
+
changed in any file, no part's load removed, and every part the candidate adds is
|
|
1028
|
+
loaded. Returns {"moved": [(name, from, to)], "problems": [text]}.
|
|
1029
|
+
|
|
1030
|
+
Given two commits, the same proof reads a range that landed: `end` against `start`.
|
|
1031
|
+
A waived review of a move closes on it once the move has landed.
|
|
1032
|
+
"""
|
|
1033
|
+
if start is None:
|
|
1034
|
+
listing, before, after = ("diff", "--cached", "--name-only", "--no-renames", "-z"), "HEAD", ""
|
|
1035
|
+
else:
|
|
1036
|
+
listing, before, after = ("diff", "--name-only", "--no-renames", "-z", start, end, "--"), start, end
|
|
1037
|
+
raw = _git_output(root, *listing).decode(UTF8, "replace").split("\0")
|
|
1038
|
+
paths = sorted({path for path in raw if path.endswith(".py")})
|
|
1039
|
+
base, head = before, after # the names below are taken by a definition's texts
|
|
1040
|
+
|
|
1041
|
+
def read(spec):
|
|
1042
|
+
result = subprocess.run([git_binary(), "show", spec], cwd=root, capture_output=True)
|
|
1043
|
+
return result.stdout.decode(UTF8, "replace") if result.returncode == 0 else None
|
|
1044
|
+
|
|
1045
|
+
old, new = {}, {}
|
|
1046
|
+
# Statements and loads are kept by file: one moved between files changed both (SPLIT-CHECK-2).
|
|
1047
|
+
other, loads, parts, present = {"old": {}, "new": {}}, {"old": {}, "new": {}}, [], {}
|
|
1048
|
+
order, loaders, touched = {"old": {}, "new": {}}, {}, {}
|
|
1049
|
+
for path in paths:
|
|
1050
|
+
for side, spec, defs in (("old", f"{before}:{path}", old), ("new", f"{after}:{path}", new)):
|
|
1051
|
+
text = read(spec)
|
|
1052
|
+
if text is None:
|
|
1053
|
+
continue
|
|
1054
|
+
try:
|
|
1055
|
+
definitions, others, loaded, sequence = top_level_statements(text, path)
|
|
1056
|
+
except SyntaxError as exc:
|
|
1057
|
+
return {"moved": [], "problems": [f"{path} does not parse on the {side} side: {exc.msg}"]}
|
|
1058
|
+
for name, texts in definitions.items():
|
|
1059
|
+
defs.setdefault(name, []).extend((path, t) for t in texts)
|
|
1060
|
+
other[side][path] = others # in their order (SPLIT-CHECK-3)
|
|
1061
|
+
loads[side][path] = set(loaded)
|
|
1062
|
+
order[side][path] = sequence
|
|
1063
|
+
present.setdefault(path, {})[side] = bool(definitions or others or loaded)
|
|
1064
|
+
if side == "new" and "/parts/" in f"/{path}" and read(f"{before}:{path}") is None:
|
|
1065
|
+
parts.append(path)
|
|
1066
|
+
if side == "new":
|
|
1067
|
+
touched[path] = text
|
|
1068
|
+
if loaded:
|
|
1069
|
+
loaders[path] = text
|
|
1070
|
+
# A load runs polyctl's loader only through a name the module binds to it (SPLIT-CHECK-7), in its own file and in each
|
|
1071
|
+
# part that runs in its namespace, written by the candidate or landed before it (#111).
|
|
1072
|
+
rebinders, writers = _namespace_findings(loaders, lambda path: read(f"{after}:{path}"), touched)
|
|
1073
|
+
moved, problems = [], [f"{path} binds {name}, which its _part loads call through, to something else than "
|
|
1074
|
+
"polyctl's loader" for path, name in rebinders]
|
|
1075
|
+
problems += [f"{path} can bind a name in the namespace its module's parts load into by {what}, which the move "
|
|
1076
|
+
"proof cannot read" for path, what in writers]
|
|
1077
|
+
for name in sorted(set(old) | set(new)):
|
|
1078
|
+
before, after = old.get(name, []), new.get(name, [])
|
|
1079
|
+
if not after:
|
|
1080
|
+
problems.append(f"{name} left {', '.join(sorted({p for p, _ in before}))} and arrived nowhere")
|
|
1081
|
+
continue
|
|
1082
|
+
if not before:
|
|
1083
|
+
problems.append(f"{name} is new in {', '.join(sorted({p for p, _ in after}))}")
|
|
1084
|
+
continue
|
|
1085
|
+
was, now = sorted({p for p, _ in before}), sorted({p for p, _ in after})
|
|
1086
|
+
if sorted(t for _, t in before) != sorted(t for _, t in after):
|
|
1087
|
+
problems.append(f"{name} changed" + (f" on its way from {', '.join(was)} to {', '.join(now)}"
|
|
1088
|
+
if was != now else f" in {', '.join(now)}"))
|
|
1089
|
+
elif was != now:
|
|
1090
|
+
# A definition leaves a module only for a part that module loads, as a split does: renamed, or
|
|
1091
|
+
# into a part another module loads, it runs in another namespace (SPLIT-CHECK-2).
|
|
1092
|
+
loader = {_part_file(path, part) for path in was for part in loads["new"].get(path, set())}
|
|
1093
|
+
stray = [path for path in now if path not in was and path not in loader]
|
|
1094
|
+
if stray:
|
|
1095
|
+
problems.append(f"{name} moved to {', '.join(stray)}, which no file it left loads as its part")
|
|
1096
|
+
else:
|
|
1097
|
+
moved.append((name, ", ".join(was), ", ".join(now)))
|
|
1098
|
+
for path in sorted(set(other["old"]) | set(other["new"])):
|
|
1099
|
+
if other["old"].get(path, []) != other["new"].get(path, []):
|
|
1100
|
+
problems.append(f"a top-level statement that is not a definition changed in {path}")
|
|
1101
|
+
# A module's text is the move's whole: read with its parts in place it is the text it was, line for line, so a
|
|
1102
|
+
# docstring, a comment or a line carried elsewhere is no move - a move-only slice lands without a review, and text
|
|
1103
|
+
# steers whoever reads the code next (SPLIT-DOCSTRING). A part's text is read in the module that loads it.
|
|
1104
|
+
for path in sorted(_loading_modules(root, read, base, head, paths)):
|
|
1105
|
+
was, now = _inlined_lines(read, base, path), _inlined_lines(read, head, path)
|
|
1106
|
+
if was is None or now is None or was == now:
|
|
1107
|
+
continue
|
|
1108
|
+
at = next((i for i, pair in enumerate(zip(was, now)) if pair[0] != pair[1]), min(len(was), len(now)))
|
|
1109
|
+
line = (now[at] if at < len(now) else was[at]).strip()
|
|
1110
|
+
problems.append(f"{path}, read with its parts where they load, is not the text it was: a move adds, drops or "
|
|
1111
|
+
f"carries elsewhere no line (first: {line[:80]!r})")
|
|
1112
|
+
for path in sorted(loads["old"]):
|
|
1113
|
+
for name in sorted(loads["old"][path] - loads["new"].get(path, set())):
|
|
1114
|
+
problems.append(f"the _part call that loaded {name} is gone")
|
|
1115
|
+
# A part the candidate adds runs where the module that loads it loads it. Put in place there, each
|
|
1116
|
+
# file's statements must be its old ones in their old order - loads of existing parts included - and an
|
|
1117
|
+
# added file must be such a part, put in place once (SPLIT-CHECK-3).
|
|
1118
|
+
added = {path for path in order["new"] if path not in order["old"]}
|
|
1119
|
+
placed = set()
|
|
1120
|
+
for path in sorted(order["old"]):
|
|
1121
|
+
inlined = []
|
|
1122
|
+
for kind, value in order["new"].get(path, []):
|
|
1123
|
+
target = _part_file(path, value) if kind == "load" else None
|
|
1124
|
+
if target in added and target not in placed:
|
|
1125
|
+
placed.add(target)
|
|
1126
|
+
inlined.extend(order["new"][target])
|
|
1127
|
+
else:
|
|
1128
|
+
inlined.append((kind, value))
|
|
1129
|
+
if inlined != order["old"][path]:
|
|
1130
|
+
problems.append(f"{path} does not run its old statements in their old order with its new parts in place")
|
|
1131
|
+
for path in sorted(added - placed):
|
|
1132
|
+
if present.get(path, {}).get("new"):
|
|
1133
|
+
problems.append(f"{path} is added and is no new part that a module it was moved out of loads")
|
|
1134
|
+
# An empty, comment-only or docstring-only file holds nothing to compare, so one added or removed beside
|
|
1135
|
+
# a real move passed as part of it - an __init__.py changes which packages there are (CATCHUP-EVIDENCE-2).
|
|
1136
|
+
for path, sides in sorted(present.items()):
|
|
1137
|
+
if len(sides) == 1 and not any(sides.values()):
|
|
1138
|
+
problems.append(f"{path} is {'added' if 'new' in sides else 'removed'} and holds no definition: "
|
|
1139
|
+
"a file's presence is not a move")
|
|
1140
|
+
loaded_files = {_part_file(path, part) for path, names in loads["new"].items() for part in names}
|
|
1141
|
+
for path in parts:
|
|
1142
|
+
if path not in loaded_files:
|
|
1143
|
+
problems.append(f"{path} is not loaded by any _part call")
|
|
1144
|
+
if not moved and not problems:
|
|
1145
|
+
problems.append("nothing moved")
|
|
1146
|
+
return {"moved": moved, "problems": problems}
|
|
1147
|
+
|
|
1148
|
+
|
|
1149
|
+
_part("lib_adapters", globals())
|
|
1150
|
+
|
|
1151
|
+
|
|
1152
|
+
# ── shell ─────────────────────────────────────────────────────────────────────
|
|
1153
|
+
|
|
1154
|
+
def _shell_word(word):
|
|
1155
|
+
if os.name == "nt":
|
|
1156
|
+
return subprocess.list2cmdline([word])
|
|
1157
|
+
import shlex
|
|
1158
|
+
return shlex.quote(word)
|
|
1159
|
+
|
|
1160
|
+
|
|
1161
|
+
# What PowerShell expands inside double quotes (`$`, the backtick), what cmd.exe expands there (`%`, `!`), and the
|
|
1162
|
+
# quotes either reads as its own, the typographic ones among them.
|
|
1163
|
+
_WINDOWS_UNQUOTABLE = frozenset('$`"%!\u201c\u201d\u201e\u2018\u2019\u201a\u201b')
|
|
1164
|
+
|
|
1165
|
+
|
|
1166
|
+
def copyable_word(word, windows=None):
|
|
1167
|
+
"""`word` quoted as one word of a command a person copies into their shell, or None where no quoting is sure to
|
|
1168
|
+
keep it one.
|
|
1169
|
+
|
|
1170
|
+
POSIX shells read shlex's single quotes literally. On Windows the command may be pasted into cmd.exe or
|
|
1171
|
+
PowerShell, and the word is always put in double quotes, where both read `&`, `|`, `<`, `>`, `^`, `(` and `;` as
|
|
1172
|
+
text: the C runtime's quoting left a word with no space bare, and `polyctl -C C:\\repo&calc` ran calc in cmd.exe. Inside
|
|
1173
|
+
the quotes PowerShell still runs `$(...)` and cmd.exe expands `%NAME%`, so a word holding either's sign, a quote,
|
|
1174
|
+
or a control character is copyable nowhere: a review id an agent wrote, `R-1 $(Start-Process calc)`, ran as the
|
|
1175
|
+
person who copied `polyctl review collect` (LEADS-MCP). A backslash before the closing quote is doubled, since the C
|
|
1176
|
+
runtime reads `\\"` as a quote.
|
|
1177
|
+
"""
|
|
1178
|
+
text = str(word)
|
|
1179
|
+
if any(ord(char) < 32 or ord(char) == 127 for char in text):
|
|
1180
|
+
return None
|
|
1181
|
+
if not (os.name == "nt" if windows is None else windows):
|
|
1182
|
+
import shlex
|
|
1183
|
+
return shlex.quote(text)
|
|
1184
|
+
if _WINDOWS_UNQUOTABLE & set(text):
|
|
1185
|
+
return None
|
|
1186
|
+
return '"' + text + "\\" * (len(text) - len(text.rstrip("\\"))) + '"'
|
|
1187
|
+
|
|
1188
|
+
|
|
1189
|
+
def sh(cmd, cwd=None, timeout=20):
|
|
1190
|
+
return _sh_run(cmd, cwd=cwd, timeout=timeout)[0]
|
|
1191
|
+
|
|
1192
|
+
|
|
1193
|
+
def shell_program():
|
|
1194
|
+
"""The shell a command line polyctl runs starts in: None on POSIX, where subprocess starts /bin/sh by its path, and
|
|
1195
|
+
Windows' own cmd.exe on Windows (WINDOWS-NO-CWD-EXEC).
|
|
1196
|
+
|
|
1197
|
+
subprocess starts what %ComSpec% names, and where it names nothing an older Python started
|
|
1198
|
+
`cmd.exe` by its bare name, which Windows looks for in the current directory first.
|
|
1199
|
+
FileNotFoundError where Windows' system directory holds no cmd.exe.
|
|
1200
|
+
"""
|
|
1201
|
+
if os.name != "nt":
|
|
1202
|
+
return None
|
|
1203
|
+
program = program_path("cmd")
|
|
1204
|
+
if program is None:
|
|
1205
|
+
raise FileNotFoundError(f"cmd.exe is not in Windows' system directory {windows_system_directory()}")
|
|
1206
|
+
return program
|
|
1207
|
+
|
|
1208
|
+
|
|
1209
|
+
def _sh_run(cmd, cwd=None, timeout=20):
|
|
1210
|
+
"""sh()'s command and how it ended: (stripped standard output, exit status), or ("", None).
|
|
1211
|
+
|
|
1212
|
+
None when no shell could be started for it or it ran past its timeout. sh() returns the
|
|
1213
|
+
output alone, and a caller that keeps what a command printed has to tell a command that
|
|
1214
|
+
answered from one that failed.
|
|
1215
|
+
"""
|
|
1216
|
+
# cmd.exe has no /dev/null; it calls it NUL, and the command failed instead (#71).
|
|
1217
|
+
if os.name == "nt":
|
|
1218
|
+
cmd = cmd.replace("2>/dev/null", "2>NUL")
|
|
1219
|
+
# Through a shell too, git is the compiled one, not a script standing in front of it (#51).
|
|
1220
|
+
if cmd.startswith("git "):
|
|
1221
|
+
cmd = _shell_word(git_binary()) + cmd[3:]
|
|
1222
|
+
try:
|
|
1223
|
+
# On Windows the shell is Windows' own cmd.exe, and it is told to look for the command in PATH
|
|
1224
|
+
# alone: by default it looks in the directory it runs in first (WINDOWS-NO-CWD-EXEC).
|
|
1225
|
+
windows = {"executable": shell_program(), "env": dict(os.environ, NoDefaultCurrentDirectoryInExePath="1")} \
|
|
1226
|
+
if os.name == "nt" else {}
|
|
1227
|
+
r = subprocess.run(cmd, shell=True, cwd=cwd, capture_output=True,
|
|
1228
|
+
text=True, encoding=UTF8, errors="replace", timeout=timeout, **windows)
|
|
1229
|
+
return r.stdout.strip(), r.returncode
|
|
1230
|
+
except Exception:
|
|
1231
|
+
return "", None
|
|
1232
|
+
|
|
1233
|
+
|
|
1234
|
+
def self_child_env(env=None):
|
|
1235
|
+
"""The environment a child that re-enters polyctl as `-m polyctl` needs, so a clone stays findable.
|
|
1236
|
+
|
|
1237
|
+
polyctl's documented quickstart is a clone plus a symlink on PATH: `bin/polyctl` puts `src` on this
|
|
1238
|
+
process's `sys.path`, and nothing tells a child of it. Three places start such a child - the
|
|
1239
|
+
review runner, the watchdog's hunt and the MCP server's verify - and each died on "No module
|
|
1240
|
+
named polyctl" when polyctl was not installed. The review died silently: the process was gone before its
|
|
1241
|
+
log held anything a person would read, and the review stood at "running" until it was lost.
|
|
1242
|
+
The package's own parent goes first on PYTHONPATH, which is the directory this polyctl was imported
|
|
1243
|
+
from, whether that is a clone or an installation.
|
|
1244
|
+
"""
|
|
1245
|
+
child = dict(os.environ if env is None else env)
|
|
1246
|
+
parent = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
|
|
1247
|
+
# One PYTHONPATH, whatever case a caller's environment spelt it in: Windows reads `PythonPath` and `PYTHONPATH` as
|
|
1248
|
+
# one name, and a block holding both may hand the child the one without this polyctl (the review of DEMO-2).
|
|
1249
|
+
spelt = [name for name in child if name.upper() == "PYTHONPATH"]
|
|
1250
|
+
given = os.pathsep.join(child.pop(name) or "" for name in spelt)
|
|
1251
|
+
rest = [part for part in given.split(os.pathsep) if part and part != parent]
|
|
1252
|
+
child["PYTHONPATH"] = os.pathsep.join([parent] + list(dict.fromkeys(rest)))
|
|
1253
|
+
# `-m` puts the working directory first on the import path: where the interpreter can be told not to (3.11), it
|
|
1254
|
+
# is; self_child_cwd holds on the older ones (CHILD-CWD).
|
|
1255
|
+
child["PYTHONSAFEPATH"] = "1"
|
|
1256
|
+
return child
|
|
1257
|
+
|
|
1258
|
+
|
|
1259
|
+
def self_child_cwd():
|
|
1260
|
+
"""The working directory of a child that re-enters polyctl as `-m polyctl`: polyctl's own folder in the person's home, which holds
|
|
1261
|
+
no module of a project's (CHILD-CWD, #117).
|
|
1262
|
+
|
|
1263
|
+
`python -m polyctl` puts its working directory first on the import path. The watchdog's hunt, a submitted review's
|
|
1264
|
+
runner, the MCP server's verify and init's watchdog install started that child in the project - or wherever the
|
|
1265
|
+
person stood, which is the project - so a json.py or a polyctl/ package an agent left at its root was imported in
|
|
1266
|
+
place of the standard library's or polyctl's own: from the watchdog's job, outside any agent's sandbox. Each names the
|
|
1267
|
+
project with -C and needs no working directory there.
|
|
1268
|
+
"""
|
|
1269
|
+
path = os.path.join(HOME, ".polyctl")
|
|
1270
|
+
os.makedirs(path, exist_ok=True)
|
|
1271
|
+
return path
|
|
1272
|
+
|
|
1273
|
+
|
|
1274
|
+
_part("lib_transcript", globals())
|
|
1275
|
+
|
|
1276
|
+
|
|
1277
|
+
_part("lib_gates", globals())
|
|
1278
|
+
|
|
1279
|
+
|
|
1280
|
+
_part("lib_state", globals())
|
|
1281
|
+
|
|
1282
|
+
|
|
1283
|
+
_part("lib_slices", globals())
|
|
1284
|
+
|
|
1285
|
+
|
|
1286
|
+
_part("lib_mail", globals())
|
|
1287
|
+
|
|
1288
|
+
|
|
1289
|
+
_part("lib_alarms", globals())
|
|
1290
|
+
|
|
1291
|
+
|
|
1292
|
+
_part("lib_lanes", globals())
|
|
1293
|
+
_part("lib_pr", globals())
|
|
1294
|
+
_part("lib_events", globals())
|
|
1295
|
+
_part("lib_evidence", globals())
|
|
1296
|
+
_part("lib_next", globals())
|