throughline-transform 0.4.1__tar.gz → 0.6.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (34) hide show
  1. {throughline_transform-0.4.1 → throughline_transform-0.6.0}/LICENSE +1 -1
  2. {throughline_transform-0.4.1 → throughline_transform-0.6.0}/NOTICE +3 -3
  3. {throughline_transform-0.4.1/src/throughline_transform.egg-info → throughline_transform-0.6.0}/PKG-INFO +14 -6
  4. {throughline_transform-0.4.1 → throughline_transform-0.6.0}/README.md +12 -4
  5. {throughline_transform-0.4.1 → throughline_transform-0.6.0}/pyproject.toml +6 -6
  6. throughline_transform-0.6.0/src/throughline_transform/assistant.py +133 -0
  7. {throughline_transform-0.4.1 → throughline_transform-0.6.0}/src/throughline_transform/cli.py +59 -13
  8. {throughline_transform-0.4.1 → throughline_transform-0.6.0}/src/throughline_transform/markdown.py +23 -5
  9. {throughline_transform-0.4.1 → throughline_transform-0.6.0}/src/throughline_transform/model.py +26 -2
  10. {throughline_transform-0.4.1 → throughline_transform-0.6.0}/src/throughline_transform/project.py +8 -0
  11. {throughline_transform-0.4.1 → throughline_transform-0.6.0}/src/throughline_transform/provenance.py +16 -2
  12. {throughline_transform-0.4.1 → throughline_transform-0.6.0}/src/throughline_transform/tables.py +6 -1
  13. {throughline_transform-0.4.1 → throughline_transform-0.6.0/src/throughline_transform.egg-info}/PKG-INFO +14 -6
  14. {throughline_transform-0.4.1 → throughline_transform-0.6.0}/src/throughline_transform.egg-info/SOURCES.txt +3 -0
  15. throughline_transform-0.6.0/src/throughline_transform.egg-info/requires.txt +4 -0
  16. throughline_transform-0.6.0/tests/test_assistant.py +149 -0
  17. throughline_transform-0.6.0/tests/test_only.py +150 -0
  18. throughline_transform-0.4.1/src/throughline_transform.egg-info/requires.txt +0 -4
  19. {throughline_transform-0.4.1 → throughline_transform-0.6.0}/MANIFEST.in +0 -0
  20. {throughline_transform-0.4.1 → throughline_transform-0.6.0}/setup.cfg +0 -0
  21. {throughline_transform-0.4.1 → throughline_transform-0.6.0}/src/throughline_transform/__init__.py +0 -0
  22. {throughline_transform-0.4.1 → throughline_transform-0.6.0}/src/throughline_transform/blocks.py +0 -0
  23. {throughline_transform-0.4.1 → throughline_transform-0.6.0}/src/throughline_transform/html.py +0 -0
  24. {throughline_transform-0.4.1 → throughline_transform-0.6.0}/src/throughline_transform/notes.py +0 -0
  25. {throughline_transform-0.4.1 → throughline_transform-0.6.0}/src/throughline_transform/office.py +0 -0
  26. {throughline_transform-0.4.1 → throughline_transform-0.6.0}/src/throughline_transform/package.py +0 -0
  27. {throughline_transform-0.4.1 → throughline_transform-0.6.0}/src/throughline_transform/progress.py +0 -0
  28. {throughline_transform-0.4.1 → throughline_transform-0.6.0}/src/throughline_transform/shape.py +0 -0
  29. {throughline_transform-0.4.1 → throughline_transform-0.6.0}/src/throughline_transform.egg-info/dependency_links.txt +0 -0
  30. {throughline_transform-0.4.1 → throughline_transform-0.6.0}/src/throughline_transform.egg-info/entry_points.txt +0 -0
  31. {throughline_transform-0.4.1 → throughline_transform-0.6.0}/src/throughline_transform.egg-info/top_level.txt +0 -0
  32. {throughline_transform-0.4.1 → throughline_transform-0.6.0}/tests/conftest.py +0 -0
  33. {throughline_transform-0.4.1 → throughline_transform-0.6.0}/tests/test_outputs.py +0 -0
  34. {throughline_transform-0.4.1 → throughline_transform-0.6.0}/tests/test_surface.py +0 -0
@@ -186,7 +186,7 @@
186
186
  same "printed page" as the copyright notice for easier
187
187
  identification within third-party archives.
188
188
 
189
- Copyright 2026 The throughline-ratify authors
189
+ Copyright 2026 The throughline-transform authors
190
190
 
191
191
  Licensed under the Apache License, Version 2.0 (the "License");
192
192
  you may not use this file except in compliance with the License.
@@ -7,6 +7,6 @@ This product includes software developed by Henry J Grech-Cini.
7
7
  Licensed under the Apache License, Version 2.0. See the LICENSE file for the
8
8
  full terms.
9
9
 
10
- throughline-transform is a full-screen terminal companion for
11
- throughline (the `tl` CLI) and throughline-compose (`tl-compose`). It builds
12
- on their public Python APIs; no third-party source code was copied.
10
+ throughline-transform is a command-line companion for throughline (the `tl`
11
+ CLI). It builds on throughline's published command line; no third-party source
12
+ code was copied.
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: throughline-transform
3
- Version: 0.4.1
3
+ Version: 0.6.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
@@ -21,7 +21,7 @@ Requires-Python: >=3.11
21
21
  Description-Content-Type: text/markdown
