tracecite 0.0.2__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.
- tracecite/__init__.py +35 -0
- tracecite/__main__.py +3 -0
- tracecite/cli.py +656 -0
- tracecite/docs/__init__.py +56 -0
- tracecite/docs/build.py +381 -0
- tracecite/docs/config.py +114 -0
- tracecite/docs/contract.py +17 -0
- tracecite/docs/modes.py +240 -0
- tracecite/docs/stage.py +407 -0
- tracecite/docs/vectorize.py +457 -0
- tracecite/evidence/__init__.py +3 -0
- tracecite/evidence/chunking.py +214 -0
- tracecite/evidence/commands.py +552 -0
- tracecite/evidence/config.py +49 -0
- tracecite/evidence/embedding.py +59 -0
- tracecite/evidence/manifest.py +197 -0
- tracecite/evidence/page_extraction.py +200 -0
- tracecite/evidence/page_output.py +80 -0
- tracecite/evidence/page_selection.py +116 -0
- tracecite/evidence/parsers/__init__.py +1 -0
- tracecite/evidence/parsers/base.py +65 -0
- tracecite/evidence/parsers/markdown.py +142 -0
- tracecite/evidence/parsers/pdf.py +315 -0
- tracecite/evidence/parsers/workbook.py +334 -0
- tracecite/evidence/paths.py +94 -0
- tracecite/evidence/schema.py +570 -0
- tracecite/evidence/source_links.py +185 -0
- tracecite/evidence/sync.py +1434 -0
- tracecite/evidence/vector_backend.py +130 -0
- tracecite/evidence/verify.py +368 -0
- tracecite/skills/routing-documentation-source-links/SKILL.md +167 -0
- tracecite/skills/routing-documentation-source-links/agents/openai.yaml +3 -0
- tracecite/skills/routing-documentation-source-links/references/documenter-integration.md +71 -0
- tracecite/skills/routing-documentation-source-links/references/registry-contract.md +86 -0
- tracecite/skills/routing-documentation-source-links/references/staging-and-rewriting.md +118 -0
- tracecite/skills/routing-documentation-source-links/references/validation-and-failure-modes.md +67 -0
- tracecite/skills/using-tracecite/SKILL.md +97 -0
- tracecite/skills/using-tracecite/agents/openai.yaml +3 -0
- tracecite/skills/using-tracecite/references/architecture.md +68 -0
- tracecite/skills/using-tracecite/references/pdf-and-assets.md +67 -0
- tracecite/skills/using-tracecite/references/retrieval.md +45 -0
- tracecite/skills/using-tracecite/references/schema-and-migrations.md +52 -0
- tracecite/skills/using-tracecite/references/synchronisation.md +98 -0
- tracecite/skills/using-tracecite/references/workspace-runtime.md +44 -0
- tracecite/skills/writing-evidence-backed-reports/SKILL.md +91 -0
- tracecite/skills/writing-evidence-backed-reports/agents/openai.yaml +3 -0
- tracecite/skills/writing-evidence-backed-reports/fixtures/README.md +13 -0
- tracecite/skills/writing-evidence-backed-reports/fixtures/reports/invalid-bad-path.md +5 -0
- tracecite/skills/writing-evidence-backed-reports/fixtures/reports/invalid-grammar.md +8 -0
- tracecite/skills/writing-evidence-backed-reports/fixtures/reports/invalid-missing-definition.md +3 -0
- tracecite/skills/writing-evidence-backed-reports/fixtures/reports/invalid-page-not-indexed.md +5 -0
- tracecite/skills/writing-evidence-backed-reports/fixtures/reports/invalid-unindexed-path.md +5 -0
- tracecite/skills/writing-evidence-backed-reports/fixtures/reports/valid-grammar.md +12 -0
- tracecite/skills/writing-evidence-backed-reports/fixtures/reports/valid-report.md +27 -0
- tracecite/skills/writing-evidence-backed-reports/fixtures/source-links.toml +17 -0
- tracecite/skills/writing-evidence-backed-reports/fixtures/validate_fixtures.py +295 -0
- tracecite/skills/writing-evidence-backed-reports/references/images-and-source-links.md +34 -0
- tracecite/skills/writing-evidence-backed-reports/references/quotation-and-verification.md +43 -0
- tracecite/skills/writing-evidence-backed-reports/references/reference-style-citations.md +48 -0
- tracecite/skills/writing-evidence-backed-reports/references/report-structure.md +58 -0
- tracecite/tables/__init__.py +41 -0
- tracecite/tables/_text.py +142 -0
- tracecite/tables/document.py +582 -0
- tracecite/tables/html.py +299 -0
- tracecite/tables/models.py +119 -0
- tracecite/tables/normalise.py +786 -0
- tracecite/tables/pandoc.py +503 -0
- tracecite/tables/publish.py +238 -0
- tracecite/tables/render.py +128 -0
- tracecite/tables/site.py +457 -0
- tracecite-0.0.2.dist-info/METADATA +320 -0
- tracecite-0.0.2.dist-info/RECORD +76 -0
- tracecite-0.0.2.dist-info/WHEEL +5 -0
- tracecite-0.0.2.dist-info/entry_points.txt +2 -0
- tracecite-0.0.2.dist-info/licenses/LICENSE +21 -0
- tracecite-0.0.2.dist-info/top_level.txt +1 -0
|
@@ -0,0 +1,185 @@
|
|
|
1
|
+
"""Lightweight schema-v3 source-link registry and destination parsing.
|
|
2
|
+
|
|
3
|
+
The registry maps one stable local ``.pdf`` or ``.md`` source path to a
|
|
4
|
+
public HTTPS destination for documentation-link routing and report-source
|
|
5
|
+
validation. It intentionally carries only ``name``, ``local_path``, and
|
|
6
|
+
``public_url`` plus an opaque optional ``metadata`` table; it is not a
|
|
7
|
+
bibliography, citation-key, or remote-ingestion system.
|
|
8
|
+
"""
|
|
9
|
+
|
|
10
|
+
from __future__ import annotations
|
|
11
|
+
|
|
12
|
+
import re
|
|
13
|
+
import tomllib
|
|
14
|
+
from dataclasses import dataclass, field
|
|
15
|
+
from pathlib import Path
|
|
16
|
+
from typing import Any
|
|
17
|
+
from urllib.parse import urlparse
|
|
18
|
+
|
|
19
|
+
from .paths import PathAuthorityError, normalise_source_path
|
|
20
|
+
|
|
21
|
+
SCHEMA_VERSION = 3
|
|
22
|
+
|
|
23
|
+
_SOURCE_LINK_REQUIRED = {"name", "local_path", "public_url"}
|
|
24
|
+
_SOURCE_LINK_OPTIONAL = {"metadata"}
|
|
25
|
+
_ROUTABLE_EXTENSIONS = (".pdf", ".md")
|
|
26
|
+
|
|
27
|
+
|
|
28
|
+
@dataclass(frozen=True)
|
|
29
|
+
class SourceLinkEntry:
|
|
30
|
+
name: str
|
|
31
|
+
local_path: str
|
|
32
|
+
public_url: str
|
|
33
|
+
metadata: dict[str, Any] = field(default_factory=dict)
|
|
34
|
+
|
|
35
|
+
|
|
36
|
+
def load_source_links(
|
|
37
|
+
path: Path, source_links_root: Path
|
|
38
|
+
) -> tuple[dict[Path, list[SourceLinkEntry]], list[str]]:
|
|
39
|
+
with Path(path).open("rb") as handle:
|
|
40
|
+
data = tomllib.load(handle)
|
|
41
|
+
issues: list[str] = []
|
|
42
|
+
if data.get("schema_version") != SCHEMA_VERSION:
|
|
43
|
+
return {}, [f"{path} requires schema_version = {SCHEMA_VERSION}"]
|
|
44
|
+
source_entries = data.get("source", [])
|
|
45
|
+
if not isinstance(source_entries, list):
|
|
46
|
+
return {}, [f"{path} field source must be an array of tables"]
|
|
47
|
+
registry: dict[Path, list[SourceLinkEntry]] = {}
|
|
48
|
+
seen_paths: set[Path] = set()
|
|
49
|
+
seen_names: set[str] = set()
|
|
50
|
+
for index, entry in enumerate(source_entries, start=1):
|
|
51
|
+
if not isinstance(entry, dict):
|
|
52
|
+
issues.append(f"source entry {index} must be a table")
|
|
53
|
+
continue
|
|
54
|
+
keys = set(entry)
|
|
55
|
+
unknown = keys - _SOURCE_LINK_REQUIRED - _SOURCE_LINK_OPTIONAL
|
|
56
|
+
missing = _SOURCE_LINK_REQUIRED - keys
|
|
57
|
+
if unknown:
|
|
58
|
+
issues.append(
|
|
59
|
+
f"source entry {index} has unknown field(s): {', '.join(sorted(unknown))}"
|
|
60
|
+
)
|
|
61
|
+
continue
|
|
62
|
+
if missing:
|
|
63
|
+
issues.append(
|
|
64
|
+
f"source entry {index} missing required field(s): {', '.join(sorted(missing))}"
|
|
65
|
+
)
|
|
66
|
+
continue
|
|
67
|
+
invalid_fields = [
|
|
68
|
+
field_name
|
|
69
|
+
for field_name in sorted(_SOURCE_LINK_REQUIRED)
|
|
70
|
+
if not isinstance(entry[field_name], str) or not entry[field_name].strip()
|
|
71
|
+
]
|
|
72
|
+
if invalid_fields:
|
|
73
|
+
issues.extend(
|
|
74
|
+
f"source entry {index} field {field_name} must be a non-empty string"
|
|
75
|
+
for field_name in invalid_fields
|
|
76
|
+
)
|
|
77
|
+
continue
|
|
78
|
+
metadata = entry.get("metadata", {})
|
|
79
|
+
if not isinstance(metadata, dict):
|
|
80
|
+
issues.append(f"source entry {index} field metadata must be a table")
|
|
81
|
+
continue
|
|
82
|
+
if any(character in entry["local_path"] for character in "?#"):
|
|
83
|
+
issues.append(
|
|
84
|
+
f"source entry {index} local_path must not contain a query or fragment"
|
|
85
|
+
)
|
|
86
|
+
continue
|
|
87
|
+
try:
|
|
88
|
+
local_path = normalise_source_path(source_links_root, entry["local_path"])
|
|
89
|
+
except PathAuthorityError as exc:
|
|
90
|
+
issues.append(f"source entry {index} invalid local_path: {exc}")
|
|
91
|
+
continue
|
|
92
|
+
if not local_path.lower().endswith(_ROUTABLE_EXTENSIONS):
|
|
93
|
+
issues.append(f"source entry {index} local_path must end in .pdf or .md")
|
|
94
|
+
continue
|
|
95
|
+
local_abs = (source_links_root / local_path).resolve()
|
|
96
|
+
if local_abs in seen_paths:
|
|
97
|
+
issues.append(f"duplicate source-link local_path: {local_path}")
|
|
98
|
+
continue
|
|
99
|
+
name = entry["name"]
|
|
100
|
+
if name in seen_names:
|
|
101
|
+
issues.append(f"duplicate source-link name: {name}")
|
|
102
|
+
continue
|
|
103
|
+
parsed_url = urlparse(entry["public_url"])
|
|
104
|
+
if (
|
|
105
|
+
parsed_url.scheme != "https"
|
|
106
|
+
or not parsed_url.netloc
|
|
107
|
+
or parsed_url.username is not None
|
|
108
|
+
or parsed_url.password is not None
|
|
109
|
+
or parsed_url.fragment
|
|
110
|
+
):
|
|
111
|
+
issues.append(
|
|
112
|
+
f"source entry {index} public_url must be an HTTPS URL without credentials or fragment"
|
|
113
|
+
)
|
|
114
|
+
continue
|
|
115
|
+
seen_paths.add(local_abs)
|
|
116
|
+
seen_names.add(name)
|
|
117
|
+
registry.setdefault(local_abs, []).append(
|
|
118
|
+
SourceLinkEntry(name, local_path, entry["public_url"], metadata)
|
|
119
|
+
)
|
|
120
|
+
return registry, issues
|
|
121
|
+
|
|
122
|
+
|
|
123
|
+
_REFERENCE_DESTINATION_RE = re.compile(
|
|
124
|
+
r"^(?:<(?P<angle>.*?)#page=(?P<angle_page>-?\d+)>|(?P<bare>.*?)#page=(?P<bare_page>-?\d+))$"
|
|
125
|
+
)
|
|
126
|
+
|
|
127
|
+
|
|
128
|
+
def parse_source_link_destination(destination: str) -> tuple[str, int] | None:
|
|
129
|
+
"""Parse a positive-page PDF reference destination while retaining verifier diagnostics."""
|
|
130
|
+
match = _REFERENCE_DESTINATION_RE.fullmatch(destination)
|
|
131
|
+
if match is None:
|
|
132
|
+
return None
|
|
133
|
+
path = match.group("angle") or match.group("bare") or ""
|
|
134
|
+
page = match.group("angle_page") or match.group("bare_page")
|
|
135
|
+
return path.replace(r"\ ", " "), int(page)
|
|
136
|
+
|
|
137
|
+
|
|
138
|
+
def parse_staged_source_destination(destination: str) -> tuple[str, int] | None:
|
|
139
|
+
"""Parse a narrow local PDF `#page=N` destination for stage rewriting."""
|
|
140
|
+
parsed = parse_source_link_destination(destination)
|
|
141
|
+
if parsed is None:
|
|
142
|
+
return None
|
|
143
|
+
path, page = parsed
|
|
144
|
+
if (
|
|
145
|
+
page <= 0
|
|
146
|
+
or any(character in path for character in "?#()<>\t\r\n")
|
|
147
|
+
or any(character.isspace() for character in path)
|
|
148
|
+
or not path.lower().endswith(".pdf")
|
|
149
|
+
):
|
|
150
|
+
return None
|
|
151
|
+
return path, page
|
|
152
|
+
|
|
153
|
+
|
|
154
|
+
def parse_staged_markdown_destination(destination: str) -> tuple[str, str] | None:
|
|
155
|
+
"""Parse a narrow local `.md` or `.md#anchor` destination for stage rewriting.
|
|
156
|
+
|
|
157
|
+
Returns ``(path, anchor)`` with ``anchor`` the empty string when no
|
|
158
|
+
fragment was authored, or ``None`` when the destination is not a
|
|
159
|
+
supported local Markdown routing candidate (remote, query-bearing,
|
|
160
|
+
angle-wrapped, malformed, or wrong-extension destinations all return
|
|
161
|
+
``None`` so the caller can leave them untouched rather than erroring).
|
|
162
|
+
"""
|
|
163
|
+
if (
|
|
164
|
+
not destination
|
|
165
|
+
or "?" in destination
|
|
166
|
+
or "://" in destination
|
|
167
|
+
or destination.startswith("<")
|
|
168
|
+
or destination.count("#") > 1
|
|
169
|
+
):
|
|
170
|
+
return None
|
|
171
|
+
path, separator, anchor = destination.partition("#")
|
|
172
|
+
if separator and not anchor:
|
|
173
|
+
return None
|
|
174
|
+
if (
|
|
175
|
+
not path
|
|
176
|
+
or any(character in path for character in "?#()<>\t\r\n")
|
|
177
|
+
or any(character.isspace() for character in path)
|
|
178
|
+
or not path.lower().endswith(".md")
|
|
179
|
+
):
|
|
180
|
+
return None
|
|
181
|
+
if any(character.isspace() for character in anchor) or any(
|
|
182
|
+
character in anchor for character in "()<>"
|
|
183
|
+
):
|
|
184
|
+
return None
|
|
185
|
+
return path, anchor
|