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.
Files changed (76) hide show
  1. tracecite/__init__.py +35 -0
  2. tracecite/__main__.py +3 -0
  3. tracecite/cli.py +656 -0
  4. tracecite/docs/__init__.py +56 -0
  5. tracecite/docs/build.py +381 -0
  6. tracecite/docs/config.py +114 -0
  7. tracecite/docs/contract.py +17 -0
  8. tracecite/docs/modes.py +240 -0
  9. tracecite/docs/stage.py +407 -0
  10. tracecite/docs/vectorize.py +457 -0
  11. tracecite/evidence/__init__.py +3 -0
  12. tracecite/evidence/chunking.py +214 -0
  13. tracecite/evidence/commands.py +552 -0
  14. tracecite/evidence/config.py +49 -0
  15. tracecite/evidence/embedding.py +59 -0
  16. tracecite/evidence/manifest.py +197 -0
  17. tracecite/evidence/page_extraction.py +200 -0
  18. tracecite/evidence/page_output.py +80 -0
  19. tracecite/evidence/page_selection.py +116 -0
  20. tracecite/evidence/parsers/__init__.py +1 -0
  21. tracecite/evidence/parsers/base.py +65 -0
  22. tracecite/evidence/parsers/markdown.py +142 -0
  23. tracecite/evidence/parsers/pdf.py +315 -0
  24. tracecite/evidence/parsers/workbook.py +334 -0
  25. tracecite/evidence/paths.py +94 -0
  26. tracecite/evidence/schema.py +570 -0
  27. tracecite/evidence/source_links.py +185 -0
  28. tracecite/evidence/sync.py +1434 -0
  29. tracecite/evidence/vector_backend.py +130 -0
  30. tracecite/evidence/verify.py +368 -0
  31. tracecite/skills/routing-documentation-source-links/SKILL.md +167 -0
  32. tracecite/skills/routing-documentation-source-links/agents/openai.yaml +3 -0
  33. tracecite/skills/routing-documentation-source-links/references/documenter-integration.md +71 -0
  34. tracecite/skills/routing-documentation-source-links/references/registry-contract.md +86 -0
  35. tracecite/skills/routing-documentation-source-links/references/staging-and-rewriting.md +118 -0
  36. tracecite/skills/routing-documentation-source-links/references/validation-and-failure-modes.md +67 -0
  37. tracecite/skills/using-tracecite/SKILL.md +97 -0
  38. tracecite/skills/using-tracecite/agents/openai.yaml +3 -0
  39. tracecite/skills/using-tracecite/references/architecture.md +68 -0
  40. tracecite/skills/using-tracecite/references/pdf-and-assets.md +67 -0
  41. tracecite/skills/using-tracecite/references/retrieval.md +45 -0
  42. tracecite/skills/using-tracecite/references/schema-and-migrations.md +52 -0
  43. tracecite/skills/using-tracecite/references/synchronisation.md +98 -0
  44. tracecite/skills/using-tracecite/references/workspace-runtime.md +44 -0
  45. tracecite/skills/writing-evidence-backed-reports/SKILL.md +91 -0
  46. tracecite/skills/writing-evidence-backed-reports/agents/openai.yaml +3 -0
  47. tracecite/skills/writing-evidence-backed-reports/fixtures/README.md +13 -0
  48. tracecite/skills/writing-evidence-backed-reports/fixtures/reports/invalid-bad-path.md +5 -0
  49. tracecite/skills/writing-evidence-backed-reports/fixtures/reports/invalid-grammar.md +8 -0
  50. tracecite/skills/writing-evidence-backed-reports/fixtures/reports/invalid-missing-definition.md +3 -0
  51. tracecite/skills/writing-evidence-backed-reports/fixtures/reports/invalid-page-not-indexed.md +5 -0
  52. tracecite/skills/writing-evidence-backed-reports/fixtures/reports/invalid-unindexed-path.md +5 -0
  53. tracecite/skills/writing-evidence-backed-reports/fixtures/reports/valid-grammar.md +12 -0
  54. tracecite/skills/writing-evidence-backed-reports/fixtures/reports/valid-report.md +27 -0
  55. tracecite/skills/writing-evidence-backed-reports/fixtures/source-links.toml +17 -0
  56. tracecite/skills/writing-evidence-backed-reports/fixtures/validate_fixtures.py +295 -0
  57. tracecite/skills/writing-evidence-backed-reports/references/images-and-source-links.md +34 -0
  58. tracecite/skills/writing-evidence-backed-reports/references/quotation-and-verification.md +43 -0
  59. tracecite/skills/writing-evidence-backed-reports/references/reference-style-citations.md +48 -0
  60. tracecite/skills/writing-evidence-backed-reports/references/report-structure.md +58 -0
  61. tracecite/tables/__init__.py +41 -0
  62. tracecite/tables/_text.py +142 -0
  63. tracecite/tables/document.py +582 -0
  64. tracecite/tables/html.py +299 -0
  65. tracecite/tables/models.py +119 -0
  66. tracecite/tables/normalise.py +786 -0
  67. tracecite/tables/pandoc.py +503 -0
  68. tracecite/tables/publish.py +238 -0
  69. tracecite/tables/render.py +128 -0
  70. tracecite/tables/site.py +457 -0
  71. tracecite-0.0.2.dist-info/METADATA +320 -0
  72. tracecite-0.0.2.dist-info/RECORD +76 -0
  73. tracecite-0.0.2.dist-info/WHEEL +5 -0
  74. tracecite-0.0.2.dist-info/entry_points.txt +2 -0
  75. tracecite-0.0.2.dist-info/licenses/LICENSE +21 -0
  76. 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