22
22
  License-File: LICENSE
23
23
  License-File: NOTICE
24
- Requires-Dist: throughline>=3.11.1
24
+ Requires-Dist: throughline>=3.18.0
25
25
  Provides-Extra: dev
26
26
  Requires-Dist: pytest>=8.0; extra == "dev"
27
27
  Dynamic: license-file
@@ -41,6 +41,7 @@ tl-transform csv -C idd # one row per item, a links file, a file
41
41
  tl-transform xlsx -C idd # the same as a read-only workbook that still sorts and filters
42
42
  tl-transform docx -C idd # a Word document: title page, contents, a heading per item
43
43
  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
44
45
  ```
45
46
 
46
47
  It is the command-line half of the
@@ -71,8 +72,7 @@ Office formats, which are written from their own specifications.
71
72
 
72
73
  Every graph is read through `tl`, which composes a graph that declares
73
74
  `[[sources]]` itself, so a borrowed clause is written with the reference number
74
- a conformance document exists to carry; `tl-compose` is a second name for the
75
- same program.
75
+ a conformance document exists to carry.
76
76
  The tool is found beside this package's interpreter first and on the path
77
77
  second, and is run as a command — its command line is the surface it publishes.
78
78
 
@@ -86,6 +86,7 @@ second, and is run as a command — its command line is the surface it publishes
86
86
  | `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
87
  | `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
88
  | `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. |
89
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
@@ -95,6 +96,13 @@ knows them without git — the editor holds them from its clone — states them
95
96
  `--repository`, `--ref`, `--commit` and `--tree clean|dirty|untracked`, and git
96
97
  is then not consulted.
97
98
 
99
+ `--only UID[,UID…]`, given once or more, narrows any format to the items it
100
+ names: the catalogue, table and matrices hold only those, the tables only their
101
+ rows and the links between them, the notes only their notes, and the clauses
102
+ mirrored are only the ones they cite. The output then says `Items: n of N`,
103
+ because a partial document read as a whole one misleads. An identifier the
104
+ graph does not hold is a usage error (exit 2), and nothing is written.
105
+
98
106
  A quick run is silent. When a step — reading the graph, asking the tool to
99
107
  write the document, writing the file — has run for a second, one line on
100
108
  stderr says which, because a composed graph fetching its sources for the first
@@ -117,8 +125,8 @@ clause of the tool it reads (`satisfies: tl:SR-0111`) and have the citation
117
125
  resolved rather than asserted.
118
126
 
119
127
  ```bash
120
- tl-compose -C idd check --strict # the grounding gate
121
- tl-compose -C idd docs --check # idd/docs/spec.md must match the graph
128
+ tl -C idd check --strict # the grounding gate
129
+ tl -C idd docs --check # idd/docs/spec.md must match the graph
122
130
  tl-transform html -C idd # and the tool over its own graph
123
131
  ```
124
132
 
@@ -13,6 +13,7 @@ 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
16
17
  ```
17
18
 
18
19
  It is the command-line half of the
@@ -43,8 +44,7 @@ Office formats, which are written from their own specifications.
43
44
 
44
45
  Every graph is read through `tl`, which composes a graph that declares
45
46
  `[[sources]]` itself, so a borrowed clause is written with the reference number
46
- a conformance document exists to carry; `tl-compose` is a second name for the
47
- same program.
47
+ a conformance document exists to carry.
48
48
  The tool is found beside this package's interpreter first and on the path
49
49
  second, and is run as a command — its command line is the surface it publishes.
50
50
 
@@ -58,6 +58,7 @@ second, and is run as a command — its command line is the surface it publishes
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
+ | `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. |
61
62
  | `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. |
62
63
 
63
64
  Every output carries the repository, ref, commit, working-tree state and tool
@@ -67,6 +68,13 @@ knows them without git — the editor holds them from its clone — states them
67
68
  `--repository`, `--ref`, `--commit` and `--tree clean|dirty|untracked`, and git
68
69
  is then not consulted.
69
70
 
71
+ `--only UID[,UID…]`, given once or more, narrows any format to the items it
72
+ names: the catalogue, table and matrices hold only those, the tables only their
73
+ rows and the links between them, the notes only their notes, and the clauses
74
+ mirrored are only the ones they cite. The output then says `Items: n of N`,
75
+ because a partial document read as a whole one misleads. An identifier the
76
+ graph does not hold is a usage error (exit 2), and nothing is written.
77
+
70
78
  A quick run is silent. When a step — reading the graph, asking the tool to
71
79
  write the document, writing the file — has run for a second, one line on
72
80
  stderr says which, because a composed graph fetching its sources for the first
@@ -89,8 +97,8 @@ clause of the tool it reads (`satisfies: tl:SR-0111`) and have the citation
89
97
  resolved rather than asserted.
90
98
 
91
99
  ```bash
92
- tl-compose -C idd check --strict # the grounding gate
93
- tl-compose -C idd docs --check # idd/docs/spec.md must match the graph
100
+ tl -C idd check --strict # the grounding gate
101
+ tl -C idd docs --check # idd/docs/spec.md must match the graph
94
102
  tl-transform html -C idd # and the tool over its own graph
