throughline-transform 0.6.0__tar.gz → 0.7.1__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 (34) hide show
  1. {throughline_transform-0.6.0/src/throughline_transform.egg-info → throughline_transform-0.7.1}/PKG-INFO +29 -5
  2. {throughline_transform-0.6.0 → throughline_transform-0.7.1}/README.md +25 -3
  3. {throughline_transform-0.6.0 → throughline_transform-0.7.1}/pyproject.toml +4 -2
  4. {throughline_transform-0.6.0 → throughline_transform-0.7.1}/src/throughline_transform/cli.py +5 -23
  5. {throughline_transform-0.6.0 → throughline_transform-0.7.1}/src/throughline_transform/markdown.py +38 -16
  6. {throughline_transform-0.6.0 → throughline_transform-0.7.1}/src/throughline_transform/model.py +0 -4
  7. {throughline_transform-0.6.0 → throughline_transform-0.7.1}/src/throughline_transform/project.py +0 -8
  8. {throughline_transform-0.6.0 → throughline_transform-0.7.1/src/throughline_transform.egg-info}/PKG-INFO +29 -5
  9. {throughline_transform-0.6.0 → throughline_transform-0.7.1}/src/throughline_transform.egg-info/SOURCES.txt +0 -2
  10. throughline_transform-0.7.1/src/throughline_transform.egg-info/requires.txt +4 -0
  11. {throughline_transform-0.6.0 → throughline_transform-0.7.1}/tests/conftest.py +28 -8
  12. {throughline_transform-0.6.0 → throughline_transform-0.7.1}/tests/test_outputs.py +6 -4
  13. {throughline_transform-0.6.0 → throughline_transform-0.7.1}/tests/test_surface.py +3 -1
  14. throughline_transform-0.6.0/src/throughline_transform/assistant.py +0 -133
  15. throughline_transform-0.6.0/src/throughline_transform.egg-info/requires.txt +0 -4
  16. throughline_transform-0.6.0/tests/test_assistant.py +0 -149
  17. {throughline_transform-0.6.0 → throughline_transform-0.7.1}/LICENSE +0 -0
  18. {throughline_transform-0.6.0 → throughline_transform-0.7.1}/MANIFEST.in +0 -0
  19. {throughline_transform-0.6.0 → throughline_transform-0.7.1}/NOTICE +0 -0
  20. {throughline_transform-0.6.0 → throughline_transform-0.7.1}/setup.cfg +0 -0
  21. {throughline_transform-0.6.0 → throughline_transform-0.7.1}/src/throughline_transform/__init__.py +0 -0
  22. {throughline_transform-0.6.0 → throughline_transform-0.7.1}/src/throughline_transform/blocks.py +0 -0
  23. {throughline_transform-0.6.0 → throughline_transform-0.7.1}/src/throughline_transform/html.py +0 -0
  24. {throughline_transform-0.6.0 → throughline_transform-0.7.1}/src/throughline_transform/notes.py +0 -0
  25. {throughline_transform-0.6.0 → throughline_transform-0.7.1}/src/throughline_transform/office.py +0 -0
  26. {throughline_transform-0.6.0 → throughline_transform-0.7.1}/src/throughline_transform/package.py +0 -0
  27. {throughline_transform-0.6.0 → throughline_transform-0.7.1}/src/throughline_transform/progress.py +0 -0
  28. {throughline_transform-0.6.0 → throughline_transform-0.7.1}/src/throughline_transform/provenance.py +0 -0
  29. {throughline_transform-0.6.0 → throughline_transform-0.7.1}/src/throughline_transform/shape.py +0 -0
  30. {throughline_transform-0.6.0 → throughline_transform-0.7.1}/src/throughline_transform/tables.py +0 -0
  31. {throughline_transform-0.6.0 → throughline_transform-0.7.1}/src/throughline_transform.egg-info/dependency_links.txt +0 -0
  32. {throughline_transform-0.6.0 → throughline_transform-0.7.1}/src/throughline_transform.egg-info/entry_points.txt +0 -0
  33. {throughline_transform-0.6.0 → throughline_transform-0.7.1}/src/throughline_transform.egg-info/top_level.txt +0 -0
  34. {throughline_transform-0.6.0 → throughline_transform-0.7.1}/tests/test_only.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: throughline-transform
3
- Version: 0.6.0
3
+ Version: 0.7.1
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
@@ -15,13 +15,15 @@ Classifier: Operating System :: OS Independent
15
15
  Classifier: Programming Language :: Python :: 3
16
16
  Classifier: Programming Language :: Python :: 3.11
17
17
  Classifier: Programming Language :: Python :: 3.12
18
+ Classifier: Programming Language :: Python :: 3.13
19
+ Classifier: Programming Language :: Python :: 3.14
18
20
  Classifier: Topic :: Software Development :: Documentation
19
21
  Classifier: Topic :: Office/Business
20
22
  Requires-Python: >=3.11
21
23
  Description-Content-Type: text/markdown
22
24
  License-File: LICENSE
23
25
  License-File: NOTICE
24
- Requires-Dist: throughline>=3.18.0
26
+ Requires-Dist: throughline>=3.11.1
25
27
  Provides-Extra: dev
26
28
  Requires-Dist: pytest>=8.0; extra == "dev"
27
29
  Dynamic: license-file
