throughline-transform 0.1.0__py3-none-any.whl

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.
@@ -0,0 +1,334 @@
1
+ # Copyright (c) 2026 Henry J Grech-Cini
2
+ # SPDX-License-Identifier: Apache-2.0
3
+ """xlsx and docx, written from their own specifications (SR-0010).
4
+
5
+ Both are zips of XML, and both are written here rather than depended on. What
6
+ is produced is deliberately plain — a sheet of cells, a document of headings
7
+ and paragraphs. Neither format is exercised beyond what a reader needs to sort
8
+ a column or read a requirement.
9
+ """
10
+
11
+ from __future__ import annotations
12
+
13
+ import re
14
+
15
+ from .blocks import Block
16
+ from .package import Entry, archive, utf8, xml
17
+ from .tables import Table
18
+
19
+ # --- xlsx ------------------------------------------------------------------
20
+
21
+
22
+ def column_name(index: int) -> str:
23
+ """Column names in a sheet — A, B, … Z, AA, AB, …"""
24
+ name = ""
25
+ n = index + 1
26
+ while n > 0:
27
+ remainder = (n - 1) % 26
28
+ name = chr(65 + remainder) + name
29
+ n = (n - remainder) // 26
30
+ return name
31
+
32
+
33
+ def _widths(table: Table) -> list[int]:
34
+ """Column widths from the content, bounded at both ends."""
35
+ widths = []
36
+ for i, name in enumerate(table.columns):
37
+ longest = max([len(name), *[len(row[i]) if i < len(row) else 0 for row in table.rows]])
38
+ widths.append(min(60, max(10, longest + 2)))
39
+ return widths
40
+
41
+
42
+ def _sheet_xml(table: Table) -> str:
43
+ def row(cells: list[str], index: int) -> str:
44
+ style = 1 if index == 0 else 2
45
+ out = [f'<row r="{index + 1}">']
46
+ for column, value in enumerate(cells):
47
+ out.append(
48
+ f'<c r="{column_name(column)}{index + 1}" t="inlineStr" s="{style}">'
49
+ f'<is><t xml:space="preserve">{xml(value)}</t></is></c>'
50
+ )
51
+ out.append("</row>")
52
+ return "".join(out)
53
+
54
+ last = f"{column_name(max(0, len(table.columns) - 1))}{len(table.rows) + 1}"
55
+ cols = "".join(
56
+ f'<col min="{i + 1}" max="{i + 1}" width="{w}" customWidth="1"/>' for i, w in enumerate(_widths(table))
57
+ )
58
+ data = "".join(row(cells, i) for i, cells in enumerate([table.columns, *table.rows]))
59
+ return (
60
+ '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>'
61
+ '<worksheet xmlns="http://schemas.openxmlformats.org/spreadsheetml/2006/main">'
62
+ # The header row is frozen: a table of requirements is longer than a
63
+ # screen, and a column nobody can name is not sortable.
64
+ '<sheetViews><sheetView workbookViewId="0">'
65
+ '<pane ySplit="1" topLeftCell="A2" activePane="bottomLeft" state="frozen"/>'
66
+ "</sheetView></sheetViews>"
67
+ f"<cols>{cols}</cols>"
68
+ f"<sheetData>{data}</sheetData>"
69
+ # Read-only, without a password (SR-0007): a guard against a stray
70
+ # keystroke and a statement that this is a record. Sorting, filtering
71
+ # and selecting stay permitted. In this element a 0 means "allowed".
72
+ '<sheetProtection sheet="1" objects="1" scenarios="1" '
73
+ 'selectLockedCells="0" selectUnlockedCells="0" sort="0" autoFilter="0"/>'
74
+ f'<autoFilter ref="A1:{last}"/>'
75
+ "</worksheet>"
76
+ )
77
+
78
+
79
+ def sheet_name(name: str, index: int) -> str:
80
+ """A sheet name Excel will accept: 31 characters, and none of \\/?*[]:"""
81
+ clean = re.sub(r"[\\/?*\[\]:]", " ", name).strip()[:31]
82
+ return clean or f"Sheet{index + 1}"
83
+
84
+
85
+ def to_xlsx(tables: list[Table]) -> bytes:
86
+ names = [sheet_name(t.name, i) for i, t in enumerate(tables)]
87
+ n = len(tables)
88
+ entries: list[Entry] = [
89
+ (
90
+ "[Content_Types].xml",
91
+ utf8(
92
+ '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>'
93
+ '<Types xmlns="http://schemas.openxmlformats.org/package/2006/content-types">'
94
+ '<Default Extension="rels" ContentType="application/vnd.openxmlformats-package.relationships+xml"/>'
95
+ '<Default Extension="xml" ContentType="application/xml"/>'
96
+ '<Override PartName="/xl/workbook.xml" ContentType="application/vnd.openxmlformats-officedocument.spreadsheetml.sheet.main+xml"/>'
97
+ '<Override PartName="/xl/styles.xml" ContentType="application/vnd.openxmlformats-officedocument.spreadsheetml.styles+xml"/>'
98
+ + "".join(
99
+ f'<Override PartName="/xl/worksheets/sheet{i + 1}.xml" '
100
+ 'ContentType="application/vnd.openxmlformats-officedocument.spreadsheetml.worksheet+xml"/>'
101
+ for i in range(n)
102
+ )
103
+ + "</Types>"
104
+ ),
105
+ ),
106
+ (
107
+ "_rels/.rels",
108
+ utf8(
109
+ '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>'
110
+ '<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships">'
111
+ '<Relationship Id="rId1" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/officeDocument" Target="xl/workbook.xml"/>'
112
+ "</Relationships>"
113
+ ),
114
+ ),
115
+ (
116
+ "xl/workbook.xml",
117
+ utf8(
118
+ '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>'
119
+ '<workbook xmlns="http://schemas.openxmlformats.org/spreadsheetml/2006/main" '
120
+ 'xmlns:r="http://schemas.openxmlformats.org/officeDocument/2006/relationships">'
121
+ # Opened read-only by recommendation, structure locked so no
122
+ # sheet is added, removed or renamed (SR-0007).
123
+ '<fileSharing readOnlyRecommended="1"/>'
124
+ '<workbookProtection lockStructure="1"/>'
125
+ "<sheets>"
126
+ + "".join(
127
+ f'<sheet name="{xml(name)}" sheetId="{i + 1}" r:id="rId{i + 1}"/>' for i, name in enumerate(names)
128
+ )
129
+ + "</sheets></workbook>"
130
+ ),
131
+ ),
132
+ (
133
+ "xl/_rels/workbook.xml.rels",
134
+ utf8(
135
+ '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>'
136
+ '<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships">'
137
+ + "".join(
138
+ f'<Relationship Id="rId{i + 1}" '
139
+ 'Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/worksheet" '
140
+ f'Target="worksheets/sheet{i + 1}.xml"/>'
141
+ for i in range(n)
142
+ )
143
+ + f'<Relationship Id="rId{n + 1}" '
144
+ 'Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/styles" '
145
+ 'Target="styles.xml"/>'
146
+ "</Relationships>"
147
+ ),
148
+ ),
149
+ (
150
+ "xl/styles.xml",
151
+ utf8(
152
+ '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>'
153
+ '<styleSheet xmlns="http://schemas.openxmlformats.org/spreadsheetml/2006/main">'
154
+ '<fonts count="2"><font><sz val="11"/><name val="Calibri"/></font>'
155
+ '<font><b/><sz val="11"/><name val="Calibri"/></font></fonts>'
156
+ # A fill and a border are required even when nothing uses them —
157
+ # Excel indexes into these tables and refuses a file whose
158
+ # counts do not line up.
159
+ '<fills count="2"><fill><patternFill patternType="none"/></fill>'
160
+ '<fill><patternFill patternType="gray125"/></fill></fills>'
161
+ '<borders count="1"><border/></borders>'
162
+ '<cellStyleXfs count="1"><xf/></cellStyleXfs>'
163
+ '<cellXfs count="3">'
164
+ '<xf xfId="0"/>'
165
+ '<xf xfId="0" fontId="1" applyFont="1" applyAlignment="1">'
166
+ '<alignment vertical="top" wrapText="1"/></xf>'
167
+ '<xf xfId="0" applyAlignment="1">'
168
+ '<alignment vertical="top" wrapText="1"/></xf>'
169
+ "</cellXfs>"
170
+ '<cellStyles count="1">'
171
+ '<cellStyle name="Normal" xfId="0" builtinId="0"/></cellStyles>'
172
+ "</styleSheet>"
173
+ ),
174
+ ),
175
+ *[(f"xl/worksheets/sheet{i + 1}.xml", utf8(_sheet_xml(t))) for i, t in enumerate(tables)],
176
+ ]
177
+ return archive(entries)
178
+
179
+
180
+ # --- docx ------------------------------------------------------------------
181
+
182
+
183
+ def _run(text: str, bold: bool = False) -> str:
184
+ lines = "".join(
185
+ ("" if i == 0 else "<w:br/>") + f'<w:t xml:space="preserve">{xml(line)}</w:t>'
186
+ for i, line in enumerate(text.split("\n"))
187
+ )
188
+ return f"<w:r>{'<w:rPr><w:b/></w:rPr>' if bold else ''}{lines}</w:r>"
189
+
190
+
191
+ def _table_xml(header: list[str], rows: list[list[str]]) -> str:
192
+ def side(edge: str) -> str:
193
+ return f'<w:{edge} w:val="single" w:sz="4" w:space="0" w:color="auto"/>'
194
+
195
+ def tc(text: str, bold: bool) -> str:
196
+ return (
197
+ '<w:tc><w:tcPr><w:tcW w:w="0" w:type="auto"/></w:tcPr>'
198
+ f"<w:p>{_run(text, bold)}</w:p></w:tc>"
199
+ )
200
+
201
+ def tr(cells: list[str], head: bool) -> str:
202
+ return (
203
+ f"<w:tr>{'<w:trPr><w:tblHeader/></w:trPr>' if head else ''}"
204
+ + "".join(tc(c, head) for c in cells)
205
+ + "</w:tr>"
206
+ )
207
+
208
+ width = 9360 // max(1, len(header))
209
+ return (
210
+ '<w:tbl><w:tblPr><w:tblW w:w="5000" w:type="pct"/><w:tblBorders>'
211
+ + "".join(side(e) for e in ["top", "left", "bottom", "right", "insideH", "insideV"])
212
+ + "</w:tblBorders></w:tblPr>"
213
+ # The grid is required, not decorative: a table without it is one Word
214
+ # will usually render and a conforming reader refuses outright.
215
+ "<w:tblGrid>"
216
+ + "".join(f'<w:gridCol w:w="{width}"/>' for _ in header)
217
+ + "</w:tblGrid>"
218
+ + tr(header, True)
219
+ + "".join(tr(r, False) for r in rows)
220
+ + "</w:tbl>"
221
+ )
222
+
223
+
224
+ def _paragraph(block: Block) -> str:
225
+ if block.table:
226
+ return _table_xml(block.table["header"], block.table["rows"])
227
+ if block.heading:
228
+ style = f'<w:pStyle w:val="Heading{min(block.heading, 4)}"/>'
229
+ elif block.quote:
230
+ style = '<w:pStyle w:val="Quote"/>'
231
+ elif block.small:
232
+ style = '<w:pStyle w:val="Attrs"/>'
233
+ else:
234
+ style = ""
235
+ text = f"<w:p>{f'<w:pPr>{style}</w:pPr>' if style else ''}{_run(block.text)}</w:p>"
236
+ beneath = (
237
+ f"{block.item['type'].replace('_', ' ')} · {block.item['status']}" if block.item else block.subtitle
238
+ )
239
+ if beneath:
240
+ text += f'<w:p><w:pPr><w:pStyle w:val="Attrs"/></w:pPr>{_run(beneath)}</w:p>'
241
+ return text
242
+
243
+
244
+ def _contents_xml() -> str:
245
+ """A table of contents Word fills in when asked (SR-0008)."""
246
+ return (
247
+ '<w:p><w:pPr><w:pStyle w:val="Heading1"/></w:pPr>' + _run("Contents") + "</w:p>"
248
+ '<w:p><w:fldSimple w:instr="TOC \\o &quot;1-4&quot; \\h \\z \\u">'
249
+ + _run("Right-click here and choose Update Field to fill in the contents.")
250
+ + "</w:fldSimple></w:p>"
251
+ '<w:p><w:r><w:br w:type="page"/></w:r></w:p>'
252
+ )
253
+
254
+
255
+ _STYLES = (
256
+ '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>'
257
+ '<w:styles xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">'
258
+ '<w:docDefaults><w:rPrDefault><w:rPr><w:rFonts w:ascii="Calibri" w:hAnsi="Calibri"/>'
259
+ '<w:sz w:val="22"/></w:rPr></w:rPrDefault>'
260
+ '<w:pPrDefault><w:pPr><w:spacing w:after="120"/></w:pPr></w:pPrDefault></w:docDefaults>'
261
+ + "".join(
262
+ f'<w:style w:type="paragraph" w:styleId="Heading{level}">'
263
+ f'<w:name w:val="heading {level}"/><w:basedOn w:val="Normal"/>'
264
+ f'<w:pPr><w:outlineLvl w:val="{level - 1}"/><w:spacing w:before="240"/></w:pPr>'
265
+ f'<w:rPr><w:b/><w:sz w:val="{36 - level * 4}"/></w:rPr></w:style>'
266
+ for level in (1, 2, 3, 4)
267
+ )
268
+ + '<w:style w:type="paragraph" w:styleId="Quote"><w:name w:val="Quote"/>'
269
+ '<w:pPr><w:ind w:left="720"/></w:pPr><w:rPr><w:i/></w:rPr></w:style>'
270
+ '<w:style w:type="paragraph" w:styleId="Attrs"><w:name w:val="Attrs"/>'
271
+ '<w:basedOn w:val="Normal"/><w:rPr><w:sz w:val="18"/><w:color w:val="555555"/></w:rPr></w:style>'
272
+ '<w:style w:type="paragraph" w:default="1" w:styleId="Normal">'
273
+ '<w:name w:val="Normal"/></w:style>'
274
+ "</w:styles>"
275
+ )
276
+
277
+
278
+ def to_docx(blocks: list[Block]) -> bytes:
279
+ first_section = next((i for i, b in enumerate(blocks) if b.heading == 2), -1)
280
+ body: list[str] = []
281
+ for i, block in enumerate(blocks):
282
+ if i == first_section:
283
+ body.append(_contents_xml())
284
+ elif block.heading == 2:
285
+ body.append('<w:p><w:r><w:br w:type="page"/></w:r></w:p>')
286
+ body.append(_paragraph(block))
287
+ # Word joins two tables that touch into one.
288
+ if block.table and i + 1 < len(blocks) and blocks[i + 1].table:
289
+ body.append("<w:p/>")
290
+ document = (
291
+ '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>'
292
+ '<w:document xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">'
293
+ "<w:body>" + "".join(body) +
294
+ # A4, with a margin on every side.
295
+ '<w:sectPr><w:pgSz w:w="11906" w:h="16838"/>'
296
+ '<w:pgMar w:top="1418" w:right="1134" w:bottom="1418" w:left="1134" w:header="709" w:footer="709"/>'
297
+ "</w:sectPr>"
298
+ "</w:body></w:document>"
299
+ )
300
+ entries: list[Entry] = [
301
+ (
302
+ "[Content_Types].xml",
303
+ utf8(
304
+ '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>'
305
+ '<Types xmlns="http://schemas.openxmlformats.org/package/2006/content-types">'
306
+ '<Default Extension="rels" ContentType="application/vnd.openxmlformats-package.relationships+xml"/>'
307
+ '<Default Extension="xml" ContentType="application/xml"/>'
308
+ '<Override PartName="/word/document.xml" ContentType="application/vnd.openxmlformats-officedocument.wordprocessingml.document.main+xml"/>'
309
+ '<Override PartName="/word/styles.xml" ContentType="application/vnd.openxmlformats-officedocument.wordprocessingml.styles+xml"/>'
310
+ "</Types>"
311
+ ),
312
+ ),
313
+ (
314
+ "_rels/.rels",
315
+ utf8(
316
+ '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>'
317
+ '<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships">'
318
+ '<Relationship Id="rId1" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/officeDocument" Target="word/document.xml"/>'
319
+ "</Relationships>"
320
+ ),
321
+ ),
322
+ (
323
+ "word/_rels/document.xml.rels",
324
+ utf8(
325
+ '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>'
326
+ '<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships">'
327
+ '<Relationship Id="rId1" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/styles" Target="styles.xml"/>'
328
+ "</Relationships>"
329
+ ),
330
+ ),
331
+ ("word/styles.xml", utf8(_STYLES)),
332
+ ("word/document.xml", utf8(document)),
333
+ ]
334
+ return archive(entries)
@@ -0,0 +1,70 @@
1
+ # Copyright (c) 2026 Henry J Grech-Cini
2
+ # SPDX-License-Identifier: Apache-2.0
3
+ """Containers (SR-0011): a zip, or the same files written into a folder.
4
+
5
+ Every timestamp is the same fixed value, so the same graph exported twice
6
+ produces identical bytes. An output that differs only in when it was taken
7
+ cannot be compared with the one before it, and comparing them is a thing
8
+ people do with a specification.
9
+ """
10
+
11
+ from __future__ import annotations
12
+
13
+ import io
14
+ import re
15
+ import zipfile
16
+ from pathlib import Path
17
+
18
+ Entry = tuple[str, bytes]
19
+
20
+ #: 1980-01-01 00:00:00 — the epoch of the zip format itself.
21
+ _EPOCH = (1980, 1, 1, 0, 0, 0)
22
+
23
+
24
+ def archive(entries: list[Entry]) -> bytes:
25
+ buffer = io.BytesIO()
26
+ with zipfile.ZipFile(buffer, "w", compression=zipfile.ZIP_DEFLATED) as zf:
27
+ for path, data in entries:
28
+ info = zipfile.ZipInfo(path, date_time=_EPOCH)
29
+ info.compress_type = zipfile.ZIP_DEFLATED
30
+ # Regular file, rw-r--r--, so the member unpacks with sane permissions.
31
+ info.external_attr = 0o100644 << 16
32
+ zf.writestr(info, data)
33
+ return buffer.getvalue()
34
+
35
+
36
+ def unpack(entries: list[Entry], folder: Path) -> list[Path]:
37
+ """Write the entries beneath ``folder``. Refuses a path that would escape it."""
38
+ folder = folder.resolve()
39
+ written: list[Path] = []
40
+ for path, data in entries:
41
+ target = (folder / path).resolve()
42
+ if folder != target and folder not in target.parents:
43
+ raise ValueError(f"refusing to write outside {folder}: {path}")
44
+ target.parent.mkdir(parents=True, exist_ok=True)
45
+ target.write_bytes(data)
46
+ written.append(target)
47
+ return written
48
+
49
+
50
+ _CONTROL = re.compile(r"[\x00-\x08\x0b\x0c\x0e-\x1f]")
51
+
52
+
53
+ def xml(text: str) -> str:
54
+ """XML text escaping, needed by every part of both Office formats.
55
+
56
+ A control character is not legal in XML 1.0 at all, and an item's text is
57
+ arbitrary content from a repository — so they go rather than producing a
58
+ file the reader refuses to open. Tab, newline and carriage return stay.
59
+ """
60
+ text = (
61
+ text.replace("&", "&amp;")
62
+ .replace("<", "&lt;")
63
+ .replace(">", "&gt;")
64
+ .replace('"', "&quot;")
65
+ )
66
+ return _CONTROL.sub("", text)
67
+
68
+
69
+ def utf8(text: str) -> bytes:
70
+ return text.encode("utf-8")
@@ -0,0 +1,108 @@
1
+ # Copyright (c) 2026 Henry J Grech-Cini
2
+ # SPDX-License-Identifier: Apache-2.0
3
+ """Reaching the tool (SR-0001, SR-0002).
4
+
5
+ Two commands are asked of it and nothing else: ``dump`` for the structure and
6
+ ``docs`` for the prose. Which entry point answers is decided by the graph, not
7
+ the caller — a graph that declares sources is composed, and the core command
8
+ run over it would exit cleanly and drop every borrowed clause's own reference
9
+ number, which is exactly the identifier a conformance document exists to carry.
10
+
11
+ The tool is reached as a command, not imported. Its command line is the surface
12
+ it publishes; its modules move between releases.
13
+ """
14
+
15
+ from __future__ import annotations
16
+
17
+ import json
18
+ import os
19
+ import shutil
20
+ import subprocess
21
+ import sys
22
+ import tempfile
23
+ import tomllib
24
+ from pathlib import Path
25
+ from typing import Any
26
+
27
+ from .model import Graph, index
28
+
29
+ CONFIG = "throughline.toml"
30
+
31
+
32
+ class TransformError(Exception):
33
+ """A failure the user can act on, reported in one line on stderr."""
34
+
35
+
36
+ def find_graph(start: str | os.PathLike[str] | None) -> Path:
37
+ """The directory holding ``throughline.toml``.
38
+
39
+ With ``-C``, that directory must be a graph — a wrong path is refused rather
40
+ than searched around, because an export of the wrong graph reads exactly
41
+ like the right one. Without it, the walk upward from the working directory
42
+ is the one ``tl`` itself makes.
43
+ """
44
+ if start is not None:
45
+ root = Path(start).resolve()
46
+ if not (root / CONFIG).is_file():
47
+ raise TransformError(f"{root} holds no {CONFIG}")
48
+ return root
49
+ here = Path.cwd().resolve()
50
+ for candidate in (here, *here.parents):
51
+ if (candidate / CONFIG).is_file():
52
+ return candidate
53
+ raise TransformError(f"no {CONFIG} here or above; pass -C <dir>")
54
+
55
+
56
+ def is_composed(root: Path) -> bool:
57
+ """Whether the graph declares sources, and so is the composer's to read."""
58
+ with open(root / CONFIG, "rb") as fh:
59
+ config = tomllib.load(fh)
60
+ return bool(config.get("sources"))
61
+
62
+
63
+ def executable(name: str) -> str:
64
+ """Where the tool is.
65
+
66
+ Beside this interpreter first, because that is the tool this package was
67
+ installed with and the one its floors were proven against; then the path.
68
+ """
69
+ beside = Path(sys.executable).parent / name
70
+ if beside.is_file() and os.access(beside, os.X_OK):
71
+ return str(beside)
72
+ found = shutil.which(name)
73
+ if found:
74
+ return found
75
+ raise TransformError(f"{name} is not installed beside this tool nor on the path")
76
+
77
+
78
+ def run(root: Path, args: list[str], composed: bool) -> str:
79
+ """Run the tool over the graph and hand back what it wrote."""
80
+ command = [executable("tl-compose" if composed else "tl"), "-C", str(root), *args]
81
+ try:
82
+ done = subprocess.run(command, capture_output=True, text=True, encoding="utf-8")
83
+ except OSError as exc: # pragma: no cover - the executable check above covers the common case
84
+ raise TransformError(f"could not run {command[0]}: {exc}") from exc
85
+ if done.returncode != 0:
86
+ detail = done.stderr.strip() or done.stdout.strip() or f"exit {done.returncode}"
87
+ raise TransformError(f"{Path(command[0]).name} {args[0]} failed — {detail}")
88
+ return done.stdout
89
+
90
+
91
+ def load(root: Path) -> Graph:
92
+ """The graph, as the tool exports it."""
93
+ composed = is_composed(root)
94
+ raw: dict[str, Any] = json.loads(run(root, ["dump"], composed))
95
+ return index(raw, composed)
96
+
97
+
98
+ def docs(root: Path, document: str, composed: bool) -> str:
99
+ """Hand the tool a document of directives and read back what it wrote.
100
+
101
+ Written outside the graph, so an export can never be mistaken for a change
102
+ to it and never reaches a commit.
103
+ """
104
+ with tempfile.TemporaryDirectory(prefix="tl-transform-") as scratch:
105
+ path = Path(scratch) / "document.md"
106
+ path.write_text(document, encoding="utf-8")
107
+ run(root, ["docs", str(path)], composed)
108
+ return path.read_text(encoding="utf-8")
@@ -0,0 +1,91 @@
1
+ # Copyright (c) 2026 Henry J Grech-Cini
2
+ # SPDX-License-Identifier: Apache-2.0
3
+ """What an output was taken from (SR-0004).
4
+
5
+ An output outlives the working tree that made it, and the first question anyone
6
+ asks of one is what it was true of. A commit answers that when there is one. A
7
+ tree with uncommitted changes, or none under version control at all, is still a
8
+ graph worth exporting — the output has to say which it was, because a reader
9
+ holding the file cannot tell.
10
+ """
11
+
12
+ from __future__ import annotations
13
+
14
+ import re
15
+ import subprocess
16
+ from dataclasses import dataclass
17
+ from pathlib import Path
18
+
19
+ CLEAN = "clean"
20
+ DIRTY = "uncommitted changes"
21
+ UNTRACKED = "not under version control"
22
+
23
+
24
+ @dataclass(frozen=True)
25
+ class Provenance:
26
+ repository: str
27
+ ref: str
28
+ commit: str
29
+ tree: str
30
+ tool: str
31
+
32
+ def lines(self) -> list[str]:
33
+ return [
34
+ f"Repository: {self.repository}",
35
+ f"Ref: {self.ref or 'none'}",
36
+ f"Commit: {self.commit or 'none'}",
37
+ f"Working tree: {self.tree}",
38
+ f"Produced by: {self.tool}",
39
+ ]
40
+
41
+ @property
42
+ def stem(self) -> str:
43
+ """A file name stem: the repository and the ref, made safe for a file name."""
44
+ base = self.repository.replace("/", "-")
45
+ if self.ref:
46
+ base = f"{base}-{self.ref}"
47
+ return re.sub(r"[^\w.-]", "-", base).strip("-") or "graph"
48
+
49
+
50
+ def _git(root: Path, *args: str) -> str | None:
51
+ try:
52
+ done = subprocess.run(
53
+ ["git", "-C", str(root), *args], capture_output=True, text=True, encoding="utf-8"
54
+ )
55
+ except OSError:
56
+ return None
57
+ return done.stdout.strip() if done.returncode == 0 else None
58
+
59
+
60
+ _REMOTE = re.compile(r"(?:[:/])([^/:]+/[^/]+?)(?:\.git)?/?$")
61
+
62
+
63
+ def _repository_name(remote: str | None, toplevel: Path) -> str:
64
+ if remote:
65
+ match = _REMOTE.search(remote)
66
+ if match:
67
+ return match.group(1)
68
+ return toplevel.name
69
+
70
+
71
+ def provenance_of(root: Path, tool: str) -> Provenance:
72
+ """Read the working tree's state for the graph at ``root``.
73
+
74
+ Cleanliness is judged over the graph's directory, not the whole repository:
75
+ an output is of the graph, and a change elsewhere in the repository does not
76
+ alter what it says.
77
+ """
78
+ toplevel = _git(root, "rev-parse", "--show-toplevel")
79
+ if not toplevel:
80
+ return Provenance(repository=root.name, ref="", commit="", tree=UNTRACKED, tool=tool)
81
+ top = Path(toplevel)
82
+ repository = _repository_name(_git(root, "remote", "get-url", "origin"), top)
83
+ ref = _git(root, "rev-parse", "--abbrev-ref", "HEAD") or ""
84
+ if ref == "HEAD":
85
+ ref = "detached"
86
+ commit = _git(root, "rev-parse", "HEAD") or ""
87
+ status = _git(root, "status", "--porcelain", "--", str(root))
88
+ tree = DIRTY if status else CLEAN
89
+ if not commit:
90
+ tree = DIRTY
91
+ return Provenance(repository=repository, ref=ref, commit=commit, tree=tree, tool=tool)
@@ -0,0 +1,32 @@
1
+ # Copyright (c) 2026 Henry J Grech-Cini
2
+ # SPDX-License-Identifier: Apache-2.0
3
+ """The shape of what the tool writes, read in one place (SR-0003).
4
+
5
+ ``tl docs`` renders an item as a bold line, its words as a quotation, its
6
+ rationale, one line per link type and a line of attributes (throughline
7
+ SR-0111, SR-0113, SR-0187). Nothing here is restated — these patterns are read,
8
+ never written. If the tool changes the line, every consumer of this module
9
+ falls back the same way rather than each guessing differently.
10
+ """
11
+
12
+ from __future__ import annotations
13
+
14
+ import re
15
+
16
+ #: The line the tool writes to open an item in a catalogue or a mirrored source:
17
+ #: ``**UID — title** — `type`, status `status```, where a borrowed clause's UID is
18
+ #: namespace-qualified and may carry its reference in brackets.
19
+ ITEM_LINE = re.compile(
20
+ r"^\*\*((?:[a-z][a-z0-9_-]*:)?[A-Z][A-Z0-9]*-\d+)(?: \((.*?)\))? — (.+?)\*\* — "
21
+ r"`([^`]+)`, status `([^`]+)`$"
22
+ )
23
+
24
+ #: The tool's attribute line: ``**name**: value · **name**: value``.
25
+ ATTRS_LINE = re.compile(r"^\*\*[a-z_]+\*\*: .*$")
26
+
27
+ #: An identifier as the tool writes one anywhere in prose: a local UID, or a
28
+ #: namespace-qualified one naming a clause of an adopted source.
29
+ IDENTIFIER = re.compile(r"(?:[a-z][a-z0-9_-]*:)?[A-Z][A-Z0-9]*-\d+")
30
+
31
+ #: A region marker, opening or closing.
32
+ MARKER = re.compile(r"^\s*<!--\s*tl:(?:[a-z.]+|end)\b.*-->\s*$", re.IGNORECASE)