protocolith 0.6.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.
Files changed (57) hide show
  1. protocolith/__init__.py +38 -0
  2. protocolith/baseline_groups.py +294 -0
  3. protocolith/baselines.py +288 -0
  4. protocolith/card_svg_render.py +281 -0
  5. protocolith/card_svg_styles.py +178 -0
  6. protocolith/cli.py +796 -0
  7. protocolith/core/__init__.py +63 -0
  8. protocolith/core/_lock_posix.py +29 -0
  9. protocolith/core/_lock_windows.py +29 -0
  10. protocolith/core/atlas.py +406 -0
  11. protocolith/core/atlas_assets/atlas.css +86 -0
  12. protocolith/core/atlas_assets/atlas.html +84 -0
  13. protocolith/core/atlas_assets/atlas.js +370 -0
  14. protocolith/core/atlas_i18n/en.json +61 -0
  15. protocolith/core/canonical.py +124 -0
  16. protocolith/core/capture.py +68 -0
  17. protocolith/core/clock.py +25 -0
  18. protocolith/core/commands.py +356 -0
  19. protocolith/core/errors.py +116 -0
  20. protocolith/core/issue.py +98 -0
  21. protocolith/core/ledger.py +75 -0
  22. protocolith/core/mcp.py +371 -0
  23. protocolith/core/ops.py +183 -0
  24. protocolith/core/rules.py +352 -0
  25. protocolith/core/schema.py +137 -0
  26. protocolith/core/store.py +101 -0
  27. protocolith/core/views.py +136 -0
  28. protocolith/doctor.py +135 -0
  29. protocolith/evidence_card.py +354 -0
  30. protocolith/family_ledger.py +489 -0
  31. protocolith/generic_ohlcv_batch_pre_registration_meta.py +123 -0
  32. protocolith/inspect.py +48 -0
  33. protocolith/nasa_power.py +266 -0
  34. protocolith/nasa_power_fetch.py +64 -0
  35. protocolith/nasa_power_parser.py +133 -0
  36. protocolith/nasa_power_prereg_runner.py +383 -0
  37. protocolith/noaa_coops_fetch.py +188 -0
  38. protocolith/noaa_coops_parser.py +120 -0
  39. protocolith/noaa_coops_prereg_runner.py +341 -0
  40. protocolith/public_ai_protocol.py +176 -0
  41. protocolith/py.typed +0 -0
  42. protocolith/registry.py +139 -0
  43. protocolith/registry_view.py +302 -0
  44. protocolith/rerun_report.py +111 -0
  45. protocolith/run_root.py +243 -0
  46. protocolith/scaffold.py +565 -0
  47. protocolith/source_probe.py +230 -0
  48. protocolith/svg_a11y.py +100 -0
  49. protocolith/tree_overlay.py +343 -0
  50. protocolith/verify_packs.py +251 -0
  51. protocolith/workflows.py +233 -0
  52. protocolith-0.6.0.dist-info/METADATA +283 -0
  53. protocolith-0.6.0.dist-info/RECORD +57 -0
  54. protocolith-0.6.0.dist-info/WHEEL +4 -0
  55. protocolith-0.6.0.dist-info/entry_points.txt +3 -0
  56. protocolith-0.6.0.dist-info/licenses/LICENSE +201 -0
  57. protocolith-0.6.0.dist-info/licenses/NOTICE +13 -0
