emdash-plugin-sitegraph 0.0.0-stage → 0.1.0

package/src/admin/graph-canvas.tsx

@@ -0,0 +1,222 @@
+// A small SVG graph view: pan, zoom, drag, fit. Hand-rolled on purpose: React Flow's
+// zustand dependency breaks against EmDash's use-sync-external-store shim and takes the
+// whole admin down with it. We already lay nodes out ourselves, so this is all we need.
+
+import * as React from "react";
+
+import { type Edge, isBroken, type Node, RELATION_LABEL, TYPE_LABEL } from "./api.js";
+
+import { NODE_H as H, NODE_W as W, type Point } from "./layout.js";
+
+export type { Point };
+type View = { x: number; y: number; k: number };
+const MIN_K = 0.2;
+const MAX_K = 2;
+const DRAG_THRESHOLD = 4;
+
+// Provenance is carried by line style, never colour alone (SPEC D4).
+const DASH = { DISCOVERED: undefined, DOCUMENTED: "7 5", INFERRED: "2 5" } as const;
+const QUIET = new Set(["LINKS_TO", "PUBLISHES_AS"]);
+
+/** Where the segment from a box's centre towards `to` leaves the box. */
+function boxExit(from: Point, to: Point): Point {
+	const dx = to.x - from.x;
+	const dy = to.y - from.y;
+	if (dx === 0 && dy === 0) return from;
+	const scale = 1 / Math.max(Math.abs(dx) / (W / 2 + 4), Math.abs(dy) / (H / 2 + 4));
+	return { x: from.x + dx * scale, y: from.y + dy * scale };
+}
+
+function fit(points: Point[], width: number, height: number): View {
+	if (points.length === 0 || width === 0) return { x: width / 2, y: height / 2, k: 1 };
+	const xs = points.map((p) => p.x);
+	const ys = points.map((p) => p.y);
+	const minX = Math.min(...xs) - W / 2 - 40;
+	const maxX = Math.max(...xs) + W / 2 + 40;
+	const minY = Math.min(...ys) - H / 2 - 40;
+	const maxY = Math.max(...ys) + H / 2 + 40;
+	const k = Math.min(1.2, Math.max(MIN_K, Math.min(width / (maxX - minX), height / (maxY - minY))));
+	return { k, x: width / 2 - ((minX + maxX) / 2) * k, y: height / 2 - ((minY + maxY) / 2) * k };
+}
+
+export function GraphCanvas({
+	nodes,
+	edges,
+	positions,
+	centerId,
+	selectedId,
+	onSelect,
+	onExpand,
+	onMove,
+}: {
+	nodes: Node[];
+	edges: Edge[];
+	positions: Map<string, Point>;
+	centerId: string | null;
+	selectedId: string | null;
+	onSelect: (id: string | null) => void;
+	onExpand: (id: string) => void;
+	onMove: (id: string, point: Point) => void;
+}) {
+	const svgRef = React.useRef<SVGSVGElement>(null);
+	const [view, setView] = React.useState<View>({ x: 0, y: 0, k: 1 });
+	const drag = React.useRef<{ kind: "pan" | "node"; id?: string; start: Point; origin: Point; moved: boolean } | null>(null);
+	const markerId = React.useId().replace(/:/g, "");
+
+	const fitAll = React.useCallback(() => {
+		const el = svgRef.current;
+		if (!el) return;
+		setView(fit([...positions.values()], el.clientWidth, el.clientHeight));
+	}, [positions]);
+
+	// Refit when the graph is re-centred (a new search pick or an impact view), not on every drag.
+	React.useEffect(fitAll, [centerId, nodes.length]);
+
+	// Wheel zoom around the cursor. Registered natively so preventDefault stops page scroll.
+	React.useEffect(() => {
+		const el = svgRef.current;
+		if (!el) return;
+		const onWheel = (e: WheelEvent) => {
+			e.preventDefault();
+			const rect = el.getBoundingClientRect();
+			const cx = e.clientX - rect.left;
+			const cy = e.clientY - rect.top;
+			setView((v) => {
+				const k = Math.min(MAX_K, Math.max(MIN_K, v.k * Math.exp(-e.deltaY * 0.0015)));
+				return { k, x: cx - ((cx - v.x) * k) / v.k, y: cy - ((cy - v.y) * k) / v.k };
+			});
+		};
+		el.addEventListener("wheel", onWheel, { passive: false });
+		return () => el.removeEventListener("wheel", onWheel);
+	}, []);
+
+	const zoomBy = (factor: number) => {
+		const el = svgRef.current;
+		if (!el) return;
+		const cx = el.clientWidth / 2;
+		const cy = el.clientHeight / 2;
+		setView((v) => {
+			const k = Math.min(MAX_K, Math.max(MIN_K, v.k * factor));
+			return { k, x: cx - ((cx - v.x) * k) / v.k, y: cy - ((cy - v.y) * k) / v.k };
+		});
+	};
+
+	const onPointerDown = (e: React.PointerEvent, id?: string) => {
+		if (e.button !== 0) return;
+		e.stopPropagation();
+		(e.currentTarget as Element).setPointerCapture(e.pointerId);
+		const origin = id ? positions.get(id)! : { x: view.x, y: view.y };
+		drag.current = { kind: id ? "node" : "pan", id, start: { x: e.clientX, y: e.clientY }, origin, moved: false };
+	};
+
+	const onPointerMove = (e: React.PointerEvent) => {
+		const d = drag.current;
+		if (!d) return;
+		const dx = e.clientX - d.start.x;
+		const dy = e.clientY - d.start.y;
+		if (!d.moved && Math.hypot(dx, dy) < DRAG_THRESHOLD) return;
+		d.moved = true;
+		if (d.kind === "pan") setView((v) => ({ ...v, x: d.origin.x + dx, y: d.origin.y + dy }));
+		else if (d.id) onMove(d.id, { x: d.origin.x + dx / view.k, y: d.origin.y + dy / view.k });
+	};
+
+	const onPointerUp = () => {
+		const d = drag.current;
+		drag.current = null;
+		if (d && !d.moved) onSelect(d.kind === "node" ? d.id! : null);
+	};
+
+	const visible = nodes.filter((n) => positions.has(n.id));
+
+	return (
+		<div className="sg-canvas">
+			<svg
+				ref={svgRef}
+				className="sg-svg"
+				role="group"
+				aria-label="Dependency graph"
+				onPointerDown={(e) => onPointerDown(e)}
+				onPointerMove={onPointerMove}
+				onPointerUp={onPointerUp}
+			>
+				<defs>
+					<marker id={markerId} viewBox="0 0 10 10" refX="9" refY="5" markerWidth="8" markerHeight="8" orient="auto-start-reverse">
+						<path d="M0,0 L10,5 L0,10 z" className="sg-arrow" />
+					</marker>
+					<pattern id={`${markerId}-dots`} width={24 * view.k} height={24 * view.k} x={view.x} y={view.y} patternUnits="userSpaceOnUse">
+						<circle cx={1} cy={1} r={1} className="sg-dot" />
+					</pattern>
+				</defs>
+				<rect width="100%" height="100%" fill={`url(#${markerId}-dots)`} />
+				<g transform={`translate(${view.x} ${view.y}) scale(${view.k})`}>
+					{edges.map((edge) => {
+						const a = positions.get(edge.sourceNodeId);
+						const b = positions.get(edge.targetNodeId);
+						if (!a || !b) return null;
+						const start = boxExit(a, b);
+						const end = boxExit(b, a);
+						const label = QUIET.has(edge.relation) ? null : edge.label || RELATION_LABEL[edge.relation];
+						const active = edge.sourceNodeId === selectedId || edge.targetNodeId === selectedId;
+						return (
+							<g key={edge.id} className="sg-edge" data-prov={edge.provenance} data-active={active || undefined}>
+								<line x1={start.x} y1={start.y} x2={end.x} y2={end.y} strokeDasharray={DASH[edge.provenance]} markerEnd={`url(#${markerId})`} />
+								{label ? (
+									<text x={(start.x + end.x) / 2} y={(start.y + end.y) / 2 - 6} textAnchor="middle">
+										{label}
+									</text>
+								) : null}
+							</g>
+						);
+					})}
+					{visible.map((node) => {
+						const p = positions.get(node.id)!;
+						const broken = isBroken(node);
+						return (
+							<foreignObject key={node.id} x={p.x - W / 2} y={p.y - H / 2} width={W} height={H} className="sg-fo">
+								<div
+									className="sg-node"
+									data-type={node.type}
+									data-broken={broken || undefined}
+									data-selected={node.id === selectedId || undefined}
+									data-center={node.id === centerId || undefined}
+									role="button"
+									tabIndex={0}
+									aria-pressed={node.id === selectedId}
+									aria-label={`${broken ? "Broken link" : TYPE_LABEL[node.type]}: ${node.label}. Press Enter to inspect, Shift+Enter to show its connections.`}
+									title={node.label}
+									onPointerDown={(e) => onPointerDown(e, node.id)}
+									onDoubleClick={() => onExpand(node.id)}
+									onKeyDown={(e) => {
+										if (e.key !== "Enter" && e.key !== " ") return;
+										e.preventDefault();
+										if (e.shiftKey) onExpand(node.id);
+										else onSelect(node.id);
+									}}
+								>
+									<span className="sg-node-type">{broken ? "Broken link" : TYPE_LABEL[node.type]}</span>
+									<span className="sg-node-label">{node.label}</span>
+									{node.criticality && node.criticality !== "LOW" ? (
+										<span className="sg-node-crit" data-level={node.criticality}>
+											{node.criticality[0] + node.criticality.slice(1).toLowerCase()}
+										</span>
+									) : null}
+								</div>
+							</foreignObject>
+						);
+					})}
+				</g>
+			</svg>
+			<div className="sg-zoom" role="toolbar" aria-label="Zoom">
+				<button type="button" onClick={() => zoomBy(1.25)} aria-label="Zoom in">
+					+
+				</button>
+				<button type="button" onClick={() => zoomBy(0.8)} aria-label="Zoom out">
+					−
+				</button>
+				<button type="button" onClick={fitAll}>
+					Fit
+				</button>
+			</div>
+		</div>
+	);
+}

