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.
- {throughline_transform-0.4.1 → throughline_transform-0.6.0}/LICENSE +1 -1
- {throughline_transform-0.4.1 → throughline_transform-0.6.0}/NOTICE +3 -3
- {throughline_transform-0.4.1/src/throughline_transform.egg-info → throughline_transform-0.6.0}/PKG-INFO +14 -6
- {throughline_transform-0.4.1 → throughline_transform-0.6.0}/README.md +12 -4
- {throughline_transform-0.4.1 → throughline_transform-0.6.0}/pyproject.toml +6 -6
- throughline_transform-0.6.0/src/throughline_transform/assistant.py +133 -0
- {throughline_transform-0.4.1 → throughline_transform-0.6.0}/src/throughline_transform/cli.py +59 -13
- {throughline_transform-0.4.1 → throughline_transform-0.6.0}/src/throughline_transform/markdown.py +23 -5
- {throughline_transform-0.4.1 → throughline_transform-0.6.0}/src/throughline_transform/model.py +26 -2
- {throughline_transform-0.4.1 → throughline_transform-0.6.0}/src/throughline_transform/project.py +8 -0
- {throughline_transform-0.4.1 → throughline_transform-0.6.0}/src/throughline_transform/provenance.py +16 -2
- {throughline_transform-0.4.1 → throughline_transform-0.6.0}/src/throughline_transform/tables.py +6 -1
- {throughline_transform-0.4.1 → throughline_transform-0.6.0/src/throughline_transform.egg-info}/PKG-INFO +14 -6
- {throughline_transform-0.4.1 → throughline_transform-0.6.0}/src/throughline_transform.egg-info/SOURCES.txt +3 -0
- throughline_transform-0.6.0/src/throughline_transform.egg-info/requires.txt +4 -0
- throughline_transform-0.6.0/tests/test_assistant.py +149 -0
- throughline_transform-0.6.0/tests/test_only.py +150 -0
- throughline_transform-0.4.1/src/throughline_transform.egg-info/requires.txt +0 -4
- {throughline_transform-0.4.1 → throughline_transform-0.6.0}/MANIFEST.in +0 -0
- {throughline_transform-0.4.1 → throughline_transform-0.6.0}/setup.cfg +0 -0
- {throughline_transform-0.4.1 → throughline_transform-0.6.0}/src/throughline_transform/__init__.py +0 -0
- {throughline_transform-0.4.1 → throughline_transform-0.6.0}/src/throughline_transform/blocks.py +0 -0
- {throughline_transform-0.4.1 → throughline_transform-0.6.0}/src/throughline_transform/html.py +0 -0
- {throughline_transform-0.4.1 → throughline_transform-0.6.0}/src/throughline_transform/notes.py +0 -0
- {throughline_transform-0.4.1 → throughline_transform-0.6.0}/src/throughline_transform/office.py +0 -0
- {throughline_transform-0.4.1 → throughline_transform-0.6.0}/src/throughline_transform/package.py +0 -0
- {throughline_transform-0.4.1 → throughline_transform-0.6.0}/src/throughline_transform/progress.py +0 -0
- {throughline_transform-0.4.1 → throughline_transform-0.6.0}/src/throughline_transform/shape.py +0 -0
- {throughline_transform-0.4.1 → throughline_transform-0.6.0}/src/throughline_transform.egg-info/dependency_links.txt +0 -0
- {throughline_transform-0.4.1 → throughline_transform-0.6.0}/src/throughline_transform.egg-info/entry_points.txt +0 -0
- {throughline_transform-0.4.1 → throughline_transform-0.6.0}/src/throughline_transform.egg-info/top_level.txt +0 -0
- {throughline_transform-0.4.1 → throughline_transform-0.6.0}/tests/conftest.py +0 -0
- {throughline_transform-0.4.1 → throughline_transform-0.6.0}/tests/test_outputs.py +0 -0
- {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-
|
|
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
|
|
11
|
-
throughline
|
|
12
|
-
|
|
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.
|
|
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.
|
|
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
|
|
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
|
|
121
|
-
tl
|
|
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
|
|
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
|
|
93
|
-
tl
|
|
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.
|
|
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`
|
|
41
|
-
#
|
|
42
|
-
#
|
|
43
|
-
#
|
|
44
|
-
dependencies = ["throughline>=3.
|
|
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
|
{throughline_transform-0.4.1 → throughline_transform-0.6.0}/src/throughline_transform/cli.py
RENAMED
|
@@ -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
|
|
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
|
|
86
|
-
|
|
87
|
-
|
|
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(),
|
|
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
|
-
|
|
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
|
{throughline_transform-0.4.1 → throughline_transform-0.6.0}/src/throughline_transform/markdown.py
RENAMED
|
@@ -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(
|
|
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
|
|
{throughline_transform-0.4.1 → throughline_transform-0.6.0}/src/throughline_transform/model.py
RENAMED
|
@@ -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
|
|
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
|
|
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
|
+
)
|
{throughline_transform-0.4.1 → throughline_transform-0.6.0}/src/throughline_transform/project.py
RENAMED
|
@@ -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
|
|
{throughline_transform-0.4.1 → throughline_transform-0.6.0}/src/throughline_transform/provenance.py
RENAMED
|
@@ -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
|
-
|
|
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:
|
{throughline_transform-0.4.1 → throughline_transform-0.6.0}/src/throughline_transform/tables.py
RENAMED
|
@@ -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.
|
|
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.
|
|
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
|
|
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
|
|
121
|
-
tl
|
|
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,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
|
|
File without changes
|
|
File without changes
|
{throughline_transform-0.4.1 → throughline_transform-0.6.0}/src/throughline_transform/__init__.py
RENAMED
|
File without changes
|
{throughline_transform-0.4.1 → throughline_transform-0.6.0}/src/throughline_transform/blocks.py
RENAMED
|
File without changes
|
{throughline_transform-0.4.1 → throughline_transform-0.6.0}/src/throughline_transform/html.py
RENAMED
|
File without changes
|
{throughline_transform-0.4.1 → throughline_transform-0.6.0}/src/throughline_transform/notes.py
RENAMED
|
File without changes
|
{throughline_transform-0.4.1 → throughline_transform-0.6.0}/src/throughline_transform/office.py
RENAMED
|
File without changes
|
{throughline_transform-0.4.1 → throughline_transform-0.6.0}/src/throughline_transform/package.py
RENAMED
|
File without changes
|
{throughline_transform-0.4.1 → throughline_transform-0.6.0}/src/throughline_transform/progress.py
RENAMED
|
File without changes
|
{throughline_transform-0.4.1 → throughline_transform-0.6.0}/src/throughline_transform/shape.py
RENAMED
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|