@@ -0,0 +1,63 @@
1
+ # SPDX-License-Identifier: Apache-2.0
2
+ """Protocolith core: record, verify and issue trial records. Standard library only."""
3
+
4
+ from __future__ import annotations
5
+
6
+ from .atlas import build_atlas
7
+ from .canonical import CanonError, decode, encode, sha256_hex
8
+ from .clock import now_utc
9
+ from .errors import EnvError, InputError, ProtocolithError, VerificationFailed, Violation
10
+ from .ledger import MAX_ENTRY_BYTES, RESULT_STATUSES
11
+ from .capture import capture
12
+ from .ops import (
13
+ deviation,
14
+ entries,
15
+ freeze,
16
+ head,
17
+ init,
18
+ issue,
19
+ log,
20
+ record,
21
+ repair_truncate_partial_tail,
22
+ show,
23
+ summary,
24
+ verify,
25
+ )
26
+ from .rules import Verdict, Verifier, scan
27
+ from .schema import schema_for
28
+ from .store import Store, resolve_store
29
+
30
+ __all__ = [
31
+ "MAX_ENTRY_BYTES",
32
+ "RESULT_STATUSES",
33
+ "CanonError",
34
+ "EnvError",
35
+ "InputError",
36
+ "ProtocolithError",
37
+ "Store",
38
+ "Verdict",
39
+ "VerificationFailed",
40
+ "Verifier",
41
+ "Violation",
42
+ "build_atlas",
43
+ "capture",
44
+ "decode",
45
+ "deviation",
46
+ "encode",
47
+ "entries",
48
+ "freeze",
49
+ "head",
50
+ "init",
51
+ "issue",
52
+ "log",
53
+ "now_utc",
54
+ "record",
55
+ "repair_truncate_partial_tail",
56
+ "resolve_store",
57
+ "scan",
58
+ "schema_for",
59
+ "show",
60
+ "sha256_hex",
61
+ "summary",
62
+ "verify",
63
+ ]
@@ -0,0 +1,29 @@
1
+ # SPDX-License-Identifier: Apache-2.0
2
+ """POSIX advisory locking. Exercised on its own platform in CI, hence the pragmas."""
3
+
4
+ from __future__ import annotations # pragma: no cover
5
+
6
+ import fcntl # pragma: no cover
7
+ import os # pragma: no cover
8
+
9
+
10
+ def try_lock(fd: int) -> bool: # pragma: no cover
11
+ """Try to take an exclusive lock without blocking."""
12
+ try:
13
+ fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
14
+ except OSError:
15
+ return False
16
+ return True
17
+
18
+
19
+ def unlock(fd: int) -> None: # pragma: no cover
20
+ fcntl.flock(fd, fcntl.LOCK_UN)
21
+
22
+
23
+ def fsync_dir(path: str) -> None: # pragma: no cover
24
+ """Make a newly created file name durable."""
25
+ fd = os.open(path, os.O_RDONLY)
26
+ try:
27
+ os.fsync(fd)
28
+ finally:
29
+ os.close(fd)
@@ -0,0 +1,29 @@
1
+ # SPDX-License-Identifier: Apache-2.0
2
+ """Windows advisory locking. Exercised on its own platform in CI, hence the pragmas."""
3
+
4
+ from __future__ import annotations # pragma: no cover
5
+
6
+ import os # pragma: no cover
7
+
8
+
9
+ def try_lock(fd: int) -> bool: # pragma: no cover
10
+ """Try to take an exclusive lock on the first byte without blocking."""
11
+ import msvcrt
12
+
13
+ os.lseek(fd, 0, os.SEEK_SET)
14
+ try:
15
+ msvcrt.locking(fd, msvcrt.LK_NBLCK, 1) # type: ignore[attr-defined, unused-ignore]
16
+ except OSError:
17
+ return False
18
+ return True
19
+
20
+
21
+ def unlock(fd: int) -> None: # pragma: no cover
22
+ import msvcrt
23
+
24
+ os.lseek(fd, 0, os.SEEK_SET)
25
+ msvcrt.locking(fd, msvcrt.LK_UNLCK, 1) # type: ignore[attr-defined, unused-ignore]
26
+
27
+
28
+ def fsync_dir(path: str) -> None: # pragma: no cover
29
+ """Directories cannot be fsynced on Windows; nothing to do."""
@@ -0,0 +1,406 @@
1
+ # SPDX-License-Identifier: Apache-2.0
2
+ """``atlas``: one self-contained, offline HTML page that lets a person browse experiments.
3
+
4
+ Sources are a local ledger store and/or directories of evidence card JSON files. The page embeds its data as one JSON
5
+ block, loads nothing from the network, and is byte-for-byte reproducible: the same input gives the same bytes.
6
+ The page script, style and markup are template files (``atlas_assets``); the UI strings are ``atlas_i18n/en.json`` plus
7
+ any translation files the user supplies.
8
+ """
9
+
10
+ from __future__ import annotations
11
+
12
+ import base64
13
+ import hashlib
14
+ import html
15
+ import json
16
+ import math
17
+ import os
18
+ import re
19
+ import zlib
20
+ from collections.abc import Sequence
21
+ from dataclasses import dataclass, field
22
+ from importlib import resources
23
+ from pathlib import Path
24
+ from typing import Any
25
+
26
+ from .errors import EnvError, InputError, ProtocolithError, io_guard
27
+ from .issue import _atomic_write, build_card, card_hash
28
+ from .rules import Verdict, Verifier, scan
29
+ from .store import Store
30
+ from .views import protocol_of
31
+
32
+ DEFAULT_TITLE = "Protocolith atlas"
33
+ DEFAULT_OUT = "protocolith-atlas.html"
34
+ DEFAULT_CARDS_DIR = "docs/evidence_cards"
35
+ DATA_VERSION = 1
36
+ MAX_FILE_BYTES = 2_097_152
37
+ MAX_STRING = 2000
38
+ MAX_ITEMS = 100
39
+ MAX_DEPTH = 8
40
+ MAX_PROBLEMS = 20
41
+ MAX_ISSUES = 50
42
+ BLOCK_ROWS = 128
43
+ MAX_SOURCE_TEXT = 600
44
+
45
+ _CARD_COLUMNS = ("evidence_id", "protocol_id", "result_status", "domain", "reproduction_level", "claim_boundary")
46
+ _DATE_KEYS = ("created_at", "last_verified_date", "access_date")
47
+ _DATE_RE = re.compile(r"[0-9]{4}-[0-9]{2}-[0-9]{2}")
48
+ _LANG_RE = re.compile(r"[a-z]{2,3}(-[A-Za-z0-9]{2,8})*")
49
+ _CONTROL_RE = re.compile("[\x00-\x1f\x7f]")
50
+ _PLACEHOLDER_RE = re.compile(r"\{\{(T:)?(\w+)\}\}")
51
+
52
+
53
+ @dataclass
54
+ class AtlasResult:
55
+ """The page bytes plus what a caller needs to report: counts, warnings and whether the ledger verified."""
56
+
57
+ html: bytes
58
+ ok: bool
59
+ total: int
60
+ shown: int
61
+ skipped: int
62
+ warnings: list[str] = field(default_factory=list)
63
+ ledger: dict[str, Any] | None = None
64
+
65
+ def to_dict(self) -> dict[str, Any]:
66
+ return {
67
+ "bytes": len(self.html),
68
+ "cards": self.total,
69
+ "ledger": self.ledger,
70
+ "ok": self.ok,
71
+ "shown": self.shown,
72
+ "skipped": self.skipped,
73
+ "warnings": self.warnings,
74
+ }
75
+
76
+
77
+ def _asset(name: str) -> str:
78
+ return (resources.files("protocolith.core") / "atlas_assets" / name).read_text(encoding="utf-8")
79
+
80
+
81
+ def english_catalog() -> dict[str, str]:
82
+ """The shipped English UI strings, key to text (``_name`` is the language's own name)."""
83
+ text = (resources.files("protocolith.core") / "atlas_i18n" / "en.json").read_text(encoding="utf-8")
84
+ catalog: dict[str, str] = json.loads(text)
85
+ return catalog
86
+
87
+
88
+ def _read_translation(path: Path, english: dict[str, str], warnings: list[str]) -> dict[str, str] | None:
89
+ try:
90
+ data = json.loads(path.read_text(encoding="utf-8"))
91
+ except (OSError, ValueError, RecursionError):
92
+ warnings.append(f"{path.name}: not readable as UTF-8 JSON; skipped")
93
+ return None
94
+ if not isinstance(data, dict):
95
+ warnings.append(f"{path.name}: must be a JSON object; skipped")
96
+ return None
97
+ clean: dict[str, str] = {}
98
+ for key, value in data.items():
99
+ if key not in english:
100
+ warnings.append(f"{path.name}: unknown key {key!r} ignored")
101
+ elif not isinstance(value, str):
102
+ warnings.append(f"{path.name}: value of {key!r} must be a string; ignored")
103
+ elif value: # an empty value is an untranslated template entry
104
+ clean[key] = value
105
+ return clean
106
+
107
+
108
+ def load_languages(i18n_dir: str | os.PathLike[str] | None) -> tuple[dict[str, dict[str, str]], list[str]]:
109
+ """English plus every ``<code>.json`` in ``i18n_dir``; missing keys fall back to English. Returns (languages, warnings)."""
110
+ english = english_catalog()
111
+ languages = {"en": dict(english)}
112
+ warnings: list[str] = []
113
+ if i18n_dir is None:
114
+ return languages, warnings
115
+ folder = Path(i18n_dir)
116
+ if not folder.is_dir():
117
+ raise InputError("BAD_PATH", f"{i18n_dir}: not a directory")
118
+ with io_guard():
119
+ names = sorted(item.name for item in folder.iterdir() if item.name.endswith(".json") and item.is_file())
120
+ for name in names:
121
+ code = name[: -len(".json")]
122
+ if code == "en" or not _LANG_RE.fullmatch(code):
123
+ warnings.append(f"{name}: not a usable language code (English is built in); skipped")
124
+ continue
125
+ translation = _read_translation(folder / name, english, warnings)
126
+ if translation is not None:
127
+ merged = {**english, **translation}
128
+ merged["_name"] = _CONTROL_RE.sub(" ", merged["_name"])[:60] if "_name" in translation else code
129
+ languages[code] = merged
130
+ return languages, warnings
131
+
132
+
133
+ def _clip(value: Any, depth: int = 0) -> Any:
134
+ """Bound string length, list length and nesting so one hostile card cannot bloat the page."""
135
+ if isinstance(value, str):
136
+ if len(value) <= MAX_STRING:
137
+ return value
138
+ return f"{value[:MAX_STRING]}... [clipped {len(value) - MAX_STRING} characters]"
139
+ if isinstance(value, (list, dict)) and depth >= MAX_DEPTH:
140
+ return "[clipped: nested too deeply]"
141
+ if isinstance(value, list):
142
+ items = [_clip(item, depth + 1) for item in value[:MAX_ITEMS]]
143
+ if len(value) > MAX_ITEMS:
144
+ items.append(f"[clipped {len(value) - MAX_ITEMS} items]")
145
+ return items
146
+ if isinstance(value, dict):
147
+ return {str(key)[:200]: _clip(item, depth + 1) for key, item in value.items()}
148
+ return value
149
+
150
+
151
+ def _finite(text: str) -> float:
152
+ number = float(text)
153
+ if not math.isfinite(number):
154
+ raise ValueError("number out of range")
155
+ return number
156
+
157
+
158
+ def _no_constant(name: str) -> Any:
159
+ raise ValueError(f"{name} is not JSON")
160
+
161
+
162
+ Pair = tuple[list[Any], dict[str, Any]]
163
+
164
+
165
+ def _row(card: dict[str, Any], digest: str) -> Pair:
166
+ """A compact table row and the other fields of the card (they travel compressed, in blocks)."""
167
+ clipped = _clip(card)
168
+ in_columns = {key for key in _CARD_COLUMNS if isinstance(card.get(key), str)}
169
+ columns = [clipped[key] if key in in_columns else None for key in _CARD_COLUMNS]
170
+ extra = {key: value for key, value in clipped.items() if key not in in_columns}
171
+ stamps = (card.get(key) for key in _DATE_KEYS)
172
+ date = next((s[:10] for s in stamps if isinstance(s, str) and _DATE_RE.match(s)), "")
173
+ found = [card.get("official_source_name"), card.get("official_source_url"), card.get("sources")]
174
+ text = "\n".join(v if isinstance(v, str) else json.dumps(v, ensure_ascii=False) for v in found if v)
175
+ # row layout: id, protocol, status, domain, level, date, claim, hash, source text (see atlas.js)
176
+ row = [*columns[:5], date, columns[5], digest, text[:MAX_SOURCE_TEXT]]
177
+ return row, extra
178
+
179
+
180
+ def _blocks(extras: list[dict[str, Any]]) -> list[str]:
181
+ """Per-block deflate+base64 of the other card fields; the page decodes a block only when a record is opened."""
182
+ blocks = []
183
+ for start in range(0, len(extras), BLOCK_ROWS):
184
+ raw = json.dumps(extras[start : start + BLOCK_ROWS], ensure_ascii=True, sort_keys=True, separators=(",", ":"))
185
+ blocks.append(base64.b64encode(zlib.compress(raw.encode("ascii"), 6)).decode("ascii"))
186
+ return blocks
187
+
188
+
189
+ def _scan_dir(root: Path) -> list[Path]:
190
+ found: list[Path] = []
191
+ for here, dirs, files in os.walk(root):
192
+ dirs.sort()
193
+ found += [Path(here) / name for name in sorted(files) if name.lower().endswith(".json")]
194
+ return found
195
+
196
+
197
+ def _read_card(path: Path) -> tuple[dict[str, Any], str] | str:
198
+ """The card and the sha256 of its file bytes, or the reason the file is skipped."""
199
+ try:
200
+ if path.stat().st_size > MAX_FILE_BYTES:
201
+ return "larger than 2 MiB"
202
+ raw = path.read_bytes()
203
+ text = raw.decode("utf-8")
204
+ data = json.loads(text, parse_float=_finite, parse_constant=_no_constant)
205
+ except OSError:
206
+ return "unreadable"
207
+ except (ValueError, RecursionError):
208
+ return "not valid UTF-8 JSON"
209
+ ident = data.get("evidence_id") if isinstance(data, dict) else None
210
+ if not (isinstance(ident, str) and ident and isinstance(data.get("result_status"), str)):
211
+ return "not an evidence card (needs evidence_id and result_status)"
212
+ return data, hashlib.sha256(raw).hexdigest()
213
+
214
+
215
+ def _from_cards(folders: Sequence[str | os.PathLike[str]]) -> tuple[list[Pair], list[dict[str, str]]]:
216
+ rows: list[Pair] = []
217
+ issues: list[dict[str, str]] = []
218
+ for folder in folders:
219
+ root = Path(folder)
220
+ if not root.is_dir():
221
+ raise InputError("BAD_PATH", f"{folder}: not a directory")
222
+ with io_guard():
223
+ paths = _scan_dir(root)
224
+ for path in paths:
225
+ found = _read_card(path)
226
+ if isinstance(found, str):
227
+ issues.append({"path": path.relative_to(root).as_posix(), "reason": found})
228
+ else:
229
+ rows.append(_row(*found))
230
+ return rows, issues
231
+
232
+
233
+ def _ledger_card(verifier: Verifier, seq: int) -> dict[str, Any]:
234
+ entry = verifier.entries[seq]
235
+ body = entry["body"]
236
+ try:
237
+ return build_card(verifier, seq)
238
+ except (ProtocolithError, KeyError, TypeError): # a tampered ledger: show what the record itself says
239
+ return {
240
+ "claim_boundary": body.get("claim_boundary"),
241
+ "created_at": entry["ts"],
242
+ "evidence_id": f"LEDGER-RECORD-{seq:06d}",
243
+ "ledger_record_seq": seq,
244
+ "protocol_id": protocol_of(verifier, entry),
245
+ "reproduction_level": body.get("reproduction_level"),
246
+ "result_status": body.get("status"),
247
+ }
248
+
249
+
250
+ def _from_ledger(store: Store) -> tuple[list[Pair], dict[str, Any]]:
251
+ with io_guard(), store.locked(write=False):
252
+ verdict, verifier = scan(store.read(missing_ok=False), card_hash)
253
+ rows = [
254
+ _row(_ledger_card(verifier, seq), verifier.entries[seq]["hash"])
255
+ for seq in sorted(verifier.entries)
256
+ if verifier.entries[seq]["type"] == "record"
257
+ ]
258
+ return rows, _ledger_integrity(verdict)
259
+
260
+
261
+ def _ledger_integrity(verdict: Verdict) -> dict[str, Any]:
262
+ problems = [v.to_dict() for v in verdict.violations[:MAX_PROBLEMS]]
263
+ return {
264
+ "count": verdict.count,
265
+ "head_hash": verdict.head_hash,
266
+ "head_seq": verdict.head_seq,
267
+ "kind": "ledger",
268
+ "ok": verdict.ok,
269
+ "problem_count": len(verdict.violations),
270
+ "problems": problems,
271
+ }
272
+
273
+
274
+ def _embed(data: Any) -> str:
275
+ """Canonical-ish JSON that cannot end a script block or smuggle markup: ASCII only, no raw < > &."""
276
+ text = json.dumps(data, ensure_ascii=True, sort_keys=True, separators=(",", ":"), allow_nan=False)
277
+ return text.replace("<", "\\u003c").replace(">", "\\u003e").replace("&", "\\u0026")
278
+
279
+
280
+ def _title(title: str) -> str:
281
+ if not (isinstance(title, str) and title.strip()):
282
+ raise InputError("BAD_ENTRY", "title must be a non-empty string")
283
+ return _CONTROL_RE.sub(" ", title).strip()[:200]
284
+
285
+
286
+ def _auto_sources(
287
+ store: Store | str | os.PathLike[str] | None, cards: Sequence[str | os.PathLike[str]]
288
+ ) -> tuple[Store | None, Sequence[str | os.PathLike[str]]]:
289
+ if store is not None or cards:
290
+ return (None if store is None else store if isinstance(store, Store) else Store(store)), cards
291
+ from .store import resolve_store
292
+
293
+ local = resolve_store(None)
294
+ if local.ledger_path.is_file():
295
+ return local, ()
296
+ if Path(DEFAULT_CARDS_DIR).is_dir():
297
+ return None, (DEFAULT_CARDS_DIR,)
298
+ raise InputError("NO_SOURCE", f"no ledger at {local.path} and no {DEFAULT_CARDS_DIR}; pass --store or --cards")
299
+
300
+
301
+ def build_atlas_result(
302
+ *,
303
+ store: Store | str | os.PathLike[str] | None = None,
304
+ cards: Sequence[str | os.PathLike[str]] = (),
305
+ title: str = DEFAULT_TITLE,
306
+ i18n_dir: str | os.PathLike[str] | None = None,
307
+ default_lang: str = "en",
308
+ max_rows: int | None = None,
309
+ ) -> AtlasResult:
310
+ """Build the page. With no ``store`` and no ``cards`` a local ledger, else ``docs/evidence_cards``, is used."""
311
+ if max_rows is not None and not (type(max_rows) is int and max_rows >= 1):
312
+ raise InputError("BAD_ENTRY", "max_rows must be an integer of at least 1")
313
+ page_title = _title(title)
314
+ languages, warnings = load_languages(i18n_dir)
315
+ if default_lang not in languages:
316
+ raise InputError(
317
+ "BAD_LANG", f"default language {default_lang!r} is not available: " + ", ".join(sorted(languages))
318
+ )
319
+ real_store, folders = _auto_sources(store, cards)
320
+ rows: list[Pair] = []
321
+ integrity: list[dict[str, Any]] = []
322
+ issues: list[dict[str, str]] = []
323
+ ledger = None
324
+ if real_store is not None:
325
+ rows, ledger = _from_ledger(real_store)
326
+ integrity.append(ledger)
327
+ if folders:
328
+ found, issues = _from_cards(folders)
329
+ rows += found
330
+ integrity.append({"count": len(found), "kind": "cards"})
331
+ seen: set[str] = set()
332
+ unique = []
333
+ for pair in rows:
334
+ if pair[0][0] not in seen:
335
+ seen.add(pair[0][0])
336
+ unique.append(pair)
337
+ if len(unique) < len(rows):
338
+ warnings.append(f"{len(rows) - len(unique)} records with an already used evidence id were left out")
339
+ unique.sort(key=lambda pair: pair[0][0])
340
+ unique.sort(key=lambda pair: pair[0][5], reverse=True)
341
+ statuses: dict[str, int] = {}
342
+ for pair in unique:
343
+ statuses[pair[0][2]] = statuses.get(pair[0][2], 0) + 1
344
+ shown = unique if max_rows is None else unique[:max_rows]
345
+ data = {
346
+ "block": BLOCK_ROWS,
347
+ "blocks": _blocks([extra for _, extra in shown]),
348
+ "i18n": {"default": default_lang, "langs": languages},
349
+ "integrity": integrity,
350
+ "issues": {"count": len(issues), "items": issues[:MAX_ISSUES]},
351
+ "rows": [row for row, _ in shown],
352
+ "shown": len(shown),
353
+ "statuses": dict(sorted(statuses.items())),
354
+ "title": page_title,
355
+ "total": len(unique),
356
+ "v": DATA_VERSION,
357
+ }
358
+ english = languages["en"]
359
+ fill = {
360
+ "CSS": _asset("atlas.css"),
361
+ "DATA": _embed(data),
362
+ "JS": _asset("atlas.js"),
363
+ "LANG": default_lang,
364
+ "TITLE": html.escape(page_title),
365
+ }
366
+
367
+ def replace(found: re.Match[str]) -> str:
368
+ return html.escape(english[found.group(2)]) if found.group(1) else fill[found.group(2)]
369
+
370
+ page = _PLACEHOLDER_RE.sub(replace, _asset("atlas.html")).encode("utf-8")
371
+ ok = all(group.get("ok", True) for group in integrity)
372
+ return AtlasResult(page, ok, len(unique), len(shown), len(issues), warnings, ledger)
373
+
374
+
375
+ def build_atlas(**options: Any) -> bytes:
376
+ """The atlas page as bytes; see :func:`build_atlas_result` for the options."""
377
+ return build_atlas_result(**options).html
378
+
379
+
380
+ def write_atlas(page: bytes, out: str | os.PathLike[str] = DEFAULT_OUT) -> Path:
381
+ """Write the page atomically. ``out`` is a ``.html`` file, or a directory (existing, or without that suffix)."""
382
+ target = Path(out)
383
+ is_file = (
384
+ target.suffix.lower() in (".html", ".htm") and not target.is_dir() and not str(out).endswith(("/", os.sep))
385
+ )
386
+ path = target if is_file else target / DEFAULT_OUT
387
+ with io_guard():
388
+ path.parent.mkdir(parents=True, exist_ok=True)
389
+ _atomic_write(path, page)
390
+ return path
391
+
392
+
393
+ def confine(name: object, base: Path | None = None) -> Path:
394
+ """A path that stays inside ``base`` (default: the working directory) after links are resolved."""
395
+ if not isinstance(name, str) or not name:
396
+ raise InputError("BAD_PATH", "a path must be a non-empty string")
397
+ if "\x00" in name:
398
+ raise EnvError("IO_ERROR", "a path must not contain a NUL byte")
399
+ with io_guard():
400
+ root = (base or Path.cwd()).resolve()
401
+ path = (root / name).resolve()
402
+ try:
403
+ path.relative_to(root)
404
+ except ValueError:
405
+ raise InputError("BAD_PATH", f"{name}: the path is outside the current directory") from None
406
+ return path
@@ -0,0 +1,86 @@
1
+ :root{--bg:#fff;--fg:#1b1f24;--muted:#57606a;--line:#d0d7de;--panel:#f6f8fa;--accent:#0b5cad;--accent-fg:#fff;
2
+ --ok:#116329;--ok-bg:#dafbe1;--neg:#8a1c1c;--neg-bg:#ffe1e1;--blk:#7a4b00;--blk-bg:#fff1cf;--ins:#5b3a8c;--ins-bg:#efe6ff;
3
+ --drf:#0a5560;--drf-bg:#d9f4f7;--rep:#0b4f9c;--rep-bg:#dbeafe;--unk:#3d444d;--unk-bg:#e6e9ed;--focus:#b35900}
4
+ @media (prefers-color-scheme:dark){:root:not([data-theme="light"]){--bg:#0d1117;--fg:#e6edf3;--muted:#9da7b3;--line:#30363d;--panel:#161b22;--accent:#58a6ff;--accent-fg:#0d1117;
5
+ --ok:#7ee787;--ok-bg:#12351c;--neg:#ffa198;--neg-bg:#4a1717;--blk:#f2cc60;--blk-bg:#3b2a05;--ins:#d2a8ff;--ins-bg:#2e1f4d;
6
+ --drf:#76e3ea;--drf-bg:#0c3b41;--rep:#79c0ff;--rep-bg:#12294a;--unk:#c9d1d9;--unk-bg:#2b3139;--focus:#ffb454}}
7
+ :root[data-theme="dark"]{--bg:#0d1117;--fg:#e6edf3;--muted:#9da7b3;--line:#30363d;--panel:#161b22;--accent:#58a6ff;--accent-fg:#0d1117;
8
+ --ok:#7ee787;--ok-bg:#12351c;--neg:#ffa198;--neg-bg:#4a1717;--blk:#f2cc60;--blk-bg:#3b2a05;--ins:#d2a8ff;--ins-bg:#2e1f4d;
9
+ --drf:#76e3ea;--drf-bg:#0c3b41;--rep:#79c0ff;--rep-bg:#12294a;--unk:#c9d1d9;--unk-bg:#2b3139;--focus:#ffb454}
10
+ *{box-sizing:border-box}
11
+ html{color-scheme:light dark}
12
+ body{margin:0;background:var(--bg);color:var(--fg);font:15px/1.5 system-ui,-apple-system,"Segoe UI",Roboto,sans-serif}
13
+ body>*{max-width:1200px;margin-left:auto;margin-right:auto;padding-left:16px;padding-right:16px}
14
+ :focus-visible{outline:3px solid var(--focus);outline-offset:2px}
15
+ .skip{position:absolute;left:-999px;top:0;background:var(--accent);color:var(--accent-fg);padding:8px}
16
+ .skip:focus{left:8px;z-index:50}
17
+ .top{display:flex;gap:12px;align-items:center;justify-content:space-between;flex-wrap:wrap;padding-top:16px;padding-bottom:8px}
18
+ h1{font-size:1.4rem;margin:0;overflow-wrap:anywhere}
19
+ h2,h3{margin:.8rem 0 .4rem}
20
+ .tools{display:flex;gap:8px;align-items:center}
21
+ .lang{display:flex;gap:6px;align-items:center}
22
+ button,select,input{font:inherit;color:var(--fg);background:var(--panel);border:1px solid var(--line);border-radius:6px;padding:6px 10px;min-height:36px}
23
+ button{cursor:pointer}
24
+ button:hover{border-color:var(--accent)}
25
+ button[aria-pressed="true"]{background:var(--accent);color:var(--accent-fg)}
26
+ .muted{color:var(--muted)}
27
+ .mono,pre{font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,monospace;font-size:.85rem}
28
+ .wrapany{overflow-wrap:anywhere;margin:.2rem 0}
29
+ .sr{position:absolute;width:1px;height:1px;overflow:hidden;clip:rect(0 0 0 0)}
30
+ .banner{border:2px solid var(--line);border-radius:8px;padding:10px 14px;margin:8px 0;background:var(--panel)}
31
+ .banner.ok{border-color:var(--ok)}
32
+ .banner.bad{border-color:var(--neg);background:var(--neg-bg);color:var(--neg);font-weight:600}
33
+ .banner ul{margin:6px 0 0;padding-left:20px;font-weight:400}
34
+ .tiles{display:grid;grid-template-columns:repeat(auto-fit,minmax(150px,1fr));gap:8px;margin:12px auto}
35
+ .tile{border:1px solid var(--line);border-radius:8px;padding:8px 12px;background:var(--panel)}
36
+ .tile b{display:block;font-size:1.5rem}
37
+ .tile span{overflow-wrap:anywhere;font-size:.8rem}
38
+ .charts{display:grid;grid-template-columns:repeat(auto-fit,minmax(300px,1fr));gap:16px;margin:12px auto}
39
+ figure{margin:0;border:1px solid var(--line);border-radius:8px;padding:10px;background:var(--panel);min-width:0}
40
+ figcaption{font-weight:600;margin-bottom:6px}
41
+ .bars{display:grid;gap:4px}
42
+ .bar{display:grid;grid-template-columns:minmax(100px,38%) 1fr auto;gap:8px;align-items:center;text-align:left;width:100%;padding:2px 6px;min-height:28px}
43
+ .bar i{display:block;height:14px;border-radius:3px;background:currentColor;min-width:2px}
44
+ .bar .lbl{overflow-wrap:anywhere;font-size:.8rem}
45
+ .badge{display:inline-flex;gap:4px;align-items:center;border-radius:999px;padding:1px 8px;font-size:.78rem;font-weight:600;border:1px solid currentColor;white-space:nowrap}
46
+ .s-PASSED_UNDER_PROTOCOL{color:var(--ok);background:var(--ok-bg)}
47
+ .s-NEGATIVE_RESULT_UNDER_PROTOCOL{color:var(--neg);background:var(--neg-bg)}
48
+ .s-BLOCKED_SOURCE{color:var(--blk);background:var(--blk-bg)}
49
+ .s-INSUFFICIENT_COVERAGE{color:var(--ins);background:var(--ins-bg)}
50
+ .s-SOURCE_DRIFT{color:var(--drf);background:var(--drf-bg)}
51
+ .s-REPRODUCED_OUTCOME{color:var(--rep);background:var(--rep-bg)}
52
+ .s-unknown{color:var(--unk);background:var(--unk-bg)}
53
+ .bar.s-PASSED_UNDER_PROTOCOL,.bar.s-NEGATIVE_RESULT_UNDER_PROTOCOL,.bar.s-BLOCKED_SOURCE,.bar.s-INSUFFICIENT_COVERAGE,.bar.s-SOURCE_DRIFT,.bar.s-REPRODUCED_OUTCOME,.bar.s-unknown{background:var(--panel)}
54
+ .filters{display:flex;flex-wrap:wrap;gap:8px;align-items:flex-end;margin:12px auto}
55
+ .filters label{display:flex;flex-direction:column;font-size:.8rem;gap:2px}
56
+ .filters .grow{flex:1 1 260px}
57
+ .filters select{max-width:220px}
58
+ .wrap{overflow-x:auto;border:1px solid var(--line);border-radius:8px}
59
+ table{border-collapse:collapse;width:100%}
60
+ th,td{text-align:left;padding:6px 10px;border-bottom:1px solid var(--line);vertical-align:top}
61
+ th{background:var(--panel);white-space:nowrap}
62
+ th button{border:0;background:none;padding:0;font-weight:700;min-height:0}
63
+ tbody tr{cursor:pointer}
64
+ tbody tr:hover{background:var(--panel)}
65
+ tbody tr.cur{outline:2px solid var(--accent);outline-offset:-2px}
66
+ tbody tr.sel{background:var(--panel)}
67
+ td .idb{border:0;background:none;padding:0;color:var(--accent);text-align:left;overflow-wrap:anywhere;min-height:0;text-decoration:underline}
68
+ td.id{max-width:420px}
69
+ .pager{display:flex;gap:12px;align-items:center;justify-content:center;margin:12px auto}
70
+ button[disabled]{opacity:.5;cursor:default}
71
+ #drawer{position:fixed;top:0;right:0;bottom:0;width:min(560px,100%);overflow:auto;background:var(--bg);border-left:2px solid var(--accent);padding:12px 16px 24px;z-index:40;box-shadow:-8px 0 24px rgba(0,0,0,.25);max-width:none}
72
+ #drawer[hidden]{display:none}
73
+ .drawer-head,.drawer-actions{display:flex;gap:8px;align-items:center;flex-wrap:wrap;justify-content:space-between}
74
+ .drawer-actions{justify-content:flex-start}
75
+ dl{display:grid;grid-template-columns:minmax(90px,30%) 1fr;gap:4px 12px;margin:0}
76
+ dt{font-weight:600;overflow-wrap:anywhere}
77
+ dd{margin:0;overflow-wrap:anywhere;white-space:pre-wrap}
78
+ pre{background:var(--panel);border:1px solid var(--line);border-radius:6px;padding:8px;overflow:auto;max-height:50vh;white-space:pre-wrap;overflow-wrap:anywhere}
79
+ .foot{padding-top:16px;padding-bottom:32px;font-size:.85rem}
80
+ .keys{font-size:.8rem}
81
+ svg text{fill:var(--muted);font-size:10px}
82
+ svg .col{fill:var(--accent)}
83
+ @media (max-width:640px){.hide-s{display:none}body{font-size:14px}dl{grid-template-columns:1fr}}
84
+ @media print{.skip,.tools,.filters,.pager,.keys,#drawer,.charts button{display:none!important}
85
+ body{background:#fff;color:#000}.wrap{overflow:visible;border:0}tbody tr{cursor:auto}td .idb{color:#000;text-decoration:none}
86
+ :root{--bg:#fff;--fg:#000}.badge{border-color:#000;color:#000;background:#fff}}