throughline-transform 0.1.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- throughline_transform/__init__.py +13 -0
- throughline_transform/blocks.py +156 -0
- throughline_transform/cli.py +155 -0
- throughline_transform/html.py +157 -0
- throughline_transform/markdown.py +82 -0
- throughline_transform/model.py +171 -0
- throughline_transform/notes.py +215 -0
- throughline_transform/office.py +334 -0
- throughline_transform/package.py +70 -0
- throughline_transform/project.py +108 -0
- throughline_transform/provenance.py +91 -0
- throughline_transform/shape.py +32 -0
- throughline_transform/tables.py +165 -0
- throughline_transform-0.1.0.dist-info/METADATA +108 -0
- throughline_transform-0.1.0.dist-info/RECORD +20 -0
- throughline_transform-0.1.0.dist-info/WHEEL +5 -0
- throughline_transform-0.1.0.dist-info/entry_points.txt +3 -0
- throughline_transform-0.1.0.dist-info/licenses/LICENSE +201 -0
- throughline_transform-0.1.0.dist-info/licenses/NOTICE +12 -0
- throughline_transform-0.1.0.dist-info/top_level.txt +1 -0
|
@@ -0,0 +1,171 @@
|
|
|
1
|
+
# Copyright (c) 2026 Henry J Grech-Cini
|
|
2
|
+
# SPDX-License-Identifier: Apache-2.0
|
|
3
|
+
"""The graph as ``tl dump`` exports it (throughline SR-0055).
|
|
4
|
+
|
|
5
|
+
These types describe the tool's own output; nothing here re-derives anything
|
|
6
|
+
about the graph. The one thing computed locally is the reverse link index, which
|
|
7
|
+
is not a rule — it is the same edges read the other way.
|
|
8
|
+
"""
|
|
9
|
+
|
|
10
|
+
from __future__ import annotations
|
|
11
|
+
|
|
12
|
+
from dataclasses import dataclass, field
|
|
13
|
+
from typing import Any
|
|
14
|
+
|
|
15
|
+
|
|
16
|
+
@dataclass(frozen=True)
|
|
17
|
+
class Link:
|
|
18
|
+
target: str
|
|
19
|
+
type: str
|
|
20
|
+
stamp: str | None = None
|
|
21
|
+
|
|
22
|
+
|
|
23
|
+
@dataclass
|
|
24
|
+
class Item:
|
|
25
|
+
uid: str
|
|
26
|
+
type: str
|
|
27
|
+
status: str
|
|
28
|
+
title: str
|
|
29
|
+
text: str | None = None
|
|
30
|
+
rationale: str | None = None
|
|
31
|
+
normative: bool | None = None
|
|
32
|
+
links: list[Link] = field(default_factory=list)
|
|
33
|
+
attrs: dict[str, Any] = field(default_factory=dict)
|
|
34
|
+
#: The namespace a borrowed item came from, as ``tl-compose dump`` states it.
|
|
35
|
+
#: ``None`` on the graph's own items.
|
|
36
|
+
source: str | None = None
|
|
37
|
+
|
|
38
|
+
|
|
39
|
+
@dataclass(frozen=True)
|
|
40
|
+
class Register:
|
|
41
|
+
prefix: str
|
|
42
|
+
digits: int
|
|
43
|
+
title: str
|
|
44
|
+
item_count: int
|
|
45
|
+
|
|
46
|
+
|
|
47
|
+
@dataclass(frozen=True)
|
|
48
|
+
class Source:
|
|
49
|
+
namespace: str
|
|
50
|
+
url: str | None = None
|
|
51
|
+
ref: str | None = None
|
|
52
|
+
subdir: str | None = None
|
|
53
|
+
path: str | None = None
|
|
54
|
+
item_count: int | None = None
|
|
55
|
+
|
|
56
|
+
|
|
57
|
+
@dataclass
|
|
58
|
+
class Graph:
|
|
59
|
+
#: The graph's own items, by UID. Never a borrowed one.
|
|
60
|
+
items: dict[str, Item]
|
|
61
|
+
#: UID -> (from, link type) for every edge pointing at it.
|
|
62
|
+
incoming: dict[str, list[tuple[str, str]]]
|
|
63
|
+
#: Register prefix -> its items, in UID order.
|
|
64
|
+
by_register: dict[str, list[Item]]
|
|
65
|
+
registers: list[Register]
|
|
66
|
+
config: dict[str, Any]
|
|
67
|
+
#: The clauses of every adopted source, by namespace-qualified identifier.
|
|
68
|
+
borrowed: dict[str, Item]
|
|
69
|
+
#: The sources the union was assembled from, in the composer's order.
|
|
70
|
+
sources: list[Source]
|
|
71
|
+
#: What the tool called itself in the dump.
|
|
72
|
+
tool_version: str
|
|
73
|
+
composed: bool
|
|
74
|
+
|
|
75
|
+
|
|
76
|
+
def prefix_of(uid: str) -> str:
|
|
77
|
+
"""A UID's register prefix — the part before the number."""
|
|
78
|
+
dash = uid.rfind("-")
|
|
79
|
+
return uid if dash == -1 else uid[:dash]
|
|
80
|
+
|
|
81
|
+
|
|
82
|
+
def is_borrowed(target: str) -> bool:
|
|
83
|
+
"""A namespace-qualified target names a clause in an adopted source."""
|
|
84
|
+
return ":" in target
|
|
85
|
+
|
|
86
|
+
|
|
87
|
+
def split_borrowed(target: str) -> tuple[str, str]:
|
|
88
|
+
"""``asvs:SR-0003`` -> ``("asvs", "SR-0003")``."""
|
|
89
|
+
colon = target.index(":")
|
|
90
|
+
return target[:colon], target[colon + 1 :]
|
|
91
|
+
|
|
92
|
+
|
|
93
|
+
def _item(raw: dict[str, Any]) -> Item:
|
|
94
|
+
return Item(
|
|
95
|
+
uid=raw["uid"],
|
|
96
|
+
type=raw["type"],
|
|
97
|
+
status=raw["status"],
|
|
98
|
+
title=raw.get("title") or "",
|
|
99
|
+
text=raw.get("text"),
|
|
100
|
+
rationale=raw.get("rationale"),
|
|
101
|
+
normative=raw.get("normative"),
|
|
102
|
+
links=[Link(link["target"], link["type"], link.get("stamp")) for link in raw.get("links") or []],
|
|
103
|
+
attrs=dict(raw.get("attrs") or {}),
|
|
104
|
+
source=raw.get("source"),
|
|
105
|
+
)
|
|
106
|
+
|
|
107
|
+
|
|
108
|
+
def index(dump: dict[str, Any], composed: bool) -> Graph:
|
|
109
|
+
"""Read the tool's export into the shape the writers need."""
|
|
110
|
+
items: dict[str, Item] = {}
|
|
111
|
+
borrowed: dict[str, Item] = {}
|
|
112
|
+
incoming: dict[str, list[tuple[str, str]]] = {}
|
|
113
|
+
for raw in dump.get("items") or []:
|
|
114
|
+
item = _item(raw)
|
|
115
|
+
(borrowed if item.source else items)[item.uid] = item
|
|
116
|
+
for item in items.values():
|
|
117
|
+
for link in item.links:
|
|
118
|
+
incoming.setdefault(link.target, []).append((item.uid, link.type))
|
|
119
|
+
|
|
120
|
+
registers = [
|
|
121
|
+
Register(r["prefix"], int(r.get("digits", 4)), r.get("title") or r["prefix"], int(r.get("item_count", 0)))
|
|
122
|
+
for r in dump.get("registers") or []
|
|
123
|
+
]
|
|
124
|
+
by_register: dict[str, list[Item]] = {r.prefix: [] for r in registers}
|
|
125
|
+
for item in items.values():
|
|
126
|
+
by_register.setdefault(prefix_of(item.uid), []).append(item)
|
|
127
|
+
|
|
128
|
+
composition = dump.get("composition") or {}
|
|
129
|
+
sources = [
|
|
130
|
+
Source(
|
|
131
|
+
namespace=s["namespace"],
|
|
132
|
+
url=s.get("url"),
|
|
133
|
+
ref=s.get("ref"),
|
|
134
|
+
subdir=s.get("subdir"),
|
|
135
|
+
path=s.get("path"),
|
|
136
|
+
item_count=s.get("item_count"),
|
|
137
|
+
)
|
|
138
|
+
for s in composition.get("sources") or []
|
|
139
|
+
]
|
|
140
|
+
meta = dump.get("throughline_dump") or {}
|
|
141
|
+
return Graph(
|
|
142
|
+
items=items,
|
|
143
|
+
incoming=incoming,
|
|
144
|
+
by_register=by_register,
|
|
145
|
+
registers=registers,
|
|
146
|
+
config=dump.get("config") or {},
|
|
147
|
+
borrowed=borrowed,
|
|
148
|
+
sources=sources,
|
|
149
|
+
tool_version=str(meta.get("tool_version") or "?"),
|
|
150
|
+
composed=composed,
|
|
151
|
+
)
|
|
152
|
+
|
|
153
|
+
|
|
154
|
+
def ground_links(graph: Graph) -> list[str]:
|
|
155
|
+
"""The link types that ground an item, as the graph declares them — one matrix each."""
|
|
156
|
+
declared = (graph.config.get("grounding") or {}).get("ground_link_types") or []
|
|
157
|
+
return list(declared) or ["implements"]
|
|
158
|
+
|
|
159
|
+
|
|
160
|
+
def register_titles(graph: Graph) -> dict[str, str]:
|
|
161
|
+
"""Register prefix -> title, for the sections a document groups items under."""
|
|
162
|
+
return {r.prefix: r.title for r in graph.registers}
|
|
163
|
+
|
|
164
|
+
|
|
165
|
+
def source_titles(graph: Graph) -> dict[str, str]:
|
|
166
|
+
"""Namespace -> where the source comes from, for an appendix's subtitle."""
|
|
167
|
+
out: dict[str, str] = {}
|
|
168
|
+
for s in graph.sources:
|
|
169
|
+
parts = [s.url or s.path or "", f"at {s.ref}" if s.ref else "", f"in {s.subdir}/" if s.subdir else ""]
|
|
170
|
+
out[s.namespace] = " ".join(p for p in parts if p)
|
|
171
|
+
return out
|
|
@@ -0,0 +1,215 @@
|
|
|
1
|
+
# Copyright (c) 2026 Henry J Grech-Cini
|
|
2
|
+
# SPDX-License-Identifier: Apache-2.0
|
|
3
|
+
"""The graph as a folder of notes (SR-0009).
|
|
4
|
+
|
|
5
|
+
A note-taking tool such as Obsidian opens a folder of Markdown files as a
|
|
6
|
+
vault, follows ``[[wikilinks]]`` between them in both directions and draws the
|
|
7
|
+
graph they make. This output is that folder: one note per item, one per cited
|
|
8
|
+
clause of an adopted source, and an About note carrying the provenance.
|
|
9
|
+
|
|
10
|
+
The prose is the tool's. The catalogue is written once and cut here at the
|
|
11
|
+
item line, so the words in a note are the words ``tl docs`` publishes. What is
|
|
12
|
+
added is what the tool has no view on: file boundaries, YAML front matter the
|
|
13
|
+
note tool reads as properties, and link syntax.
|
|
14
|
+
"""
|
|
15
|
+
|
|
16
|
+
from __future__ import annotations
|
|
17
|
+
|
|
18
|
+
import json
|
|
19
|
+
import re
|
|
20
|
+
from dataclasses import dataclass, field
|
|
21
|
+
|
|
22
|
+
from .model import Graph, Item, prefix_of, split_borrowed
|
|
23
|
+
from .package import Entry, utf8
|
|
24
|
+
from .provenance import Provenance
|
|
25
|
+
from .shape import IDENTIFIER, ITEM_LINE
|
|
26
|
+
|
|
27
|
+
_HEADING = re.compile(r"^#{1,3}\s+(.*)$")
|
|
28
|
+
|
|
29
|
+
|
|
30
|
+
@dataclass
|
|
31
|
+
class NoteBlock:
|
|
32
|
+
#: The identifier the tool wrote — namespace-qualified for a clause.
|
|
33
|
+
id: str
|
|
34
|
+
#: Every line of the block, the head line first, exactly as written.
|
|
35
|
+
lines: list[str] = field(default_factory=list)
|
|
36
|
+
#: Whether the block came from the mirrored clauses of adopted sources.
|
|
37
|
+
borrowed: bool = False
|
|
38
|
+
|
|
39
|
+
|
|
40
|
+
def blocks_of(markdown: str) -> list[NoteBlock]:
|
|
41
|
+
"""Cut the tool's document into its item blocks.
|
|
42
|
+
|
|
43
|
+
Which section a block sits in is what says whether it is the graph's own
|
|
44
|
+
item or a clause mirrored from a source: the composer qualifies a clause's
|
|
45
|
+
identifier, but the section is the boundary the tool itself drew.
|
|
46
|
+
"""
|
|
47
|
+
blocks: list[NoteBlock] = []
|
|
48
|
+
borrowed = False
|
|
49
|
+
current: NoteBlock | None = None
|
|
50
|
+
for raw in markdown.split("\n"):
|
|
51
|
+
line = raw.rstrip()
|
|
52
|
+
heading = _HEADING.match(line)
|
|
53
|
+
if heading:
|
|
54
|
+
current = None
|
|
55
|
+
borrowed = bool(re.search(r"adopted sources", heading.group(1), re.I))
|
|
56
|
+
continue
|
|
57
|
+
head = ITEM_LINE.match(line)
|
|
58
|
+
if head:
|
|
59
|
+
current = NoteBlock(id=head.group(1), lines=[line], borrowed=borrowed)
|
|
60
|
+
blocks.append(current)
|
|
61
|
+
continue
|
|
62
|
+
if current is not None:
|
|
63
|
+
current.lines.append(line)
|
|
64
|
+
for block in blocks:
|
|
65
|
+
while block.lines and not block.lines[-1]:
|
|
66
|
+
block.lines.pop()
|
|
67
|
+
return blocks
|
|
68
|
+
|
|
69
|
+
|
|
70
|
+
def note_name(identifier: str) -> str:
|
|
71
|
+
"""What a note is called.
|
|
72
|
+
|
|
73
|
+
A note tool links by name, so every name in the vault has to be unique, and
|
|
74
|
+
refuses a colon in one. A clause keeps its namespace so it cannot collide
|
|
75
|
+
with a local item of the same number, with the colon replaced by a space.
|
|
76
|
+
"""
|
|
77
|
+
return identifier.replace(":", " ")
|
|
78
|
+
|
|
79
|
+
|
|
80
|
+
def file_safe(text: str) -> str:
|
|
81
|
+
return re.sub(r'[\\/:*?"<>|#^\[\]]', "", text).strip() or "untitled"
|
|
82
|
+
|
|
83
|
+
|
|
84
|
+
def _folder_of(block: NoteBlock, registers: dict[str, str]) -> str:
|
|
85
|
+
if block.borrowed:
|
|
86
|
+
namespace, _ = split_borrowed(block.id)
|
|
87
|
+
return f"sources/{file_safe(namespace)}"
|
|
88
|
+
prefix = prefix_of(block.id)
|
|
89
|
+
return file_safe(registers.get(prefix, prefix))
|
|
90
|
+
|
|
91
|
+
|
|
92
|
+
def scalar(value: object) -> str:
|
|
93
|
+
"""A YAML scalar the note tool reads back as what it was.
|
|
94
|
+
|
|
95
|
+
Every string is double-quoted through JSON, which is a valid YAML
|
|
96
|
+
double-quoted scalar, so a title holding a colon or a hash cannot change
|
|
97
|
+
the document's shape.
|
|
98
|
+
"""
|
|
99
|
+
if isinstance(value, bool):
|
|
100
|
+
return "true" if value else "false"
|
|
101
|
+
if isinstance(value, (int, float)):
|
|
102
|
+
return str(value)
|
|
103
|
+
if value is None:
|
|
104
|
+
return '""'
|
|
105
|
+
return json.dumps(str(value), ensure_ascii=False)
|
|
106
|
+
|
|
107
|
+
|
|
108
|
+
def _key(name: str) -> str:
|
|
109
|
+
return name if re.match(r"^[A-Za-z_][A-Za-z0-9_-]*$", name) else json.dumps(name)
|
|
110
|
+
|
|
111
|
+
|
|
112
|
+
def front_matter(item: Item, identifier: str, reference: str | None = None) -> str:
|
|
113
|
+
lines = ["---", f"uid: {scalar(identifier)}"]
|
|
114
|
+
if reference:
|
|
115
|
+
lines.append(f"reference: {scalar(reference)}")
|
|
116
|
+
if item.source:
|
|
117
|
+
lines.append(f"source: {scalar(item.source)}")
|
|
118
|
+
lines += [f"type: {scalar(item.type)}", f"status: {scalar(item.status)}"]
|
|
119
|
+
if item.normative is not None:
|
|
120
|
+
lines.append(f"normative: {scalar(item.normative)}")
|
|
121
|
+
for name, value in item.attrs.items():
|
|
122
|
+
if isinstance(value, list):
|
|
123
|
+
lines.append(f"{_key(name)}:")
|
|
124
|
+
lines += [f" - {scalar(v)}" for v in value]
|
|
125
|
+
else:
|
|
126
|
+
lines.append(f"{_key(name)}: {scalar(value)}")
|
|
127
|
+
lines += ["aliases:", f" - {scalar(item.title)}"]
|
|
128
|
+
lines += ["tags:", f" - {scalar(f'type/{item.type}')}", f" - {scalar(f'status/{item.status}')}"]
|
|
129
|
+
lines.append("---")
|
|
130
|
+
return "\n".join(lines)
|
|
131
|
+
|
|
132
|
+
|
|
133
|
+
def wikilink(line: str, own: str, names: dict[str, str]) -> str:
|
|
134
|
+
"""Turn every identifier that names a note in this export into a link to it.
|
|
135
|
+
|
|
136
|
+
A bracket pair the tool wrote is prose, not a link — an item that says
|
|
137
|
+
"declare it in [[sources]]" means the TOML table — so it is escaped first.
|
|
138
|
+
A note never links to itself. A clause link shows the identifier the tool
|
|
139
|
+
wrote as its text.
|
|
140
|
+
"""
|
|
141
|
+
line = line.replace("[[", "\\[\\[").replace("]]", "\\]\\]")
|
|
142
|
+
|
|
143
|
+
def link(match: re.Match[str]) -> str:
|
|
144
|
+
identifier = match.group(0)
|
|
145
|
+
name = names.get(identifier)
|
|
146
|
+
if name is None or identifier == own:
|
|
147
|
+
return identifier
|
|
148
|
+
return f"[[{identifier}]]" if name == identifier else f"[[{name}|{identifier}]]"
|
|
149
|
+
|
|
150
|
+
return IDENTIFIER.sub(link, line)
|
|
151
|
+
|
|
152
|
+
|
|
153
|
+
def to_notes(markdown: str, graph: Graph, provenance: Provenance, folder: str = "") -> list[Entry]:
|
|
154
|
+
"""The notes, as the files of the folder. ``folder`` prefixes every path when set."""
|
|
155
|
+
blocks = blocks_of(markdown)
|
|
156
|
+
registers = {r.prefix: r.title for r in graph.registers}
|
|
157
|
+
names = {block.id: note_name(block.id) for block in blocks}
|
|
158
|
+
prefix = f"{folder}/" if folder else ""
|
|
159
|
+
|
|
160
|
+
entries: list[Entry] = []
|
|
161
|
+
for block in blocks:
|
|
162
|
+
item = graph.borrowed.get(block.id) if block.borrowed else graph.items.get(block.id)
|
|
163
|
+
if item is None:
|
|
164
|
+
# Two readings of one graph disagree; an export that quietly
|
|
165
|
+
# dropped the block would hide it.
|
|
166
|
+
raise ValueError(f"the tool wrote {block.id}, which is not in the graph's export")
|
|
167
|
+
head = ITEM_LINE.match(block.lines[0])
|
|
168
|
+
reference = head.group(2) if head else None
|
|
169
|
+
body = "\n".join(wikilink(line, block.id, names) for line in block.lines)
|
|
170
|
+
entries.append(
|
|
171
|
+
(
|
|
172
|
+
f"{prefix}{_folder_of(block, registers)}/{note_name(block.id)}.md",
|
|
173
|
+
utf8(f"{front_matter(item, block.id, reference)}\n{body}\n"),
|
|
174
|
+
)
|
|
175
|
+
)
|
|
176
|
+
entries.append((f"{prefix}About this export.md", utf8(_about(provenance, blocks))))
|
|
177
|
+
return entries
|
|
178
|
+
|
|
179
|
+
|
|
180
|
+
def _about(p: Provenance, blocks: list[NoteBlock]) -> str:
|
|
181
|
+
items = sum(1 for b in blocks if not b.borrowed)
|
|
182
|
+
clauses = len(blocks) - items
|
|
183
|
+
plural = lambda n, word: f"{n} {word}{'' if n == 1 else 's'}" # noqa: E731
|
|
184
|
+
held = f"This export holds {plural(items, 'item')}"
|
|
185
|
+
held += (
|
|
186
|
+
f" and {plural(clauses, 'cited clause')} of adopted sources, under `sources`."
|
|
187
|
+
if clauses
|
|
188
|
+
else "."
|
|
189
|
+
)
|
|
190
|
+
return "\n".join(
|
|
191
|
+
[
|
|
192
|
+
"---",
|
|
193
|
+
f"repository: {scalar(p.repository)}",
|
|
194
|
+
f"ref: {scalar(p.ref or None)}",
|
|
195
|
+
f"commit: {scalar(p.commit or None)}",
|
|
196
|
+
f"working_tree: {scalar(p.tree)}",
|
|
197
|
+
f"produced_by: {scalar(p.tool)}",
|
|
198
|
+
"---",
|
|
199
|
+
f"# {p.repository} — requirements",
|
|
200
|
+
"",
|
|
201
|
+
*[f"- {line}" for line in p.lines()],
|
|
202
|
+
"",
|
|
203
|
+
"Open this folder as a vault. Each note is one item of the intent graph, in a "
|
|
204
|
+
"folder named for its register, and every link between items is a link between "
|
|
205
|
+
"notes. The graph view draws the whole intent graph from them; a note's backlinks "
|
|
206
|
+
"list what rests on it. Type and status are tags, so the graph can be filtered by "
|
|
207
|
+
"either.",
|
|
208
|
+
"",
|
|
209
|
+
held,
|
|
210
|
+
"",
|
|
211
|
+
"The words of every note are the ones the tool publishes; this folder is a record "
|
|
212
|
+
"of the graph as it stood, not a copy to edit.",
|
|
213
|
+
"",
|
|
214
|
+
]
|
|
215
|
+
)
|