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.
- protocolith/__init__.py +38 -0
- protocolith/baseline_groups.py +294 -0
- protocolith/baselines.py +288 -0
- protocolith/card_svg_render.py +281 -0
- protocolith/card_svg_styles.py +178 -0
- protocolith/cli.py +796 -0
- protocolith/core/__init__.py +63 -0
- protocolith/core/_lock_posix.py +29 -0
- protocolith/core/_lock_windows.py +29 -0
- protocolith/core/atlas.py +406 -0
- protocolith/core/atlas_assets/atlas.css +86 -0
- protocolith/core/atlas_assets/atlas.html +84 -0
- protocolith/core/atlas_assets/atlas.js +370 -0
- protocolith/core/atlas_i18n/en.json +61 -0
- protocolith/core/canonical.py +124 -0
- protocolith/core/capture.py +68 -0
- protocolith/core/clock.py +25 -0
- protocolith/core/commands.py +356 -0
- protocolith/core/errors.py +116 -0
- protocolith/core/issue.py +98 -0
- protocolith/core/ledger.py +75 -0
- protocolith/core/mcp.py +371 -0
- protocolith/core/ops.py +183 -0
- protocolith/core/rules.py +352 -0
- protocolith/core/schema.py +137 -0
- protocolith/core/store.py +101 -0
- protocolith/core/views.py +136 -0
- protocolith/doctor.py +135 -0
- protocolith/evidence_card.py +354 -0
- protocolith/family_ledger.py +489 -0
- protocolith/generic_ohlcv_batch_pre_registration_meta.py +123 -0
- protocolith/inspect.py +48 -0
- protocolith/nasa_power.py +266 -0
- protocolith/nasa_power_fetch.py +64 -0
- protocolith/nasa_power_parser.py +133 -0
- protocolith/nasa_power_prereg_runner.py +383 -0
- protocolith/noaa_coops_fetch.py +188 -0
- protocolith/noaa_coops_parser.py +120 -0
- protocolith/noaa_coops_prereg_runner.py +341 -0
- protocolith/public_ai_protocol.py +176 -0
- protocolith/py.typed +0 -0
- protocolith/registry.py +139 -0
- protocolith/registry_view.py +302 -0
- protocolith/rerun_report.py +111 -0
- protocolith/run_root.py +243 -0
- protocolith/scaffold.py +565 -0
- protocolith/source_probe.py +230 -0
- protocolith/svg_a11y.py +100 -0
- protocolith/tree_overlay.py +343 -0
- protocolith/verify_packs.py +251 -0
- protocolith/workflows.py +233 -0
- protocolith-0.6.0.dist-info/METADATA +283 -0
- protocolith-0.6.0.dist-info/RECORD +57 -0
- protocolith-0.6.0.dist-info/WHEEL +4 -0
- protocolith-0.6.0.dist-info/entry_points.txt +3 -0
- protocolith-0.6.0.dist-info/licenses/LICENSE +201 -0
- 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}}
|