lab-kit-cli 1.13.0__tar.gz → 1.14.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.
Files changed (46) hide show
  1. {lab_kit_cli-1.13.0 → lab_kit_cli-1.14.0}/CHANGELOG.md +12 -0
  2. {lab_kit_cli-1.13.0 → lab_kit_cli-1.14.0}/PKG-INFO +1 -1
  3. {lab_kit_cli-1.13.0 → lab_kit_cli-1.14.0}/docs/model.md +11 -2
  4. {lab_kit_cli-1.13.0 → lab_kit_cli-1.14.0}/pyproject.toml +1 -1
  5. {lab_kit_cli-1.13.0 → lab_kit_cli-1.14.0}/skills/lab-set-up/SKILL.md +9 -6
  6. {lab_kit_cli-1.13.0 → lab_kit_cli-1.14.0}/skills/lab-work/SKILL.md +7 -1
  7. {lab_kit_cli-1.13.0 → lab_kit_cli-1.14.0}/src/lab_kit/__init__.py +1 -1
  8. {lab_kit_cli-1.13.0 → lab_kit_cli-1.14.0}/src/lab_kit/storylines.py +87 -1
  9. {lab_kit_cli-1.13.0 → lab_kit_cli-1.14.0}/tests/test_storylines.py +43 -1
  10. {lab_kit_cli-1.13.0 → lab_kit_cli-1.14.0}/.github/workflows/ci.yml +0 -0
  11. {lab_kit_cli-1.13.0 → lab_kit_cli-1.14.0}/.github/workflows/policy.yml +0 -0
  12. {lab_kit_cli-1.13.0 → lab_kit_cli-1.14.0}/.github/workflows/release.yml +0 -0
  13. {lab_kit_cli-1.13.0 → lab_kit_cli-1.14.0}/.gitignore +0 -0
  14. {lab_kit_cli-1.13.0 → lab_kit_cli-1.14.0}/AGENTS.md +0 -0
  15. {lab_kit_cli-1.13.0 → lab_kit_cli-1.14.0}/CLAUDE.md +0 -0
  16. {lab_kit_cli-1.13.0 → lab_kit_cli-1.14.0}/CONTRIBUTING.md +0 -0
  17. {lab_kit_cli-1.13.0 → lab_kit_cli-1.14.0}/LICENSE +0 -0
  18. {lab_kit_cli-1.13.0 → lab_kit_cli-1.14.0}/README.md +0 -0
  19. {lab_kit_cli-1.13.0 → lab_kit_cli-1.14.0}/agents/reviewer.md +0 -0
  20. {lab_kit_cli-1.13.0 → lab_kit_cli-1.14.0}/method/METHOD.md +0 -0
  21. {lab_kit_cli-1.13.0 → lab_kit_cli-1.14.0}/skills/lab-mission/SKILL.md +0 -0
  22. {lab_kit_cli-1.13.0 → lab_kit_cli-1.14.0}/skills/lab-review/SKILL.md +0 -0
  23. {lab_kit_cli-1.13.0 → lab_kit_cli-1.14.0}/skills/lab-talk/SKILL.md +0 -0
  24. {lab_kit_cli-1.13.0 → lab_kit_cli-1.14.0}/src/lab_kit/checks.py +0 -0
  25. {lab_kit_cli-1.13.0 → lab_kit_cli-1.14.0}/src/lab_kit/cli.py +0 -0
  26. {lab_kit_cli-1.13.0 → lab_kit_cli-1.14.0}/src/lab_kit/history.py +0 -0
  27. {lab_kit_cli-1.13.0 → lab_kit_cli-1.14.0}/src/lab_kit/record.py +0 -0
  28. {lab_kit_cli-1.13.0 → lab_kit_cli-1.14.0}/src/lab_kit/runs.py +0 -0
  29. {lab_kit_cli-1.13.0 → lab_kit_cli-1.14.0}/src/lab_kit/site.py +0 -0
  30. {lab_kit_cli-1.13.0 → lab_kit_cli-1.14.0}/src/lab_kit/supervise.py +0 -0
  31. {lab_kit_cli-1.13.0 → lab_kit_cli-1.14.0}/src/lab_kit/views.py +0 -0
  32. {lab_kit_cli-1.13.0 → lab_kit_cli-1.14.0}/src/lab_kit/write.py +0 -0
  33. {lab_kit_cli-1.13.0 → lab_kit_cli-1.14.0}/tests/test_drafts.py +0 -0
  34. {lab_kit_cli-1.13.0 → lab_kit_cli-1.14.0}/tests/test_flow.py +0 -0
  35. {lab_kit_cli-1.13.0 → lab_kit_cli-1.14.0}/tests/test_held.py +0 -0
  36. {lab_kit_cli-1.13.0 → lab_kit_cli-1.14.0}/tests/test_integrity.py +0 -0
  37. {lab_kit_cli-1.13.0 → lab_kit_cli-1.14.0}/tests/test_mission.py +0 -0
  38. {lab_kit_cli-1.13.0 → lab_kit_cli-1.14.0}/tests/test_needs.py +0 -0
  39. {lab_kit_cli-1.13.0 → lab_kit_cli-1.14.0}/tests/test_order.py +0 -0
  40. {lab_kit_cli-1.13.0 → lab_kit_cli-1.14.0}/tests/test_parked.py +0 -0
  41. {lab_kit_cli-1.13.0 → lab_kit_cli-1.14.0}/tests/test_refusals.py +0 -0
  42. {lab_kit_cli-1.13.0 → lab_kit_cli-1.14.0}/tests/test_site.py +0 -0
  43. {lab_kit_cli-1.13.0 → lab_kit_cli-1.14.0}/tests/test_states.py +0 -0
  44. {lab_kit_cli-1.13.0 → lab_kit_cli-1.14.0}/tests/test_vocabulary.py +0 -0
  45. {lab_kit_cli-1.13.0 → lab_kit_cli-1.14.0}/tests/test_wording.py +0 -0
  46. {lab_kit_cli-1.13.0 → lab_kit_cli-1.14.0}/tools/import_run.py +0 -0
