throughline-transform 0.1.0__tar.gz → 0.3.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 (30) hide show
  1. {throughline_transform-0.1.0/src/throughline_transform.egg-info → throughline_transform-0.3.0}/PKG-INFO +21 -3
  2. {throughline_transform-0.1.0 → throughline_transform-0.3.0}/README.md +20 -2
  3. {throughline_transform-0.1.0 → throughline_transform-0.3.0}/pyproject.toml +1 -1
  4. {throughline_transform-0.1.0 → throughline_transform-0.3.0}/src/throughline_transform/blocks.py +27 -0
  5. {throughline_transform-0.1.0 → throughline_transform-0.3.0}/src/throughline_transform/cli.py +30 -10
  6. {throughline_transform-0.1.0 → throughline_transform-0.3.0}/src/throughline_transform/notes.py +54 -3
  7. throughline_transform-0.3.0/src/throughline_transform/progress.py +47 -0
  8. {throughline_transform-0.1.0 → throughline_transform-0.3.0}/src/throughline_transform/project.py +59 -12
  9. {throughline_transform-0.1.0 → throughline_transform-0.3.0}/src/throughline_transform/provenance.py +26 -0
  10. {throughline_transform-0.1.0 → throughline_transform-0.3.0/src/throughline_transform.egg-info}/PKG-INFO +21 -3
  11. {throughline_transform-0.1.0 → throughline_transform-0.3.0}/src/throughline_transform.egg-info/SOURCES.txt +3 -1
  12. {throughline_transform-0.1.0 → throughline_transform-0.3.0}/tests/test_outputs.py +14 -0
  13. throughline_transform-0.3.0/tests/test_surface.py +183 -0
  14. {throughline_transform-0.1.0 → throughline_transform-0.3.0}/LICENSE +0 -0
  15. {throughline_transform-0.1.0 → throughline_transform-0.3.0}/MANIFEST.in +0 -0
  16. {throughline_transform-0.1.0 → throughline_transform-0.3.0}/NOTICE +0 -0
  17. {throughline_transform-0.1.0 → throughline_transform-0.3.0}/setup.cfg +0 -0
  18. {throughline_transform-0.1.0 → throughline_transform-0.3.0}/src/throughline_transform/__init__.py +0 -0
  19. {throughline_transform-0.1.0 → throughline_transform-0.3.0}/src/throughline_transform/html.py +0 -0
  20. {throughline_transform-0.1.0 → throughline_transform-0.3.0}/src/throughline_transform/markdown.py +0 -0
  21. {throughline_transform-0.1.0 → throughline_transform-0.3.0}/src/throughline_transform/model.py +0 -0
  22. {throughline_transform-0.1.0 → throughline_transform-0.3.0}/src/throughline_transform/office.py +0 -0
  23. {throughline_transform-0.1.0 → throughline_transform-0.3.0}/src/throughline_transform/package.py +0 -0
  24. {throughline_transform-0.1.0 → throughline_transform-0.3.0}/src/throughline_transform/shape.py +0 -0
  25. {throughline_transform-0.1.0 → throughline_transform-0.3.0}/src/throughline_transform/tables.py +0 -0
  26. {throughline_transform-0.1.0 → throughline_transform-0.3.0}/src/throughline_transform.egg-info/dependency_links.txt +0 -0
  27. {throughline_transform-0.1.0 → throughline_transform-0.3.0}/src/throughline_transform.egg-info/entry_points.txt +0 -0
  28. {throughline_transform-0.1.0 → throughline_transform-0.3.0}/src/throughline_transform.egg-info/requires.txt +0 -0
  29. {throughline_transform-0.1.0 → throughline_transform-0.3.0}/src/throughline_transform.egg-info/top_level.txt +0 -0
  30. {throughline_transform-0.1.0 → throughline_transform-0.3.0}/tests/conftest.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: throughline-transform
3
- Version: 0.1.0
3
+ Version: 0.3.0
4
4
  Summary: Turn a throughline requirements graph on disk, committed or not, into the forms its readers open: Markdown, a folder of Obsidian notes, CSV, an Excel workbook, a Word document, or a print-ready HTML document. Ships the tl-transform CLI.
5
5
  Author-email: Henry J Grech-Cini <henry.grechcini@gmail.com>
6
6
  License-Expression: Apache-2.0
@@ -82,15 +82,33 @@ second, and is run as a command — its command line is the surface it publishes
82
82
  | Format | What you get |
83
83
  |---|---|
84
84
  | `md` | The tool's own document: a summary, a catalogue of every item in full, the mirrored clauses of adopted sources. `--body table` or `both` for a one-line-per-item table, `--matrix` for one traceability matrix per grounding link type, `--markers` to keep the region markers so `tl docs` can refill the file later. |
85
- | `notes` | One Markdown note per item in a folder per register, YAML front matter as properties (type, status, attributes, the title as an alias, a tag each for type and status), every identifier a `[[wikilink]]`. Cited clauses under `sources/<namespace>/`, the colon in their name replaced by a space. Open the folder as an Obsidian vault: the graph view is the intent graph, and a note's backlinks are what rests on it. |
85
+ | `notes` | One Markdown note per item in a folder per register: YAML front matter as properties (type, status, attributes, the title as an alias, a tag each for type and status), a heading of the identifier and title, the item's words, rationale and links, then what links to it — `Implements this`, `Derives from this` — every identifier a `[[wikilink]]`. Cited clauses under `sources/<namespace>/`, the colon in their name replaced by a space. Open the folder as an Obsidian vault: the graph view is the intent graph, and a note's backlinks are what rests on it. |
86
86
  | `csv` | A zip of one file of items (or one per register with `--split per-register`), `links.csv` with one row per link naming the sheet at each end, one file per cited source, and the provenance. |
87
87
  | `xlsx` | The same as sheets, read-only by recommendation with the structure locked and no password. Sorting and filtering stay allowed; a spreadsheet nobody can sort is one nobody can review. |
88
88
  | `docx` | A title page with the provenance, a contents field Word fills in, a section per register, a heading per item with its type and status beneath, its words as a quotation, its rationale, its attributes in small print, and one appendix per cited source. |
