Fix docs connectivity and stabilize Bun CI

dev-dami · dev-dami · commit 664d553c5986 · 2026-02-18T06:17:28.000+01:00
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -22,7 +22,7 @@ jobs:
       - name: Setup Bun
         uses: oven-sh/setup-bun@v2
         with:
-          bun-version: latest
+          bun-version: "1.3.6"
 
       - name: Install dependencies
         run: bun install --frozen-lockfile
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
@@ -21,7 +21,7 @@ jobs:
       - name: Setup Bun
         uses: oven-sh/setup-bun@v2
         with:
-          bun-version: latest
+          bun-version: "1.3.6"
 
       - name: Setup Node (npm publish auth)
         uses: actions/setup-node@v4
diff --git a/bun.lock b/bun.lock
diff --git a/docs/pages/api.html b/docs/pages/api.html
@@ -10,7 +10,18 @@
     <main class="docs-shell">
       <header class="docs-nav" data-motion>
         <a class="brand" href="../index.html">Qirrel Docs</a>
-        <nav class="nav-links"><a class="nav-pill" href="../index.html">Back</a><a class="nav-pill" href="../../README.MD">README</a></nav>
+        <nav class="nav-links">
+          <a class="nav-pill" href="../index.html">Hub</a>
+          <a class="nav-pill" href="../../README.MD">README</a>
+          <a class="nav-pill" href="./api.html">API</a>
+          <a class="nav-pill" href="./configuration.html">Configuration</a>
+          <a class="nav-pill" href="./examples.html">Examples</a>
+          <a class="nav-pill" href="./basic.html">Basic</a>
+          <a class="nav-pill" href="./caching.html">Caching</a>
+          <a class="nav-pill" href="./events.html">Events</a>
+          <a class="nav-pill" href="./llm.html">LLM</a>
+          <a class="nav-pill" href="./walkthrough.html">Architecture</a>
+        </nav>
       </header>
 
       <section class="hero" data-motion>
diff --git a/docs/pages/basic.html b/docs/pages/basic.html
@@ -10,7 +10,18 @@
     <main class="docs-shell">
       <header class="docs-nav" data-motion>
         <a class="brand" href="../index.html">Qirrel Docs</a>
-        <nav class="nav-links"><a class="nav-pill" href="../index.html">Back</a></nav>
+        <nav class="nav-links">
+          <a class="nav-pill" href="../index.html">Hub</a>
+          <a class="nav-pill" href="../../README.MD">README</a>
+          <a class="nav-pill" href="./api.html">API</a>
+          <a class="nav-pill" href="./configuration.html">Configuration</a>
+          <a class="nav-pill" href="./examples.html">Examples</a>
+          <a class="nav-pill" href="./basic.html">Basic</a>
+          <a class="nav-pill" href="./caching.html">Caching</a>
+          <a class="nav-pill" href="./events.html">Events</a>
+          <a class="nav-pill" href="./llm.html">LLM</a>
+          <a class="nav-pill" href="./walkthrough.html">Architecture</a>
+        </nav>
       </header>
       <section class="hero" data-motion>
         <h1>Basic Usage</h1>
diff --git a/docs/pages/caching.html b/docs/pages/caching.html
@@ -8,7 +8,21 @@
   </head>
   <body>
     <main class="docs-shell">
-      <header class="docs-nav" data-motion><a class="brand" href="../index.html">Qirrel Docs</a><nav class="nav-links"><a class="nav-pill" href="../index.html">Back</a></nav></header>
+      <header class="docs-nav" data-motion>
+        <a class="brand" href="../index.html">Qirrel Docs</a>
+        <nav class="nav-links">
+          <a class="nav-pill" href="../index.html">Hub</a>
+          <a class="nav-pill" href="../../README.MD">README</a>
+          <a class="nav-pill" href="./api.html">API</a>
+          <a class="nav-pill" href="./configuration.html">Configuration</a>
+          <a class="nav-pill" href="./examples.html">Examples</a>
+          <a class="nav-pill" href="./basic.html">Basic</a>
+          <a class="nav-pill" href="./caching.html">Caching</a>
+          <a class="nav-pill" href="./events.html">Events</a>
+          <a class="nav-pill" href="./llm.html">LLM</a>
+          <a class="nav-pill" href="./walkthrough.html">Architecture</a>
+        </nav>
+      </header>
       <section class="hero" data-motion><h1>Caching</h1><p>LRU + TTL caching at pipeline and component levels.</p></section>
       <section class="section" data-motion>
         <h2>Config</h2>
diff --git a/docs/pages/configuration.html b/docs/pages/configuration.html
@@ -8,7 +8,21 @@
   </head>
   <body>
     <main class="docs-shell">
