throughline-transform 0.5.0__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.5.0/src/throughline_transform.egg-info → throughline_transform-0.6.0}/PKG-INFO +4 -2
- {throughline_transform-0.5.0 → throughline_transform-0.6.0}/README.md +2 -0
- {throughline_transform-0.5.0 → throughline_transform-0.6.0}/pyproject.toml +2 -2
- throughline_transform-0.6.0/src/throughline_transform/assistant.py +133 -0
- {throughline_transform-0.5.0 → throughline_transform-0.6.0}/src/throughline_transform/cli.py +23 -5
- {throughline_transform-0.5.0 → throughline_transform-0.6.0}/src/throughline_transform/markdown.py +3 -0
- {throughline_transform-0.5.0 → throughline_transform-0.6.0}/src/throughline_transform/model.py +4 -0
- {throughline_transform-0.5.0 → throughline_transform-0.6.0}/src/throughline_transform/project.py +8 -0
- {throughline_transform-0.5.0 → throughline_transform-0.6.0/src/throughline_transform.egg-info}/PKG-INFO +4 -2
- {throughline_transform-0.5.0 → throughline_transform-0.6.0}/src/throughline_transform.egg-info/SOURCES.txt +2 -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.5.0/src/throughline_transform.egg-info/requires.txt +0 -4
- {throughline_transform-0.5.0 → throughline_transform-0.6.0}/LICENSE +0 -0
- {throughline_transform-0.5.0 → throughline_transform-0.6.0}/MANIFEST.in +0 -0
- {throughline_transform-0.5.0 → throughline_transform-0.6.0}/NOTICE +0 -0
- {throughline_transform-0.5.0 → throughline_transform-0.6.0}/setup.cfg +0 -0
- {throughline_transform-0.5.0 → throughline_transform-0.6.0}/src/throughline_transform/__init__.py +0 -0
- {throughline_transform-0.5.0 → throughline_transform-0.6.0}/src/throughline_transform/blocks.py +0 -0
- {throughline_transform-0.5.0 → throughline_transform-0.6.0}/src/throughline_transform/html.py +0 -0
- {throughline_transform-0.5.0 → throughline_transform-0.6.0}/src/throughline_transform/notes.py +0 -0
- {throughline_transform-0.5.0 → throughline_transform-0.6.0}/src/throughline_transform/office.py +0 -0
- {throughline_transform-0.5.0 → throughline_transform-0.6.0}/src/throughline_transform/package.py +0 -0
- {throughline_transform-0.5.0 → throughline_transform-0.6.0}/src/throughline_transform/progress.py +0 -0
- {throughline_transform-0.5.0 → throughline_transform-0.6.0}/src/throughline_transform/provenance.py +0 -0
- {throughline_transform-0.5.0 → throughline_transform-0.6.0}/src/throughline_transform/shape.py +0 -0
- {throughline_transform-0.5.0 → throughline_transform-0.6.0}/src/throughline_transform/tables.py +0 -0
- {throughline_transform-0.5.0 → throughline_transform-0.6.0}/src/throughline_transform.egg-info/dependency_links.txt +0 -0
- {throughline_transform-0.5.0 → throughline_transform-0.6.0}/src/throughline_transform.egg-info/entry_points.txt +0 -0
- {throughline_transform-0.5.0 → throughline_transform-0.6.0}/src/throughline_transform.egg-info/top_level.txt +0 -0
- {throughline_transform-0.5.0 → throughline_transform-0.6.0}/tests/conftest.py +0 -0
- {throughline_transform-0.5.0 → throughline_transform-0.6.0}/tests/test_only.py +0 -0
- {throughline_transform-0.5.0 → throughline_transform-0.6.0}/tests/test_outputs.py +0 -0
- {throughline_transform-0.5.0 → throughline_transform-0.6.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.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
|
|
@@ -85,6 +86,7 @@ second, and is run as a command — its command line is the surface it publishes
|
|
|
85
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. |
|
|
86
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. |
|
|
87
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. |
|
|
88
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. |
|
|
89
91
|
|
|
90
92
|
Every output carries the repository, ref, commit, working-tree state and tool
|
|
@@ -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
|
|
@@ -57,6 +58,7 @@ second, and is run as a command — its command line is the surface it publishes
|
|
|
57
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. |
|
|
58
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. |
|
|
59
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. |
|
|
60
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. |
|
|
61
63
|
|
|
62
64
|
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.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"
|
|
@@ -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.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.5.0 → throughline_transform-0.6.0}/src/throughline_transform/cli.py
RENAMED
|
@@ -9,6 +9,7 @@
|
|
|
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
15
|
provenance instead of reading git (SR-0013), and --only UID[,UID…] to hold
|
|
@@ -28,19 +29,22 @@ from throughline.version import distribution_version as _v
|
|
|
28
29
|
|
|
29
30
|
from . import markdown as md
|
|
30
31
|
from .blocks import as_blocks, to_json
|
|
32
|
+
from .assistant import WRAPS, to_assistant
|
|
31
33
|
from .html import to_html
|
|
32
34
|
from .model import Graph, narrowed, register_titles, source_titles
|
|
33
35
|
from .notes import to_notes
|
|
34
36
|
from .office import to_docx, to_xlsx
|
|
35
37
|
from .package import Entry, archive, unpack, utf8
|
|
36
38
|
from .progress import slow
|
|
37
|
-
from .project import TransformError, find_graph, load
|
|
39
|
+
from .project import TransformError, change_set_format, find_graph, load
|
|
38
40
|
from .provenance import TREE_WORDS, Provenance, provenance_of, stated
|
|
39
41
|
from .tables import Table, cited_sources, file_name, links_of, per_register, to_csv, whole_graph
|
|
40
42
|
|
|
41
|
-
FORMATS = ("md", "notes", "csv", "xlsx", "docx", "html", "blocks")
|
|
43
|
+
FORMATS = ("md", "notes", "csv", "xlsx", "docx", "html", "blocks", "assistant")
|
|
42
44
|
PROSE = ("md", "docx", "html", "blocks")
|
|
43
|
-
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",)
|
|
44
48
|
|
|
45
49
|
|
|
46
50
|
def version_string() -> str:
|
|
@@ -66,6 +70,12 @@ def build_parser() -> argparse.ArgumentParser:
|
|
|
66
70
|
p.add_argument("--matrix", action="store_true", help="md, docx, html, blocks: add a traceability matrix per grounding link")
|
|
67
71
|
p.add_argument("--no-stats", dest="stats", action="store_false", help="md, docx, html, blocks: leave out the tool's summary")
|
|
68
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
|
+
)
|
|
69
79
|
p.add_argument("--repository", metavar="OWNER/NAME", help="state the repository instead of reading git")
|
|
70
80
|
p.add_argument("--ref", metavar="REF", help="state the ref instead of reading git")
|
|
71
81
|
p.add_argument("--commit", metavar="SHA", help="state the commit instead of reading git")
|
|
@@ -124,6 +134,12 @@ def produce(graph: Graph, root: Path, fmt: str, opts: md.Options, provenance: Pr
|
|
|
124
134
|
return utf8(to_json(blocks, provenance.lines(), provenance.record())), f"{stem}-blocks.json"
|
|
125
135
|
return utf8(to_html(blocks, provenance)), f"{stem}.html"
|
|
126
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
|
+
|
|
127
143
|
if fmt == "notes":
|
|
128
144
|
text = md.to_markdown(
|
|
129
145
|
root, graph, replace(opts, body="catalog", matrix=False, stats=False, markers=False), provenance
|
|
@@ -169,7 +185,9 @@ def main(argv: list[str] | None = None) -> int:
|
|
|
169
185
|
only = named(args.only)
|
|
170
186
|
if args.only is not None and not only:
|
|
171
187
|
parser.error("--only names no item")
|
|
172
|
-
opts = md.Options(
|
|
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
|
+
)
|
|
173
191
|
try:
|
|
174
192
|
root = find_graph(args.directory)
|
|
175
193
|
graph = load(root)
|
|
@@ -191,7 +209,7 @@ def main(argv: list[str] | None = None) -> int:
|
|
|
191
209
|
provenance = replace(provenance, items=f"{len(only)} of {len(graph.items)}")
|
|
192
210
|
result, default = produce(graph, root, args.format, opts, provenance)
|
|
193
211
|
with slow(f"still writing {args.output or default}…"):
|
|
194
|
-
target = write(result, default, args.output, args.folder)
|
|
212
|
+
target = write(result, default, args.output, args.folder or args.format in FOLDER_ONLY)
|
|
195
213
|
except (TransformError, OSError, ValueError) as exc:
|
|
196
214
|
print(f"tl-transform: {exc}", file=sys.stderr)
|
|
197
215
|
return 1
|
{throughline_transform-0.5.0 → throughline_transform-0.6.0}/src/throughline_transform/markdown.py
RENAMED
|
@@ -31,6 +31,9 @@ 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"
|
|
34
37
|
#: The items the output holds, where the caller named them (SR-0016);
|
|
35
38
|
#: empty for every item.
|
|
36
39
|
only: tuple[str, ...] = ()
|
{throughline_transform-0.5.0 → throughline_transform-0.6.0}/src/throughline_transform/model.py
RENAMED
|
@@ -72,6 +72,9 @@ 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)
|
|
75
78
|
|
|
76
79
|
|
|
77
80
|
def prefix_of(uid: str) -> str:
|
|
@@ -149,6 +152,7 @@ def index(dump: dict[str, Any], composed: bool) -> Graph:
|
|
|
149
152
|
sources=sources,
|
|
150
153
|
tool_version=str(meta.get("tool_version") or "?"),
|
|
151
154
|
composed=composed,
|
|
155
|
+
raw=dump,
|
|
152
156
|
)
|
|
153
157
|
|
|
154
158
|
|
{throughline_transform-0.5.0 → 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
|
|
|
@@ -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
|
|
@@ -85,6 +86,7 @@ second, and is run as a command — its command line is the surface it publishes
|
|
|
85
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. |
|
|
86
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. |
|
|
87
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. |
|
|
88
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. |
|
|
89
91
|
|
|
90
92
|
Every output carries the repository, ref, commit, working-tree state and tool
|
|
@@ -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,6 +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
|
|
27
29
|
tests/test_only.py
|
|
28
30
|
tests/test_outputs.py
|
|
29
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"
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
{throughline_transform-0.5.0 → throughline_transform-0.6.0}/src/throughline_transform/__init__.py
RENAMED
|
File without changes
|
{throughline_transform-0.5.0 → throughline_transform-0.6.0}/src/throughline_transform/blocks.py
RENAMED
|
File without changes
|
{throughline_transform-0.5.0 → throughline_transform-0.6.0}/src/throughline_transform/html.py
RENAMED
|
File without changes
|
{throughline_transform-0.5.0 → throughline_transform-0.6.0}/src/throughline_transform/notes.py
RENAMED
|
File without changes
|
{throughline_transform-0.5.0 → throughline_transform-0.6.0}/src/throughline_transform/office.py
RENAMED
|
File without changes
|
{throughline_transform-0.5.0 → throughline_transform-0.6.0}/src/throughline_transform/package.py
RENAMED
|
File without changes
|
{throughline_transform-0.5.0 → throughline_transform-0.6.0}/src/throughline_transform/progress.py
RENAMED
|
File without changes
|
{throughline_transform-0.5.0 → throughline_transform-0.6.0}/src/throughline_transform/provenance.py
RENAMED
|
File without changes
|
{throughline_transform-0.5.0 → throughline_transform-0.6.0}/src/throughline_transform/shape.py
RENAMED
|
File without changes
|
{throughline_transform-0.5.0 → throughline_transform-0.6.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
|