package/src/admin/index.tsx

@@ -0,0 +1,47 @@
+import "./sitegraph.css";
+
+import { Loader } from "@cloudflare/kumo";
+import type { PluginAdminExports } from "emdash";
+import * as React from "react";
+
+import { api, message, type Overview } from "./api.js";
+import { Explorer } from "./explorer.js";
+
+function OverviewWidget() {
+	const [overview, setOverview] = React.useState<Overview>();
+	const [error, setError] = React.useState<string>();
+	React.useEffect(() => {
+		api.overview().then(setOverview, (e: unknown) => setError(message(e)));
+	}, []);
+
+	if (error) return <p role="alert">{error}</p>;
+	if (!overview) return <Loader />;
+	if (!overview.scan.last) {
+		return (
+			<p className="sg-widget">
+				Your site hasn't been mapped yet. <a href="/_emdash/admin/plugins/sitegraph/">Run the first scan</a>
+			</p>
+		);
+	}
+	return (
+		<div className="sg-widget">
+			<p>
+				{overview.counts.CONTENT} entries mapped,{" "}
+				<a href="/_emdash/admin/plugins/sitegraph/" data-alert={overview.brokenLinks > 0 || undefined}>
+					{overview.brokenLinks === 0
+						? "no broken internal links"
+						: `${overview.brokenLinks} broken internal link${overview.brokenLinks === 1 ? "" : "s"}`}
+				</a>
+				.
+			</p>
+		</div>
+	);
+}
+
+export const pages: PluginAdminExports["pages"] = {
+	"/": Explorer,
+};
+
+export const widgets: PluginAdminExports["widgets"] = {
+	overview: OverviewWidget,
+};