-      <header class="docs-nav" data-motion><a class="brand" href="../index.html">Qirrel Docs</a><nav class="nav-links"><a class="nav-pill" href="../index.html">Back</a></nav></header>
+      <header class="docs-nav" data-motion>
+        <a class="brand" href="../index.html">Qirrel Docs</a>
+        <nav class="nav-links">
+          <a class="nav-pill" href="../index.html">Hub</a>
+          <a class="nav-pill" href="../../README.MD">README</a>
+          <a class="nav-pill" href="./api.html">API</a>
+          <a class="nav-pill" href="./configuration.html">Configuration</a>
+          <a class="nav-pill" href="./examples.html">Examples</a>
+          <a class="nav-pill" href="./basic.html">Basic</a>
+          <a class="nav-pill" href="./caching.html">Caching</a>
+          <a class="nav-pill" href="./events.html">Events</a>
+          <a class="nav-pill" href="./llm.html">LLM</a>
+          <a class="nav-pill" href="./walkthrough.html">Architecture</a>
+        </nav>
+      </header>
       <section class="hero" data-motion><h1>Configuration</h1><p>Config loading order, sections, and env placeholder behavior.</p></section>
       <section class="section" data-motion>
         <h2>Loading Order</h2>
diff --git a/docs/pages/events.html b/docs/pages/events.html
@@ -8,7 +8,21 @@
   </head>
   <body>
     <main class="docs-shell">
-      <header class="docs-nav" data-motion><a class="brand" href="../index.html">Qirrel Docs</a><nav class="nav-links"><a class="nav-pill" href="../index.html">Back</a></nav></header>
+      <header class="docs-nav" data-motion>
+        <a class="brand" href="../index.html">Qirrel Docs</a>
+        <nav class="nav-links">
+          <a class="nav-pill" href="../index.html">Hub</a>
+          <a class="nav-pill" href="../../README.MD">README</a>
+          <a class="nav-pill" href="./api.html">API</a>
+          <a class="nav-pill" href="./configuration.html">Configuration</a>
+          <a class="nav-pill" href="./examples.html">Examples</a>
+          <a class="nav-pill" href="./basic.html">Basic</a>
+          <a class="nav-pill" href="./caching.html">Caching</a>
+          <a class="nav-pill" href="./events.html">Events</a>
+          <a class="nav-pill" href="./llm.html">LLM</a>
+          <a class="nav-pill" href="./walkthrough.html">Architecture</a>
+        </nav>
+      </header>
       <section class="hero" data-motion><h1>Pipeline Events</h1><p>Observe run-level and processor-level execution with lightweight handlers.</p></section>
       <section class="section" data-motion>
         <h2>Events</h2>
diff --git a/docs/pages/examples.html b/docs/pages/examples.html
@@ -8,7 +8,21 @@
   </head>
   <body>
     <main class="docs-shell">
-      <header class="docs-nav" data-motion><a class="brand" href="../index.html">Qirrel Docs</a><nav class="nav-links"><a class="nav-pill" href="../index.html">Back</a></nav></header>
+      <header class="docs-nav" data-motion>
+        <a class="brand" href="../index.html">Qirrel Docs</a>
+        <nav class="nav-links">
+          <a class="nav-pill" href="../index.html">Hub</a>
+          <a class="nav-pill" href="../../README.MD">README</a>
+          <a class="nav-pill" href="./api.html">API</a>
+          <a class="nav-pill" href="./configuration.html">Configuration</a>
+          <a class="nav-pill" href="./examples.html">Examples</a>
+          <a class="nav-pill" href="./basic.html">Basic</a>
+          <a class="nav-pill" href="./caching.html">Caching</a>
+          <a class="nav-pill" href="./events.html">Events</a>
+          <a class="nav-pill" href="./llm.html">LLM</a>
+          <a class="nav-pill" href="./walkthrough.html">Architecture</a>
+        </nav>
+      </header>
       <section class="hero" data-motion><h1>Examples</h1><p>Practical patterns for common integrations.</p></section>
       <section class="section" data-motion>
         <h2>Batch</h2>
diff --git a/docs/pages/llm.html b/docs/pages/llm.html
@@ -8,7 +8,21 @@
   </head>
   <body>
     <main class="docs-shell">
