workorder 0.5.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.
- workorder/__init__.py +3 -0
- workorder/__main__.py +3 -0
- workorder/cli.py +198 -0
- workorder/gate.py +1292 -0
- workorder/store.py +1164 -0
- workorder-0.5.0.dist-info/METADATA +397 -0
- workorder-0.5.0.dist-info/RECORD +11 -0
- workorder-0.5.0.dist-info/WHEEL +5 -0
- workorder-0.5.0.dist-info/entry_points.txt +2 -0
- workorder-0.5.0.dist-info/licenses/LICENSE +21 -0
- workorder-0.5.0.dist-info/top_level.txt +1 -0
workorder/gate.py
ADDED
|
@@ -0,0 +1,1292 @@
|
|
|
1
|
+
"""Derive completion from receipts; a status line never supplies missing proof."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import json
|
|
6
|
+
import posixpath
|
|
7
|
+
import subprocess
|
|
8
|
+
import uuid
|
|
9
|
+
|
|
10
|
+
from . import store as s
|
|
11
|
+
|
|
12
|
+
|
|
13
|
+
def contract_debt(root, record, history, implemented, staged=False):
|
|
14
|
+
path = record["contract"]
|
|
15
|
+
if path == "none":
|
|
16
|
+
return []
|
|
17
|
+
try:
|
|
18
|
+
contract = json.loads(s.read_text(root, path, staged))
|
|
19
|
+
except json.JSONDecodeError as error:
|
|
20
|
+
raise s.Refused(f"{record['id']}: contract {path} is not valid JSON"
|
|
21
|
+
f" ({error.msg}, line {error.lineno})") from None
|
|
22
|
+
if not isinstance(contract, dict) or contract.get("task") != record["id"]:
|
|
23
|
+
raise s.Refused("contract must name its task")
|
|
24
|
+
criteria = contract.get("criteria")
|
|
25
|
+
if not isinstance(criteria, list) or not criteria:
|
|
26
|
+
raise s.Refused("contract needs a nonempty criteria list")
|
|
27
|
+
debts, seen = [], set()
|
|
28
|
+
for item in criteria:
|
|
29
|
+
if not isinstance(item, dict):
|
|
30
|
+
raise s.Refused("criterion must be an object")
|
|
31
|
+
cid = item.get("id")
|
|
32
|
+
if not isinstance(cid, str) or not cid or cid in seen:
|
|
33
|
+
raise s.Refused("criterion ids must be distinct nonempty strings")
|
|
34
|
+
seen.add(cid)
|
|
35
|
+
if (not isinstance(item.get("ask"), str) or not item["ask"].strip()
|
|
36
|
+
or type(item.get("critical")) is not bool
|
|
37
|
+
or item.get("requires") not in {"REAL", "REAL_OR_TEST"}
|
|
38
|
+
or not isinstance(item.get("evidence"), list)):
|
|
39
|
+
raise s.Refused(f"{cid}: need ask, critical, requires and evidence")
|
|
40
|
+
proved = False
|
|
41
|
+
for evidence in item["evidence"]:
|
|
42
|
+
if (not isinstance(evidence, dict)
|
|
43
|
+
or evidence.get("provenance") not in {"REAL", "TEST", "MOCK", "SYNTHETIC", "UNKNOWN"}
|
|
44
|
+
or not isinstance(evidence.get("ref"), str) or not evidence["ref"]):
|
|
45
|
+
raise s.Refused(f"{cid}: every evidence item needs provenance and ref")
|
|
46
|
+
provenance = evidence["provenance"]
|
|
47
|
+
if provenance == "REAL":
|
|
48
|
+
try:
|
|
49
|
+
artifact = s.read_bytes(root, evidence["ref"], staged)
|
|
50
|
+
except (OSError, s.Refused):
|
|
51
|
+
continue # a missing evidence file proves nothing; the criterion stays owed
|
|
52
|
+
proved |= s.digest(artifact) == evidence.get("sha256")
|
|
53
|
+
elif provenance == "TEST" and item["requires"] != "REAL":
|
|
54
|
+
proved |= any(evidence["ref"] in {"receipt:" + entry["hash"],
|
|
55
|
+
"receipt:" + entry.get("legacy", {}).get("hash", "")}
|
|
56
|
+
and entry["kind"] == "test" and entry["exit_code"] == 0
|
|
57
|
+
and entry["valid"] and implemented is not None and not entry["missing"]
|
|
58
|
+
and entry["code"] == implemented["code"] for entry in history)
|
|
59
|
+
if item["critical"] and not proved:
|
|
60
|
+
debts.append(f"contract {cid}: {item['requires']} evidence")
|
|
61
|
+
return debts
|
|
62
|
+
|
|
63
|
+
|
|
64
|
+
ANY_TEST = "any"
|
|
65
|
+
|
|
66
|
+
|
|
67
|
+
def declared_test(record):
|
|
68
|
+
"""The task's own test command as an argument list, or None when any command counts: no test
|
|
69
|
+
declared (which DONE refuses) or the explicit opt-out test: any."""
|
|
70
|
+
value = record.get("test", "").strip()
|
|
71
|
+
return s.split_command(value) if value and value != ANY_TEST else None
|
|
72
|
+
|
|
73
|
+
|
|
74
|
+
def counting_runs(record, current, implemented):
|
|
75
|
+
"""Test runs that can decide: on the implemented code, on a commit in this clone, and the task's
|
|
76
|
+
declared test command when it has one."""
|
|
77
|
+
declared = declared_test(record)
|
|
78
|
+
return [e for e in current if e["kind"] == "test" and not e["missing"]
|
|
79
|
+
and e["code"] == implemented["code"] and (declared is None or e["command"] == declared)]
|
|
80
|
+
|
|
81
|
+
|
|
82
|
+
def carries(root, implemented, item):
|
|
83
|
+
"""A merge or deployment carries the tested code when it holds exactly that code, or when its commit
|
|
84
|
+
contains the implemented commit (a merge commit or fast-forward, with other work beside it)."""
|
|
85
|
+
return (implemented is not None and not implemented["missing"] and not item["missing"]
|
|
86
|
+
and (item["code"] == implemented["code"]
|
|
87
|
+
or s.contains(root, implemented["commit"], item["commit"])))
|
|
88
|
+
|
|
89
|
+
|
|
90
|
+
def code_seen(root, tid, code, staged=False):
|
|
91
|
+
"""A commit in this clone that holds exactly this code: HEAD, or a commit that touched the task or
|
|
92
|
+
its receipts (a squash merge does). None when there is none."""
|
|
93
|
+
candidates = ["HEAD"] + s.git(root, "log", "--format=%H", "-n", "50", "HEAD", "--", f"tasks/{tid}.md",
|
|
94
|
+
s.ledger_path(tid), f".workorder/receipts/{tid}",
|
|
95
|
+
f".notquite/receipts/{tid}.jsonl", required=False).stdout.split()
|
|
96
|
+
for commit in candidates:
|
|
97
|
+
found = s.git(root, "rev-parse", "--verify", "--quiet", f"{commit}^{{commit}}", required=False)
|
|
98
|
+
if found.returncode == 0 and s.code_digest(root, found.stdout.strip()) == code:
|
|
99
|
+
return found.stdout.strip()
|
|
100
|
+
return None
|
|
101
|
+
|
|
102
|
+
|
|
103
|
+
def recognise_squashed(root, tid, history, staged=False):
|
|
104
|
+
"""Receipts whose commits are gone (squash, rebase, amend) count again when a commit in this clone
|
|
105
|
+
holds exactly the code they recorded: the evidence is about that code, and the code is here."""
|
|
106
|
+
implemented = newest_implementation(history)
|
|
107
|
+
if implemented is None or not implemented["missing"]:
|
|
108
|
+
return
|
|
109
|
+
seen = code_seen(root, tid, implemented["code"], staged)
|
|
110
|
+
if not seen:
|
|
111
|
+
merged = computed_merge(root, s.record(root, tid, staged), implemented)
|
|
112
|
+
if merged and merged["method"] == "same code":
|
|
113
|
+
seen = merged["commit"]
|
|
114
|
+
if seen:
|
|
115
|
+
for item in history:
|
|
116
|
+
if item["missing"] and item["code"] == implemented["code"]:
|
|
117
|
+
item["missing"], item["seen_on"] = False, seen
|
|
118
|
+
|
|
119
|
+
|
|
120
|
+
# Limit both sides of a patch comparison. An incomplete search never proves a rebase.
|
|
121
|
+
MERGE_SEARCH_LIMIT = 1000
|
|
122
|
+
|
|
123
|
+
|
|
124
|
+
def merge_target(root, record):
|
|
125
|
+
# The pushed branch first: a commit only on local main is not merged for anyone else yet.
|
|
126
|
+
override = record.get("merge_ref")
|
|
127
|
+
refs = [override] if override else ["refs/remotes/origin/main", "refs/remotes/origin/master",
|
|
128
|
+
"refs/heads/main", "refs/heads/master"]
|
|
129
|
+
for ref in refs:
|
|
130
|
+
found = s.git(root, "rev-parse", "--verify", "--quiet", f"{ref}^{{commit}}", required=False)
|
|
131
|
+
if found.returncode == 0:
|
|
132
|
+
return ref, found.stdout.strip()
|
|
133
|
+
return None
|
|
134
|
+
|
|
135
|
+
|
|
136
|
+
def patch_ids(root, revision, commits=None):
|
|
137
|
+
"""git cherry semantics, restricted to code, in two Git calls for the whole range."""
|
|
138
|
+
selection = (["--no-walk=unsorted", "--diff-merges=first-parent", *commits] if commits is not None
|
|
139
|
+
else ["--no-merges", f"--max-count={MERGE_SEARCH_LIMIT + 1}", revision])
|
|
140
|
+
if commits == []:
|
|
141
|
+
return {}
|
|
142
|
+
patches = s.git(root, "log", *selection, "--format=commit %H", "-p", "--binary", "--no-renames",
|
|
143
|
+
"--no-ext-diff", "--no-textconv", "--", *s.CODE_PATHS).stdout
|
|
144
|
+
result = s.git(root, "patch-id", "--stable", data=patches).stdout
|
|
145
|
+
return {commit: patch for patch, commit in (line.split() for line in result.splitlines())}
|
|
146
|
+
|
|
147
|
+
|
|
148
|
+
def merge_match(root, implemented, target):
|
|
149
|
+
"""Evidence from immutable commits, cached independently of branch names and HEAD."""
|
|
150
|
+
original = implemented["commit"]
|
|
151
|
+
key = s.digest(s.packed(["merge-v4", original, s.has_commit(root, original), implemented["code"],
|
|
152
|
+
target, MERGE_SEARCH_LIMIT]).encode())
|
|
153
|
+
folder = s._cache_dir(root)
|
|
154
|
+
cached = folder / ("merge-" + key + ".json") if folder else None
|
|
155
|
+
try:
|
|
156
|
+
if cached and cached.is_file():
|
|
157
|
+
value = json.loads(cached.read_text(encoding="utf-8"))
|
|
158
|
+
if value is None or (isinstance(value, dict) and value.get("method") in
|
|
159
|
+
{"ancestry", "same code", "squash", "rebase"} and s.has_commit(root, value.get("commit", ""))):
|
|
160
|
+
return value
|
|
161
|
+
except (OSError, ValueError):
|
|
162
|
+
pass
|
|
163
|
+
result = _merge_match(root, implemented, target)
|
|
164
|
+
try:
|
|
165
|
+
if cached:
|
|
166
|
+
folder.mkdir(exist_ok=True)
|
|
167
|
+
# Atomic replacement keeps concurrent checks from reading a partial cache file.
|
|
168
|
+
temporary = cached.with_suffix("." + uuid.uuid4().hex)
|
|
169
|
+
temporary.write_text(s.packed(result), encoding="utf-8")
|
|
170
|
+
temporary.replace(cached)
|
|
171
|
+
except OSError:
|
|
172
|
+
pass
|
|
173
|
+
return result
|
|
174
|
+
|
|
175
|
+
|
|
176
|
+
def _merge_match(root, implemented, target):
|
|
177
|
+
original = implemented["commit"]
|
|
178
|
+
present = s.has_commit(root, original)
|
|
179
|
+
if present and s.contains(root, original, target):
|
|
180
|
+
# Name the landing, not a moving tip that may have undone the tested code.
|
|
181
|
+
mainline = s.git(root, "rev-list", "--first-parent", target).stdout.split()
|
|
182
|
+
if original in mainline:
|
|
183
|
+
landing = original
|
|
184
|
+
else:
|
|
185
|
+
descendants = set(s.git(root, "rev-list", "--ancestry-path", f"{original}..{target}").stdout.split())
|
|
186
|
+
landing = next(commit for commit in reversed(mainline) if commit in descendants)
|
|
187
|
+
return {"method": "ancestry", "commit": landing}
|
|
188
|
+
base = s.git(root, "merge-base", original, target, required=False).stdout.strip() if present else ""
|
|
189
|
+
revision = f"{base}..{target}" if base else target
|
|
190
|
+
# Only code-changing commits can supply a same-code or patch match.
|
|
191
|
+
candidates = s.git(root, "rev-list", f"--max-count={MERGE_SEARCH_LIMIT}", revision).stdout.split()
|
|
192
|
+
target_patches = patch_ids(root, revision, candidates)
|
|
193
|
+
for commit in reversed(target_patches):
|
|
194
|
+
if s.code_digest(root, commit) == implemented["code"]:
|
|
195
|
+
return {"method": "same code", "commit": commit}
|
|
196
|
+
if not base:
|
|
197
|
+
return None
|
|
198
|
+
combined = s.git(root, "diff", "--binary", "--no-renames", "--no-ext-diff", "--no-textconv",
|
|
199
|
+
base, original, "--", *s.CODE_PATHS).stdout
|
|
200
|
+
combined_id = s.git(root, "patch-id", "--stable", data=combined).stdout.split()
|
|
201
|
+
if combined_id:
|
|
202
|
+
for commit, patch in reversed(list(target_patches.items())):
|
|
203
|
+
if patch == combined_id[0]:
|
|
204
|
+
return {"method": "squash", "commit": commit}
|
|
205
|
+
# Count all commits (including merges and metadata) so truncation cannot look complete.
|
|
206
|
+
feature = s.git(root, "rev-list", f"--max-count={MERGE_SEARCH_LIMIT + 1}", f"{base}..{original}").stdout.split()
|
|
207
|
+
if len(feature) > MERGE_SEARCH_LIMIT:
|
|
208
|
+
return None
|
|
209
|
+
feature_patches = patch_ids(root, f"{base}..{original}")
|
|
210
|
+
# A merge's own resolution is not represented by git cherry; do not silently skip it.
|
|
211
|
+
merges = s.git(root, "rev-list", "--merges", f"{base}..{original}", "--", *s.CODE_PATHS).stdout.split()
|
|
212
|
+
available = set(target_patches.values())
|
|
213
|
+
if not merges and feature_patches and set(feature_patches.values()) <= available:
|
|
214
|
+
representatives = {patch: commit for commit, patch in target_patches.items()
|
|
215
|
+
if patch in set(feature_patches.values())}
|
|
216
|
+
matched = next(commit for commit in target_patches if commit in set(representatives.values()))
|
|
217
|
+
if not all(s.contains(root, representatives[patch], matched) for patch in feature_patches.values()):
|
|
218
|
+
matched = target # patches on separate merged branches must all be present in a deployment
|
|
219
|
+
return {"method": "rebase", "commit": matched}
|
|
220
|
+
return None
|
|
221
|
+
|
|
222
|
+
|
|
223
|
+
def computed_merge(root, record, implemented):
|
|
224
|
+
if record["ships"] == "none" or implemented is None:
|
|
225
|
+
return None
|
|
226
|
+
target = merge_target(root, record)
|
|
227
|
+
if target is None:
|
|
228
|
+
return None
|
|
229
|
+
ref, commit = target
|
|
230
|
+
# Always inspect the selected target. HEAD on a feature branch is never a fallback target.
|
|
231
|
+
match = merge_match(root, implemented, commit)
|
|
232
|
+
if match:
|
|
233
|
+
return {**match, "ref": ref, "target": commit}
|
|
234
|
+
return None
|
|
235
|
+
|
|
236
|
+
|
|
237
|
+
def merge_line(merged):
|
|
238
|
+
ref = merged["ref"].removeprefix("refs/heads/").removeprefix("refs/remotes/")
|
|
239
|
+
return f"merged into {ref} by {merged['method']} {merged['commit'][:7]}, computed"
|
|
240
|
+
|
|
241
|
+
|
|
242
|
+
def delivered_code(root, implemented, item, computed=None):
|
|
243
|
+
return carries(root, implemented, item) or bool(
|
|
244
|
+
computed and not item["missing"] and s.contains(root, computed["commit"], item["commit"]))
|
|
245
|
+
|
|
246
|
+
|
|
247
|
+
def verdict(root, record, staged=False):
|
|
248
|
+
tid = record["id"]
|
|
249
|
+
history = s.entries(root, tid, staged)
|
|
250
|
+
recognise_squashed(root, tid, history, staged)
|
|
251
|
+
index = max((i for i, e in enumerate(history) if e["kind"] == "implemented"), default=-1)
|
|
252
|
+
implemented = history[index] if index >= 0 else None
|
|
253
|
+
current = history[index + 1:] if implemented else []
|
|
254
|
+
done = []
|
|
255
|
+
if not record.get("test", "").strip():
|
|
256
|
+
done.append("a declared test") # the command that proves the task, or test: any
|
|
257
|
+
if not implemented:
|
|
258
|
+
done.append("implementation")
|
|
259
|
+
elif implemented["missing"]:
|
|
260
|
+
done.append(f"implementation (commit {implemented['commit'][:7]} is not in this clone)")
|
|
261
|
+
else:
|
|
262
|
+
# The latest test run on the implemented code decides; a later failure revokes an earlier pass.
|
|
263
|
+
# Code leaves out tasks/ and .workorder/, so committing the receipts does not hide later runs.
|
|
264
|
+
runs = counting_runs(record, current, implemented)
|
|
265
|
+
if not runs or runs[-1]["exit_code"] != 0 or not runs[-1]["valid"]:
|
|
266
|
+
done.append(f"a passing test on {implemented['commit'][:7]}")
|
|
267
|
+
done += contract_debt(root, record, current, implemented, staged)
|
|
268
|
+
delivery = []
|
|
269
|
+
computed = computed_merge(root, record, implemented)
|
|
270
|
+
if record["ships"] != "none":
|
|
271
|
+
# Any merge receipt that carries the tested code counts; a later one that does not, cannot undo it.
|
|
272
|
+
merges = [i for i, e in enumerate(current) if e["kind"] == "merged" and carries(root, implemented, e)]
|
|
273
|
+
merge_index = merges[-1] if merges else -1
|
|
274
|
+
merged = current[merge_index] if merges else computed
|
|
275
|
+
if not merged:
|
|
276
|
+
delivery.append("merge of the tested code")
|
|
277
|
+
if record["ships"] == "live":
|
|
278
|
+
after_merge = current if computed else current[merge_index + 1:] if merged else []
|
|
279
|
+
deploy_index = max((i for i, e in enumerate(after_merge) if e["kind"] == "deployed"), default=-1)
|
|
280
|
+
deployed = after_merge[deploy_index] if deploy_index >= 0 else None
|
|
281
|
+
if (not deployed or not deployed["valid"] or deployed["exit_code"] != 0
|
|
282
|
+
or not delivered_code(root, implemented, deployed, computed)):
|
|
283
|
+
delivery.append("deployment read-back of the tested code")
|
|
284
|
+
after_deploy = after_merge[deploy_index + 1:] if deployed else []
|
|
285
|
+
if not deployed or not any(e["kind"] == "live" and e["valid"] and e["exit_code"] == 0
|
|
286
|
+
and not e["missing"] and e["commit"] == deployed["commit"]
|
|
287
|
+
and e["target"] == deployed["target"] for e in after_deploy):
|
|
288
|
+
delivery.append("live read-back after deployment")
|
|
289
|
+
computed = "IN_PROGRESS" if done else "DONE" if delivery else "CLOSED"
|
|
290
|
+
return computed, done, delivery
|
|
291
|
+
|
|
292
|
+
|
|
293
|
+
def task_names(root, staged=False):
|
|
294
|
+
"""Ids of the task files: tasks/<ID>.md. Other files there (a README, notes, subfolders) are not tasks."""
|
|
295
|
+
names = []
|
|
296
|
+
for path in s.files(root, "tasks", staged):
|
|
297
|
+
name = path.removeprefix("tasks/")
|
|
298
|
+
if name.endswith(".md") and "/" not in name and s.ID.fullmatch(name[:-3]):
|
|
299
|
+
names.append(name[:-3])
|
|
300
|
+
return names
|
|
301
|
+
|
|
302
|
+
|
|
303
|
+
def records(root, staged=False, errors=None):
|
|
304
|
+
"""Task records by id. With errors (a dict), a task file that cannot be read is reported there and
|
|
305
|
+
left out, so one bad file does not stop the others; without it, the first bad file is refused."""
|
|
306
|
+
result = {}
|
|
307
|
+
for tid in task_names(root, staged):
|
|
308
|
+
try:
|
|
309
|
+
result[tid] = s.record(root, tid, staged)
|
|
310
|
+
except s.Refused as error:
|
|
311
|
+
if errors is None:
|
|
312
|
+
raise
|
|
313
|
+
errors[tid] = str(error)
|
|
314
|
+
return result
|
|
315
|
+
|
|
316
|
+
|
|
317
|
+
def waits(record, all_records, views, seen=frozenset()):
|
|
318
|
+
"""Open dependencies: person waits, and tasks that are not finished."""
|
|
319
|
+
result = []
|
|
320
|
+
for wait in s.dependencies(record):
|
|
321
|
+
kind, value = wait.split(":", 1)
|
|
322
|
+
if kind == "person" or not finished(value, all_records, views, seen):
|
|
323
|
+
result.append(wait)
|
|
324
|
+
return result
|
|
325
|
+
|
|
326
|
+
|
|
327
|
+
def finished(tid, all_records, views, seen=frozenset()):
|
|
328
|
+
"""A dependency is finished when its evidence computes DONE or CLOSED and its own dependencies are
|
|
329
|
+
finished, all the way down. A cycle never counts as finished."""
|
|
330
|
+
# Finished means the task says DONE or CLOSED and its evidence supports that: a reopened task
|
|
331
|
+
# (status set back to IN_PROGRESS) holds back the tasks that depend on it, as does a cancelled one.
|
|
332
|
+
if (tid not in all_records or tid in seen or views[tid][0] not in {"DONE", "CLOSED"}
|
|
333
|
+
or all_records[tid]["status"] not in {"DONE", "CLOSED"}):
|
|
334
|
+
return False
|
|
335
|
+
return not waits(all_records[tid], all_records, views, seen | {tid})
|
|
336
|
+
|
|
337
|
+
|
|
338
|
+
@s.cached_read
|
|
339
|
+
def fields_at(root, tid, rev="HEAD"):
|
|
340
|
+
"""The front matter of tasks/<tid>.md at a revision, or None if it has no readable record there."""
|
|
341
|
+
text = s.metadata_texts(root, rev, tid if rev != "HEAD" else None, False).get(f"tasks/{tid}.md")
|
|
342
|
+
if text is None:
|
|
343
|
+
return None
|
|
344
|
+
lines = text.splitlines()
|
|
345
|
+
try:
|
|
346
|
+
return s.front_matter(tid, lines[1:lines.index("---", 1)])
|
|
347
|
+
except (s.Refused, ValueError):
|
|
348
|
+
return None
|
|
349
|
+
|
|
350
|
+
|
|
351
|
+
def committed_status(root, tid, rev="HEAD"):
|
|
352
|
+
"""The status line of tasks/<tid>.md at a revision, or None if it has no readable record there."""
|
|
353
|
+
fields = fields_at(root, tid, rev)
|
|
354
|
+
return fields.get("status") if fields else None
|
|
355
|
+
|
|
356
|
+
|
|
357
|
+
def newest_implementation(history):
|
|
358
|
+
index = max((i for i, e in enumerate(history) if e["kind"] == "implemented"), default=-1)
|
|
359
|
+
return history[index] if index >= 0 else None
|
|
360
|
+
|
|
361
|
+
|
|
362
|
+
def base_problems(root, base, staged=False, retired=frozenset()):
|
|
363
|
+
"""Receipts committed on the base revision must still be there, unchanged, as a prefix."""
|
|
364
|
+
found = s.git(root, "rev-parse", "--verify", "--quiet", f"{base}^{{commit}}", required=False)
|
|
365
|
+
if found.returncode:
|
|
366
|
+
raise s.Refused(f"base {base} is not in this clone; fetch it"
|
|
367
|
+
" (in GitHub Actions: actions/checkout with fetch-depth: 0)")
|
|
368
|
+
commit = found.stdout.strip()
|
|
369
|
+
problems = []
|
|
370
|
+
tids = {s.receipt_task(p) for p in s.receipt_paths(root, rev=commit)} - {None}
|
|
371
|
+
for tid in sorted(tids):
|
|
372
|
+
if tid in retired:
|
|
373
|
+
continue
|
|
374
|
+
before = s.receipt_texts(root, tid, rev=commit)
|
|
375
|
+
after = s.receipt_texts(root, tid, staged)
|
|
376
|
+
try:
|
|
377
|
+
history = s.ordered_entries(root, tid, after)
|
|
378
|
+
except (s.Refused, ValueError):
|
|
379
|
+
history = None
|
|
380
|
+
if s.receipt_changes(root, tid, before, after, history):
|
|
381
|
+
problems.append(f"{tid}: receipts recorded on {base} were removed or changed")
|
|
382
|
+
# Endpoints miss a receipt added and then hidden, or edited and restored, in this range.
|
|
383
|
+
changed = s.git(root, "log", "--format=", "--name-only", "-z", "--diff-filter=DMT",
|
|
384
|
+
"--no-renames", "-m", "--full-history", f"{commit}..HEAD", "--",
|
|
385
|
+
*s.RECEIPT_DIRS).stdout
|
|
386
|
+
for path in sorted(set(changed.split("\0")) - {""}):
|
|
387
|
+
tid = s.receipt_task(path)
|
|
388
|
+
if tid and tid not in retired:
|
|
389
|
+
problems.append(f"{tid}: committed receipt file removed or changed since {base}: {path}")
|
|
390
|
+
return problems
|
|
391
|
+
|
|
392
|
+
|
|
393
|
+
def implementation_at(root, rev, tid):
|
|
394
|
+
"""Use the same receipt order for historical claims as for current verdicts."""
|
|
395
|
+
return newest_implementation(s.entries(root, tid, rev=rev))
|
|
396
|
+
|
|
397
|
+
|
|
398
|
+
FINISHED = {"DONE", "CLOSED"}
|
|
399
|
+
ACCEPTANCE_NOTE = ("the evidence covers the task's test only, not its Acceptance list;"
|
|
400
|
+
" finish every Acceptance item before claiming DONE")
|
|
401
|
+
UNCLAIMED_OWES = "its Acceptance items, then status DONE (the evidence for its test is in place)"
|
|
402
|
+
|
|
403
|
+
|
|
404
|
+
def owes(record, owed, delivery=()):
|
|
405
|
+
"""What a task still owes. A task nobody has claimed finished is never 'owing nothing'."""
|
|
406
|
+
items = list(owed)
|
|
407
|
+
if not items and record["status"] not in FINISHED | {"CANCELLED"}:
|
|
408
|
+
items.append(UNCLAIMED_OWES)
|
|
409
|
+
return ", ".join(items + list(delivery)) or "nothing"
|
|
410
|
+
|
|
411
|
+
|
|
412
|
+
@s.cached_read
|
|
413
|
+
def task_history(root, base=None):
|
|
414
|
+
"""One history walk for a linear task history. Merge histories keep Git's per-path simplification."""
|
|
415
|
+
log = s.git(root, "log", "--full-history", "--format=commit %H %P", "--raw", "--no-abbrev",
|
|
416
|
+
"--no-renames", f"{base}..HEAD" if base else "HEAD", "--", "tasks").stdout
|
|
417
|
+
changes, commit = {}, None
|
|
418
|
+
for line in log.splitlines():
|
|
419
|
+
if line.startswith("commit "):
|
|
420
|
+
words = line.split()
|
|
421
|
+
if len(words) > 3:
|
|
422
|
+
return None # a merge needs the same path-specific history used by earlier releases
|
|
423
|
+
commit = words[1]
|
|
424
|
+
elif line.startswith(":") and "\t" in line:
|
|
425
|
+
info, path = line.split("\t", 1)
|
|
426
|
+
tid = path.removeprefix("tasks/").removesuffix(".md")
|
|
427
|
+
if path == f"tasks/{tid}.md" and s.ID.fullmatch(tid):
|
|
428
|
+
oid = info.split()[3]
|
|
429
|
+
changes.setdefault(tid, []).append((commit, oid))
|
|
430
|
+
blobs = s.read_blobs(root, {oid for items in changes.values() for _, oid in items if set(oid) != {"0"}})
|
|
431
|
+
result = {}
|
|
432
|
+
for tid, items in changes.items():
|
|
433
|
+
statuses = []
|
|
434
|
+
for commit, oid in items:
|
|
435
|
+
lines = blobs.get(oid, "").splitlines()
|
|
436
|
+
try:
|
|
437
|
+
fields = s.front_matter(tid, lines[1:lines.index("---", 1)])
|
|
438
|
+
except (ValueError, s.Refused):
|
|
439
|
+
fields = {}
|
|
440
|
+
statuses.append((commit, fields.get("status")))
|
|
441
|
+
result[tid] = statuses
|
|
442
|
+
return result
|
|
443
|
+
|
|
444
|
+
|
|
445
|
+
def stale_claim(root, record, staged=False, base=None):
|
|
446
|
+
"""A DONE or CLOSED claim must be made on the code of the implementation it relies on.
|
|
447
|
+
|
|
448
|
+
An uncommitted claim is compared with the code being committed (the index under --staged, HEAD
|
|
449
|
+
otherwise). A committed claim is found in the task file's history (since base, when given) and
|
|
450
|
+
compared with the code of the commit that made it, unless the evidence was renewed after it.
|
|
451
|
+
"""
|
|
452
|
+
tid, status = record["id"], record["status"]
|
|
453
|
+
if status not in FINISHED:
|
|
454
|
+
return None
|
|
455
|
+
current = newest_implementation(s.entries(root, tid, staged))
|
|
456
|
+
if current is None or current["missing"]:
|
|
457
|
+
return None # the verdict already reports these
|
|
458
|
+
short = current["commit"][:7]
|
|
459
|
+
if committed_status(root, tid) != status:
|
|
460
|
+
dirty = [] if staged else s.dirty_paths(root)
|
|
461
|
+
if dirty:
|
|
462
|
+
return (f"NOT QUITE {tid} is being marked {status} with uncommitted code changes; "
|
|
463
|
+
+ s.describe_dirty(dirty) + f". Commit, record workorder receipt implemented --task {tid}"
|
|
464
|
+
" and test again.")
|
|
465
|
+
tree = s.git(root, "write-tree").stdout.strip() if staged else s.head(root)
|
|
466
|
+
if claim_matches(root, record, current, s.head(root), tree):
|
|
467
|
+
return None
|
|
468
|
+
where = "in this commit" if staged else "now"
|
|
469
|
+
return (f"NOT QUITE {tid} is being marked {status}, but the code {where} differs from the"
|
|
470
|
+
f" implemented commit {short}. Record workorder receipt implemented --task {tid} and test again.")
|
|
471
|
+
histories = task_history(root, base)
|
|
472
|
+
if histories is None:
|
|
473
|
+
commits = s.git(root, "log", "--format=%H", f"{base}..HEAD" if base else "HEAD", "--",
|
|
474
|
+
f"tasks/{tid}.md").stdout.split()
|
|
475
|
+
statuses = ((commit, committed_status(root, tid, commit)) for commit in commits)
|
|
476
|
+
else:
|
|
477
|
+
statuses = histories.get(tid, [])
|
|
478
|
+
claim = None
|
|
479
|
+
for commit, status_at_commit in statuses: # newest first: find the commit that made the claim
|
|
480
|
+
if status_at_commit != status:
|
|
481
|
+
break
|
|
482
|
+
claim = commit
|
|
483
|
+
else:
|
|
484
|
+
if base and committed_status(root, tid, base) == status:
|
|
485
|
+
claim = None # claimed before the base
|
|
486
|
+
if claim is None:
|
|
487
|
+
return None
|
|
488
|
+
relied_on = implementation_at(root, claim, tid)
|
|
489
|
+
if relied_on is None or current["hash"] != relied_on.get("hash"):
|
|
490
|
+
return None
|
|
491
|
+
if claim_matches(root, record, current, claim):
|
|
492
|
+
return None
|
|
493
|
+
return (f"NOT QUITE {tid} was marked {status} in {claim[:7]} on code other than the implemented"
|
|
494
|
+
f" commit {short}. Run workorder renew --task {tid} on that code, or record"
|
|
495
|
+
f" workorder receipt implemented --task {tid} and test again.")
|
|
496
|
+
|
|
497
|
+
|
|
498
|
+
def claim_matches(root, record, implemented, claim, tree=None):
|
|
499
|
+
tree = tree or claim
|
|
500
|
+
# This concerns the claim's history, even when the task ships nothing.
|
|
501
|
+
target = merge_target(root, record)
|
|
502
|
+
merged = merge_match(root, implemented, target[1]) if target else None
|
|
503
|
+
if merged and s.contains(root, merged["commit"], claim):
|
|
504
|
+
return unchanged_implementation_paths(root, implemented, merged, tree)
|
|
505
|
+
if s.code_digest(root, tree) == implemented["code"]:
|
|
506
|
+
return True
|
|
507
|
+
if merged and s.contains(root, claim, merged["commit"]):
|
|
508
|
+
# Landing must not invalidate a claim whose patch matched before it landed.
|
|
509
|
+
before = s.git(root, "rev-parse", "--verify", "--quiet", f"{merged['commit']}^1",
|
|
510
|
+
required=False).stdout.strip()
|
|
511
|
+
if before and equivalent_claim(root, record, implemented, tree, before):
|
|
512
|
+
return True
|
|
513
|
+
return tree == claim and equivalent_claim(root, record, implemented, claim)
|
|
514
|
+
|
|
515
|
+
|
|
516
|
+
def unchanged_implementation_paths(root, implemented, merged, claim):
|
|
517
|
+
"""Only changes on implementation paths can invalidate a claim after its landing."""
|
|
518
|
+
original, landing = implemented["commit"], merged["commit"]
|
|
519
|
+
if claim == landing:
|
|
520
|
+
return True
|
|
521
|
+
changed = s.git(root, "diff", "--name-only", "-z", "--no-renames", landing, claim,
|
|
522
|
+
"--", *s.CODE_PATHS).stdout
|
|
523
|
+
if not changed:
|
|
524
|
+
return True
|
|
525
|
+
reference = landing
|
|
526
|
+
if merged["method"] == "ancestry":
|
|
527
|
+
reference = s.git(root, "rev-parse", "--verify", "--quiet", f"{landing}^1",
|
|
528
|
+
required=False).stdout.strip()
|
|
529
|
+
base = (s.git(root, "merge-base", original, reference, required=False).stdout.strip()
|
|
530
|
+
if reference and s.has_commit(root, original) else "")
|
|
531
|
+
if landing == original:
|
|
532
|
+
# A fast-forward has no merge commit recording the branch boundary. Use the
|
|
533
|
+
# task's current open period, or the implementation's parent when the task
|
|
534
|
+
# was introduced later. This includes earlier commits of a multi-commit task.
|
|
535
|
+
commits = s.git(root, "log", "--format=%H", original, "--", f"tasks/{implemented['task']}.md").stdout.split()
|
|
536
|
+
for commit in commits:
|
|
537
|
+
status = committed_status(root, implemented["task"], commit)
|
|
538
|
+
if status is None or status in FINISHED | {"CANCELLED"}:
|
|
539
|
+
break
|
|
540
|
+
base = commit
|
|
541
|
+
if base and base != original:
|
|
542
|
+
paths = s.git(root, "diff", "--name-only", "-z", "--no-renames", base, original,
|
|
543
|
+
"--", *s.CODE_PATHS).stdout
|
|
544
|
+
else:
|
|
545
|
+
# Without a branch boundary (or the original history), the recorded tree is the
|
|
546
|
+
# evidence available. Include deleted paths too, so restoring one cannot escape.
|
|
547
|
+
paths = s.git(root, "ls-tree", "-r", "--name-only", "-z", landing).stdout
|
|
548
|
+
paths = "\0".join(p for p in paths.split("\0")
|
|
549
|
+
if not p.startswith(("tasks/", ".workorder/", ".notquite/")))
|
|
550
|
+
paths += s.git(root, "diff-tree", "--root", "--no-commit-id", "-r", "--name-only", "-z",
|
|
551
|
+
"--no-renames", landing, "--", *s.CODE_PATHS).stdout
|
|
552
|
+
return not ((set(paths.split("\0")) - {""}) & (set(changed.split("\0")) - {""}))
|
|
553
|
+
|
|
554
|
+
|
|
555
|
+
def equivalent_claim(root, record, implemented, claim, target_commit=None):
|
|
556
|
+
"""A rebase preserves the code patch relative to each commit's own target merge base."""
|
|
557
|
+
if target_commit is None:
|
|
558
|
+
target = merge_target(root, record)
|
|
559
|
+
if target is None:
|
|
560
|
+
return False
|
|
561
|
+
target_commit = target[1]
|
|
562
|
+
patches = []
|
|
563
|
+
for commit in (implemented["commit"], claim):
|
|
564
|
+
base = s.git(root, "merge-base", commit, target_commit, required=False).stdout.strip()
|
|
565
|
+
if not base:
|
|
566
|
+
return False
|
|
567
|
+
diff = s.git(root, "diff", "--binary", "--no-renames", "--no-ext-diff", "--no-textconv",
|
|
568
|
+
base, commit, "--", *s.CODE_PATHS).stdout
|
|
569
|
+
patch = s.git(root, "patch-id", "--stable", data=diff).stdout.split()
|
|
570
|
+
if not patch:
|
|
571
|
+
return False # an empty change cannot excuse a claim on different code
|
|
572
|
+
patches.append(patch[0])
|
|
573
|
+
return patches[0] == patches[1]
|
|
574
|
+
|
|
575
|
+
|
|
576
|
+
def unpushed_target(root, record):
|
|
577
|
+
target = merge_target(root, record)
|
|
578
|
+
if target is None or not target[0].startswith("refs/remotes/"):
|
|
579
|
+
return None
|
|
580
|
+
remote, branch = target[0].removeprefix("refs/remotes/").split("/", 1)
|
|
581
|
+
local = s.git(root, "rev-parse", "--verify", "--quiet", f"refs/heads/{branch}^{{commit}}",
|
|
582
|
+
required=False)
|
|
583
|
+
implemented = newest_implementation(s.entries(root, record["id"]))
|
|
584
|
+
if (local.returncode == 0 and implemented and not merge_match(root, implemented, target[1])
|
|
585
|
+
and merge_match(root, implemented, local.stdout.strip())):
|
|
586
|
+
return f"push {branch} to {remote}: git push {remote} {branch}"
|
|
587
|
+
return None
|
|
588
|
+
|
|
589
|
+
|
|
590
|
+
def changed_paths(root, reference, staged=False):
|
|
591
|
+
"""Paths that differ between reference and what is being checked (the index under --staged, the
|
|
592
|
+
working tree otherwise, which in CI is the commit being checked), untracked task files included."""
|
|
593
|
+
args = ["diff", "--name-only", "-z", "--no-renames"] + (["--cached"] if staged else []) + [reference]
|
|
594
|
+
paths = set(s.git(root, *args).stdout.split("\0")) - {""}
|
|
595
|
+
if not staged:
|
|
596
|
+
paths |= set(s.git(root, "ls-files", "-z", "--others", "--exclude-standard").stdout.split("\0")) - {""}
|
|
597
|
+
return paths
|
|
598
|
+
|
|
599
|
+
|
|
600
|
+
def evidence_paths(root, record, staged=False):
|
|
601
|
+
"""The contract file of a task and the REAL evidence files it names."""
|
|
602
|
+
path = record.get("contract", "none")
|
|
603
|
+
if path == "none":
|
|
604
|
+
return set()
|
|
605
|
+
found = {path}
|
|
606
|
+
try:
|
|
607
|
+
contract = json.loads(s.read_text(root, path, staged))
|
|
608
|
+
for item in contract.get("criteria", []) if isinstance(contract, dict) else []:
|
|
609
|
+
for evidence in item.get("evidence", []) if isinstance(item, dict) else []:
|
|
610
|
+
if isinstance(evidence, dict) and evidence.get("provenance") == "REAL":
|
|
611
|
+
found.add(str(evidence.get("ref", "")))
|
|
612
|
+
except (OSError, ValueError, s.Refused, AttributeError):
|
|
613
|
+
pass
|
|
614
|
+
return found
|
|
615
|
+
|
|
616
|
+
|
|
617
|
+
@s.cached_read
|
|
618
|
+
def repository_files(root, rev=None):
|
|
619
|
+
args = ["ls-tree", "-r", "--name-only", "-z", rev] if rev else ["ls-files", "-z"]
|
|
620
|
+
return set(s.git(root, *args).stdout.split("\0")) - {""}
|
|
621
|
+
|
|
622
|
+
|
|
623
|
+
def test_files(root, record, base, staged=False):
|
|
624
|
+
"""Expand current and base definitions, so deleting a test or changing its path cannot hide it."""
|
|
625
|
+
before = fields_at(root, record["id"], base)
|
|
626
|
+
candidates = repository_files(root, base) | repository_files(root)
|
|
627
|
+
candidates |= changed_paths(root, base, staged)
|
|
628
|
+
found = set()
|
|
629
|
+
for definition in (before, record):
|
|
630
|
+
if definition is None:
|
|
631
|
+
continue
|
|
632
|
+
paths = definition.get("test_paths")
|
|
633
|
+
if paths is None:
|
|
634
|
+
paths = declared_test(definition) or []
|
|
635
|
+
if not isinstance(paths, list):
|
|
636
|
+
continue
|
|
637
|
+
for path in paths:
|
|
638
|
+
if not isinstance(path, str):
|
|
639
|
+
continue
|
|
640
|
+
if "test_paths" not in definition:
|
|
641
|
+
path = path.split("::", 1)[0] # pytest node selection
|
|
642
|
+
try:
|
|
643
|
+
path = posixpath.normpath(s.local_path(root, path).relative_to(root).as_posix())
|
|
644
|
+
except (s.Refused, ValueError):
|
|
645
|
+
continue
|
|
646
|
+
found |= {p for p in candidates if path == "." or p == path or p.startswith(path + "/")}
|
|
647
|
+
return found
|
|
648
|
+
|
|
649
|
+
|
|
650
|
+
def test_file_changes(root, base, record, staged=False):
|
|
651
|
+
paths = sorted(test_files(root, record, base, staged) & changed_paths(root, base, staged))
|
|
652
|
+
if not paths:
|
|
653
|
+
return None
|
|
654
|
+
# Disabling rename detection makes a rename remove the old file's lines, even when identical.
|
|
655
|
+
args = ["diff", "--numstat", "-z", "--no-renames", "--no-ext-diff", "--no-textconv"]
|
|
656
|
+
if staged:
|
|
657
|
+
args.append("--cached")
|
|
658
|
+
delta = s.git(root, *args, base, "--", *(f":(literal){p}" for p in paths)).stdout
|
|
659
|
+
lost, affected, binary = 0, [], False
|
|
660
|
+
for entry in delta.split("\0"):
|
|
661
|
+
if not entry:
|
|
662
|
+
continue
|
|
663
|
+
added, removed, path = entry.split("\t", 2)
|
|
664
|
+
if path not in repository_files(root, base):
|
|
665
|
+
continue # new files, including binary fixtures, are pure additions
|
|
666
|
+
exists = path in repository_files(root) if staged else s.local_path(root, path).is_file()
|
|
667
|
+
if removed == "-" or int(removed) or not exists:
|
|
668
|
+
lost += int(removed) if removed != "-" else 0
|
|
669
|
+
binary |= removed == "-"
|
|
670
|
+
affected.append(path)
|
|
671
|
+
if affected:
|
|
672
|
+
change = "changed binary content" if binary else f"lost or changed {lost} lines"
|
|
673
|
+
return f"{record['id']}: its test files {change} since {base} ({', '.join(affected)})"
|
|
674
|
+
return None
|
|
675
|
+
|
|
676
|
+
|
|
677
|
+
def scope(root, reference, staged, names, all_records, include_tests=False):
|
|
678
|
+
"""The tasks a change touches (task file, receipts, contract or its evidence), and every task that
|
|
679
|
+
depends on one of them, directly or not."""
|
|
680
|
+
changed = changed_paths(root, reference, staged)
|
|
681
|
+
touched = {path[6:-3] for path in changed if path.startswith("tasks/") and path.endswith(".md")
|
|
682
|
+
and s.ID.fullmatch(path[6:-3])}
|
|
683
|
+
touched |= {s.receipt_task(path) for path in changed} - {None}
|
|
684
|
+
touched |= {tid for tid, record in all_records.items() if evidence_paths(root, record, staged) & changed}
|
|
685
|
+
if include_tests:
|
|
686
|
+
touched |= {tid for tid, record in all_records.items()
|
|
687
|
+
if test_files(root, record, reference, staged) & changed}
|
|
688
|
+
growing = True
|
|
689
|
+
while growing:
|
|
690
|
+
growing = False
|
|
691
|
+
for tid, record in all_records.items():
|
|
692
|
+
if tid not in touched and any(w[5:] in touched for w in s.dependencies(record) if w.startswith("task:")):
|
|
693
|
+
touched.add(tid)
|
|
694
|
+
growing = True
|
|
695
|
+
return touched, changed
|
|
696
|
+
|
|
697
|
+
|
|
698
|
+
def requirement_changes(root, base, record):
|
|
699
|
+
"""Changes since base to what a task requires: its test, its contract, its dependencies."""
|
|
700
|
+
tid, found = record["id"], []
|
|
701
|
+
before = fields_at(root, tid, base)
|
|
702
|
+
if before is None:
|
|
703
|
+
return found
|
|
704
|
+
if before.get("test", "") != record.get("test", ""):
|
|
705
|
+
found.append(f"test changed: {before.get('test', '') or '(none)'!r} -> {record.get('test', '') or '(none)'!r}")
|
|
706
|
+
if before.get("test_paths") != record.get("test_paths"):
|
|
707
|
+
found.append("test_paths changed")
|
|
708
|
+
if before.get("contract") != record.get("contract"):
|
|
709
|
+
found.append(f"contract changed: {before.get('contract')} -> {record.get('contract')}")
|
|
710
|
+
elif record.get("contract", "none") != "none":
|
|
711
|
+
old = s.git(root, "show", f"{base}:{record['contract']}", required=False)
|
|
712
|
+
try:
|
|
713
|
+
now = s.read_text(root, record["contract"])
|
|
714
|
+
except (OSError, s.Refused):
|
|
715
|
+
now = None
|
|
716
|
+
if old.returncode == 0 and now is not None and now != old.stdout.replace("\r\n", "\n"):
|
|
717
|
+
found.append(f"contract {record['contract']} edited")
|
|
718
|
+
try:
|
|
719
|
+
dropped = sorted(set(s.dependencies({"waits_on": before.get("waits_on", []),
|
|
720
|
+
"depends_on": s.task_refs(tid, "depends_on", before.get("depends_on", []))}))
|
|
721
|
+
- set(s.dependencies(record)))
|
|
722
|
+
except (s.Refused, TypeError):
|
|
723
|
+
dropped = []
|
|
724
|
+
if dropped:
|
|
725
|
+
found.append(f"dependencies removed: {', '.join(dropped)}")
|
|
726
|
+
# The written ask: removing or rewording a Scope or Acceptance line changes what DONE means.
|
|
727
|
+
# Adding lines does not (that is how a task gets filled in).
|
|
728
|
+
old = s.git(root, "show", f"{base}:tasks/{tid}.md", required=False)
|
|
729
|
+
if old.returncode == 0:
|
|
730
|
+
def section_lines(text, name):
|
|
731
|
+
return {line.strip() for heading, body in s.task_body_sections(text) if heading == name
|
|
732
|
+
for line in body if line.strip() and not line.strip().startswith("<!--")}
|
|
733
|
+
try:
|
|
734
|
+
now_text = s.read_text(root, f"tasks/{tid}.md")
|
|
735
|
+
except (OSError, s.Refused):
|
|
736
|
+
now_text = ""
|
|
737
|
+
before_text = old.stdout.replace("\r\n", "\n")
|
|
738
|
+
for name in ("Scope", "Acceptance"):
|
|
739
|
+
removed = section_lines(before_text, name) - section_lines(now_text, name)
|
|
740
|
+
if removed:
|
|
741
|
+
found.append(f"{name} lines removed or changed: {len(removed)}")
|
|
742
|
+
return found
|
|
743
|
+
|
|
744
|
+
|
|
745
|
+
def run_declared_test(root, record, counts=None):
|
|
746
|
+
"""Run a task's declared test here (CI), without a shell; return a problem line, or None if it passed."""
|
|
747
|
+
tid, declared = record["id"], declared_test(record)
|
|
748
|
+
if declared is None:
|
|
749
|
+
return f"NOT QUITE {tid} says {record['status']} but declares no test for this check to run"
|
|
750
|
+
try:
|
|
751
|
+
code = subprocess.run(declared, cwd=root).returncode
|
|
752
|
+
if counts is not None:
|
|
753
|
+
counts["tests"] += 1
|
|
754
|
+
except OSError as error:
|
|
755
|
+
code = f"not started: {error.strerror}"
|
|
756
|
+
finally:
|
|
757
|
+
s.invalidate_reads() # a declared command may have changed files or refs
|
|
758
|
+
if code == 0:
|
|
759
|
+
return None
|
|
760
|
+
return f"NOT QUITE {tid} says {record['status']}, but its test failed when this check ran it (exit {code})"
|
|
761
|
+
|
|
762
|
+
|
|
763
|
+
class Views(dict):
|
|
764
|
+
"""Verdicts worked out on first use, so a scoped check reads only the tasks it needs."""
|
|
765
|
+
|
|
766
|
+
def __init__(self, root, all_records, staged=False):
|
|
767
|
+
super().__init__()
|
|
768
|
+
self.root, self.all_records, self.staged = root, all_records, staged
|
|
769
|
+
|
|
770
|
+
def __missing__(self, tid):
|
|
771
|
+
self[tid] = verdict(self.root, self.all_records[tid], self.staged)
|
|
772
|
+
return self[tid]
|
|
773
|
+
|
|
774
|
+
|
|
775
|
+
def dependency_cycles(all_records):
|
|
776
|
+
"""Strongly connected components: only participants get a cycle problem."""
|
|
777
|
+
indices, low, stack, active, cycles = {}, {}, [], set(), {}
|
|
778
|
+
|
|
779
|
+
def visit(tid):
|
|
780
|
+
indices[tid] = low[tid] = len(indices)
|
|
781
|
+
stack.append(tid)
|
|
782
|
+
active.add(tid)
|
|
783
|
+
children = [w[5:] for w in s.dependencies(all_records[tid])
|
|
784
|
+
if w.startswith("task:") and w[5:] in all_records]
|
|
785
|
+
for other in children:
|
|
786
|
+
if other not in indices:
|
|
787
|
+
visit(other)
|
|
788
|
+
low[tid] = min(low[tid], low[other])
|
|
789
|
+
elif other in active:
|
|
790
|
+
low[tid] = min(low[tid], indices[other])
|
|
791
|
+
if low[tid] == indices[tid]:
|
|
792
|
+
group = []
|
|
793
|
+
while True:
|
|
794
|
+
other = stack.pop()
|
|
795
|
+
active.remove(other)
|
|
796
|
+
group.append(other)
|
|
797
|
+
if other == tid:
|
|
798
|
+
break
|
|
799
|
+
if len(group) > 1 or tid in children:
|
|
800
|
+
for other in group:
|
|
801
|
+
cycles[other] = "dependency cycle: " + ", ".join(sorted(group))
|
|
802
|
+
|
|
803
|
+
for tid in all_records:
|
|
804
|
+
if tid not in indices:
|
|
805
|
+
visit(tid)
|
|
806
|
+
return cycles
|
|
807
|
+
|
|
808
|
+
|
|
809
|
+
def removals(root, base, names, allow, staged=False):
|
|
810
|
+
before = s.metadata_texts(root, base, None, False)
|
|
811
|
+
old_tasks = {p[6:-3] for p in before if p.startswith("tasks/") and p.endswith(".md")
|
|
812
|
+
and s.ID.fullmatch(p[6:-3])}
|
|
813
|
+
retired, problems = set(), []
|
|
814
|
+
for tid in sorted(old_tasks - set(names)):
|
|
815
|
+
if (tid in allow and committed_status(root, tid, base) in FINISHED | {"CANCELLED"}
|
|
816
|
+
and not s.receipt_paths(root, staged, tid=tid)):
|
|
817
|
+
retired.add(tid)
|
|
818
|
+
else:
|
|
819
|
+
problems.append(f"{tid}: task file removed since {base}; removing a DONE, CLOSED or CANCELLED"
|
|
820
|
+
f" task requires all its receipts removed and --allow {tid}")
|
|
821
|
+
return retired, problems
|
|
822
|
+
|
|
823
|
+
|
|
824
|
+
def check_summary(counts, run_tests=False):
|
|
825
|
+
line = f"checked {counts['tasks']} tasks ({counts['claimed']} claimed DONE or CLOSED)"
|
|
826
|
+
if run_tests:
|
|
827
|
+
line += f"; ran {counts['tests']} declared tests"
|
|
828
|
+
return line
|
|
829
|
+
|
|
830
|
+
|
|
831
|
+
@s.read_session()
|
|
832
|
+
def check(root, staged=False, base=None, notes=None, allow=(), run_tests=False, counts=None):
|
|
833
|
+
"""Problems that refuse the check.
|
|
834
|
+
|
|
835
|
+
Plain check reads every task. With --staged (the pre-commit hook) or --base REF (CI) it judges the
|
|
836
|
+
change: the tasks it touches and the tasks that depend on them. A task file that cannot be read is
|
|
837
|
+
a problem for that task only. With base, a change to what a task requires (its test, contract or
|
|
838
|
+
dependencies) fails unless the task is in allow; with run_tests, CI runs each claimed task's test.
|
|
839
|
+
"""
|
|
840
|
+
notes = [] if notes is None else notes
|
|
841
|
+
counts = {} if counts is None else counts
|
|
842
|
+
errors = {}
|
|
843
|
+
all_records = records(root, staged, errors)
|
|
844
|
+
names = task_names(root, staged)
|
|
845
|
+
reference = base or ("HEAD" if staged else None)
|
|
846
|
+
if reference and s.git(root, "rev-parse", "--verify", "--quiet", f"{reference}^{{commit}}",
|
|
847
|
+
required=False).returncode:
|
|
848
|
+
if base:
|
|
849
|
+
raise s.Refused(f"base {base} is not in this clone; fetch it"
|
|
850
|
+
" (in GitHub Actions: actions/checkout with fetch-depth: 0)")
|
|
851
|
+
reference = None # the first commit: nothing to compare with, check everything
|
|
852
|
+
if reference:
|
|
853
|
+
selected, changed = scope(root, reference, staged, names, all_records, include_tests=bool(base))
|
|
854
|
+
else:
|
|
855
|
+
selected, changed = set(names), None
|
|
856
|
+
counts.update(tasks=len(selected), claimed=sum(r["status"] in FINISHED for tid, r in all_records.items()
|
|
857
|
+
if tid in selected), tests=0)
|
|
858
|
+
problems = [f"{tid}: {message.removeprefix(tid + ': ')}" for tid, message in sorted(errors.items())
|
|
859
|
+
if tid in selected]
|
|
860
|
+
stray = [path for path in s.files(root, "tasks", staged) if not path.endswith(".md")
|
|
861
|
+
and (changed is None or path in changed)]
|
|
862
|
+
problems += [f"{path}: only task files belong in tasks/; a file here is outside the code fingerprint,"
|
|
863
|
+
" so changes to it are never checked" for path in stray]
|
|
864
|
+
retired = set()
|
|
865
|
+
if base:
|
|
866
|
+
retired, removed_problems = removals(root, base, names, allow, staged)
|
|
867
|
+
problems += removed_problems + base_problems(root, base, staged, retired)
|
|
868
|
+
notes += [f"{tid}: task and all receipts removed (allowed)" for tid in sorted(retired)]
|
|
869
|
+
views = Views(root, all_records, staged)
|
|
870
|
+
# Include removed receipts and ledgers whose task file was also removed.
|
|
871
|
+
paths = set(s.receipt_paths(root, rev="HEAD")) | set(s.receipt_paths(root, staged))
|
|
872
|
+
tids = {s.receipt_task(path) for path in paths
|
|
873
|
+
if changed is None or path in changed or s.receipt_task(path) in selected} - {None}
|
|
874
|
+
for tid in sorted(tids):
|
|
875
|
+
if tid in retired:
|
|
876
|
+
continue
|
|
877
|
+
try:
|
|
878
|
+
s.entries(root, tid, staged)
|
|
879
|
+
except s.Refused as error:
|
|
880
|
+
problems.append(f"{tid}: {str(error).removeprefix(tid + ': ')}")
|
|
881
|
+
errors.setdefault(tid, str(error))
|
|
882
|
+
continue
|
|
883
|
+
if tid not in all_records and tid not in errors:
|
|
884
|
+
problems.append(f"{tid}: receipt ledger has no task record")
|
|
885
|
+
visiting, visited = set(), set()
|
|
886
|
+
cycles = dependency_cycles(all_records)
|
|
887
|
+
problems += [f"{tid}: {message}" for tid, message in sorted(cycles.items()) if tid in selected]
|
|
888
|
+
|
|
889
|
+
def walk(tid):
|
|
890
|
+
if tid in visiting:
|
|
891
|
+
return
|
|
892
|
+
if tid in visited:
|
|
893
|
+
return
|
|
894
|
+
visiting.add(tid)
|
|
895
|
+
for wait in s.dependencies(all_records[tid]):
|
|
896
|
+
if wait.startswith("task:"):
|
|
897
|
+
other = wait[5:]
|
|
898
|
+
if other not in all_records:
|
|
899
|
+
if other not in errors:
|
|
900
|
+
problems.append(f"{tid}: missing dependency {other}")
|
|
901
|
+
else:
|
|
902
|
+
walk(other)
|
|
903
|
+
visiting.remove(tid)
|
|
904
|
+
visited.add(tid)
|
|
905
|
+
|
|
906
|
+
for tid, record in sorted(all_records.items()):
|
|
907
|
+
if tid not in selected or tid in errors:
|
|
908
|
+
continue
|
|
909
|
+
try:
|
|
910
|
+
views[tid] # read the task's receipts and contract now, so their errors belong to this task
|
|
911
|
+
except s.Refused as error:
|
|
912
|
+
problems.append(f"{tid}: {str(error).removeprefix(tid + ': ')}")
|
|
913
|
+
continue
|
|
914
|
+
walk(tid)
|
|
915
|
+
# blocks is informational: it is checked for consistency but never enforced.
|
|
916
|
+
for other in record.get("blocks", []):
|
|
917
|
+
if other not in all_records and other not in errors:
|
|
918
|
+
problems.append(f"{tid}: blocks unknown task {other}")
|
|
919
|
+
elif other in all_records and tid in all_records[other].get("blocks", []) and tid < other:
|
|
920
|
+
problems.append(f"{tid} and {other} each say they block the other")
|
|
921
|
+
try:
|
|
922
|
+
debt = claim_debt(record, all_records, views)
|
|
923
|
+
found = (f"NOT QUITE {tid} says {record['status']} but owes: {', '.join(debt)}."
|
|
924
|
+
f" Details: workorder check {tid}") if debt else stale_claim(root, record, staged, base)
|
|
925
|
+
except s.Refused as error: # a dependency that cannot be read
|
|
926
|
+
found = f"{tid}: {error}"
|
|
927
|
+
merged = computed_merge(root, record, newest_implementation(s.entries(root, tid, staged)))
|
|
928
|
+
if merged:
|
|
929
|
+
notes.append(f"{tid}: {merge_line(merged)}")
|
|
930
|
+
if found:
|
|
931
|
+
problems.append(found)
|
|
932
|
+
if base:
|
|
933
|
+
if fields_at(root, tid, base) is None and record["status"] in FINISHED:
|
|
934
|
+
line = f"{tid} was created and claimed {record['status']} in the same change"
|
|
935
|
+
if tid in allow:
|
|
936
|
+
notes.append(line + " (definition allowed)")
|
|
937
|
+
else:
|
|
938
|
+
problems.append(line + f"; a reviewer accepts its definition with --allow {tid}")
|
|
939
|
+
changed_tests = test_file_changes(root, base, record, staged)
|
|
940
|
+
if changed_tests:
|
|
941
|
+
if tid in allow:
|
|
942
|
+
notes.append(changed_tests + " (allowed)")
|
|
943
|
+
else:
|
|
944
|
+
problems.append(changed_tests + f"; a reviewer accepts it with --allow {tid}")
|
|
945
|
+
for change in requirement_changes(root, base, record):
|
|
946
|
+
line = f"{tid}: {change} since {base}"
|
|
947
|
+
if tid in allow:
|
|
948
|
+
notes.append(line + " (allowed)")
|
|
949
|
+
else:
|
|
950
|
+
problems.append(f"{line}; a reviewer accepts it with --allow {tid}")
|
|
951
|
+
elif staged:
|
|
952
|
+
for change in requirement_changes(root, "HEAD", record):
|
|
953
|
+
notes.append(f"{tid}: {change} in this commit")
|
|
954
|
+
if run_tests and not found and record["status"] in FINISHED:
|
|
955
|
+
failed = run_declared_test(root, record, counts)
|
|
956
|
+
if failed:
|
|
957
|
+
problems.append(failed)
|
|
958
|
+
else:
|
|
959
|
+
notes.append(f"{tid}: its test passed when this check ran it")
|
|
960
|
+
return problems
|
|
961
|
+
|
|
962
|
+
|
|
963
|
+
def claim_debt(record, all_records, views):
|
|
964
|
+
"""What a DONE or CLOSED status line claims but the evidence does not yet support."""
|
|
965
|
+
claimed = record["status"]
|
|
966
|
+
if claimed not in {"DONE", "CLOSED"}:
|
|
967
|
+
return []
|
|
968
|
+
_, done, delivery = views[record["id"]]
|
|
969
|
+
return done + (delivery if claimed == "CLOSED" else []) + waits(record, all_records, views)
|
|
970
|
+
|
|
971
|
+
|
|
972
|
+
def next_step(item, record, code_changed=False, root=None):
|
|
973
|
+
tid = record["id"]
|
|
974
|
+
command = record.get("test", "").strip() or "<your test command>"
|
|
975
|
+
if item == "implementation":
|
|
976
|
+
return f"commit the code, then: workorder receipt implemented --task {tid}"
|
|
977
|
+
if item == "a declared test":
|
|
978
|
+
return (f'add the command that proves it to tasks/{tid}.md, e.g. test: "python -m pytest",'
|
|
979
|
+
' or test: any to accept any recorded command')
|
|
980
|
+
if item.startswith("implementation (commit"):
|
|
981
|
+
return ("fetch the full history; after a squash or rebase merge, record it again on the merged"
|
|
982
|
+
f" code: workorder receipt implemented --task {tid}")
|
|
983
|
+
if item == "evidence for the uncommitted code changes":
|
|
984
|
+
return (f"commit the code, then: workorder receipt implemented --task {tid}, then"
|
|
985
|
+
f" workorder receipt test --task {tid} -- {command}")
|
|
986
|
+
if item.startswith("a passing test on the code marked"):
|
|
987
|
+
return (f"workorder receipt implemented --task {tid}, then"
|
|
988
|
+
f" workorder receipt test --task {tid} -- {command}; or workorder renew --task {tid}")
|
|
989
|
+
if item.startswith("a passing test on"):
|
|
990
|
+
if code_changed:
|
|
991
|
+
return (f"workorder receipt implemented --task {tid}, then"
|
|
992
|
+
f" workorder receipt test --task {tid} -- {command}")
|
|
993
|
+
return f"workorder receipt test --task {tid} -- {command}"
|
|
994
|
+
if item.startswith("contract "):
|
|
995
|
+
return f"add qualifying evidence to {record['contract']}"
|
|
996
|
+
if item == "merge of the tested code":
|
|
997
|
+
push = unpushed_target(root, record) if root else None
|
|
998
|
+
if push:
|
|
999
|
+
return push
|
|
1000
|
+
return ("the merged code differs from the tested code or no matching merge was found; "
|
|
1001
|
+
f"run workorder renew --task {tid} on main, or record workorder receipt merged --task {tid}")
|
|
1002
|
+
if item.startswith("deployment read-back"):
|
|
1003
|
+
return (f"workorder receipt deployed --task {tid} --target <name>"
|
|
1004
|
+
" -- <command that prints the deployed commit>")
|
|
1005
|
+
if item.startswith("live read-back"):
|
|
1006
|
+
return (f"workorder receipt live --task {tid} --target <name>"
|
|
1007
|
+
" -- <command that prints the commit the live system reports>")
|
|
1008
|
+
if item.startswith("task:"):
|
|
1009
|
+
field = "depends_on" if item[5:] in record.get("depends_on", []) else "waits_on"
|
|
1010
|
+
return f"finish {item[5:]} first, or remove it from {field}"
|
|
1011
|
+
return f"remove {item} from waits_on once it is answered"
|
|
1012
|
+
|
|
1013
|
+
|
|
1014
|
+
def test_line(record, history):
|
|
1015
|
+
"""Describe the newest test evidence for the newest implementation."""
|
|
1016
|
+
implemented = newest_implementation(history)
|
|
1017
|
+
if implemented is None:
|
|
1018
|
+
return None, "none counted: no implementation recorded"
|
|
1019
|
+
short = implemented["commit"][:7]
|
|
1020
|
+
if implemented["missing"]:
|
|
1021
|
+
return short, f"none counted: commit {short} is not in this clone"
|
|
1022
|
+
after = history[history.index(implemented) + 1:]
|
|
1023
|
+
runs = counting_runs(record, after, implemented)
|
|
1024
|
+
if runs:
|
|
1025
|
+
newest = runs[-1]
|
|
1026
|
+
where = newest["commit"][:7]
|
|
1027
|
+
if newest["commit"] != implemented["commit"]:
|
|
1028
|
+
where += f", same code as {short}"
|
|
1029
|
+
if newest["exit_code"] != 0:
|
|
1030
|
+
latest = f"FAIL (exit {newest['exit_code']}, {where})"
|
|
1031
|
+
elif not newest["valid"]:
|
|
1032
|
+
latest = f"not counted: files or HEAD changed while it ran ({where})"
|
|
1033
|
+
else:
|
|
1034
|
+
return short, f"PASS (exit 0, {where})"
|
|
1035
|
+
if any(e["exit_code"] == 0 and e["valid"] for e in runs):
|
|
1036
|
+
return short, f"{latest}; an earlier run passed, but the latest run decides"
|
|
1037
|
+
return short, latest
|
|
1038
|
+
if declared_test(record) and any(e["kind"] == "test" and e["code"] == implemented["code"] for e in after):
|
|
1039
|
+
return short, f"no run of the task's test for this commit (test: {record['test'].strip()})"
|
|
1040
|
+
tests = [e for e in history if e["kind"] == "test"]
|
|
1041
|
+
if not tests:
|
|
1042
|
+
return short, "no passing test for this commit"
|
|
1043
|
+
if tests[-1]["code"] == implemented["code"]:
|
|
1044
|
+
return short, "no passing test for this commit; the last test was recorded before the implementation"
|
|
1045
|
+
return short, f"no passing test for this commit; the last test ran on {tests[-1]['commit'][:7]}"
|
|
1046
|
+
|
|
1047
|
+
|
|
1048
|
+
def uncounted(root, record, history):
|
|
1049
|
+
"""Why the newest receipt, though recorded, cannot count toward the verdict; None if it can.
|
|
1050
|
+
|
|
1051
|
+
Failed or invalid runs are reported by their exit code and are not repeated here.
|
|
1052
|
+
"""
|
|
1053
|
+
item, before = history[-1], history[:-1]
|
|
1054
|
+
kind = item["kind"]
|
|
1055
|
+
if kind == "implemented" or (kind in {"test", "deployed", "live"}
|
|
1056
|
+
and (item["exit_code"] != 0 or not item["valid"])):
|
|
1057
|
+
return None
|
|
1058
|
+
tid = record["id"]
|
|
1059
|
+
implemented = newest_implementation(before)
|
|
1060
|
+
if kind in {"merged", "deployed", "live"}:
|
|
1061
|
+
needed = {"merged": {"repo", "live"}, "deployed": {"live"}, "live": {"live"}}[kind]
|
|
1062
|
+
if record["ships"] not in needed:
|
|
1063
|
+
return f"{tid} has ships: {record['ships']}, so a {kind} receipt is not part of its evidence"
|
|
1064
|
+
if implemented is None:
|
|
1065
|
+
return f"no implementation is recorded yet; run workorder receipt implemented --task {tid} first"
|
|
1066
|
+
short = implemented["commit"][:7]
|
|
1067
|
+
if implemented["missing"]:
|
|
1068
|
+
return (f"the implementation names commit {short}, which is not in this clone; run"
|
|
1069
|
+
f" workorder receipt implemented --task {tid} again")
|
|
1070
|
+
if kind == "test":
|
|
1071
|
+
if item["code"] != implemented["code"]:
|
|
1072
|
+
return (f"this code differs from the implemented commit {short}; run"
|
|
1073
|
+
f" workorder receipt implemented --task {tid} first")
|
|
1074
|
+
declared = declared_test(record)
|
|
1075
|
+
if declared is not None and item["command"] != declared:
|
|
1076
|
+
return f"{tid} declares its test as: {record['test'].strip()}; only that command counts"
|
|
1077
|
+
return None
|
|
1078
|
+
if kind == "merged" and not carries(root, implemented, item):
|
|
1079
|
+
return (f"{item['ref']} on origin neither contains the implemented commit {short} nor holds exactly its"
|
|
1080
|
+
f" code; after a squash merge, record implemented and test again on the merged code")
|
|
1081
|
+
computed = computed_merge(root, record, implemented)
|
|
1082
|
+
if kind == "deployed" and not delivered_code(root, implemented, item, computed):
|
|
1083
|
+
return f"the deployed commit neither contains the implemented commit {short} nor holds exactly its code"
|
|
1084
|
+
current = before[before.index(implemented) + 1:]
|
|
1085
|
+
merges = [i for i, e in enumerate(current) if e["kind"] == "merged" and carries(root, implemented, e)]
|
|
1086
|
+
if kind == "deployed" and not merges and not computed:
|
|
1087
|
+
return (f"no merge of the tested code is recorded since the implementation;"
|
|
1088
|
+
f" run workorder receipt merged --task {tid} first")
|
|
1089
|
+
if kind == "live":
|
|
1090
|
+
after_merge = current if computed else current[merges[-1] + 1:] if merges else []
|
|
1091
|
+
deployed = [e for e in after_merge if e["kind"] == "deployed"]
|
|
1092
|
+
if not deployed:
|
|
1093
|
+
return "no deployment read-back is recorded after the merge"
|
|
1094
|
+
if deployed[-1]["exit_code"] != 0 or not deployed[-1]["valid"]:
|
|
1095
|
+
return "the latest deployment read-back did not pass"
|
|
1096
|
+
if deployed[-1]["commit"] != item["commit"] or deployed[-1]["target"] != item["target"]:
|
|
1097
|
+
return (f"it does not match the latest deployment read-back"
|
|
1098
|
+
f" ({deployed[-1]['target']} on {deployed[-1]['commit'][:7]})")
|
|
1099
|
+
return None
|
|
1100
|
+
|
|
1101
|
+
|
|
1102
|
+
def timeline(root, record, history):
|
|
1103
|
+
"""One line per receipt, oldest first: when, what, by whom."""
|
|
1104
|
+
lines = []
|
|
1105
|
+
for item in history:
|
|
1106
|
+
when = item["at"][:16].replace("T", " ")
|
|
1107
|
+
commit = item["commit"][:7]
|
|
1108
|
+
kind = item["kind"]
|
|
1109
|
+
if kind == "implemented":
|
|
1110
|
+
what = f"implemented {commit}"
|
|
1111
|
+
elif kind == "test":
|
|
1112
|
+
result = ("PASS" if item["exit_code"] == 0 and item["valid"]
|
|
1113
|
+
else f"FAIL (exit {item['exit_code']})" if item["exit_code"] != 0 else "not counted")
|
|
1114
|
+
what = f"test {result}: {s.join_command(item['command'])} on {commit}"
|
|
1115
|
+
elif kind == "merged":
|
|
1116
|
+
what = f"merged: {item.get('ref', '')} at {commit}"
|
|
1117
|
+
else:
|
|
1118
|
+
what = f"{kind} read-back {item.get('target', '')}: {'ok' if item['valid'] else 'not valid'} ({commit})"
|
|
1119
|
+
if item["missing"]:
|
|
1120
|
+
what += " (commit not in this clone)"
|
|
1121
|
+
lines.append(f" {when} {what} ({item['who']})")
|
|
1122
|
+
computed = computed_merge(root, record, newest_implementation(history))
|
|
1123
|
+
if computed:
|
|
1124
|
+
lines.append(" " + merge_line(computed))
|
|
1125
|
+
return lines
|
|
1126
|
+
|
|
1127
|
+
|
|
1128
|
+
@s.read_session()
|
|
1129
|
+
def record_lines(root, tid):
|
|
1130
|
+
"""The task as a record to come back to: what it is, where it stands, what happened, what is next."""
|
|
1131
|
+
errors = {}
|
|
1132
|
+
all_records = records(root, errors=errors)
|
|
1133
|
+
if tid in errors:
|
|
1134
|
+
raise s.Refused(errors[tid])
|
|
1135
|
+
if tid not in all_records:
|
|
1136
|
+
raise s.Refused(f"no task record tasks/{tid}.md")
|
|
1137
|
+
record = all_records[tid]
|
|
1138
|
+
views = Views(root, all_records)
|
|
1139
|
+
computed, done, delivery = views[tid]
|
|
1140
|
+
open_waits = waits(record, all_records, views)
|
|
1141
|
+
if computed in FINISHED and open_waits:
|
|
1142
|
+
computed = "BLOCKED"
|
|
1143
|
+
history = s.entries(root, tid)
|
|
1144
|
+
recognise_squashed(root, tid, history)
|
|
1145
|
+
stale = [] if done or delivery else (["a passing test on the code marked " + record["status"]]
|
|
1146
|
+
if stale_claim(root, record) else [])
|
|
1147
|
+
if stale and computed in FINISHED:
|
|
1148
|
+
computed = "IN_PROGRESS"
|
|
1149
|
+
lines = [f"{tid} recorded {record['status']}; computed {computed}",
|
|
1150
|
+
"still owes: " + owes(record, stale + done + open_waits, delivery)]
|
|
1151
|
+
if record["status"] not in FINISHED and computed in FINISHED:
|
|
1152
|
+
# Found in the handoff trial: "computed CLOSED, owes nothing" on a half-done task misleads.
|
|
1153
|
+
lines.append("note: " + ACCEPTANCE_NOTE)
|
|
1154
|
+
if s.dependencies(record):
|
|
1155
|
+
lines.append("waits_on: " + ", ".join(s.dependencies(record)))
|
|
1156
|
+
lines += ["", f"title: {record['title']}", f"owner: {record['owner']}"]
|
|
1157
|
+
for key in ("mission", "summary", "next"):
|
|
1158
|
+
if record.get(key, "").strip():
|
|
1159
|
+
lines.append(f"{key + ':':<9} {' '.join(record[key].split())}")
|
|
1160
|
+
lines.append(f"test: {record.get('test', '').strip() or '(none declared)'}")
|
|
1161
|
+
# The task's own words: every section of the body except Progress, which follows the history.
|
|
1162
|
+
sections = s.task_body_sections(s.read_text(root, f"tasks/{tid}.md"))
|
|
1163
|
+
for heading, body in sections:
|
|
1164
|
+
if heading in (None, "Progress"):
|
|
1165
|
+
continue
|
|
1166
|
+
text = [line.rstrip() for line in body if not line.strip().startswith("<!--")]
|
|
1167
|
+
while text and not text[0].strip():
|
|
1168
|
+
text.pop(0)
|
|
1169
|
+
while text and not text[-1].strip():
|
|
1170
|
+
text.pop()
|
|
1171
|
+
lines += ["", f"{heading.lower()}:"] + ([f" {line}" if line.strip() else "" for line in text]
|
|
1172
|
+
or [" (empty)"])
|
|
1173
|
+
lines += ["", "history:"] + (timeline(root, record, history) or [" (no receipts yet)"])
|
|
1174
|
+
progress = [line.strip() for heading, body in sections
|
|
1175
|
+
if heading == "Progress" for line in body if line.strip() and not line.strip().startswith("<!--")]
|
|
1176
|
+
lines += ["", "progress:"] + ([f" {line}" for line in progress] or [" (no notes yet)"])
|
|
1177
|
+
owed = stale + done + delivery + open_waits
|
|
1178
|
+
if owed:
|
|
1179
|
+
lines += ["", f"next step: {next_step(owed[0], record, root=root)}"]
|
|
1180
|
+
return lines
|
|
1181
|
+
|
|
1182
|
+
|
|
1183
|
+
@s.read_session()
|
|
1184
|
+
def explain(root, tid):
|
|
1185
|
+
"""Lines describing one task's claim and evidence, and whether the claim stands."""
|
|
1186
|
+
errors = {}
|
|
1187
|
+
all_records = records(root, errors=errors)
|
|
1188
|
+
if tid in errors:
|
|
1189
|
+
raise s.Refused(errors[tid])
|
|
1190
|
+
if tid not in all_records:
|
|
1191
|
+
raise s.Refused(f"no task record tasks/{tid}.md")
|
|
1192
|
+
views = Views(root, all_records)
|
|
1193
|
+
record = all_records[tid]
|
|
1194
|
+
computed, done, delivery = views[tid]
|
|
1195
|
+
debt = claim_debt(record, all_records, views)
|
|
1196
|
+
history = s.entries(root, tid)
|
|
1197
|
+
recognise_squashed(root, tid, history)
|
|
1198
|
+
commit, test = test_line(record, history)
|
|
1199
|
+
implemented = newest_implementation(history)
|
|
1200
|
+
runs = (counting_runs(record, history[history.index(implemented) + 1:], implemented)
|
|
1201
|
+
if implemented and not implemented["missing"] else [])
|
|
1202
|
+
stale = None if debt else stale_claim(root, record)
|
|
1203
|
+
if stale and "uncommitted code changes" in stale:
|
|
1204
|
+
debt = ["evidence for the uncommitted code changes"]
|
|
1205
|
+
elif stale:
|
|
1206
|
+
debt = [f"a passing test on the code marked {record['status']} (it differs from {commit})"]
|
|
1207
|
+
code_changed = implemented is not None and s.code_digest(root, s.head(root)) != implemented["code"]
|
|
1208
|
+
claimed = record["status"]
|
|
1209
|
+
if computed in FINISHED and waits(record, all_records, views):
|
|
1210
|
+
computed = "BLOCKED" # the evidence is in, but a dependency is still open
|
|
1211
|
+
if s.dirty_paths(root):
|
|
1212
|
+
code_note = "uncommitted code changes are not covered by any receipt"
|
|
1213
|
+
else:
|
|
1214
|
+
code_note = None
|
|
1215
|
+
lines = [f"NOT QUITE {tid}" if debt else f"{claimed} {tid}", "",
|
|
1216
|
+
f" Claimed: {claimed}", f" Computed: {computed}",
|
|
1217
|
+
f" Commit: {commit or 'none recorded'}", f" Test: {test}"]
|
|
1218
|
+
merged = computed_merge(root, record, implemented)
|
|
1219
|
+
if merged:
|
|
1220
|
+
lines.append(" Merge: " + merge_line(merged))
|
|
1221
|
+
if runs:
|
|
1222
|
+
lines.append(f" Command: {s.join_command(runs[-1]['command'])}")
|
|
1223
|
+
if code_changed:
|
|
1224
|
+
lines.append(f" Note: the code has changed since {commit}; this verdict is about {commit}")
|
|
1225
|
+
if code_note:
|
|
1226
|
+
lines.append(f" Note: {code_note}")
|
|
1227
|
+
if not debt and claimed not in FINISHED and computed in FINISHED:
|
|
1228
|
+
lines.append(f" Note: {ACCEPTANCE_NOTE}")
|
|
1229
|
+
if debt:
|
|
1230
|
+
lines += [f" Missing: {item}" for item in debt]
|
|
1231
|
+
lines += [f" Next: {next_step(item, record, code_changed, root)}" for item in debt]
|
|
1232
|
+
result = "NOT DONE" if done or claimed == "DONE" else "NOT CLOSED"
|
|
1233
|
+
lines += ["", f" Result: {result}. The status says {claimed}; the evidence above does not support it."]
|
|
1234
|
+
else:
|
|
1235
|
+
owed = done + delivery
|
|
1236
|
+
if owed:
|
|
1237
|
+
lines.append(f" Owes: {', '.join(owed)}")
|
|
1238
|
+
lines += ["", f" Result: {'claim supported' if claimed in {'DONE', 'CLOSED'} else 'no completion claimed'}"]
|
|
1239
|
+
return lines, bool(debt)
|
|
1240
|
+
|
|
1241
|
+
|
|
1242
|
+
@s.read_session()
|
|
1243
|
+
def ready(root):
|
|
1244
|
+
# A refused DONE or CLOSED claim is shown on its own task; it does not hide the rest of the work.
|
|
1245
|
+
# Cycles belong to their participants; unrelated work remains visible.
|
|
1246
|
+
issues = check(root)
|
|
1247
|
+
unreadable = {}
|
|
1248
|
+
records(root, errors=unreadable)
|
|
1249
|
+
refused = {issue.split()[2] for issue in issues if issue.startswith("NOT QUITE ")}
|
|
1250
|
+
structural = [issue for issue in issues if not issue.startswith("NOT QUITE ")
|
|
1251
|
+
and issue.split(":")[0] not in unreadable and not issue.startswith("tasks/")
|
|
1252
|
+
and ": dependency cycle:" not in issue]
|
|
1253
|
+
if structural:
|
|
1254
|
+
raise s.Refused("; ".join(structural))
|
|
1255
|
+
errors = {}
|
|
1256
|
+
all_records = records(root, errors=errors)
|
|
1257
|
+
cycles = dependency_cycles(all_records)
|
|
1258
|
+
views = Views(root, all_records)
|
|
1259
|
+
lines = [f"{tid} cannot be read: {message.removeprefix(tid + ': ')}" for tid, message in sorted(errors.items())]
|
|
1260
|
+
upstream = {}
|
|
1261
|
+
try:
|
|
1262
|
+
claims = s.active_claims(root, upstream) if s.has_origin(root) else {}
|
|
1263
|
+
except s.Refused:
|
|
1264
|
+
claims = {}
|
|
1265
|
+
upstream = {}
|
|
1266
|
+
lines.append("(claims not shown: origin could not be reached)")
|
|
1267
|
+
for tid, record in sorted(all_records.items()):
|
|
1268
|
+
if record["status"] == "CANCELLED":
|
|
1269
|
+
continue
|
|
1270
|
+
blocked = waits(record, all_records, views)
|
|
1271
|
+
if record["status"] == "BLOCKED":
|
|
1272
|
+
blocked = ["status BLOCKED"] + blocked
|
|
1273
|
+
claimed = record["status"] in FINISHED
|
|
1274
|
+
if claimed and views[tid][0] == "CLOSED" and not blocked and tid not in refused:
|
|
1275
|
+
continue
|
|
1276
|
+
held = claims.get(tid)
|
|
1277
|
+
if tid in upstream:
|
|
1278
|
+
state = f"finished on {upstream[tid]['ref']}; pull to update"
|
|
1279
|
+
elif tid in cycles:
|
|
1280
|
+
state = cycles[tid]
|
|
1281
|
+
elif tid in refused:
|
|
1282
|
+
state = f"says {record['status']}, which the evidence does not support: workorder check {tid}"
|
|
1283
|
+
elif blocked:
|
|
1284
|
+
state = "blocked: " + ", ".join(blocked)
|
|
1285
|
+
elif held and not held["released"]:
|
|
1286
|
+
state = f"held by {held['who']} since {held['at']}"
|
|
1287
|
+
elif claimed and views[tid][0] == "DONE":
|
|
1288
|
+
state = "waiting for delivery: " + ", ".join(views[tid][2])
|
|
1289
|
+
else:
|
|
1290
|
+
state = "free"
|
|
1291
|
+
lines.append(f"{tid} {state}")
|
|
1292
|
+
return lines
|