95
103
  ```
96
104
 
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
4
4
 
5
5
  [project]
6
6
  name = "throughline-transform"
7
- version = "0.4.1"
7
+ version = "0.6.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"
@@ -37,11 +37,11 @@ classifiers = [
37
37
  ]
38
38
  # The prose of every output is the tool's own: this package asks `tl docs` for the
39
39
  # Markdown and `tl dump` for the structure, and writes nothing of an item itself
40
- # (SR-0002). `tl:catalog` and `tl:sourced` as they are rendered from 2.2.0 and
41
- # 0.16.1 are the shapes this package reads (SR-0003); it was written against those
42
- # releases and the floors say so. compose 0.16.1 requires throughline 2.2.0, so the
43
- # two floors are one fact stated at both ends.
44
- dependencies = ["throughline>=3.11.1"] # composition is the Tool's own since 3.11.1 (throughline UR-0037); tl-compose is a second name for tl
40
+ # (SR-0002). `tl:catalog` and `tl:sourced` are the shapes this package reads
41
+ # (SR-0003). It was written against throughline 2.2.0 and throughline-compose
42
+ # 0.16.1; since 3.11.1 composition is the Tool's own (throughline UR-0037), `tl`
43
+ # 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)
45
45
 
46
46
  [project.optional-dependencies]
47
47
  dev = ["pytest>=8.0"]
@@ -0,0 +1,133 @@
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
@@ -9,9 +9,11 @@
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]
12
13
 
13
14
  Any format takes --repository, --ref, --commit and --tree to state the
14
- provenance instead of reading git (SR-0013).
15
+ provenance instead of reading git (SR-0013), and --only UID[,UID…] to hold
16
+ only the items named, saying how many of how many it holds (SR-0016).
15
17
 
16
18
  Exit codes: 0 written · 1 the tool or the file system refused · 2 usage.
17
19
  """
@@ -20,26 +22,29 @@ from __future__ import annotations
20
22
 
21
23
  import argparse
22
24
  import sys
23
- from dataclasses import asdict, replace
25
+ from dataclasses import replace
24
26
  from pathlib import Path
25
27
 
26
28
  from throughline.version import distribution_version as _v
27
29
 
28
30
  from . import markdown as md
29
31
  from .blocks import as_blocks, to_json
32
+ from .assistant import WRAPS, to_assistant
30
33
  from .html import to_html
31
- from .model import Graph, register_titles, source_titles
34
+ from .model import Graph, narrowed, register_titles, source_titles
32
35
  from .notes import to_notes
33
36
  from .office import to_docx, to_xlsx
34
37
  from .package import Entry, archive, unpack, utf8
35
38
  from .progress import slow
36
- from .project import TransformError, find_graph, load
39
+ from .project import TransformError, change_set_format, find_graph, load
37
40
  from .provenance import TREE_WORDS, Provenance, provenance_of, stated
38
41
  from .tables import Table, cited_sources, file_name, links_of, per_register, to_csv, whole_graph
39
42
 
40
- FORMATS = ("md", "notes", "csv", "xlsx", "docx", "html", "blocks")
43
+ FORMATS = ("md", "notes", "csv", "xlsx", "docx", "html", "blocks", "assistant")
41
44
  PROSE = ("md", "docx", "html", "blocks")
42
- FOLDERS = ("notes", "csv")
45
+ FOLDERS = ("notes", "csv", "assistant")
46
+ #: Always a folder, never an archive: an assistant cannot open one (SR-0017).
47
+ FOLDER_ONLY = ("assistant",)
43
48
 
44
49
 
45
50
  def version_string() -> str:
@@ -65,6 +70,12 @@ def build_parser() -> argparse.ArgumentParser:
65
70
  p.add_argument("--matrix", action="store_true", help="md, docx, html, blocks: add a traceability matrix per grounding link")
66
71
  p.add_argument("--no-stats", dest="stats", action="store_false", help="md, docx, html, blocks: leave out the tool's summary")
67
72
  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
+ )
68
79
  p.add_argument("--repository", metavar="OWNER/NAME", help="state the repository instead of reading git")
69
80
  p.add_argument("--ref", metavar="REF", help="state the ref instead of reading git")
70
81
  p.add_argument("--commit", metavar="SHA", help="state the commit instead of reading git")
@@ -79,12 +90,29 @@ def build_parser() -> argparse.ArgumentParser:
79
90
  default="one",
80
91
  help="csv, xlsx: one table of everything, or one per register",
81
92
  )
93
+ p.add_argument(
94
+ "--only",
95
+ action="append",
96
+ metavar="UID[,UID…]",
97
+ help="any format: hold only these items, and say so; may be given more than once",
98
+ )
82
99
  return p
83
100
 
84
101
 
85
- def _tables(graph: Graph, split: str) -> tuple[list[Table], Table, list[Table]]:
86
- tables = per_register(graph) if split == "per-register" else [whole_graph(graph)]
87
- return tables, links_of(tables), cited_sources(graph)
102
+ def named(values: list[str] | None) -> tuple[str, ...]:
103
+ """The identifiers --only names, once each, in the order given (SR-0016)."""
104
+ seen: dict[str, None] = {}
105
+ for value in values or []:
106
+ for uid in value.split(","):
107
+ if uid.strip():
108
+ seen.setdefault(uid.strip(), None)
109
+ return tuple(seen)
110
+
111
+
112
+ def _tables(graph: Graph, split: str, only: tuple[str, ...] = ()) -> tuple[list[Table], Table, list[Table]]:
113
+ held = narrowed(graph, only) if only else graph
114
+ tables = per_register(held) if split == "per-register" else [whole_graph(held)]
115
+ return tables, links_of(tables, narrowed=bool(only)), cited_sources(held)
88
116
 
89
117
 
90
118
  def _about(provenance: Provenance, extra: list[list[str]] | None = None) -> Table:
@@ -103,16 +131,22 @@ def produce(graph: Graph, root: Path, fmt: str, opts: md.Options, provenance: Pr
103
131
  if fmt == "docx":
104
132
  return to_docx(blocks), f"{stem}.docx"
105
133
  if fmt == "blocks":
106
- return utf8(to_json(blocks, provenance.lines(), asdict(provenance))), f"{stem}-blocks.json"
134
+ return utf8(to_json(blocks, provenance.lines(), provenance.record())), f"{stem}-blocks.json"
107
135
  return utf8(to_html(blocks, provenance)), f"{stem}.html"
108
136
 
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
+
109
143
  if fmt == "notes":
110
144
  text = md.to_markdown(
111
145
  root, graph, replace(opts, body="catalog", matrix=False, stats=False, markers=False), provenance
112
146
  )
113
147
  return to_notes(text, graph, provenance), f"{stem}-notes"
114
148
 
115
- tables, links, sources = _tables(graph, opts.split)
149
+ tables, links, sources = _tables(graph, opts.split, opts.only)
116
150
  if fmt == "xlsx":
117
151
  return to_xlsx([*tables, links, *sources, _about(provenance)]), f"{stem}.xlsx"
118
152
 
@@ -148,10 +182,20 @@ def main(argv: list[str] | None = None) -> int:
148
182
  args = parser.parse_args(argv)
149
183
  if args.folder and args.format not in FOLDERS:
150
184
  parser.error(f"--folder applies to {' and '.join(FOLDERS)}, not {args.format}")
151
- opts = md.Options(body=args.body, matrix=args.matrix, stats=args.stats, markers=args.markers, split=args.split)
185
+ only = named(args.only)
186
+ if args.only is not None and not only:
187
+ 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
+ )
152
191
  try:
153
192
  root = find_graph(args.directory)
154
193
  graph = load(root)
194
+ # SR-0016: an item asked for and not held is the caller's mistake, said
195
+ # before anything is written rather than a document quietly without it.
196
+ missing = [uid for uid in only if uid not in graph.items]
197
+ if missing:
198
+ parser.error(f"--only names what the graph does not hold: {', '.join(missing)}")
155
199
  # UR-0003: the tool that produced the output, named as tl-ratify names itself —
156
200
  # this package first, then the throughline that read the graph. The dump
157
201
  # records throughline's bare distribution version.
@@ -161,9 +205,11 @@ def main(argv: list[str] | None = None) -> int:
161
205
  if any((args.repository, args.ref, args.commit, args.tree))
162
206
  else provenance_of(root, producer)
163
207
  )
208
+ if only:
209
+ provenance = replace(provenance, items=f"{len(only)} of {len(graph.items)}")
164
210
  result, default = produce(graph, root, args.format, opts, provenance)
165
211
  with slow(f"still writing {args.output or default}…"):
166
- target = write(result, default, args.output, args.folder)
212
+ target = write(result, default, args.output, args.folder or args.format in FOLDER_ONLY)
167
213
  except (TransformError, OSError, ValueError) as exc:
168
214
  print(f"tl-transform: {exc}", file=sys.stderr)
169
215
  return 1
@@ -31,12 +31,30 @@ 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
+ #: The items the output holds, where the caller named them (SR-0016);
38
+ #: empty for every item.
39
+ only: tuple[str, ...] = ()
34
40
 
35
41
 
36
42
  def _region(directive: str) -> str:
37
43
  return f"<!-- tl:{directive} -->\n<!-- tl:end -->"
38
44
 
39
45
 
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).
48
+
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).
51
+ """
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}])"
56
+
57
+
40
58
  def directive_document(graph: Graph, opts: Options, provenance: Provenance) -> str:
41
59
  """The document the tool is asked to fill."""
42
60
  lines: list[str] = [f"# {provenance.repository} — requirements", ""]
@@ -44,9 +62,9 @@ def directive_document(graph: Graph, opts: Options, provenance: Provenance) -> s
44
62
  lines.append("")
45
63
 
46
64
  if opts.stats:
47
- lines += ["## Summary", "", _region("stats True"), ""]
65
+ lines += ["## Summary", "", _region(f"stats {_within('True', opts)}"), ""]
48
66
  if opts.body in ("table", "both"):
49
- lines += ["## Items", "", _region("table True"), ""]
67
+ lines += ["## Items", "", _region(f"table {_within('True', opts)}"), ""]
50
68
  if opts.matrix:
51
69
  # One matrix per grounding link type the graph declares, each over the
52
70
  # items something actually reaches by that link. Over every item a
@@ -56,16 +74,16 @@ def directive_document(graph: Graph, opts: Options, provenance: Provenance) -> s
56
74
  lines += [
57
75
  f"### {link_type.replace('_', ' ')}",
58
76
  "",
59
- _region(f"matrix incoming:{link_type} links.incoming('{link_type}')"),
77
+ _region(f"matrix incoming:{link_type} {_within(f'links.incoming({link_type!r})', opts)}"),
60
78
  "",
61
79
  ]
62
80
  if opts.body in ("catalog", "both"):
63
- lines += ["## Every item", "", _region("catalog True"), ""]
81
+ lines += ["## Every item", "", _region(f"catalog {_within('True', opts)}"), ""]
64
82
  # The words every cited clause answers to. Only over a composed graph: the
65
83
  # directive is the composer's, and a graph adopting no source has nothing
66
84
  # to mirror.
67
85
  if graph.composed:
68
- lines += ["## Clauses of adopted sources", "", _region("sourced True"), ""]
86
+ lines += ["## Clauses of adopted sources", "", _region(f"sourced {_within('True', opts)}"), ""]
69
87
  return "\n".join(lines)
70
88
 
71
89
 
@@ -9,7 +9,8 @@ is not a rule — it is the same edges read the other way.
9
9
 
10
10
  from __future__ import annotations
11
11
 
12
- from dataclasses import dataclass, field
12
+ from collections.abc import Iterable
13
+ from dataclasses import dataclass, field, replace
13
14
  from typing import Any
14
15
 
15
16
 
@@ -31,7 +32,7 @@ class Item:
31
32
  normative: bool | None = None
32
33
  links: list[Link] = field(default_factory=list)
33
34
  attrs: dict[str, Any] = field(default_factory=dict)
34
- #: The namespace a borrowed item came from, as ``tl-compose dump`` states it.
35
+ #: The namespace a borrowed item came from, as ``tl dump`` states it.
35
36
  #: ``None`` on the graph's own items.
36
37
  source: str | None = None
37
38
 
@@ -71,6 +72,9 @@ class Graph:
71
72
  #: What the tool called itself in the dump.
72
73
  tool_version: str
73
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)
74
78
 
75
79
 
76
80
  def prefix_of(uid: str) -> str:
@@ -148,6 +152,7 @@ def index(dump: dict[str, Any], composed: bool) -> Graph:
148
152
  sources=sources,
149
153
  tool_version=str(meta.get("tool_version") or "?"),
150
154
  composed=composed,
155
+ raw=dump,
151
156
  )
152
157
 
153
158
 
@@ -169,3 +174,22 @@ def source_titles(graph: Graph) -> dict[str, str]:
169
174
  parts = [s.url or s.path or "", f"at {s.ref}" if s.ref else "", f"in {s.subdir}/" if s.subdir else ""]
170
175
  out[s.namespace] = " ".join(p for p in parts if p)
171
176
  return out
177
+
178
+
179
+ def narrowed(graph: Graph, only: Iterable[str]) -> Graph:
180
+ """The graph holding only the named items of its own (SR-0016).
181
+
182
+ Its registers, sources and clauses stay as they are: a clause is cited or
183
+ not by what is kept, and the writers already ask only for what is cited.
184
+ An edge from an item left out is not an edge of what is held.
185
+ """
186
+ keep = set(only)
187
+ return replace(
188
+ graph,
189
+ items={uid: item for uid, item in graph.items.items() if uid in keep},
190
+ by_register={prefix: [i for i in items if i.uid in keep] for prefix, items in graph.by_register.items()},
191
+ incoming={
192
+ target: [(source, kind) for source, kind in edges if source in keep]
193
+ for target, edges in graph.incoming.items()
194
+ },
195
+ )
@@ -141,6 +141,14 @@ 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
+
144
152
  def docs(root: Path, document: str, composed: bool) -> str:
145
153
  """Hand the tool a document of directives and read back what it wrote.
146
154
 
@@ -13,7 +13,7 @@ from __future__ import annotations
13
13
 
14
14
  import re
15
15
  import subprocess
16
- from dataclasses import dataclass
16
+ from dataclasses import asdict, dataclass
17
17
  from pathlib import Path
18
18
 
19
19
  CLEAN = "clean"
@@ -31,15 +31,29 @@ class Provenance:
31
31
  commit: str
32
32
  tree: str
33
33
  tool: str
34
+ #: How many of the graph's items the output holds, where the caller named
35
+ #: them (SR-0016) — "2 of 7". Empty for an output of every item, which then
36
+ #: says nothing more than it always did.
37
+ items: str = ""
34
38
 
35
39
  def lines(self) -> list[str]:
36
- return [
40
+ lines = [
37
41
  f"Repository: {self.repository}",
38
42
  f"Ref: {self.ref or 'none'}",
39
43
  f"Commit: {self.commit or 'none'}",
40
44
  f"Working tree: {self.tree}",
41
45
  f"Produced by: {self.tool}",
42
46
  ]
47
+ if self.items:
48
+ lines.append(f"Items: {self.items}")
49
+ return lines
50
+
51
+ def record(self) -> dict[str, str]:
52
+ """The fields as data, for the blocks output; ``items`` only where a selection was made."""
53
+ fields = asdict(self)
54
+ if not self.items:
55
+ del fields["items"]
56
+ return fields
43
57
 
44
58
  @property
45
59
  def stem(self) -> str:
@@ -121,12 +121,15 @@ def cited_sources(graph: Graph) -> list[Table]:
121
121
  ]
122
122
 
123
123
 
124
- def links_of(tables: list[Table]) -> Table:
124
+ def links_of(tables: list[Table], narrowed: bool = False) -> Table:
125
125
  """Every link as a row of its own (SR-0006).
126
126
 
127
127
  The item tables are read, not the graph: the links table names each end by
128
128
  the sheet its row is on in this export, which depends on how the export was
129
129
  split. A link into an adopted source names the namespace as the sheet.
130
+ Where the export holds only the items its caller named, a link to one of
131
+ the graph's own items left out is not given: both ends of every link are
132
+ in the export (SR-0016).
130
133
  """
131
134
  sheet_of: dict[str, str] = {}
132
135
  for table in tables:
@@ -144,6 +147,8 @@ def links_of(tables: list[Table]) -> Table:
144
147
  continue
145
148
  for target in row[c].split(", "):
146
149
  home = sheet_of.get(target)
150
+ if narrowed and home is None and not is_borrowed(target):
151
+ continue
147
152
  to_sheet = home if home is not None else (target.split(":")[0] if ":" in target else "")
148
153
  rows.append([table.name, source, link_type, to_sheet, target])
149
154
  return Table(name=LINKS_TABLE, columns=list(LINK_COLUMNS), rows=rows)
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: throughline-transform
3
- Version: 0.4.1
3
+ Version: 0.6.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
@@ -21,7 +21,7 @@ Requires-Python: >=3.11
21
21
  Description-Content-Type: text/markdown
22
22
  License-File: LICENSE
23
23
  License-File: NOTICE
24
- Requires-Dist: throughline>=3.11.1
24
+ Requires-Dist: throughline>=3.18.0
25
25
  Provides-Extra: dev
26
26
  Requires-Dist: pytest>=8.0; extra == "dev"
27
27
  Dynamic: license-file
@@ -41,6 +41,7 @@ tl-transform csv -C idd # one row per item, a links file, a file
41
41
  tl-transform xlsx -C idd # the same as a read-only workbook that still sorts and filters
42
42
  tl-transform docx -C idd # a Word document: title page, contents, a heading per item
43
43
  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
44
45
  ```
