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,224 @@
|
|
|
1
|
+
"""The machine's event log: what polyctl did, one line an event, in ~/.polyctl/events.jsonl (EVENTS-LOG).
|
|
2
|
+
|
|
3
|
+
A part of src/polyctl/lib.py, run in its namespace by `_part`; it is not importable on its own.
|
|
4
|
+
|
|
5
|
+
A surface that wanted to know what polyctl was doing had to poll: `polyctl status` read a project's files
|
|
6
|
+
again, and a person waiting on a submitted review ran `polyctl reviews` until it came back. Now polyctl
|
|
7
|
+
appends one line to a file the whole machine shares when it records a verification, submits a
|
|
8
|
+
review or sees a submitted one end, grants commit authority, sends mail, and nudges or wakes an
|
|
9
|
+
agent, and `polyctl events --follow`, or any program that reads the file, learns of each as it happens.
|
|
10
|
+
|
|
11
|
+
The log observes the work and is never part of it. Nothing reads it to decide anything, so it is
|
|
12
|
+
no evidence: it is kept as the other observation stores are, held to its bound as it is written,
|
|
13
|
+
its oldest lines going first. And writing an event never fails the command that did the work.
|
|
14
|
+
"""
|
|
15
|
+
|
|
16
|
+
|
|
17
|
+
# How long an event waits for another process's append or trim of the log. Each holds the lock
|
|
18
|
+
# for one short write, or one rewrite of a bounded file, so a wait this long means something is
|
|
19
|
+
# stuck, and the event is given up and said rather than holding up the work it reports.
|
|
20
|
+
EVENTS_LOCK_SECONDS = 5
|
|
21
|
+
|
|
22
|
+
|
|
23
|
+
def events_path():
|
|
24
|
+
"""Where the machine's event log is: ~/.polyctl/events.jsonl, or the file POLYCTL_EVENTS names.
|
|
25
|
+
|
|
26
|
+
POLYCTL_EVENTS is how the tests keep their events apart from a person's, as POLYCTL_SETTINGS keeps
|
|
27
|
+
their settings apart.
|
|
28
|
+
"""
|
|
29
|
+
return os.environ.get("POLYCTL_EVENTS") or os.path.join(HOME, ".polyctl", "events.jsonl")
|
|
30
|
+
|
|
31
|
+
|
|
32
|
+
def event_line(row):
|
|
33
|
+
"""One event as the log holds it: compact JSON on one line, as UTF-8 bytes.
|
|
34
|
+
|
|
35
|
+
A value JSON cannot hold is written as its text, so an odd value costs its form, never the event.
|
|
36
|
+
"""
|
|
37
|
+
return (json.dumps(row, ensure_ascii=False, separators=(",", ":"), default=str) + "\n").encode(UTF8)
|
|
38
|
+
|
|
39
|
+
|
|
40
|
+
def emit_event(root, kind, data=None):
|
|
41
|
+
"""Append one event of this project to the machine's log; the row written, or None when it could not be.
|
|
42
|
+
|
|
43
|
+
`data` is the event's short payload - ids, names and verdicts, never a body, a diff or a
|
|
44
|
+
transcript - with each value that is None left out. Every string in it is scanned the way
|
|
45
|
+
evidence is (#48): the log is a file other programs read, and docs/safety.md keeps secrets
|
|
46
|
+
out of the event log. The project is named by its key (project_key), the name its files in
|
|
47
|
+
~/.polyctl carry, so one line of the log and the rest of what polyctl keeps of a project agree.
|
|
48
|
+
|
|
49
|
+
The append and the bound share one lock, so an event written while another process trims
|
|
50
|
+
the file is not lost with the old file. A line a killed writer left unfinished is ended
|
|
51
|
+
first, so it spoils only itself.
|
|
52
|
+
|
|
53
|
+
Nothing here raises into the command that did the work: the verification, the grant or the
|
|
54
|
+
mail it reports stands whether or not its event could be written. An event that could not
|
|
55
|
+
be, or a bound that could not be held, is said on standard error - never on standard output,
|
|
56
|
+
where the MCP server speaks its protocol - and the command goes on.
|
|
57
|
+
"""
|
|
58
|
+
path = events_path()
|
|
59
|
+
try:
|
|
60
|
+
from .storage import _exclusive_lock
|
|
61
|
+
payload = {key: value for key, value in (data or {}).items() if value is not None}
|
|
62
|
+
row = {"at": round(time.time(), 3), "project": project_key(root), "kind": kind,
|
|
63
|
+
"data": scan_record(payload)}
|
|
64
|
+
line = event_line(row)
|
|
65
|
+
with _exclusive_lock(path + ".lock", timeout=EVENTS_LOCK_SECONDS):
|
|
66
|
+
with open(path, "a+b") as fh:
|
|
67
|
+
fh.seek(0, os.SEEK_END)
|
|
68
|
+
if fh.tell():
|
|
69
|
+
fh.seek(-1, os.SEEK_END)
|
|
70
|
+
if fh.read(1) != b"\n":
|
|
71
|
+
line = b"\n" + line
|
|
72
|
+
fh.seek(0, os.SEEK_END)
|
|
73
|
+
fh.write(line)
|
|
74
|
+
try:
|
|
75
|
+
bound_store(path, settings.get(None, "retention.events_kb"))
|
|
76
|
+
except Exception as exc: # the event is written; only the trim failed
|
|
77
|
+
print(f"polyctl: {path} was not held to its bound: {type(exc).__name__}: {exc}", file=sys.stderr)
|
|
78
|
+
return row
|
|
79
|
+
except Exception as exc:
|
|
80
|
+
print(f"polyctl: the {kind} event was not written to {path}: {type(exc).__name__}: {exc}", file=sys.stderr)
|
|
81
|
+
return None
|
|
82
|
+
|
|
83
|
+
|
|
84
|
+
def event_row(line):
|
|
85
|
+
"""The event one line of the log holds, as a dict, or None for a line that holds none."""
|
|
86
|
+
try:
|
|
87
|
+
row = json.loads(line)
|
|
88
|
+
except ValueError: # not JSON, or not UTF-8
|
|
89
|
+
return None
|
|
90
|
+
return row if isinstance(row, dict) else None
|
|
91
|
+
|
|
92
|
+
|
|
93
|
+
def event_matches(row, project=None, since=None):
|
|
94
|
+
"""Whether an event is of `project`, its key compared without case, and written at or after `since`, an epoch.
|
|
95
|
+
|
|
96
|
+
A key is compared without case because no two projects hold keys that differ only in case
|
|
97
|
+
(project_key). An event whose time cannot be read is not shown as being after anything.
|
|
98
|
+
"""
|
|
99
|
+
if project is not None and str(row.get("project", "")).lower() != str(project).lower():
|
|
100
|
+
return False
|
|
101
|
+
if since is not None:
|
|
102
|
+
at = row.get("at")
|
|
103
|
+
if isinstance(at, bool) or not isinstance(at, (int, float)) or at < since:
|
|
104
|
+
return False
|
|
105
|
+
return True
|
|
106
|
+
|
|
107
|
+
|
|
108
|
+
class EventTail:
|
|
109
|
+
"""A reader of the machine's event log that goes on from where it stopped, whatever the bound did meanwhile.
|
|
110
|
+
|
|
111
|
+
The bound replaces the file with its newest lines (bound_store), so an offset alone would read
|
|
112
|
+
on from the wrong place after a trim, or wait past the end of the shorter file. The reader keeps
|
|
113
|
+
the last line it read and where that line ended as well: while the line still ends there, the
|
|
114
|
+
file is the one it was reading; once it does not, the reader finds the line in the new file and
|
|
115
|
+
goes on after it. A trim that took lines this reader had not reached leaves `missed` set, so a
|
|
116
|
+
follower can say that events may be missing instead of passing over them. `skipped` counts the
|
|
117
|
+
lines that held no event. A line still being written is left for the next poll.
|
|
118
|
+
|
|
119
|
+
The file is opened for each poll and closed again: on Windows a handle held open would stop the
|
|
120
|
+
bound from replacing the file.
|
|
121
|
+
"""
|
|
122
|
+
|
|
123
|
+
def __init__(self, path=None):
|
|
124
|
+
self.path = path or events_path()
|
|
125
|
+
self.offset = 0 # bytes of the file read
|
|
126
|
+
self.mark, self.mark_end = b"", 0 # the last line read with content, and where it ended
|
|
127
|
+
self.missed, self.skipped = False, 0
|
|
128
|
+
|
|
129
|
+
def poll(self):
|
|
130
|
+
"""The events written since the last poll, oldest first.
|
|
131
|
+
|
|
132
|
+
Raises OSError when the log exists and cannot be read; a log not written yet has no events.
|
|
133
|
+
"""
|
|
134
|
+
try:
|
|
135
|
+
fh = open(self.path, "rb")
|
|
136
|
+
except FileNotFoundError:
|
|
137
|
+
return []
|
|
138
|
+
with fh:
|
|
139
|
+
if not self._in_place(fh, os.fstat(fh.fileno()).st_size):
|
|
140
|
+
self._find_place(fh)
|
|
141
|
+
fh.seek(self.offset)
|
|
142
|
+
chunk = fh.read()
|
|
143
|
+
whole = chunk[:chunk.rfind(b"\n") + 1]
|
|
144
|
+
rows, end = [], self.offset
|
|
145
|
+
for line in whole.split(b"\n")[:-1]:
|
|
146
|
+
end += len(line) + 1
|
|
147
|
+
if not line.strip():
|
|
148
|
+
continue
|
|
149
|
+
self.mark, self.mark_end = line, end
|
|
150
|
+
row = event_row(line)
|
|
151
|
+
if row is None:
|
|
152
|
+
self.skipped += 1
|
|
153
|
+
else:
|
|
154
|
+
rows.append(row)
|
|
155
|
+
self.offset += len(whole)
|
|
156
|
+
return rows
|
|
157
|
+
|
|
158
|
+
def _in_place(self, fh, size):
|
|
159
|
+
"""Whether the file is still the one the last poll read: as long, and its last line still where it was."""
|
|
160
|
+
if size < self.offset:
|
|
161
|
+
return False
|
|
162
|
+
if not self.mark:
|
|
163
|
+
return True
|
|
164
|
+
fh.seek(self.mark_end - len(self.mark) - 1)
|
|
165
|
+
return fh.read(len(self.mark) + 1) == self.mark + b"\n"
|
|
166
|
+
|
|
167
|
+
def _find_place(self, fh):
|
|
168
|
+
"""After a trim, go on after the last line read; if the trim took it, from the top, and say so."""
|
|
169
|
+
if not self.mark:
|
|
170
|
+
self.offset = 0
|
|
171
|
+
return
|
|
172
|
+
fh.seek(0)
|
|
173
|
+
found = (b"\n" + fh.read()).rfind(b"\n" + self.mark + b"\n")
|
|
174
|
+
if found < 0:
|
|
175
|
+
self.offset, self.mark, self.mark_end, self.missed = 0, b"", 0, True
|
|
176
|
+
return
|
|
177
|
+
after = found + len(self.mark) + 1 # where the line ends in the file as it is now
|
|
178
|
+
self.offset, self.mark_end = after + (self.offset - self.mark_end), after
|
|
179
|
+
|
|
180
|
+
|
|
181
|
+
def read_events(path=None):
|
|
182
|
+
"""Every event the log holds now, oldest first."""
|
|
183
|
+
return EventTail(path).poll()
|
|
184
|
+
|
|
185
|
+
|
|
186
|
+
# ---- what a harness's lifecycle hooks said of its sessions (HOOK-SPOOL) ----------------------------------------
|
|
187
|
+
|
|
188
|
+
# The lifecycle events polyctl takes from a harness's hooks, by the name the hook command gives it, and what each says
|
|
189
|
+
# of the session it came from. A harness names its events its own way - Claude Code's Stop and Gemini's
|
|
190
|
+
# AfterAgent are both a turn-end here - so the command a hook runs names the event in polyctl's words, and an event
|
|
191
|
+
# polyctl does not know is not recorded.
|
|
192
|
+
AGENT_EVENTS = {
|
|
193
|
+
"session-start": "idle",
|
|
194
|
+
"prompt": "working",
|
|
195
|
+
"tool": "working",
|
|
196
|
+
"tool-done": "working",
|
|
197
|
+
"subagent-end": "working",
|
|
198
|
+
"compact": "working",
|
|
199
|
+
"notification": "waiting",
|
|
200
|
+
"turn-end": "idle",
|
|
201
|
+
"session-end": "ended",
|
|
202
|
+
}
|
|
203
|
+
|
|
204
|
+
|
|
205
|
+
def agent_sessions(root, rows=None):
|
|
206
|
+
"""{session: {"session", "harness", "state", "event", "at", "first", "cwd"}} for this project, from what its
|
|
207
|
+
harnesses' hooks told the machine's event log, the latest event of each session deciding its state (HOOK-SPOOL).
|
|
208
|
+
|
|
209
|
+
A session is known here only from its hooks: one no hook has spoken of is not in it, and nothing here reads
|
|
210
|
+
a harness's own store.
|
|
211
|
+
"""
|
|
212
|
+
key = project_key(root)
|
|
213
|
+
sessions = {}
|
|
214
|
+
for row in read_events() if rows is None else rows:
|
|
215
|
+
kind = str(row.get("kind") or "")
|
|
216
|
+
if row.get("project") != key or not kind.startswith("agent-") or kind[len("agent-"):] not in AGENT_EVENTS:
|
|
217
|
+
continue
|
|
218
|
+
data = row.get("data") if isinstance(row.get("data"), dict) else {}
|
|
219
|
+
event = kind[len("agent-"):]
|
|
220
|
+
sid = str(data.get("session") or "(no session id)")
|
|
221
|
+
session = sessions.setdefault(sid, {"session": sid, "first": row.get("at"), "harness": None, "cwd": None})
|
|
222
|
+
session.update(event=event, at=row.get("at"), state=AGENT_EVENTS[event],
|
|
223
|
+
harness=data.get("harness") or session["harness"], cwd=data.get("cwd") or session["cwd"])
|
|
224
|
+
return sessions
|
|
@@ -0,0 +1,412 @@
|
|
|
1
|
+
"""Platform lane runs recorded as evidence: what each platform last proved, and what still vouches (LANE-EVIDENCE).
|
|
2
|
+
|
|
3
|
+
A part of src/polyctl/lib.py, run in its namespace by `_part`; it is not importable on its own.
|
|
4
|
+
|
|
5
|
+
`polyctl gain` already showed the newest run of each platform from `.polyctl/ledger/platform-runs.jsonl`,
|
|
6
|
+
and nothing polyctl shipped wrote that file: the record was whatever a lane's script left there,
|
|
7
|
+
plain JSON that nothing could tell an edited row from one a run wrote. `polyctl evidence record`
|
|
8
|
+
reads a lane's CI run through `gh` and writes what the run says — its status and conclusion,
|
|
9
|
+
its head commit, its repository, and its jobs — into the chained, checkpointed
|
|
10
|
+
ledger. A run that is not on this repository, not finished, not successful, or not on a commit
|
|
11
|
+
HEAD holds as an ancestor is recorded as such and never reads as green; `polyctl doctor --check`
|
|
12
|
+
names any newest run that no longer covers HEAD. A project that recorded none is not told
|
|
13
|
+
anything: absence of evidence is not evidence of a failure.
|
|
14
|
+
"""
|
|
15
|
+
import os
|
|
16
|
+
import time
|
|
17
|
+
|
|
18
|
+
PLATFORM_RUNS_FILE = os.path.join(".polyctl", "ledger", "platform-runs.jsonl")
|
|
19
|
+
PLATFORM_RUNS_CHAIN = "polyctl-platform-run-v1"
|
|
20
|
+
PLATFORM_RUN_FIELDS = "databaseId,number,createdAt,status,conclusion,headSha,workflowName,name,jobs,url"
|
|
21
|
+
_PLATFORM_ALIASES = {
|
|
22
|
+
"windows": ("windows", "win32", "win64"),
|
|
23
|
+
"linux": ("linux", "ubuntu", "debian"),
|
|
24
|
+
"macos": ("macos", "darwin", "mac"),
|
|
25
|
+
}
|
|
26
|
+
|
|
27
|
+
|
|
28
|
+
def platform_runs_path(root):
|
|
29
|
+
"""Where a project records its platform runs: .polyctl/ledger/platform-runs.jsonl."""
|
|
30
|
+
return os.path.join(root, PLATFORM_RUNS_FILE)
|
|
31
|
+
|
|
32
|
+
|
|
33
|
+
def _platform_text(value, field):
|
|
34
|
+
"""One non-empty word a row carries, such as the platform or the run's id."""
|
|
35
|
+
text = str(value if value is not None else "").strip()
|
|
36
|
+
if not text:
|
|
37
|
+
raise ValueError(f"a platform run needs a {field}")
|
|
38
|
+
if any(character.isspace() for character in text):
|
|
39
|
+
raise ValueError(f"the {field} must be one word, not {text!r}")
|
|
40
|
+
return text
|
|
41
|
+
|
|
42
|
+
|
|
43
|
+
def _platform_count(value, field):
|
|
44
|
+
"""A non-negative whole number, such as a run number or timestamp, never a bool."""
|
|
45
|
+
if isinstance(value, bool) or not isinstance(value, (int, str)):
|
|
46
|
+
raise ValueError(f"{field} must be a whole number, not {value!r}")
|
|
47
|
+
try:
|
|
48
|
+
number = int(value)
|
|
49
|
+
except (TypeError, ValueError):
|
|
50
|
+
raise ValueError(f"{field} must be a whole number, not {value!r}") from None
|
|
51
|
+
if number < 0:
|
|
52
|
+
raise ValueError(f"{field} cannot be negative")
|
|
53
|
+
return number
|
|
54
|
+
|
|
55
|
+
|
|
56
|
+
def _platform_repo_slug(value):
|
|
57
|
+
"""The lowercase `owner/repo` a run URL, remote URL, or repository object names, or ''."""
|
|
58
|
+
if isinstance(value, dict):
|
|
59
|
+
owner = value.get("owner")
|
|
60
|
+
owner = owner.get("login") if isinstance(owner, dict) else owner
|
|
61
|
+
value = value.get("nameWithOwner") or value.get("full_name") or (
|
|
62
|
+
f"{owner}/{value.get('name')}" if owner and value.get("name") else ""
|
|
63
|
+
)
|
|
64
|
+
text = str(value or "").strip()
|
|
65
|
+
if not text:
|
|
66
|
+
return ""
|
|
67
|
+
identity = _remote_identity(text)
|
|
68
|
+
if identity is not None:
|
|
69
|
+
parts = [part for part in identity[1].split("/") if part]
|
|
70
|
+
if len(parts) >= 2:
|
|
71
|
+
return f"{parts[0]}/{parts[1]}".lower().removesuffix(".git")
|
|
72
|
+
parts = [part for part in text.strip("/").split("/") if part]
|
|
73
|
+
if len(parts) == 2 and not any(character.isspace() for character in text):
|
|
74
|
+
return f"{parts[0]}/{parts[1]}".lower().removesuffix(".git")
|
|
75
|
+
return ""
|
|
76
|
+
|
|
77
|
+
|
|
78
|
+
def _platform_checkout_repos(root):
|
|
79
|
+
"""Every `owner/repo` this checkout's git remotes name, in lowercase; set() when no remote names one."""
|
|
80
|
+
try:
|
|
81
|
+
entries = _git_config_entries(root, r"^(remote\..+\.(url|pushurl)|url\..+\.(insteadof|pushinsteadof))$")
|
|
82
|
+
except Exception:
|
|
83
|
+
entries = []
|
|
84
|
+
urls = set()
|
|
85
|
+
for key, value in entries:
|
|
86
|
+
if key.startswith("remote.") and key.endswith((".url", ".pushurl")):
|
|
87
|
+
urls.add(value.strip())
|
|
88
|
+
for rule in ("insteadof", "pushinsteadof"):
|
|
89
|
+
rewritten = _git_rewrite(value.strip(), entries, rule)
|
|
90
|
+
if rewritten:
|
|
91
|
+
urls.add(rewritten[0].strip())
|
|
92
|
+
return {slug for url in urls for slug in (_platform_repo_slug(url),) if slug}
|
|
93
|
+
|
|
94
|
+
|
|
95
|
+
def _platform_on_repository(root, repository, explicit=None):
|
|
96
|
+
"""Whether a run belongs to one of this checkout's configured git remote repositories."""
|
|
97
|
+
if explicit is False:
|
|
98
|
+
return False
|
|
99
|
+
repo = _platform_repo_slug(repository)
|
|
100
|
+
repos = _platform_checkout_repos(root)
|
|
101
|
+
return bool(repo and repos and repo in repos)
|
|
102
|
+
|
|
103
|
+
|
|
104
|
+
def _platform_job_matches(name, platform_name):
|
|
105
|
+
"""Whether a CI job's name identifies `platform_name`."""
|
|
106
|
+
lower = str(name or "").lower()
|
|
107
|
+
tokens = _PLATFORM_ALIASES.get(platform_name, (platform_name,))
|
|
108
|
+
return any(token in lower for token in tokens)
|
|
109
|
+
|
|
110
|
+
|
|
111
|
+
def _platform_relevant_jobs(platform_name, jobs):
|
|
112
|
+
"""The jobs of a run whose names identify `platform_name`."""
|
|
113
|
+
if not jobs or not platform_name:
|
|
114
|
+
return []
|
|
115
|
+
return [job for job in jobs if isinstance(job, dict)
|
|
116
|
+
and _platform_job_matches(job.get("name"), platform_name)]
|
|
117
|
+
|
|
118
|
+
|
|
119
|
+
def _platform_clean_jobs(raw_jobs):
|
|
120
|
+
"""Normalized job entries (`name`, `status`, `conclusion`) from a CI run."""
|
|
121
|
+
if not isinstance(raw_jobs, list):
|
|
122
|
+
return []
|
|
123
|
+
jobs = []
|
|
124
|
+
for item in raw_jobs:
|
|
125
|
+
if not isinstance(item, dict):
|
|
126
|
+
continue
|
|
127
|
+
jobs.append({
|
|
128
|
+
"name": str(item.get("name") or "").strip(),
|
|
129
|
+
"status": str(item.get("status") or "").strip().lower(),
|
|
130
|
+
"conclusion": str(item.get("conclusion") or "").strip().lower(),
|
|
131
|
+
})
|
|
132
|
+
return jobs
|
|
133
|
+
|
|
134
|
+
|
|
135
|
+
def _platform_run_order(row):
|
|
136
|
+
"""Where a run stands in CI's own order: its creation time, run number, and run id."""
|
|
137
|
+
created = row.get("created_at") or row.get("createdAt")
|
|
138
|
+
when = _ledger_time(created) if isinstance(created, (int, float, str)) and not isinstance(created, bool) else 0.0
|
|
139
|
+
raw_number = row.get("number")
|
|
140
|
+
try:
|
|
141
|
+
number = 0 if isinstance(raw_number, bool) or raw_number is None else int(raw_number)
|
|
142
|
+
except (TypeError, ValueError):
|
|
143
|
+
number = 0
|
|
144
|
+
raw_run = str(row.get("run") or "").strip()
|
|
145
|
+
run_id = int(raw_run) if raw_run.isdigit() else 0
|
|
146
|
+
return when, number, run_id
|
|
147
|
+
|
|
148
|
+
|
|
149
|
+
def _platform_commit_placement(root, commit):
|
|
150
|
+
"""(known, behind) for `commit` in `root`: `behind` is None unless `commit` is an ancestor of HEAD."""
|
|
151
|
+
commit = str(commit or "").strip()
|
|
152
|
+
if not commit:
|
|
153
|
+
return False, None
|
|
154
|
+
resolved = _git_text(root, "rev-parse", "--verify", "--quiet", f"{commit}^{{commit}}").strip()
|
|
155
|
+
if not resolved:
|
|
156
|
+
return False, None
|
|
157
|
+
if _git_text(root, "merge-base", resolved, "HEAD").strip() != resolved:
|
|
158
|
+
return True, None
|
|
159
|
+
counted = _git_text(root, "rev-list", "--count", f"{resolved}..HEAD").strip()
|
|
160
|
+
return True, (int(counted) if counted.isdigit() else None)
|
|
161
|
+
|
|
162
|
+
|
|
163
|
+
def _platform_evaluate_row(root, row):
|
|
164
|
+
"""Evaluate a recorded or draft row against `root` now."""
|
|
165
|
+
platform_name = str(row.get("platform") or "").strip().lower()
|
|
166
|
+
on_repo = _platform_on_repository(
|
|
167
|
+
root,
|
|
168
|
+
row.get("repository") or row.get("url"),
|
|
169
|
+
row.get("on_repository"),
|
|
170
|
+
)
|
|
171
|
+
status = str(row.get("status") or "completed").strip().lower()
|
|
172
|
+
conclusion = str(row.get("conclusion") if row.get("conclusion") is not None else "success").strip().lower()
|
|
173
|
+
has_jobs = isinstance(row.get("jobs"), list)
|
|
174
|
+
jobs = _platform_clean_jobs(row.get("jobs")) if has_jobs else []
|
|
175
|
+
relevant = _platform_relevant_jobs(platform_name, jobs) if has_jobs else []
|
|
176
|
+
jobs_total = len(relevant) if has_jobs else row.get("jobs_total")
|
|
177
|
+
jobs_passed = (sum(1 for job in relevant if job["status"] == "completed" and job["conclusion"] == "success")
|
|
178
|
+
if has_jobs else row.get("jobs_passed"))
|
|
179
|
+
jobs_failed = (sum(1 for job in relevant
|
|
180
|
+
if job["status"] != "completed" or job["conclusion"] not in ("success", "skipped", "neutral"))
|
|
181
|
+
if has_jobs else row.get("jobs_failed"))
|
|
182
|
+
finished = (status == "completed"
|
|
183
|
+
and (not has_jobs or all(job["status"] == "completed" for job in relevant)))
|
|
184
|
+
jobs_ok = (not has_jobs and jobs_failed in (None, 0)) or (
|
|
185
|
+
bool(jobs_passed and jobs_passed > 0) and jobs_failed == 0
|
|
186
|
+
)
|
|
187
|
+
succeeded = finished and conclusion == "success" and jobs_ok
|
|
188
|
+
known, behind = _platform_commit_placement(root, row.get("commit"))
|
|
189
|
+
return on_repo, finished, succeeded, known, behind, jobs_total, jobs_passed, jobs_failed
|
|
190
|
+
|
|
191
|
+
|
|
192
|
+
def read_platform_run(root, platform, run, gh=None):
|
|
193
|
+
"""Read one CI run through `gh run view` and return the row it describes (LANE-EVIDENCE)."""
|
|
194
|
+
platform_name = _platform_text(platform, "platform").lower()
|
|
195
|
+
run_id = _platform_text(run, "run")
|
|
196
|
+
if run_id.startswith("-"):
|
|
197
|
+
raise ValueError(f"the run must be a run id, not {run_id!r}")
|
|
198
|
+
program = gh or runnable_binary("gh")
|
|
199
|
+
if not program:
|
|
200
|
+
raise GhUnreadable(
|
|
201
|
+
"gh is not on this machine (PATH, binaries.extra_dirs, the usual install directories): "
|
|
202
|
+
"polyctl reads a lane's run only through GitHub's CLI. Install it and run `gh auth login`"
|
|
203
|
+
)
|
|
204
|
+
raw = gh_json(root, program, "run", "view", run_id, "--json", PLATFORM_RUN_FIELDS)
|
|
205
|
+
if not isinstance(raw, dict):
|
|
206
|
+
raise GhUnreadable(f"`gh run view {run_id}` answered with something that is not a JSON object")
|
|
207
|
+
seen_id = raw.get("databaseId")
|
|
208
|
+
if seen_id not in (None, "") and str(seen_id).strip() != run_id:
|
|
209
|
+
raise GhUnreadable(f"`gh run view {run_id}` answered for run {seen_id!r}, not {run_id}")
|
|
210
|
+
raw_number = raw.get("number")
|
|
211
|
+
number = (_platform_count(raw_number, "number")
|
|
212
|
+
if raw_number not in (None, "") and not isinstance(raw_number, bool) else None)
|
|
213
|
+
created_at = str(raw.get("createdAt") or "").strip()
|
|
214
|
+
commit = str(raw.get("headSha") or "").strip()
|
|
215
|
+
if any(character.isspace() for character in commit):
|
|
216
|
+
raise GhUnreadable(f"`gh run view {run_id}` answered with an invalid headSha {commit!r}")
|
|
217
|
+
suite = str(raw.get("workflowName") or raw.get("name") or "full").strip() or "full"
|
|
218
|
+
status = str(raw.get("status") or "").strip().lower() or "unknown"
|
|
219
|
+
conclusion = str(raw.get("conclusion") or "").strip().lower()
|
|
220
|
+
url = str(raw.get("url") or "").strip()
|
|
221
|
+
repository = _platform_repo_slug(url)
|
|
222
|
+
jobs = _platform_clean_jobs(raw.get("jobs"))
|
|
223
|
+
draft = {
|
|
224
|
+
"platform": platform_name,
|
|
225
|
+
"run": run_id,
|
|
226
|
+
"number": number,
|
|
227
|
+
"created_at": created_at,
|
|
228
|
+
"suite": suite,
|
|
229
|
+
"status": status,
|
|
230
|
+
"conclusion": conclusion,
|
|
231
|
+
"commit": commit,
|
|
232
|
+
"repository": repository,
|
|
233
|
+
"on_repository": _platform_on_repository(root, repository or url),
|
|
234
|
+
"jobs": jobs,
|
|
235
|
+
}
|
|
236
|
+
on_repo, finished, succeeded, known, behind, jobs_total, jobs_passed, jobs_failed = _platform_evaluate_row(
|
|
237
|
+
root, draft
|
|
238
|
+
)
|
|
239
|
+
draft.update(
|
|
240
|
+
on_repository=on_repo,
|
|
241
|
+
finished=finished,
|
|
242
|
+
succeeded=succeeded,
|
|
243
|
+
ancestor=bool(known and behind is not None),
|
|
244
|
+
jobs_total=jobs_total,
|
|
245
|
+
jobs_passed=jobs_passed,
|
|
246
|
+
jobs_failed=jobs_failed,
|
|
247
|
+
green=bool(on_repo and finished and succeeded and known and behind is not None),
|
|
248
|
+
)
|
|
249
|
+
return draft
|
|
250
|
+
|
|
251
|
+
|
|
252
|
+
def record_platform_run(root, *, platform, run, gh=None, at=None):
|
|
253
|
+
"""Read a platform lane's CI run through `gh` and append what it says to the chained evidence ledger.
|
|
254
|
+
|
|
255
|
+
`platform` names the lane - windows, macos, linux, or whatever a lane is called - and is
|
|
256
|
+
written without case. `run` is the CI run's id, unique within its platform so an older run
|
|
257
|
+
cannot be re-appended over a newer one. `polyctl` reads the run itself through `gh run view` and
|
|
258
|
+
records what the run says: its number and creation time, its status and conclusion, its head
|
|
259
|
+
SHA (`commit`), its repository, and its jobs. A run that is not on this repository, not
|
|
260
|
+
finished, not successful, or not on a commit HEAD holds as an ancestor is recorded as such
|
|
261
|
+
(`green: False`) and never reads as green. Every row is chained and held to this machine's
|
|
262
|
+
checkpoint store (OPTIN-ATTESTED).
|
|
263
|
+
"""
|
|
264
|
+
platform_name = _platform_text(platform, "platform").lower()
|
|
265
|
+
run_id = _platform_text(run, "run")
|
|
266
|
+
if run_id.startswith("-"):
|
|
267
|
+
raise ValueError(f"the run must be a run id, not {run_id!r}")
|
|
268
|
+
when = int(time.time()) if at is None else _platform_count(at, "at")
|
|
269
|
+
for existing in platform_runs(root):
|
|
270
|
+
held = existing.get("run")
|
|
271
|
+
if (existing["platform"].strip().lower() == platform_name
|
|
272
|
+
and held is not None and not isinstance(held, bool)
|
|
273
|
+
and str(held).strip() == run_id):
|
|
274
|
+
raise ValueError(
|
|
275
|
+
f"{platform_name} run {run_id} is already recorded in {PLATFORM_RUNS_FILE}")
|
|
276
|
+
row = dict(read_platform_run(root, platform_name, run_id, gh=gh), at=when)
|
|
277
|
+
from .storage import append_chained_in_tree
|
|
278
|
+
return append_chained_in_tree(root, PLATFORM_RUNS_FILE, row, PLATFORM_RUNS_CHAIN)
|
|
279
|
+
|
|
280
|
+
|
|
281
|
+
def platform_runs(root):
|
|
282
|
+
"""Every recorded run this machine's checkpoint store attests, oldest first; [] when none is attested.
|
|
283
|
+
|
|
284
|
+
Only the prefix recorded by this machine's checkpoint store is read and validated
|
|
285
|
+
(OPTIN-ATTESTED); rows past it - written by hand or on another machine - do not count as
|
|
286
|
+
evidence here and never make polyctl's own rows unreadable (LANE-EVIDENCE). A row that names
|
|
287
|
+
no platform is left out, as `polyctl gain` leaves it out.
|
|
288
|
+
"""
|
|
289
|
+
from .storage import read_chained_in_tree
|
|
290
|
+
return [row for row in read_chained_in_tree(root, PLATFORM_RUNS_FILE, PLATFORM_RUNS_CHAIN)
|
|
291
|
+
if isinstance(row, dict) and isinstance(row.get("platform"), str)
|
|
292
|
+
and row["platform"].strip()]
|
|
293
|
+
|
|
294
|
+
|
|
295
|
+
def platform_run_reading(root, cfg, row):
|
|
296
|
+
"""One recorded run as it stands against this repository now, and whether it still vouches for it.
|
|
297
|
+
|
|
298
|
+
`behind` is how many commits HEAD has added since the run's commit when that commit is an
|
|
299
|
+
ancestor of HEAD, and `known` whether this repository holds that commit at all; both are
|
|
300
|
+
read from git, never guessed. A run that is not on this repository, not finished, not
|
|
301
|
+
successful, or not on a commit HEAD holds as an ancestor never reads as `green` and never
|
|
302
|
+
`vouches`. `stale` is a green ancestor run more than `evidence.max_commits_behind` commits
|
|
303
|
+
behind HEAD, and `vouches` is true only when `green` holds and the run is within the bound.
|
|
304
|
+
"""
|
|
305
|
+
commit = str(row.get("commit") or "").strip()
|
|
306
|
+
on_repo, finished, succeeded, known, behind, jobs_total, jobs_passed, jobs_failed = _platform_evaluate_row(
|
|
307
|
+
root, row
|
|
308
|
+
)
|
|
309
|
+
bound = settings.get(cfg, "evidence.max_commits_behind")
|
|
310
|
+
ancestor = known and behind is not None
|
|
311
|
+
green = bool(on_repo and finished and succeeded and ancestor)
|
|
312
|
+
stale = bool(green and behind > bound)
|
|
313
|
+
return {
|
|
314
|
+
"platform": row["platform"].strip().lower(),
|
|
315
|
+
"run": row.get("run"),
|
|
316
|
+
"number": row.get("number"),
|
|
317
|
+
"created_at": row.get("created_at") or "",
|
|
318
|
+
"suite": row.get("suite"),
|
|
319
|
+
"status": row.get("status") or "completed",
|
|
320
|
+
"conclusion": row.get("conclusion") if row.get("conclusion") is not None else "success",
|
|
321
|
+
"commit": commit,
|
|
322
|
+
"repository": row.get("repository") or "",
|
|
323
|
+
"on_repository": on_repo,
|
|
324
|
+
"finished": finished,
|
|
325
|
+
"succeeded": succeeded,
|
|
326
|
+
"jobs": row.get("jobs") if isinstance(row.get("jobs"), list) else [],
|
|
327
|
+
"jobs_total": jobs_total,
|
|
328
|
+
"jobs_passed": jobs_passed,
|
|
329
|
+
"jobs_failed": jobs_failed,
|
|
330
|
+
"at": row.get("at"),
|
|
331
|
+
"green": green,
|
|
332
|
+
"known": known,
|
|
333
|
+
"behind": behind,
|
|
334
|
+
"stale": stale,
|
|
335
|
+
"vouches": bool(green and not stale),
|
|
336
|
+
}
|
|
337
|
+
|
|
338
|
+
|
|
339
|
+
def platform_run_summaries(root, cfg):
|
|
340
|
+
"""The newest recorded run of each platform, as CI numbers and dates its runs, read against HEAD now.
|
|
341
|
+
|
|
342
|
+
CI's own creation time, run number, and run id decide which run of a platform is newest,
|
|
343
|
+
never which row was appended to the ledger last (LANE-EVIDENCE).
|
|
344
|
+
"""
|
|
345
|
+
newest = {}
|
|
346
|
+
for row in platform_runs(root):
|
|
347
|
+
platform = row["platform"].strip().lower()
|
|
348
|
+
if platform not in newest or _platform_run_order(row) > _platform_run_order(newest[platform]):
|
|
349
|
+
newest[platform] = row
|
|
350
|
+
return [platform_run_reading(root, cfg, newest[platform]) for platform in sorted(newest)]
|
|
351
|
+
|
|
352
|
+
|
|
353
|
+
def evidence_problems(cfg):
|
|
354
|
+
"""What `polyctl doctor --check` acts on about platform evidence, as (key, text); [] when nothing was recorded.
|
|
355
|
+
|
|
356
|
+
Absence is not a finding: a project that never recorded a platform run is not told its
|
|
357
|
+
evidence is red. A row that was recorded and no longer covers the tree is, and the newest
|
|
358
|
+
row of each platform decides alone - a green rerun clears what the run before it said.
|
|
359
|
+
"""
|
|
360
|
+
from .storage import _unattested_repair, unattested_in_tree
|
|
361
|
+
root = cfg["root"]
|
|
362
|
+
try:
|
|
363
|
+
foreign, attested = unattested_in_tree(root, PLATFORM_RUNS_FILE, PLATFORM_RUNS_CHAIN)
|
|
364
|
+
rows = platform_run_summaries(root, cfg)
|
|
365
|
+
except Exception as exc:
|
|
366
|
+
problem = " ".join(str(exc).split())
|
|
367
|
+
return [("evidence-ledger",
|
|
368
|
+
f"{PLATFORM_RUNS_FILE} cannot be read ({problem}); fix it as docs/telemetry.md shows, or "
|
|
369
|
+
"record a new run once it is gone")]
|
|
370
|
+
bound = settings.get(cfg, "evidence.max_commits_behind")
|
|
371
|
+
out = []
|
|
372
|
+
if foreign:
|
|
373
|
+
out.append(("evidence-unattested",
|
|
374
|
+
f"{PLATFORM_RUNS_FILE} holds {_unattested_repair(foreign, attested)}"))
|
|
375
|
+
for row in rows:
|
|
376
|
+
platform, where = row["platform"], f"run {row.get('run') or '?'}"
|
|
377
|
+
commit = row.get("commit") or ""
|
|
378
|
+
if not row["on_repository"]:
|
|
379
|
+
repo = row.get("repository") or "another repository"
|
|
380
|
+
out.append((f"evidence-red:{platform}",
|
|
381
|
+
f"{platform}'s newest recorded {where} is from {repo}, not this repository — "
|
|
382
|
+
f"run the {platform} lane on this repository and record it"))
|
|
383
|
+
elif not row["finished"]:
|
|
384
|
+
status = row.get("status") or "unfinished"
|
|
385
|
+
out.append((f"evidence-red:{platform}",
|
|
386
|
+
f"{platform}'s newest recorded {where} is not finished ({status}) at "
|
|
387
|
+
f"{commit[:10] or 'no commit'} — wait for the {platform} lane to finish and record it"))
|
|
388
|
+
elif not row["succeeded"]:
|
|
389
|
+
if row.get("jobs_total") == 0:
|
|
390
|
+
why = f"ran no {platform} job"
|
|
391
|
+
elif row.get("jobs_failed"):
|
|
392
|
+
why = f"failed {row['jobs_failed']} job(s) ({row.get('conclusion') or 'failure'})"
|
|
393
|
+
else:
|
|
394
|
+
why = f"ended {row.get('conclusion') or 'unsuccessfully'}"
|
|
395
|
+
out.append((f"evidence-red:{platform}",
|
|
396
|
+
f"{platform}'s newest recorded {where} {why} at "
|
|
397
|
+
f"{commit[:10] or 'no commit'} — rerun the {platform} lane and record it when it passes"))
|
|
398
|
+
elif not row["known"]:
|
|
399
|
+
what = ("names no commit" if not commit
|
|
400
|
+
else f"names commit {commit[:10]}, which this repository cannot resolve")
|
|
401
|
+
out.append((f"evidence-unresolved:{platform}",
|
|
402
|
+
f"{platform}'s newest recorded {where} {what}, so nothing says which tree it ran — "
|
|
403
|
+
f"rerun the {platform} lane on HEAD and record it"))
|
|
404
|
+
elif row["behind"] is None:
|
|
405
|
+
out.append((f"evidence-unresolved:{platform}",
|
|
406
|
+
f"{platform}'s newest recorded {where} is at {commit[:10]}, which is not an ancestor of "
|
|
407
|
+
f"HEAD — rerun the {platform} lane on HEAD and record it"))
|
|
408
|
+
elif row["stale"]:
|
|
409
|
+
out.append((f"evidence-stale:{platform}",
|
|
410
|
+
f"{platform}'s newest recorded {where} is {row['behind']} commit(s) behind HEAD "
|
|
411
|
+
f"(evidence.max_commits_behind {bound}) — rerun the {platform} lane and record it"))
|
|
412
|
+
return out
|