create-eziwiki 0.1.0

package/template/lib/graph/build.ts

@@ -0,0 +1,214 @@
+import { unified } from 'unified';
+import remarkParse from 'remark-parse';
+import remarkGfm from 'remark-gfm';
+import { visit } from 'unist-util-visit';
+import type { Root, Link, Text } from 'mdast';
+import { getContentRegistry, type ContentDoc } from '../content/registry';
+import { resolveTarget } from '../content/resolver';
+import { findWikiLinks } from '../markdown/wikilink';
+import { getSite } from '../site';
+import { cached } from '../cache';
+
+/**
+ * The document link graph.
+ *
+ * Built by scanning every page for links that point at another page, whether
+ * written as `[[wiki links]]` or as ordinary Markdown links. The result drives
+ * the backlinks panel and the graph view, and surfaces dangling references that
+ * would otherwise go unnoticed until a reader clicked one.
+ *
+ * Server-only.
+ */
+
+/** A link from one document to another. */
+export interface GraphEdge {
+  /** Path of the document containing the link */
+  from: string;
+  /** Path of the document being linked to */
+  to: string;
+}
+
+/** A link that could not be resolved to any document. */
+export interface BrokenLink {
+  /** Path of the document containing the link */
+  from: string;
+  /** The target as written */
+  target: string;
+  /** Why it failed: nothing matched, or the shorthand matched several pages */
+  reason: 'missing' | 'ambiguous';
+  /** Matching paths, when the target was ambiguous */
+  candidates?: string[];
+}
+
+/** A node in the rendered graph. */
+export interface GraphNode {
+  /** Content path, used as the node id */
+  path: string;
+  /** Display title */
+  title: string;
+  /** Href for navigation */
+  url: string;
+  /** Number of links in and out, used to size the node */
+  degree: number;
+}
+
+/** The full graph. */
+export interface LinkGraph {
+  /** Every visible document */
+  nodes: GraphNode[];
+  /** Every resolved link between documents */
+  edges: GraphEdge[];
+  /** Documents linking *to* a given path */
+  backlinks: Map<string, string[]>;
+  /** Documents linked *from* a given path */
+  outbound: Map<string, string[]>;
+  /** Links that resolved to nothing */
+  broken: BrokenLink[];
+}
+
+/** Parser used for scanning; no rendering plugins, so it stays fast. */
+const parser = unified().use(remarkParse).use(remarkGfm);
+
+/**
+ * Extracts the document path an ordinary Markdown link points at.
+ *
+ * External links, anchors, and links to files that are not pages all yield
+ * null, so only real page-to-page references become edges.
+ *
+ * @param url - The link's href as authored
+ * @returns The referenced content path, or null
+ */
+function resolveMarkdownLink(url: string): string | null {
+  if (!url || url.startsWith('#')) return null;
+  if (/^[a-z][a-z0-9+.-]*:/i.test(url) || url.startsWith('//')) return null;
+
+  const path = url.split(/[#?]/)[0].replace(/^\/+/, '').replace(/\.md$/i, '').replace(/\/+$/, '');
+
+  if (!path) return null;
+
+  return getContentRegistry().byPath.has(path) ? path : null;
+}
+
+/**
+ * Collects every outbound reference in one document.
+ *
+ * Text nodes are scanned for wiki links and link nodes for Markdown links,
+ * which means references written inside code are excluded — documentation
+ * showing the syntax should not register as a link.
+ *
+ * @param doc - Document to scan
+ * @returns Resolved targets and any broken references
+ */
+function scanDoc(doc: ContentDoc): { targets: Set<string>; broken: BrokenLink[] } {
+  const tree = parser.parse(doc.content) as Root;
+  const targets = new Set<string>();
+  const broken: BrokenLink[] = [];
+
+  visit(tree, (node) => {
+    if (node.type === 'link') {
+      const path = resolveMarkdownLink((node as Link).url);
+      if (path && path !== doc.path) targets.add(path);
+      return;
+    }
+
+    if (node.type !== 'text') return;
+
+    for (const link of findWikiLinks((node as Text).value)) {
+      // An anchor-only link stays within the page and is not an edge.
+      if (!link.target) continue;
+
+      const resolution = resolveTarget(link.target);
+
+      if (resolution.doc) {
+        if (resolution.doc.path !== doc.path) targets.add(resolution.doc.path);
+        continue;
+      }
+
+      broken.push({
+        from: doc.path,
+        target: link.target,
+        reason: resolution.kind === 'ambiguous' ? 'ambiguous' : 'missing',
+        candidates: resolution.candidates,
+      });
+    }
+  });
+
+  return { targets, broken };
+}
+
+let memo: LinkGraph | null = null;
+
+/**
+ * Builds the link graph across all visible documents, memoised per process.
+ *
+ * Hidden pages are left out entirely: they do not appear as nodes, and links
+ * to them do not become edges, so an unlisted page cannot be discovered by
+ * reading the graph.
+ *
+ * @returns The graph
+ */
+export function getLinkGraph(): LinkGraph {
+  const hit = cached(memo);
+  if (hit) return hit;
+
+  const { docs } = getContentRegistry();
+  const { urlMap, hiddenPaths } = getSite();
+
+  const visible = docs.filter((doc) => !hiddenPaths.has(doc.path));
+  const visiblePaths = new Set(visible.map((doc) => doc.path));
+
+  const edges: GraphEdge[] = [];
+  const broken: BrokenLink[] = [];
+  const backlinks = new Map<string, string[]>();
+  const outbound = new Map<string, string[]>();
+
+  for (const doc of visible) {
+    const scan = scanDoc(doc);
+    broken.push(...scan.broken);
+
+    const targets = [...scan.targets].filter((target) => visiblePaths.has(target)).sort();
+    outbound.set(doc.path, targets);
+
+    for (const target of targets) {
+      edges.push({ from: doc.path, to: target });
+
+      const existing = backlinks.get(target);
+      if (existing) existing.push(doc.path);
+      else backlinks.set(target, [doc.path]);
+    }
+  }
+
+  for (const list of backlinks.values()) list.sort();
+
+  const degree = new Map<string, number>();
+  for (const edge of edges) {
+    degree.set(edge.from, (degree.get(edge.from) ?? 0) + 1);
+    degree.set(edge.to, (degree.get(edge.to) ?? 0) + 1);
+  }
+
+  const nodes: GraphNode[] = visible.map((doc) => ({
+    path: doc.path,
+    title: doc.title,
+    url: `/${urlMap.toUrl[doc.path] ?? doc.path}`,
+    degree: degree.get(doc.path) ?? 0,
+  }));
+
+  memo = { nodes, edges, backlinks, outbound, broken };
+  return memo;
+}
+
+/**
+ * Returns the documents that link to a given page.
+ *
+ * @param path - Content path of the page
+ * @returns Nodes linking to it, sorted by title
+ */
+export function getBacklinks(path: string): GraphNode[] {
+  const graph = getLinkGraph();
+  const byPath = new Map(graph.nodes.map((node) => [node.path, node]));
+
+  return (graph.backlinks.get(path) ?? [])
+    .map((from) => byPath.get(from))
+    .filter((node): node is GraphNode => node !== undefined)
+    .sort((a, b) => a.title.localeCompare(b.title));
+}

package/template/lib/graph/layout.test.ts

@@ -0,0 +1,189 @@
+import { describe, it, expect } from 'vitest';
+import { bounds, layout, seedPositions, step, type LayoutEdge } from './layout';
+
+const AREA = { width: 800, height: 600 };
+
+describe('seedPositions', () => {
+  it('places every node inside the area', () => {
+    const nodes = seedPositions(['a', 'b', 'c'], AREA);
+
+    expect(nodes).toHaveLength(3);
+    for (const node of nodes) {
+      expect(node.x).toBeGreaterThan(0);
+      expect(node.x).toBeLessThan(AREA.width);
+      expect(node.y).toBeGreaterThan(0);
+      expect(node.y).toBeLessThan(AREA.height);
+    }
+  });
+
+  it('gives distinct starting positions', () => {
+    const nodes = seedPositions(['a', 'b', 'c', 'd'], AREA);
+    const keys = new Set(nodes.map((node) => `${node.x.toFixed(3)},${node.y.toFixed(3)}`));
+
+    expect(keys.size).toBe(4);
+  });
+
+  it('is deterministic', () => {
+    const a = seedPositions(['x', 'y'], AREA);
+    const b = seedPositions(['x', 'y'], AREA);
+
+    expect(a).toEqual(b);
+  });
+
+  it('handles a single node', () => {
+    expect(seedPositions(['only'], AREA)).toHaveLength(1);
+  });
+
+  it('handles no nodes', () => {
+    expect(seedPositions([], AREA)).toEqual([]);
+  });
+});
+
+describe('step', () => {
+  it('does nothing with no nodes', () => {
+    expect(() => step([], [], AREA, 1)).not.toThrow();
+  });
+
+  it('pushes unconnected nodes apart', () => {
+    const nodes = [
+      { id: 'a', x: 400, y: 300, vx: 0, vy: 0 },
+      { id: 'b', x: 410, y: 300, vx: 0, vy: 0 },
+    ];
+    const before = Math.hypot(nodes[0].x - nodes[1].x, nodes[0].y - nodes[1].y);
+
+    step(nodes, [], AREA, 1);
+
+    const after = Math.hypot(nodes[0].x - nodes[1].x, nodes[0].y - nodes[1].y);
+    expect(after).toBeGreaterThan(before);
+  });
+
+  it('pulls connected nodes together when they are far apart', () => {
+    const nodes = [
+      { id: 'a', x: 50, y: 300, vx: 0, vy: 0 },
+      { id: 'b', x: 750, y: 300, vx: 0, vy: 0 },
+    ];
+    const edges: LayoutEdge[] = [{ from: 'a', to: 'b' }];
+    const before = Math.abs(nodes[0].x - nodes[1].x);
+
+    for (let i = 0; i < 20; i++) step(nodes, edges, AREA, 1);
+
+    expect(Math.abs(nodes[0].x - nodes[1].x)).toBeLessThan(before);
+  });
+
+  it('separates coincident nodes instead of producing NaN', () => {
+    const nodes = [
+      { id: 'a', x: 400, y: 300, vx: 0, vy: 0 },
+      { id: 'b', x: 400, y: 300, vx: 0, vy: 0 },
+    ];
+
+    step(nodes, [], AREA, 1);
+
+    for (const node of nodes) {
+      expect(Number.isFinite(node.x)).toBe(true);
+      expect(Number.isFinite(node.y)).toBe(true);
+    }
+    expect(nodes[0].x !== nodes[1].x || nodes[0].y !== nodes[1].y).toBe(true);
+  });
+
+  it('leaves fixed nodes in place', () => {
+    const nodes = [
+      { id: 'a', x: 100, y: 100, vx: 0, vy: 0, fixed: true },
+      { id: 'b', x: 110, y: 100, vx: 0, vy: 0 },
+    ];
+
+    step(nodes, [], AREA, 1);
+
+    expect(nodes[0].x).toBe(100);
+    expect(nodes[0].y).toBe(100);
+  });
+
+  it('ignores edges referencing unknown nodes', () => {
+    const nodes = [{ id: 'a', x: 400, y: 300, vx: 0, vy: 0 }];
+
+    expect(() => step(nodes, [{ from: 'a', to: 'ghost' }], AREA, 1)).not.toThrow();
+    expect(Number.isFinite(nodes[0].x)).toBe(true);
+  });
+
+  it('ignores self-links', () => {
+    const nodes = [{ id: 'a', x: 400, y: 300, vx: 0, vy: 0 }];
+
+    step(nodes, [{ from: 'a', to: 'a' }], AREA, 1);
+
+    expect(Number.isFinite(nodes[0].x)).toBe(true);
+  });
+});
+
+describe('layout', () => {
+  it('produces finite positions for a connected graph', () => {
+    const ids = ['a', 'b', 'c', 'd', 'e'];
+    const edges: LayoutEdge[] = [
+      { from: 'a', to: 'b' },
+      { from: 'b', to: 'c' },
+      { from: 'c', to: 'd' },
+      { from: 'd', to: 'e' },
+    ];
+
+    for (const node of layout(ids, edges, AREA)) {
+      expect(Number.isFinite(node.x)).toBe(true);
+      expect(Number.isFinite(node.y)).toBe(true);
+    }
+  });
+
+  it('is deterministic across runs', () => {
+    const ids = ['a', 'b', 'c'];
+    const edges: LayoutEdge[] = [{ from: 'a', to: 'b' }];
+
+    expect(layout(ids, edges, AREA)).toEqual(layout(ids, edges, AREA));
+  });
+
+  it('places linked nodes closer than unlinked ones', () => {
+    const nodes = layout(['a', 'b', 'far'], [{ from: 'a', to: 'b' }], AREA);
+    const byId = new Map(nodes.map((node) => [node.id, node]));
+
+    const linked = Math.hypot(
+      byId.get('a')!.x - byId.get('b')!.x,
+      byId.get('a')!.y - byId.get('b')!.y,
+    );
+    const unlinked = Math.hypot(
+      byId.get('a')!.x - byId.get('far')!.x,
+      byId.get('a')!.y - byId.get('far')!.y,
+    );
+
+    expect(linked).toBeLessThan(unlinked);
+  });
+
+  it('handles a graph with no edges', () => {
+    expect(layout(['a', 'b'], [], AREA)).toHaveLength(2);
+  });
+});
+
+describe('bounds', () => {
+  it('covers every node with padding', () => {
+    const box = bounds(
+      [
+        { id: 'a', x: 100, y: 100, vx: 0, vy: 0 },
+        { id: 'b', x: 300, y: 200, vx: 0, vy: 0 },
+      ],
+      10,
+    );
+
+    expect(box.x).toBe(90);
+    expect(box.y).toBe(90);
+    expect(box.width).toBe(220);
+    expect(box.height).toBe(120);
+  });
+
+  it('never returns a zero-size box for a single node', () => {
+    const box = bounds([{ id: 'a', x: 5, y: 5, vx: 0, vy: 0 }], 0);
+
+    expect(box.width).toBeGreaterThan(0);
+    expect(box.height).toBeGreaterThan(0);
+  });
+
+  it('returns a usable box for no nodes', () => {
+    const box = bounds([]);
+
+    expect(box.width).toBeGreaterThan(0);
+    expect(box.height).toBeGreaterThan(0);
+  });
+});

package/template/lib/graph/layout.ts

@@ -0,0 +1,247 @@
+/**
+ * Force-directed graph layout.
+ *
+ * A small Fruchterman–Reingold implementation rather than a charting library:
+ * published pages must be self-contained, and a graph of this size does not
+ * justify shipping a general-purpose layout engine to every reader.
+ *
+ * Pure and isomorphic — no DOM access — so it can be unit-tested directly.
+ */
+
+/** A node being laid out. */
+export interface LayoutNode {
+  /** Stable identifier, matching edge endpoints */
+  id: string;
+  /** Current position, mutated in place as the simulation runs */
+  x: number;
+  y: number;
+  /** Velocity carried between steps */
+  vx: number;
+  vy: number;
+  /** Pinned nodes are not moved by forces */
+  fixed?: boolean;
+}
+
+/** An edge between two node ids. */
+export interface LayoutEdge {
+  from: string;
+  to: string;
+}
+
+/** Tunable simulation parameters. */
+export interface LayoutOptions {
+  /** Width of the layout area */
+  width: number;
+  /** Height of the layout area */
+  height: number;
+  /** Multiplier on the natural spring length; higher spreads nodes further */
+  spacing?: number;
+}
+
+/** Fraction of velocity retained each step. */
+const DAMPING = 0.9;
+
+/** Pull toward the centre, keeping disconnected nodes from drifting away. */
+const GRAVITY = 0.03;
+
+/**
+ * Largest distance a node may move in one step, as a fraction of `k`.
+ *
+ * Connected nodes settle at roughly `k` apart, so a step anywhere near that
+ * distance overshoots the equilibrium and the pair oscillates instead of
+ * converging. Keeping it well below `k` is what makes the layout settle.
+ */
+const MAX_STEP = 0.1;
+
+/** Minimum separation used in force calculations, avoiding division by zero. */
+const MIN_DISTANCE = 0.01;
+
+/**
+ * Deterministically spreads nodes around a circle as a starting position.
+ *
+ * A random start would relayout differently on every render — and would not be
+ * reproducible in tests — so positions are seeded from each node's index.
+ *
+ * @param ids - Node ids, in a stable order
+ * @param options - Layout area
+ * @returns Nodes positioned on a circle around the centre
+ */
+export function seedPositions(ids: string[], options: LayoutOptions): LayoutNode[] {
+  const { width, height } = options;
+  const radius = Math.min(width, height) * 0.35;
+
+  return ids.map((id, index) => {
+    const angle = (index / Math.max(1, ids.length)) * Math.PI * 2;
+
+    return {
+      id,
+      x: width / 2 + Math.cos(angle) * radius,
+      y: height / 2 + Math.sin(angle) * radius,
+      vx: 0,
+      vy: 0,
+    };
+  });
+}
+
+/**
+ * Advances the simulation by one step.
+ *
+ * Every pair of nodes repels; connected pairs also attract. `alpha` scales the
+ * whole step and is decayed by the caller, which is what lets the layout settle
+ * instead of oscillating forever.
+ *
+ * @param nodes - Nodes to move, mutated in place
+ * @param edges - Edges providing attraction
+ * @param options - Layout area
+ * @param alpha - Step scale, from 1 down toward 0
+ */
+export function step(
+  nodes: LayoutNode[],
+  edges: LayoutEdge[],
+  options: LayoutOptions,
+  alpha: number,
+): void {
+  const { width, height, spacing = 1 } = options;
+  if (nodes.length === 0) return;
+
+  // Natural distance between connected nodes for the available area.
+  const k = spacing * Math.sqrt((width * height) / nodes.length);
+  const byId = new Map(nodes.map((node) => [node.id, node]));
+
+  for (const node of nodes) {
+    node.vx *= DAMPING;
+    node.vy *= DAMPING;
+  }
+
+  // Repulsion: every pair pushes apart, strongest when close.
+  for (let i = 0; i < nodes.length; i++) {
+    for (let j = i + 1; j < nodes.length; j++) {
+      const a = nodes[i];
+      const b = nodes[j];
+
+      let dx = a.x - b.x;
+      let dy = a.y - b.y;
+      let distance = Math.hypot(dx, dy);
+
+      if (distance < MIN_DISTANCE) {
+        // Coincident nodes have no direction to separate along; nudge them
+        // apart deterministically using their index so the layout stays stable.
+        dx = (i - j) * MIN_DISTANCE;
+        dy = MIN_DISTANCE;
+        distance = Math.hypot(dx, dy);
+      }
+
+      const force = (k * k) / distance;
+      const fx = (dx / distance) * force;
+      const fy = (dy / distance) * force;
+
+      a.vx += fx;
+      a.vy += fy;
+      b.vx -= fx;
+      b.vy -= fy;
+    }
+  }
+
+  // Attraction along edges.
+  for (const edge of edges) {
+    const a = byId.get(edge.from);
+    const b = byId.get(edge.to);
+    if (!a || !b || a === b) continue;
+
+    const dx = a.x - b.x;
+    const dy = a.y - b.y;
+    const distance = Math.max(MIN_DISTANCE, Math.hypot(dx, dy));
+
+    const force = (distance * distance) / k;
+    const fx = (dx / distance) * force;
+    const fy = (dy / distance) * force;
+
+    a.vx -= fx;
+    a.vy -= fy;
+    b.vx += fx;
+    b.vy += fy;
+  }
+
+  const maxStep = k * MAX_STEP;
+
+  for (const node of nodes) {
+    if (node.fixed) {
+      node.vx = 0;
+      node.vy = 0;
+      continue;
+    }
+
+    // Displacement-based pull toward the centre.
+    node.vx += (width / 2 - node.x) * GRAVITY;
+    node.vy += (height / 2 - node.y) * GRAVITY;
+
+    const speed = Math.hypot(node.vx, node.vy);
+    const scale = speed > maxStep ? maxStep / speed : 1;
+
+    node.x += node.vx * scale * alpha;
+    node.y += node.vy * scale * alpha;
+  }
+}
+
+/**
+ * Runs the simulation to completion and returns the settled positions.
+ *
+ * @param ids - Node ids
+ * @param edges - Edges between them
+ * @param options - Layout area
+ * @param iterations - Number of steps to run
+ * @returns Settled node positions
+ *
+ * @example
+ * ```typescript
+ * const nodes = layout(['a', 'b'], [{ from: 'a', to: 'b' }], { width: 800, height: 600 });
+ * ```
+ */
+export function layout(
+  ids: string[],
+  edges: LayoutEdge[],
+  options: LayoutOptions,
+  iterations = 300,
+): LayoutNode[] {
+  const nodes = seedPositions(ids, options);
+
+  for (let i = 0; i < iterations; i++) {
+    step(nodes, edges, options, 1 - i / iterations);
+  }
+
+  return nodes;
+}
+
+/**
+ * Computes the bounding box of laid-out nodes.
+ *
+ * Used to fit the result into the viewport regardless of how far the simulation
+ * spread things.
+ *
+ * @param nodes - Positioned nodes
+ * @param padding - Margin added on every side
+ * @returns The bounding box
+ */
+export function bounds(
+  nodes: LayoutNode[],
+  padding = 40,
+): { x: number; y: number; width: number; height: number } {
+  if (nodes.length === 0) return { x: 0, y: 0, width: 1, height: 1 };
+
+  const xs = nodes.map((node) => node.x);
+  const ys = nodes.map((node) => node.y);
+
+  const minX = Math.min(...xs) - padding;
+  const minY = Math.min(...ys) - padding;
+  const maxX = Math.max(...xs) + padding;
+  const maxY = Math.max(...ys) + padding;
+
+  return {
+    x: minX,
+    y: minY,
+    // A single node produces a zero-size box, which would make the SVG
+    // viewBox degenerate.
+    width: Math.max(1, maxX - minX),
+    height: Math.max(1, maxY - minY),
+  };
+}