45
46
 
46
47
  It is the command-line half of the
@@ -71,8 +72,7 @@ Office formats, which are written from their own specifications.
71
72
 
72
73
  Every graph is read through `tl`, which composes a graph that declares
73
74
  `[[sources]]` itself, so a borrowed clause is written with the reference number
74
- a conformance document exists to carry; `tl-compose` is a second name for the
75
- same program.
75
+ a conformance document exists to carry.
76
76
  The tool is found beside this package's interpreter first and on the path
77
77
  second, and is run as a command — its command line is the surface it publishes.
78
78
 
@@ -86,6 +86,7 @@ second, and is run as a command — its command line is the surface it publishes
86
86
  | `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
87
  | `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
88
  | `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. |
89
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
@@ -95,6 +96,13 @@ knows them without git — the editor holds them from its clone — states them
95
96
  `--repository`, `--ref`, `--commit` and `--tree clean|dirty|untracked`, and git
96
97
  is then not consulted.
97
98
 
99
+ `--only UID[,UID…]`, given once or more, narrows any format to the items it
100
+ names: the catalogue, table and matrices hold only those, the tables only their
101
+ rows and the links between them, the notes only their notes, and the clauses
102
+ mirrored are only the ones they cite. The output then says `Items: n of N`,
103
+ because a partial document read as a whole one misleads. An identifier the
104
+ graph does not hold is a usage error (exit 2), and nothing is written.
105
+
98
106
  A quick run is silent. When a step — reading the graph, asking the tool to
99
107
  write the document, writing the file — has run for a second, one line on
100
108
  stderr says which, because a composed graph fetching its sources for the first
@@ -117,8 +125,8 @@ clause of the tool it reads (`satisfies: tl:SR-0111`) and have the citation
117
125
  resolved rather than asserted.
118
126
 
119
127
  ```bash
