diffwiki-core 0.6.1 → 0.7.0

package/dist/index.cjs

@@ -577,6 +577,7 @@ __export(index_exports, {
   addTags: () => addTags,
   buildArticleTree: () => buildArticleTree,
   buildCollections: () => buildCollections,
+  buildLinkGraph: () => buildLinkGraph,
   buildNavTree: () => buildNavTree,
   buildSearchIndex: () => buildSearchIndex,
   collectionDir: () => collectionDir,
@@ -601,6 +602,7 @@ __export(index_exports, {
   gitToplevel: () => gitToplevel,
   initRepoWiki: () => initRepoWiki,
   installPlugin: () => installPlugin,
+  invalidateLinkGraph: () => invalidateLinkGraph,
   isLinkedWorktree: () => isLinkedWorktree,
   listArticleTree: () => listArticleTree,
   listAvailablePlugins: () => listAvailablePlugins,
@@ -609,6 +611,7 @@ __export(index_exports, {
   listPlugins: () => listPlugins,
   listSearchModes: () => listSearchModes,
   loadSearchProvider: () => loadSearchProvider,
+  localGraph: () => localGraph,
   nativeSearch: () => nativeSearch,
   parseAddTarget: () => parseAddTarget,
   parseArticle: () => parseArticle,
@@ -943,8 +946,8 @@ function isEpochish(d) {
 }
 var timestampCache = /* @__PURE__ */ new Map();
 async function fileTimestamps(absPath) {
-  const cached = timestampCache.get(absPath);
-  if (cached) return cached;
+  const cached2 = timestampCache.get(absPath);
+  if (cached2) return cached2;
   const dir = import_node_path4.default.dirname(absPath);
   const base = import_node_path4.default.basename(absPath);
   const [addLog, lastLog] = await Promise.all([
@@ -1304,6 +1307,56 @@ function rehypeCollectToc(toc) {
     });
   };
 }
+function isExternalHref(href) {
+  if (!href) return true;
+  if (href.startsWith("#")) return true;
+  if (href.startsWith("//")) return true;
+  return /^[a-z][a-z0-9+.-]*:/i.test(href);
+}
+function resolveHref(href, ctx) {
+  if (isExternalHref(href)) return null;
+  const clean = (p) => p.replace(/[?#].*$/, "").replace(/\.(mdx?|html)$/i, "").replace(/\/+$/, "");
+  const target = clean(href);
+  if (!target) return null;
+  if (target.startsWith("/")) {
+    const base = ctx.base ?? process.env.DIFFWIKI_BASE ?? "";
+    const baseSegs2 = base.split("/").filter(Boolean);
+    let segs = target.split("/").filter(Boolean);
+    if (baseSegs2.length > 0 && baseSegs2.every((b, i) => segs[i] === b)) {
+      segs = segs.slice(baseSegs2.length);
+    }
+    if (segs.length < 2) return null;
+    return segs.join("/");
+  }
+  const dir = ctx.isIndex ? ctx.slug : ctx.slug.includes("/") ? ctx.slug.slice(0, ctx.slug.lastIndexOf("/")) : "";
+  const baseSegs = dir ? dir.split("/") : [];
+  const out = [...baseSegs];
+  for (const seg of target.split("/")) {
+    if (seg === "" || seg === ".") continue;
+    if (seg === "..") {
+      if (out.length === 0) return null;
+      out.pop();
+      continue;
+    }
+    out.push(seg);
+  }
+  if (out.length === 0) return null;
+  return `${ctx.coll}/${out.join("/")}`;
+}
+function rehypeCollectLinks(links, ctx) {
+  const seen = /* @__PURE__ */ new Set();
+  return (tree) => {
+    (0, import_unist_util_visit.visit)(tree, "element", (node) => {
+      if (node.tagName !== "a") return;
+      const href = node.properties?.href;
+      if (typeof href !== "string") return;
+      const id = resolveHref(href, ctx);
+      if (!id || seen.has(id)) return;
+      seen.add(id);
+      links.push(id);
+    });
+  };
+}
 function rehypeStripLeadingH1() {
   return (tree) => {
     let removed = false;
@@ -1331,13 +1384,112 @@ function rehypeMarkMermaid() {
 }
 async function renderArticle(body, ctx) {
   const toc = [];
-  const file = await (0, import_unified.unified)().use(import_remark_parse.default).use(import_remark_gfm.default).use(import_remark_rehype.default).use(import_rehype_slug.default).use(rehypeCollectToc, toc).use(rehypeStripLeadingH1).use(rehypeMarkMermaid).use(rehypeRewriteLinks, ctx).use(import_rehype.default, {
+  const links = [];
+  const pipeline = (0, import_unified.unified)().use(import_remark_parse.default).use(import_remark_gfm.default).use(import_remark_rehype.default).use(import_rehype_slug.default).use(rehypeCollectToc, toc).use(rehypeCollectLinks, links, ctx);
+  const file = await pipeline.use(rehypeStripLeadingH1).use(rehypeMarkMermaid).use(rehypeRewriteLinks, ctx).use(import_rehype.default, {
     themes: { light: "github-light", dark: "github-dark" },
     defaultColor: false,
     langAlias: LANG_ALIASES,
     fallbackLanguage: "plaintext"
   }).use(import_rehype_stringify.default).process(body);
-  return { html: String(file), toc };
+  return { html: String(file), toc, links };
+}
+
+// src/graph.ts
+init_collections();
+init_errors();
+function tagId(tag) {
+  return `tag:${tag}`;
+}
+async function collectArticle(coll, slug, fallbackTitle, outNodes, outEdges, outTags) {
+  let art;
+  try {
+    art = await readArticle(coll, slug);
+  } catch (err) {
+    if (err instanceof ArticleNotFoundError) return;
+    throw err;
+  }
+  const id = `${coll}/${slug}`;
+  outNodes.push({ id, kind: "article", coll, slug, title: art.title ?? fallbackTitle ?? slug });
+  const { links } = await renderArticle(art.body, { coll, slug, isIndex: art.isIndex });
+  for (const target of links) outEdges.push({ source: id, target, kind: "link" });
+  for (const tag of art.tags) outTags.push({ source: id, tag });
+}
+async function collectCollection(coll, nodes, outNodes, outEdges, outTags) {
+  for (const n of nodes) {
+    if (n.slug) await collectArticle(coll, n.slug, n.title ?? n.name, outNodes, outEdges, outTags);
+    if (n.children) await collectCollection(coll, n.children, outNodes, outEdges, outTags);
+  }
+}
+var cached;
+function invalidateLinkGraph() {
+  cached = void 0;
+}
+async function buildLinkGraph() {
+  if (cached) return cached;
+  const nodes = [];
+  const rawEdges = [];
+  const rawTags = [];
+  for (const e of await listCollections()) {
+    try {
+      await collectArticle(e.name, "", e.name, nodes, rawEdges, rawTags);
+      await collectCollection(e.name, await listArticleTree(e.name), nodes, rawEdges, rawTags);
+    } catch {
+    }
+  }
+  const nodeIds = new Set(nodes.map((n) => n.id));
+  const seen = /* @__PURE__ */ new Set();
+  const edges = [];
+  for (const edge of rawEdges) {
+    if (edge.source === edge.target) continue;
+    if (!nodeIds.has(edge.target)) continue;
+    const key = `${edge.source} ${edge.target}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    edges.push(edge);
+  }
+  const tagSeen = /* @__PURE__ */ new Set();
+  for (const { source, tag } of rawTags) {
+    if (!nodeIds.has(source)) continue;
+    const id = tagId(tag);
+    if (!tagSeen.has(id)) {
+      tagSeen.add(id);
+      nodes.push({ id, kind: "tag", coll: "", slug: "", title: `#${tag}` });
+    }
+    const key = `${source} ${id}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    edges.push({ source, target: id, kind: "tag" });
+  }
+  cached = { nodes, edges };
+  return cached;
+}
+function localGraph(graph, focusId, include, siblingCap = 12) {
+  const scoped = include ? {
+    // Tag hubs survive the filter — never a page, so they can't 404.
+    nodes: graph.nodes.filter((n) => n.kind === "tag" || include.has(n.coll)),
+    edges: graph.edges
+  } : graph;
+  const byId = new Map(scoped.nodes.map((n) => [n.id, n]));
+  const focus = byId.get(focusId);
+  if (!focus) return { focus: focusId, nodes: [], edges: [] };
+  const keep = /* @__PURE__ */ new Set([focusId]);
+  for (const e of scoped.edges) {
+    if (e.source === focusId && byId.has(e.target)) keep.add(e.target);
+    if (e.target === focusId && byId.has(e.source)) keep.add(e.source);
+  }
+  const focusTagHubs = new Set([...keep].filter((id) => byId.get(id)?.kind === "tag"));
+  let siblings = 0;
+  for (const e of scoped.edges) {
+    if (siblings >= siblingCap) break;
+    if (e.kind === "tag" && focusTagHubs.has(e.target) && byId.has(e.source) && !keep.has(e.source)) {
+      keep.add(e.source);
+      siblings++;
+    }
+  }
+  const nodes = scoped.nodes.filter((n) => keep.has(n.id));
+  const edges = scoped.edges.filter((e) => keep.has(e.source) && keep.has(e.target));
+  return { focus: focusId, nodes, edges };
 }
 
 // src/site.ts
@@ -1391,7 +1543,7 @@ function findNode(nodes, slug) {
   }
   return void 0;
 }
-async function resolvePage(coll, slug) {
+async function resolvePage(coll, slug, opts) {
   try {
     const art = await readArticle(coll, slug);
     const { html, toc } = await renderArticle(art.body, {
@@ -1400,6 +1552,7 @@ async function resolvePage(coll, slug) {
       isIndex: art.isIndex
     });
     const { created, updated } = await fileTimestamps(art.path);
+    const graph = localGraph(await buildLinkGraph(), `${art.coll}/${art.slug}`, opts?.include);
     return {
       kind: "doc",
       coll: art.coll,
@@ -1410,7 +1563,8 @@ async function resolvePage(coll, slug) {
       toc,
       path: `/${art.coll}/${art.slug}`,
       created,
-      updated
+      updated,
+      graph
     };
   } catch (err) {
     if (err instanceof CollectionNotFoundError) return null;
@@ -2097,6 +2251,7 @@ init_registry2();
   addTags,
   buildArticleTree,
   buildCollections,
+  buildLinkGraph,
   buildNavTree,
   buildSearchIndex,
   collectionDir,
@@ -2121,6 +2276,7 @@ init_registry2();
   gitToplevel,
   initRepoWiki,
   installPlugin,
+  invalidateLinkGraph,
   isLinkedWorktree,
   listArticleTree,
   listAvailablePlugins,
@@ -2129,6 +2285,7 @@ init_registry2();
   listPlugins,
   listSearchModes,
   loadSearchProvider,
+  localGraph,
   nativeSearch,
   parseAddTarget,
   parseArticle,

package/dist/index.d.cts

@@ -192,6 +192,8 @@ interface DocData {
     created?: string;
     /** ISO-8601 last-update date, sourced from git history / filesystem (not frontmatter). */
     updated?: string;
+    /** Local knowledge-graph neighbourhood for this page (this node + its direct links). */
+    graph: LocalGraph;
 }
 interface ListingEntry {
     name: string;
@@ -208,6 +210,44 @@ type PageData = ({
     title: string;
     entries: ListingEntry[];
 };
+/**
+ * One node in the knowledge graph. Two kinds:
+ * - `article` — a wiki page. `id` is `"<coll>/<slug>"`, with `coll`/`slug` set.
+ * - `tag` — an Obsidian-style tag hub. `id` is `"tag:<name>"`; `coll`/`slug` are
+ *   empty (a tag is not a page, so clicking it never navigates), `title` is `#name`.
+ */
+interface GraphNode {
+    id: string;
+    kind: 'article' | 'tag';
+    coll: string;
+    slug: string;
+    title: string;
+}
+/**
+ * A graph edge. `kind` distinguishes an explicit hyperlink between two articles
+ * (`link`) from an article↔tag-hub membership edge (`tag`). For `link` edges the
+ * direction (source→target) is the link direction; `tag` edges go article→tag.
+ */
+interface GraphEdge {
+    source: string;
+    target: string;
+    kind: 'link' | 'tag';
+}
+/** The whole-wiki knowledge graph. */
+interface LinkGraph {
+    nodes: GraphNode[];
+    edges: GraphEdge[];
+}
+/**
+ * The local neighbourhood of one node: the node itself plus its directly linked
+ * (outgoing) and linking (incoming) neighbours, and the edges among them. `focus`
+ * is the id of the page this neighbourhood is centred on.
+ */
+interface LocalGraph {
+    focus: string;
+    nodes: GraphNode[];
+    edges: GraphEdge[];
+}
 
 /** Base class for all expected, user-facing diffwiki failures. */
 declare class DiffwikiError extends Error {
@@ -400,8 +440,18 @@ declare function fileTimestamps(absPath: string): Promise<FileTimestamps>;
 declare function toTreeNodes(coll: string, nodes: ArticleNode[]): TreeNode[];
 declare function buildCollections(): Promise<CollectionInfo[]>;
 declare function buildNavTree(): Promise<CollectionTree[]>;
-/** Resolve a route to a rendered doc or a generated directory listing (or null). */
-declare function resolvePage(coll: string, slug: string): Promise<PageData | null>;
+/**
+ * Resolve a route to a rendered doc or a generated directory listing (or null).
+ *
+ * `opts.include` restricts the doc's sidebar `graph` preview to the given set of
+ * collection names — supplied by the static exporter for subset exports so the
+ * per-page local graph matches the filtered overlay `graph.json` and never links
+ * to a page that was excluded from the build. Omitting it (the dynamic server
+ * path, which serves every collection) keeps the whole-wiki neighbourhood.
+ */
+declare function resolvePage(coll: string, slug: string, opts?: {
+    include?: ReadonlySet<string>;
+}): Promise<PageData | null>;
 
 /**
  * Collection selection for `diffwiki export` — resolve which collection names to
@@ -603,18 +653,26 @@ declare function listArticleTree(coll: string): Promise<ArticleNode[]>;
  */
 declare function readArticle(coll: string, slug: string): Promise<ArticleContent>;
 
-/** Route context for an article being rendered — used to resolve relative links. */
+/**
+ * Route context for an article being rendered — used both to rewrite relative
+ * inter-page links into in-app routes and to resolve links to `coll/slug` graph
+ * node ids.
+ */
 interface RenderContext {
     /** Collection name (first route segment). */
     coll: string;
     /** Article route slug (path within the collection, no extension), e.g. "a/b/deep". */
     slug: string;
     /**
-     * True when the source file is a folder-index page (`<slug>/index.md`). Such a
-     * page shares its route slug with the folder, so relative links must resolve
-     * against the folder itself, not its parent. Defaults to false (leaf page).
+     * True for a directory index page: relative links resolve against the folder
+     * (`slug`) itself, not its parent — so `./sub` from `guide/index.md` → `guide/sub`.
      */
     isIndex?: boolean;
+    /**
+     * Deployment base path (e.g. `/my-repo/`) stripped from absolute route links so
+     * the collection segment resolves cleanly. Defaults to `DIFFWIKI_BASE`.
+     */
+    base?: string;
 }
 /** The result of rendering an article body to HTML. */
 interface RenderedArticle {
@@ -622,17 +680,47 @@ interface RenderedArticle {
     html: string;
     /** h2/h3 headings collected during render, in document order. */
     toc: TocItem[];
+    /**
+     * Internal outgoing links as `coll/slug` node ids, de-duplicated, in document
+     * order. Only populated when a {@link RenderContext} is supplied; external
+     * links, in-page anchors, and unresolvable targets are dropped.
+     */
+    links: string[];
 }
 /**
  * Render an article body (markdown) to Shiki-highlighted HTML plus its table of
- * contents, rewriting relative links to in-app routes via `ctx`.
- * Runs entirely server-side; the client mounts the HTML directly with
- * no `eval`/`new Function`, so it works under a strict CSP. Code is highlighted
- * here (dual github-light/github-dark via CSS variables); mermaid fences are
- * marked for client rendering.
+ * contents. Rewrites relative inter-page links to in-app routes and collects the
+ * article's internal outgoing links (`coll/slug` node ids) for the knowledge graph.
+ * Runs entirely server-side; the client mounts the HTML directly with no
+ * `eval`/`new Function`, so it works under a strict CSP. Code is highlighted here
+ * (dual github-light/github-dark via CSS variables); mermaid fences are marked for
+ * client rendering.
  */
 declare function renderArticle(body: string, ctx: RenderContext): Promise<RenderedArticle>;
 
+/** Clear the memoised whole-wiki graph (tests; future live-reload invalidation). */
+declare function invalidateLinkGraph(): void;
+/**
+ * Build the whole-wiki graph: one node per article, one directed edge per resolved
+ * internal link (self/dead/external dropped, duplicates collapsed), plus tag hubs.
+ * Memoised per process; {@link invalidateLinkGraph} clears it.
+ *
+ * TODO(live-reload): the memo is process-keyed and the dynamic server fn never
+ * invalidates, so a long-lived server freezes the graph until restart.
+ */
+declare function buildLinkGraph(): Promise<LinkGraph>;
+/**
+ * Slice the local neighbourhood of `focusId`: the focus, its direct link neighbours,
+ * its tag hubs, and its co-tagged sibling articles (2 hops through a shared hub, so
+ * the tag-proximity view has neighbours rather than a lone dot). All edges among the
+ * kept nodes are retained; an unknown focus yields an empty-but-focused graph.
+ * `siblingCap` bounds the co-tagged siblings pulled in.
+ *
+ * `include` prunes to the given collection set before slicing (tag hubs kept), so a
+ * subset export's preview never links to an excluded page.
+ */
+declare function localGraph(graph: LinkGraph, focusId: string, include?: ReadonlySet<string>, siblingCap?: number): LocalGraph;
+
 /**
  * Host-side plugin invocation and search-provider loading.
  *
@@ -802,4 +890,4 @@ declare function findEnabledPlugin(kind: PluginKind, name?: string): Promise<Plu
 /** Find a plugin record by name (regardless of enabled state). */
 declare function findPluginRecord(name: string): Promise<PluginRecord | undefined>;
 
-export { type AddExternalOptions, type Article, type ArticleContent, type ArticleNode, ArticleNotFoundError, CollectionAlreadyAddedError, type CollectionEntry, CollectionExistsError, type CollectionGitStatus, type CollectionInfo, CollectionNotFoundError, type CollectionSelection, type CollectionSelectionResult, type CollectionTree, type CollectionType, type Config, type Diagnostic, type DiagnosticLevel, DiffwikiError, type DiffwikiLogLevel, type DocData, type FileTimestamps, type InitOptions, type InstallOutcome, InvalidExportSelectionError, InvalidTargetError, type KnownPlugin, type ListingEntry, NATIVE_ENGINE, NoDefaultCollectionError, type NodeMeta, type PageData, type ParsedArticle, type PluginCapabilities, PluginError, type PluginEvent, type PluginHealth, type PluginKind, type PluginReadiness, type PluginRecord, type PluginRegistryFile, type QueryHit, type QueryOptions, REPO_CONFIG_FILE, type Registry, type RenderContext, type RenderedArticle, type RepoConfig, SearchDoc, type SearchMode, type SearchOutcome, type SearchProvider, type SerializableArticle, type SetupOutcome, type SetupStep, type TocItem, type TreeNode, type UpstreamStatus, WorktreeNotAllowedError, addExternalCollection, addTags, buildArticleTree, buildCollections, buildNavTree, buildSearchIndex, collectionDir, collectionGitStatus, collectionsDir, configPath, createArticle, createCollection, currentBranch, deregisterPlugin, doctor, emitPluginEvent, ensureGitRepo, ensurePluginRoot, fileTimestamps, findCollection, findCollectionById, findEnabledPlugin, findPluginRecord, getConfigValue, getLogger, gitToplevel, initRepoWiki, installPlugin, isLinkedWorktree, listArticleTree, listAvailablePlugins, listCollections, listEnabledPlugins, listPlugins, listSearchModes, loadSearchProvider, nativeSearch, parseAddTarget, parseArticle, parsePathTarget, pluginsDir, pluginsRegistryPath, query, readArticle, readConfig, readPluginRegistry, readRegistry, readRepoConfig, registerCollection, registerPlugin, registryPath, removeArticle, removeCollection, removePlugin, removeTags, renderArticle, repoId, repoRemoteName, resolveCollectionSelection, resolveCwdCollection, resolveDefaultSearchMode, resolveHome, resolveLogLevel, resolvePage, search, serializeArticle, setConfigValue, setTags, slugify, toTreeNodes, unregisterCollection, updateArticleBody, upsertPlugin, upstreamStatus, writeConfig, writePluginRegistry, writeRegistry };
+export { type AddExternalOptions, type Article, type ArticleContent, type ArticleNode, ArticleNotFoundError, CollectionAlreadyAddedError, type CollectionEntry, CollectionExistsError, type CollectionGitStatus, type CollectionInfo, CollectionNotFoundError, type CollectionSelection, type CollectionSelectionResult, type CollectionTree, type CollectionType, type Config, type Diagnostic, type DiagnosticLevel, DiffwikiError, type DiffwikiLogLevel, type DocData, type FileTimestamps, type GraphEdge, type GraphNode, type InitOptions, type InstallOutcome, InvalidExportSelectionError, InvalidTargetError, type KnownPlugin, type LinkGraph, type ListingEntry, type LocalGraph, NATIVE_ENGINE, NoDefaultCollectionError, type NodeMeta, type PageData, type ParsedArticle, type PluginCapabilities, PluginError, type PluginEvent, type PluginHealth, type PluginKind, type PluginReadiness, type PluginRecord, type PluginRegistryFile, type QueryHit, type QueryOptions, REPO_CONFIG_FILE, type Registry, type RenderContext, type RenderedArticle, type RepoConfig, SearchDoc, type SearchMode, type SearchOutcome, type SearchProvider, type SerializableArticle, type SetupOutcome, type SetupStep, type TocItem, type TreeNode, type UpstreamStatus, WorktreeNotAllowedError, addExternalCollection, addTags, buildArticleTree, buildCollections, buildLinkGraph, buildNavTree, buildSearchIndex, collectionDir, collectionGitStatus, collectionsDir, configPath, createArticle, createCollection, currentBranch, deregisterPlugin, doctor, emitPluginEvent, ensureGitRepo, ensurePluginRoot, fileTimestamps, findCollection, findCollectionById, findEnabledPlugin, findPluginRecord, getConfigValue, getLogger, gitToplevel, initRepoWiki, installPlugin, invalidateLinkGraph, isLinkedWorktree, listArticleTree, listAvailablePlugins, listCollections, listEnabledPlugins, listPlugins, listSearchModes, loadSearchProvider, localGraph, nativeSearch, parseAddTarget, parseArticle, parsePathTarget, pluginsDir, pluginsRegistryPath, query, readArticle, readConfig, readPluginRegistry, readRegistry, readRepoConfig, registerCollection, registerPlugin, registryPath, removeArticle, removeCollection, removePlugin, removeTags, renderArticle, repoId, repoRemoteName, resolveCollectionSelection, resolveCwdCollection, resolveDefaultSearchMode, resolveHome, resolveLogLevel, resolvePage, search, serializeArticle, setConfigValue, setTags, slugify, toTreeNodes, unregisterCollection, updateArticleBody, upsertPlugin, upstreamStatus, writeConfig, writePluginRegistry, writeRegistry };

package/dist/index.d.ts

@@ -192,6 +192,8 @@ interface DocData {
     created?: string;
     /** ISO-8601 last-update date, sourced from git history / filesystem (not frontmatter). */
     updated?: string;
+    /** Local knowledge-graph neighbourhood for this page (this node + its direct links). */
+    graph: LocalGraph;
 }
 interface ListingEntry {
     name: string;
@@ -208,6 +210,44 @@ type PageData = ({
     title: string;
     entries: ListingEntry[];
 };
+/**
+ * One node in the knowledge graph. Two kinds:
+ * - `article` — a wiki page. `id` is `"<coll>/<slug>"`, with `coll`/`slug` set.
+ * - `tag` — an Obsidian-style tag hub. `id` is `"tag:<name>"`; `coll`/`slug` are
+ *   empty (a tag is not a page, so clicking it never navigates), `title` is `#name`.
+ */
+interface GraphNode {
+    id: string;
+    kind: 'article' | 'tag';
+    coll: string;
+    slug: string;
+    title: string;
+}
+/**
+ * A graph edge. `kind` distinguishes an explicit hyperlink between two articles
+ * (`link`) from an article↔tag-hub membership edge (`tag`). For `link` edges the
+ * direction (source→target) is the link direction; `tag` edges go article→tag.
+ */
+interface GraphEdge {
+    source: string;
+    target: string;
+    kind: 'link' | 'tag';
+}
+/** The whole-wiki knowledge graph. */
+interface LinkGraph {
+    nodes: GraphNode[];
+    edges: GraphEdge[];
+}
+/**
+ * The local neighbourhood of one node: the node itself plus its directly linked
+ * (outgoing) and linking (incoming) neighbours, and the edges among them. `focus`
+ * is the id of the page this neighbourhood is centred on.
+ */
+interface LocalGraph {
+    focus: string;
+    nodes: GraphNode[];
+    edges: GraphEdge[];
+}
 
 /** Base class for all expected, user-facing diffwiki failures. */
 declare class DiffwikiError extends Error {
@@ -400,8 +440,18 @@ declare function fileTimestamps(absPath: string): Promise<FileTimestamps>;
 declare function toTreeNodes(coll: string, nodes: ArticleNode[]): TreeNode[];
 declare function buildCollections(): Promise<CollectionInfo[]>;
 declare function buildNavTree(): Promise<CollectionTree[]>;
-/** Resolve a route to a rendered doc or a generated directory listing (or null). */
-declare function resolvePage(coll: string, slug: string): Promise<PageData | null>;
+/**
+ * Resolve a route to a rendered doc or a generated directory listing (or null).
+ *
+ * `opts.include` restricts the doc's sidebar `graph` preview to the given set of
+ * collection names — supplied by the static exporter for subset exports so the
+ * per-page local graph matches the filtered overlay `graph.json` and never links
+ * to a page that was excluded from the build. Omitting it (the dynamic server
+ * path, which serves every collection) keeps the whole-wiki neighbourhood.
+ */
+declare function resolvePage(coll: string, slug: string, opts?: {
+    include?: ReadonlySet<string>;
+}): Promise<PageData | null>;
 
 /**
  * Collection selection for `diffwiki export` — resolve which collection names to
@@ -603,18 +653,26 @@ declare function listArticleTree(coll: string): Promise<ArticleNode[]>;
  */
 declare function readArticle(coll: string, slug: string): Promise<ArticleContent>;
 
-/** Route context for an article being rendered — used to resolve relative links. */
+/**
+ * Route context for an article being rendered — used both to rewrite relative
+ * inter-page links into in-app routes and to resolve links to `coll/slug` graph
+ * node ids.
+ */
 interface RenderContext {
     /** Collection name (first route segment). */
     coll: string;
     /** Article route slug (path within the collection, no extension), e.g. "a/b/deep". */
     slug: string;
     /**
-     * True when the source file is a folder-index page (`<slug>/index.md`). Such a
-     * page shares its route slug with the folder, so relative links must resolve
-     * against the folder itself, not its parent. Defaults to false (leaf page).
+     * True for a directory index page: relative links resolve against the folder
+     * (`slug`) itself, not its parent — so `./sub` from `guide/index.md` → `guide/sub`.
      */
     isIndex?: boolean;
+    /**
+     * Deployment base path (e.g. `/my-repo/`) stripped from absolute route links so
+     * the collection segment resolves cleanly. Defaults to `DIFFWIKI_BASE`.
+     */
+    base?: string;
 }
 /** The result of rendering an article body to HTML. */
 interface RenderedArticle {
@@ -622,17 +680,47 @@ interface RenderedArticle {
     html: string;
     /** h2/h3 headings collected during render, in document order. */
     toc: TocItem[];
+    /**
+     * Internal outgoing links as `coll/slug` node ids, de-duplicated, in document
+     * order. Only populated when a {@link RenderContext} is supplied; external
+     * links, in-page anchors, and unresolvable targets are dropped.
+     */
+    links: string[];
 }
 /**
  * Render an article body (markdown) to Shiki-highlighted HTML plus its table of
- * contents, rewriting relative links to in-app routes via `ctx`.
- * Runs entirely server-side; the client mounts the HTML directly with
- * no `eval`/`new Function`, so it works under a strict CSP. Code is highlighted
- * here (dual github-light/github-dark via CSS variables); mermaid fences are
- * marked for client rendering.
+ * contents. Rewrites relative inter-page links to in-app routes and collects the
+ * article's internal outgoing links (`coll/slug` node ids) for the knowledge graph.
+ * Runs entirely server-side; the client mounts the HTML directly with no
+ * `eval`/`new Function`, so it works under a strict CSP. Code is highlighted here
+ * (dual github-light/github-dark via CSS variables); mermaid fences are marked for
+ * client rendering.
  */
 declare function renderArticle(body: string, ctx: RenderContext): Promise<RenderedArticle>;
 
+/** Clear the memoised whole-wiki graph (tests; future live-reload invalidation). */
+declare function invalidateLinkGraph(): void;
+/**
+ * Build the whole-wiki graph: one node per article, one directed edge per resolved
+ * internal link (self/dead/external dropped, duplicates collapsed), plus tag hubs.
+ * Memoised per process; {@link invalidateLinkGraph} clears it.
+ *
+ * TODO(live-reload): the memo is process-keyed and the dynamic server fn never
+ * invalidates, so a long-lived server freezes the graph until restart.
+ */
+declare function buildLinkGraph(): Promise<LinkGraph>;
+/**
+ * Slice the local neighbourhood of `focusId`: the focus, its direct link neighbours,
+ * its tag hubs, and its co-tagged sibling articles (2 hops through a shared hub, so
+ * the tag-proximity view has neighbours rather than a lone dot). All edges among the
+ * kept nodes are retained; an unknown focus yields an empty-but-focused graph.
+ * `siblingCap` bounds the co-tagged siblings pulled in.
+ *
+ * `include` prunes to the given collection set before slicing (tag hubs kept), so a
+ * subset export's preview never links to an excluded page.
+ */
+declare function localGraph(graph: LinkGraph, focusId: string, include?: ReadonlySet<string>, siblingCap?: number): LocalGraph;
+
 /**
  * Host-side plugin invocation and search-provider loading.
  *
@@ -802,4 +890,4 @@ declare function findEnabledPlugin(kind: PluginKind, name?: string): Promise<Plu
 /** Find a plugin record by name (regardless of enabled state). */
 declare function findPluginRecord(name: string): Promise<PluginRecord | undefined>;
 
-export { type AddExternalOptions, type Article, type ArticleContent, type ArticleNode, ArticleNotFoundError, CollectionAlreadyAddedError, type CollectionEntry, CollectionExistsError, type CollectionGitStatus, type CollectionInfo, CollectionNotFoundError, type CollectionSelection, type CollectionSelectionResult, type CollectionTree, type CollectionType, type Config, type Diagnostic, type DiagnosticLevel, DiffwikiError, type DiffwikiLogLevel, type DocData, type FileTimestamps, type InitOptions, type InstallOutcome, InvalidExportSelectionError, InvalidTargetError, type KnownPlugin, type ListingEntry, NATIVE_ENGINE, NoDefaultCollectionError, type NodeMeta, type PageData, type ParsedArticle, type PluginCapabilities, PluginError, type PluginEvent, type PluginHealth, type PluginKind, type PluginReadiness, type PluginRecord, type PluginRegistryFile, type QueryHit, type QueryOptions, REPO_CONFIG_FILE, type Registry, type RenderContext, type RenderedArticle, type RepoConfig, SearchDoc, type SearchMode, type SearchOutcome, type SearchProvider, type SerializableArticle, type SetupOutcome, type SetupStep, type TocItem, type TreeNode, type UpstreamStatus, WorktreeNotAllowedError, addExternalCollection, addTags, buildArticleTree, buildCollections, buildNavTree, buildSearchIndex, collectionDir, collectionGitStatus, collectionsDir, configPath, createArticle, createCollection, currentBranch, deregisterPlugin, doctor, emitPluginEvent, ensureGitRepo, ensurePluginRoot, fileTimestamps, findCollection, findCollectionById, findEnabledPlugin, findPluginRecord, getConfigValue, getLogger, gitToplevel, initRepoWiki, installPlugin, isLinkedWorktree, listArticleTree, listAvailablePlugins, listCollections, listEnabledPlugins, listPlugins, listSearchModes, loadSearchProvider, nativeSearch, parseAddTarget, parseArticle, parsePathTarget, pluginsDir, pluginsRegistryPath, query, readArticle, readConfig, readPluginRegistry, readRegistry, readRepoConfig, registerCollection, registerPlugin, registryPath, removeArticle, removeCollection, removePlugin, removeTags, renderArticle, repoId, repoRemoteName, resolveCollectionSelection, resolveCwdCollection, resolveDefaultSearchMode, resolveHome, resolveLogLevel, resolvePage, search, serializeArticle, setConfigValue, setTags, slugify, toTreeNodes, unregisterCollection, updateArticleBody, upsertPlugin, upstreamStatus, writeConfig, writePluginRegistry, writeRegistry };
+export { type AddExternalOptions, type Article, type ArticleContent, type ArticleNode, ArticleNotFoundError, CollectionAlreadyAddedError, type CollectionEntry, CollectionExistsError, type CollectionGitStatus, type CollectionInfo, CollectionNotFoundError, type CollectionSelection, type CollectionSelectionResult, type CollectionTree, type CollectionType, type Config, type Diagnostic, type DiagnosticLevel, DiffwikiError, type DiffwikiLogLevel, type DocData, type FileTimestamps, type GraphEdge, type GraphNode, type InitOptions, type InstallOutcome, InvalidExportSelectionError, InvalidTargetError, type KnownPlugin, type LinkGraph, type ListingEntry, type LocalGraph, NATIVE_ENGINE, NoDefaultCollectionError, type NodeMeta, type PageData, type ParsedArticle, type PluginCapabilities, PluginError, type PluginEvent, type PluginHealth, type PluginKind, type PluginReadiness, type PluginRecord, type PluginRegistryFile, type QueryHit, type QueryOptions, REPO_CONFIG_FILE, type Registry, type RenderContext, type RenderedArticle, type RepoConfig, SearchDoc, type SearchMode, type SearchOutcome, type SearchProvider, type SerializableArticle, type SetupOutcome, type SetupStep, type TocItem, type TreeNode, type UpstreamStatus, WorktreeNotAllowedError, addExternalCollection, addTags, buildArticleTree, buildCollections, buildLinkGraph, buildNavTree, buildSearchIndex, collectionDir, collectionGitStatus, collectionsDir, configPath, createArticle, createCollection, currentBranch, deregisterPlugin, doctor, emitPluginEvent, ensureGitRepo, ensurePluginRoot, fileTimestamps, findCollection, findCollectionById, findEnabledPlugin, findPluginRecord, getConfigValue, getLogger, gitToplevel, initRepoWiki, installPlugin, invalidateLinkGraph, isLinkedWorktree, listArticleTree, listAvailablePlugins, listCollections, listEnabledPlugins, listPlugins, listSearchModes, loadSearchProvider, localGraph, nativeSearch, parseAddTarget, parseArticle, parsePathTarget, pluginsDir, pluginsRegistryPath, query, readArticle, readConfig, readPluginRegistry, readRegistry, readRepoConfig, registerCollection, registerPlugin, registryPath, removeArticle, removeCollection, removePlugin, removeTags, renderArticle, repoId, repoRemoteName, resolveCollectionSelection, resolveCwdCollection, resolveDefaultSearchMode, resolveHome, resolveLogLevel, resolvePage, search, serializeArticle, setConfigValue, setTags, slugify, toTreeNodes, unregisterCollection, updateArticleBody, upsertPlugin, upstreamStatus, writeConfig, writePluginRegistry, writeRegistry };

package/dist/index.js

@@ -318,8 +318,8 @@ function isEpochish(d) {
 }
 var timestampCache = /* @__PURE__ */ new Map();
 async function fileTimestamps(absPath) {
-  const cached = timestampCache.get(absPath);
-  if (cached) return cached;
+  const cached2 = timestampCache.get(absPath);
+  if (cached2) return cached2;
   const dir = path2.dirname(absPath);
   const base = path2.basename(absPath);
   const [addLog, lastLog] = await Promise.all([
@@ -673,6 +673,56 @@ function rehypeCollectToc(toc) {
     });
   };
 }
+function isExternalHref(href) {
+  if (!href) return true;
+  if (href.startsWith("#")) return true;
+  if (href.startsWith("//")) return true;
+  return /^[a-z][a-z0-9+.-]*:/i.test(href);
+}
+function resolveHref(href, ctx) {
+  if (isExternalHref(href)) return null;
+  const clean = (p) => p.replace(/[?#].*$/, "").replace(/\.(mdx?|html)$/i, "").replace(/\/+$/, "");
+  const target = clean(href);
+  if (!target) return null;
+  if (target.startsWith("/")) {
+    const base = ctx.base ?? process.env.DIFFWIKI_BASE ?? "";
+    const baseSegs2 = base.split("/").filter(Boolean);
+    let segs = target.split("/").filter(Boolean);
+    if (baseSegs2.length > 0 && baseSegs2.every((b, i) => segs[i] === b)) {
+      segs = segs.slice(baseSegs2.length);
+    }
+    if (segs.length < 2) return null;
+    return segs.join("/");
+  }
+  const dir = ctx.isIndex ? ctx.slug : ctx.slug.includes("/") ? ctx.slug.slice(0, ctx.slug.lastIndexOf("/")) : "";
+  const baseSegs = dir ? dir.split("/") : [];
+  const out = [...baseSegs];
+  for (const seg of target.split("/")) {
+    if (seg === "" || seg === ".") continue;
+    if (seg === "..") {
+      if (out.length === 0) return null;
+      out.pop();
+      continue;
+    }
+    out.push(seg);
+  }
+  if (out.length === 0) return null;
+  return `${ctx.coll}/${out.join("/")}`;
+}
+function rehypeCollectLinks(links, ctx) {
+  const seen = /* @__PURE__ */ new Set();
+  return (tree) => {
+    visit(tree, "element", (node) => {
+      if (node.tagName !== "a") return;
+      const href = node.properties?.href;
+      if (typeof href !== "string") return;
+      const id = resolveHref(href, ctx);
+      if (!id || seen.has(id)) return;
+      seen.add(id);
+      links.push(id);
+    });
+  };
+}
 function rehypeStripLeadingH1() {
   return (tree) => {
     let removed = false;
@@ -700,13 +750,110 @@ function rehypeMarkMermaid() {
 }
 async function renderArticle(body, ctx) {
   const toc = [];
-  const file = await unified().use(remarkParse).use(remarkGfm).use(remarkRehype).use(rehypeSlug).use(rehypeCollectToc, toc).use(rehypeStripLeadingH1).use(rehypeMarkMermaid).use(rehypeRewriteLinks, ctx).use(rehypeShiki, {
+  const links = [];
+  const pipeline = unified().use(remarkParse).use(remarkGfm).use(remarkRehype).use(rehypeSlug).use(rehypeCollectToc, toc).use(rehypeCollectLinks, links, ctx);
+  const file = await pipeline.use(rehypeStripLeadingH1).use(rehypeMarkMermaid).use(rehypeRewriteLinks, ctx).use(rehypeShiki, {
     themes: { light: "github-light", dark: "github-dark" },
     defaultColor: false,
     langAlias: LANG_ALIASES,
     fallbackLanguage: "plaintext"
   }).use(rehypeStringify).process(body);
-  return { html: String(file), toc };
+  return { html: String(file), toc, links };
+}
+
+// src/graph.ts
+function tagId(tag) {
+  return `tag:${tag}`;
+}
+async function collectArticle(coll, slug, fallbackTitle, outNodes, outEdges, outTags) {
+  let art;
+  try {
+    art = await readArticle(coll, slug);
+  } catch (err) {
+    if (err instanceof ArticleNotFoundError) return;
+    throw err;
+  }
+  const id = `${coll}/${slug}`;
+  outNodes.push({ id, kind: "article", coll, slug, title: art.title ?? fallbackTitle ?? slug });
+  const { links } = await renderArticle(art.body, { coll, slug, isIndex: art.isIndex });
+  for (const target of links) outEdges.push({ source: id, target, kind: "link" });
+  for (const tag of art.tags) outTags.push({ source: id, tag });
+}
+async function collectCollection(coll, nodes, outNodes, outEdges, outTags) {
+  for (const n of nodes) {
+    if (n.slug) await collectArticle(coll, n.slug, n.title ?? n.name, outNodes, outEdges, outTags);
+    if (n.children) await collectCollection(coll, n.children, outNodes, outEdges, outTags);
+  }
+}
+var cached;
+function invalidateLinkGraph() {
+  cached = void 0;
+}
+async function buildLinkGraph() {
+  if (cached) return cached;
+  const nodes = [];
+  const rawEdges = [];
+  const rawTags = [];
+  for (const e of await listCollections()) {
+    try {
+      await collectArticle(e.name, "", e.name, nodes, rawEdges, rawTags);
+      await collectCollection(e.name, await listArticleTree(e.name), nodes, rawEdges, rawTags);
+    } catch {
+    }
+  }
+  const nodeIds = new Set(nodes.map((n) => n.id));
+  const seen = /* @__PURE__ */ new Set();
+  const edges = [];
+  for (const edge of rawEdges) {
+    if (edge.source === edge.target) continue;
+    if (!nodeIds.has(edge.target)) continue;
+    const key = `${edge.source} ${edge.target}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    edges.push(edge);
+  }
+  const tagSeen = /* @__PURE__ */ new Set();
+  for (const { source, tag } of rawTags) {
+    if (!nodeIds.has(source)) continue;
+    const id = tagId(tag);
+    if (!tagSeen.has(id)) {
+      tagSeen.add(id);
+      nodes.push({ id, kind: "tag", coll: "", slug: "", title: `#${tag}` });
+    }
+    const key = `${source} ${id}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    edges.push({ source, target: id, kind: "tag" });
+  }
+  cached = { nodes, edges };
+  return cached;
+}
+function localGraph(graph, focusId, include, siblingCap = 12) {
+  const scoped = include ? {
+    // Tag hubs survive the filter — never a page, so they can't 404.
+    nodes: graph.nodes.filter((n) => n.kind === "tag" || include.has(n.coll)),
+    edges: graph.edges
+  } : graph;
+  const byId = new Map(scoped.nodes.map((n) => [n.id, n]));
+  const focus = byId.get(focusId);
+  if (!focus) return { focus: focusId, nodes: [], edges: [] };
+  const keep = /* @__PURE__ */ new Set([focusId]);
+  for (const e of scoped.edges) {
+    if (e.source === focusId && byId.has(e.target)) keep.add(e.target);
+    if (e.target === focusId && byId.has(e.source)) keep.add(e.source);
+  }
+  const focusTagHubs = new Set([...keep].filter((id) => byId.get(id)?.kind === "tag"));
+  let siblings = 0;
+  for (const e of scoped.edges) {
+    if (siblings >= siblingCap) break;
+    if (e.kind === "tag" && focusTagHubs.has(e.target) && byId.has(e.source) && !keep.has(e.source)) {
+      keep.add(e.source);
+      siblings++;
+    }
+  }
+  const nodes = scoped.nodes.filter((n) => keep.has(n.id));
+  const edges = scoped.edges.filter((e) => keep.has(e.source) && keep.has(e.target));
+  return { focus: focusId, nodes, edges };
 }
 
 // src/site.ts
@@ -759,7 +906,7 @@ function findNode(nodes, slug) {
   }
   return void 0;
 }
-async function resolvePage(coll, slug) {
+async function resolvePage(coll, slug, opts) {
   try {
     const art = await readArticle(coll, slug);
     const { html, toc } = await renderArticle(art.body, {
@@ -768,6 +915,7 @@ async function resolvePage(coll, slug) {
       isIndex: art.isIndex
     });
     const { created, updated } = await fileTimestamps(art.path);
+    const graph = localGraph(await buildLinkGraph(), `${art.coll}/${art.slug}`, opts?.include);
     return {
       kind: "doc",
       coll: art.coll,
@@ -778,7 +926,8 @@ async function resolvePage(coll, slug) {
       toc,
       path: `/${art.coll}/${art.slug}`,
       created,
-      updated
+      updated,
+      graph
     };
   } catch (err) {
     if (err instanceof CollectionNotFoundError) return null;
@@ -1360,6 +1509,7 @@ export {
   addTags,
   buildArticleTree,
   buildCollections,
+  buildLinkGraph,
   buildNavTree,
   buildSearchIndex,
   collectionDir,
@@ -1384,6 +1534,7 @@ export {
   gitToplevel,
   initRepoWiki,
   installPlugin,
+  invalidateLinkGraph,
   isLinkedWorktree,
   listArticleTree,
   listAvailablePlugins,
@@ -1392,6 +1543,7 @@ export {
   listPlugins,
   listSearchModes,
   loadSearchProvider,
+  localGraph,
   nativeSearch,
   parseAddTarget,
   parseArticle,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "diffwiki-core",
-  "version": "0.6.1",
+  "version": "0.7.0",
   "description": "Core configuration, registry, and article management for diffwiki",
   "license": "MIT",
   "type": "module",