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.
@@ -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
+ )