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.
- {throughline_transform-0.1.0/src/throughline_transform.egg-info → throughline_transform-0.3.0}/PKG-INFO +21 -3
- {throughline_transform-0.1.0 → throughline_transform-0.3.0}/README.md +20 -2
- {throughline_transform-0.1.0 → throughline_transform-0.3.0}/pyproject.toml +1 -1
- {throughline_transform-0.1.0 → throughline_transform-0.3.0}/src/throughline_transform/blocks.py +27 -0
- {throughline_transform-0.1.0 → throughline_transform-0.3.0}/src/throughline_transform/cli.py +30 -10
- {throughline_transform-0.1.0 → throughline_transform-0.3.0}/src/throughline_transform/notes.py +54 -3
- throughline_transform-0.3.0/src/throughline_transform/progress.py +47 -0
- {throughline_transform-0.1.0 → throughline_transform-0.3.0}/src/throughline_transform/project.py +59 -12
- {throughline_transform-0.1.0 → throughline_transform-0.3.0}/src/throughline_transform/provenance.py +26 -0
- {throughline_transform-0.1.0 → throughline_transform-0.3.0/src/throughline_transform.egg-info}/PKG-INFO +21 -3
- {throughline_transform-0.1.0 → throughline_transform-0.3.0}/src/throughline_transform.egg-info/SOURCES.txt +3 -1
- {throughline_transform-0.1.0 → throughline_transform-0.3.0}/tests/test_outputs.py +14 -0
- throughline_transform-0.3.0/tests/test_surface.py +183 -0
- {throughline_transform-0.1.0 → throughline_transform-0.3.0}/LICENSE +0 -0
- {throughline_transform-0.1.0 → throughline_transform-0.3.0}/MANIFEST.in +0 -0
- {throughline_transform-0.1.0 → throughline_transform-0.3.0}/NOTICE +0 -0
- {throughline_transform-0.1.0 → throughline_transform-0.3.0}/setup.cfg +0 -0
- {throughline_transform-0.1.0 → throughline_transform-0.3.0}/src/throughline_transform/__init__.py +0 -0
- {throughline_transform-0.1.0 → throughline_transform-0.3.0}/src/throughline_transform/html.py +0 -0
- {throughline_transform-0.1.0 → throughline_transform-0.3.0}/src/throughline_transform/markdown.py +0 -0
- {throughline_transform-0.1.0 → throughline_transform-0.3.0}/src/throughline_transform/model.py +0 -0
- {throughline_transform-0.1.0 → throughline_transform-0.3.0}/src/throughline_transform/office.py +0 -0
- {throughline_transform-0.1.0 → throughline_transform-0.3.0}/src/throughline_transform/package.py +0 -0
- {throughline_transform-0.1.0 → throughline_transform-0.3.0}/src/throughline_transform/shape.py +0 -0
- {throughline_transform-0.1.0 → throughline_transform-0.3.0}/src/throughline_transform/tables.py +0 -0
- {throughline_transform-0.1.0 → throughline_transform-0.3.0}/src/throughline_transform.egg-info/dependency_links.txt +0 -0
- {throughline_transform-0.1.0 → throughline_transform-0.3.0}/src/throughline_transform.egg-info/entry_points.txt +0 -0
- {throughline_transform-0.1.0 → throughline_transform-0.3.0}/src/throughline_transform.egg-info/requires.txt +0 -0
- {throughline_transform-0.1.0 → throughline_transform-0.3.0}/src/throughline_transform.egg-info/top_level.txt +0 -0
- {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.
|
|
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
|
|
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
|
|
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.
|
|
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"
|
{throughline_transform-0.1.0 → throughline_transform-0.3.0}/src/throughline_transform/blocks.py
RENAMED
|
@@ -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
|
+
)
|
{throughline_transform-0.1.0 → throughline_transform-0.3.0}/src/throughline_transform/cli.py
RENAMED
|
@@ -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 =
|
|
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
|
-
|
|
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
|
{throughline_transform-0.1.0 → throughline_transform-0.3.0}/src/throughline_transform/notes.py
RENAMED
|
@@ -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
|
|
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(
|
|
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)
|
{throughline_transform-0.1.0 → throughline_transform-0.3.0}/src/throughline_transform/project.py
RENAMED
|
@@ -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
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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")
|
{throughline_transform-0.1.0 → throughline_transform-0.3.0}/src/throughline_transform/provenance.py
RENAMED
|
@@ -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.
|
|
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
|
|
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("&", "&").replace("<", "<").replace(">", ">").replace('"', """) 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 == ""
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
{throughline_transform-0.1.0 → throughline_transform-0.3.0}/src/throughline_transform/__init__.py
RENAMED
|
File without changes
|
{throughline_transform-0.1.0 → throughline_transform-0.3.0}/src/throughline_transform/html.py
RENAMED
|
File without changes
|
{throughline_transform-0.1.0 → throughline_transform-0.3.0}/src/throughline_transform/markdown.py
RENAMED
|
File without changes
|
{throughline_transform-0.1.0 → throughline_transform-0.3.0}/src/throughline_transform/model.py
RENAMED
|
File without changes
|
{throughline_transform-0.1.0 → throughline_transform-0.3.0}/src/throughline_transform/office.py
RENAMED
|
File without changes
|
{throughline_transform-0.1.0 → throughline_transform-0.3.0}/src/throughline_transform/package.py
RENAMED
|
File without changes
|
{throughline_transform-0.1.0 → throughline_transform-0.3.0}/src/throughline_transform/shape.py
RENAMED
|
File without changes
|
{throughline_transform-0.1.0 → throughline_transform-0.3.0}/src/throughline_transform/tables.py
RENAMED
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|