llm-wiki-compiler 0.7.0 → 0.8.0

package/dist/viewer/assets/viewer.js

@@ -22,43 +22,101 @@
 import { wireSearch } from "./viewer-search.js";
 import { renderSidebar, markActive } from "./viewer-sidebar.js";
 import { renderProjectRail, renderSupportRail, clearSupportRail } from "./viewer-rail.js";
+import { loadGraph } from "./viewer-graph.js";
 
 const PAGE_INDEX_SELECTOR = "#page-index";
 const MAIN_SELECTOR = "[data-main-pane]";
 const TITLE_SELECTOR = "[data-app-title]";
+const DEFAULT_TITLE = "llmwiki";
+const EMPTY_INDEX = { pages: [] };
+
+/** Hashes that all map to the home route — `#`, `#/`, and empty/missing. */
+const HOME_HASHES = new Set(["", "#", "#/"]);
+
+/** Static routes whose hash uniquely names the kind (no slug segment). */
+const STATIC_ROUTES = new Map([
+  ["#/index", { kind: "index" }],
+  ["#/health", { kind: "health" }],
+  ["#/graph", { kind: "graph" }],
+]);
+
+/** Pattern matching `#/(concepts|queries)/<slug>` hash routes. */
+const PAGE_HASH_PATTERN = /^#\/(concepts|queries)\/(.+)$/;
+
+/** Rows for the home dashboard counts grid: `[label, envelope.counts key]`. */
+const COUNT_ROWS = [
+  ["Concepts", "concepts"],
+  ["Saved queries", "queries"],
+  ["Source files", "sourceFiles"],
+  ["Pending reviews", "pendingReviews"],
+];
+
+/** Rows for the /api/health metrics block: `[label, health key]`. */
+const HEALTH_METRIC_ROWS = [
+  ["Concepts", "concepts"],
+  ["Saved queries", "queries"],
+  ["Compiled sources", "sources"],
+  ["Source files", "sourceFiles"],
+  ["Pending reviews", "pendingReviews"],
+];
+
+/** Rows for the lint block: `[label, key, fallback]`. */
+const LINT_METRIC_ROWS = [
+  ["Warnings", "warnings", 0],
+  ["Errors", "errors", 0],
+  ["Last run", "at", ""],
+];
 
 /** Parse the server-embedded page-index JSON. Empty list if absent or malformed. */
 function readEmbeddedIndex() {
   const node = document.querySelector(PAGE_INDEX_SELECTOR);
-  if (!node || !node.textContent) return { pages: [] };
+  const text = node?.textContent;
+  if (!text) return EMPTY_INDEX;
+  return parsePageIndex(text);
+}
+
+/** Best-effort JSON.parse of the embedded blob. Always returns a `{pages}` shape. */
+function parsePageIndex(text) {
   try {
-    const data = JSON.parse(node.textContent);
-    return Array.isArray(data?.pages) ? { pages: data.pages } : { pages: [] };
+    const data = JSON.parse(text);
+    if (Array.isArray(data?.pages)) return { pages: data.pages };
   } catch {
-    return { pages: [] };
+    // Malformed JSON in the embedded blob is not a user-facing error.
   }
+  return EMPTY_INDEX;
 }
 