@@ -1,5 +1,17 @@
1
1
  # Changelog
2
2
 
3
+ ## 1.14.0
4
+
5
+ - **A home map has Current storylines.** When `lab.toml` names active storylines, one of the library's home
6
+ maps has a section `<h2 id="current-storylines">Current storylines</h2>` whose rows are the active storyline
7
+ pages and nothing else, so every lab shows its storylines in the same place. `lab check` refuses a library
8
+ with no such section or with two, the section on a map that is not a home map, an active storyline with no
9
+ row there, a row listed twice, and a row there that is not an active storyline. Rows are read as folio reads
10
+ them: the first link of an item in a `rows` list, up to the next `h2` or `h3`. lab-set-up writes the section,
11
+ and lab-work keeps it when a storyline is added or retired.
12
+ - Upgrading: run `lab init`. A lab that names its storylines also moves their rows under Current storylines
13
+ (`folio map move <id> --to <map>#current-storylines`) before `lab check` passes.
14
+
3
15
  ## 1.13.0
4
16
 
5
17
  - **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.13.0
3
+ Version: 1.14.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
@@ -402,7 +402,8 @@ moves from included to excluded. Adding, merging or retiring a storyline is dire
402
402
  you. A question's or an experiment's So far gives the current finding, not the story of the bugs on the way:
403
403
  the replaced experiments and the reasons they were replaced keep that story.
404
404
 
405
- A lab opts in by naming the pages in `lab.toml` (section 9). Then `lab check` holds each scope table:
405
+ A lab opts in by naming the pages in `lab.toml` (section 9), and its library's home map lists them under one
406
+ section, Current storylines. Then `lab check` holds that section and each scope table:
406
407
  included lists only finished work that is not void, replaced or dropped, open only work still to do, nothing
407
408
  parked or dropped is in either, and a goal, a question or a step sits in one row; a storyline page committed
408
409
  before a result about something it lists under included or open is noted. `lab now` lists each storyline's
@@ -962,7 +963,15 @@ a question or a step has one row on a page: where another row needs to mention i
962
963
  without its link. A question written in one row and a step under it written in another is allowed: the open
963
964
  question with its one finished step included is the usual case. A decision may be cited in any row. In
964
965
  `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. A lab without `[storylines]` has none of this.
966
+ every step under it.
967
+
968
+ While a storyline is active, one of the library's home maps (`home.maps` in `folio.yaml`) has a section headed
969
+ `<h2 id="current-storylines">Current storylines</h2>`, and its rows are the active storyline pages and nothing
970
+ else. A row is what folio counts as one: the first link, to `/content/<path>/`, of an item of a list whose classes
971
+ 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
972
+ is the one place those pages have on a map; the overview and a retired storyline have theirs under other
973
+ headings. The library has one such section, and no map that is not a home map has one. A lab without
974
+ `[storylines]` has none of this.
966
975
 
967
976
  **Worked-out states.** A goal is open until `reached: true` makes it done or `dropped:` drops it. A
968
977
  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.13.0"
8
+ version = "1.14.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" }]
@@ -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 `entries/where-the-results-stand`) with folio's
49
- write skill: the words on one running example, the workflow, the related work, and empty sections for the
50
- findings and the criticisms. For each storyline, write `entries/storyline-<slug>`: its thesis, then the scope table
51
- (target audience and venues, core thesis, experiments included, excluded or superseded, open), with the
52
- last three cells marked `data-scope="included"`, `"excluded"` and `"open"`. Name them in `lab.toml` under
53
- `[storylines]` (`overview`, `active`). No card names a storyline (method rule 8).
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 and `[storylines]`. A retired storyline's page leaves `active` and stays in the library.
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.13.0"
2
+ __version__ = "1.14.0"
@@ -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
 
@@ -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