@@ -32,7 +34,7 @@ A [throughline](https://github.com/rhodium-org/throughline) requirements graph o
32
34
  disk — committed or not — in the forms its readers open. One command, one file:
33
35
 
34
36
  ```bash
35
- pipx install throughline-transform # pulls tl along too
37
+ uv tool install --python 3.13 --managed-python throughline-transform --with-executables-from throughline # tl too
36
38
 
37
39
  tl-transform md -C idd # Markdown, written by the tool itself
38
40
  tl-transform notes -C idd # a folder of notes for Obsidian (zip)
@@ -41,7 +43,6 @@ tl-transform csv -C idd # one row per item, a links file, a file
41
43
  tl-transform xlsx -C idd # the same as a read-only workbook that still sorts and filters
42
44
  tl-transform docx -C idd # a Word document: title page, contents, a heading per item
43
45
  tl-transform html -C idd # a print-ready page — print it to PDF from any browser
44
- tl-transform assistant -C idd # a folder an assistant that cannot run tl reads whole: one file per register, and how to answer
45
46
  ```
46
47
 
47
48
  It is the command-line half of the
@@ -51,6 +52,30 @@ disk. The editor needs the graph on GitHub. This does not — it reads the worki
51
52
  tree, and the output says whether that tree was clean, carried uncommitted
52
53
  changes, or was not under version control at all.
53
54
 
55
+ `--managed-python` has uv use its own build of Python rather than the operating
56
+ system's, so an OS Python upgrade does not break the install;
57
+ `--with-executables-from throughline` puts `tl` on your `PATH` beside it. Get uv
58
+ from [docs.astral.sh/uv](https://docs.astral.sh/uv/getting-started/installation/).
59
+ If you use pipx instead: `pipx install --include-deps throughline-transform`.
60
+
61
+ ## If `tl-transform` says `bad interpreter` after a Python upgrade
62
+
63
+ A tool installed with pipx (or into any virtual environment) runs on the Python it
64
+ was installed with. When your operating system upgrades its Python and removes the
65
+ old one, every command in that environment fails before any of its code runs, with
66
+ `bad interpreter` or `No module named ...`. Your graphs are fine; the environment has
67
+ to be rebuilt on the new Python:
68
+
69
+ | Installed with | Rebuild with |
70
+ |---|---|
71
+ | pipx | `pipx reinstall-all --python python3` (or the new Python's full path) |
72
+ | pipx, when `pipx` itself is broken too | `uvx pipx reinstall-all --python python3` |
73
+ | uv | `uv tool install --reinstall --python 3.13 --managed-python throughline-transform --with-executables-from throughline` |
74
+
75
+ An install made with uv's `--managed-python` does not hit this: the operating system
76
+ does not touch the Python uv manages. `tl doctor` (throughline releases after 6.0.0) says
77
+ which Python runs `tl` and how it was installed.
78
+
54
79
  ## What it does not do
55
80
 
56
81
  **It never renders an item's words.** The Markdown is asked of `tl docs` over a
@@ -86,7 +111,6 @@ second, and is run as a command — its command line is the surface it publishes
86
111
  | `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. |
87
112
  | `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. |
88
113
  | `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. |
89
- | `assistant` | A folder for an assistant that reads only a few files and cannot run `tl` — Microsoft 365 Copilot in a controlled environment reads at most fifty: one file per register carrying its items exactly as `tl dump` gives them, each with its fingerprint, and a manifest naming the repository, ref, commit and tree state, the file of each register, the `tl` that wrote it, and the change-set form `tl apply` accepts, taken from `tl apply --describe`, with the instruction to answer with a change set quoting each fingerprint and never with rewritten files. `--wrap md` writes each file as Markdown holding one fenced JSON block, for an assistant that will not read a `.json` file. Always a folder, never an archive. |
90
114
  | `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. |
91
115
 
92
116
  Every output carries the repository, ref, commit, working-tree state and tool
@@ -4,7 +4,7 @@ A [throughline](https://github.com/rhodium-org/throughline) requirements graph o
4
4
  disk — committed or not — in the forms its readers open. One command, one file:
5
5
 
6
6
  ```bash
7
- pipx install throughline-transform # pulls tl along too
7
+ uv tool install --python 3.13 --managed-python throughline-transform --with-executables-from throughline # tl too
8
8
 
9
9
  tl-transform md -C idd # Markdown, written by the tool itself
10
10
  tl-transform notes -C idd # a folder of notes for Obsidian (zip)
@@ -13,7 +13,6 @@ tl-transform csv -C idd # one row per item, a links file, a file
13
13
  tl-transform xlsx -C idd # the same as a read-only workbook that still sorts and filters
14
14
  tl-transform docx -C idd # a Word document: title page, contents, a heading per item
15
15
  tl-transform html -C idd # a print-ready page — print it to PDF from any browser
16
- tl-transform assistant -C idd # a folder an assistant that cannot run tl reads whole: one file per register, and how to answer
17
16
  ```
18
17
 
19
18
  It is the command-line half of the
@@ -23,6 +22,30 @@ disk. The editor needs the graph on GitHub. This does not — it reads the worki
23
22
  tree, and the output says whether that tree was clean, carried uncommitted
24
23
  changes, or was not under version control at all.
25
24
 
25
+ `--managed-python` has uv use its own build of Python rather than the operating
26
+ system's, so an OS Python upgrade does not break the install;
27
+ `--with-executables-from throughline` puts `tl` on your `PATH` beside it. Get uv
28
+ from [docs.astral.sh/uv](https://docs.astral.sh/uv/getting-started/installation/).
29
+ If you use pipx instead: `pipx install --include-deps throughline-transform`.
30
+
31
+ ## If `tl-transform` says `bad interpreter` after a Python upgrade
32
+
33
+ A tool installed with pipx (or into any virtual environment) runs on the Python it
34
+ was installed with. When your operating system upgrades its Python and removes the
35
+ old one, every command in that environment fails before any of its code runs, with
36
+ `bad interpreter` or `No module named ...`. Your graphs are fine; the environment has
37
+ to be rebuilt on the new Python:
38
+
39
+ | Installed with | Rebuild with |
40
+ |---|---|
41
+ | pipx | `pipx reinstall-all --python python3` (or the new Python's full path) |
42
+ | pipx, when `pipx` itself is broken too | `uvx pipx reinstall-all --python python3` |
43
+ | uv | `uv tool install --reinstall --python 3.13 --managed-python throughline-transform --with-executables-from throughline` |
44
+
45
+ An install made with uv's `--managed-python` does not hit this: the operating system
46
+ does not touch the Python uv manages. `tl doctor` (throughline releases after 6.0.0) says
47
+ which Python runs `tl` and how it was installed.
48
+
26
49
  ## What it does not do
27
50
 
28
51
  **It never renders an item's words.** The Markdown is asked of `tl docs` over a
@@ -58,7 +81,6 @@ second, and is run as a command — its command line is the surface it publishes
58
81
  | `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
82
  | `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
83
  | `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
- | `assistant` | A folder for an assistant that reads only a few files and cannot run `tl` — Microsoft 365 Copilot in a controlled environment reads at most fifty: one file per register carrying its items exactly as `tl dump` gives them, each with its fingerprint, and a manifest naming the repository, ref, commit and tree state, the file of each register, the `tl` that wrote it, and the change-set form `tl apply` accepts, taken from `tl apply --describe`, with the instruction to answer with a change set quoting each fingerprint and never with rewritten files. `--wrap md` writes each file as Markdown holding one fenced JSON block, for an assistant that will not read a `.json` file. Always a folder, never an archive. |
62
84
  | `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. |
63
85
 
64
86
  Every output carries the repository, ref, commit, working-tree state and tool
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
4
4
 
5
5
  [project]
6
6
  name = "throughline-transform"
7
- version = "0.6.0"
7
+ version = "0.7.1"
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"
@@ -32,6 +32,8 @@ classifiers = [
32
32
  "Programming Language :: Python :: 3",
33
33
  "Programming Language :: Python :: 3.11",
34
34
  "Programming Language :: Python :: 3.12",
35
+ "Programming Language :: Python :: 3.13",
36
+ "Programming Language :: Python :: 3.14",
35
37
  "Topic :: Software Development :: Documentation",
36
38
  "Topic :: Office/Business",
37
39
  ]
@@ -41,7 +43,7 @@ classifiers = [
41
43
  # (SR-0003). It was written against throughline 2.2.0 and throughline-compose
42
44
  # 0.16.1; since 3.11.1 composition is the Tool's own (throughline UR-0037), `tl`
43
45
  # renders both directives, and throughline is the one floor.
44
- dependencies = ["throughline>=3.18.0"] # the assistant form reads each item's fingerprint from the dump and takes the change-set form from `tl apply --describe` (throughline SR-0251, SR-0252)
46
+ dependencies = ["throughline>=3.11.1"] # composition is the Tool's own since 3.11.1 (throughline UR-0037)
45
47
 
46
48
  [project.optional-dependencies]
47
49
  dev = ["pytest>=8.0"]
@@ -9,7 +9,6 @@
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
11
  tl-transform blocks [-C DIR] [-o FILE] [--body …] [--matrix] [--no-stats]
12
- tl-transform assistant [-C DIR] [-o DIR] [--wrap json|md]
13
12
 
14
13
  Any format takes --repository, --ref, --commit and --tree to state the
15
14
  provenance instead of reading git (SR-0013), and --only UID[,UID…] to hold
@@ -29,22 +28,19 @@ from throughline.version import distribution_version as _v
29
28
 
30
29
  from . import markdown as md
31
30
  from .blocks import as_blocks, to_json
32
- from .assistant import WRAPS, to_assistant
33
31
  from .html import to_html
34
32
  from .model import Graph, narrowed, register_titles, source_titles
35
33
  from .notes import to_notes
36
34
  from .office import to_docx, to_xlsx
37
35
  from .package import Entry, archive, unpack, utf8
38
36
  from .progress import slow
39
- from .project import TransformError, change_set_format, find_graph, load
37
+ from .project import TransformError, find_graph, load
40
38
  from .provenance import TREE_WORDS, Provenance, provenance_of, stated
41
39
  from .tables import Table, cited_sources, file_name, links_of, per_register, to_csv, whole_graph
42
40
 
43
- FORMATS = ("md", "notes", "csv", "xlsx", "docx", "html", "blocks", "assistant")
41
+ FORMATS = ("md", "notes", "csv", "xlsx", "docx", "html", "blocks")
44
42
  PROSE = ("md", "docx", "html", "blocks")
45
- FOLDERS = ("notes", "csv", "assistant")
46
- #: Always a folder, never an archive: an assistant cannot open one (SR-0017).
47
- FOLDER_ONLY = ("assistant",)
43
+ FOLDERS = ("notes", "csv")
48
44
 
49
45
 
50
46
  def version_string() -> str:
@@ -70,12 +66,6 @@ def build_parser() -> argparse.ArgumentParser:
70
66
  p.add_argument("--matrix", action="store_true", help="md, docx, html, blocks: add a traceability matrix per grounding link")
71
67
  p.add_argument("--no-stats", dest="stats", action="store_false", help="md, docx, html, blocks: leave out the tool's summary")
72
68
  p.add_argument("--markers", action="store_true", help="md: keep the tool's region markers so `tl docs` can refill the file")
73
- p.add_argument(
74
- "--wrap",
75
- choices=WRAPS,
76
- default="json",
77
- help="assistant: each file as JSON, or as Markdown holding one fenced JSON block for an assistant that will not read a .json file",
78
- )
79
69
  p.add_argument("--repository", metavar="OWNER/NAME", help="state the repository instead of reading git")
80
70
  p.add_argument("--ref", metavar="REF", help="state the ref instead of reading git")
81
71
  p.add_argument("--commit", metavar="SHA", help="state the commit instead of reading git")
@@ -134,12 +124,6 @@ def produce(graph: Graph, root: Path, fmt: str, opts: md.Options, provenance: Pr
134
124
  return utf8(to_json(blocks, provenance.lines(), provenance.record())), f"{stem}-blocks.json"
135
125
  return utf8(to_html(blocks, provenance)), f"{stem}.html"
136
126
 
137
- if fmt == "assistant":
138
- entries = to_assistant(
139
- graph.raw, provenance, change_set_format(root, graph.composed), wrap=opts.wrap, only=opts.only
140
- )
141
- return entries, f"{stem}-assistant"
142
-
143
127
  if fmt == "notes":
144
128
  text = md.to_markdown(
145
129
  root, graph, replace(opts, body="catalog", matrix=False, stats=False, markers=False), provenance
@@ -185,9 +169,7 @@ def main(argv: list[str] | None = None) -> int:
185
169
  only = named(args.only)
186
170
  if args.only is not None and not only:
187
171
  parser.error("--only names no item")
188
- opts = md.Options(
189
- body=args.body, matrix=args.matrix, stats=args.stats, markers=args.markers, split=args.split, only=only, wrap=args.wrap
190
- )
172
+ opts = md.Options(body=args.body, matrix=args.matrix, stats=args.stats, markers=args.markers, split=args.split, only=only)
191
173
  try:
192
174
  root = find_graph(args.directory)
193
175
  graph = load(root)
@@ -209,7 +191,7 @@ def main(argv: list[str] | None = None) -> int:
209
191
  provenance = replace(provenance, items=f"{len(only)} of {len(graph.items)}")
210
192
  result, default = produce(graph, root, args.format, opts, provenance)
211
193
  with slow(f"still writing {args.output or default}…"):
212
- target = write(result, default, args.output, args.folder or args.format in FOLDER_ONLY)
194
+ target = write(result, default, args.output, args.folder)
213
195
  except (TransformError, OSError, ValueError) as exc:
214
196
  print(f"tl-transform: {exc}", file=sys.stderr)
215
197
  return 1
@@ -31,9 +31,6 @@ class Options:
31
31
  markers: bool = False
32
32
  #: For the tabular outputs: one table for everything, or one per register.
33
33
  split: str = "one"
34
- #: For the assistant form: each file as JSON, or as Markdown holding one
35
- #: fenced JSON block.
36
- wrap: str = "json"
37
34
  #: The items the output holds, where the caller named them (SR-0016);
38
35
  #: empty for every item.
39
36
  only: tuple[str, ...] = ()
@@ -43,28 +40,53 @@ def _region(directive: str) -> str:
43
40
  return f"<!-- tl:{directive} -->\n<!-- tl:end -->"
44
41
 
45
42
 
46
- def _within(expression: str, opts: Options) -> str:
47
- """A directive's filter, joined with the items named, so tl docs writes only those (SR-0016).
43
+ class _Filters:
44
+ """Filters written in the language the graph declares (SR-0021).
48
45
 
49
- The identifiers are ones the graph holds (the command refuses any other), so
50
- each is written as a quoted literal the filter language reads (tl:SR-0045).
46
+ tl reads every filter of a project in the one language its configuration names
47
+ as ``filter_language`` under ``[project]`` (tl:SR-0337): ``gql`` for a graph
48
+ made or migrated by tl 6, the earlier expression language where it names none.
49
+ The tool never guesses a filter's language from its text, so neither does this.
51
50
  """
52
- if not opts.only:
53
- return expression
54
- named = ", ".join(repr(uid) for uid in opts.only)
55
- return f"({expression}) and (uid in [{named}])"
51
+
52
+ def __init__(self, graph: Graph) -> None:
53
+ project = graph.config.get("project") or {}
54
+ self.gql = project.get("filter_language") == "gql"
55
+
56
+ @property
57
+ def every(self) -> str:
58
+ return "TRUE" if self.gql else "True"
59
+
60
+ def incoming(self, link_type: str) -> str:
61
+ if self.gql:
62
+ return f"EXISTS {{ (item)<-[:{link_type}]-() }}"
63
+ return f"links.incoming({link_type!r})"
64
+
65
+ def within(self, expression: str, opts: Options) -> str:
66
+ """A directive's filter, joined with the items named, so tl docs writes only those (SR-0016).
67
+
68
+ The identifiers are ones the graph holds (the command refuses any other), so
69
+ each is written as a quoted literal the filter language reads (tl:SR-0045).
70
+ """
71
+ if not opts.only:
72
+ return expression
73
+ named = ", ".join(repr(uid) for uid in opts.only)
74
+ if self.gql:
75
+ return f"({expression}) AND (item.uid IN [{named}])"
76
+ return f"({expression}) and (uid in [{named}])"
56
77
 
57
78
 
58
79
  def directive_document(graph: Graph, opts: Options, provenance: Provenance) -> str:
59
80
  """The document the tool is asked to fill."""
81
+ f = _Filters(graph)
60
82
  lines: list[str] = [f"# {provenance.repository} — requirements", ""]
61
83
  lines += [f"- {line}" for line in provenance.lines()]
62
84
  lines.append("")
63
85
 
64
86
  if opts.stats:
65
- lines += ["## Summary", "", _region(f"stats {_within('True', opts)}"), ""]
87
+ lines += ["## Summary", "", _region(f"stats {f.within(f.every, opts)}"), ""]
66
88
  if opts.body in ("table", "both"):
67
- lines += ["## Items", "", _region(f"table {_within('True', opts)}"), ""]
89
+ lines += ["## Items", "", _region(f"table {f.within(f.every, opts)}"), ""]
68
90
  if opts.matrix:
69
91
  # One matrix per grounding link type the graph declares, each over the
70
92
  # items something actually reaches by that link. Over every item a
@@ -74,16 +96,16 @@ def directive_document(graph: Graph, opts: Options, provenance: Provenance) -> s
74
96
  lines += [
75
97
  f"### {link_type.replace('_', ' ')}",
76
98
  "",
77
- _region(f"matrix incoming:{link_type} {_within(f'links.incoming({link_type!r})', opts)}"),
99
+ _region(f"matrix incoming:{link_type} {f.within(f.incoming(link_type), opts)}"),
78
100
  "",
79
101
  ]
80
102
  if opts.body in ("catalog", "both"):
81
- lines += ["## Every item", "", _region(f"catalog {_within('True', opts)}"), ""]
103
+ lines += ["## Every item", "", _region(f"catalog {f.within(f.every, opts)}"), ""]
82
104
  # The words every cited clause answers to. Only over a composed graph: the
83
105
  # directive is the composer's, and a graph adopting no source has nothing
84
106
  # to mirror.
85
107
  if graph.composed:
86
- lines += ["## Clauses of adopted sources", "", _region(f"sourced {_within('True', opts)}"), ""]
108
+ lines += ["## Clauses of adopted sources", "", _region(f"sourced {f.within(f.every, opts)}"), ""]
87
109
  return "\n".join(lines)
88
110
 
89
111
 
@@ -72,9 +72,6 @@ class Graph:
72
72
  #: What the tool called itself in the dump.
73
73
  tool_version: str
74
74
  composed: bool
75
- #: The dump itself, as the tool wrote it, for the assistant form that hands
76
- #: it on unreshaped (SR-0017).
77
- raw: dict[str, Any] = field(default_factory=dict)
78
75
 
79
76
 
80
77
  def prefix_of(uid: str) -> str:
@@ -152,7 +149,6 @@ def index(dump: dict[str, Any], composed: bool) -> Graph:
152
149
  sources=sources,
153
150
  tool_version=str(meta.get("tool_version") or "?"),
154
151
  composed=composed,
155
- raw=dump,
156
152
  )
157
153
 
158
154
 
@@ -141,14 +141,6 @@ def load(root: Path) -> Graph:
141
141
  return index(raw, composed)
142
142
 
143
143
 
144
- def change_set_format(root: Path, composed: bool) -> str:
145
- """The change-set form ``tl apply`` accepts, as the tool itself states it
146
- (SR-0018): taken from the command, never written here, so what an assistant
147
- is told to write cannot drift from what apply reads."""
148
- with slow(f"still asking {_tool(composed)} for the change-set format…"):
149
- return run(root, ["apply", "--describe"], composed)
150
-
151
-
152
144
  def docs(root: Path, document: str, composed: bool) -> str:
153
145
  """Hand the tool a document of directives and read back what it wrote.
154
146
 
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: throughline-transform
3
- Version: 0.6.0
3
+ Version: 0.7.1
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
@@ -15,13 +15,15 @@ Classifier: Operating System :: OS Independent
15
15
  Classifier: Programming Language :: Python :: 3
16
16
  Classifier: Programming Language :: Python :: 3.11
17
17
  Classifier: Programming Language :: Python :: 3.12
18
+ Classifier: Programming Language :: Python :: 3.13
19
+ Classifier: Programming Language :: Python :: 3.14
18
20
  Classifier: Topic :: Software Development :: Documentation
19
21
  Classifier: Topic :: Office/Business
20
22
  Requires-Python: >=3.11
21
23
  Description-Content-Type: text/markdown
22
24
  License-File: LICENSE
23
25
  License-File: NOTICE
24
- Requires-Dist: throughline>=3.18.0
26
+ Requires-Dist: throughline>=3.11.1
25
27
  Provides-Extra: dev
26
28
  Requires-Dist: pytest>=8.0; extra == "dev"
27
29
  Dynamic: license-file
@@ -32,7 +34,7 @@ A [throughline](https://github.com/rhodium-org/throughline) requirements graph o
32
34
  disk — committed or not — in the forms its readers open. One command, one file:
33
35
 
34
36
  ```bash
35
- pipx install throughline-transform # pulls tl along too
37
+ uv tool install --python 3.13 --managed-python throughline-transform --with-executables-from throughline # tl too
36
38
 
37
39
  tl-transform md -C idd # Markdown, written by the tool itself
38
40
  tl-transform notes -C idd # a folder of notes for Obsidian (zip)
@@ -41,7 +43,6 @@ tl-transform csv -C idd # one row per item, a links file, a file
41
43
  tl-transform xlsx -C idd # the same as a read-only workbook that still sorts and filters
42
44
  tl-transform docx -C idd # a Word document: title page, contents, a heading per item
43
45
  tl-transform html -C idd # a print-ready page — print it to PDF from any browser
44
- tl-transform assistant -C idd # a folder an assistant that cannot run tl reads whole: one file per register, and how to answer
45
46
  ```
46
47
 
47
48
  It is the command-line half of the
@@ -51,6 +52,30 @@ disk. The editor needs the graph on GitHub. This does not — it reads the worki
51
52
  tree, and the output says whether that tree was clean, carried uncommitted
52
53
  changes, or was not under version control at all.
53
54
 
55
+ `--managed-python` has uv use its own build of Python rather than the operating
56
+ system's, so an OS Python upgrade does not break the install;
57
+ `--with-executables-from throughline` puts `tl` on your `PATH` beside it. Get uv
58
+ from [docs.astral.sh/uv](https://docs.astral.sh/uv/getting-started/installation/).
59
+ If you use pipx instead: `pipx install --include-deps throughline-transform`.
60
+
61
+ ## If `tl-transform` says `bad interpreter` after a Python upgrade
62
+
63
+ A tool installed with pipx (or into any virtual environment) runs on the Python it
64
+ was installed with. When your operating system upgrades its Python and removes the
65
+ old one, every command in that environment fails before any of its code runs, with
66
+ `bad interpreter` or `No module named ...`. Your graphs are fine; the environment has
67
+ to be rebuilt on the new Python:
68
+
69
+ | Installed with | Rebuild with |
70
+ |---|---|
71
+ | pipx | `pipx reinstall-all --python python3` (or the new Python's full path) |
72
+ | pipx, when `pipx` itself is broken too | `uvx pipx reinstall-all --python python3` |
73
+ | uv | `uv tool install --reinstall --python 3.13 --managed-python throughline-transform --with-executables-from throughline` |
74
+
75
+ An install made with uv's `--managed-python` does not hit this: the operating system
76
+ does not touch the Python uv manages. `tl doctor` (throughline releases after 6.0.0) says
77
+ which Python runs `tl` and how it was installed.
78
+
54
79
  ## What it does not do
55
80
 
56
81
  **It never renders an item's words.** The Markdown is asked of `tl docs` over a
@@ -86,7 +111,6 @@ second, and is run as a command — its command line is the surface it publishes
86
111
  | `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. |
87
112
  | `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. |
88
113
  | `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. |
89
- | `assistant` | A folder for an assistant that reads only a few files and cannot run `tl` — Microsoft 365 Copilot in a controlled environment reads at most fifty: one file per register carrying its items exactly as `tl dump` gives them, each with its fingerprint, and a manifest naming the repository, ref, commit and tree state, the file of each register, the `tl` that wrote it, and the change-set form `tl apply` accepts, taken from `tl apply --describe`, with the instruction to answer with a change set quoting each fingerprint and never with rewritten files. `--wrap md` writes each file as Markdown holding one fenced JSON block, for an assistant that will not read a `.json` file. Always a folder, never an archive. |
90
114
  | `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. |
91
115
 
92
116
  Every output carries the repository, ref, commit, working-tree state and tool
@@ -4,7 +4,6 @@ NOTICE
4
4
  README.md
5
5
  pyproject.toml
6
6
  src/throughline_transform/__init__.py
7
- src/throughline_transform/assistant.py
8
7
  src/throughline_transform/blocks.py
9
8
  src/throughline_transform/cli.py
10
9
  src/throughline_transform/html.py
@@ -25,7 +24,6 @@ src/throughline_transform.egg-info/entry_points.txt
25
24
  src/throughline_transform.egg-info/requires.txt
26
25
  src/throughline_transform.egg-info/top_level.txt
27
26
  tests/conftest.py
28
- tests/test_assistant.py
29
27
  tests/test_only.py
30
28
  tests/test_outputs.py
31
29
  tests/test_surface.py
@@ -0,0 +1,4 @@
1
+ throughline>=3.11.1
2
+
3
+ [dev]
4
+ pytest>=8.0
@@ -17,6 +17,8 @@ import subprocess
17
17
  import sys
18
18
  from pathlib import Path
19
19
 
20
+ import tomllib
21
+
20
22
  import pytest
21
23
 
22
24
  BIN = Path(sys.executable).parent
@@ -69,13 +71,14 @@ implements = { from = ["system_requirement"], to = ["user_requirement"] }
69
71
 
70
72
  """
71
73
  config.write_text(head + model + tail, encoding="utf-8")
72
- for prefix, folder, title in (
73
- ("INT", "intents", "Intents"),
74
- ("NG", "non-goals", "Non-goals"),
75
- ("UR", "user-requirements", "User requirements"),
76
- ("SR", "system-requirements", "System requirements"),
74
+ # tl 6 makes a register with the item type it holds (tl SR-0351).
75
+ for prefix, folder, title, type_ in (
76
+ ("INT", "intents", "Intents", "intent"),
77
+ ("NG", "non-goals", "Non-goals", "non_goal"),
78
+ ("UR", "user-requirements", "User requirements", "user_requirement"),
79
+ ("SR", "system-requirements", "System requirements", "system_requirement"),
77
80
  ):
78
- _tl(root, "register", "new", prefix, folder, "--title", title)
81
+ _tl(root, "register", "new", prefix, folder, "--title", title, "--type", type_)
79
82
 
80
83
 
81
84
  def _new(root: Path, prefix: str, type_: str, title: str, text: str, **kw: str) -> str:
@@ -108,7 +111,8 @@ def plain_graph(tmp_path_factory: pytest.TempPathFactory) -> Path:
108
111
  _tl(root, "link", sr2, sr1, "--type", "relates")
109
112
  _tl(root, "link", sr3, sr1, "--type", "refines")
110
113
  _tl(root, "amend", sr1, "--rationale", "Because a second renderer drifts. Rejected: writing it here.")
111
- _tl(root, "check", "--strict")
114
+ # Sound, not signed: tl 6's --strict also refuses an unsigned item.
115
+ _tl(root, "check")
112
116
  return root
113
117
 
114
118
 
@@ -125,7 +129,7 @@ def composed_graph(tmp_path_factory: pytest.TempPathFactory, plain_graph: Path)
125
129
  ur = _new(root, "UR", "user_requirement", "Cite a clause", "One requirement satisfies a borrowed clause.", ground=intent, ground_type="derives_from")
126
130
  sr = _new(root, "SR", "system_requirement", "Satisfies the source", "It does what the clause says.", ground=ur, ground_type="implements", attr_priority="must")
127
131
  _tl(root, "link", sr, "src:SR-0001", "--type", "satisfies", compose=True)
128
- _tl(root, "check", "--strict", compose=True)
132
+ _tl(root, "check", compose=True)
129
133
  return root
130
134
 
131
135
 
@@ -142,3 +146,19 @@ def git_graph(tmp_path_factory: pytest.TempPathFactory, plain_graph: Path) -> Pa
142
146
  git("add", ".")
143
147
  git("commit", "-q", "-m", "fixture")
144
148
  return repo / "idd"
149
+
150
+
151
+ def born(root: Path) -> str:
152
+ """The status the fixture graph's tl gave its items at birth: ``draft`` before
153
+ tl 6, ``proposed`` from it. Read from an item, so the suite runs on either."""
154
+ for line in (root / "system-requirements" / "SR-0001.yml").read_text(encoding="utf-8").splitlines():
155
+ if line.startswith("status:"):
156
+ return line.split(":", 1)[1].strip()
157
+ raise AssertionError("SR-0001 has no status")
158
+
159
+
160
+ def every(root: Path) -> str:
161
+ """The filter that selects every item, in the language the graph declares."""
162
+ with open(root / "throughline.toml", "rb") as fh:
163
+ project = tomllib.load(fh).get("project", {})
164
+ return "TRUE" if project.get("filter_language") == "gql" else "True"
@@ -13,6 +13,8 @@ from pathlib import Path
13
13
 
14
14
  import pytest
15
15
 
16
+ from conftest import born, every
17
+
16
18
  from throughline_transform import markdown as md
17
19
  from throughline_transform.blocks import as_blocks
18
20
  from throughline_transform.cli import main, produce
@@ -84,7 +86,7 @@ def test_markdown_is_written_by_the_tool(plain_graph: Path):
84
86
 
85
87
  def test_markdown_keeps_markers_when_asked(plain_graph: Path):
86
88
  _, text = _md(plain_graph, markers=True)
87
- assert "<!-- tl:catalog True -->" in text and "<!-- tl:end -->" in text
89
+ assert f"<!-- tl:catalog {every(plain_graph)} -->" in text and "<!-- tl:end -->" in text
88
90
 
89
91
 
90
92
  def test_markdown_options_change_the_document(plain_graph: Path):
@@ -115,7 +117,7 @@ def test_blocks_read_the_shape_of_the_tools_output(plain_graph: Path):
115
117
  items = [b for b in blocks if b.item]
116
118
  assert len(items) == 7
117
119
  sr1 = next(b for b in items if b.item["uid"] == "SR-0001")
118
- assert sr1.heading == 4 and sr1.item["status"] == "draft"
120
+ assert sr1.heading == 4 and sr1.item["status"] == born(plain_graph)
119
121
  assert 'a colon, "quotes" & <angles>' in sr1.text
120
122
  quotes = [b for b in blocks if b.quote]
121
123
  assert any("The tool writes the Markdown." in b.text for b in quotes)
@@ -234,11 +236,11 @@ def test_notes_are_one_per_item_with_front_matter_and_links(plain_graph: Path):
234
236
  assert "System requirements/SR-0001.md" in entries and "Intents/INT-0001.md" in entries
235
237
  sr2 = entries["System requirements/SR-0002.md"].decode()
236
238
  assert sr2.startswith('---\nuid: "SR-0002"\n')
237
- assert 'priority: "should"' in sr2 and ' - "type/system_requirement"' in sr2 and ' - "status/draft"' in sr2
239
+ assert 'priority: "should"' in sr2 and ' - "type/system_requirement"' in sr2 and f' - "status/{born(plain_graph)}"' in sr2
238
240
  # The body is the tool's block reshaped for a note (SR-0009): a heading,
239
241
  # the type and status beneath, no attribute line, the incoming links.
240
242
  body = sr2.split("\n---\n", 1)[1]
241
- assert body.startswith("# SR-0002 — Declare it in \\[\\[sources\\]\\]\nsystem requirement · draft\n")
243
+ assert body.startswith(f"# SR-0002 — Declare it in \\[\\[sources\\]\\]\nsystem requirement · {born(plain_graph)}\n")
242
244
  assert "**priority**" not in body and "**origin**" not in body
243
245
  assert "*Relates:* [[SR-0001]]" in sr2
244
246
  assert "*Implements:* [[UR-0002]]" in sr2
@@ -13,6 +13,8 @@ from pathlib import Path
13
13
 
14
14
  import pytest
15
15
 
16
+ from conftest import born
17
+
16
18
  from throughline_transform import project
17
19
  from throughline_transform.cli import main
18
20
  from throughline_transform.provenance import CLEAN, DIRTY, UNTRACKED, stated
@@ -31,7 +33,7 @@ def test_blocks_output_is_the_documents_structure(plain_graph: Path, tmp_path: P
31
33
  items = [b for b in blocks if "item" in b]
32
34
  assert len(items) == 7
33
35
  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"
36
+ assert sr1["heading"] == 4 and sr1["item"]["type"] == "system_requirement" and sr1["item"]["status"] == born(plain_graph)
35
37
  assert any(b.get("quote") for b in blocks) and any(b.get("small") for b in blocks)
36
38
  assert any(b.get("group") and b["text"] == "System requirements" for b in blocks)
37
39
  assert any("table" in b for b in blocks) # --body both carries the table of items
@@ -1,133 +0,0 @@
1
- # Copyright (c) 2026 Henry J Grech-Cini
2
- # SPDX-License-Identifier: Apache-2.0
3
- """The graph handed to an assistant that reads a few files and cannot run tl
4
- (UR-0008, SR-0017, SR-0018).
5
-
6
- Such an assistant — Microsoft 365 Copilot in a controlled environment reads at
7
- most fifty files, runs no command and returns only text — has to read the whole
8
- graph from a handful of files and be told, in those files, how to send changes
9
- back. This form is a folder: one file per register, each carrying that
10
- register's items exactly as ``tl dump`` gives them, fingerprint included, and a
11
- manifest that says what the export was true of, which file holds which
12
- register, which tl wrote it, and the change-set form ``tl apply`` accepts —
13
- taken from the tool, never written here, so it cannot drift from what apply
14
- reads. One file per register because the assistant's cap counts files, not
15
- items; a folder rather than an archive because an assistant cannot open one.
16
-
17
- Nothing of an item is reshaped or computed here (NG-0001): the words and the
18
- fingerprint are the dump's. What this module adds is the file boundaries, the
19
- wrapping, and the manifest.
20
- """
21
-
22
- from __future__ import annotations
23
-
24
- import json
25
- from typing import Any
26
-
27
- from .model import prefix_of
28
- from .package import Entry, utf8
29
- from .provenance import Provenance
30
-
31
- #: How each file is written: JSON, or Markdown holding one fenced JSON block for
32
- #: an assistant that will not read a ``.json`` file.
33
- WRAPS = ("json", "md")
34
-
35
- #: The version of this form, stated in the manifest.
36
- FORM_VERSION = 1
37
-
38
- MANIFEST = "manifest"
39
-
40
- #: What the manifest tells the assistant to do, beside the form it must write.
41
- INSTRUCTION = (
42
- "Read every file named under \"files\" before you answer — each has the same "
43
- "extension as this manifest: together they are the whole graph as it stood at "
44
- "the commit named under \"provenance\". Send changes "
45
- "back as one change set in the form given under \"change_set_format\", quoting "
46
- "each item's \"fingerprint\" exactly as these files give it. Never send a "
47
- "rewritten item file, and never a file at all: a change set is text, and the "
48
- "person who gave you this folder will apply it."
49
- )
50
-
51
-
52
- def _json(data: dict[str, Any]) -> str:
53
- return json.dumps(data, indent=2, ensure_ascii=False) + "\n"
54
-
55
-
56
- def _entry(name: str, title: str, data: dict[str, Any], wrap: str, after: str = "") -> Entry:
57
- """One file of the folder: the JSON itself, or Markdown holding it in one
58
- fenced block, with ``after`` — Markdown of its own — following the block."""
59
- text = _json(data)
60
- if wrap == "json":
61
- return (f"{name}.json", utf8(text))
62
- body = f"# {title}\n\n```json\n{text}```\n"
63
- if after:
64
- body += f"\n{after}"
65
- return (f"{name}.md", utf8(body))
66
-
67
-
68
- def to_assistant(
69
- dump: dict[str, Any],
70
- provenance: Provenance,
71
- change_set_format: str,
72
- *,
73
- wrap: str = "json",
74
- only: tuple[str, ...] = (),
75
- ) -> list[Entry]:
76
- """The folder's files, the manifest first.
77
-
78
- ``dump`` is ``tl dump``'s document, unreshaped; ``change_set_format`` is what
79
- ``tl apply --describe`` printed. With ``only``, the register files hold the
80
- items named and the clauses they cite, and the manifest says how many of how
81
- many, as every narrowed output does (SR-0016).
82
- """
83
- if wrap not in WRAPS:
84
- raise ValueError(f"wrap must be one of {', '.join(WRAPS)}, not {wrap!r}")
85
- items: list[dict[str, Any]] = list(dump.get("items") or [])
86
- if only:
87
- keep = set(only)
88
- own = [i for i in items if not i.get("source") and i["uid"] in keep]
89
- cited = {link["target"] for i in own for link in i.get("links") or []}
90
- items = own + [i for i in items if i.get("source") and i["uid"] in cited]
91
- registers: list[dict[str, Any]] = list(dump.get("registers") or [])
92
- by_register: dict[str, list[dict[str, Any]]] = {r["prefix"]: [] for r in registers}
93
- borrowed: dict[str, list[dict[str, Any]]] = {}
94
- for item in items:
95
- if item.get("source"):
96
- borrowed.setdefault(str(item["source"]), []).append(item)
97
- else:
98
- by_register.setdefault(prefix_of(item["uid"]), []).append(item)
99
-
100
- files: list[dict[str, Any]] = []
101
- entries: list[Entry] = []
102
- for register in registers:
103
- prefix = register["prefix"]
104
- title = register.get("title") or prefix
105
- held = by_register.get(prefix, [])
106
- entries.append(_entry(prefix, f"{title} ({prefix})", {"register": register, "items": held}, wrap))
107
- files.append({"file": prefix, "register": prefix, "title": title, "items": len(held)})
108
- for namespace, clauses in sorted(borrowed.items()):
109
- name = f"source-{namespace}"
110
- entries.append(
111
- _entry(name, f"Clauses of the adopted source {namespace}", {"source": namespace, "items": clauses}, wrap)
112
- )
113
- files.append({"file": name, "source": namespace, "items": len(clauses)})
114
-
115
- meta = dump.get("throughline_dump") or {}
116
- # The manifest is the same in either wrapping, so a file is named by its stem:
117
- # the reader holds the files, and sees their kind.
118
- manifest: dict[str, Any] = {
119
- "throughline_assistant_form": FORM_VERSION,
120
- "provenance": provenance.record(),
121
- "provenance_lines": provenance.lines(),
122
- "tl": str(meta.get("tool_version") or "?"),
123
- "dump_schema_version": meta.get("dump_schema_version"),
124
- "files": files,
125
- "config": dump.get("config") or {},
126
- }
127
- if dump.get("composition"):
128
- manifest["composition"] = dump["composition"]
129
- manifest["instruction"] = INSTRUCTION
130
- manifest["change_set_format"] = change_set_format
131
- readable = f"## How to answer\n\n{INSTRUCTION}\n\n{change_set_format}" if wrap == "md" else ""
132
- entries.insert(0, _entry(MANIFEST, "Manifest", manifest, wrap, readable))
133
- return entries
@@ -1,4 +0,0 @@
1
- throughline>=3.18.0
2
-
3
- [dev]
4
- pytest>=8.0
@@ -1,149 +0,0 @@
1
- # Copyright (c) 2026 Henry J Grech-Cini
2
- # SPDX-License-Identifier: Apache-2.0
3
- """The assistant form (UR-0008, SR-0017, SR-0018): one file per register, each
4
- carrying the register's items exactly as ``tl dump`` gives them, and a manifest
5
- that says what the folder was true of and how to answer."""
6
-
7
- from __future__ import annotations
8
-
9
- import json
10
- import re
11
- import subprocess
12
- import sys
13
- from pathlib import Path
14
-
15
- from throughline_transform.assistant import FORM_VERSION, INSTRUCTION, to_assistant
16
- from throughline_transform.cli import main
17
- from throughline_transform.project import change_set_format, load, run
18
- from throughline_transform.provenance import CLEAN, Provenance, provenance_of
19
-
20
- PROV = Provenance(repository="example/fixture", ref="main", commit="0" * 40, tree=CLEAN, tool="tl 2.2.0")
21
- FENCE = re.compile(r"^```json\n(.*?)^```\n", re.S | re.M)
22
-
23
-
24
- def _dump(root: Path) -> dict:
25
- return json.loads(run(root, ["dump"], False))
26
-
27
-
28
- def _folder(root: Path, out: Path, *extra: str) -> dict[str, str]:
29
- assert main(["assistant", "-C", str(root), "-o", str(out), *extra]) == 0
30
- assert out.is_dir() and not out.with_suffix(".zip").exists()
31
- return {p.name: p.read_text(encoding="utf-8") for p in sorted(out.iterdir())}
32
-
33
-
34
- def _block(text: str) -> dict:
35
- blocks = FENCE.findall(text)
36
- assert len(blocks) == 1, "one fenced JSON block per file"
37
- return json.loads(blocks[0])
38
-
39
-
40
- # --- SR-0017: one file per register, the dump's items unreshaped ----------------
41
-
42
-
43
- def test_the_folder_holds_one_file_per_register_and_the_manifest(plain_graph: Path, tmp_path: Path):
44
- files = _folder(plain_graph, tmp_path / "form")
45
- dump = _dump(plain_graph)
46
- prefixes = [r["prefix"] for r in dump["registers"]]
47
- assert sorted(files) == sorted([f"{p}.json" for p in prefixes] + ["manifest.json"])
48
- seen = []
49
- for prefix in prefixes:
50
- data = json.loads(files[f"{prefix}.json"])
51
- assert data["register"]["prefix"] == prefix
52
- for item in data["items"]:
53
- assert item["uid"].startswith(prefix + "-")
54
- seen.append(item)
55
- # every item, and every link on it, appears exactly once and unchanged
56
- assert sorted(seen, key=lambda i: i["uid"]) == dump["items"]
57
- assert all("fingerprint" in item for item in seen)
58
-
59
-
60
- def test_md_wrapping_holds_the_same_content_in_one_fenced_block(plain_graph: Path, tmp_path: Path):
61
- as_json = _folder(plain_graph, tmp_path / "json")
62
- as_md = _folder(plain_graph, tmp_path / "md", "--wrap", "md")
63
- assert sorted(as_md) == sorted(n.replace(".json", ".md") for n in as_json)
64
- for name, text in as_json.items():
65
- assert _block(as_md[name.replace(".json", ".md")]) == json.loads(text)
66
- # the manifest's Markdown also states the form in words the assistant can read
67
- assert "## How to answer" in as_md["manifest.md"] and "`tl apply` accepts" in as_md["manifest.md"]
68
-
69
-
70
- def test_a_composed_graph_lends_its_clauses_in_a_file_of_their_source(composed_graph: Path, tmp_path: Path):
71
- files = _folder(composed_graph, tmp_path / "form")
72
- dump = json.loads(run(composed_graph, ["dump"], True))
73
- assert "source-src.json" in files
74
- clauses = json.loads(files["source-src.json"])["items"]
75
- assert [c["uid"] for c in clauses] == [i["uid"] for i in dump["items"] if i.get("source")]
76
- own = [i for name, text in files.items() if name not in ("manifest.json", "source-src.json")
77
- for i in json.loads(text)["items"]]
78
- assert sorted(i["uid"] for i in own) == sorted(i["uid"] for i in dump["items"] if not i.get("source"))
79
- manifest = json.loads(files["manifest.json"])
80
- assert any(f.get("source") == "src" for f in manifest["files"])
81
- assert manifest["composition"]["sources"][0]["namespace"] == "src"
82
-
83
-
84
- def test_only_narrows_the_files_and_the_manifest_says_so(plain_graph: Path, tmp_path: Path):
85
- graph = load(plain_graph)
86
- sr1 = graph.by_register["SR"][0].uid
87
- files = _folder(plain_graph, tmp_path / "form", "--only", sr1)
88
- held = [i["uid"] for name, text in files.items() if name != "manifest.json" for i in json.loads(text)["items"]]
89
- assert held == [sr1]
90
- manifest = json.loads(files["manifest.json"])
91
- assert manifest["provenance"]["items"] == f"1 of {len(graph.items)}"
92
-
93
-
94
- def test_the_form_is_a_folder_never_an_archive(plain_graph: Path, tmp_path: Path):
95
- out = tmp_path / "form"
96
- assert main(["assistant", "-C", str(plain_graph), "-o", str(out), "--folder"]) == 0
97
- assert out.is_dir()
98
- assert main(["assistant", "-C", str(plain_graph), "-o", str(tmp_path / "again")]) == 0
99
- assert (tmp_path / "again").is_dir() and not list(tmp_path.glob("*.zip"))
100
-
101
-
102
- def test_the_same_graph_gives_the_same_bytes(plain_graph: Path, tmp_path: Path):
103
- first = _folder(plain_graph, tmp_path / "a", "--repository", "x/y", "--ref", "main", "--commit", "0" * 40, "--tree", "clean")
104
- second = _folder(plain_graph, tmp_path / "b", "--repository", "x/y", "--ref", "main", "--commit", "0" * 40, "--tree", "clean")
105
- assert first == second
106
-
107
-
108
- # --- SR-0018: the manifest -------------------------------------------------------
109
-
110
-
111
- def test_the_manifest_names_what_the_folder_was_true_of_and_how_to_answer(git_graph: Path, tmp_path: Path):
112
- files = _folder(git_graph, tmp_path / "form")
113
- manifest = json.loads(files["manifest.json"])
114
- expected = provenance_of(git_graph, "x")
115
- assert manifest["throughline_assistant_form"] == FORM_VERSION
116
- assert manifest["provenance"]["repository"] == expected.repository == "example/fixture"
117
- assert manifest["provenance"]["ref"] == expected.ref
118
- assert manifest["provenance"]["commit"] == expected.commit and len(expected.commit) == 40
119
- assert manifest["provenance"]["tree"] == expected.tree
120
- assert manifest["tl"] == load(git_graph).tool_version
121
- assert {f["register"] for f in manifest["files"]} == {r.prefix for r in load(git_graph).registers}
122
- assert all((tmp_path / "form" / f"{f['file']}.json").is_file() for f in manifest["files"])
123
- assert manifest["instruction"] == INSTRUCTION
124
- assert "fingerprint" in manifest["instruction"] and "change set" in manifest["instruction"]
125
- # the form is the tool's own words, taken from the command, never written here
126
- assert manifest["change_set_format"] == change_set_format(git_graph, False)
127
- described = subprocess.run([str(Path(sys.executable).parent / "tl"), "apply", "--describe"],
128
- capture_output=True, text=True, encoding="utf-8")
129
- assert manifest["change_set_format"] == described.stdout
130
- assert '"op": "amend"' in manifest["change_set_format"]
131
- assert "config" in manifest and "grounding" in manifest["config"]
132
-
133
-
134
- def test_a_stated_provenance_is_written_as_given(plain_graph: Path, tmp_path: Path):
135
- files = _folder(plain_graph, tmp_path / "form", "--repository", "octo/graph", "--ref", "main",
136
- "--commit", "f" * 40, "--tree", "dirty")
137
- manifest = json.loads(files["manifest.json"])
138
- assert manifest["provenance"] == {"repository": "octo/graph", "ref": "main", "commit": "f" * 40,
139
- "tree": "uncommitted changes", "tool": manifest["provenance"]["tool"]}
140
- assert "Working tree: uncommitted changes" in manifest["provenance_lines"]
141
-
142
-
143
- def test_the_writer_reshapes_nothing(plain_graph: Path):
144
- dump = _dump(plain_graph)
145
- entries = dict(to_assistant(dump, PROV, "THE FORM"))
146
- assert set(entries) == {f"{r['prefix']}.json" for r in dump["registers"]} | {"manifest.json"}
147
- items = [i for name, data in entries.items() if name != "manifest.json" for i in json.loads(data)["items"]]
148
- assert sorted(items, key=lambda i: i["uid"]) == dump["items"]
149
- assert json.loads(entries["manifest.json"])["change_set_format"] == "THE FORM"