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.
Files changed (34) hide show
  1. {throughline_transform-0.6.0/src/throughline_transform.egg-info → throughline_transform-0.7.0}/PKG-INFO +2 -4
  2. {throughline_transform-0.6.0 → throughline_transform-0.7.0}/README.md +0 -2
  3. {throughline_transform-0.6.0 → throughline_transform-0.7.0}/pyproject.toml +2 -2
  4. {throughline_transform-0.6.0 → throughline_transform-0.7.0}/src/throughline_transform/cli.py +5 -23
  5. {throughline_transform-0.6.0 → throughline_transform-0.7.0}/src/throughline_transform/markdown.py +0 -3
  6. {throughline_transform-0.6.0 → throughline_transform-0.7.0}/src/throughline_transform/model.py +0 -4
  7. {throughline_transform-0.6.0 → throughline_transform-0.7.0}/src/throughline_transform/project.py +0 -8
  8. {throughline_transform-0.6.0 → throughline_transform-0.7.0/src/throughline_transform.egg-info}/PKG-INFO +2 -4
  9. {throughline_transform-0.6.0 → throughline_transform-0.7.0}/src/throughline_transform.egg-info/SOURCES.txt +0 -2
  10. throughline_transform-0.7.0/src/throughline_transform.egg-info/requires.txt +4 -0
  11. throughline_transform-0.6.0/src/throughline_transform/assistant.py +0 -133
  12. throughline_transform-0.6.0/src/throughline_transform.egg-info/requires.txt +0 -4
  13. throughline_transform-0.6.0/tests/test_assistant.py +0 -149
  14. {throughline_transform-0.6.0 → throughline_transform-0.7.0}/LICENSE +0 -0
  15. {throughline_transform-0.6.0 → throughline_transform-0.7.0}/MANIFEST.in +0 -0
  16. {throughline_transform-0.6.0 → throughline_transform-0.7.0}/NOTICE +0 -0
  17. {throughline_transform-0.6.0 → throughline_transform-0.7.0}/setup.cfg +0 -0
  18. {throughline_transform-0.6.0 → throughline_transform-0.7.0}/src/throughline_transform/__init__.py +0 -0
  19. {throughline_transform-0.6.0 → throughline_transform-0.7.0}/src/throughline_transform/blocks.py +0 -0
  20. {throughline_transform-0.6.0 → throughline_transform-0.7.0}/src/throughline_transform/html.py +0 -0
  21. {throughline_transform-0.6.0 → throughline_transform-0.7.0}/src/throughline_transform/notes.py +0 -0
  22. {throughline_transform-0.6.0 → throughline_transform-0.7.0}/src/throughline_transform/office.py +0 -0
  23. {throughline_transform-0.6.0 → throughline_transform-0.7.0}/src/throughline_transform/package.py +0 -0
  24. {throughline_transform-0.6.0 → throughline_transform-0.7.0}/src/throughline_transform/progress.py +0 -0
  25. {throughline_transform-0.6.0 → throughline_transform-0.7.0}/src/throughline_transform/provenance.py +0 -0
  26. {throughline_transform-0.6.0 → throughline_transform-0.7.0}/src/throughline_transform/shape.py +0 -0
  27. {throughline_transform-0.6.0 → throughline_transform-0.7.0}/src/throughline_transform/tables.py +0 -0
  28. {throughline_transform-0.6.0 → throughline_transform-0.7.0}/src/throughline_transform.egg-info/dependency_links.txt +0 -0
  29. {throughline_transform-0.6.0 → throughline_transform-0.7.0}/src/throughline_transform.egg-info/entry_points.txt +0 -0
  30. {throughline_transform-0.6.0 → throughline_transform-0.7.0}/src/throughline_transform.egg-info/top_level.txt +0 -0
  31. {throughline_transform-0.6.0 → throughline_transform-0.7.0}/tests/conftest.py +0 -0
  32. {throughline_transform-0.6.0 → throughline_transform-0.7.0}/tests/test_only.py +0 -0
  33. {throughline_transform-0.6.0 → throughline_transform-0.7.0}/tests/test_outputs.py +0 -0
  34. {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.6.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.18.0
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.6.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.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)
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"]
@@ -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, change_set_format, find_graph, load
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", "assistant")
41
+ FORMATS = ("md", "notes", "csv", "xlsx", "docx", "html", "blocks")
44
42
  PROSE = ("md", "docx", "html", "blocks")
45
- FOLDERS = ("notes", "csv", "assistant")
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 or args.format in FOLDER_ONLY)
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
@@ -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, ...] = ()
@@ -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
 
@@ -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.6.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.18.0
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
@@ -0,0 +1,4 @@
1
+ throughline>=3.11.1
2
+
3
+ [dev]
4
+ pytest>=8.0
@@ -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,4 +0,0 @@
1
- throughline>=3.18.0
2
-
3
- [dev]
4
- pytest>=8.0
@@ -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"