@hutusi/amytis 1.14.0 → 1.16.0

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/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);
     }
   });
 });

package/tests/integration/code-block-features.test.ts

@@ -0,0 +1,188 @@
+import { describe, expect, test } from 'bun:test';
+import MarkdownRenderer from '@/components/MarkdownRenderer';
+import RstRenderer from '@/components/RstRenderer';
+import { renderAsync } from '@/test-utils/render';
+
+describe('Integration: Code Block Features', () => {
+  describe('Markdown / MDX', () => {
+    test('highlights specific lines from {n,n-m} fence meta', async () => {
+      const content = [
+        '```ts {1,3-4}',
+        'const a = 1;',
+        'const b = 2;',
+        'const c = 3;',
+        'const d = 4;',
+        '```',
+      ].join('\n');
+
+      const html = await renderAsync(MarkdownRenderer({ content }));
+
+      // Lines 1, 3, 4 should be marked as highlighted; 2 should not.
+      expect(html).toContain('data-highlighted-line="1"');
+      expect(html).toContain('data-highlighted-line="3"');
+      expect(html).toContain('data-highlighted-line="4"');
+      expect(html).not.toContain('data-highlighted-line="2"');
+    });
+
+    test('opt-in line numbers via `linenos` fence meta', async () => {
+      const content = ['```js linenos', 'const x = 1;', '```'].join('\n');
+      const html = await renderAsync(MarkdownRenderer({ content }));
+
+      expect(html).toContain('data-line-numbers="true"');
+    });
+
+    test('title bar from title="..." fence meta', async () => {
+      const content = ['```ts title="src/app.ts"', 'export const x = 1;', '```'].join('\n');
+      const html = await renderAsync(MarkdownRenderer({ content }));
+
+      expect(html).toContain('src/app.ts');
+      expect(html).toContain('cb-title');
+    });
+
+    test('diff fence colors +/- lines with diff add/remove classes', async () => {
+      const content = ['```diff', '-old', '+new', ' unchanged', '```'].join('\n');
+      const html = await renderAsync(MarkdownRenderer({ content }));
+
+      expect(html).toContain('diff add');
+      expect(html).toContain('diff remove');
+    });
+
+    test('mermaid blocks do not run through Shiki', async () => {
+      const content = ['```mermaid', 'graph TD; A-->B;', '```'].join('\n');
+      const html = await renderAsync(MarkdownRenderer({ content }));
+
+      // Mermaid is short-circuited in MarkdownRenderer before CodeBlock is invoked,
+      // so no Shiki wrapper should appear for a mermaid fence.
+      expect(html).not.toContain('class="shiki');
+      // The Mermaid component delegates client-side rendering; assert its container.
+      expect(html.toLowerCase()).toContain('mermaid');
+    });
+
+    // Extract the Mermaid outer-wrapper class string so token assertions are
+    // order-independent and scoped to the wrapper — not the surrounding prose
+    // chrome (which carries `prose-code:*` utilities that share substrings).
+    const findMermaidWrapperClass = (html: string): string => {
+      // The wrapper precedes the inner `class="mermaid ..."` element. Match the
+      // *previous* class attribute by anchoring on the inner mermaid class.
+      const m = html.match(/class="([^"]*)"\s*><div class="mermaid /);
+      return m?.[1] ?? '';
+    };
+
+    test('mermaid renders with a frameless wrapper (no border/padding/shadow)', async () => {
+      // Mermaid SVG nodes carry their own borders, so the prose pipeline does
+      // not wrap diagrams in a framed container the way it wraps tables.
+      const content = ['```mermaid', 'graph TD; A-->B;', '```'].join('\n');
+      const html = await renderAsync(MarkdownRenderer({ content }));
+      const wrapper = findMermaidWrapperClass(html);
+
+      expect(wrapper).toContain('my-6');
+      expect(wrapper).toContain('overflow-x-auto');
+      expect(wrapper).not.toContain('shadow-sm');
+      expect(wrapper).not.toContain('p-4');
+      expect(wrapper).not.toContain('md:p-8');
+      expect(wrapper).not.toContain('border');
+      expect(html.toLowerCase()).toContain('mermaid');
+    });
+
+    test('legacy `compact` fence meta is a no-op (no regression for old content)', async () => {
+      // ` ```mermaid compact ` used to opt out of a framed wrapper that no
+      // longer exists. The flag stays unrecognised by the pipeline and must
+      // render identically to a bare ` ```mermaid ` fence — otherwise the 52
+      // historical `compact` blocks in `content/` would regress.
+      const bare = await renderAsync(
+        MarkdownRenderer({ content: ['```mermaid', 'graph TD; A-->B;', '```'].join('\n') }),
+      );
+      const withCompact = await renderAsync(
+        MarkdownRenderer({ content: ['```mermaid compact', 'graph TD; A-->B;', '```'].join('\n') }),
+      );
+
+      expect(findMermaidWrapperClass(withCompact)).toBe(findMermaidWrapperClass(bare));
+    });
+
+    test('unknown language renders as plaintext (warn-and-degrade)', async () => {
+      // Production deploys can't fail on a single unknown fence — render as
+      // plaintext and emit a build-time warn instead. Three previous failures
+      // (make, golang, plus the alias overlay) demonstrated that strict-build
+      // at the fence-language layer was the wrong trade-off.
+      const content = ['```fakelang', 'should still render', '```'].join('\n');
+      const html = await renderAsync(MarkdownRenderer({ content }));
+
+      expect(html).toContain('class="shiki');
+      expect(html).toContain('should still render');
+      // Should NOT throw.
+    });
+
+    test('explicit `plaintext` fences render unhighlighted without erroring', async () => {
+      const content = ['```plaintext', 'just prose', '```'].join('\n');
+      const html = await renderAsync(MarkdownRenderer({ content }));
+
+      expect(html).toContain('class="shiki');
+      expect(html).toContain('just prose');
+    });
+
+    test('previously-unregistered Shiki languages (make, dockerfile, etc.) lazy-load on demand', async () => {
+      // Regression: production build broke when a real post used ```make. The fix
+      // resolves any of Shiki's ~235 bundled languages via its own metadata; the lang
+      // is loaded the first time it's seen, no hand-maintained allowlist required.
+      const content = ['```make', 'all:', '\t@echo "Building..."', '\tgcc -o app main.c', '```'].join('\n');
+      const html = await renderAsync(MarkdownRenderer({ content }));
+
+      expect(html).toContain('class="shiki');
+      // Header label uses Shiki's proper-case name from bundledLanguagesInfo.
+      expect(html).toContain('>Makefile<');
+      // Source lines survive and get token coloring.
+      expect(html).toContain('all');
+      expect(html).toContain('gcc');
+    });
+
+    test('community-alias `golang` resolves to Go (regression: production build)', async () => {
+      // Shiki does NOT list `golang` as an alias of `go` in its bundledLanguagesInfo,
+      // so a fence using ```golang would throw before the COMMUNITY_ALIASES overlay
+      // was added. The overlay maps it to the bundled `go` grammar.
+      const content = ['```golang', 'package main', '', 'func main() {', '\tprintln("hi")', '}', '```'].join('\n');
+      const html = await renderAsync(MarkdownRenderer({ content }));
+
+      expect(html).toContain('class="shiki');
+      expect(html).toContain('>Go<');
+      expect(html).toContain('package');
+      expect(html).toContain('main');
+    });
+  });
+
+  describe('rST', () => {
+    test('rST :linenos:, :emphasize-lines:, :caption: render through Shiki', async () => {
+      const content = [
+        'Section',
+        '-------',
+        '',
+        '.. code-block:: python',
+        '   :linenos:',
+        '   :emphasize-lines: 1,3-4',
+        '   :caption: app.py',
+        '',
+        '  def fib(n):',
+        '      if n < 2:',
+        '          return n',
+        '      return fib(n - 1) + fib(n - 2)',
+      ].join('\n');
+
+      const html = await renderAsync(RstRenderer({ content }));
+
+      expect(html).toContain('class="shiki');
+      expect(html).toContain('data-line-numbers="true"');
+      expect(html).toContain('data-highlighted-line="1"');
+      expect(html).toContain('data-highlighted-line="3"');
+      expect(html).toContain('data-highlighted-line="4"');
+      // :caption: surfaces as title bar text in the wrapper header.
+      expect(html).toContain('app.py');
+    });
+
+    test('rST :: literal block renders as plaintext through Shiki', async () => {
+      const content = ['Section', '-------', '', 'Example::', '', '  plain literal'].join('\n');
+      const html = await renderAsync(RstRenderer({ content }));
+
+      expect(html).toContain('class="shiki');
+      expect(html).toContain('plain literal');
+    });
+  });
+});