throughline-transform 0.6.0__tar.gz → 0.7.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.6.0/src/throughline_transform.egg-info → throughline_transform-0.7.0}/PKG-INFO +2 -4
- {throughline_transform-0.6.0 → throughline_transform-0.7.0}/README.md +0 -2
- {throughline_transform-0.6.0 → throughline_transform-0.7.0}/pyproject.toml +2 -2
- {throughline_transform-0.6.0 → throughline_transform-0.7.0}/src/throughline_transform/cli.py +5 -23
- {throughline_transform-0.6.0 → throughline_transform-0.7.0}/src/throughline_transform/markdown.py +0 -3
- {throughline_transform-0.6.0 → throughline_transform-0.7.0}/src/throughline_transform/model.py +0 -4
- {throughline_transform-0.6.0 → throughline_transform-0.7.0}/src/throughline_transform/project.py +0 -8
- {throughline_transform-0.6.0 → throughline_transform-0.7.0/src/throughline_transform.egg-info}/PKG-INFO +2 -4
- {throughline_transform-0.6.0 → throughline_transform-0.7.0}/src/throughline_transform.egg-info/SOURCES.txt +0 -2
- throughline_transform-0.7.0/src/throughline_transform.egg-info/requires.txt +4 -0
- throughline_transform-0.6.0/src/throughline_transform/assistant.py +0 -133
- throughline_transform-0.6.0/src/throughline_transform.egg-info/requires.txt +0 -4
- throughline_transform-0.6.0/tests/test_assistant.py +0 -149
- {throughline_transform-0.6.0 → throughline_transform-0.7.0}/LICENSE +0 -0
- {throughline_transform-0.6.0 → throughline_transform-0.7.0}/MANIFEST.in +0 -0
- {throughline_transform-0.6.0 → throughline_transform-0.7.0}/NOTICE +0 -0
- {throughline_transform-0.6.0 → throughline_transform-0.7.0}/setup.cfg +0 -0
- {throughline_transform-0.6.0 → throughline_transform-0.7.0}/src/throughline_transform/__init__.py +0 -0
- {throughline_transform-0.6.0 → throughline_transform-0.7.0}/src/throughline_transform/blocks.py +0 -0
- {throughline_transform-0.6.0 → throughline_transform-0.7.0}/src/throughline_transform/html.py +0 -0
- {throughline_transform-0.6.0 → throughline_transform-0.7.0}/src/throughline_transform/notes.py +0 -0
- {throughline_transform-0.6.0 → throughline_transform-0.7.0}/src/throughline_transform/office.py +0 -0
- {throughline_transform-0.6.0 → throughline_transform-0.7.0}/src/throughline_transform/package.py +0 -0
- {throughline_transform-0.6.0 → throughline_transform-0.7.0}/src/throughline_transform/progress.py +0 -0
- {throughline_transform-0.6.0 → throughline_transform-0.7.0}/src/throughline_transform/provenance.py +0 -0
- {throughline_transform-0.6.0 → throughline_transform-0.7.0}/src/throughline_transform/shape.py +0 -0
- {throughline_transform-0.6.0 → throughline_transform-0.7.0}/src/throughline_transform/tables.py +0 -0
- {throughline_transform-0.6.0 → throughline_transform-0.7.0}/src/throughline_transform.egg-info/dependency_links.txt +0 -0
- {throughline_transform-0.6.0 → throughline_transform-0.7.0}/src/throughline_transform.egg-info/entry_points.txt +0 -0
- {throughline_transform-0.6.0 → throughline_transform-0.7.0}/src/throughline_transform.egg-info/top_level.txt +0 -0
- {throughline_transform-0.6.0 → throughline_transform-0.7.0}/tests/conftest.py +0 -0
- {throughline_transform-0.6.0 → throughline_transform-0.7.0}/tests/test_only.py +0 -0
- {throughline_transform-0.6.0 → throughline_transform-0.7.0}/tests/test_outputs.py +0 -0
- {throughline_transform-0.6.0 → throughline_transform-0.7.0}/tests/test_surface.py +0 -0
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: throughline-transform
|
|
3
|
-
Version: 0.
|
|
3
|
+
Version: 0.7.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.11.1
|
|
25
25
|
Provides-Extra: dev
|
|
26
26
|
Requires-Dist: pytest>=8.0; extra == "dev"
|
|
27
27
|
Dynamic: license-file
|
|
@@ -41,7 +41,6 @@ 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
|
|
45
44
|
```
|
|
46
45
|
|
|
47
46
|
It is the command-line half of the
|
|
@@ -86,7 +85,6 @@ second, and is run as a command — its command line is the surface it publishes
|
|
|
86
85
|
| `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
86
|
| `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
87
|
| `html` | The same document as one self-contained page with print typography, A4 page rules and a contents list of links. Print it to PDF; the browser numbers the pages. |
|
|
89
|
-
| `assistant` | A folder for an assistant that reads only a few files and cannot run `tl` — Microsoft 365 Copilot in a controlled environment reads at most fifty: one file per register carrying its items exactly as `tl dump` gives them, each with its fingerprint, and a manifest naming the repository, ref, commit and tree state, the file of each register, the `tl` that wrote it, and the change-set form `tl apply` accepts, taken from `tl apply --describe`, with the instruction to answer with a change set quoting each fingerprint and never with rewritten files. `--wrap md` writes each file as Markdown holding one fenced JSON block, for an assistant that will not read a `.json` file. Always a folder, never an archive. |
|
|
90
88
|
| `blocks` | The document's structure as JSON — the same list of headings, quotations, paragraphs, attribute lines, tables and appendices the Word and HTML outputs are built from — for a front end that lays out its own pages. The editor's PDF is laid out from it. |
|
|
91
89
|
|
|
92
90
|
Every output carries the repository, ref, commit, working-tree state and tool
|
|
@@ -13,7 +13,6 @@ tl-transform csv -C idd # one row per item, a links file, a file
|
|
|
13
13
|
tl-transform xlsx -C idd # the same as a read-only workbook that still sorts and filters
|
|
14
14
|
tl-transform docx -C idd # a Word document: title page, contents, a heading per item
|
|
15
15
|
tl-transform html -C idd # a print-ready page — print it to PDF from any browser
|
|
16
|
-
tl-transform assistant -C idd # a folder an assistant that cannot run tl reads whole: one file per register, and how to answer
|
|
17
16
|
```
|
|
18
17
|
|
|
19
18
|
It is the command-line half of the
|
|
@@ -58,7 +57,6 @@ second, and is run as a command — its command line is the surface it publishes
|
|
|
58
57
|
| `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
58
|
| `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
59
|
| `html` | The same document as one self-contained page with print typography, A4 page rules and a contents list of links. Print it to PDF; the browser numbers the pages. |
|
|
61
|
-
| `assistant` | A folder for an assistant that reads only a few files and cannot run `tl` — Microsoft 365 Copilot in a controlled environment reads at most fifty: one file per register carrying its items exactly as `tl dump` gives them, each with its fingerprint, and a manifest naming the repository, ref, commit and tree state, the file of each register, the `tl` that wrote it, and the change-set form `tl apply` accepts, taken from `tl apply --describe`, with the instruction to answer with a change set quoting each fingerprint and never with rewritten files. `--wrap md` writes each file as Markdown holding one fenced JSON block, for an assistant that will not read a `.json` file. Always a folder, never an archive. |
|
|
62
60
|
| `blocks` | The document's structure as JSON — the same list of headings, quotations, paragraphs, attribute lines, tables and appendices the Word and HTML outputs are built from — for a front end that lays out its own pages. The editor's PDF is laid out from it. |
|
|
63
61
|
|
|
64
62
|
Every output carries the repository, ref, commit, working-tree state and tool
|
|
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
|
|
|
4
4
|
|
|
5
5
|
[project]
|
|
6
6
|
name = "throughline-transform"
|
|
7
|
-
version = "0.
|
|
7
|
+
version = "0.7.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"
|
|
@@ -41,7 +41,7 @@ classifiers = [
|
|
|
41
41
|
# (SR-0003). It was written against throughline 2.2.0 and throughline-compose
|
|
42
42
|
# 0.16.1; since 3.11.1 composition is the Tool's own (throughline UR-0037), `tl`
|
|
43
43
|
# renders both directives, and throughline is the one floor.
|
|
44
|
-
dependencies = ["throughline>=3.
|
|
44
|
+
dependencies = ["throughline>=3.11.1"] # composition is the Tool's own since 3.11.1 (throughline UR-0037)
|
|
45
45
|
|
|
46
46
|
[project.optional-dependencies]
|
|
47
47
|
dev = ["pytest>=8.0"]
|
{throughline_transform-0.6.0 → throughline_transform-0.7.0}/src/throughline_transform/cli.py
RENAMED
|
@@ -9,7 +9,6 @@
|
|
|
9
9
|
tl-transform docx [-C DIR] [-o FILE] [--body …] [--matrix] [--no-stats]
|
|
10
10
|
tl-transform html [-C DIR] [-o FILE] [--body …] [--matrix] [--no-stats]
|
|
11
11
|
tl-transform blocks [-C DIR] [-o FILE] [--body …] [--matrix] [--no-stats]
|
|
12
|
-
tl-transform assistant [-C DIR] [-o DIR] [--wrap json|md]
|
|
13
12
|
|
|
14
13
|
Any format takes --repository, --ref, --commit and --tree to state the
|
|
15
14
|
provenance instead of reading git (SR-0013), and --only UID[,UID…] to hold
|
|
@@ -29,22 +28,19 @@ from throughline.version import distribution_version as _v
|
|
|
29
28
|
|
|
30
29
|
from . import markdown as md
|
|
31
30
|
from .blocks import as_blocks, to_json
|
|
32
|
-
from .assistant import WRAPS, to_assistant
|
|
33
31
|
from .html import to_html
|
|
34
32
|
from .model import Graph, narrowed, register_titles, source_titles
|
|
35
33
|
from .notes import to_notes
|
|
36
34
|
from .office import to_docx, to_xlsx
|
|
37
35
|
from .package import Entry, archive, unpack, utf8
|
|
38
36
|
from .progress import slow
|
|
39
|
-
from .project import TransformError,
|
|
37
|
+
from .project import TransformError, find_graph, load
|
|
40
38
|
from .provenance import TREE_WORDS, Provenance, provenance_of, stated
|
|
41
39
|
from .tables import Table, cited_sources, file_name, links_of, per_register, to_csv, whole_graph
|
|
42
40
|
|
|
43
|
-
FORMATS = ("md", "notes", "csv", "xlsx", "docx", "html", "blocks"
|
|
41
|
+
FORMATS = ("md", "notes", "csv", "xlsx", "docx", "html", "blocks")
|
|
44
42
|
PROSE = ("md", "docx", "html", "blocks")
|
|
45
|
-
FOLDERS = ("notes", "csv"
|
|
46
|
-
#: Always a folder, never an archive: an assistant cannot open one (SR-0017).
|
|
47
|
-
FOLDER_ONLY = ("assistant",)
|
|
43
|
+
FOLDERS = ("notes", "csv")
|
|
48
44
|
|
|
49
45
|
|
|
50
46
|
def version_string() -> str:
|
|
@@ -70,12 +66,6 @@ def build_parser() -> argparse.ArgumentParser:
|
|
|
70
66
|
p.add_argument("--matrix", action="store_true", help="md, docx, html, blocks: add a traceability matrix per grounding link")
|
|
71
67
|
p.add_argument("--no-stats", dest="stats", action="store_false", help="md, docx, html, blocks: leave out the tool's summary")
|
|
72
68
|
p.add_argument("--markers", action="store_true", help="md: keep the tool's region markers so `tl docs` can refill the file")
|
|
73
|
-
p.add_argument(
|
|
74
|
-
"--wrap",
|
|
75
|
-
choices=WRAPS,
|
|
76
|
-
default="json",
|
|
77
|
-
help="assistant: each file as JSON, or as Markdown holding one fenced JSON block for an assistant that will not read a .json file",
|
|
78
|
-
)
|
|
79
69
|
p.add_argument("--repository", metavar="OWNER/NAME", help="state the repository instead of reading git")
|
|
80
70
|
p.add_argument("--ref", metavar="REF", help="state the ref instead of reading git")
|
|
81
71
|
p.add_argument("--commit", metavar="SHA", help="state the commit instead of reading git")
|
|
@@ -134,12 +124,6 @@ def produce(graph: Graph, root: Path, fmt: str, opts: md.Options, provenance: Pr
|
|
|
134
124
|
return utf8(to_json(blocks, provenance.lines(), provenance.record())), f"{stem}-blocks.json"
|
|
135
125
|
return utf8(to_html(blocks, provenance)), f"{stem}.html"
|
|
136
126
|
|
|
137
|
-
if fmt == "assistant":
|
|
138
|
-
entries = to_assistant(
|
|
139
|
-
graph.raw, provenance, change_set_format(root, graph.composed), wrap=opts.wrap, only=opts.only
|
|
140
|
-
)
|
|
141
|
-
return entries, f"{stem}-assistant"
|
|
142
|
-
|
|
143
127
|
if fmt == "notes":
|
|
144
128
|
text = md.to_markdown(
|
|
145
129
|
root, graph, replace(opts, body="catalog", matrix=False, stats=False, markers=False), provenance
|
|
@@ -185,9 +169,7 @@ def main(argv: list[str] | None = None) -> int:
|
|
|
185
169
|
only = named(args.only)
|
|
186
170
|
if args.only is not None and not only:
|
|
187
171
|
parser.error("--only names no item")
|
|
188
|
-
opts = md.Options(
|
|
189
|
-
body=args.body, matrix=args.matrix, stats=args.stats, markers=args.markers, split=args.split, only=only, wrap=args.wrap
|
|
190
|
-
)
|
|
172
|
+
opts = md.Options(body=args.body, matrix=args.matrix, stats=args.stats, markers=args.markers, split=args.split, only=only)
|
|
191
173
|
try:
|
|
192
174
|
root = find_graph(args.directory)
|
|
193
175
|
graph = load(root)
|
|
@@ -209,7 +191,7 @@ def main(argv: list[str] | None = None) -> int:
|
|
|
209
191
|
provenance = replace(provenance, items=f"{len(only)} of {len(graph.items)}")
|
|
210
192
|
result, default = produce(graph, root, args.format, opts, provenance)
|
|
211
193
|
with slow(f"still writing {args.output or default}…"):
|
|
212
|
-
target = write(result, default, args.output, args.folder
|
|
194
|
+
target = write(result, default, args.output, args.folder)
|
|
213
195
|
except (TransformError, OSError, ValueError) as exc:
|
|
214
196
|
print(f"tl-transform: {exc}", file=sys.stderr)
|
|
215
197
|
return 1
|
{throughline_transform-0.6.0 → throughline_transform-0.7.0}/src/throughline_transform/markdown.py
RENAMED
|
@@ -31,9 +31,6 @@ class Options:
|
|
|
31
31
|
markers: bool = False
|
|
32
32
|
#: For the tabular outputs: one table for everything, or one per register.
|
|
33
33
|
split: str = "one"
|
|
34
|
-
#: For the assistant form: each file as JSON, or as Markdown holding one
|
|
35
|
-
#: fenced JSON block.
|
|
36
|
-
wrap: str = "json"
|
|
37
34
|
#: The items the output holds, where the caller named them (SR-0016);
|
|
38
35
|
#: empty for every item.
|
|
39
36
|
only: tuple[str, ...] = ()
|
{throughline_transform-0.6.0 → throughline_transform-0.7.0}/src/throughline_transform/model.py
RENAMED
|
@@ -72,9 +72,6 @@ class Graph:
|
|
|
72
72
|
#: What the tool called itself in the dump.
|
|
73
73
|
tool_version: str
|
|
74
74
|
composed: bool
|
|
75
|
-
#: The dump itself, as the tool wrote it, for the assistant form that hands
|
|
76
|
-
#: it on unreshaped (SR-0017).
|
|
77
|
-
raw: dict[str, Any] = field(default_factory=dict)
|
|
78
75
|
|
|
79
76
|
|
|
80
77
|
def prefix_of(uid: str) -> str:
|
|
@@ -152,7 +149,6 @@ def index(dump: dict[str, Any], composed: bool) -> Graph:
|
|
|
152
149
|
sources=sources,
|
|
153
150
|
tool_version=str(meta.get("tool_version") or "?"),
|
|
154
151
|
composed=composed,
|
|
155
|
-
raw=dump,
|
|
156
152
|
)
|
|
157
153
|
|
|
158
154
|
|
{throughline_transform-0.6.0 → throughline_transform-0.7.0}/src/throughline_transform/project.py
RENAMED
|
@@ -141,14 +141,6 @@ def load(root: Path) -> Graph:
|
|
|
141
141
|
return index(raw, composed)
|
|
142
142
|
|
|
143
143
|
|
|
144
|
-
def change_set_format(root: Path, composed: bool) -> str:
|
|
145
|
-
"""The change-set form ``tl apply`` accepts, as the tool itself states it
|
|
146
|
-
(SR-0018): taken from the command, never written here, so what an assistant
|
|
147
|
-
is told to write cannot drift from what apply reads."""
|
|
148
|
-
with slow(f"still asking {_tool(composed)} for the change-set format…"):
|
|
149
|
-
return run(root, ["apply", "--describe"], composed)
|
|
150
|
-
|
|
151
|
-
|
|
152
144
|
def docs(root: Path, document: str, composed: bool) -> str:
|
|
153
145
|
"""Hand the tool a document of directives and read back what it wrote.
|
|
154
146
|
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: throughline-transform
|
|
3
|
-
Version: 0.
|
|
3
|
+
Version: 0.7.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.11.1
|
|
25
25
|
Provides-Extra: dev
|
|
26
26
|
Requires-Dist: pytest>=8.0; extra == "dev"
|
|
27
27
|
Dynamic: license-file
|
|
@@ -41,7 +41,6 @@ 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
|
|
45
44
|
```
|
|
46
45
|
|
|
47
46
|
It is the command-line half of the
|
|
@@ -86,7 +85,6 @@ second, and is run as a command — its command line is the surface it publishes
|
|
|
86
85
|
| `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
86
|
| `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
87
|
| `html` | The same document as one self-contained page with print typography, A4 page rules and a contents list of links. Print it to PDF; the browser numbers the pages. |
|
|
89
|
-
| `assistant` | A folder for an assistant that reads only a few files and cannot run `tl` — Microsoft 365 Copilot in a controlled environment reads at most fifty: one file per register carrying its items exactly as `tl dump` gives them, each with its fingerprint, and a manifest naming the repository, ref, commit and tree state, the file of each register, the `tl` that wrote it, and the change-set form `tl apply` accepts, taken from `tl apply --describe`, with the instruction to answer with a change set quoting each fingerprint and never with rewritten files. `--wrap md` writes each file as Markdown holding one fenced JSON block, for an assistant that will not read a `.json` file. Always a folder, never an archive. |
|
|
90
88
|
| `blocks` | The document's structure as JSON — the same list of headings, quotations, paragraphs, attribute lines, tables and appendices the Word and HTML outputs are built from — for a front end that lays out its own pages. The editor's PDF is laid out from it. |
|
|
91
89
|
|
|
92
90
|
Every output carries the repository, ref, commit, working-tree state and tool
|
|
@@ -4,7 +4,6 @@ NOTICE
|
|
|
4
4
|
README.md
|
|
5
5
|
pyproject.toml
|
|
6
6
|
src/throughline_transform/__init__.py
|
|
7
|
-
src/throughline_transform/assistant.py
|
|
8
7
|
src/throughline_transform/blocks.py
|
|
9
8
|
src/throughline_transform/cli.py
|
|
10
9
|
src/throughline_transform/html.py
|
|
@@ -25,7 +24,6 @@ src/throughline_transform.egg-info/entry_points.txt
|
|
|
25
24
|
src/throughline_transform.egg-info/requires.txt
|
|
26
25
|
src/throughline_transform.egg-info/top_level.txt
|
|
27
26
|
tests/conftest.py
|
|
28
|
-
tests/test_assistant.py
|
|
29
27
|
tests/test_only.py
|
|
30
28
|
tests/test_outputs.py
|
|
31
29
|
tests/test_surface.py
|
|
@@ -1,133 +0,0 @@
|
|
|
1
|
-
# Copyright (c) 2026 Henry J Grech-Cini
|
|
2
|
-
# SPDX-License-Identifier: Apache-2.0
|
|
3
|
-
"""The graph handed to an assistant that reads a few files and cannot run tl
|
|
4
|
-
(UR-0008, SR-0017, SR-0018).
|
|
5
|
-
|
|
6
|
-
Such an assistant — Microsoft 365 Copilot in a controlled environment reads at
|
|
7
|
-
most fifty files, runs no command and returns only text — has to read the whole
|
|
8
|
-
graph from a handful of files and be told, in those files, how to send changes
|
|
9
|
-
back. This form is a folder: one file per register, each carrying that
|
|
10
|
-
register's items exactly as ``tl dump`` gives them, fingerprint included, and a
|
|
11
|
-
manifest that says what the export was true of, which file holds which
|
|
12
|
-
register, which tl wrote it, and the change-set form ``tl apply`` accepts —
|
|
13
|
-
taken from the tool, never written here, so it cannot drift from what apply
|
|
14
|
-
reads. One file per register because the assistant's cap counts files, not
|
|
15
|
-
items; a folder rather than an archive because an assistant cannot open one.
|
|
16
|
-
|
|
17
|
-
Nothing of an item is reshaped or computed here (NG-0001): the words and the
|
|
18
|
-
fingerprint are the dump's. What this module adds is the file boundaries, the
|
|
19
|
-
wrapping, and the manifest.
|
|
20
|
-
"""
|
|
21
|
-
|
|
22
|
-
from __future__ import annotations
|
|
23
|
-
|
|
24
|
-
import json
|
|
25
|
-
from typing import Any
|
|
26
|
-
|
|
27
|
-
from .model import prefix_of
|
|
28
|
-
from .package import Entry, utf8
|
|
29
|
-
from .provenance import Provenance
|
|
30
|
-
|
|
31
|
-
#: How each file is written: JSON, or Markdown holding one fenced JSON block for
|
|
32
|
-
#: an assistant that will not read a ``.json`` file.
|
|
33
|
-
WRAPS = ("json", "md")
|
|
34
|
-
|
|
35
|
-
#: The version of this form, stated in the manifest.
|
|
36
|
-
FORM_VERSION = 1
|
|
37
|
-
|
|
38
|
-
MANIFEST = "manifest"
|
|
39
|
-
|
|
40
|
-
#: What the manifest tells the assistant to do, beside the form it must write.
|
|
41
|
-
INSTRUCTION = (
|
|
42
|
-
"Read every file named under \"files\" before you answer — each has the same "
|
|
43
|
-
"extension as this manifest: together they are the whole graph as it stood at "
|
|
44
|
-
"the commit named under \"provenance\". Send changes "
|
|
45
|
-
"back as one change set in the form given under \"change_set_format\", quoting "
|
|
46
|
-
"each item's \"fingerprint\" exactly as these files give it. Never send a "
|
|
47
|
-
"rewritten item file, and never a file at all: a change set is text, and the "
|
|
48
|
-
"person who gave you this folder will apply it."
|
|
49
|
-
)
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
def _json(data: dict[str, Any]) -> str:
|
|
53
|
-
return json.dumps(data, indent=2, ensure_ascii=False) + "\n"
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
def _entry(name: str, title: str, data: dict[str, Any], wrap: str, after: str = "") -> Entry:
|
|
57
|
-
"""One file of the folder: the JSON itself, or Markdown holding it in one
|
|
58
|
-
fenced block, with ``after`` — Markdown of its own — following the block."""
|
|
59
|
-
text = _json(data)
|
|
60
|
-
if wrap == "json":
|
|
61
|
-
return (f"{name}.json", utf8(text))
|
|
62
|
-
body = f"# {title}\n\n```json\n{text}```\n"
|
|
63
|
-
if after:
|
|
64
|
-
body += f"\n{after}"
|
|
65
|
-
return (f"{name}.md", utf8(body))
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
def to_assistant(
|
|
69
|
-
dump: dict[str, Any],
|
|
70
|
-
provenance: Provenance,
|
|
71
|
-
change_set_format: str,
|
|
72
|
-
*,
|
|
73
|
-
wrap: str = "json",
|
|
74
|
-
only: tuple[str, ...] = (),
|
|
75
|
-
) -> list[Entry]:
|
|
76
|
-
"""The folder's files, the manifest first.
|
|
77
|
-
|
|
78
|
-
``dump`` is ``tl dump``'s document, unreshaped; ``change_set_format`` is what
|
|
79
|
-
``tl apply --describe`` printed. With ``only``, the register files hold the
|
|
80
|
-
items named and the clauses they cite, and the manifest says how many of how
|
|
81
|
-
many, as every narrowed output does (SR-0016).
|
|
82
|
-
"""
|
|
83
|
-
if wrap not in WRAPS:
|
|
84
|
-
raise ValueError(f"wrap must be one of {', '.join(WRAPS)}, not {wrap!r}")
|
|
85
|
-
items: list[dict[str, Any]] = list(dump.get("items") or [])
|
|
86
|
-
if only:
|
|
87
|
-
keep = set(only)
|
|
88
|
-
own = [i for i in items if not i.get("source") and i["uid"] in keep]
|
|
89
|
-
cited = {link["target"] for i in own for link in i.get("links") or []}
|
|
90
|
-
items = own + [i for i in items if i.get("source") and i["uid"] in cited]
|
|
91
|
-
registers: list[dict[str, Any]] = list(dump.get("registers") or [])
|
|
92
|
-
by_register: dict[str, list[dict[str, Any]]] = {r["prefix"]: [] for r in registers}
|
|
93
|
-
borrowed: dict[str, list[dict[str, Any]]] = {}
|
|
94
|
-
for item in items:
|
|
95
|
-
if item.get("source"):
|
|
96
|
-
borrowed.setdefault(str(item["source"]), []).append(item)
|
|
97
|
-
else:
|
|
98
|
-
by_register.setdefault(prefix_of(item["uid"]), []).append(item)
|
|
99
|
-
|
|
100
|
-
files: list[dict[str, Any]] = []
|
|
101
|
-
entries: list[Entry] = []
|
|
102
|
-
for register in registers:
|
|
103
|
-
prefix = register["prefix"]
|
|
104
|
-
title = register.get("title") or prefix
|
|
105
|
-
held = by_register.get(prefix, [])
|
|
106
|
-
entries.append(_entry(prefix, f"{title} ({prefix})", {"register": register, "items": held}, wrap))
|
|
107
|
-
files.append({"file": prefix, "register": prefix, "title": title, "items": len(held)})
|
|
108
|
-
for namespace, clauses in sorted(borrowed.items()):
|
|
109
|
-
name = f"source-{namespace}"
|
|
110
|
-
entries.append(
|
|
111
|
-
_entry(name, f"Clauses of the adopted source {namespace}", {"source": namespace, "items": clauses}, wrap)
|
|
112
|
-
)
|
|
113
|
-
files.append({"file": name, "source": namespace, "items": len(clauses)})
|
|
114
|
-
|
|
115
|
-
meta = dump.get("throughline_dump") or {}
|
|
116
|
-
# The manifest is the same in either wrapping, so a file is named by its stem:
|
|
117
|
-
# the reader holds the files, and sees their kind.
|
|
118
|
-
manifest: dict[str, Any] = {
|
|
119
|
-
"throughline_assistant_form": FORM_VERSION,
|
|
120
|
-
"provenance": provenance.record(),
|
|
121
|
-
"provenance_lines": provenance.lines(),
|
|
122
|
-
"tl": str(meta.get("tool_version") or "?"),
|
|
123
|
-
"dump_schema_version": meta.get("dump_schema_version"),
|
|
124
|
-
"files": files,
|
|
125
|
-
"config": dump.get("config") or {},
|
|
126
|
-
}
|
|
127
|
-
if dump.get("composition"):
|
|
128
|
-
manifest["composition"] = dump["composition"]
|
|
129
|
-
manifest["instruction"] = INSTRUCTION
|
|
130
|
-
manifest["change_set_format"] = change_set_format
|
|
131
|
-
readable = f"## How to answer\n\n{INSTRUCTION}\n\n{change_set_format}" if wrap == "md" else ""
|
|
132
|
-
entries.insert(0, _entry(MANIFEST, "Manifest", manifest, wrap, readable))
|
|
133
|
-
return entries
|
|
@@ -1,149 +0,0 @@
|
|
|
1
|
-
# Copyright (c) 2026 Henry J Grech-Cini
|
|
2
|
-
# SPDX-License-Identifier: Apache-2.0
|
|
3
|
-
"""The assistant form (UR-0008, SR-0017, SR-0018): one file per register, each
|
|
4
|
-
carrying the register's items exactly as ``tl dump`` gives them, and a manifest
|
|
5
|
-
that says what the folder was true of and how to answer."""
|
|
6
|
-
|
|
7
|
-
from __future__ import annotations
|
|
8
|
-
|
|
9
|
-
import json
|
|
10
|
-
import re
|
|
11
|
-
import subprocess
|
|
12
|
-
import sys
|
|
13
|
-
from pathlib import Path
|
|
14
|
-
|
|
15
|
-
from throughline_transform.assistant import FORM_VERSION, INSTRUCTION, to_assistant
|
|
16
|
-
from throughline_transform.cli import main
|
|
17
|
-
from throughline_transform.project import change_set_format, load, run
|
|
18
|
-
from throughline_transform.provenance import CLEAN, Provenance, provenance_of
|
|
19
|
-
|
|
20
|
-
PROV = Provenance(repository="example/fixture", ref="main", commit="0" * 40, tree=CLEAN, tool="tl 2.2.0")
|
|
21
|
-
FENCE = re.compile(r"^```json\n(.*?)^```\n", re.S | re.M)
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
def _dump(root: Path) -> dict:
|
|
25
|
-
return json.loads(run(root, ["dump"], False))
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
def _folder(root: Path, out: Path, *extra: str) -> dict[str, str]:
|
|
29
|
-
assert main(["assistant", "-C", str(root), "-o", str(out), *extra]) == 0
|
|
30
|
-
assert out.is_dir() and not out.with_suffix(".zip").exists()
|
|
31
|
-
return {p.name: p.read_text(encoding="utf-8") for p in sorted(out.iterdir())}
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
def _block(text: str) -> dict:
|
|
35
|
-
blocks = FENCE.findall(text)
|
|
36
|
-
assert len(blocks) == 1, "one fenced JSON block per file"
|
|
37
|
-
return json.loads(blocks[0])
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
# --- SR-0017: one file per register, the dump's items unreshaped ----------------
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
def test_the_folder_holds_one_file_per_register_and_the_manifest(plain_graph: Path, tmp_path: Path):
|
|
44
|
-
files = _folder(plain_graph, tmp_path / "form")
|
|
45
|
-
dump = _dump(plain_graph)
|
|
46
|
-
prefixes = [r["prefix"] for r in dump["registers"]]
|
|
47
|
-
assert sorted(files) == sorted([f"{p}.json" for p in prefixes] + ["manifest.json"])
|
|
48
|
-
seen = []
|
|
49
|
-
for prefix in prefixes:
|
|
50
|
-
data = json.loads(files[f"{prefix}.json"])
|
|
51
|
-
assert data["register"]["prefix"] == prefix
|
|
52
|
-
for item in data["items"]:
|
|
53
|
-
assert item["uid"].startswith(prefix + "-")
|
|
54
|
-
seen.append(item)
|
|
55
|
-
# every item, and every link on it, appears exactly once and unchanged
|
|
56
|
-
assert sorted(seen, key=lambda i: i["uid"]) == dump["items"]
|
|
57
|
-
assert all("fingerprint" in item for item in seen)
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
def test_md_wrapping_holds_the_same_content_in_one_fenced_block(plain_graph: Path, tmp_path: Path):
|
|
61
|
-
as_json = _folder(plain_graph, tmp_path / "json")
|
|
62
|
-
as_md = _folder(plain_graph, tmp_path / "md", "--wrap", "md")
|
|
63
|
-
assert sorted(as_md) == sorted(n.replace(".json", ".md") for n in as_json)
|
|
64
|
-
for name, text in as_json.items():
|
|
65
|
-
assert _block(as_md[name.replace(".json", ".md")]) == json.loads(text)
|
|
66
|
-
# the manifest's Markdown also states the form in words the assistant can read
|
|
67
|
-
assert "## How to answer" in as_md["manifest.md"] and "`tl apply` accepts" in as_md["manifest.md"]
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
def test_a_composed_graph_lends_its_clauses_in_a_file_of_their_source(composed_graph: Path, tmp_path: Path):
|
|
71
|
-
files = _folder(composed_graph, tmp_path / "form")
|
|
72
|
-
dump = json.loads(run(composed_graph, ["dump"], True))
|
|
73
|
-
assert "source-src.json" in files
|
|
74
|
-
clauses = json.loads(files["source-src.json"])["items"]
|
|
75
|
-
assert [c["uid"] for c in clauses] == [i["uid"] for i in dump["items"] if i.get("source")]
|
|
76
|
-
own = [i for name, text in files.items() if name not in ("manifest.json", "source-src.json")
|
|
77
|
-
for i in json.loads(text)["items"]]
|
|
78
|
-
assert sorted(i["uid"] for i in own) == sorted(i["uid"] for i in dump["items"] if not i.get("source"))
|
|
79
|
-
manifest = json.loads(files["manifest.json"])
|
|
80
|
-
assert any(f.get("source") == "src" for f in manifest["files"])
|
|
81
|
-
assert manifest["composition"]["sources"][0]["namespace"] == "src"
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
def test_only_narrows_the_files_and_the_manifest_says_so(plain_graph: Path, tmp_path: Path):
|
|
85
|
-
graph = load(plain_graph)
|
|
86
|
-
sr1 = graph.by_register["SR"][0].uid
|
|
87
|
-
files = _folder(plain_graph, tmp_path / "form", "--only", sr1)
|
|
88
|
-
held = [i["uid"] for name, text in files.items() if name != "manifest.json" for i in json.loads(text)["items"]]
|
|
89
|
-
assert held == [sr1]
|
|
90
|
-
manifest = json.loads(files["manifest.json"])
|
|
91
|
-
assert manifest["provenance"]["items"] == f"1 of {len(graph.items)}"
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
def test_the_form_is_a_folder_never_an_archive(plain_graph: Path, tmp_path: Path):
|
|
95
|
-
out = tmp_path / "form"
|
|
96
|
-
assert main(["assistant", "-C", str(plain_graph), "-o", str(out), "--folder"]) == 0
|
|
97
|
-
assert out.is_dir()
|
|
98
|
-
assert main(["assistant", "-C", str(plain_graph), "-o", str(tmp_path / "again")]) == 0
|
|
99
|
-
assert (tmp_path / "again").is_dir() and not list(tmp_path.glob("*.zip"))
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
def test_the_same_graph_gives_the_same_bytes(plain_graph: Path, tmp_path: Path):
|
|
103
|
-
first = _folder(plain_graph, tmp_path / "a", "--repository", "x/y", "--ref", "main", "--commit", "0" * 40, "--tree", "clean")
|
|
104
|
-
second = _folder(plain_graph, tmp_path / "b", "--repository", "x/y", "--ref", "main", "--commit", "0" * 40, "--tree", "clean")
|
|
105
|
-
assert first == second
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
# --- SR-0018: the manifest -------------------------------------------------------
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
def test_the_manifest_names_what_the_folder_was_true_of_and_how_to_answer(git_graph: Path, tmp_path: Path):
|
|
112
|
-
files = _folder(git_graph, tmp_path / "form")
|
|
113
|
-
manifest = json.loads(files["manifest.json"])
|
|
114
|
-
expected = provenance_of(git_graph, "x")
|
|
115
|
-
assert manifest["throughline_assistant_form"] == FORM_VERSION
|
|
116
|
-
assert manifest["provenance"]["repository"] == expected.repository == "example/fixture"
|
|
117
|
-
assert manifest["provenance"]["ref"] == expected.ref
|
|
118
|
-
assert manifest["provenance"]["commit"] == expected.commit and len(expected.commit) == 40
|
|
119
|
-
assert manifest["provenance"]["tree"] == expected.tree
|
|
120
|
-
assert manifest["tl"] == load(git_graph).tool_version
|
|
121
|
-
assert {f["register"] for f in manifest["files"]} == {r.prefix for r in load(git_graph).registers}
|
|
122
|
-
assert all((tmp_path / "form" / f"{f['file']}.json").is_file() for f in manifest["files"])
|
|
123
|
-
assert manifest["instruction"] == INSTRUCTION
|
|
124
|
-
assert "fingerprint" in manifest["instruction"] and "change set" in manifest["instruction"]
|
|
125
|
-
# the form is the tool's own words, taken from the command, never written here
|
|
126
|
-
assert manifest["change_set_format"] == change_set_format(git_graph, False)
|
|
127
|
-
described = subprocess.run([str(Path(sys.executable).parent / "tl"), "apply", "--describe"],
|
|
128
|
-
capture_output=True, text=True, encoding="utf-8")
|
|
129
|
-
assert manifest["change_set_format"] == described.stdout
|
|
130
|
-
assert '"op": "amend"' in manifest["change_set_format"]
|
|
131
|
-
assert "config" in manifest and "grounding" in manifest["config"]
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
def test_a_stated_provenance_is_written_as_given(plain_graph: Path, tmp_path: Path):
|
|
135
|
-
files = _folder(plain_graph, tmp_path / "form", "--repository", "octo/graph", "--ref", "main",
|
|
136
|
-
"--commit", "f" * 40, "--tree", "dirty")
|
|
137
|
-
manifest = json.loads(files["manifest.json"])
|
|
138
|
-
assert manifest["provenance"] == {"repository": "octo/graph", "ref": "main", "commit": "f" * 40,
|
|
139
|
-
"tree": "uncommitted changes", "tool": manifest["provenance"]["tool"]}
|
|
140
|
-
assert "Working tree: uncommitted changes" in manifest["provenance_lines"]
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
def test_the_writer_reshapes_nothing(plain_graph: Path):
|
|
144
|
-
dump = _dump(plain_graph)
|
|
145
|
-
entries = dict(to_assistant(dump, PROV, "THE FORM"))
|
|
146
|
-
assert set(entries) == {f"{r['prefix']}.json" for r in dump["registers"]} | {"manifest.json"}
|
|
147
|
-
items = [i for name, data in entries.items() if name != "manifest.json" for i in json.loads(data)["items"]]
|
|
148
|
-
assert sorted(items, key=lambda i: i["uid"]) == dump["items"]
|
|
149
|
-
assert json.loads(entries["manifest.json"])["change_set_format"] == "THE FORM"
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
{throughline_transform-0.6.0 → throughline_transform-0.7.0}/src/throughline_transform/__init__.py
RENAMED
|
File without changes
|
{throughline_transform-0.6.0 → throughline_transform-0.7.0}/src/throughline_transform/blocks.py
RENAMED
|
File without changes
|
{throughline_transform-0.6.0 → throughline_transform-0.7.0}/src/throughline_transform/html.py
RENAMED
|
File without changes
|
{throughline_transform-0.6.0 → throughline_transform-0.7.0}/src/throughline_transform/notes.py
RENAMED
|
File without changes
|
{throughline_transform-0.6.0 → throughline_transform-0.7.0}/src/throughline_transform/office.py
RENAMED
|
File without changes
|
{throughline_transform-0.6.0 → throughline_transform-0.7.0}/src/throughline_transform/package.py
RENAMED
|
File without changes
|
{throughline_transform-0.6.0 → throughline_transform-0.7.0}/src/throughline_transform/progress.py
RENAMED
|
File without changes
|
{throughline_transform-0.6.0 → throughline_transform-0.7.0}/src/throughline_transform/provenance.py
RENAMED
|
File without changes
|
{throughline_transform-0.6.0 → throughline_transform-0.7.0}/src/throughline_transform/shape.py
RENAMED
|
File without changes
|
{throughline_transform-0.6.0 → throughline_transform-0.7.0}/src/throughline_transform/tables.py
RENAMED
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|