433 lines
25 KiB
Python
433 lines
25 KiB
Python
#!/usr/bin/env python3
|
||
# /// script
|
||
# requires-python = ">=3.11"
|
||
# dependencies = ["pyyaml>=6"]
|
||
# ///
|
||
"""Render an Open Knowledge Format (OKF) bundle as a single self-contained,
|
||
interactive HTML graph (`viz.html`). No backend, no install on the viewing side,
|
||
no data leaves the page — concepts become nodes (coloured by `type`, sized by
|
||
body length), markdown links and bundle-internal `sources` become edges, and
|
||
clicking a node opens a wiki-style panel with its rendered markdown, OKF v0.2
|
||
provenance/trust/lifecycle metadata, outgoing links, and "Cited by" backlinks.
|
||
|
||
Features: force/concentric/breadth-first/circle/grid layouts, per-type filter,
|
||
free-text search, neighbour highlight, clickable cross-links and backlinks.
|
||
|
||
The default layout is force (cose) up to AUTO_COSE_MAX concepts, then the linear
|
||
concentric layout — force-directed cost grows roughly quadratically with node
|
||
count and freezes the page on large bundles. An explicit --layout always wins.
|
||
|
||
Run: uv run okf_visualize.py <bundle-dir> [-o viz.html]
|
||
"""
|
||
from __future__ import annotations
|
||
|
||
import argparse
|
||
import json
|
||
import re
|
||
import sys
|
||
from pathlib import Path
|
||
|
||
import yaml
|
||
|
||
RESERVED = {"index.md", "log.md"}
|
||
# Force (cose) layout froze the page for ~32 s at ~2k concepts (measured in
|
||
# Chrome); the linear layouts load the same bundle in under 2 s. Past this size
|
||
# the default switches to concentric, and the in-page layout picker asks before
|
||
# running force. An explicit --layout (or ?layout=) still wins.
|
||
AUTO_COSE_MAX = 1000
|
||
# Above this the page is slow on any layout (23k concepts measured: ~27 s load,
|
||
# ~650 MB heap) and reads as a hairball — warn and suggest rendering a subtree.
|
||
SCALE_WARN = 5000
|
||
FENCE = re.compile(r"^(```|~~~)")
|
||
LINK = re.compile(r"(?<!\!)\[[^\]]*\]\(([^)\s]+)(?:\s+\"[^\"]*\")?\)")
|
||
|
||
|
||
def json_for_script(obj) -> str:
|
||
"""JSON-encode ``obj`` for safe embedding inside an inline ``<script>``.
|
||
|
||
The HTML tokenizer knows nothing about JS string context: a literal
|
||
``</script>`` in a concept body ends the inline script early (truncating the
|
||
embedded ``NODES``/``EDGES`` and breaking the whole page), and ``<!--`` can
|
||
shift it into the escaped script-data states where even the template's real
|
||
closing tag stops working. Escaping every ``<`` as ``\\u003c`` neutralizes
|
||
``</script>``, ``<!--`` and ``<script`` in one stroke, and the result stays
|
||
valid JSON *and* JavaScript (``json.dumps`` keeps everything else ASCII via
|
||
the default ``ensure_ascii=True``).
|
||
"""
|
||
return json.dumps(obj, default=str).replace("<", "\\u003c")
|
||
|
||
|
||
def split_frontmatter(text: str):
|
||
if not text.startswith("---"):
|
||
return {}, text
|
||
lines = text.splitlines(keepends=True)
|
||
if lines[0].strip() != "---":
|
||
return {}, text
|
||
for i in range(1, len(lines)):
|
||
if lines[i].strip() == "---":
|
||
try:
|
||
meta = yaml.safe_load("".join(lines[1:i])) or {}
|
||
except yaml.YAMLError:
|
||
meta = {}
|
||
return (meta if isinstance(meta, dict) else {}), "".join(lines[i + 1:])
|
||
return {}, text
|
||
|
||
|
||
def link_targets(text: str):
|
||
out, in_fence = [], False
|
||
for line in text.splitlines():
|
||
if FENCE.match(line.strip()):
|
||
in_fence = not in_fence
|
||
continue
|
||
if not in_fence:
|
||
out.extend(LINK.findall(line))
|
||
return out
|
||
|
||
|
||
def resolve(target: str, path: Path, bundle: Path):
|
||
"""Resolve a link/`sources[].resource` to a concept id, or None if it is not
|
||
one (an external URL, an asset, a scope descriptor, an escape from the tree)."""
|
||
t = str(target).split("#", 1)[0]
|
||
if not t.endswith(".md"):
|
||
return None
|
||
if t.startswith("/"):
|
||
return t.lstrip("/")[:-3]
|
||
cand = (path.parent / t).resolve()
|
||
return cand.relative_to(bundle.resolve()).as_posix()[:-3] \
|
||
if cand.is_relative_to(bundle.resolve()) else None
|
||
|
||
|
||
def read_sources(meta: dict, path: Path, bundle: Path):
|
||
"""§5.1 `sources`, flattened for display. `cid` is set when the source is
|
||
itself a concept in this bundle — that derivation is a real graph edge."""
|
||
raw = meta.get("sources")
|
||
out = []
|
||
if not isinstance(raw, list):
|
||
return out
|
||
for src in raw:
|
||
if not isinstance(src, dict):
|
||
continue
|
||
resource = str(src.get("resource", "")).strip()
|
||
# §5.1 — an entry's own `usage_window` overrides the one written once as a
|
||
# sibling of `sources`. A count without its window has no units.
|
||
window = src.get("usage_window", meta.get("usage_window"))
|
||
out.append({
|
||
"title": str(src.get("title") or src.get("id") or resource),
|
||
"resource": resource,
|
||
"cid": resolve(resource, path, bundle) if resource else None,
|
||
"author": str(src.get("author", "")),
|
||
"usage_count": src.get("usage_count"),
|
||
"usage_window": (f"{window.get('from', '?')}→{window.get('to', '?')}"
|
||
if isinstance(window, dict) else ""),
|
||
"last_modified": str(src.get("last_modified") or ""),
|
||
})
|
||
return out
|
||
|
||
|
||
def read_trust(meta: dict):
|
||
"""§5.2 `generated` / `verified`, falling back to a v0.1 `timestamp` (§13.1)."""
|
||
gen = meta.get("generated")
|
||
if isinstance(gen, dict):
|
||
generated = {"by": str(gen.get("by", "")), "at": str(gen.get("at", ""))}
|
||
elif meta.get("timestamp"):
|
||
generated = {"by": "", "at": str(meta["timestamp"])}
|
||
else:
|
||
generated = None
|
||
ver = meta.get("verified")
|
||
# a bare mapping is one verification event (§5.2)
|
||
entries = [ver] if isinstance(ver, dict) else (ver if isinstance(ver, list) else [])
|
||
verified = [{"by": str(e.get("by", "")), "at": str(e.get("at", ""))}
|
||
for e in entries if isinstance(e, dict)]
|
||
return generated, verified
|
||
|
||
|
||
def build(bundle: Path):
|
||
nodes, edges, seen = [], [], set()
|
||
files = sorted(p for p in bundle.rglob("*.md") if p.is_file() and p.name not in RESERVED)
|
||
ids = {p.relative_to(bundle).with_suffix("").as_posix() for p in files}
|
||
for p in files:
|
||
cid = p.relative_to(bundle).with_suffix("").as_posix()
|
||
try:
|
||
raw = p.read_text(encoding="utf-8").lstrip("")
|
||
except (UnicodeDecodeError, OSError) as exc:
|
||
print(f"warning: skipping {p.relative_to(bundle)}: cannot read file: {exc}", file=sys.stderr)
|
||
ids.discard(cid)
|
||
continue
|
||
meta, body = split_frontmatter(raw)
|
||
body = body.strip()
|
||
generated, verified = read_trust(meta)
|
||
sources = read_sources(meta, p, bundle)
|
||
nodes.append({
|
||
"id": cid,
|
||
"type": str(meta.get("type", "Untyped")),
|
||
"title": str(meta.get("title", p.stem)),
|
||
"description": str(meta.get("description", "")),
|
||
"tags": meta.get("tags", []) if isinstance(meta.get("tags"), list) else [],
|
||
"group": cid.split("/")[0] if "/" in cid else "(root)",
|
||
"sz": max(24, min(70, 24 + len(body) // 200)),
|
||
"status": str(meta.get("status", "")),
|
||
"stale_after": str(meta.get("stale_after") or ""),
|
||
"generated": generated,
|
||
"verified": verified,
|
||
"sources": sources,
|
||
"body": body[:8000],
|
||
})
|
||
targets = link_targets(body) + [s["resource"] for s in sources if s["cid"]]
|
||
for t in targets:
|
||
tgt = resolve(t, p, bundle)
|
||
if tgt and tgt in ids and tgt != cid and (cid, tgt) not in seen:
|
||
seen.add((cid, tgt))
|
||
edges.append({"source": cid, "target": tgt})
|
||
return nodes, edges
|
||
|
||
|
||
HTML = r"""<!doctype html><html lang="en"><head><meta charset="utf-8">
|
||
<meta name="viewport" content="width=device-width,initial-scale=1">
|
||
<title>OKF — __NAME__</title>
|
||
<meta property="og:title" content="__OGTITLE__">
|
||
<meta property="og:description" content="__OGDESC__">
|
||
<meta property="og:type" content="website">
|
||
<meta name="twitter:card" content="summary_large_image">
|
||
__OGIMAGE__
|
||
<script src="https://cdn.jsdelivr.net/npm/cytoscape@3.30.2/dist/cytoscape.min.js"></script>
|
||
<script src="https://cdn.jsdelivr.net/npm/marked@14/marked.min.js"></script>
|
||
<script src="https://cdn.jsdelivr.net/npm/dompurify@3.4.12/dist/purify.min.js" integrity="sha384-piCcpDdJ7qVeK4Tv8Z6Hpcr3ZBIgP16TxQTPVfsLFdZ5uDgwc3Y8Ho7oUnqf12qu" crossorigin="anonymous"></script>
|
||
<style>
|
||
:root{--bg:#0e0f13;--panel:#16181f;--line:#262a35;--fg:#e6e8ee;--mut:#9aa3b2;--accent:#8ab4ff}
|
||
*{box-sizing:border-box} html,body{margin:0;height:100%;background:var(--bg);color:var(--fg);
|
||
font:14px/1.5 ui-sans-serif,system-ui,-apple-system,Segoe UI,Roboto,sans-serif}
|
||
/* The row must be stated. Left implicit it sizes to `auto`, i.e. to the tallest
|
||
item — a long concept body then stretched #side past the viewport and the page
|
||
grew its own scrollbar on top of the panel's, which in turn forced a spurious
|
||
horizontal one. Pinning the row to 100% keeps the panel scrolling inside. */
|
||
#app{display:grid;grid-template-columns:1fr 400px;grid-template-rows:100%;height:100vh}
|
||
#cy{width:100%;height:100%}
|
||
#side{border-left:1px solid var(--line);background:var(--panel);overflow:auto;padding:18px}
|
||
header{position:absolute;top:0;left:0;padding:14px 18px;z-index:5;pointer-events:none}
|
||
h1{font-size:15px;margin:0;font-weight:650} .sub{color:var(--mut);font-size:12px;margin-top:2px}
|
||
#bar{position:absolute;top:12px;left:50%;transform:translateX(-50%);z-index:5;display:flex;gap:8px}
|
||
#bar input,#bar select{background:var(--panel);border:1px solid var(--line);color:var(--fg);
|
||
border-radius:8px;padding:8px 10px;outline:none;font-size:13px}
|
||
#search{width:min(300px,32vw)}
|
||
#legend{position:absolute;bottom:14px;left:18px;z-index:5;display:flex;flex-wrap:wrap;gap:6px;max-width:60vw}
|
||
.chip{display:flex;align-items:center;gap:6px;background:var(--panel);border:1px solid var(--line);
|
||
border-radius:20px;padding:3px 10px;font-size:12px;color:var(--mut);cursor:pointer;user-select:none}
|
||
.chip.off{opacity:.4} .dot{width:10px;height:10px;border-radius:50%}
|
||
#side h2{font-size:17px;margin:.2em 0} .type{display:inline-block;border-radius:6px;padding:2px 8px;
|
||
font-size:11px;font-weight:600;color:#0e0f13} .desc{color:var(--mut);margin:8px 0 12px}
|
||
.tags{display:flex;gap:6px;flex-wrap:wrap;margin-bottom:12px}
|
||
.tag{background:#1d2230;border:1px solid var(--line);border-radius:6px;padding:1px 8px;font-size:11px;color:var(--mut)}
|
||
.meta{margin:10px 0;font-size:12px;color:var(--mut)} .meta div{padding:1px 0} .meta b{color:var(--fg);font-weight:600}
|
||
.sig{color:var(--mut)}
|
||
.badges{display:flex;gap:6px;flex-wrap:wrap;margin:8px 0}
|
||
.badge{border-radius:6px;padding:2px 8px;font-size:11px;font-weight:600;border:1px solid}
|
||
.t-unverified{color:#9aa3b2;border-color:#3a4150;background:#1d2230}
|
||
.t-machine{color:#8ab4ff;border-color:#2b4570;background:#141c2b}
|
||
.t-human{color:#4ade80;border-color:#276b45;background:#12211a}
|
||
.b-stale{color:#fca5a5;border-color:#7f2b2b;background:#241416}
|
||
.b-deprecated{color:#fbbf24;border-color:#7a5312;background:#241d10}
|
||
.rel{margin:10px 0} .rel h4{margin:0 0 4px;font-size:11px;text-transform:uppercase;letter-spacing:.05em;color:var(--mut)}
|
||
.rel a{display:block;color:var(--accent);cursor:pointer;font-size:13px;padding:1px 0;text-decoration:none}
|
||
.rel a:hover{text-decoration:underline}
|
||
.body{border-top:1px solid var(--line);padding-top:12px;margin-top:12px} .body table{border-collapse:collapse;display:block;overflow:auto}
|
||
.body td,.body th{border:1px solid var(--line);padding:4px 8px} .body code{background:#1d2230;padding:1px 5px;border-radius:4px}
|
||
.body pre{background:#1d2230;padding:10px;border-radius:8px;overflow:auto} .body img{max-width:100%}
|
||
.empty{color:var(--mut)} a{color:var(--accent)}
|
||
.src{pointer-events:auto;color:var(--accent);margin-left:10px;text-decoration:none} .src:hover{text-decoration:underline}
|
||
</style></head><body>
|
||
<div id="app"><div id="cy"></div><div id="side"><p class="empty">Click a concept to inspect it.</p></div></div>
|
||
<header><h1>__NAME__</h1><div class="sub">__N__ concepts · __E__ links · OKF v0.2__LINK__</div></header>
|
||
<div id="bar">
|
||
<input id="search" placeholder="search concepts…">
|
||
<select id="type"><option value="">all types</option></select>
|
||
<select id="layout">
|
||
<option value="cose">force</option><option value="concentric">concentric</option>
|
||
<option value="breadthfirst">breadth-first</option><option value="circle">circle</option><option value="grid">grid</option>
|
||
</select>
|
||
</div>
|
||
<div id="legend"></div>
|
||
<script>
|
||
const NODES=__NODES__, EDGES=__EDGES__;
|
||
const PALETTE=["#6E56CF","#D97757","#22C55E","#3B82F6","#EAB308","#EC4899","#14B8A6","#F97316","#A855F7","#0EA5E9","#84CC16","#EF4444","#64748B"];
|
||
const byId=Object.fromEntries(NODES.map(n=>[n.id,n]));
|
||
const outL={}, inL={};
|
||
NODES.forEach(n=>{outL[n.id]=[];inL[n.id]=[];});
|
||
EDGES.forEach(e=>{outL[e.source].push(e.target);inL[e.target].push(e.source);});
|
||
const types=[...new Set(NODES.map(n=>n.type))].sort();
|
||
const color=Object.fromEntries(types.map((t,i)=>[t,PALETTE[i%PALETTE.length]]));
|
||
const off=new Set();
|
||
const cy=cytoscape({container:document.getElementById('cy'),minZoom:.2,maxZoom:1.6,wheelSensitivity:.2,
|
||
elements:[...NODES.map(n=>({data:{...n,c:color[n.type]}})),...EDGES.map(e=>({data:e}))],
|
||
style:[
|
||
{selector:'node',style:{'background-color':'data(c)','label':'data(title)','color':'#e6e8ee',
|
||
'font-size':10,'text-wrap':'wrap','text-max-width':120,'text-valign':'bottom','text-margin-y':4,
|
||
'text-outline-width':2,'text-outline-color':'#0e0f13','min-zoomed-font-size':6,
|
||
'width':'data(sz)','height':'data(sz)'}},
|
||
{selector:'edge',style:{'width':1.2,'line-color':'#3a4150','target-arrow-color':'#3a4150',
|
||
'target-arrow-shape':'triangle','arrow-scale':.8,'curve-style':'bezier','opacity':.7}},
|
||
{selector:'.dim',style:{'opacity':.10}},{selector:'.hl',style:{'border-width':3,'border-color':'#fff'}}
|
||
],
|
||
layout:{name:'__LAYOUT__',animate:false,nodeRepulsion:9000,idealEdgeLength:90,padding:40}});
|
||
const side=document.getElementById('side');
|
||
const esc=s=>(s||'').replace(/[&<>"']/g,c=>({'&':'&','<':'<','>':'>','"':'"',"'":'''}[c]));
|
||
function relList(title,arr){if(!arr.length)return'';
|
||
return `<div class="rel"><h4>${title}</h4>${arr.map(id=>`<a data-go="${esc(id)}">${esc((byId[id]||{}).title||id)}</a>`).join('')}</div>`;}
|
||
// §5.3 — the trust tier is derived, never stored: no `verified` is unverified,
|
||
// `verified` by non-`human:` actors only is machine-confirmed, and any `human:`
|
||
// actor makes it human-reviewed. The exact lowercase prefix is the whole key.
|
||
// §5.5 — a concept is stale when now >= stale_after. PyYAML renders an unquoted
|
||
// datetime with a space separator, which Date.parse rejects in some engines.
|
||
// Advisory signals, not access control.
|
||
function trustTier(n){const v=n.verified||[];
|
||
if(!v.length)return['t-unverified','unverified'];
|
||
return v.some(e=>(e.by||'').startsWith('human:'))?['t-human','human-reviewed']
|
||
:['t-machine','machine-confirmed'];}
|
||
function badges(n){const [cls,label]=trustTier(n),out=[`<span class="badge ${cls}">${label}</span>`];
|
||
if(n.stale_after&&Date.parse(n.stale_after.replace(' ','T'))<=Date.now())out.push(`<span class="badge b-stale">stale since ${esc(n.stale_after)}</span>`);
|
||
if(n.status==='deprecated')out.push('<span class="badge b-deprecated">deprecated</span>');
|
||
return `<div class="badges">${out.join('')}</div>`;}
|
||
// OKF v0.2 trust (§5.2) + lifecycle (§5.4/§5.5). A v0.1 `timestamp` arrives here
|
||
// as generated.at with an empty `by`, so legacy bundles still show a date.
|
||
function metaBlock(n){const g=n.generated||{},rows=[];
|
||
if(n.status)rows.push(`<div>status <b>${esc(n.status)}</b></div>`);
|
||
if(g.at||g.by)rows.push(`<div>generated${g.at?` <b>${esc(g.at)}</b>`:''}${g.by?` by ${esc(g.by)}`:''}</div>`);
|
||
(n.verified||[]).forEach(v=>rows.push(`<div>verified${v.at?` <b>${esc(v.at)}</b>`:''}${v.by?` by ${esc(v.by)}`:''}</div>`));
|
||
if(n.stale_after)rows.push(`<div>stale after <b>${esc(n.stale_after)}</b></div>`);
|
||
return rows.length?`<div class="meta">${rows.join('')}</div>`:'';}
|
||
// Provenance (§5.1). A source may be another concept (graph link), an external
|
||
// URL, or a scope descriptor that is not followable at all.
|
||
function srcList(n){const s=n.sources||[];if(!s.length)return'';
|
||
return `<div class="rel"><h4>Sources</h4>${s.map(x=>{
|
||
const used=x.usage_count!=null?`used ${x.usage_count}×${x.usage_window?` (${x.usage_window})`:''}`:'';
|
||
const sig=[x.author,used,x.last_modified].filter(Boolean).join(' · ');
|
||
const label=esc(x.title||x.resource)+(sig?` <span class="sig">(${esc(sig)})</span>`:'');
|
||
if(x.cid&&byId[x.cid])return `<a data-go="${esc(x.cid)}">${label}</a>`;
|
||
if(/^https?:\/\//i.test(x.resource))return `<a href="${esc(x.resource)}" target="_blank" rel="noopener">${label}</a>`;
|
||
return `<span class="empty">${label}</span>`;}).join('')}</div>`;}
|
||
// Resolve an in-body markdown link href to a concept id, mirroring build()'s
|
||
// resolution: strip #anchor, require .md, absolute strips leading /, relative
|
||
// resolves against the current concept's dir. Returns null if it's not a concept.
|
||
function resolveHref(cid,href){let t=(href||'').split('#')[0];if(!t.endsWith('.md'))return null;
|
||
let tgt;if(t[0]==='/'){tgt=t.replace(/^\/+/,'').slice(0,-3);}
|
||
else{const base=cid.split('/').slice(0,-1);
|
||
for(const seg of t.slice(0,-3).split('/')){if(seg===''||seg==='.')continue;
|
||
if(seg==='..'){if(!base.length)return null;base.pop();}else base.push(seg);}
|
||
tgt=base.join('/');}
|
||
return byId[tgt]?tgt:null;}
|
||
function show(id){const n=byId[id];if(!n)return;const c=color[n.type];
|
||
side.innerHTML=`<span class="type" style="background:${c}">${esc(n.type)}</span>
|
||
<h2>${esc(n.title)}</h2><div class="desc">${esc(n.description)||'<span class=empty>no description</span>'}</div>
|
||
<div class="tags">${(n.tags||[]).map(t=>`<span class="tag">${esc(t)}</span>`).join('')}</div>
|
||
${badges(n)}${metaBlock(n)}${srcList(n)}${relList('Links to',outL[id])}${relList('Cited by',inL[id])}
|
||
<div class="body">${n.body?DOMPurify.sanitize(marked.parse(n.body)):'<span class=empty>empty body</span>'}</div>`;
|
||
side.querySelectorAll('[data-go]').forEach(a=>a.onclick=()=>select(a.getAttribute('data-go')));
|
||
side.querySelectorAll('.body a[href]').forEach(a=>{const tgt=resolveHref(id,a.getAttribute('href'));
|
||
if(tgt)a.onclick=e=>{e.preventDefault();select(tgt);};});}
|
||
function select(id){const ele=cy.getElementById(id);if(!ele.length)return;show(id);
|
||
cy.elements().removeClass('hl').addClass('dim');const nb=ele.closedNeighborhood();nb.removeClass('dim');ele.addClass('hl');
|
||
cy.animate({center:{eles:ele},duration:250});
|
||
try{if(decodeURIComponent((location.hash||'').slice(1))!==id)location.hash=encodeURIComponent(id);}catch(e){}}
|
||
cy.on('tap','node',e=>select(e.target.id()));
|
||
cy.on('tap',e=>{if(e.target===cy)cy.elements().removeClass('dim hl');});
|
||
function applyFilter(){const q=document.getElementById('search').value.toLowerCase();const ty=document.getElementById('type').value;
|
||
cy.batch(()=>cy.nodes().forEach(n=>{const d=n.data();
|
||
const m=(!q||(d.title+' '+d.type+' '+d.description+' '+(d.tags||[]).join(' ')).toLowerCase().includes(q))
|
||
&&(!ty||d.type===ty)&&!off.has(d.type);
|
||
n.style('display',m?'element':'none');}));}
|
||
let debounce;
|
||
document.getElementById('search').oninput=()=>{clearTimeout(debounce);debounce=setTimeout(applyFilter,150);};
|
||
document.getElementById('type').oninput=applyFilter;
|
||
const tysel=document.getElementById('type');types.forEach(t=>{const o=document.createElement('option');o.value=t;o.textContent=t;tysel.appendChild(o);});
|
||
let curLayout='__LAYOUT__';
|
||
document.getElementById('layout').onchange=e=>{const v=e.target.value;
|
||
if(v==='cose'&&NODES.length>__COSEMAX__&&!confirm(`force layout on ${NODES.length} concepts can freeze this tab — run anyway?`)){e.target.value=curLayout;return;}
|
||
curLayout=v;cy.layout({name:v,animate:true,padding:40,nodeRepulsion:9000,idealEdgeLength:90}).run();};
|
||
document.getElementById('legend').innerHTML=types.map(t=>`<span class="chip" data-t="${esc(t)}"><span class="dot" style="background:${color[t]}"></span>${esc(t)} (${NODES.filter(n=>n.type===t).length})</span>`).join('');
|
||
document.querySelectorAll('#legend .chip').forEach(ch=>ch.onclick=()=>{const t=ch.getAttribute('data-t');
|
||
if(off.has(t)){off.delete(t);ch.classList.remove('off');}else{off.add(t);ch.classList.add('off');}applyFilter();});
|
||
document.getElementById('layout').value='__LAYOUT__';
|
||
const Q=new URLSearchParams(location.search),QL=Q.get('layout'),QS=Q.get('select');
|
||
if(QL&&[...document.querySelectorAll('#layout option')].some(o=>o.value===QL)){document.getElementById('layout').value=QL;curLayout=QL;cy.layout({name:QL,animate:false,padding:40,nodeRepulsion:9000,idealEdgeLength:90}).run();}
|
||
function fromHash(){try{const h=decodeURIComponent((location.hash||'').slice(1));if(h&&byId[h])select(h);}catch(e){}}
|
||
addEventListener('hashchange',fromHash);
|
||
if(QS&&byId[QS])select(QS);else fromHash();
|
||
</script></body></html>"""
|
||
|
||
|
||
def render(bundle: Path, out: Path, title: str | None = None, link: str | None = None,
|
||
layout: str | None = None, og_image: str | None = None,
|
||
max_nodes: int | None = None):
|
||
nodes, edges = build(bundle)
|
||
if max_nodes is not None and len(nodes) > max_nodes:
|
||
sys.exit(f"error: {len(nodes)} concepts exceeds --max-nodes {max_nodes}")
|
||
if layout is None:
|
||
layout = "cose" if len(nodes) <= AUTO_COSE_MAX else "concentric"
|
||
if layout != "cose":
|
||
print(f"note: {len(nodes)} concepts > {AUTO_COSE_MAX} — using the linear 'concentric' "
|
||
"layout (force freezes the page at this size; pass --layout cose to override)",
|
||
file=sys.stderr)
|
||
if len(nodes) > SCALE_WARN:
|
||
print(f"warning: {len(nodes)} concepts — the page will load slowly and read as a hairball; "
|
||
f"consider rendering a subtree, e.g. okf_visualize.py {bundle}/<subdir>",
|
||
file=sys.stderr)
|
||
name = title or f"{bundle.resolve().parent.name}/{bundle.name}"
|
||
src = f' <a class="src" href="{link}" target="_blank" rel="noopener">source ↗</a>' if link else ""
|
||
aesc = lambda s: (s or "").replace("&", "&").replace('"', """).replace("<", "<").replace(">", ">")
|
||
og_title = aesc(f"OKF — {name}")
|
||
og_desc = aesc(f"{len(nodes)} concepts · interactive Open Knowledge Format knowledge graph")
|
||
og_img = (f'<meta property="og:image" content="{aesc(og_image)}">\n'
|
||
f'<meta name="twitter:image" content="{aesc(og_image)}">') if og_image else ""
|
||
subs = {"__NAME__": name, "__LINK__": src, "__LAYOUT__": layout,
|
||
"__COSEMAX__": str(AUTO_COSE_MAX),
|
||
"__OGTITLE__": og_title, "__OGDESC__": og_desc, "__OGIMAGE__": og_img,
|
||
"__N__": str(len(nodes)), "__E__": str(len(edges)),
|
||
"__NODES__": json_for_script(nodes), "__EDGES__": json_for_script(edges)}
|
||
# One pass, longest marker first: substituted content (e.g. a concept body that
|
||
# mentions "__EDGES__") must never itself be rescanned for other markers.
|
||
marker = re.compile("|".join(sorted(map(re.escape, subs), key=len, reverse=True)))
|
||
html = marker.sub(lambda m: subs[m.group(0)], HTML)
|
||
out.write_text(html, encoding="utf-8")
|
||
return len(nodes), len(edges)
|
||
|
||
|
||
def _force_utf8_stdio() -> None:
|
||
"""Reconfigure stdout/stderr to UTF-8 so status lines never crash on a
|
||
cp1252 (default Windows) console. `errors="replace"` is a fallback."""
|
||
for stream in (sys.stdout, sys.stderr):
|
||
reconfigure = getattr(stream, "reconfigure", None)
|
||
if reconfigure is not None:
|
||
try:
|
||
reconfigure(encoding="utf-8", errors="replace")
|
||
except (ValueError, OSError):
|
||
pass
|
||
|
||
|
||
def main() -> int:
|
||
_force_utf8_stdio()
|
||
ap = argparse.ArgumentParser(description="Render an OKF bundle as a self-contained HTML graph.")
|
||
ap.add_argument("bundle", type=Path)
|
||
ap.add_argument("-o", "--out", type=Path, default=None)
|
||
ap.add_argument("-t", "--title", default=None, help="graph title (default: parent/bundle dir name)")
|
||
ap.add_argument("-l", "--link", default=None, help="optional source URL shown in the header")
|
||
ap.add_argument("--layout", default=None,
|
||
choices=["cose", "concentric", "breadthfirst", "circle", "grid"],
|
||
help=f"initial graph layout (default: cose, or concentric above {AUTO_COSE_MAX} "
|
||
"concepts — force layout freezes the page on large bundles)")
|
||
ap.add_argument("--max-nodes", type=int, default=None,
|
||
help="refuse to render bundles with more concepts than this (useful in CI)")
|
||
ap.add_argument("--og-image", default=None,
|
||
help="absolute URL for the social-preview image (og:image / twitter:image)")
|
||
args = ap.parse_args()
|
||
if not args.bundle.is_dir():
|
||
print(f"error: {args.bundle} is not a directory", file=sys.stderr)
|
||
return 2
|
||
out = args.out or (args.bundle / "viz.html")
|
||
n, e = render(args.bundle, out, title=args.title, link=args.link, layout=args.layout,
|
||
og_image=args.og_image, max_nodes=args.max_nodes)
|
||
print(f"rendered {n} concepts, {e} links -> {out}")
|
||
return 0
|
||
|
||
|
||
if __name__ == "__main__":
|
||
raise SystemExit(main())
|