lab-kit-cli 1.13.0__tar.gz → 1.15.0__tar.gz
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.
- {lab_kit_cli-1.13.0 → lab_kit_cli-1.15.0}/CHANGELOG.md +26 -0
- {lab_kit_cli-1.13.0 → lab_kit_cli-1.15.0}/PKG-INFO +1 -1
- {lab_kit_cli-1.13.0 → lab_kit_cli-1.15.0}/docs/model.md +27 -3
- {lab_kit_cli-1.13.0 → lab_kit_cli-1.15.0}/pyproject.toml +1 -1
- {lab_kit_cli-1.13.0 → lab_kit_cli-1.15.0}/skills/lab-review/SKILL.md +5 -0
- {lab_kit_cli-1.13.0 → lab_kit_cli-1.15.0}/skills/lab-set-up/SKILL.md +9 -6
- {lab_kit_cli-1.13.0 → lab_kit_cli-1.15.0}/skills/lab-work/SKILL.md +7 -1
- {lab_kit_cli-1.13.0 → lab_kit_cli-1.15.0}/src/lab_kit/__init__.py +1 -1
- {lab_kit_cli-1.13.0 → lab_kit_cli-1.15.0}/src/lab_kit/checks.py +4 -0
- {lab_kit_cli-1.13.0 → lab_kit_cli-1.15.0}/src/lab_kit/cli.py +6 -3
- {lab_kit_cli-1.13.0 → lab_kit_cli-1.15.0}/src/lab_kit/history.py +8 -0
- {lab_kit_cli-1.13.0 → lab_kit_cli-1.15.0}/src/lab_kit/record.py +12 -0
- {lab_kit_cli-1.13.0 → lab_kit_cli-1.15.0}/src/lab_kit/storylines.py +87 -1
- {lab_kit_cli-1.13.0 → lab_kit_cli-1.15.0}/src/lab_kit/write.py +19 -2
- {lab_kit_cli-1.13.0 → lab_kit_cli-1.15.0}/tests/test_held.py +61 -0
- {lab_kit_cli-1.13.0 → lab_kit_cli-1.15.0}/tests/test_storylines.py +43 -1
- {lab_kit_cli-1.13.0 → lab_kit_cli-1.15.0}/.github/workflows/ci.yml +0 -0
- {lab_kit_cli-1.13.0 → lab_kit_cli-1.15.0}/.github/workflows/policy.yml +0 -0
- {lab_kit_cli-1.13.0 → lab_kit_cli-1.15.0}/.github/workflows/release.yml +0 -0
- {lab_kit_cli-1.13.0 → lab_kit_cli-1.15.0}/.gitignore +0 -0
- {lab_kit_cli-1.13.0 → lab_kit_cli-1.15.0}/AGENTS.md +0 -0
- {lab_kit_cli-1.13.0 → lab_kit_cli-1.15.0}/CLAUDE.md +0 -0
- {lab_kit_cli-1.13.0 → lab_kit_cli-1.15.0}/CONTRIBUTING.md +0 -0
- {lab_kit_cli-1.13.0 → lab_kit_cli-1.15.0}/LICENSE +0 -0
- {lab_kit_cli-1.13.0 → lab_kit_cli-1.15.0}/README.md +0 -0
- {lab_kit_cli-1.13.0 → lab_kit_cli-1.15.0}/agents/reviewer.md +0 -0
- {lab_kit_cli-1.13.0 → lab_kit_cli-1.15.0}/method/METHOD.md +0 -0
- {lab_kit_cli-1.13.0 → lab_kit_cli-1.15.0}/skills/lab-mission/SKILL.md +0 -0
- {lab_kit_cli-1.13.0 → lab_kit_cli-1.15.0}/skills/lab-talk/SKILL.md +0 -0
- {lab_kit_cli-1.13.0 → lab_kit_cli-1.15.0}/src/lab_kit/runs.py +0 -0
- {lab_kit_cli-1.13.0 → lab_kit_cli-1.15.0}/src/lab_kit/site.py +0 -0
- {lab_kit_cli-1.13.0 → lab_kit_cli-1.15.0}/src/lab_kit/supervise.py +0 -0
- {lab_kit_cli-1.13.0 → lab_kit_cli-1.15.0}/src/lab_kit/views.py +0 -0
- {lab_kit_cli-1.13.0 → lab_kit_cli-1.15.0}/tests/test_drafts.py +0 -0
- {lab_kit_cli-1.13.0 → lab_kit_cli-1.15.0}/tests/test_flow.py +0 -0
- {lab_kit_cli-1.13.0 → lab_kit_cli-1.15.0}/tests/test_integrity.py +0 -0
- {lab_kit_cli-1.13.0 → lab_kit_cli-1.15.0}/tests/test_mission.py +0 -0
- {lab_kit_cli-1.13.0 → lab_kit_cli-1.15.0}/tests/test_needs.py +0 -0
- {lab_kit_cli-1.13.0 → lab_kit_cli-1.15.0}/tests/test_order.py +0 -0
- {lab_kit_cli-1.13.0 → lab_kit_cli-1.15.0}/tests/test_parked.py +0 -0
- {lab_kit_cli-1.13.0 → lab_kit_cli-1.15.0}/tests/test_refusals.py +0 -0
- {lab_kit_cli-1.13.0 → lab_kit_cli-1.15.0}/tests/test_site.py +0 -0
- {lab_kit_cli-1.13.0 → lab_kit_cli-1.15.0}/tests/test_states.py +0 -0
- {lab_kit_cli-1.13.0 → lab_kit_cli-1.15.0}/tests/test_vocabulary.py +0 -0
- {lab_kit_cli-1.13.0 → lab_kit_cli-1.15.0}/tests/test_wording.py +0 -0
- {lab_kit_cli-1.13.0 → lab_kit_cli-1.15.0}/tools/import_run.py +0 -0
|
@@ -1,5 +1,31 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 1.15.0
|
|
4
|
+
|
|
5
|
+
- **A later results review can supersede an earlier one, by name.** A reviewed row that had to be read another
|
|
6
|
+
way, to the same result (a command that read the run by a fixed path, rewritten to read `$RUN` so the gate
|
|
7
|
+
passes), was held as it was: `lab check` said "a row that a review had passed in ... is gone or changed", a
|
|
8
|
+
second passing review did not lift it, and putting the old row back brought back the failure it was changed
|
|
9
|
+
to fix. `lab review <experiment> results pass "<why>" --supersedes <of>` now names the earlier passing results
|
|
10
|
+
review by its `of`; it ends the note with "Supersedes the results review of <of>.", and the rows that review
|
|
11
|
+
read are held no more once it is committed together with the rows it read, which are held in their place. A review that does not name the earlier one
|
|
12
|
+
still supersedes nothing, and a note may not end with that sentence by hand. `lab review` refuses it on a plan or a failing review, for an `of` no earlier passing
|
|
13
|
+
results review has, and when the earlier review read the rows as they are now; `lab check` refuses a note that
|
|
14
|
+
names no earlier passing results review of other rows.
|
|
15
|
+
- The skill `lab-review` changed: run `lab init` in a lab after upgrading.
|
|
16
|
+
|
|
17
|
+
## 1.14.0
|
|
18
|
+
|
|
19
|
+
- **A home map has Current storylines.** When `lab.toml` names active storylines, one of the library's home
|
|
20
|
+
maps has a section `<h2 id="current-storylines">Current storylines</h2>` whose rows are the active storyline
|
|
21
|
+
pages and nothing else, so every lab shows its storylines in the same place. `lab check` refuses a library
|
|
22
|
+
with no such section or with two, the section on a map that is not a home map, an active storyline with no
|
|
23
|
+
row there, a row listed twice, and a row there that is not an active storyline. Rows are read as folio reads
|
|
24
|
+
them: the first link of an item in a `rows` list, up to the next `h2` or `h3`. lab-set-up writes the section,
|
|
25
|
+
and lab-work keeps it when a storyline is added or retired.
|
|
26
|
+
- Upgrading: run `lab init`. A lab that names its storylines also moves their rows under Current storylines
|
|
27
|
+
(`folio map move <id> --to <map>#current-storylines`) before `lab check` passes.
|
|
28
|
+
|
|
3
29
|
## 1.13.0
|
|
4
30
|
|
|
5
31
|
- **A scope page is a storyline.** A storyline is one argument the lab is building from its findings, for one
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.5
|
|
2
2
|
Name: lab-kit-cli
|
|
3
|
-
Version: 1.
|
|
3
|
+
Version: 1.15.0
|
|
4
4
|
Summary: A research lab's record, its method, and the command that keeps both.
|
|
5
5
|
Project-URL: Homepage, https://github.com/pierg/lab-kit
|
|
6
6
|
Project-URL: Issues, https://github.com/pierg/lab-kit/issues
|
|
@@ -199,6 +199,20 @@ Each arrow is a command that refuses when the step before it is missing. You see
|
|
|
199
199
|
problem `lab check` reports at every step: a different result is a new experiment. A review is
|
|
200
200
|
bound to the rows it read by its `of`, so only those are held: a draft row committed after a
|
|
201
201
|
review, which that review never read, may still be corrected before the next review reads it.
|
|
202
|
+
**A review that supersedes another.** A reviewed row that must be read another way, to the same
|
|
203
|
+
result (a command that read the run by a fixed path and now reads `$RUN`), is not a new
|
|
204
|
+
experiment. A later results review that passes the new rows says so by name: `lab review
|
|
205
|
+
<experiment> results pass "<why the rows changed, and what was re-read>" --supersedes <of>`, where
|
|
206
|
+
`<of>` is the earlier passing results review's `of` (eight to sixteen of its first hex digits).
|
|
207
|
+
The command ends the note with "Supersedes the results review of <of>.". Once that review is
|
|
208
|
+
committed together with the rows it read, the rows the earlier review read are held no more, and
|
|
209
|
+
the new rows are held in their place; until then it supersedes nothing. A note cannot end with that
|
|
210
|
+
sentence except through `--supersedes`.
|
|
211
|
+
A later review that passes changed rows without naming the earlier one supersedes nothing, so the
|
|
212
|
+
old rows are still held. `lab review` refuses `--supersedes` on a plan review or a failing one, an
|
|
213
|
+
`of` that no earlier passing results review has, and a review that read the rows as they are now;
|
|
214
|
+
`lab check` refuses a note that names a review that is not an earlier passing results review of
|
|
215
|
+
other rows.
|
|
202
216
|
**The history that is read.** The check reads the history of the record under the lab's root as
|
|
203
217
|
that root is now. Moving the lab's root inside its repository, or to another repository, starts
|
|
204
218
|
again what is held: what was committed under the old root is not compared. And it needs the
|
|
@@ -402,7 +416,8 @@ moves from included to excluded. Adding, merging or retiring a storyline is dire
|
|
|
402
416
|
you. A question's or an experiment's So far gives the current finding, not the story of the bugs on the way:
|
|
403
417
|
the replaced experiments and the reasons they were replaced keep that story.
|
|
404
418
|
|
|
405
|
-
A lab opts in by naming the pages in `lab.toml` (section 9)
|
|
419
|
+
A lab opts in by naming the pages in `lab.toml` (section 9), and its library's home map lists them under one
|
|
420
|
+
section, Current storylines. Then `lab check` holds that section and each scope table:
|
|
406
421
|
included lists only finished work that is not void, replaced or dropped, open only work still to do, nothing
|
|
407
422
|
parked or dropped is in either, and a goal, a question or a step sits in one row; a storyline page committed
|
|
408
423
|
before a result about something it lists under included or open is noted. `lab now` lists each storyline's
|
|
@@ -821,7 +836,8 @@ with each quote inside written twice, as a spreadsheet writes it, is read withou
|
|
|
821
836
|
quote is a character like any other.
|
|
822
837
|
|
|
823
838
|
**`reviews.tsv`** is written by `lab review`: `date`, `stage` (plan, results), `verdict` (pass, fail),
|
|
824
|
-
`by`, `of` (a hash of what was read), `note`.
|
|
839
|
+
`by`, `of` (a hash of what was read), `note`. A results review written with `--supersedes` ends its
|
|
840
|
+
note with "Supersedes the results review of <of>." (section 3, Reviewed rows stay).
|
|
825
841
|
|
|
826
842
|
**`resources.toml`** has one table per resource: `what`, `key` (where it is kept), `rules` (a list of
|
|
827
843
|
sentences), `retired` (why, once it is no longer used), and for a metered resource `unit`, `granted`,
|
|
@@ -962,7 +978,15 @@ a question or a step has one row on a page: where another row needs to mention i
|
|
|
962
978
|
without its link. A question written in one row and a step under it written in another is allowed: the open
|
|
963
979
|
question with its one finished step included is the usual case. A decision may be cited in any row. In
|
|
964
980
|
`lab now` and in the note on a stale page, a goal or a question written under included or open stands for
|
|
965
|
-
every step under it.
|
|
981
|
+
every step under it.
|
|
982
|
+
|
|
983
|
+
While a storyline is active, one of the library's home maps (`home.maps` in `folio.yaml`) has a section headed
|
|
984
|
+
`<h2 id="current-storylines">Current storylines</h2>`, and its rows are the active storyline pages and nothing
|
|
985
|
+
else. A row is what folio counts as one: the first link, to `/content/<path>/`, of an item of a list whose classes
|
|
986
|
+
include `rows`, from the heading to the next `h2` or `h3`. A link in prose or in a row's reason is not a row. It
|
|
987
|
+
is the one place those pages have on a map; the overview and a retired storyline have theirs under other
|
|
988
|
+
headings. The library has one such section, and no map that is not a home map has one. A lab without
|
|
989
|
+
`[storylines]` has none of this.
|
|
966
990
|
|
|
967
991
|
**Worked-out states.** A goal is open until `reached: true` makes it done or `dropped:` drops it. A
|
|
968
992
|
question is waiting while the decision it came from is open, then open, then done with its answer; it
|
|
@@ -5,7 +5,7 @@ build-backend = "hatchling.build"
|
|
|
5
5
|
[project]
|
|
6
6
|
dynamic = ["readme"]
|
|
7
7
|
name = "lab-kit-cli"
|
|
8
|
-
version = "1.
|
|
8
|
+
version = "1.15.0"
|
|
9
9
|
description = "A research lab's record, its method, and the command that keeps both."
|
|
10
10
|
license = "MIT"
|
|
11
11
|
authors = [{ name = "Piergiuseppe Mallozzi" }]
|
|
@@ -42,6 +42,11 @@ A failed plan is fixed by its author and read again.
|
|
|
42
42
|
can read, saying what you conclude ("The numbers are what the rows say, and the bars were fixed
|
|
43
43
|
before the run."). What you re-ran and what you could not verify comes after it: the page shows
|
|
44
44
|
the first sentence and folds the rest.
|
|
45
|
+
5. When rows that an earlier results review passed have changed since (`lab check` says "a row that a
|
|
46
|
+
review had passed in ... is gone or changed"), read what changed (`git diff` of `results.tsv` from
|
|
47
|
+
the commit it names) as well as the rows. Pass it only when each changed row still reports the same
|
|
48
|
+
result, read another way, and add `--supersedes <of>`, naming that earlier review's `of` from
|
|
49
|
+
`reviews.tsv`: the note says why the rows changed. A different result is a new experiment: fail it.
|
|
45
50
|
|
|
46
51
|
A failed results review is final for that experiment. Say in the note what a replacement must do
|
|
47
52
|
differently. Its numbers can then be cited nowhere: if a storyline page lists it under included, `lab check`
|
|
@@ -45,12 +45,15 @@ You set the lab up in one discussion with the operator, so that everything it se
|
|
|
45
45
|
`views:`. Set it up with folio's own skill if it is not there.
|
|
46
46
|
12. If the lab will argue its findings to an audience (a paper, a talk, a report), ask the operator which
|
|
47
47
|
storylines it aims at now, for whom and where (it is direction, and may stay empty). A storyline is the
|
|
48
|
-
argument such an output is written from, not the output itself. Write the overview page (for example
|
|
49
|
-
write skill: the words on one running example, the
|
|
50
|
-
findings and the criticisms. For each storyline,
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
`
|
|
48
|
+
argument such an output is written from, not the output itself. Write the overview page (for example
|
|
49
|
+
`entries/where-the-results-stand`) with folio's write skill: the words on one running example, the
|
|
50
|
+
workflow, the related work, and empty sections for the findings and the criticisms. For each storyline,
|
|
51
|
+
write `entries/storyline-<slug>`: its thesis, then the scope table (target audience and venues, core
|
|
52
|
+
thesis, experiments included, excluded or superseded, open), with the last three cells marked
|
|
53
|
+
`data-scope="included"`, `"excluded"` and `"open"`. Name them in `lab.toml` under `[storylines]`
|
|
54
|
+
(`overview`, `active`), and give each storyline page its row on a home map under the heading Current
|
|
55
|
+
storylines (`folio map add <map> <id> --section "Current storylines"`, which writes
|
|
56
|
+
`<h2 id="current-storylines">`); nothing else goes under that heading. No card names a storyline (method rule 8).
|
|
54
57
|
13. Commit. Git is what holds the record: nothing is held before the first commit, and
|
|
55
58
|
`lab check --strict` says so.
|
|
56
59
|
|
|
@@ -127,8 +127,14 @@ row, move it to included, or to excluded if it is void or no longer serves the a
|
|
|
127
127
|
that fails makes the experiment void: take it off every included row. `lab check` refuses what a row may
|
|
128
128
|
not list, and notes a storyline committed before a result about something it lists.
|
|
129
129
|
|
|
130
|
+
A home map has the section Current storylines (`<h2 id="current-storylines">`): one row per active storyline
|
|
131
|
+
page, and nothing else. `lab check` holds that its rows and `active` name the same pages.
|
|
132
|
+
|
|
130
133
|
Adding, splitting, merging or retiring a storyline is direction: bring it to the operator (the lab-talk skill),
|
|
131
|
-
then change the pages
|
|
134
|
+
then change the pages, `[storylines]` and the Current storylines rows. A new storyline page gets its row with
|
|
135
|
+
`folio map add <map> <id> --section "Current storylines"`; a page that already has a place moves there with
|
|
136
|
+
`folio map move <id> --to <map>#current-storylines`. A retired storyline's page leaves `active` and stays in the
|
|
137
|
+
library: move its row under another heading (`folio map move <id> --to <map>#<heading>`).
|
|
132
138
|
|
|
133
139
|
## When to open a decision
|
|
134
140
|
|
|
@@ -1,2 +1,2 @@
|
|
|
1
1
|
"""lab-kit: a research lab's record, its method, and the command that keeps both."""
|
|
2
|
-
__version__ = "1.
|
|
2
|
+
__version__ = "1.15.0"
|
|
@@ -305,6 +305,10 @@ def run(lab, rederive=True):
|
|
|
305
305
|
if r["stage"] not in ("plan", "results") or r["verdict"] not in ("pass", "fail") or not R.day(r["date"]) or not r["of"]:
|
|
306
306
|
bad("reviews", p, f"a row of reviews.tsv is not one `lab review` wrote: {R.flat(' '.join(r.values()))[:60]!r}")
|
|
307
307
|
break
|
|
308
|
+
for i, r in enumerate(x["reviews"]):
|
|
309
|
+
m = R.SUPERSEDING.search((r.get("note") or "").rstrip()) if r.get("stage") == "results" and r.get("verdict") == "pass" else None
|
|
310
|
+
if m and not any(e.get("stage") == "results" and e.get("verdict") == "pass" and e.get("of") == m.group(1) and e.get("of") != r.get("of") for e in x["reviews"][:i]):
|
|
311
|
+
bad("reviews", p, f"a results review supersedes {m.group(1)}, which is no earlier results review of other rows that passed")
|
|
308
312
|
if x["results"]:
|
|
309
313
|
if not x["lock"] or not x["finished"]:
|
|
310
314
|
bad("results", p, "has results with no locked plan and finished run behind them")
|
|
@@ -34,7 +34,9 @@ For evidence
|
|
|
34
34
|
lab runs close <run> "<why>" [--used <resource>=<amount>]... a run whose process died; --used for one that wrote no used.json
|
|
35
35
|
lab runs close <run> "<why>" --used <resource>=<amount>... --evidence <folder> an ended run that did not record what it used of a resource it ran on
|
|
36
36
|
lab runs lost <run> "<why>" [--used <resource>=<amount>]... a run that started and whose folder is gone for good
|
|
37
|
-
lab review <experiment> plan|results pass|fail "<note>" [--by <who>]
|
|
37
|
+
lab review <experiment> plan|results pass|fail "<note>" [--by <who>] [--supersedes <of>]
|
|
38
|
+
--supersedes: a results review that passes rows changed after the review
|
|
39
|
+
whose `of` it names had passed them; the note says why they changed
|
|
38
40
|
lab check [--no-rederive] [--strict] runs every command in results.tsv: only on a lab you trust. --strict fails when
|
|
39
41
|
history or the store could not be checked, as in CI
|
|
40
42
|
Once
|
|
@@ -191,10 +193,11 @@ def main(argv=None):
|
|
|
191
193
|
else:
|
|
192
194
|
raise SystemExit(USAGE)
|
|
193
195
|
elif cmd == "review":
|
|
194
|
-
|
|
196
|
+
named = "--supersedes" in rest
|
|
197
|
+
by, supersedes = flag("--by"), flag("--supersedes")
|
|
195
198
|
if len(rest) != 4:
|
|
196
199
|
raise SystemExit(USAGE)
|
|
197
|
-
print(f"recorded in {write.review(lab, rest[0], rest[1], rest[2], rest[3], by or None)}")
|
|
200
|
+
print(f"recorded in {write.review(lab, rest[0], rest[1], rest[2], rest[3], by or None, supersedes if named else None)}")
|
|
198
201
|
elif cmd == "check":
|
|
199
202
|
if set(rest) - {"--no-rederive", "--strict"}:
|
|
200
203
|
raise SystemExit(USAGE)
|
|
@@ -382,6 +382,7 @@ def check(lab):
|
|
|
382
382
|
rows, read = where.rsplit("/", 1)[0] + "/results.tsv", set()
|
|
383
383
|
if rows not in now:
|
|
384
384
|
continue # never committed, so nothing is held; or committed and gone, which is said above
|
|
385
|
+
held_at = [] # (commit, the rows it holds, the last review that passed them there), newest first
|
|
385
386
|
for c, path in reversed(commits + versions.get(rows, [])): # every commit that touched the reviews or the rows
|
|
386
387
|
folder = os.path.dirname(path)
|
|
387
388
|
if c in read:
|
|
@@ -395,6 +396,13 @@ def check(lab):
|
|
|
395
396
|
seals = [l[5] for l in listed if len(l) >= 6 and l[1] == "run" and l[2] == "ended" and l[4] == "0"] # the finished run, as that commit lists it
|
|
396
397
|
if passed[-1].get("of") not in {R.text_hash(R.text_hash(was) + str(seal))[:16] for seal in seals}:
|
|
397
398
|
continue # the last review that passed there read other rows than these
|
|
399
|
+
held_at.append((c, was, passed[-1]))
|
|
400
|
+
# A passing results review that names an earlier one by its `of` (`lab review ... --supersedes`) supersedes it
|
|
401
|
+
# only once it is committed together with the rows it read: then those rows are held instead of the earlier ones.
|
|
402
|
+
gone = R.superseded([r for _, _, r in held_at])
|
|
403
|
+
for c, was, review in held_at:
|
|
404
|
+
if review.get("of") in gone:
|
|
405
|
+
continue # a later review, committed with the rows it read, superseded it and said why
|
|
398
406
|
lost = subsequence(was.splitlines(), R.read(os.path.join(root, now[rows][0])).splitlines())
|
|
399
407
|
if lost is not None:
|
|
400
408
|
bad(now[rows][0], f"a row that a review had passed in {c[:8]} is gone or changed: {lost[:70]!r}. Reviewed rows stay; a different result is a new experiment")
|
|
@@ -52,6 +52,18 @@ RUN_ID = re.compile(r"^\d{8}-\d{4}_G\d+\.Q\d+\.\d+_[a-z0-9]{4}$") # <date>-<tim
|
|
|
52
52
|
# it lost (what it used, and why). A file written before `used` and `note` existed has the first six columns.
|
|
53
53
|
LEDGER = ("run", "kind", "what", "at", "exit", "seal", "used", "note")
|
|
54
54
|
COLUMNS = {"results.tsv": ("name", "label", "value", "reads", "versus", "command"), "reviews.tsv": ("date", "stage", "verdict", "by", "of", "note")}
|
|
55
|
+
# A results review that passed rows changed after an earlier one passed them ends its note with this, naming the
|
|
56
|
+
# earlier review by its `of` (`lab review ... --supersedes`): the rows the earlier one read are then held no more.
|
|
57
|
+
SUPERSEDES = "Supersedes the results review of {}."
|
|
58
|
+
SUPERSEDING = re.compile(r"Supersedes the results review of ([0-9a-f]{16})\.$")
|
|
59
|
+
|
|
60
|
+
|
|
61
|
+
def superseded(reviews):
|
|
62
|
+
"""The `of` of each results review that a later passing results review supersedes."""
|
|
63
|
+
found = (SUPERSEDING.search((r.get("note") or "").rstrip()) for r in reviews if r.get("stage") == "results" and r.get("verdict") == "pass")
|
|
64
|
+
return {m.group(1) for m in found if m}
|
|
65
|
+
|
|
66
|
+
|
|
55
67
|
HASH = 2 # how a folder is hashed in the locks and runs made now; one without the marker was made with the first way
|
|
56
68
|
NUMBER = re.compile(r"[+-]?(?:[0-9]+(?:\.[0-9]*)?|\.[0-9]+)(?:[eE][+-]?[0-9]+)?")
|
|
57
69
|
LISTS = {"goal": ("see",), "question": ("needs", "see"), "experiment": ("needs", "uses", "see"), "build": ("needs", "commits", "tests", "see"),
|
|
@@ -10,7 +10,7 @@ serve no storyline.
|
|
|
10
10
|
"""
|
|
11
11
|
from __future__ import annotations
|
|
12
12
|
|
|
13
|
-
import os, re
|
|
13
|
+
import glob, os, re
|
|
14
14
|
from html.parser import HTMLParser
|
|
15
15
|
|
|
16
16
|
from . import record as R
|
|
@@ -65,6 +65,70 @@ class _Scope(HTMLParser):
|
|
|
65
65
|
self.title += data
|
|
66
66
|
|
|
67
67
|
|
|
68
|
+
SECTION = "current-storylines"
|
|
69
|
+
PAGE_LINK = re.compile(r"^/content/(.+?)/?(?:index\.html)?(?:[#?].*)?$")
|
|
70
|
+
|
|
71
|
+
|
|
72
|
+
class _Section(HTMLParser):
|
|
73
|
+
"""The rows of a map's "Current storylines" section, as folio places them: from `<h2 id="current-storylines">`
|
|
74
|
+
to the next `h2` or `h3` or the end of `main`, each row the first link of an `<li>` in a list whose classes
|
|
75
|
+
include `rows`. A link in prose, in a row's reason or in another list is not a row."""
|
|
76
|
+
|
|
77
|
+
def __init__(self):
|
|
78
|
+
super().__init__(convert_charrefs=True)
|
|
79
|
+
self.found, self.links, self._in, self._lists, self._li = 0, [], False, [], False
|
|
80
|
+
|
|
81
|
+
def handle_starttag(self, tag, attrs):
|
|
82
|
+
a = dict(attrs)
|
|
83
|
+
if tag in ("h2", "h3"):
|
|
84
|
+
self._in = tag == "h2" and a.get("id") == SECTION
|
|
85
|
+
self.found += self._in
|
|
86
|
+
elif not self._in:
|
|
87
|
+
return
|
|
88
|
+
elif tag in ("ul", "ol"):
|
|
89
|
+
self._lists.append("rows" in (a.get("class") or "").split())
|
|
90
|
+
elif tag == "li":
|
|
91
|
+
self._li = bool(self._lists and self._lists[-1])
|
|
92
|
+
elif tag == "a" and self._li:
|
|
93
|
+
self._li = False # only the row's first link places a page
|
|
94
|
+
m = PAGE_LINK.match(a.get("href") or "")
|
|
95
|
+
if m:
|
|
96
|
+
self.links.append(m.group(1).strip("/"))
|
|
97
|
+
|
|
98
|
+
def handle_endtag(self, tag):
|
|
99
|
+
if tag == "main":
|
|
100
|
+
self._in = False
|
|
101
|
+
elif self._in and tag in ("ul", "ol") and self._lists:
|
|
102
|
+
self._lists.pop()
|
|
103
|
+
elif tag == "li":
|
|
104
|
+
self._li = False
|
|
105
|
+
|
|
106
|
+
|
|
107
|
+
def home_maps(lab):
|
|
108
|
+
"""The map files the library's charter lists under `home.maps`."""
|
|
109
|
+
import yaml
|
|
110
|
+
docs = os.path.join(lab.root, lab.cfg.get("library", "docs"))
|
|
111
|
+
try:
|
|
112
|
+
charter = yaml.safe_load(open(os.path.join(docs, "folio.yaml"))) or {}
|
|
113
|
+
except (OSError, yaml.YAMLError):
|
|
114
|
+
return []
|
|
115
|
+
home = charter.get("home") if isinstance(charter, dict) else None
|
|
116
|
+
names = (home.get("maps") if isinstance(home, dict) else None) or []
|
|
117
|
+
return [os.path.join(docs, "content", "maps", f"{n}.html") for n in names if isinstance(n, str)]
|
|
118
|
+
|
|
119
|
+
|
|
120
|
+
def section(lab):
|
|
121
|
+
"""[(map file, [page paths], on a home map)] for each map of the library with a "Current storylines" section."""
|
|
122
|
+
home = {os.path.normpath(f) for f in home_maps(lab)}
|
|
123
|
+
out = []
|
|
124
|
+
for f in sorted(glob.glob(os.path.join(lab.root, lab.cfg.get("library", "docs"), "content", "maps", "*.html")),
|
|
125
|
+
key=lambda f: (os.path.normpath(f) not in home, f)):
|
|
126
|
+
s = _Section()
|
|
127
|
+
s.feed(R.read(f))
|
|
128
|
+
out += [(f, s.links, os.path.normpath(f) in home)] * s.found
|
|
129
|
+
return out
|
|
130
|
+
|
|
131
|
+
|
|
68
132
|
def page_file(lab, path):
|
|
69
133
|
return os.path.join(lab.root, lab.cfg.get("library", "docs"), "content", path.strip("/"), "index.html")
|
|
70
134
|
|
|
@@ -180,6 +244,28 @@ def check(lab, bad, notes):
|
|
|
180
244
|
for a, b in (("included", "excluded"), ("included", "open"), ("open", "excluded")):
|
|
181
245
|
for i in sorted(i for i in set(rows[a]) & set(rows[b]) if lab.nodes.get(i, {}).get("type") != "decision"): # a decision may be cited wherever it explains a row
|
|
182
246
|
bad("storylines", where, f"lists {i} under both {a} and {b}: a step or a question has one row; where another row needs it, name it in words, without its link")
|
|
247
|
+
found = section(lab)
|
|
248
|
+
for f, _, home in found:
|
|
249
|
+
if not home:
|
|
250
|
+
bad("storylines", lab.rel(f), "has a \"Current storylines\" section but is not a home map (`home.maps` in "
|
|
251
|
+
"folio.yaml): the section goes on a home map, where its rows are the pages' places")
|
|
252
|
+
found = [x for x in found if x[2]]
|
|
253
|
+
if not found and active:
|
|
254
|
+
bad("storylines", "lab.toml", f"no home map of the library has a section `<h2 id=\"{SECTION}\">Current storylines</h2>`: "
|
|
255
|
+
"one row for each active storyline")
|
|
256
|
+
for f, _, _ in found[1:]:
|
|
257
|
+
bad("storylines", lab.rel(f), f"has a second \"Current storylines\" section; the library has one, on {lab.rel(found[0][0])}")
|
|
258
|
+
if found:
|
|
259
|
+
f, listed, _ = found[0]
|
|
260
|
+
for a in active:
|
|
261
|
+
if a not in listed:
|
|
262
|
+
bad("storylines", lab.rel(f), f"\"Current storylines\" has no row for {a}, which `[storylines]` lists as active")
|
|
263
|
+
for x in sorted(set(listed)):
|
|
264
|
+
if x not in active:
|
|
265
|
+
bad("storylines", lab.rel(f), f"\"Current storylines\" lists {x}, which is not an active storyline: "
|
|
266
|
+
"add it to `active`, or move its row under another heading (`folio map move`)")
|
|
267
|
+
elif listed.count(x) > 1:
|
|
268
|
+
bad("storylines", lab.rel(f), f"\"Current storylines\" lists {x} more than once")
|
|
183
269
|
for q, step, at in stale(lab):
|
|
184
270
|
notes.append(f"storylines: {q} was last committed before the result of {step} ({at}): bring the storyline's argument up to date with it")
|
|
185
271
|
|
|
@@ -317,15 +317,22 @@ def lock(lab, ident):
|
|
|
317
317
|
return lab.rel(path)
|
|
318
318
|
|
|
319
319
|
|
|
320
|
-
def review(lab, ident, stage, verdict, note, by=None):
|
|
321
|
-
"""One independent reading of a plan or of an experiment's results, bound to exactly what it read.
|
|
320
|
+
def review(lab, ident, stage, verdict, note, by=None, supersedes=None):
|
|
321
|
+
"""One independent reading of a plan or of an experiment's results, bound to exactly what it read. With
|
|
322
|
+
`supersedes`, a passing results review of rows that were changed after an earlier results review passed them: it
|
|
323
|
+
names that review by its `of`, and the note says why the rows changed. The rows that review read are held no more;
|
|
324
|
+
these are, once committed."""
|
|
322
325
|
x = lab.nodes.get(ident)
|
|
323
326
|
if not x or x["type"] != "experiment":
|
|
324
327
|
stop(f"no experiment {ident}")
|
|
325
328
|
if stage not in ("plan", "results") or verdict not in ("pass", "fail"):
|
|
326
329
|
stop("lab review <experiment> plan|results pass|fail \"<note>\"")
|
|
330
|
+
if supersedes is not None and (stage != "results" or verdict != "pass"):
|
|
331
|
+
stop("only a results review that passes supersedes another")
|
|
327
332
|
if not R.flat(note):
|
|
328
333
|
stop("a review says what it read and what it found")
|
|
334
|
+
if R.SUPERSEDING.search(R.flat(note).rstrip()):
|
|
335
|
+
stop("a note does not end by superseding a review: name the earlier review with --supersedes <of>, and the command writes that sentence")
|
|
329
336
|
if stage == "plan" and x["lock"]:
|
|
330
337
|
stop(f"{ident} is locked: a plan is reviewed before its lock")
|
|
331
338
|
if stage == "results":
|
|
@@ -333,6 +340,16 @@ def review(lab, ident, stage, verdict, note, by=None):
|
|
|
333
340
|
stop(f"{ident} has no finished run with results to review")
|
|
334
341
|
if lab.reviewed(x, "results")[0] == "fail":
|
|
335
342
|
stop(f"{ident} already failed its results review, and that is final: replace the experiment")
|
|
343
|
+
if supersedes is not None:
|
|
344
|
+
if not re.fullmatch(r"[0-9a-f]{8,16}", supersedes or ""):
|
|
345
|
+
stop("--supersedes names the earlier review by its `of`, eight to sixteen hex digits")
|
|
346
|
+
earlier = {r["of"] for r in x["reviews"] if r.get("stage") == "results" and r.get("verdict") == "pass" and (r.get("of") or "").startswith(supersedes)}
|
|
347
|
+
if len(earlier) != 1:
|
|
348
|
+
stop(f"{ident} has {'no' if not earlier else 'more than one'} results review that passed whose `of` begins {supersedes}")
|
|
349
|
+
earlier = earlier.pop()
|
|
350
|
+
if earlier in (lab.content(x, stage), lab.content(x, stage, 1)):
|
|
351
|
+
stop(f"the review {earlier} read the rows as they are now: there is nothing to supersede, so review them without --supersedes")
|
|
352
|
+
note = f"{R.flat(note).rstrip()} {R.SUPERSEDES.format(earlier)}"
|
|
336
353
|
path = os.path.join(lab.root, x["dir"], "reviews.tsv")
|
|
337
354
|
if not os.path.exists(path):
|
|
338
355
|
open(path, "w").write("date\tstage\tverdict\tby\tof\tnote\n")
|
|
@@ -406,3 +406,64 @@ def test_a_page_of_another_library_is_looked_for_where_that_library_is(tmp_path)
|
|
|
406
406
|
# a library the charter does not name is a problem wherever the check runs
|
|
407
407
|
front(f"{qdir}/question.md", see="[elsewhere:/content/readings/the-law.html]")
|
|
408
408
|
assert "which is not a page of a library the charter names" in lab(root, "check", ok=False)
|
|
409
|
+
|
|
410
|
+
|
|
411
|
+
def test_a_later_review_supersedes_an_earlier_one_only_by_naming_it(tmp_path):
|
|
412
|
+
root = under(tmp_path, "lab")
|
|
413
|
+
ident, d = finished(root) # its rows reviewed, passed and committed
|
|
414
|
+
rows, reviews, held = f"{d}/results.tsv", f"{d}/reviews.tsv", "a row that a review had passed in"
|
|
415
|
+
was = open(rows).read()
|
|
416
|
+
first = [l.split("\t") for l in open(reviews).read().splitlines() if "\tresults\tpass\t" in l][-1][4]
|
|
417
|
+
|
|
418
|
+
# a reviewed row read again another way, to the same value: held, and a second review alone does not change that
|
|
419
|
+
open(rows, "w").write(was.replace("cat $RUN/ratio.txt", "python3 -c \"print(open('$RUN/ratio.txt').read().strip())\""))
|
|
420
|
+
assert open(rows).read() != was
|
|
421
|
+
assert held in lab(root, "check", "--no-rederive", ok=False)
|
|
422
|
+
lab(root, "review", ident, "results", "pass", "Read the new command; it prints the same value.")
|
|
423
|
+
commit(root, "the row read another way, reviewed again")
|
|
424
|
+
assert held in lab(root, "check", "--no-rederive", ok=False)
|
|
425
|
+
|
|
426
|
+
# what --supersedes refuses: a plan review, a fail, a review that is not there, one that read the rows as they are now
|
|
427
|
+
second = [l.split("\t") for l in open(reviews).read().splitlines() if "\tresults\tpass\t" in l][-1][4]
|
|
428
|
+
assert "only a results review that passes" in lab(root, "review", ident, "plan", "pass", "x", "--supersedes", first, ok=False)
|
|
429
|
+
assert "only a results review that passes" in lab(root, "review", ident, "results", "fail", "x", "--supersedes", first, ok=False)
|
|
430
|
+
assert "eight to sixteen hex" in lab(root, "review", ident, "results", "pass", "x", "--supersedes", "zz", ok=False)
|
|
431
|
+
assert "no results review that passed" in lab(root, "review", ident, "results", "pass", "x", "--supersedes", "0123abcd", ok=False)
|
|
432
|
+
assert "nothing to supersede" in lab(root, "review", ident, "results", "pass", "x", "--supersedes", second, ok=False)
|
|
433
|
+
assert "eight to sixteen hex" in lab(root, "review", ident, "results", "pass", "x", "--supersedes", "", ok=False)
|
|
434
|
+
assert "name the earlier review with --supersedes" in lab(root, "review", ident, "results", "pass", f"x. Supersedes the results review of {first}.", ok=False)
|
|
435
|
+
|
|
436
|
+
# named, with why: the rows the first review read are held no more, and these are
|
|
437
|
+
out = lab(root, "review", ident, "results", "pass", "The row now reads the value through $RUN, as the gate asks; the value is the same.", "--supersedes", first[:8])
|
|
438
|
+
assert "recorded in" in out
|
|
439
|
+
assert open(reviews).read().rstrip().endswith(f"Supersedes the results review of {first}.")
|
|
440
|
+
commit(root, "the first review superseded")
|
|
441
|
+
assert "the record is sound" in lab(root, "check", "--no-rederive", "--strict")
|
|
442
|
+
open(rows, "w").write(was)
|
|
443
|
+
assert held in lab(root, "check", "--no-rederive", ok=False) # the superseding review's rows are held in their turn
|
|
444
|
+
|
|
445
|
+
|
|
446
|
+
def test_a_review_that_names_no_earlier_pass_supersedes_nothing(tmp_path):
|
|
447
|
+
root = under(tmp_path, "lab")
|
|
448
|
+
ident, d = finished(root)
|
|
449
|
+
reviews = f"{d}/reviews.tsv"
|
|
450
|
+
line = [l for l in open(reviews).read().splitlines() if "\tresults\tpass\t" in l][-1]
|
|
451
|
+
open(reviews, "a").write(line + " Supersedes the results review of 0123456789abcdef.\n")
|
|
452
|
+
assert "which is no earlier results review of other rows that passed" in lab(root, "check", "--no-rederive", ok=False)
|
|
453
|
+
|
|
454
|
+
|
|
455
|
+
def test_a_superseding_review_frees_nothing_until_its_own_rows_are_committed_with_it(tmp_path):
|
|
456
|
+
root = under(tmp_path, "lab")
|
|
457
|
+
ident, d = finished(root)
|
|
458
|
+
rows, reviews, held = f"{d}/results.tsv", f"{d}/reviews.tsv", "a row that a review had passed in"
|
|
459
|
+
was = open(rows).read()
|
|
460
|
+
first = [l.split("\t") for l in open(reviews).read().splitlines() if "\tresults\tpass\t" in l][-1][4]
|
|
461
|
+
other = was.replace("cat $RUN/ratio.txt", "cat \"$RUN/ratio.txt\"")
|
|
462
|
+
open(rows, "w").write(other)
|
|
463
|
+
lab(root, "review", ident, "results", "pass", "The command quotes $RUN now; same value.", "--supersedes", first)
|
|
464
|
+
git(root, "add", reviews)
|
|
465
|
+
git(root, "commit", "-qm", "the review, without the rows it read")
|
|
466
|
+
open(rows, "w").write(other.replace("cat \"$RUN/ratio.txt\"", "cat $RUN/ratio.txt # a third way"))
|
|
467
|
+
lab(root, "review", ident, "results", "pass", "Read the rows again.")
|
|
468
|
+
commit(root, "a third way, reviewed without naming anything")
|
|
469
|
+
assert held in lab(root, "check", "--no-rederive", ok=False)
|
|
@@ -29,9 +29,19 @@ def page(root, path, title="Storyline A: The square-root law", included=(), excl
|
|
|
29
29
|
open(f"{d}/index.html", "w").write(PAGE.format(title=title, included=links(*included), excluded=links(*excluded), open=links(*open_)))
|
|
30
30
|
|
|
31
31
|
|
|
32
|
-
def storylines(root, overview="entries/where-the-results-stand", active=("entries/storyline-a",)):
|
|
32
|
+
def storylines(root, overview="entries/where-the-results-stand", active=("entries/storyline-a",), listed=None):
|
|
33
33
|
text = open(f"{root}/lab.toml").read().split("[storylines]")[0]
|
|
34
34
|
open(f"{root}/lab.toml", "w").write(text + f'[storylines]\noverview = "{overview}"\nactive = [{", ".join(chr(34) + a + chr(34) for a in active)}]\n')
|
|
35
|
+
home_map(root, active if listed is None else listed)
|
|
36
|
+
|
|
37
|
+
|
|
38
|
+
def home_map(root, listed, name="library", home=("library",), extra=""):
|
|
39
|
+
os.makedirs(f"{root}/docs/content/maps", exist_ok=True)
|
|
40
|
+
open(f"{root}/docs/folio.yaml", "w").write("name: lab\nhome:\n maps: [" + ", ".join(home) + "]\n")
|
|
41
|
+
rows = "".join(f'<li><a href="/content/{a}/">{a}</a> <span class="why">why</span></li>' for a in listed)
|
|
42
|
+
open(f"{root}/docs/content/maps/{name}.html", "w").write(
|
|
43
|
+
f'<html><body><main><h2 id="current-storylines">Current storylines</h2><ul class="rows">{rows}</ul>{extra}'
|
|
44
|
+
f'<h2 id="what-the-lab-proves">What the lab proves</h2><ul class="rows"><li><a href="/content/entries/where-the-results-stand/">Overview</a></li></ul></main></body></html>')
|
|
35
45
|
|
|
36
46
|
|
|
37
47
|
def two_experiments(root):
|
|
@@ -187,3 +197,35 @@ def test_a_table_inside_a_scope_cell_is_read_as_part_of_it(tmp_path):
|
|
|
187
197
|
open(f"{d}/index.html", "w").write(f'<html><body><table><tr><td data-scope="included"><table><tr><td>{links(first, void)}</td></tr></table></td>'
|
|
188
198
|
f'<td data-scope="excluded"></td><td data-scope="open">{links(later)}</td></tr></table></body></html>')
|
|
189
199
|
assert f"lists {void} under included, which is void" in lab(root, "check", "--no-rederive", ok=False)
|
|
200
|
+
|
|
201
|
+
|
|
202
|
+
def test_the_home_map_lists_the_active_storylines_under_current_storylines(tmp_path):
|
|
203
|
+
root = str(tmp_path)
|
|
204
|
+
first, void, later = two_experiments(root)
|
|
205
|
+
page(root, "entries/storyline-a", included=(first,), excluded=(void,), open_=(later,))
|
|
206
|
+
page(root, "entries/storyline-b", included=(first,), excluded=(void,), open_=(later,))
|
|
207
|
+
storylines(root, active=("entries/storyline-a", "entries/storyline-b"), listed=("entries/storyline-a", "entries/old-storyline"))
|
|
208
|
+
out = lab(root, "check", "--no-rederive", ok=False)
|
|
209
|
+
assert '"Current storylines" has no row for entries/storyline-b' in out
|
|
210
|
+
assert '"Current storylines" lists entries/old-storyline, which is not an active storyline' in out
|
|
211
|
+
assert "where-the-results-stand, which" not in out # a row under another heading is not read
|
|
212
|
+
# only a row's first link, in a `rows` list, before the next h2 or h3, is a row; other forms of a page's link count
|
|
213
|
+
extra = ('<p>See <a href="/content/entries/prose/">a page</a>.</p><ul><li><a href="/content/entries/pointer/">x</a></li></ul>'
|
|
214
|
+
'<ul class="rows"><li><a href="/content/entries/storyline-b/index.html#top">B</a> <span class="why">vs '
|
|
215
|
+
'<a href="/content/entries/why/">why</a></span></li></ul><h3 id="later">Later</h3><ul class="rows">'
|
|
216
|
+
'<li><a href="/content/entries/under-h3/">c</a></li></ul>')
|
|
217
|
+
home_map(root, ("entries/storyline-a",), extra=extra)
|
|
218
|
+
assert "storylines:" not in lab(root, "check", "--no-rederive")
|
|
219
|
+
home_map(root, ("entries/storyline-a", "entries/storyline-a", "entries/storyline-b"))
|
|
220
|
+
assert '"Current storylines" lists entries/storyline-a more than once' in lab(root, "check", "--no-rederive", ok=False)
|
|
221
|
+
home_map(root, ("entries/storyline-a", "entries/storyline-b"))
|
|
222
|
+
home_map(root, ("entries/storyline-a",), name="another", home=("library", "another"))
|
|
223
|
+
assert 'has a second "Current storylines" section' in lab(root, "check", "--no-rederive", ok=False)
|
|
224
|
+
home_map(root, ("entries/storyline-a",), name="another", home=("library",))
|
|
225
|
+
assert "is not a home map" in lab(root, "check", "--no-rederive", ok=False)
|
|
226
|
+
os.remove(f"{root}/docs/content/maps/another.html")
|
|
227
|
+
os.remove(f"{root}/docs/content/maps/library.html")
|
|
228
|
+
assert 'no home map of the library has a section `<h2 id="current-storylines">' in lab(root, "check", "--no-rederive", ok=False)
|
|
229
|
+
storylines(root, active=())
|
|
230
|
+
os.remove(f"{root}/docs/content/maps/library.html")
|
|
231
|
+
assert "storylines:" not in lab(root, "check", "--no-rederive") # no active storyline needs no section
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|