package/src/admin/layout.ts

@@ -0,0 +1,114 @@
+// Graph layout: seed new nodes on a ring, then relax them so boxes don't overlap each other
+// and don't sit on top of lines they aren't part of. Only `movable` nodes move, so what the
+// person already sees (or dragged into place) stays put.
+
+export type Point = { x: number; y: number };
+
+export const NODE_W = 176;
+export const NODE_H = 62;
+
+const GAP_X = NODE_W + 36;
+const GAP_Y = NODE_H + 36;
+const EDGE_LENGTH = 250;
+const LINE_CLEARANCE = NODE_H / 2 + 18;
+const ITERATIONS = 220;
+// ponytail: O(n²) pairs + O(edges × nodes) line checks per step; fine for the ≤500-node
+// views the API returns. A spatial grid is the upgrade if views ever get bigger.
+
+/** Place new nodes on a ring around `origin`. */
+export function seedRing(origin: Point, ids: string[], taken: Map<string, Point>): Map<string, Point> {
+	const fresh = ids.filter((id) => !taken.has(id));
+	const radius = Math.max(EDGE_LENGTH, fresh.length * 34);
+	const placed = new Map<string, Point>();
+	fresh.forEach((id, i) => {
+		const angle = (2 * Math.PI * i) / Math.max(fresh.length, 1) - Math.PI / 2;
+		placed.set(id, { x: origin.x + radius * Math.cos(angle), y: origin.y + radius * Math.sin(angle) });
+	});
+	return placed;
+}
+
+/** Push `movable` nodes apart and off unrelated lines; pull linked nodes toward EDGE_LENGTH. */
+export function relax(
+	positions: Map<string, Point>,
+	edges: Array<{ sourceNodeId: string; targetNodeId: string }>,
+	movable: Set<string>,
+): Map<string, Point> {
+	const pos = new Map([...positions].map(([id, p]) => [id, { ...p }]));
+	const ids = [...pos.keys()];
+	const links = edges.filter((e) => pos.has(e.sourceNodeId) && pos.has(e.targetNodeId) && e.sourceNodeId !== e.targetNodeId);
+	if (![...movable].some((id) => pos.has(id))) return pos;
+
+	for (let step = 0; step < ITERATIONS; step++) {
+		const cooling = 1 - step / ITERATIONS;
+		const force = new Map(ids.map((id) => [id, { x: 0, y: 0 }]));
+		const add = (id: string, x: number, y: number) => {
+			const f = force.get(id)!;
+			f.x += x;
+			f.y += y;
+		};
+
+		// Boxes repel when they come closer than one box plus a gap.
+		for (let i = 0; i < ids.length; i++) {
+			for (let j = i + 1; j < ids.length; j++) {
+				const a = pos.get(ids[i]!)!;
+				const b = pos.get(ids[j]!)!;
+				let dx = b.x - a.x;
+				let dy = b.y - a.y;
+				if (dx === 0 && dy === 0) dx = (i % 2 ? 1 : -1) * 0.5;
+				const ox = GAP_X - Math.abs(dx);
+				const oy = GAP_Y - Math.abs(dy);
+				if (ox <= 0 || oy <= 0) continue;
+				// Separate along the axis that needs the smaller move.
+				const [px, py] = ox / GAP_X < oy / GAP_Y ? [Math.sign(dx) * ox, 0] : [0, Math.sign(dy || 1) * oy];
+				add(ids[i]!, -px / 2, -py / 2);
+				add(ids[j]!, px / 2, py / 2);
+			}
+		}
+
+		// Linked boxes settle at a readable distance.
+		for (const e of links) {
+			const a = pos.get(e.sourceNodeId)!;
+			const b = pos.get(e.targetNodeId)!;
+			const dx = b.x - a.x;
+			const dy = b.y - a.y;
+			const d = Math.hypot(dx, dy) || 1;
+			const pull = ((d - EDGE_LENGTH) / d) * 0.06;
+			add(e.sourceNodeId, dx * pull, dy * pull);
+			add(e.targetNodeId, -dx * pull, -dy * pull);
+		}
+
+		// A box sitting on a line it isn't part of gets nudged sideways off it.
+		for (const e of links) {
+			const a = pos.get(e.sourceNodeId)!;
+			const b = pos.get(e.targetNodeId)!;
+			const vx = b.x - a.x;
+			const vy = b.y - a.y;
+			const len2 = vx * vx + vy * vy || 1;
+			for (const id of ids) {
+				if (id === e.sourceNodeId || id === e.targetNodeId || !movable.has(id)) continue;
+				const p = pos.get(id)!;
+				const t = ((p.x - a.x) * vx + (p.y - a.y) * vy) / len2;
+				if (t <= 0.05 || t >= 0.95) continue;
+				const cx = a.x + t * vx;
+				const cy = a.y + t * vy;
+				let nx = p.x - cx;
+				let ny = p.y - cy;
+				const d = Math.hypot(nx, ny);
+				if (d >= LINE_CLEARANCE) continue;
+				if (d < 1e-6) [nx, ny] = [-vy, vx];
+				const n = Math.hypot(nx, ny) || 1;
+				add(id, (nx / n) * (LINE_CLEARANCE - d), (ny / n) * (LINE_CLEARANCE - d));
+			}
+		}
+
+		for (const id of ids) {
+			if (!movable.has(id)) continue;
+			const f = force.get(id)!;
+			const p = pos.get(id)!;
+			const limit = 40 * cooling + 2;
+			p.x += Math.max(-limit, Math.min(limit, f.x));
+			p.y += Math.max(-limit, Math.min(limit, f.y));
+		}
+	}
+	return pos;
+}