89
89
  | `html` | The same document as one self-contained page with print typography, A4 page rules and a contents list of links. Print it to PDF; the browser numbers the pages. |
90
+ | `blocks` | The document's structure as JSON — the same list of headings, quotations, paragraphs, attribute lines, tables and appendices the Word and HTML outputs are built from — for a front end that lays out its own pages. The editor's PDF is laid out from it. |
90
91
 
91
92
  Every output carries the repository, ref, commit, working-tree state and tool
92
93
  version it was taken from, because an output outlives the tree that made it and
93
- the first question anyone asks of one is what it was true of.
94
+ the first question anyone asks of one is what it was true of. A caller that
95
+ knows them without git — the editor holds them from its clone — states them with
96
+ `--repository`, `--ref`, `--commit` and `--tree clean|dirty|untracked`, and git
97
+ is then not consulted.
98
+
99
+ A quick run is silent. When a step — reading the graph, asking the tool to
100
+ write the document, writing the file — has run for a second, one line on
101
+ stderr says which, because a composed graph fetching its sources for the first
102
+ time otherwise reads as a hang.
103
+
104
+ ## One implementation, two surfaces
105
+
106
+ The [throughline editor](https://github.com/rhodium-org/throughline-editor)
107
+ runs this package as a wheel under Pyodide beside `tl` and `tl-compose`, so an
108
+ export from a browser tab and an export from a terminal are the same bytes for
109
+ the same graph at the same commit. Pyodide has no processes, so there the tool
110
+ calls the console entry point `tl` or `tl-compose` declares in its package
111
+ metadata — the same function the command runs — instead of spawning it.
94
112
 
95
113
  ## Self-hosting
96
114
 
@@ -53,15 +53,33 @@ second, and is run as a command — its command line is the surface it publishes
53
53
  | Format | What you get |
54
54
  |---|---|
55
55
  | `md` | The tool's own document: a summary, a catalogue of every item in full, the mirrored clauses of adopted sources. `--body table` or `both` for a one-line-per-item table, `--matrix` for one traceability matrix per grounding link type, `--markers` to keep the region markers so `tl docs` can refill the file later. |
56
- | `notes` | One Markdown note per item in a folder per register, YAML front matter as properties (type, status, attributes, the title as an alias, a tag each for type and status), every identifier a `[[wikilink]]`. Cited clauses under `sources/<namespace>/`, the colon in their name replaced by a space. Open the folder as an Obsidian vault: the graph view is the intent graph, and a note's backlinks are what rests on it. |
56
+ | `notes` | One Markdown note per item in a folder per register: YAML front matter as properties (type, status, attributes, the title as an alias, a tag each for type and status), a heading of the identifier and title, the item's words, rationale and links, then what links to it — `Implements this`, `Derives from this` — every identifier a `[[wikilink]]`. Cited clauses under `sources/<namespace>/`, the colon in their name replaced by a space. Open the folder as an Obsidian vault: the graph view is the intent graph, and a note's backlinks are what rests on it. |
57
57
  | `csv` | A zip of one file of items (or one per register with `--split per-register`), `links.csv` with one row per link naming the sheet at each end, one file per cited source, and the provenance. |
58
58
  | `xlsx` | The same as sheets, read-only by recommendation with the structure locked and no password. Sorting and filtering stay allowed; a spreadsheet nobody can sort is one nobody can review. |
59
59
  | `docx` | A title page with the provenance, a contents field Word fills in, a section per register, a heading per item with its type and status beneath, its words as a quotation, its rationale, its attributes in small print, and one appendix per cited source. |
60
60
  | `html` | The same document as one self-contained page with print typography, A4 page rules and a contents list of links. Print it to PDF; the browser numbers the pages. |
61
+ | `blocks` | The document's structure as JSON — the same list of headings, quotations, paragraphs, attribute lines, tables and appendices the Word and HTML outputs are built from — for a front end that lays out its own pages. The editor's PDF is laid out from it. |
61
62
 
62
63
  Every output carries the repository, ref, commit, working-tree state and tool
63
64
  version it was taken from, because an output outlives the tree that made it and
64
- the first question anyone asks of one is what it was true of.
65
+ the first question anyone asks of one is what it was true of. A caller that
66
+ knows them without git — the editor holds them from its clone — states them with
67
+ `--repository`, `--ref`, `--commit` and `--tree clean|dirty|untracked`, and git
68
+ is then not consulted.
69
+
70
+ A quick run is silent. When a step — reading the graph, asking the tool to
71
+ write the document, writing the file — has run for a second, one line on
72
+ stderr says which, because a composed graph fetching its sources for the first
73
+ time otherwise reads as a hang.
74
+
75
+ ## One implementation, two surfaces
76
+
77
+ The [throughline editor](https://github.com/rhodium-org/throughline-editor)
78
+ runs this package as a wheel under Pyodide beside `tl` and `tl-compose`, so an
79
+ export from a browser tab and an export from a terminal are the same bytes for
80
+ the same graph at the same commit. Pyodide has no processes, so there the tool
81
+ calls the console entry point `tl` or `tl-compose` declares in its package
82
+ metadata — the same function the command runs — instead of spawning it.
65
83
 
66
84
  ## Self-hosting
67
85
 
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
4
4
 
5
5
  [project]
6
6
  name = "throughline-transform"
7
- version = "0.1.0"
7
+ version = "0.3.0"
8
8
  description = "Turn a throughline requirements graph on disk, committed or not, into the forms its readers open: Markdown, a folder of Obsidian notes, CSV, an Excel workbook, a Word document, or a print-ready HTML document. Ships the tl-transform CLI."
9
9
  readme = "README.md"
10
10
  requires-python = ">=3.11"
@@ -14,6 +14,7 @@ and the attribute line is marked as the small print it is.
14
14
 
15
15
  from __future__ import annotations
16
16
 
17
+ import json
17
18
  import re
18
19
  from dataclasses import dataclass, field
19
20
 
@@ -154,3 +155,29 @@ def as_blocks(
154
155
  continue
155
156
  blocks.append(Block(text=strip(re.sub(r"^[-*]\s+", "", text)), front=front))
156
157
  return blocks
158
+
159
+
160
+ def as_dict(block: Block) -> dict:
161
+ """A block as data, absent fields omitted (SR-0012)."""
162
+ out: dict = {"text": block.text}
163
+ if block.heading:
164
+ out["heading"] = block.heading
165
+ for flag in ("quote", "small", "front", "group"):
166
+ if getattr(block, flag):
167
+ out[flag] = True
168
+ if block.subtitle:
169
+ out["subtitle"] = block.subtitle
170
+ if block.item:
171
+ out["item"] = dict(block.item)
172
+ if block.table:
173
+ out["table"] = {"header": list(block.table["header"]), "rows": [list(r) for r in block.table["rows"]]}
174
+ return out
175
+
176
+
177
+ def to_json(blocks: list[Block], provenance_lines: list[str], provenance: dict) -> str:
178
+ """The document's structure as one JSON document: the provenance, then the blocks in order."""
179
+ return json.dumps(
180
+ {"provenance": provenance, "provenance_lines": provenance_lines, "blocks": [as_dict(b) for b in blocks]},
181
+ ensure_ascii=False,
182
+ indent=1,
183
+ )
@@ -8,6 +8,10 @@
8
8
  tl-transform xlsx [-C DIR] [-o FILE] [--split …]
9
9
  tl-transform docx [-C DIR] [-o FILE] [--body …] [--matrix] [--no-stats]
10
10
  tl-transform html [-C DIR] [-o FILE] [--body …] [--matrix] [--no-stats]
11
+ tl-transform blocks [-C DIR] [-o FILE] [--body …] [--matrix] [--no-stats]
12
+
13
+ Any format takes --repository, --ref, --commit and --tree to state the
14
+ provenance instead of reading git (SR-0013).
11
15
 
12
16
  Exit codes: 0 written · 1 the tool or the file system refused · 2 usage.
13
17
  """
@@ -16,24 +20,25 @@ from __future__ import annotations
16
20
 
17
21
  import argparse
18
22
  import sys
19
- from dataclasses import replace
23
+ from dataclasses import asdict, replace
20
24
  from pathlib import Path
21
25
 
22
26
  from throughline.version import distribution_version as _v
23
27
 
24
28
  from . import markdown as md
25
- from .blocks import as_blocks
29
+ from .blocks import as_blocks, to_json
26
30
  from .html import to_html
27
31
  from .model import Graph, register_titles, source_titles
28
32
  from .notes import to_notes
29
33
  from .office import to_docx, to_xlsx
30
34
  from .package import Entry, archive, unpack, utf8
35
+ from .progress import slow
31
36
  from .project import TransformError, find_graph, load
32
- from .provenance import Provenance, provenance_of
37
+ from .provenance import TREE_WORDS, Provenance, provenance_of, stated
33
38
  from .tables import Table, cited_sources, file_name, links_of, per_register, to_csv, whole_graph
34
39
 
35
- FORMATS = ("md", "notes", "csv", "xlsx", "docx", "html")
36
- PROSE = ("md", "docx", "html")
40
+ FORMATS = ("md", "notes", "csv", "xlsx", "docx", "html", "blocks")
41
+ PROSE = ("md", "docx", "html", "blocks")
37
42
  FOLDERS = ("notes", "csv")
38
43
 
39
44
 
@@ -58,11 +63,19 @@ def build_parser() -> argparse.ArgumentParser:
58
63
  "--body",
59
64
  choices=("catalog", "table", "both"),
60
65
  default="catalog",
61
- help="md, docx, html: every item in full, a table of items, or both",
66
+ help="md, docx, html, blocks: every item in full, a table of items, or both",
62
67
  )
63
- p.add_argument("--matrix", action="store_true", help="md, docx, html: add a traceability matrix per grounding link")
64
- p.add_argument("--no-stats", dest="stats", action="store_false", help="md, docx, html: leave out the tool's summary")
68
+ p.add_argument("--matrix", action="store_true", help="md, docx, html, blocks: add a traceability matrix per grounding link")
69
+ p.add_argument("--no-stats", dest="stats", action="store_false", help="md, docx, html, blocks: leave out the tool's summary")
65
70
  p.add_argument("--markers", action="store_true", help="md: keep the tool's region markers so `tl docs` can refill the file")
71
+ p.add_argument("--repository", metavar="OWNER/NAME", help="state the repository instead of reading git")
72
+ p.add_argument("--ref", metavar="REF", help="state the ref instead of reading git")
73
+ p.add_argument("--commit", metavar="SHA", help="state the commit instead of reading git")
74
+ p.add_argument(
75
+ "--tree",
76
+ choices=tuple(TREE_WORDS),
77
+ help="state the working tree's state instead of reading git",
78
+ )
66
79
  p.add_argument(
67
80
  "--split",
68
81
  choices=("one", "per-register"),
@@ -92,6 +105,8 @@ def produce(graph: Graph, root: Path, fmt: str, opts: md.Options, provenance: Pr
92
105
  blocks = as_blocks(text, register_titles(graph), source_titles(graph))
93
106
  if fmt == "docx":
94
107
  return to_docx(blocks), f"{stem}.docx"
108
+ if fmt == "blocks":
109
+ return utf8(to_json(blocks, provenance.lines(), asdict(provenance))), f"{stem}-blocks.json"
95
110
  return utf8(to_html(blocks, provenance)), f"{stem}.html"
96
111
 
97
112
  if fmt == "notes":
@@ -140,9 +155,14 @@ def main(argv: list[str] | None = None) -> int:
140
155
  try:
141
156
  root = find_graph(args.directory)
142
157
  graph = load(root)
143
- provenance = provenance_of(root, graph.tool_version)
158
+ provenance = (
159
+ stated(graph.tool_version, args.repository, args.ref, args.commit, args.tree)
160
+ if any((args.repository, args.ref, args.commit, args.tree))
161
+ else provenance_of(root, graph.tool_version)
162
+ )
144
163
  result, default = produce(graph, root, args.format, opts, provenance)
145
- target = write(result, default, args.output, args.folder)
164
+ with slow(f"still writing {args.output or default}…"):
165
+ target = write(result, default, args.output, args.folder)
146
166
  except (TransformError, OSError, ValueError) as exc:
147
167
  print(f"tl-transform: {exc}", file=sys.stderr)
148
168
  return 1
@@ -10,7 +10,10 @@ clause of an adopted source, and an About note carrying the provenance.
10
10
  The prose is the tool's. The catalogue is written once and cut here at the
11
11
  item line, so the words in a note are the words ``tl docs`` publishes. What is
12
12
  added is what the tool has no view on: file boundaries, YAML front matter the
13
- note tool reads as properties, and link syntax.
13
+ note tool reads as properties, link syntax, and the body reshaped for a note —
14
+ the item line as the note's heading, the attribute line left to the front
15
+ matter, and the incoming links written out so a reader sees what rests on the
16
+ item without opening a pane (SR-0009, reversed on first use in Obsidian).
14
17
  """
15
18
 
16
19
  from __future__ import annotations
@@ -22,7 +25,7 @@ from dataclasses import dataclass, field
22
25
  from .model import Graph, Item, prefix_of, split_borrowed
23
26
  from .package import Entry, utf8
24
27
  from .provenance import Provenance
25
- from .shape import IDENTIFIER, ITEM_LINE
28
+ from .shape import ATTRS_LINE, IDENTIFIER, ITEM_LINE
26
29
 
27
30
  _HEADING = re.compile(r"^#{1,3}\s+(.*)$")
28
31
 
@@ -150,6 +153,54 @@ def wikilink(line: str, own: str, names: dict[str, str]) -> str:
150
153
  return IDENTIFIER.sub(link, line)
151
154
 
152
155
 
156
+ def _link(identifier: str, names: dict[str, str]) -> str:
157
+ name = names[identifier]
158
+ return f"[[{identifier}]]" if name == identifier else f"[[{name}|{identifier}]]"
159
+
160
+
161
+ def _label(link_type: str) -> str:
162
+ """The tool's own label for a link type — ``derives_from`` -> ``Derives from``."""
163
+ return link_type.replace("_", " ").capitalize()
164
+
165
+
166
+ def note_body(block: NoteBlock, graph: Graph, names: dict[str, str]) -> list[str]:
167
+ """The tool's block reshaped for a note (SR-0009).
168
+
169
+ The item line becomes a level-one heading with the type and status on the
170
+ line beneath; the words, rationale and outgoing link lines follow as the
171
+ tool wrote them, wikilinked; the attribute line goes, because the front
172
+ matter already carries every attribute; then one line per incoming link
173
+ type names what links to this item, worded as the link type reads with
174
+ the word "this", so a reader of a requirement sees what rests on it.
175
+ """
176
+ head = ITEM_LINE.match(block.lines[0])
177
+ assert head is not None
178
+ identifier, reference, title, type_, status = head.groups()
179
+ # The heading goes through the same link pass as any line: a title that
180
+ # names another item links to it, and a bracket pair in a title is prose.
181
+ lines = [
182
+ wikilink(f"# {identifier}{f' ({reference})' if reference else ''} — {title}", block.id, names),
183
+ f"{type_.replace('_', ' ')} · {status}",
184
+ ]
185
+ for line in block.lines[1:]:
186
+ if ATTRS_LINE.match(line):
187
+ continue
188
+ lines.append(wikilink(line, block.id, names))
189
+ while lines and not lines[-1]:
190
+ lines.pop()
191
+
192
+ by_type: dict[str, list[str]] = {}
193
+ for source, link_type in graph.incoming.get(block.id, []):
194
+ if source in names:
195
+ by_type.setdefault(link_type, []).append(source)
196
+ if by_type:
197
+ lines.append("")
198
+ for link_type in sorted(by_type):
199
+ sources = ", ".join(_link(uid, names) for uid in sorted(by_type[link_type]))
200
+ lines.append(f"*{_label(link_type)} this:* {sources}")
201
+ return lines
202
+
203
+
153
204
  def to_notes(markdown: str, graph: Graph, provenance: Provenance, folder: str = "") -> list[Entry]:
154
205
  """The notes, as the files of the folder. ``folder`` prefixes every path when set."""
155
206
  blocks = blocks_of(markdown)
@@ -166,7 +217,7 @@ def to_notes(markdown: str, graph: Graph, provenance: Provenance, folder: str =
166
217
  raise ValueError(f"the tool wrote {block.id}, which is not in the graph's export")
167
218
  head = ITEM_LINE.match(block.lines[0])
168
219
  reference = head.group(2) if head else None
169
- body = "\n".join(wikilink(line, block.id, names) for line in block.lines)
220
+ body = "\n".join(note_body(block, graph, names))
170
221
  entries.append(
171
222
  (
172
223
  f"{prefix}{_folder_of(block, registers)}/{note_name(block.id)}.md",
@@ -0,0 +1,47 @@
1
+ # Copyright (c) 2026 Henry J Grech-Cini
2
+ # SPDX-License-Identifier: Apache-2.0
3
+ """A word when a step is slow (SR-0015).
4
+
5
+ The command says nothing while a step is quick. When a step has run for a
6
+ second and not finished, one line on stderr names it, so a composed graph
7
+ fetching its sources for the first time does not read as a hang. Never on
8
+ stdout, so a script capturing the output is unaffected; never where there are
9
+ no threads, which is Pyodide, where the caller shows its own progress.
10
+ """
11
+
12
+ from __future__ import annotations
13
+
14
+ import sys
15
+ import threading
16
+ from contextlib import contextmanager
17
+ from typing import Iterator
18
+
19
+ #: How long a step may run in silence.
20
+ SLOW_AFTER = 1.0
21
+
22
+
23
+ def has_threads() -> bool:
24
+ """Whether a timer can run beside the step at all."""
25
+ return sys.platform != "emscripten"
26
+
27
+
28
+ @contextmanager
29
+ def slow(message: str, after: float | None = None) -> Iterator[None]:
30
+ """Say ``message`` on stderr if the enclosed step is still running after ``after`` seconds."""
31
+ timer: threading.Timer | None = None
32
+ if has_threads():
33
+ timer = threading.Timer(SLOW_AFTER if after is None else after, _say, args=(message,))
34
+ timer.daemon = True
35
+ try:
36
+ timer.start()
37
+ except RuntimeError: # a platform that has the module but cannot start a thread
38
+ timer = None
39
+ try:
40
+ yield
41
+ finally:
42
+ if timer is not None:
43
+ timer.cancel()
44
+
45
+
46
+ def _say(message: str) -> None:
47
+ print(f"tl-transform: {message}", file=sys.stderr, flush=True)
@@ -9,11 +9,16 @@ run over it would exit cleanly and drop every borrowed clause's own reference
9
9
  number, which is exactly the identifier a conformance document exists to carry.
10
10
 
11
11
  The tool is reached as a command, not imported. Its command line is the surface
12
- it publishes; its modules move between releases.
12
+ it publishes; its modules move between releases. Where the platform has no
13
+ processes — Python under Pyodide in a browser — the console entry point the
14
+ package declares in its own metadata is called in-process instead (SR-0014):
15
+ that entry point is what the ``tl`` command itself runs, so it is the command
16
+ by another route, not an import of the tool's modules for their functions.
13
17
  """
14
18
 
15
19
  from __future__ import annotations
16
20
 
21
+ import io
17
22
  import json
18
23
  import os
19
24
  import shutil
@@ -21,10 +26,13 @@ import subprocess
21
26
  import sys
22
27
  import tempfile
23
28
  import tomllib
29
+ from contextlib import redirect_stderr, redirect_stdout
30
+ from importlib.metadata import entry_points
24
31
  from pathlib import Path
25
32
  from typing import Any
26
33
 
27
34
  from .model import Graph, index
35
+ from .progress import slow
28
36
 
29
37
  CONFIG = "throughline.toml"
30
38
 
@@ -75,23 +83,61 @@ def executable(name: str) -> str:
75
83
  raise TransformError(f"{name} is not installed beside this tool nor on the path")
76
84
 
77
85
 
86
+ def has_processes() -> bool:
87
+ """Whether this platform can start a process at all."""
88
+ return sys.platform != "emscripten"
89
+
90
+
91
+ def _in_process(name: str, argv: list[str]) -> tuple[int, str, str]:
92
+ """Call the console entry point the package declares for ``name``.
93
+
94
+ Resolved from package metadata, never from a module path written here, so
95
+ what runs is exactly what the ``tl`` command on a terminal runs.
96
+ """
97
+ found = [ep for ep in entry_points(group="console_scripts") if ep.name == name]
98
+ if not found:
99
+ raise TransformError(f"no package installed here declares the {name} command")
100
+ main = found[0].load()
101
+ out, err = io.StringIO(), io.StringIO()
102
+ with redirect_stdout(out), redirect_stderr(err):
103
+ try:
104
+ code = main(argv)
105
+ except SystemExit as exc:
106
+ code = exc.code if isinstance(exc.code, int) else (0 if exc.code is None else 1)
107
+ return int(code or 0), out.getvalue(), err.getvalue()
108
+
109
+
78
110
  def run(root: Path, args: list[str], composed: bool) -> str:
79
111
  """Run the tool over the graph and hand back what it wrote."""
80
- command = [executable("tl-compose" if composed else "tl"), "-C", str(root), *args]
81
- try:
82
- done = subprocess.run(command, capture_output=True, text=True, encoding="utf-8")
83
- except OSError as exc: # pragma: no cover - the executable check above covers the common case
84
- raise TransformError(f"could not run {command[0]}: {exc}") from exc
85
- if done.returncode != 0:
86
- detail = done.stderr.strip() or done.stdout.strip() or f"exit {done.returncode}"
87
- raise TransformError(f"{Path(command[0]).name} {args[0]} failed — {detail}")
88
- return done.stdout
112
+ name = "tl-compose" if composed else "tl"
113
+ argv = ["-C", str(root), *args]
114
+ if has_processes():
115
+ command = [executable(name), *argv]
116
+ try:
117
+ done = subprocess.run(command, capture_output=True, text=True, encoding="utf-8")
118
+ code, stdout, stderr = done.returncode, done.stdout, done.stderr
119
+ except OSError:
120
+ # A platform that has an executable but cannot start it: the
121
+ # entry point is the same command by the other route.
122
+ code, stdout, stderr = _in_process(name, argv)
123
+ else:
124
+ code, stdout, stderr = _in_process(name, argv)
125
+ if code != 0:
126
+ detail = stderr.strip() or stdout.strip() or f"exit {code}"
127
+ raise TransformError(f"{name} {args[0]} failed — {detail}")
128
+ return stdout
129
+
130
+
131
+ def _tool(composed: bool) -> str:
132
+ return "tl-compose" if composed else "tl"
89
133
 
90
134
 
91
135
  def load(root: Path) -> Graph:
92
136
  """The graph, as the tool exports it."""
93
137
  composed = is_composed(root)
94
- raw: dict[str, Any] = json.loads(run(root, ["dump"], composed))
138
+ fetching = " — its sources may be being fetched" if composed else ""
139
+ with slow(f"still reading the graph with {_tool(composed)}{fetching}…"):
140
+ raw: dict[str, Any] = json.loads(run(root, ["dump"], composed))
95
141
  return index(raw, composed)
96
142
 
97
143
 
@@ -104,5 +150,6 @@ def docs(root: Path, document: str, composed: bool) -> str:
104
150
  with tempfile.TemporaryDirectory(prefix="tl-transform-") as scratch:
105
151
  path = Path(scratch) / "document.md"
106
152
  path.write_text(document, encoding="utf-8")
107
- run(root, ["docs", str(path)], composed)
153
+ with slow(f"still asking {_tool(composed)} to write the document…"):
154
+ run(root, ["docs", str(path)], composed)
108
155
  return path.read_text(encoding="utf-8")
@@ -20,6 +20,9 @@ CLEAN = "clean"
20
20
  DIRTY = "uncommitted changes"
21
21
  UNTRACKED = "not under version control"
22
22
 
23
+ #: The words a caller may state the tree in, and what each is written as.
24
+ TREE_WORDS = {"clean": CLEAN, "dirty": DIRTY, "untracked": UNTRACKED}
25
+
23
26
 
24
27
  @dataclass(frozen=True)
25
28
  class Provenance:
@@ -89,3 +92,26 @@ def provenance_of(root: Path, tool: str) -> Provenance:
89
92
  if not commit:
90
93
  tree = DIRTY
91
94
  return Provenance(repository=repository, ref=ref, commit=commit, tree=tree, tool=tool)
95
+
96
+
97
+ def stated(
98
+ tool: str,
99
+ repository: str | None,
100
+ ref: str | None,
101
+ commit: str | None,
102
+ tree: str | None,
103
+ ) -> Provenance:
104
+ """Provenance as the caller states it (SR-0013). Git is not consulted.
105
+
106
+ A caller that gives any of the four knows better than git — the editor
107
+ holds them from the clone and has no git to ask — so nothing is merged
108
+ with a reading; what is unstated is none, and an unstated tree is not
109
+ under version control.
110
+ """
111
+ return Provenance(
112
+ repository=repository or "graph",
113
+ ref=ref or "",
114
+ commit=commit or "",
115
+ tree=TREE_WORDS[tree] if tree else UNTRACKED,
116
+ tool=tool,
117
+ )
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: throughline-transform
3
- Version: 0.1.0
3
+ Version: 0.3.0
4
4
  Summary: Turn a throughline requirements graph on disk, committed or not, into the forms its readers open: Markdown, a folder of Obsidian notes, CSV, an Excel workbook, a Word document, or a print-ready HTML document. Ships the tl-transform CLI.
5
5
  Author-email: Henry J Grech-Cini <henry.grechcini@gmail.com>
6
6
  License-Expression: Apache-2.0
@@ -82,15 +82,33 @@ second, and is run as a command — its command line is the surface it publishes
82
82
  | Format | What you get |
83
83
  |---|---|
84
84
  | `md` | The tool's own document: a summary, a catalogue of every item in full, the mirrored clauses of adopted sources. `--body table` or `both` for a one-line-per-item table, `--matrix` for one traceability matrix per grounding link type, `--markers` to keep the region markers so `tl docs` can refill the file later. |
85
- | `notes` | One Markdown note per item in a folder per register, YAML front matter as properties (type, status, attributes, the title as an alias, a tag each for type and status), every identifier a `[[wikilink]]`. Cited clauses under `sources/<namespace>/`, the colon in their name replaced by a space. Open the folder as an Obsidian vault: the graph view is the intent graph, and a note's backlinks are what rests on it. |
85
+ | `notes` | One Markdown note per item in a folder per register: YAML front matter as properties (type, status, attributes, the title as an alias, a tag each for type and status), a heading of the identifier and title, the item's words, rationale and links, then what links to it — `Implements this`, `Derives from this` — every identifier a `[[wikilink]]`. Cited clauses under `sources/<namespace>/`, the colon in their name replaced by a space. Open the folder as an Obsidian vault: the graph view is the intent graph, and a note's backlinks are what rests on it. |
86
86
  | `csv` | A zip of one file of items (or one per register with `--split per-register`), `links.csv` with one row per link naming the sheet at each end, one file per cited source, and the provenance. |
87
87
  | `xlsx` | The same as sheets, read-only by recommendation with the structure locked and no password. Sorting and filtering stay allowed; a spreadsheet nobody can sort is one nobody can review. |
88
88
  | `docx` | A title page with the provenance, a contents field Word fills in, a section per register, a heading per item with its type and status beneath, its words as a quotation, its rationale, its attributes in small print, and one appendix per cited source. |
89
89
  | `html` | The same document as one self-contained page with print typography, A4 page rules and a contents list of links. Print it to PDF; the browser numbers the pages. |
90
+ | `blocks` | The document's structure as JSON — the same list of headings, quotations, paragraphs, attribute lines, tables and appendices the Word and HTML outputs are built from — for a front end that lays out its own pages. The editor's PDF is laid out from it. |
90
91
 
91
92
  Every output carries the repository, ref, commit, working-tree state and tool
92
93
  version it was taken from, because an output outlives the tree that made it and
93
- the first question anyone asks of one is what it was true of.
94
+ the first question anyone asks of one is what it was true of. A caller that
95
+ knows them without git — the editor holds them from its clone — states them with
96
+ `--repository`, `--ref`, `--commit` and `--tree clean|dirty|untracked`, and git
97
+ is then not consulted.
98
+
99
+ A quick run is silent. When a step — reading the graph, asking the tool to
100
+ write the document, writing the file — has run for a second, one line on
101
+ stderr says which, because a composed graph fetching its sources for the first
102
+ time otherwise reads as a hang.
103
+
104
+ ## One implementation, two surfaces
105
+
106
+ The [throughline editor](https://github.com/rhodium-org/throughline-editor)
107
+ runs this package as a wheel under Pyodide beside `tl` and `tl-compose`, so an
108
+ export from a browser tab and an export from a terminal are the same bytes for
109
+ the same graph at the same commit. Pyodide has no processes, so there the tool
110
+ calls the console entry point `tl` or `tl-compose` declares in its package
111
+ metadata — the same function the command runs — instead of spawning it.
94
112
 
95
113
  ## Self-hosting
96
114
 
@@ -12,6 +12,7 @@ src/throughline_transform/model.py
12
12
  src/throughline_transform/notes.py
13
13
  src/throughline_transform/office.py
14
14
  src/throughline_transform/package.py
15
+ src/throughline_transform/progress.py
15
16
  src/throughline_transform/project.py
16
17
  src/throughline_transform/provenance.py
17
18
  src/throughline_transform/shape.py
@@ -23,4 +24,5 @@ src/throughline_transform.egg-info/entry_points.txt
23
24
  src/throughline_transform.egg-info/requires.txt
24
25
  src/throughline_transform.egg-info/top_level.txt
25
26
  tests/conftest.py
26
- tests/test_outputs.py
27
+ tests/test_outputs.py
28
+ tests/test_surface.py
@@ -235,8 +235,19 @@ def test_notes_are_one_per_item_with_front_matter_and_links(plain_graph: Path):
235
235
  sr2 = entries["System requirements/SR-0002.md"].decode()
236
236
  assert sr2.startswith('---\nuid: "SR-0002"\n')
237
237
  assert 'priority: "should"' in sr2 and ' - "type/system_requirement"' in sr2 and ' - "status/draft"' in sr2
238
+ # The body is the tool's block reshaped for a note (SR-0009): a heading,
239
+ # the type and status beneath, no attribute line, the incoming links.
240
+ body = sr2.split("\n---\n", 1)[1]
241
+ assert body.startswith("# SR-0002 — Declare it in \\[\\[sources\\]\\]\nsystem requirement · draft\n")
242
+ assert "**priority**" not in body and "**origin**" not in body
238
243
  assert "*Relates:* [[SR-0001]]" in sr2
239
244
  assert "*Implements:* [[UR-0002]]" in sr2
245
+ sr1 = entries["System requirements/SR-0001.md"].decode()
246
+ assert "*Refines this:* [[SR-0003]]" in sr1 and "*Relates this:* [[SR-0002]]" in sr1
247
+ ur1 = entries["User requirements/UR-0001.md"].decode()
248
+ assert "*Implements this:* [[SR-0001]]" in ur1
249
+ int1 = entries["Intents/INT-0001.md"].decode()
250
+ assert "*Derives from this:* [[UR-0001]], [[UR-0002]]" in int1
240
251
  # The TOML table in prose is escaped rather than becoming a ghost note. The
241
252
  # title in the front matter is a quoted YAML string, which the note tool
242
253
  # reads as a property, not as a link.
@@ -266,6 +277,9 @@ def test_borrowed_clause_notes_replace_the_colon(composed_graph: Path):
266
277
  assert 'uid: "src:SR-0001"' in clause and 'source: "src"' in clause
267
278
  citing = entries["vault/System requirements/SR-0001.md"].decode()
268
279
  assert "[[src SR-0001|src:SR-0001]]" in citing
280
+ # The clause shows which local items claim it.
281
+ assert "*Satisfies this:* [[SR-0001]]" in clause
282
+ assert clause.split("\n---\n", 1)[1].startswith("# src:SR-0001 — ")
269
283
  assert note_name("asvs:SR-0255") == "asvs SR-0255"
270
284
 
271
285
 
@@ -0,0 +1,183 @@
1
+ # Copyright (c) 2026 Henry J Grech-Cini
2
+ # SPDX-License-Identifier: Apache-2.0
3
+ """What the editor needs of this package (INT-0002): structure as data,
4
+ provenance stated by the caller, and running where there are no processes."""
5
+
6
+ from __future__ import annotations
7
+
8
+ import json
9
+ import subprocess
10
+ import sys
11
+ import zipfile
12
+ from pathlib import Path
13
+
14
+ import pytest
15
+
16
+ from throughline_transform import project
17
+ from throughline_transform.cli import main
18
+ from throughline_transform.provenance import CLEAN, DIRTY, UNTRACKED, stated
19
+
20
+ # --- blocks (SR-0012) --------------------------------------------------------
21
+
22
+
23
+ def test_blocks_output_is_the_documents_structure(plain_graph: Path, tmp_path: Path):
24
+ out = tmp_path / "doc.json"
25
+ assert main(["blocks", "-C", str(plain_graph), "-o", str(out), "--body", "both"]) == 0
26
+ doc = json.loads(out.read_text(encoding="utf-8"))
27
+ assert set(doc) == {"provenance", "provenance_lines", "blocks"}
28
+ assert doc["provenance"]["repository"] == "plain" and doc["provenance"]["tree"] == UNTRACKED
29
+ blocks = doc["blocks"]
30
+ assert blocks[0] == {"text": "plain — requirements", "heading": 1}
31
+ items = [b for b in blocks if "item" in b]
32
+ assert len(items) == 7
33
+ sr1 = next(b for b in items if b["item"]["uid"] == "SR-0001")
34
+ assert sr1["heading"] == 4 and sr1["item"]["type"] == "system_requirement" and sr1["item"]["status"] == "draft"
35
+ assert any(b.get("quote") for b in blocks) and any(b.get("small") for b in blocks)
36
+ assert any(b.get("group") and b["text"] == "System requirements" for b in blocks)
37
+ assert any("table" in b for b in blocks) # --body both carries the table of items
38
+ # Absent fields are omitted rather than written as false or null.
39
+ assert all(v not in (False, None, "") or k == "text" for b in blocks for k, v in b.items())
40
+
41
+
42
+ def test_blocks_agree_with_the_docx(plain_graph: Path, tmp_path: Path):
43
+ assert main(["blocks", "-C", str(plain_graph), "-o", str(tmp_path / "b.json")]) == 0
44
+ assert main(["docx", "-C", str(plain_graph), "-o", str(tmp_path / "d.docx")]) == 0
45
+ headings = [b["text"] for b in json.loads((tmp_path / "b.json").read_text())["blocks"] if b.get("heading")]
46
+ with zipfile.ZipFile(tmp_path / "d.docx") as zf:
47
+ document = zf.read("word/document.xml").decode("utf-8")
48
+ for text in headings:
49
+ assert text.replace("&", "&amp;").replace("<", "&lt;").replace(">", "&gt;").replace('"', "&quot;") in document
50
+
51
+
52
+ def test_composed_blocks_carry_the_appendix(composed_graph: Path, tmp_path: Path):
53
+ out = tmp_path / "c.json"
54
+ assert main(["blocks", "-C", str(composed_graph), "-o", str(out)]) == 0
55
+ blocks = json.loads(out.read_text())["blocks"]
56
+ appendix = next(b for b in blocks if b.get("group") and b["text"].startswith("Appendix A"))
57
+ assert "subtitle" in appendix
58
+
59
+
60
+ # --- provenance stated by the caller (SR-0013) ------------------------------
61
+
62
+
63
+ def test_stated_provenance_replaces_git(git_graph: Path, tmp_path: Path, monkeypatch: pytest.MonkeyPatch):
64
+ calls: list[list[str]] = []
65
+ real = subprocess.run
66
+
67
+ def spy(cmd, *a, **k):
68
+ if cmd and cmd[0] == "git":
69
+ calls.append(list(cmd))
70
+ return real(cmd, *a, **k)
71
+
72
+ monkeypatch.setattr(subprocess, "run", spy)
73
+ out = tmp_path / "s.md"
74
+ assert main([
75
+ "md", "-C", str(git_graph), "-o", str(out),
76
+ "--repository", "x/y", "--ref", "v1", "--commit", "abc", "--tree", "clean",
77
+ ]) == 0
78
+ text = out.read_text()
79
+ assert "- Repository: x/y" in text and "- Ref: v1" in text and "- Commit: abc" in text
80
+ assert f"- Working tree: {CLEAN}" in text
81
+ assert calls == []
82
+
83
+
84
+ def test_a_single_stated_flag_means_git_is_not_asked(git_graph: Path, tmp_path: Path):
85
+ out = tmp_path / "r.md"
86
+ assert main(["md", "-C", str(git_graph), "-o", str(out), "--repository", "only/this"]) == 0
87
+ text = out.read_text()
88
+ assert "- Repository: only/this" in text
89
+ assert "- Ref: none" in text and "- Commit: none" in text
90
+ assert f"- Working tree: {UNTRACKED}" in text
91
+
92
+
93
+ def test_tree_words():
94
+ assert stated("t", "r", None, None, "dirty").tree == DIRTY
95
+ assert stated("t", "r", None, None, "untracked").tree == UNTRACKED
96
+ assert stated("t", None, None, None, None).repository == "graph"
97
+
98
+
99
+ # --- no processes (SR-0014) ---------------------------------------------------
100
+
101
+
102
+ def test_without_processes_the_entry_point_runs_in_process(plain_graph: Path, composed_graph: Path, tmp_path: Path, monkeypatch: pytest.MonkeyPatch):
103
+ via_command = {}
104
+ for fmt in ("md", "xlsx"):
105
+ assert main([fmt, "-C", str(composed_graph), "-o", str(tmp_path / f"cmd.{fmt}"), "--repository", "r", "--tree", "clean"]) == 0
106
+ via_command[fmt] = (tmp_path / f"cmd.{fmt}").read_bytes()
107
+
108
+ monkeypatch.setattr(sys, "platform", "emscripten")
109
+ assert not project.has_processes()
110
+
111
+ def refuse(*a, **k): # a process must never be started on this platform
112
+ raise AssertionError("subprocess.run was called without processes")
113
+
114
+ monkeypatch.setattr(subprocess, "run", refuse)
115
+ for fmt in ("md", "xlsx"):
116
+ assert main([fmt, "-C", str(composed_graph), "-o", str(tmp_path / f"in.{fmt}"), "--repository", "r", "--tree", "clean"]) == 0
117
+ assert (tmp_path / f"in.{fmt}").read_bytes() == via_command[fmt]
118
+ # The plain graph too: the core entry point, not only the composer's.
119
+ assert main(["notes", "-C", str(plain_graph), "-o", str(tmp_path / "in-notes.zip"), "--repository", "r"]) == 0
120
+
121
+
122
+ def test_the_entry_point_is_resolved_from_metadata(monkeypatch: pytest.MonkeyPatch):
123
+ monkeypatch.setattr(sys, "platform", "emscripten")
124
+ with pytest.raises(project.TransformError) as exc:
125
+ project._in_process("no-such-command", ["--version"])
126
+ assert "declares the no-such-command command" in str(exc.value)
127
+ code, out, err = project._in_process("tl", ["--version"])
128
+ assert code == 0 and out.startswith("tl ") and err == ""
129
+
130
+
131
+ def test_a_failing_tool_is_reported_in_process(tmp_path: Path, monkeypatch: pytest.MonkeyPatch):
132
+ monkeypatch.setattr(sys, "platform", "emscripten")
133
+ with pytest.raises(project.TransformError) as exc:
134
+ project.run(tmp_path, ["dump"], composed=False)
135
+ assert "tl dump failed" in str(exc.value)
136
+
137
+
138
+ # --- a word when a step is slow (SR-0015) -----------------------------------
139
+
140
+
141
+ def _capture(capsys, argv):
142
+ code = main(argv)
143
+ out = capsys.readouterr()
144
+ return code, out.out, out.err
145
+
146
+
147
+ def test_a_quick_run_says_nothing_on_stderr(plain_graph: Path, tmp_path: Path, capsys: pytest.CaptureFixture):
148
+ code, out, err = _capture(capsys, ["md", "-C", str(plain_graph), "-o", str(tmp_path / "q.md")])
149
+ assert code == 0 and err == "" and str(tmp_path / "q.md") in out
150
+
151
+
152
+ def test_a_slow_step_is_named_once_on_stderr(composed_graph: Path, tmp_path: Path, capsys: pytest.CaptureFixture, monkeypatch: pytest.MonkeyPatch):
153
+ from throughline_transform import progress
154
+
155
+ monkeypatch.setattr(progress, "SLOW_AFTER", 0.2)
156
+ real = subprocess.run
157
+
158
+ def dawdle(cmd, *a, **k):
159
+ if "dump" in cmd:
160
+ import time
161
+
162
+ time.sleep(0.5)
163
+ return real(cmd, *a, **k)
164
+
165
+ monkeypatch.setattr(subprocess, "run", dawdle)
166
+ code, out, err = _capture(capsys, ["md", "-C", str(composed_graph), "-o", str(tmp_path / "s.md")])
167
+ assert code == 0
168
+ # Once per slow step: the reading step was made slow, and with the
169
+ # threshold this low the docs step over a composed graph may be too.
170
+ assert err.startswith("tl-transform: still reading the graph with tl-compose — its sources may be being fetched")
171
+ assert err.count("still reading") == 1
172
+ assert all(line.startswith("tl-transform: still ") for line in err.splitlines())
173
+ assert str(tmp_path / "s.md") in out
174
+
175
+
176
+ def test_no_threads_means_no_feedback(composed_graph: Path, tmp_path: Path, capsys: pytest.CaptureFixture, monkeypatch: pytest.MonkeyPatch):
177
+ from throughline_transform import progress
178
+
179
+ monkeypatch.setattr(progress, "SLOW_AFTER", 0.05)
180
+ monkeypatch.setattr(sys, "platform", "emscripten")
181
+ assert not progress.has_threads()
182
+ code, _, err = _capture(capsys, ["notes", "-C", str(composed_graph), "-o", str(tmp_path / "n.zip"), "--repository", "r"])
183
+ assert code == 0 and err == ""