Repository navigation
Expand file tree
/
Copy pathtask_queue.py
More file actions
executable file
·305 lines (264 loc) · 11.6 KB
/
Copy pathtask_queue.py
File metadata and controls
executable file
·305 lines (264 loc) · 11.6 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
#!/usr/bin/env python3
"""Parse, validate, and select from the TODO.md task queue.
`TODO.md` holds the open tasks and is the repository's only active planning
state; `just next-task` picks work out of it. `HISTORY.md` holds the tasks that
landed and `RETIRED.md` the queue TODO.md replaced, each moved there whole so
their identifiers stay unique and their record stays addressable. `check`
validates all three files together. The selector used to grep for an exact `Status: Ready`
line, so every decorated variant that had accumulated in the file --
`Status: **Ready.**`, `Status: Ready -- reframed`, `Status: Ready, but low
expected yield` -- was silently invisible, and the queue looked empty while
most of it was startable.
The fix is a machine-readable status line: one line, one state word from a
closed vocabulary, with every explanation moved to a following `Note:`
paragraph. This module is the parser for that convention. A status line it
cannot read is an error that stops the run, never a task it quietly skips.
"""
from __future__ import annotations
import argparse
import json
import re
import sys
from pathlib import Path
ROOT = Path(__file__).resolve().parents[1]
TASKS = ROOT / "TODO.md"
HISTORY = ROOT / "HISTORY.md"
RETIRED = ROOT / "RETIRED.md"
FIXTURES = ROOT / "tests" / "todo-status"
# The closed vocabulary. The state describes what is true of the task *now*:
# for a task whose first pass landed, it describes the remaining work, not the
# part that is finished -- that narrative belongs in the Note.
STATES = {
"Ready": "startable now with the listed files and fixtures",
"Blocked": "needs hardware or an external source not available here",
"Conditional": "start only when the named trigger occurs",
"Parking lot": "deliberately deferred; not the next best use of time",
"Done": "complete; kept as the record of what was established",
"Retired": "taken out of the queue unfinished; kept as the record, never selected",
}
SELECTABLE = ("Ready",)
HEADING = re.compile(r"^### (?P<id>[^.]+)\.\s*(?P<title>.+?)\s*$")
STATUS = re.compile(r"^Status:(?P<value>.*)$")
class Task:
def __init__(self, ident: str, title: str, state: str, line: int, block: list[str]):
self.ident = ident
self.title = title
self.state = state
self.line = line
self.block = block
@property
def selectable(self) -> bool:
return self.state in SELECTABLE
def parse(text: str, source: str) -> tuple[list[Task], list[str]]:
"""Return (tasks, errors). A task with an unreadable status is an error and
is not returned, so it can never be selected by accident."""
lines = text.splitlines()
errors: list[str] = []
tasks: list[Task] = []
starts = [i for i, line in enumerate(lines) if HEADING.match(line)]
# A `## ` section heading ends the preceding task block.
for pos, start in enumerate(starts):
end = len(lines)
for i in range(start + 1, len(lines)):
if HEADING.match(lines[i]) or lines[i].startswith("## "):
end = i
break
block = lines[start:end]
match = HEADING.match(lines[start])
assert match is not None
ident, title = match.group("id").strip(), match.group("title")
status_lines = [
(start + offset + 1, STATUS.match(line))
for offset, line in enumerate(block)
if STATUS.match(line)
]
if not status_lines:
errors.append(
f"{source}:{start + 1}: task {ident!r} has no `Status:` line"
)
continue
if len(status_lines) > 1:
where = ", ".join(str(n) for n, _ in status_lines)
errors.append(
f"{source}:{start + 1}: task {ident!r} has {len(status_lines)} "
f"`Status:` lines (lines {where}); exactly one is required"
)
continue
status_line, status_match = status_lines[0]
assert status_match is not None
# The status must be the first prose in the block: a status buried
# below narrative is one a reader will not trust as current.
first_prose = next(
(start + offset + 1 for offset, line in enumerate(block[1:], start=1) if line.strip()),
None,
)
if first_prose != status_line:
errors.append(
f"{source}:{status_line}: task {ident!r} has its `Status:` line "
f"below other prose (first prose is line {first_prose}); the "
"status must be the first line under the heading"
)
continue
value = status_match.group("value").strip()
if value not in STATES:
errors.append(
f"{source}:{status_line}: task {ident!r} has unreadable status "
f"{value!r}; expected exactly one of "
f"{', '.join(sorted(STATES))} with any explanation moved to a "
"following `Note:` paragraph"
)
continue
tasks.append(Task(ident, title, value, start + 1, block))
seen: dict[str, Task] = {}
for task in tasks:
if task.ident in seen:
errors.append(
f"{source}:{task.line}: duplicate task identifier {task.ident!r} "
f"(already used at line {seen[task.ident].line})"
)
else:
seen[task.ident] = task
return tasks, errors
def load(path: Path = TASKS) -> tuple[list[Task], list[str]]:
return parse(path.read_text(encoding="utf-8"), str(path.relative_to(ROOT)))
def cmd_check(_args: argparse.Namespace) -> int:
tasks, errors = load()
history, history_errors = load(HISTORY)
retired, retired_errors = load(RETIRED)
errors = list(errors) + history_errors + retired_errors
for task in tasks:
if task.state in ("Done", "Retired"):
target = "HISTORY.md" if task.state == "Done" else "RETIRED.md"
errors.append(
f"TODO.md:{task.line}: task {task.ident!r} is {task.state}; move its block to {target}"
)
for name, archive, state in (("HISTORY.md", history, "Done"), ("RETIRED.md", retired, "Retired")):
for task in archive:
if task.state != state:
errors.append(
f"{name}:{task.line}: task {task.ident!r} is {task.state!r}; only {state} tasks live here"
)
owner: dict[str, str] = {}
for name, group in (("TODO.md", tasks), ("HISTORY.md", history), ("RETIRED.md", retired)):
for task in group:
if task.ident in owner:
errors.append(
f"{name}:{task.line}: task {task.ident!r} also appears in {owner[task.ident]}"
)
else:
owner[task.ident] = name
if errors:
print("TODO.md/HISTORY.md/RETIRED.md status metadata is malformed:", file=sys.stderr)
for error in errors:
print(f" {error}", file=sys.stderr)
return 1
if not any(task.selectable for task in tasks):
print(
"TODO.md: no task is startable; every task is Blocked, "
"Conditional, or parked. If that is wrong, a status is wrong.",
file=sys.stderr,
)
return 1
ready = sum(1 for task in tasks if task.selectable)
print(
f"task queue OK: {len(tasks)} open tasks, {ready} startable; "
f"{len(history)} completed in HISTORY.md, {len(retired)} in RETIRED.md"
)
return 0
def cmd_next(_args: argparse.Namespace) -> int:
tasks, errors = load()
if errors:
print("TODO.md status metadata is malformed; refusing to select:", file=sys.stderr)
for error in errors:
print(f" {error}", file=sys.stderr)
return 1
for task in tasks:
if task.selectable:
print("\n".join(task.block).rstrip())
return 0
print("No startable task in TODO.md.", file=sys.stderr)
return 1
def cmd_list(args: argparse.Namespace) -> int:
tasks, errors = load()
if args.format == "json":
payload = {
"tasks": [
{
"id": task.ident,
"title": task.title,
"status": task.state,
"selectable": task.selectable,
"line": task.line,
}
for task in tasks
],
"errors": errors,
}
print(json.dumps(payload, indent=2))
return 1 if errors else 0
width = max((len(task.state) for task in tasks), default=0)
for task in tasks:
marker = "*" if task.selectable else " "
print(f"{marker} {task.state:<{width}} {task.ident}. {task.title}")
for error in errors:
print(f" ERROR {error}", file=sys.stderr)
return 1 if errors else 0
def cmd_selftest(_args: argparse.Namespace) -> int:
"""Run the parser over the recorded regression fixtures.
The malformed fixture holds the real forms this file actually contained
before the convention landed, so a future selector rewrite cannot go back
to skipping them.
"""
expectations = json.loads((FIXTURES / "expected.json").read_text(encoding="utf-8"))
failures: list[str] = []
for name, expected in sorted(expectations.items()):
path = FIXTURES / name
tasks, errors = parse(path.read_text(encoding="utf-8"), name)
# Selection refuses outright when anything in the file is malformed,
# so the expectation records what `next` would really hand back.
selected = (
None
if errors
else next((task.ident for task in tasks if task.selectable), None)
)
if selected != expected["next"]:
failures.append(
f"{name}: selected {selected!r}, expected {expected['next']!r}"
)
got = [task.ident for task in tasks]
if got != expected["parsed"]:
failures.append(f"{name}: parsed {got}, expected {expected['parsed']}")
for fragment in expected["errors"]:
if not any(fragment in error for error in errors):
failures.append(
f"{name}: expected an error containing {fragment!r}; got {errors}"
)
if len(errors) != len(expected["errors"]):
failures.append(
f"{name}: {len(errors)} errors, expected {len(expected['errors'])}: {errors}"
)
for failure in failures:
print(f" {failure}", file=sys.stderr)
if failures:
print(f"task_queue selftest FAILED ({len(failures)})", file=sys.stderr)
return 1
print(f"task_queue selftest OK ({len(expectations)} fixtures)")
return 0
def main(argv: list[str]) -> int:
parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
parser.add_argument("--check", action="store_true", help="alias for the `check` command")
sub = parser.add_subparsers(dest="command")
sub.add_parser("check", help="validate every task's status metadata").set_defaults(func=cmd_check)
sub.add_parser("next", help="print the first startable task block").set_defaults(func=cmd_next)
listing = sub.add_parser("list", help="print every task with its state")
listing.add_argument("--format", choices=("text", "json"), default="text")
listing.set_defaults(func=cmd_list)
sub.add_parser("selftest", help="run the status-line regression fixtures").set_defaults(
func=cmd_selftest
)
args = parser.parse_args(argv)
if args.check or args.command is None:
return cmd_check(args)
return args.func(args)
if __name__ == "__main__":
raise SystemExit(main(sys.argv[1:]))