package/src/admin/node-picker.tsx

@@ -0,0 +1,69 @@
+import * as React from "react";
+
+import { api, isBroken, type Node, TYPE_LABEL } from "./api.js";
+
+/** Debounced search over graph nodes. Used to pick a relationship target. */
+export function useNodeSearch(query: string, opts: { type?: Node["type"]; broken?: boolean } = {}) {
+	const [state, setState] = React.useState<{ items: Node[]; loading: boolean; error?: string }>({ items: [], loading: false });
+	const { type, broken } = opts;
+	React.useEffect(() => {
+		let live = true;
+		setState((s) => ({ ...s, loading: true }));
+		const timer = setTimeout(() => {
+			api
+				.search(query.trim(), { type, broken })
+				.then((r) => live && setState({ items: r.items, loading: false }))
+				.catch((e: unknown) => live && setState({ items: [], loading: false, error: e instanceof Error ? e.message : String(e) }));
+		}, 200);
+		return () => {
+			live = false;
+			clearTimeout(timer);
+		};
+	}, [query, type, broken]);
+	return state;
+}
+
+export function NodePicker({ value, onChange, exclude }: { value: Node | null; onChange: (node: Node | null) => void; exclude?: string }) {
+	const [query, setQuery] = React.useState("");
+	const { items, loading } = useNodeSearch(query);
+	const options = items.filter((n) => n.id !== exclude).slice(0, 8);
+	const id = React.useId();
+
+	if (value) {
+		return (
+			<div className="sg-picked">
+				<span>
+					<span className="sg-kind" data-type={value.type}>
+						{TYPE_LABEL[value.type]}
+					</span>{" "}
+					{value.label}
+				</span>
+				<button type="button" className="sg-link" onClick={() => onChange(null)}>
+					Change
+				</button>
+			</div>
+		);
+	}
+
+	return (
+		<div className="sg-field">
+			<label htmlFor={id}>
+				<span>Target</span>
+			</label>
+			<input id={id} type="search" value={query} onChange={(e) => setQuery(e.target.value)} placeholder="Start typing a name or path" autoComplete="off" />
+			<ul className="sg-options" role="listbox" aria-busy={loading}>
+				{options.map((n) => (
+					<li key={n.id}>
+						<button type="button" onClick={() => onChange(n)}>
+							<span className="sg-kind" data-type={n.type}>
+								{isBroken(n) ? "Broken link" : TYPE_LABEL[n.type]}
+							</span>{" "}
+							{n.label}
+						</button>
+					</li>
+				))}
+				{!loading && options.length === 0 ? <li className="sg-muted">No matches. Names match from their first letter.</li> : null}
+			</ul>
+		</div>
+	);
+}