okf-wiki 1.1.1

First public release, published as one snapshot. What changed between
versions is in CHANGELOG.md.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
This commit is contained in:
Kjell Tore Guttormsen 2026-11-14 21:03:20 +01:00
commit 0fd86a23a3
Signed by: ktg
SSH key fingerprint: SHA256:JakMjO6FTBBzN0Bhfj9saOoEjaFxlSdYuZQQpM/lF9Q
227 changed files with 96077 additions and 0 deletions

View file

@ -0,0 +1,124 @@
"""Google's viewer on a bundle (PLAN.md criterion 5: "Googles visning leser hver samling uten feil"; brief SC5). It calls
no model and reads no network.
Usage:
python3 tools/google_viewer_check.py BUNDLE --upstream DIR [--out FILE]
DIR is an upstream checkout of Google's Open Knowledge Format repository (a `git archive` of the pinned commit, never
the mirror itself): the tool runs `generate_visualization` from DIR/src/reference_agent/viewer/generator.py with
`python3 -I -B` (isolated, no bytecode written into DIR) from a fresh temporary folder, on an unchanged copy of
BUNDLE, so the bundle itself is never written. The viewer at ad30107 skips only index.md (`_walk_concepts`), so it draws
each log.md as a node too, although SPEC 3.1 reserves the name; those nodes (id "log" or ".../log") are counted apart.
PASS when the run exits 0, its output holds no "Traceback", it writes the graph page, and the graph in that page
(the line "window.BUNDLE = <json>;") has as many concept nodes as the auditor counts concept pages, at least one, and
one log node per log.md. --out keeps the graph page (for `okfwiki.view render --graph`; it shows the log nodes). Exit 0 = PASS, 1 = FAIL, 2 = could not run (no bundle directory,
or no generator under DIR).
"""
from __future__ import annotations
import argparse
import json
import shutil
import subprocess
import sys
import tempfile
from pathlib import Path
from typing import Any
sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
from okfwiki.audit import load_bundle # noqa: E402
GENERATOR = Path("src") / "reference_agent" / "viewer" / "generator.py"
GRAPH_LINE = "window.BUNDLE = "
TIMEOUT = 900
RUNNER = """
import json, sys
from pathlib import Path
sys.path.insert(0, sys.argv[1])
from reference_agent.viewer.generator import generate_visualization
print(json.dumps(generate_visualization(Path(sys.argv[2]), Path(sys.argv[3]), bundle_name=sys.argv[4])))
"""
class RunError(Exception):
"""The check cannot run; exit 2."""
def graph_nodes(page: Path) -> tuple[list[str], int] | None:
"""(the node ids, the number of edges) of the graph embedded in the viewer's page, or None when it cannot be read."""
try:
lines = page.read_text(encoding="utf-8").splitlines()
except (OSError, UnicodeDecodeError):
return None
line = next((x for x in lines if x.startswith(GRAPH_LINE) and x.endswith(";")), None)
if line is None:
return None
try:
graph: Any = json.loads(line[len(GRAPH_LINE):-1])
except ValueError:
return None
if not isinstance(graph, dict) or not isinstance(graph.get("nodes"), list) or not isinstance(graph.get("edges"), list):
return None
data = [n.get("data") if isinstance(n, dict) else None for n in graph["nodes"]]
return [str(d.get("id")) if isinstance(d, dict) else "" for d in data], len(graph["edges"])
def check(bundle: Path, upstream: Path, out: Path | None) -> tuple[bool, list[str]]:
"""(passed, the lines to print)."""
if not bundle.is_dir():
raise RunError(f"the bundle {bundle} is not a directory")
if not (upstream / GENERATOR).is_file():
raise RunError(f"no viewer generator at {upstream / GENERATOR}")
pages = len(load_bundle(bundle, bundle).concepts)
logs = sum(1 for p in bundle.rglob("log.md") if p.is_file())
with tempfile.TemporaryDirectory(prefix="google-viewer-") as tmp:
work = Path(tmp)
copy, run_in, graph = work / "bundle" / bundle.resolve().name, work / "cwd", work / "graph.html"
shutil.copytree(bundle, copy)
run_in.mkdir()
cmd = [sys.executable, "-I", "-B", "-c", RUNNER, str((upstream / "src").resolve()), str(copy), str(graph),
bundle.resolve().name]
try:
proc = subprocess.run(cmd, cwd=run_in, capture_output=True, text=True, timeout=TIMEOUT, check=False)
code, output = proc.returncode, proc.stdout + proc.stderr
except subprocess.TimeoutExpired:
code, output = -1, f"the viewer did not finish in {TIMEOUT} seconds"
found = graph_nodes(graph)
if out is not None and graph.is_file():
out.parent.mkdir(parents=True, exist_ok=True)
shutil.copyfile(graph, out)
ids, edges = found if found is not None else ([], -1)
log_nodes = sum(1 for i in ids if i.rsplit("/", 1)[-1] == "log")
nodes = len(ids) - log_nodes
traceback = "Traceback" in output
passed = code == 0 and not traceback and found is not None and pages > 0 and nodes == pages and log_nodes == logs
lines = [f"google viewer: exit {code} · traceback {'yes' if traceback else 'no'} · "
f"concept nodes {nodes if found is not None else 'unreadable'} · concept pages {pages} · "
f"log nodes {log_nodes} of {logs} · edges {edges}"]
if code != 0 or traceback:
lines += [" " + x for x in output.strip().splitlines()[-20:]]
lines.append(f"{'PASS' if passed else 'FAIL'} Google's viewer reads the bundle: one node per concept page and per log.md")
return passed, lines
def main(argv: list[str] | None = None) -> int:
p = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
p.add_argument("bundle")
p.add_argument("--upstream", required=True, help="an upstream checkout (git archive of the pinned commit)")
p.add_argument("--out", help="keep the viewer's graph page here")
args = p.parse_args(argv)
try:
passed, lines = check(Path(args.bundle), Path(args.upstream), Path(args.out) if args.out else None)
except RunError as exc:
print(f"google viewer cannot run: {exc}", file=sys.stderr)
return 2
for line in lines:
print(line)
return 0 if passed else 1
if __name__ == "__main__":
sys.exit(main())