-      <header class="docs-nav" data-motion><a class="brand" href="../index.html">Qirrel Docs</a><nav class="nav-links"><a class="nav-pill" href="../index.html">Back</a></nav></header>
+      <header class="docs-nav" data-motion>
+        <a class="brand" href="../index.html">Qirrel Docs</a>
+        <nav class="nav-links">
+          <a class="nav-pill" href="../index.html">Hub</a>
+          <a class="nav-pill" href="../../README.MD">README</a>
+          <a class="nav-pill" href="./api.html">API</a>
+          <a class="nav-pill" href="./configuration.html">Configuration</a>
+          <a class="nav-pill" href="./examples.html">Examples</a>
+          <a class="nav-pill" href="./basic.html">Basic</a>
+          <a class="nav-pill" href="./caching.html">Caching</a>
+          <a class="nav-pill" href="./events.html">Events</a>
+          <a class="nav-pill" href="./llm.html">LLM</a>
+          <a class="nav-pill" href="./walkthrough.html">Architecture</a>
+        </nav>
+      </header>
       <section class="hero" data-motion><h1>LLM Integration</h1><p>Adapter-driven LLM extensions with resilient config and caching controls.</p></section>
       <section class="section" data-motion>
         <h2>Providers</h2>
diff --git a/docs/pages/walkthrough.html b/docs/pages/walkthrough.html
@@ -8,7 +8,21 @@
   </head>
   <body>
     <main class="docs-shell">
-      <header class="docs-nav" data-motion><a class="brand" href="../index.html">Qirrel Docs</a><nav class="nav-links"><a class="nav-pill" href="../index.html">Back</a></nav></header>
+      <header class="docs-nav" data-motion>
+        <a class="brand" href="../index.html">Qirrel Docs</a>
+        <nav class="nav-links">
+          <a class="nav-pill" href="../index.html">Hub</a>
+          <a class="nav-pill" href="../../README.MD">README</a>
+          <a class="nav-pill" href="./api.html">API</a>
+          <a class="nav-pill" href="./configuration.html">Configuration</a>
+          <a class="nav-pill" href="./examples.html">Examples</a>
+          <a class="nav-pill" href="./basic.html">Basic</a>
+          <a class="nav-pill" href="./caching.html">Caching</a>
+          <a class="nav-pill" href="./events.html">Events</a>
+          <a class="nav-pill" href="./llm.html">LLM</a>
+          <a class="nav-pill" href="./walkthrough.html">Architecture</a>
+        </nav>
+      </header>
       <section class="hero" data-motion><h1>Architecture Walkthrough</h1><p>How text moves from input to structured context.</p></section>
       <section class="section" data-motion>
         <h2>Flow</h2>
diff --git a/tests/docs-connectivity.test.ts b/tests/docs-connectivity.test.ts
@@ -0,0 +1,79 @@
+import fs from "node:fs";
+import path from "node:path";
+
+const docsRoot = path.resolve(__dirname, "..", "docs");
+const pagesDir = path.join(docsRoot, "pages");
+
+const topicPages = [
+  "api.html",
+  "basic.html",
+  "caching.html",
+  "configuration.html",
+  "events.html",
+  "examples.html",
+  "llm.html",
+  "walkthrough.html",
+];
+
+function readFile(relativePath: string): string {
+  return fs.readFileSync(path.join(docsRoot, relativePath), "utf8");
+}
+
+function extractHrefs(html: string): string[] {
+  const hrefs: string[] = [];
+  const pattern = /href="([^"]+)"/g;
+
+  for (const match of html.matchAll(pattern)) {
+    if (match[1]) {
+      hrefs.push(match[1]);
+    }
+  }
+
+  return hrefs;
+}
+
+describe("docs connectivity", () => {
+  test("docs index links to each topic page", () => {
+    const hrefs = extractHrefs(readFile("index.html"));
+    for (const page of topicPages) {
+      expect(hrefs).toContain(`./pages/${page}`);
+    }
+  });
+
+  test("every topic page links to docs hub, root README, and all topic pages", () => {
+    for (const page of topicPages) {
+      const hrefs = extractHrefs(readFile(path.join("pages", page)));
+
+      expect(hrefs).toContain("../index.html");
+      expect(hrefs).toContain("../../README.MD");
+
+      for (const linkedPage of topicPages) {
+        expect(hrefs).toContain(`./${linkedPage}`);
+      }
+    }
+  });
+
+  test("all local links resolve to an existing file", () => {
+    const htmlFiles = [
+      "index.html",
+      ...fs
+        .readdirSync(pagesDir)
+        .filter((file) => file.endsWith(".html"))
+        .map((file) => path.join("pages", file)),
+    ];
+
+    for (const htmlFile of htmlFiles) {
+      const html = readFile(htmlFile);
+      const hrefs = extractHrefs(html);
+
+      for (const href of hrefs) {
+        if (href.startsWith("http://") || href.startsWith("https://")) {
+          continue;
+        }
+
+        const resolved = path.resolve(path.join(docsRoot, htmlFile, ".."), href);
+        expect(fs.existsSync(resolved)).toBe(true);
+      }
+    }
+  });
+});