120
- tl-compose -C idd check --strict # the grounding gate
121
- tl-compose -C idd docs --check # idd/docs/spec.md must match the graph
128
+ tl -C idd check --strict # the grounding gate
129
+ tl -C idd docs --check # idd/docs/spec.md must match the graph
122
130
  tl-transform html -C idd # and the tool over its own graph
123
131
  ```
124
132
 
@@ -4,6 +4,7 @@ NOTICE
4
4
  README.md
5
5
  pyproject.toml
6
6
  src/throughline_transform/__init__.py
7
+ src/throughline_transform/assistant.py
7
8
  src/throughline_transform/blocks.py
8
9
  src/throughline_transform/cli.py
9
10
  src/throughline_transform/html.py
@@ -24,5 +25,7 @@ src/throughline_transform.egg-info/entry_points.txt
24
25
  src/throughline_transform.egg-info/requires.txt
25
26
  src/throughline_transform.egg-info/top_level.txt
26
27
  tests/conftest.py
28
+ tests/test_assistant.py
29
+ tests/test_only.py
27
30
  tests/test_outputs.py
28
31
  tests/test_surface.py
@@ -0,0 +1,4 @@
1
+ throughline>=3.18.0
2
+
3
+ [dev]
4
+ pytest>=8.0
@@ -0,0 +1,149 @@
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"
@@ -0,0 +1,150 @@
1
+ # Copyright (c) 2026 Henry J Grech-Cini
2
+ # SPDX-License-Identifier: Apache-2.0
3
+ """An output of only the items its caller names (UR-0007, SR-0016).
4
+
5
+ The plain fixture holds seven items. Two are named here, UR-0002 and SR-0002,
6
+ in two --only flags: SR-0002 implements UR-0002, so exactly one link has both
7
+ ends in the output, while SR-0002 also relates to SR-0001, UR-0002 derives from
8
+ INT-0001 and SR-0003 implements UR-0002 — three links with one end left out.
9
+ """
10
+
11
+ from __future__ import annotations
12
+
13
+ import csv
14
+ import io
15
+ import json
16
+ import re
17
+ import zipfile
18
+ from pathlib import Path
19
+
20
+ import pytest
21
+
22
+ from throughline_transform.cli import main
23
+
24
+ ONLY = ["--only", "UR-0002", "--only", "SR-0002"]
25
+ HELD = {"UR-0002", "SR-0002"}
26
+
27
+
28
+ def _rows(data: bytes) -> list[list[str]]:
29
+ return list(csv.reader(io.StringIO(data.decode("utf-8"))))
30
+
31
+
32
+ def test_the_markdown_holds_the_named_items_and_says_so(plain_graph: Path, tmp_path: Path):
33
+ out = tmp_path / "only.md"
34
+ assert main(["md", "-C", str(plain_graph), "-o", str(out), "--matrix", "--body", "both", *ONLY]) == 0
35
+ text = out.read_text(encoding="utf-8")
36
+ assert "- Items: 2 of 7" in text
37
+ # Written by tl docs, catalogue and table alike: the two named, and no other.
38
+ assert set(re.findall(r"^\*\*([A-Z]+-\d{4}) — ", text, re.M)) == HELD
39
+ table = text.split("## Items", 1)[1].split("##", 1)[0]
40
+ assert set(re.findall(r"^\| ([A-Z]+-\d{4}) \|", table, re.M)) == HELD
41
+ # Each matrix has rows only for what is held: UR-0002's realizers, and no intent.
42
+ implements = text.split("### implements", 1)[1].split("##", 1)[0]
43
+ assert set(re.findall(r"^\| ([A-Z]+-\d{4}) \|", implements, re.M)) == {"UR-0002"}
44
+ derives = text.split("### derives from", 1)[1].split("##", 1)[0]
45
+ assert re.findall(r"^\| ([A-Z]+-\d{4}) \|", derives, re.M) == []
46
+ assert "- **Items:** 2 — " in text
47
+
48
+
49
+ def test_the_tables_hold_the_named_rows_and_only_the_links_between_them(plain_graph: Path, tmp_path: Path):
50
+ target = tmp_path / "csv"
51
+ assert main(["csv", "-C", str(plain_graph), "-o", str(target), "--folder", *ONLY]) == 0
52
+ items = _rows((target / "All items.csv").read_bytes())
53
+ assert {row[0] for row in items[1:]} == HELD
54
+ links = _rows((target / "links.csv").read_bytes())
55
+ assert links[1:] == [["All items", "SR-0002", "implements", "All items", "UR-0002"]]
56
+ about = dict(tuple(row) for row in _rows((target / "about-this-export.csv").read_bytes())[1:])
57
+ assert about["Items"] == "2 of 7"
58
+
59
+ split = tmp_path / "split"
60
+ assert main(["csv", "-C", str(plain_graph), "-o", str(split), "--folder", "--split", "per-register", *ONLY]) == 0
61
+ # A register holding nothing named is no table at all.
62
+ assert sorted(p.name for p in split.iterdir()) == [
63
+ "System requirements.csv", "User requirements.csv", "about-this-export.csv", "links.csv",
64
+ ]
65
+ assert _rows((split / "links.csv").read_bytes())[1:] == [
66
+ ["System requirements", "SR-0002", "implements", "User requirements", "UR-0002"],
67
+ ]
68
+
69
+
70
+ def test_the_workbook_holds_two_item_rows_and_one_link(plain_graph: Path, tmp_path: Path):
71
+ out = tmp_path / "only.xlsx"
72
+ assert main(["xlsx", "-C", str(plain_graph), "-o", str(out), *ONLY]) == 0
73
+ with zipfile.ZipFile(out) as zf:
74
+ workbook = zf.read("xl/workbook.xml").decode()
75
+ names = re.findall(r'<sheet name="([^"]+)"', workbook)
76
+ sheets = {name: zf.read(f"xl/worksheets/sheet{i + 1}.xml").decode() for i, name in enumerate(names)}
77
+ # A header row, then one row per item or link.
78
+ assert sheets["All items"].count("<row ") == 3
79
+ assert sheets["Links"].count("<row ") == 2
80
+ # The workbook writes its strings inline, so the About sheet reads as written.
81
+ assert ">Items</t>" in sheets["About this export"] and ">2 of 7</t>" in sheets["About this export"]
82
+
83
+
84
+ def test_the_notes_hold_the_named_items_and_link_to_nothing_left_out(plain_graph: Path, tmp_path: Path):
85
+ target = tmp_path / "vault"
86
+ assert main(["notes", "-C", str(plain_graph), "-o", str(target), "--folder", *ONLY]) == 0
87
+ notes = sorted(str(p.relative_to(target)) for p in target.rglob("*.md"))
88
+ assert notes == ["About this export.md", "System requirements/SR-0002.md", "User requirements/UR-0002.md"]
89
+ for path in notes:
90
+ body = (target / path).read_text(encoding="utf-8").split("\n---\n", 1)[-1]
91
+ for linked in re.findall(r"(?<!\\)\[\[([^\]|]+)", body):
92
+ assert linked in HELD, f"{path} links to {linked}"
93
+ sr2 = (target / "System requirements/SR-0002.md").read_text(encoding="utf-8")
94
+ assert "*Implements:* [[UR-0002]]" in sr2 and "*Relates:* SR-0001" in sr2
95
+ ur2 = (target / "User requirements/UR-0002.md").read_text(encoding="utf-8")
96
+ assert "*Implements this:* [[SR-0002]]" in ur2 and "SR-0003" not in ur2
97
+ about = (target / "About this export.md").read_text(encoding="utf-8")
98
+ assert "- Items: 2 of 7" in about and "This export holds 2 items." in about
99
+
100
+
101
+ def test_the_blocks_and_documents_say_what_they_hold(plain_graph: Path, tmp_path: Path):
102
+ out = tmp_path / "only.json"
103
+ assert main(["blocks", "-C", str(plain_graph), "-o", str(out), *ONLY]) == 0
104
+ doc = json.loads(out.read_text(encoding="utf-8"))
105
+ assert doc["provenance"]["items"] == "2 of 7"
106
+ assert doc["provenance_lines"][-1] == "Items: 2 of 7"
107
+ assert {b["item"]["uid"] for b in doc["blocks"] if "item" in b} == HELD
108
+ for fmt in ("docx", "html"):
109
+ target = tmp_path / f"only.{fmt}"
110
+ assert main([fmt, "-C", str(plain_graph), "-o", str(target), *ONLY]) == 0
111
+ data = target.read_bytes()
112
+ text = zipfile.ZipFile(io.BytesIO(data)).read("word/document.xml").decode() if fmt == "docx" else data.decode()
113
+ assert "Items: 2 of 7" in text
114
+ assert "SR-0002" in text and "SR-0003" not in text
115
+
116
+
117
+ def test_a_composed_output_mirrors_only_what_the_named_items_cite(composed_graph: Path, tmp_path: Path):
118
+ citing = tmp_path / "citing.md"
119
+ assert main(["md", "-C", str(composed_graph), "-o", str(citing), "--only", "SR-0001"]) == 0
120
+ assert "**src:SR-0001 — " in citing.read_text(encoding="utf-8")
121
+ other = tmp_path / "other.md"
122
+ assert main(["md", "-C", str(composed_graph), "-o", str(other), "--only", "UR-0001"]) == 0
123
+ assert "**src:SR-0001 — " not in other.read_text(encoding="utf-8")
124
+ target = tmp_path / "csv"
125
+ assert main(["csv", "-C", str(composed_graph), "-o", str(target), "--folder", "--only", "UR-0001"]) == 0
126
+ assert not (target / "src.csv").exists()
127
+
128
+
129
+ def test_an_identifier_the_graph_lacks_is_refused_and_nothing_is_written(
130
+ plain_graph: Path, tmp_path: Path, capsys: pytest.CaptureFixture
131
+ ):
132
+ out = tmp_path / "never.md"
133
+ with pytest.raises(SystemExit) as exc:
134
+ main(["md", "-C", str(plain_graph), "-o", str(out), "--only", "SR-0002,SR-0099,NOPE-1"])
135
+ assert exc.value.code == 2
136
+ assert "SR-0099, NOPE-1" in capsys.readouterr().err
137
+ assert not out.exists()
138
+ with pytest.raises(SystemExit) as exc:
139
+ main(["md", "-C", str(plain_graph), "-o", str(out), "--only", " , "])
140
+ assert exc.value.code == 2
141
+ assert not out.exists()
142
+
143
+
144
+ def test_named_nothing_an_output_says_nothing_more(plain_graph: Path, tmp_path: Path):
145
+ out = tmp_path / "all.json"
146
+ assert main(["blocks", "-C", str(plain_graph), "-o", str(out)]) == 0
147
+ doc = json.loads(out.read_text(encoding="utf-8"))
148
+ assert "items" not in doc["provenance"]
149
+ assert not any(line.startswith("Items:") for line in doc["provenance_lines"])
150
+ assert len([b for b in doc["blocks"] if "item" in b]) == 7
@@ -1,4 +0,0 @@
1
- throughline>=3.11.1
2
-
3
- [dev]
4
- pytest>=8.0