-
 /**
- * Parse `location.hash` into a route descriptor. Malformed percent-
- * encoding in the slug segment falls back to the home route so a typo
- * or hand-edited URL cannot throw from `decodeURIComponent` and crash
- * the client (`#/concepts/%E0%A4%A` is the canonical bad-input case).
+ * Parse `location.hash` into a route descriptor. Static routes resolve
+ * via `STATIC_ROUTES`; page routes fall through to {@link parsePageRoute}.
+ * Malformed percent-encoding in the slug segment falls back to the home
+ * route so a hand-edited URL cannot throw from `decodeURIComponent`
+ * (`#/concepts/%E0%A4%A` is the canonical bad-input case).
  */
 function parseRoute(hash) {
-  if (!hash || hash === "#" || hash === "#/" || hash === "") return { kind: "home" };
-  if (hash === "#/index") return { kind: "index" };
-  if (hash === "#/health") return { kind: "health" };
-  const match = hash.match(/^#\/(concepts|queries)\/(.+)$/);
+  const key = hash ?? "";
+  if (HOME_HASHES.has(key)) return { kind: "home" };
+  const staticRoute = STATIC_ROUTES.get(key);
+  if (staticRoute) return staticRoute;
+  return parsePageRoute(key);
+}
+
+/** Resolve a `#/(concepts|queries)/<slug>` hash; non-matches return home. */
+function parsePageRoute(hash) {
+  const match = hash.match(PAGE_HASH_PATTERN);
   if (!match) return { kind: "home" };
-  let slug;
+  const slug = decodeSlug(match[2]);
+  if (slug === null) return { kind: "home" };
+  return { kind: "page", directory: match[1], slug };
+}
+
+/** Safely percent-decode a slug; returns null on malformed input. */
+function decodeSlug(raw) {
   try {
-    slug = decodeURIComponent(match[2]);
+    return decodeURIComponent(raw);
   } catch {
-    return { kind: "home" };
+    return null;
   }
-  return { kind: "page", directory: match[1], slug };
 }
 
 /** Render the home dashboard from the `/api/pages` envelope. */
@@ -67,25 +125,46 @@ function renderHome(envelope) {
   if (!main) return;
   main.innerHTML = "";
   main.className = "main-pane home-dashboard";
-  const title = document.createElement("h1");
-  title.textContent = envelope.project?.title || "llmwiki";
-  main.appendChild(title);
-  main.appendChild(buildCountsBlock(envelope.counts || {}));
-  if (envelope.index?.available) main.appendChild(buildIndexLink(envelope.index.href));
-  if (Array.isArray(envelope.recentPages) && envelope.recentPages.length > 0) {
+  appendHomeContent(main, envelope);
+  renderProjectRail(envelope);
+}
+
+/** Append every section of the home dashboard to the main pane. */
+function appendHomeContent(main, envelope) {
+  main.appendChild(buildHeading("h1", projectTitle(envelope)));
+  main.appendChild(buildCountsBlock(envelope?.counts));
+  appendIndexLinkIfAvailable(main, envelope);
+  appendRecentBlockIfAny(main, envelope);
+}
+
+/** Append the compiled-index link, if the envelope flagged it available. */
+function appendIndexLinkIfAvailable(main, envelope) {
+  if (envelope?.index?.available) {
+    main.appendChild(buildIndexLink(envelope.index.href));
+  }
+}
+
+/** Append the recent-updates block, if the envelope carried any rows. */
+function appendRecentBlockIfAny(main, envelope) {
+  if (hasRecentPages(envelope)) {
     main.appendChild(buildRecentBlock(envelope.recentPages));
   }
-  renderProjectRail(envelope);
+}
+
+/** Display title for the envelope, with a stable fallback. */
+function projectTitle(envelope) {
+  return envelope?.project?.title || DEFAULT_TITLE;
+}
+
+/** True when the envelope carries at least one recent page. */
+function hasRecentPages(envelope) {
+  return Array.isArray(envelope?.recentPages) && envelope.recentPages.length > 0;
 }
 
 /** Render a `<dl>` of project counts on the home dashboard. */
 function buildCountsBlock(counts) {
-  const dl = buildDefinitionList([
-    ["Concepts", counts.concepts ?? 0],
-    ["Saved queries", counts.queries ?? 0],
-    ["Source files", counts.sourceFiles ?? 0],
-    ["Pending reviews", counts.pendingReviews ?? 0],
-  ]);
+  const rows = COUNT_ROWS.map(([label, key]) => [label, counts?.[key] ?? 0]);
+  const dl = buildDefinitionList(rows);
   dl.className = "metric-grid";
   return dl;
 }
@@ -120,8 +199,6 @@ function buildIndexLink(href) {
 
 /** Render the recent-pages list on the home dashboard. */
 function buildRecentBlock(recent) {
-  const h2 = document.createElement("h2");
-  h2.textContent = "Recently updated";
   const ul = document.createElement("ul");
   ul.className = "recent-list";
   for (const page of recent) {
@@ -134,11 +211,34 @@ function buildRecentBlock(recent) {
   }
   const wrap = document.createElement("section");
   wrap.className = "recent-section";
-  wrap.appendChild(h2);
+  wrap.appendChild(buildHeading("h2", "Recently updated"));
   wrap.appendChild(ul);
   return wrap;
 }
 
+/** Build a heading element with the given tag and text content. */
+function buildHeading(tag, text) {
+  const el = document.createElement(tag);
+  el.textContent = text;
+  return el;
+}
+
+/** Build a `<p class="placeholder">` with the given message. */
+function buildPlaceholder(text) {
+  const p = document.createElement("p");
+  p.className = "placeholder";
+  p.textContent = text;
+  return p;
+}
+
+/** Dispatch table: route.kind → handler for routes that fit the (main) signature. */
+const ROUTE_RENDERERS = {
+  home: () => loadAndRenderHome(),
+  index: (main) => renderIndexPane(main),
+  health: (main) => renderHealthPane(main),
+  graph: (main) => renderGraphPane(main),
+};
+
 /** Fetch and render the page at the current hash route. */
 async function renderRoute() {
   const route = parseRoute(location.hash);
@@ -146,9 +246,8 @@ async function renderRoute() {
   const main = document.querySelector(MAIN_SELECTOR);
   if (!main) return;
   main.className = "main-pane";
-  if (route.kind === "home") return loadAndRenderHome();
-  if (route.kind === "index") return renderIndexPane(main);
-  if (route.kind === "health") return renderHealthPane(main);
+  const handler = ROUTE_RENDERERS[route.kind];
+  if (handler) return handler(main);
   return renderPagePane(main, route.directory, route.slug);
 }
 
@@ -157,9 +256,7 @@ async function renderHealthPane(main) {
   try {
     const health = await fetchJson("/api/health");
     main.innerHTML = "";
-    const h1 = document.createElement("h1");
-    h1.textContent = "Health";
-    main.appendChild(h1);
+    main.appendChild(buildHeading("h1", "Health"));
     main.appendChild(buildHealthDashboard(health));
     clearSupportRail();
   } catch (err) {
@@ -171,37 +268,24 @@ async function renderHealthPane(main) {
 function buildHealthDashboard(health) {
   const wrap = document.createElement("section");
   wrap.className = "health-dashboard";
-  const metrics = buildDefinitionList([
-    ["Concepts", health.concepts ?? 0],
-    ["Saved queries", health.queries ?? 0],
-    ["Compiled sources", health.sources ?? 0],
-    ["Source files", health.sourceFiles ?? 0],
-    ["Pending reviews", health.pendingReviews ?? 0],
-  ]);
+  const rows = HEALTH_METRIC_ROWS.map(([label, key]) => [label, health?.[key] ?? 0]);
+  const metrics = buildDefinitionList(rows);
   metrics.className = "metric-list";
   wrap.appendChild(metrics);
-  wrap.appendChild(buildLintBlock(health.lint));
+  wrap.appendChild(buildLintBlock(health?.lint));
   return wrap;
 }
 
 /** Render the lint summary, or a "lint has not been run yet" placeholder. */
 function buildLintBlock(lint) {
   const wrap = document.createElement("section");
-  const h2 = document.createElement("h2");
-  h2.textContent = "Lint";
-  wrap.appendChild(h2);
+  wrap.appendChild(buildHeading("h2", "Lint"));
   if (!lint) {
-    const note = document.createElement("p");
-    note.className = "placeholder";
-    note.textContent = "No cached lint summary yet — run `llmwiki lint`.";
-    wrap.appendChild(note);
+    wrap.appendChild(buildPlaceholder("No cached lint summary yet — run `llmwiki lint`."));
     return wrap;
   }
-  wrap.appendChild(buildDefinitionList([
-    ["Warnings", lint.warnings ?? 0],
-    ["Errors", lint.errors ?? 0],
-    ["Last run", lint.at ?? ""],
-  ]));
+  const rows = LINT_METRIC_ROWS.map(([label, key, fallback]) => [label, lint[key] ?? fallback]);
+  wrap.appendChild(buildDefinitionList(rows));
   return wrap;
 }
 
@@ -209,69 +293,89 @@ function buildLintBlock(lint) {
 async function loadAndRenderHome() {
   try {
     const envelope = await fetchJson("/api/pages");
-    document.querySelector(TITLE_SELECTOR).textContent = envelope.project?.title || "llmwiki";
-    renderSidebar(envelope.pages || []);
-    renderHome(envelope);
+    applyHomeEnvelope(envelope);
   } catch (err) {
     renderError(`Could not load /api/pages: ${err.message}`);
   }
 }
 
+/** Apply a successfully fetched /api/pages envelope to the chrome + main pane. */
+function applyHomeEnvelope(envelope) {
+  const titleEl = document.querySelector(TITLE_SELECTOR);
+  titleEl.textContent = projectTitle(envelope);
+  renderSidebar(envelope?.pages || []);
+  renderHome(envelope);
+}
+
 /** Fetch /api/index and render the rendered HTML coming back from the server. */
 async function renderIndexPane(main) {
   clearSupportRail();
   try {
     const payload = await fetchJson("/api/index");
     main.innerHTML = "";
-    const h1 = document.createElement("h1");
-    h1.textContent = "Index";
-    main.appendChild(h1);
+    main.appendChild(buildHeading("h1", "Index"));
     appendRenderedBody(main, payload.html);
   } catch (err) {
-    if (err.status === 404) {
-      main.innerHTML = "";
-      const note = document.createElement("p");
-      note.className = "placeholder";
-      note.textContent = "wiki/index.md is not available. Run `llmwiki compile`.";
-      main.appendChild(note);
-    } else {
-      renderError(`Could not load /api/index: ${err.message}`);
-    }
+    handleIndexError(main, err);
   }
 }
 
+/** Render either the "wiki/index.md missing" placeholder or a generic error. */
+function handleIndexError(main, err) {
+  if (err.status !== 404) {
+    renderError(`Could not load /api/index: ${err.message}`);
+    return;
+  }
+  main.innerHTML = "";
+  main.appendChild(buildPlaceholder("wiki/index.md is not available. Run `llmwiki compile`."));
+}
+
 /** Fetch /api/page/:dir/:slug and render. */
 async function renderPagePane(main, directory, slug) {
   try {
-    const payload = await fetchJson(
-      `/api/page/${encodeURIComponent(directory)}/${encodeURIComponent(slug)}`,
-    );
-    main.innerHTML = "";
-    const h1 = document.createElement("h1");
-    h1.textContent = payload.title || slug;
-    main.appendChild(h1);
-    if (payload.pageDirectory === "queries") {
-      const question = document.createElement("p");
-      question.className = "query-question";
-      question.textContent = `Question: ${payload.title || slug}`;
-      main.appendChild(question);
-    }
-    appendWarnings(main, payload.warnings || []);
-    const body = appendRenderedBody(main, payload.html);
-    removeDuplicateLeadingHeading(body, payload.title || slug);
-    renderSupportRail(payload);
+    const payload = await fetchJson(pageApiPath(directory, slug));
+    renderPagePayload(main, payload, slug);
   } catch (err) {
-    if (err.status === 404) {
-      main.innerHTML = "";
-      const note = document.createElement("p");
-      note.className = "placeholder";
-      note.textContent = `Page not found: ${directory}/${slug}`;
-      main.appendChild(note);
-      clearSupportRail();
-    } else {
-      renderError(`Could not load page: ${err.message}`);
-    }
+    handlePageError(main, err, directory, slug);
+  }
+}
+
+/** Build the `/api/page/:dir/:slug` URL with both segments percent-encoded. */
+function pageApiPath(directory, slug) {
+  return `/api/page/${encodeURIComponent(directory)}/${encodeURIComponent(slug)}`;
+}
+
+/** Render the body of a successful /api/page response into the main pane. */
+function renderPagePayload(main, payload, slug) {
+  const title = payload.title || slug;
+  main.innerHTML = "";
+  main.appendChild(buildHeading("h1", title));
+  if (payload.pageDirectory === "queries") {
+    main.appendChild(buildQueryQuestion(title));
+  }
+  appendWarnings(main, payload.warnings || []);
+  const body = appendRenderedBody(main, payload.html);
+  removeDuplicateLeadingHeading(body, title);
+  renderSupportRail(payload);
+}
+
+/** Question banner shown above the body for saved-query pages. */
+function buildQueryQuestion(title) {
+  const p = document.createElement("p");
+  p.className = "query-question";
+  p.textContent = `Question: ${title}`;
+  return p;
+}
+
+/** Render the 404 placeholder or a generic error for /api/page failures. */
+function handlePageError(main, err, directory, slug) {
+  if (err.status !== 404) {
+    renderError(`Could not load page: ${err.message}`);
+    return;
   }
+  main.innerHTML = "";
+  main.appendChild(buildPlaceholder(`Page not found: ${directory}/${slug}`));
+  clearSupportRail();
 }
 
 /**
@@ -290,18 +394,31 @@ function appendRenderedBody(main, html) {
     main.appendChild(body);
     return body;
   }
-  const note = emptyBodyNote();
+  const note = buildPlaceholder("No rendered content.");
   main.appendChild(note);
   return note;
 }
 
 /** Drop a duplicated first Markdown H1 when it matches the viewer page title. */
 function removeDuplicateLeadingHeading(body, title) {
-  if (!body || !title) return;
-  const first = body.firstElementChild;
-  if (!first || first.tagName !== "H1") return;
-  if (first.textContent?.trim() !== title.trim()) return;
-  first.remove();
+  const heading = leadingH1(body);
+  if (!heading) return;
+  if (!hasMatchingHeadingText(heading, title)) return;
+  heading.remove();
+}
+
+/** Return `body.firstElementChild` if it is an H1, else null. */
+function leadingH1(body) {
+  const first = body?.firstElementChild;
+  if (!first) return null;
+  return first.tagName === "H1" ? first : null;
+}
+
+/** True when the heading text matches `title` after trimming both sides. */
+function hasMatchingHeadingText(heading, title) {
+  if (!title) return false;
+  const headingText = heading.textContent?.trim();
+  return headingText === title.trim();
 }
 
 /** Render every payload warning as a banner above the page body. */
@@ -314,14 +431,6 @@ function appendWarnings(main, warnings) {
   }
 }
 
-/** Visible "no content" fallback for pages whose body is empty after frontmatter. */
-function emptyBodyNote() {
-  const note = document.createElement("p");
-  note.className = "placeholder";
-  note.textContent = "No rendered content.";
-  return note;
-}
-
 /** Render a top-of-main error banner without crashing the rest of the UI. */
 function renderError(message) {
   const main = document.querySelector(MAIN_SELECTOR);
@@ -334,6 +443,14 @@ function renderError(message) {
   clearSupportRail();
 }
 
+/** Fetch /api/graph and render the force-directed graph view. */
+async function renderGraphPane(main) {
+  clearSupportRail();
+  main.innerHTML = "";
+  main.className = "main-pane graph-pane";
+  await loadGraph(main);
+}
+
 /** Promise-returning fetch helper that surfaces non-2xx statuses as errors. */
 async function fetchJson(pathname) {
   const res = await fetch(pathname, { credentials: "same-origin" });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "llm-wiki-compiler",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "A knowledge compiler CLI — raw sources in, interlinked wiki out",
   "type": "module",
   "bin": {
@@ -10,10 +10,12 @@
     "build": "tsup",
     "dev": "tsup --watch",
     "dev:view": "node scripts/dev-viewer.mjs",
+    "release:check-docs": "node scripts/check-release-docs.mjs",
+    "release:check-docs:current": "node scripts/check-release-docs.mjs --current-version",
     "test": "vitest run",
     "test:watch": "vitest",
     "fallow:ci": "bash scripts/fallow-ci.sh",
-    "prepublishOnly": "npm run build && npm test",
+    "prepublishOnly": "npm run release:check-docs:current && npm run build && npm pack --dry-run --ignore-scripts",
     "prepare": "husky"
   },
   "keywords": [
@@ -36,6 +38,7 @@
   },
   "files": [
     "dist/",
+    "CHANGELOG.md",
     "LICENSE",
     "README.md"
   ],
@@ -67,7 +70,7 @@
     "@types/markdown-it": "^14.1.2",
     "@types/sanitize-html": "^2.16.1",
     "@types/turndown": "^5.0.0",
-    "fallow": "2.42.0",
+    "fallow": "2.82.0",
     "husky": "^9.1.7",
     "tsup": "^8.0.0",
     "typescript": "^5.7.0",