@hutusi/amytis 1.15.0 → 1.17.0

package/src/lib/urls.ts

@@ -81,6 +81,11 @@ export function getBooksListUrl(): string {
   return '/books';
 }
 
+/** Returns the canonical URL path for a series landing page. */
+export function getSeriesUrl(slug: string): string {
+  return `/series/${slug}`;
+}
+
 /** Returns the canonical URL path for a book landing page. */
 export function getBookUrl(slug: string): string {
   return `/books/${slug}`;
@@ -105,3 +110,60 @@ export function getStaticPageUrl(slug: string): string {
 export function getPostUrlInCollection(post: { slug: string; series?: string }, collectionSlug: string): string {
   return `${getPostUrl(post)}?${new URLSearchParams({ collection: collectionSlug }).toString()}`;
 }
+
+let cachedSiteHost: string | null | undefined;
+
+function getSiteHost(): string | null {
+  if (cachedSiteHost !== undefined) return cachedSiteHost;
+  try {
+    cachedSiteHost = new URL(siteConfig.baseUrl).host;
+  } catch {
+    cachedSiteHost = null;
+  }
+  return cachedSiteHost;
+}
+
+/**
+ * True when `href` points to a different host than `siteConfig.baseUrl`.
+ *
+ * - `http://` / `https://` absolute URLs and protocol-relative `//host/...`
+ *   are tested by host comparison.
+ * - `mailto:`, `tel:`, `sms:`, `ftp:`, `javascript:` and other non-http
+ *   schemes return false — they're "external" in spirit but have different
+ *   click semantics and don't warrant an outward-arrow indicator.
+ * - Hash-only (`#foo`), query-only (`?foo`), relative paths (`/foo`,
+ *   `foo.md`), empty strings → false.
+ * - Malformed URLs → false (defensive — don't decorate something we can't parse).
+ */
+export function isExternalUrl(href: string | undefined | null): boolean {
+  if (!href) return false;
+  if (href.startsWith('#') || href.startsWith('?')) return false;
+  if (/^(mailto|tel|sms|ftp|javascript):/i.test(href)) return false;
+
+  const siteHost = getSiteHost();
+  if (!siteHost) return false;
+
+  if (href.startsWith('//')) {
+    // Prefix a dummy scheme so the URL parser handles auth (`//user:pass@host`),
+    // port-only (`//:80`), and IPv6 forms correctly — substring splitting on
+    // `/` is too coarse for any of those.
+    try {
+      return new URL(`https:${href}`).host !== siteHost;
+    } catch {
+      return false;
+    }
+  }
+  if (/^https?:\/\//i.test(href)) {
+    try {
+      return new URL(href).host !== siteHost;
+    } catch {
+      return false;
+    }
+  }
+  return false;
+}
+
+/** Test-only: drop the cached site host so a test can re-read `siteConfig.baseUrl`. */
+export function resetSiteHostCacheForTests(): void {
+  cachedSiteHost = undefined;
+}

package/src/test-utils/render.ts

@@ -0,0 +1,23 @@
+import type { ReactElement } from 'react';
+import { renderToReadableStream } from 'react-dom/server';
+
+/**
+ * Renders a React tree (including async server components) to a full HTML string.
+ * Use this in tests where the tree contains async components — sync renderers like
+ * renderToStaticMarkup throw "A component suspended" for async server components.
+ */
+export async function renderAsync(element: ReactElement): Promise<string> {
+  const stream = await renderToReadableStream(element);
+  await stream.allReady;
+  const reader = stream.getReader();
+  const decoder = new TextDecoder();
+  let html = '';
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    if (value) html += decoder.decode(value, { stream: !done });
+  }
+  // Flush any trailing buffered bytes from incomplete sequences (no-op for well-formed UTF-8).
+  html += decoder.decode();
+  return html;
+}

package/tests/fixtures/sync-vuepress-book/docs/.vuepress/config.js

@@ -0,0 +1,43 @@
+// Minimal VuePress 2 config used by the sync-vuepress-book integration test.
+// Mimics the structural shape of a real dmla-like config: a `theme(...)`
+// wrapper around an options object whose `sidebar` property is the literal
+// the importer needs to find.
+
+import dmlaTheme from './fake-theme.js'
+
+export default {
+  lang: 'zh-CN',
+  title: 'Fixture Book',
+  description: 'A tiny VuePress book used in tests',
+
+  theme: dmlaTheme({
+    sidebar: [
+      {
+        text: 'Intro',
+        collapsible: false,
+        link: '/intro/welcome',
+      },
+      {
+        text: 'Maths',
+        collapsible: false,
+        children: [
+          {
+            text: 'Linear Algebra',
+            collapsible: false,
+            children: [
+              { text: 'Vectors', link: '/maths/linear/vectors' },
+              { text: 'Matrices', link: '/maths/linear/matrices' },
+            ],
+          },
+        ],
+      },
+      {
+        // Empty section — simulates the dmla config's placeholder sections
+        // ("alignment", "reasoning") so the importer warns instead of throws.
+        text: 'TBD',
+        collapsible: false,
+        children: [],
+      },
+    ],
+  }),
+}

package/tests/fixtures/sync-vuepress-book/docs/intro/welcome.md

@@ -0,0 +1,7 @@
+---
+title: "Welcome"
+---
+
+# Welcome
+
+A short welcome chapter.

package/tests/fixtures/sync-vuepress-book/docs/maths/linear/assets/diagram.png

@@ -0,0 +1 @@
+stub binary image placeholder

package/tests/fixtures/sync-vuepress-book/docs/maths/linear/matrices.md

@@ -0,0 +1,7 @@
+---
+title: "Matrices"
+---
+
+# Matrices
+
+Builds on [vectors](vectors.md).

package/tests/fixtures/sync-vuepress-book/docs/maths/linear/vectors.md

@@ -0,0 +1,9 @@
+---
+title: "Vectors"
+---
+
+# Vectors
+
+See [matrices](matrices.md) for the next chapter.
+
+![diagram](./assets/diagram.png)

package/tests/helpers/env.ts

@@ -0,0 +1,19 @@
+// @types/node 25+ types specific env vars (NODE_ENV, etc.) as readonly on
+// `process.env`. Test code that wants to mutate them for the duration of a
+// scenario should go through these helpers — they widen the property type so
+// TS allows the write while still working at runtime exactly like
+// `process.env[key] = ...` always has.
+
+type MutableEnv = Record<string, string | undefined>;
+
+export function setEnvVar(key: string, value: string): void {
+  (process.env as MutableEnv)[key] = value;
+}
+
+export function restoreEnvVar(key: string, value: string | undefined): void {
+  if (value === undefined) {
+    delete (process.env as MutableEnv)[key];
+  } else {
+    (process.env as MutableEnv)[key] = value;
+  }
+}

package/tests/integration/book-chapter-links.test.ts

@@ -0,0 +1,107 @@
+import { describe, expect, test } from "bun:test";
+import MarkdownRenderer from "@/components/MarkdownRenderer";
+import { renderAsync } from "@/test-utils/render";
+import path from "path";
+
+const fixtureBookDir = path.resolve("tests/fixtures/book-chapter-links");
+const chapterSourcePath = path.join(fixtureBookDir, "maths/linear/introduction.md");
+
+const bookContext = {
+  bookSlug: "dmla",
+  bookDir: fixtureBookDir,
+  chapterSourcePath,
+  validChapterIds: new Set([
+    "maths/linear/introduction",
+    "maths/linear/vectors",
+    "maths/linear/matrices",
+    "deep-learning/perceptron",
+  ]),
+};
+
+describe("Integration: remark-book-chapter-links", () => {
+  test("rewrites a relative sibling .md link to its canonical chapter URL", async () => {
+    const html = await renderAsync(
+      MarkdownRenderer({
+        content: "See [vectors](vectors.md) for details.",
+        bookContext,
+      }),
+    );
+    expect(html).toContain('href="/books/dmla/maths/linear/vectors"');
+    expect(html).not.toContain('href="vectors.md"');
+  });
+
+  test("preserves fragment anchors when rewriting", async () => {
+    const html = await renderAsync(
+      MarkdownRenderer({
+        content: "See [tensors](matrices.md#tensors).",
+        bookContext,
+      }),
+    );
+    expect(html).toContain('href="/books/dmla/maths/linear/matrices#tensors"');
+  });
+
+  test("rewrites a parent-directory .md link", async () => {
+    const html = await renderAsync(
+      MarkdownRenderer({
+        content: "See [perceptron](../../deep-learning/perceptron.md).",
+        bookContext,
+      }),
+    );
+    expect(html).toContain('href="/books/dmla/deep-learning/perceptron"');
+  });
+
+  test("leaves external http links untouched", async () => {
+    const html = await renderAsync(
+      MarkdownRenderer({
+        content: "See [Wiki](https://en.wikipedia.org/wiki/Vector_space).",
+        bookContext,
+      }),
+    );
+    expect(html).toContain('href="https://en.wikipedia.org/wiki/Vector_space"');
+  });
+
+  test("leaves hash-only links untouched", async () => {
+    const html = await renderAsync(
+      MarkdownRenderer({
+        content: "[Top](#top)",
+        bookContext,
+      }),
+    );
+    expect(html).toContain('href="#top"');
+  });
+
+  test("warns and leaves the link unrewritten when target is not in the TOC", async () => {
+    const html = await renderAsync(
+      MarkdownRenderer({
+        content: "Broken [link](nonexistent.md).",
+        bookContext,
+      }),
+    );
+    // The unmatched link is kept as-is — it will 404 if clicked, but doesn't
+    // block the build. Matches the Shiki "unknown language → warn" precedent.
+    expect(html).toContain('href="nonexistent.md"');
+  });
+
+  test("malformed percent-encoding in a link does not crash the render", async () => {
+    // `%E0%A4%A` is a truncated UTF-8 sequence — bare decodeURIComponent throws
+    // URIError on this. The plugin must swallow that and not blow up the build.
+    const html = await renderAsync(
+      MarkdownRenderer({
+        content: "Sketchy [link](%E0%A4%A.md).",
+        bookContext,
+      }),
+    );
+    // Either the link survives as-is or it's silently dropped — what matters
+    // is that we don't get an unhandled URIError tearing down the render.
+    expect(html).toContain("Sketchy");
+  });
+
+  test("non-book content (no bookContext) is not rewritten", async () => {
+    const html = await renderAsync(
+      MarkdownRenderer({
+        content: "See [vectors](vectors.md).",
+      }),
+    );
+    expect(html).toContain('href="vectors.md"');
+  });
+});

package/tests/integration/book-index-cta.test.ts

@@ -0,0 +1,87 @@
+import { describe, expect, test } from "bun:test";
+import BookLandingPage from "@/app/books/[slug]/page";
+import { renderAsync } from "@/test-utils/render";
+import { getBookData } from "@/lib/markdown";
+import { t } from "@/lib/i18n";
+import { getBookChapterUrl } from "@/lib/urls";
+
+// Renders the actual book landing page server component for a real fixture
+// book under content/books/. The page is async (calls getBookData internally)
+// so we use the project's renderAsync helper — same pattern as
+// tests/integration/book-chapter-links.test.ts. Catches the regression
+// modes that pure-helper tests can't: someone removes either CTA from the
+// JSX, or changes the href format and drops ?immersive=1.
+
+const FIXTURE_BOOK_SLUG = "sample-book";
+
+function escapeRegex(s: string): string {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+// Returns the inner HTML of the smallest <a> element on the page whose href
+// attribute equals the given value, or null if no such anchor exists. We
+// match the anchor body rather than just `href="..."` so the label-text
+// assertion is bound to the same element — otherwise an unrelated link with
+// the same href (e.g. a TOC chapter row pointing at the first chapter) would
+// satisfy a naïve `toContain('href="..."')` check and let an accidentally
+// deleted CTA pass.
+function findAnchorBodyByHref(html: string, href: string): string | null {
+  const re = new RegExp(`<a[^>]*\\bhref="${escapeRegex(href)}"[^>]*>([\\s\\S]*?)</a>`);
+  const m = html.match(re);
+  return m ? m[1] : null;
+}
+
+describe("Integration: book index Immersive reading CTA", () => {
+  test("renders an Immersive reading CTA linking to the first chapter with ?immersive=1", async () => {
+    const book = getBookData(FIXTURE_BOOK_SLUG);
+    if (!book || book.chapters.length === 0) {
+      throw new Error(
+        `Fixture book "${FIXTURE_BOOK_SLUG}" not found or has no chapters — this test depends on it`,
+      );
+    }
+    const firstChapter = book.chapters[0];
+    const expectedHref = `${getBookChapterUrl(book.slug, firstChapter.id)}?immersive=1`;
+
+    const html = await renderAsync(
+      BookLandingPage({ params: Promise.resolve({ slug: FIXTURE_BOOK_SLUG }) }),
+    );
+
+    const body = findAnchorBodyByHref(html, expectedHref);
+    expect(body).not.toBeNull();
+    // Label text is rendered inside the same anchor — guards against the
+    // anchor existing but having been repurposed to a different CTA.
+    expect(body).toContain(t("immersive_reading"));
+  });
+
+  test("primary 'Start reading' CTA still renders alongside the immersive CTA", async () => {
+    const book = getBookData(FIXTURE_BOOK_SLUG);
+    if (!book || book.chapters.length === 0) {
+      throw new Error(
+        `Fixture book "${FIXTURE_BOOK_SLUG}" not found or has no chapters`,
+      );
+    }
+    const firstChapter = book.chapters[0];
+    const primaryHref = getBookChapterUrl(book.slug, firstChapter.id);
+
+    const html = await renderAsync(
+      BookLandingPage({ params: Promise.resolve({ slug: FIXTURE_BOOK_SLUG }) }),
+    );
+
+    // Multiple links may share this href (TOC rows also point at the first
+    // chapter), so iterate over all matches and confirm at least one of them
+    // is the CTA — the one containing the start_reading label text.
+    const re = new RegExp(
+      `<a[^>]*\\bhref="${escapeRegex(primaryHref)}"[^>]*>([\\s\\S]*?)</a>`,
+      "g",
+    );
+    const label = t("start_reading");
+    let foundCta = false;
+    for (const match of html.matchAll(re)) {
+      if (match[1].includes(label)) {
+        foundCta = true;
+        break;
+      }
+    }
+    expect(foundCta).toBe(true);
+  });
+});

package/tests/integration/books-nested-toc.test.ts

@@ -0,0 +1,176 @@
+import { describe, expect, test } from "bun:test";
+import {
+  flattenBookChapters,
+  BookSchema,
+  type BookTocItem,
+} from "../../src/lib/markdown";
+
+describe("Integration: Books nested TOC", () => {
+  test("schema accepts the legacy { part, chapters } shape", () => {
+    const result = BookSchema.safeParse({
+      title: "Legacy Book",
+      date: "2026-01-01",
+      chapters: [
+        {
+          part: "Part I",
+          chapters: [
+            { title: "Intro", id: "intro" },
+            { title: "Setup", id: "setup" },
+          ],
+        },
+        {
+          part: "Part II",
+          chapters: [{ title: "Outro", id: "outro" }],
+        },
+      ],
+    });
+    expect(result.success).toBe(true);
+  });
+
+  test("schema accepts the new { section, items } shape with arbitrary nesting", () => {
+    const result = BookSchema.safeParse({
+      title: "VuePress Book",
+      date: "2026-01-01",
+      chapters: [
+        {
+          section: "Maths",
+          items: [
+            {
+              section: "Linear Algebra",
+              items: [
+                { title: "Intro", id: "maths/linear/introduction" },
+                { title: "Vectors", id: "maths/linear/vectors" },
+              ],
+            },
+            {
+              section: "Calculus",
+              items: [{ title: "Derivative", id: "maths/calculus/derivative" }],
+            },
+          ],
+        },
+      ],
+    });
+    expect(result.success).toBe(true);
+  });
+
+  test("schema accepts bare chapter refs at the top level", () => {
+    const result = BookSchema.safeParse({
+      title: "Flat Book",
+      date: "2026-01-01",
+      chapters: [
+        { title: "Chapter 1", id: "ch1" },
+        { title: "Chapter 2", id: "ch2" },
+      ],
+    });
+    expect(result.success).toBe(true);
+  });
+
+  test("schema accepts a mixed TOC (legacy parts + new sections + bare refs)", () => {
+    const result = BookSchema.safeParse({
+      title: "Mixed Book",
+      date: "2026-01-01",
+      chapters: [
+        { part: "Part A", chapters: [{ title: "A1", id: "a1" }] },
+        {
+          section: "Section B",
+          items: [{ title: "B1", id: "section-b/b1" }],
+        },
+        { title: "Standalone", id: "standalone" },
+      ],
+    });
+    expect(result.success).toBe(true);
+  });
+
+  test("schema rejects a section with neither items nor a section title", () => {
+    const result = BookSchema.safeParse({
+      title: "Bad Book",
+      date: "2026-01-01",
+      chapters: [{ section: "No items" } as unknown],
+    });
+    expect(result.success).toBe(false);
+  });
+
+  test("flattenBookChapters preserves order across legacy parts", () => {
+    const toc: BookTocItem[] = [
+      {
+        part: "Part I",
+        chapters: [
+          { title: "Intro", id: "intro" },
+          { title: "Setup", id: "setup" },
+        ],
+      },
+      { part: "Part II", chapters: [{ title: "Outro", id: "outro" }] },
+    ];
+    const flat = flattenBookChapters(toc);
+    expect(flat.map((c) => c.id)).toEqual(["intro", "setup", "outro"]);
+    expect(flat[0].part).toBe("Part I");
+    expect(flat[1].part).toBe("Part I");
+    expect(flat[2].part).toBe("Part II");
+    expect(flat[0].section).toBeUndefined();
+    expect(flat[0].sectionPath).toBeUndefined();
+  });
+
+  test("flattenBookChapters walks nested sections in source order", () => {
+    const toc: BookTocItem[] = [
+      {
+        section: "Maths",
+        items: [
+          {
+            section: "Linear Algebra",
+            items: [
+              { title: "Intro", id: "maths/linear/introduction" },
+              { title: "Vectors", id: "maths/linear/vectors" },
+            ],
+          },
+          {
+            section: "Calculus",
+            items: [{ title: "Derivative", id: "maths/calculus/derivative" }],
+          },
+        ],
+      },
+    ];
+    const flat = flattenBookChapters(toc);
+    expect(flat.map((c) => c.id)).toEqual([
+      "maths/linear/introduction",
+      "maths/linear/vectors",
+      "maths/calculus/derivative",
+    ]);
+  });
+
+  test("flattenBookChapters annotates section + sectionPath for nested chapters", () => {
+    const toc: BookTocItem[] = [
+      {
+        section: "Maths",
+        items: [
+          {
+            section: "Linear Algebra",
+            items: [{ title: "Intro", id: "maths/linear/introduction" }],
+          },
+        ],
+      },
+    ];
+    const flat = flattenBookChapters(toc);
+    expect(flat).toHaveLength(1);
+    expect(flat[0].section).toBe("Linear Algebra");
+    expect(flat[0].sectionPath).toEqual(["Maths", "Linear Algebra"]);
+    expect(flat[0].part).toBeUndefined();
+  });
+
+  test("flattenBookChapters handles mixed legacy + new + bare entries", () => {
+    const toc: BookTocItem[] = [
+      { part: "Part A", chapters: [{ title: "A1", id: "a1" }] },
+      {
+        section: "Section B",
+        items: [{ title: "B1", id: "section-b/b1" }],
+      },
+      { title: "Standalone", id: "standalone" },
+    ];
+    const flat = flattenBookChapters(toc);
+    expect(flat.map((c) => c.id)).toEqual(["a1", "section-b/b1", "standalone"]);
+    expect(flat[0].part).toBe("Part A");
+    expect(flat[1].section).toBe("Section B");
+    expect(flat[1].sectionPath).toEqual(["Section B"]);
+    expect(flat[2].part).toBeUndefined();
+    expect(flat[2].section).toBeUndefined();
+  });
+});

package/tests/integration/books.test.ts

@@ -1,5 +1,6 @@
 import { describe, expect, test } from "bun:test";
 import { getAllBooks, getFeaturedBooks } from "../../src/lib/markdown";
+import { setEnvVar, restoreEnvVar } from "../helpers/env";
 
 describe("Integration: Books", () => {
   test("getAllBooks returns an array", () => {
@@ -48,14 +49,14 @@ describe("Integration: Books", () => {
 
   test("getAllBooks excludes drafts in production", () => {
     const prev = process.env.NODE_ENV;
-    process.env.NODE_ENV = "production";
+    setEnvVar("NODE_ENV", "production");
     try {
       const books = getAllBooks();
       books.forEach((book) => {
         expect(book.draft).toBe(false);
       });
     } finally {
-      process.env.NODE_ENV = prev;
+      restoreEnvVar("NODE_ENV", prev);
     }
   });
 });