throughline-transform 0.4.0__tar.gz → 0.5.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 (31) hide show
  1. {throughline_transform-0.4.0 → throughline_transform-0.5.0}/LICENSE +1 -1
  2. {throughline_transform-0.4.0 → throughline_transform-0.5.0}/NOTICE +3 -3
  3. {throughline_transform-0.4.0/src/throughline_transform.egg-info → throughline_transform-0.5.0}/PKG-INFO +11 -5
  4. {throughline_transform-0.4.0 → throughline_transform-0.5.0}/README.md +10 -4
  5. {throughline_transform-0.4.0 → throughline_transform-0.5.0}/pyproject.toml +6 -6
  6. {throughline_transform-0.4.0 → throughline_transform-0.5.0}/src/throughline_transform/cli.py +43 -11
  7. {throughline_transform-0.4.0 → throughline_transform-0.5.0}/src/throughline_transform/markdown.py +20 -5
  8. {throughline_transform-0.4.0 → throughline_transform-0.5.0}/src/throughline_transform/model.py +22 -2
  9. {throughline_transform-0.4.0 → throughline_transform-0.5.0}/src/throughline_transform/provenance.py +16 -2
  10. {throughline_transform-0.4.0 → throughline_transform-0.5.0}/src/throughline_transform/tables.py +6 -1
  11. {throughline_transform-0.4.0 → throughline_transform-0.5.0/src/throughline_transform.egg-info}/PKG-INFO +11 -5
  12. {throughline_transform-0.4.0 → throughline_transform-0.5.0}/src/throughline_transform.egg-info/SOURCES.txt +1 -0
  13. throughline_transform-0.5.0/tests/test_only.py +150 -0
  14. {throughline_transform-0.4.0 → throughline_transform-0.5.0}/tests/test_outputs.py +9 -0
  15. {throughline_transform-0.4.0 → throughline_transform-0.5.0}/MANIFEST.in +0 -0
  16. {throughline_transform-0.4.0 → throughline_transform-0.5.0}/setup.cfg +0 -0
  17. {throughline_transform-0.4.0 → throughline_transform-0.5.0}/src/throughline_transform/__init__.py +0 -0
  18. {throughline_transform-0.4.0 → throughline_transform-0.5.0}/src/throughline_transform/blocks.py +0 -0
  19. {throughline_transform-0.4.0 → throughline_transform-0.5.0}/src/throughline_transform/html.py +0 -0
  20. {throughline_transform-0.4.0 → throughline_transform-0.5.0}/src/throughline_transform/notes.py +0 -0
  21. {throughline_transform-0.4.0 → throughline_transform-0.5.0}/src/throughline_transform/office.py +0 -0
  22. {throughline_transform-0.4.0 → throughline_transform-0.5.0}/src/throughline_transform/package.py +0 -0
  23. {throughline_transform-0.4.0 → throughline_transform-0.5.0}/src/throughline_transform/progress.py +0 -0
  24. {throughline_transform-0.4.0 → throughline_transform-0.5.0}/src/throughline_transform/project.py +0 -0
  25. {throughline_transform-0.4.0 → throughline_transform-0.5.0}/src/throughline_transform/shape.py +0 -0
  26. {throughline_transform-0.4.0 → throughline_transform-0.5.0}/src/throughline_transform.egg-info/dependency_links.txt +0 -0
  27. {throughline_transform-0.4.0 → throughline_transform-0.5.0}/src/throughline_transform.egg-info/entry_points.txt +0 -0
  28. {throughline_transform-0.4.0 → throughline_transform-0.5.0}/src/throughline_transform.egg-info/requires.txt +0 -0
  29. {throughline_transform-0.4.0 → throughline_transform-0.5.0}/src/throughline_transform.egg-info/top_level.txt +0 -0
  30. {throughline_transform-0.4.0 → throughline_transform-0.5.0}/tests/conftest.py +0 -0
  31. {throughline_transform-0.4.0 → throughline_transform-0.5.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.0
3
+ Version: 0.5.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
@@ -71,8 +71,7 @@ Office formats, which are written from their own specifications.
71
71
 
72
72
  Every graph is read through `tl`, which composes a graph that declares
73
73
  `[[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.
74
+ a conformance document exists to carry.
76
75
  The tool is found beside this package's interpreter first and on the path
77
76
  second, and is run as a command — its command line is the surface it publishes.
78
77
 
@@ -95,6 +94,13 @@ knows them without git — the editor holds them from its clone — states them
95
94
  `--repository`, `--ref`, `--commit` and `--tree clean|dirty|untracked`, and git
96
95
  is then not consulted.
97
96
 
97
+ `--only UID[,UID…]`, given once or more, narrows any format to the items it
98
+ names: the catalogue, table and matrices hold only those, the tables only their
99
+ rows and the links between them, the notes only their notes, and the clauses
100
+ mirrored are only the ones they cite. The output then says `Items: n of N`,
101
+ because a partial document read as a whole one misleads. An identifier the
102
+ graph does not hold is a usage error (exit 2), and nothing is written.
103
+
98
104
  A quick run is silent. When a step — reading the graph, asking the tool to
99
105
  write the document, writing the file — has run for a second, one line on
100
106
  stderr says which, because a composed graph fetching its sources for the first
@@ -117,8 +123,8 @@ clause of the tool it reads (`satisfies: tl:SR-0111`) and have the citation
117
123
  resolved rather than asserted.
118
124
 
119
125
  ```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
126
+ tl -C idd check --strict # the grounding gate
127
+ tl -C idd docs --check # idd/docs/spec.md must match the graph
122
128
  tl-transform html -C idd # and the tool over its own graph
123
129
  ```
124
130
 
@@ -43,8 +43,7 @@ Office formats, which are written from their own specifications.
43
43
 
44
44
  Every graph is read through `tl`, which composes a graph that declares
45
45
  `[[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.
46
+ a conformance document exists to carry.
48
47
  The tool is found beside this package's interpreter first and on the path
49
48
  second, and is run as a command — its command line is the surface it publishes.
50
49
 
@@ -67,6 +66,13 @@ knows them without git — the editor holds them from its clone — states them
67
66
  `--repository`, `--ref`, `--commit` and `--tree clean|dirty|untracked`, and git
68
67
  is then not consulted.
69
68
 
69
+ `--only UID[,UID…]`, given once or more, narrows any format to the items it
70
+ names: the catalogue, table and matrices hold only those, the tables only their
71
+ rows and the links between them, the notes only their notes, and the clauses
72
+ mirrored are only the ones they cite. The output then says `Items: n of N`,
73
+ because a partial document read as a whole one misleads. An identifier the
74
+ graph does not hold is a usage error (exit 2), and nothing is written.
75
+
70
76
  A quick run is silent. When a step — reading the graph, asking the tool to
71
77
  write the document, writing the file — has run for a second, one line on
72
78
  stderr says which, because a composed graph fetching its sources for the first
@@ -89,8 +95,8 @@ clause of the tool it reads (`satisfies: tl:SR-0111`) and have the citation
89
95
  resolved rather than asserted.
90
96
 
91
97
  ```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
98
+ tl -C idd check --strict # the grounding gate
99
+ tl -C idd docs --check # idd/docs/spec.md must match the graph
94
100
  tl-transform html -C idd # and the tool over its own graph
95
101
  ```
96
102
 
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
4
4
 
5
5
  [project]
6
6
  name = "throughline-transform"
7
- version = "0.4.0"
7
+ version = "0.5.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.11.1"] # composition is the Tool's own since 3.11.1 (throughline UR-0037)
45
45
 
46
46
  [project.optional-dependencies]
47
47
  dev = ["pytest>=8.0"]
@@ -11,7 +11,8 @@
11
11
  tl-transform blocks [-C DIR] [-o FILE] [--body …] [--matrix] [--no-stats]
12
12
 
13
13
  Any format takes --repository, --ref, --commit and --tree to state the
14
- provenance instead of reading git (SR-0013).
14
+ provenance instead of reading git (SR-0013), and --only UID[,UID…] to hold
15
+ only the items named, saying how many of how many it holds (SR-0016).
15
16
 
16
17
  Exit codes: 0 written · 1 the tool or the file system refused · 2 usage.
17
18
  """
@@ -20,7 +21,7 @@ from __future__ import annotations
20
21
 
21
22
  import argparse
22
23
  import sys
23
- from dataclasses import asdict, replace
24
+ from dataclasses import replace
24
25
  from pathlib import Path
25
26
 
26
27
  from throughline.version import distribution_version as _v
@@ -28,7 +29,7 @@ from throughline.version import distribution_version as _v
28
29
  from . import markdown as md
29
30
  from .blocks import as_blocks, to_json
30
31
  from .html import to_html
31
- from .model import Graph, register_titles, source_titles
32
+ from .model import Graph, narrowed, register_titles, source_titles
32
33
  from .notes import to_notes
33
34
  from .office import to_docx, to_xlsx
34
35
  from .package import Entry, archive, unpack, utf8
@@ -79,12 +80,29 @@ def build_parser() -> argparse.ArgumentParser:
79
80
  default="one",
80
81
  help="csv, xlsx: one table of everything, or one per register",
81
82
  )
83
+ p.add_argument(
84
+ "--only",
85
+ action="append",
86
+ metavar="UID[,UID…]",
87
+ help="any format: hold only these items, and say so; may be given more than once",
88
+ )
82
89
  return p
83
90
 
84
91
 
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)
92
+ def named(values: list[str] | None) -> tuple[str, ...]:
93
+ """The identifiers --only names, once each, in the order given (SR-0016)."""
94
+ seen: dict[str, None] = {}
95
+ for value in values or []:
96
+ for uid in value.split(","):
97
+ if uid.strip():
98
+ seen.setdefault(uid.strip(), None)
99
+ return tuple(seen)
100
+
101
+
102
+ def _tables(graph: Graph, split: str, only: tuple[str, ...] = ()) -> tuple[list[Table], Table, list[Table]]:
103
+ held = narrowed(graph, only) if only else graph
104
+ tables = per_register(held) if split == "per-register" else [whole_graph(held)]
105
+ return tables, links_of(tables, narrowed=bool(only)), cited_sources(held)
88
106
 
89
107
 
90
108
  def _about(provenance: Provenance, extra: list[list[str]] | None = None) -> Table:
@@ -103,7 +121,7 @@ def produce(graph: Graph, root: Path, fmt: str, opts: md.Options, provenance: Pr
103
121
  if fmt == "docx":
104
122
  return to_docx(blocks), f"{stem}.docx"
105
123
  if fmt == "blocks":
106
- return utf8(to_json(blocks, provenance.lines(), asdict(provenance))), f"{stem}-blocks.json"
124
+ return utf8(to_json(blocks, provenance.lines(), provenance.record())), f"{stem}-blocks.json"
107
125
  return utf8(to_html(blocks, provenance)), f"{stem}.html"
108
126
 
109
127
  if fmt == "notes":
@@ -112,7 +130,7 @@ def produce(graph: Graph, root: Path, fmt: str, opts: md.Options, provenance: Pr
112
130
  )
113
131
  return to_notes(text, graph, provenance), f"{stem}-notes"
114
132
 
115
- tables, links, sources = _tables(graph, opts.split)
133
+ tables, links, sources = _tables(graph, opts.split, opts.only)
116
134
  if fmt == "xlsx":
117
135
  return to_xlsx([*tables, links, *sources, _about(provenance)]), f"{stem}.xlsx"
118
136
 
@@ -148,15 +166,29 @@ def main(argv: list[str] | None = None) -> int:
148
166
  args = parser.parse_args(argv)
149
167
  if args.folder and args.format not in FOLDERS:
150
168
  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)
169
+ only = named(args.only)
170
+ if args.only is not None and not only:
171
+ parser.error("--only names no item")
172
+ opts = md.Options(body=args.body, matrix=args.matrix, stats=args.stats, markers=args.markers, split=args.split, only=only)
152
173
  try:
153
174
  root = find_graph(args.directory)
154
175
  graph = load(root)
176
+ # SR-0016: an item asked for and not held is the caller's mistake, said
177
+ # before anything is written rather than a document quietly without it.
178
+ missing = [uid for uid in only if uid not in graph.items]
179
+ if missing:
180
+ parser.error(f"--only names what the graph does not hold: {', '.join(missing)}")
181
+ # UR-0003: the tool that produced the output, named as tl-ratify names itself —
182
+ # this package first, then the throughline that read the graph. The dump
183
+ # records throughline's bare distribution version.
184
+ producer = f"throughline-transform {_v('throughline-transform')} (throughline {graph.tool_version})"
155
185
  provenance = (
156
- stated(graph.tool_version, args.repository, args.ref, args.commit, args.tree)
186
+ stated(producer, args.repository, args.ref, args.commit, args.tree)
157
187
  if any((args.repository, args.ref, args.commit, args.tree))
158
- else provenance_of(root, graph.tool_version)
188
+ else provenance_of(root, producer)
159
189
  )
190
+ if only:
191
+ provenance = replace(provenance, items=f"{len(only)} of {len(graph.items)}")
160
192
  result, default = produce(graph, root, args.format, opts, provenance)
161
193
  with slow(f"still writing {args.output or default}…"):
162
194
  target = write(result, default, args.output, args.folder)
@@ -31,12 +31,27 @@ 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
+ #: The items the output holds, where the caller named them (SR-0016);
35
+ #: empty for every item.
36
+ only: tuple[str, ...] = ()
34
37
 
35
38
 
36
39
  def _region(directive: str) -> str:
37
40
  return f"<!-- tl:{directive} -->\n<!-- tl:end -->"
38
41
 
39
42
 
43
+ def _within(expression: str, opts: Options) -> str:
44
+ """A directive's filter, joined with the items named, so tl docs writes only those (SR-0016).
45
+
46
+ The identifiers are ones the graph holds (the command refuses any other), so
47
+ each is written as a quoted literal the filter language reads (tl:SR-0045).
48
+ """
49
+ if not opts.only:
50
+ return expression
51
+ named = ", ".join(repr(uid) for uid in opts.only)
52
+ return f"({expression}) and (uid in [{named}])"
53
+
54
+
40
55
  def directive_document(graph: Graph, opts: Options, provenance: Provenance) -> str:
41
56
  """The document the tool is asked to fill."""
42
57
  lines: list[str] = [f"# {provenance.repository} — requirements", ""]
@@ -44,9 +59,9 @@ def directive_document(graph: Graph, opts: Options, provenance: Provenance) -> s
44
59
  lines.append("")
45
60
 
46
61
  if opts.stats:
47
- lines += ["## Summary", "", _region("stats True"), ""]
62
+ lines += ["## Summary", "", _region(f"stats {_within('True', opts)}"), ""]
48
63
  if opts.body in ("table", "both"):
49
- lines += ["## Items", "", _region("table True"), ""]
64
+ lines += ["## Items", "", _region(f"table {_within('True', opts)}"), ""]
50
65
  if opts.matrix:
51
66
  # One matrix per grounding link type the graph declares, each over the
52
67
  # items something actually reaches by that link. Over every item a
@@ -56,16 +71,16 @@ def directive_document(graph: Graph, opts: Options, provenance: Provenance) -> s
56
71
  lines += [
57
72
  f"### {link_type.replace('_', ' ')}",
58
73
  "",
59
- _region(f"matrix incoming:{link_type} links.incoming('{link_type}')"),
74
+ _region(f"matrix incoming:{link_type} {_within(f'links.incoming({link_type!r})', opts)}"),
60
75
  "",
61
76
  ]
62
77
  if opts.body in ("catalog", "both"):
63
- lines += ["## Every item", "", _region("catalog True"), ""]
78
+ lines += ["## Every item", "", _region(f"catalog {_within('True', opts)}"), ""]
64
79
  # The words every cited clause answers to. Only over a composed graph: the
65
80
  # directive is the composer's, and a graph adopting no source has nothing
66
81
  # to mirror.
67
82
  if graph.composed:
68
- lines += ["## Clauses of adopted sources", "", _region("sourced True"), ""]
83
+ lines += ["## Clauses of adopted sources", "", _region(f"sourced {_within('True', opts)}"), ""]
69
84
  return "\n".join(lines)
70
85
 
71
86
 
@@ -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
 
@@ -169,3 +170,22 @@ def source_titles(graph: Graph) -> dict[str, str]:
169
170
  parts = [s.url or s.path or "", f"at {s.ref}" if s.ref else "", f"in {s.subdir}/" if s.subdir else ""]
170
171
  out[s.namespace] = " ".join(p for p in parts if p)
171
172
  return out
173
+
174
+
175
+ def narrowed(graph: Graph, only: Iterable[str]) -> Graph:
176
+ """The graph holding only the named items of its own (SR-0016).
177
+
178
+ Its registers, sources and clauses stay as they are: a clause is cited or
179
+ not by what is kept, and the writers already ask only for what is cited.
180
+ An edge from an item left out is not an edge of what is held.
181
+ """
182
+ keep = set(only)
183
+ return replace(
184
+ graph,
185
+ items={uid: item for uid, item in graph.items.items() if uid in keep},
186
+ by_register={prefix: [i for i in items if i.uid in keep] for prefix, items in graph.by_register.items()},
187
+ incoming={
188
+ target: [(source, kind) for source, kind in edges if source in keep]
189
+ for target, edges in graph.incoming.items()
190
+ },
191
+ )
@@ -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.0
3
+ Version: 0.5.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
@@ -71,8 +71,7 @@ Office formats, which are written from their own specifications.
71
71
 
72
72
  Every graph is read through `tl`, which composes a graph that declares
73
73
  `[[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.
74
+ a conformance document exists to carry.
76
75
  The tool is found beside this package's interpreter first and on the path
77
76
  second, and is run as a command — its command line is the surface it publishes.
78
77
 
@@ -95,6 +94,13 @@ knows them without git — the editor holds them from its clone — states them
95
94
  `--repository`, `--ref`, `--commit` and `--tree clean|dirty|untracked`, and git
96
95
  is then not consulted.
97
96
 
97
+ `--only UID[,UID…]`, given once or more, narrows any format to the items it
98
+ names: the catalogue, table and matrices hold only those, the tables only their
99
+ rows and the links between them, the notes only their notes, and the clauses
100
+ mirrored are only the ones they cite. The output then says `Items: n of N`,
101
+ because a partial document read as a whole one misleads. An identifier the
102
+ graph does not hold is a usage error (exit 2), and nothing is written.
103
+
98
104
  A quick run is silent. When a step — reading the graph, asking the tool to
99
105
  write the document, writing the file — has run for a second, one line on
100
106
  stderr says which, because a composed graph fetching its sources for the first
@@ -117,8 +123,8 @@ clause of the tool it reads (`satisfies: tl:SR-0111`) and have the citation
117
123
  resolved rather than asserted.
118
124
 
119
125
  ```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
126
+ tl -C idd check --strict # the grounding gate
127
+ tl -C idd docs --check # idd/docs/spec.md must match the graph
122
128
  tl-transform html -C idd # and the tool over its own graph
123
129
  ```
124
130
 
@@ -24,5 +24,6 @@ src/throughline_transform.egg-info/entry_points.txt
24
24
  src/throughline_transform.egg-info/requires.txt
25
25
  src/throughline_transform.egg-info/top_level.txt
26
26
  tests/conftest.py
27
+ tests/test_only.py
27
28
  tests/test_outputs.py
28
29
  tests/test_surface.py
@@ -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
@@ -322,6 +322,15 @@ def test_provenance_reads_git_and_notices_uncommitted_changes(git_graph: Path):
322
322
  subprocess.run(["git", "-C", str(git_graph), "checkout", "--", "."], check=True)
323
323
 
324
324
 
325
+ def test_the_output_names_the_tool_that_produced_it(plain_graph: Path, tmp_path: Path):
326
+ # UR-0003: "the tool that produced it" is this package, named first, and then the
327
+ # throughline that read the graph; the dump records only throughline's version.
328
+ out = tmp_path / "named.md"
329
+ assert main(["md", "-C", str(plain_graph), "-o", str(out), "--repository", "r"]) == 0
330
+ line = next(l for l in out.read_text().splitlines() if "Produced by:" in l)
331
+ assert re.search(r"Produced by: throughline-transform \S+ \(throughline \S+\)$", line), line
332
+
333
+
325
334
  # --- the command (UR-0001, SR-0011) -----------------------------------------
326
335
 
327
336