@hutusi/amytis 1.14.0 → 1.15.0

package/tests/integration/series-draft.test.ts

@@ -1,6 +1,14 @@
 import { describe, expect, test } from "bun:test";
 import { getSeriesData, getAllSeries } from "../../src/lib/markdown";
 
+function restoreEnvVar(key: string, value: string | undefined): void {
+  if (value === undefined) {
+    delete process.env[key];
+  } else {
+    process.env[key] = value;
+  }
+}
+
 describe("Integration: Series Draft Support", () => {
   test("all series are included when NODE_ENV is not production", () => {
     // In test environment NODE_ENV is typically 'test'
@@ -18,20 +26,25 @@ describe("Integration: Series Draft Support", () => {
 
   test("draft filtering code path runs without error in production mode", () => {
     const originalEnv = process.env.NODE_ENV;
+    const originalPythonRst = process.env.AMYTIS_ENABLE_PYTHON_RST;
     try {
       process.env.NODE_ENV = "production";
+      process.env.AMYTIS_ENABLE_PYTHON_RST = "0";
       // This should not throw; draft series are simply excluded
       const series = getAllSeries();
       expect(typeof series).toBe("object");
     } finally {
-      process.env.NODE_ENV = originalEnv;
+      restoreEnvVar("NODE_ENV", originalEnv);
+      restoreEnvVar("AMYTIS_ENABLE_PYTHON_RST", originalPythonRst);
     }
   });
 
   test("draft series are excluded in production mode", () => {
     const originalEnv = process.env.NODE_ENV;
+    const originalPythonRst = process.env.AMYTIS_ENABLE_PYTHON_RST;
     try {
       process.env.NODE_ENV = "production";
+      process.env.AMYTIS_ENABLE_PYTHON_RST = "0";
       const allSeries = getAllSeries();
       
       // Verify that every series returned has draft: false (or undefined which defaults to false)
@@ -40,7 +53,8 @@ describe("Integration: Series Draft Support", () => {
         expect(seriesData?.draft).not.toBe(true);
       });
     } finally {
-      process.env.NODE_ENV = originalEnv;
+      restoreEnvVar("NODE_ENV", originalEnv);
+      restoreEnvVar("AMYTIS_ENABLE_PYTHON_RST", originalPythonRst);
     }
   });
 });

package/tests/integration/series.test.ts

@@ -1,7 +1,10 @@
 import { describe, expect, test } from "bun:test";
+import { parseRstDocument, RstParseError } from "../../src/lib/rst";
 import {
   getAllSeries,
+  getAdjacentPosts,
   getSeriesData,
+  getSeriesLatestPostDate,
   getSeriesPosts,
   getFeaturedPosts,
   getFeaturedSeries,
@@ -13,6 +16,10 @@ describe("Integration: Series", () => {
     expect(Object.keys(series).length).toBeGreaterThan(0);
     expect(series).toHaveProperty("nextjs-deep-dive");
     expect(series).toHaveProperty("digital-garden");
+    expect(series).toHaveProperty("rst-legacy");
+    expect(series).toHaveProperty("rst-readme");
+    expect(series).toHaveProperty("rst-toctree");
+    expect(series).toHaveProperty("rst-toctree-precedence");
   });
 
   test("getSeriesData returns metadata with correct fields", () => {
@@ -30,6 +37,49 @@ describe("Integration: Series", () => {
     expect(data).toBeNull();
   });
 
+  test("getSeriesData loads rST series metadata", () => {
+    const data = getSeriesData("rst-legacy");
+    expect(data).not.toBeNull();
+    expect(data!.title).toBe("Rst Legacy Series");
+    expect(data!.sourceFormat).toBe("rst");
+    expect(data!.sort).toBe("manual");
+    expect(data!.posts).toEqual(["getting-started", "deeper-notes"]);
+  });
+
+  test("getSeriesData accepts README.rst as the series index", () => {
+    const data = getSeriesData("rst-readme");
+    expect(data).not.toBeNull();
+    expect(data!.title).toBe("Rst README Series");
+    expect(data!.sourceFormat).toBe("rst");
+    expect(data!.posts).toEqual(["readme-index-post"]);
+  });
+
+  test("getSeriesData derives manual order from rST toctree when posts metadata is absent", () => {
+    const data = getSeriesData("rst-toctree");
+    expect(data).not.toBeNull();
+    expect(data!.title).toBe("Rst Toctree Series");
+    expect(data!.sourceFormat).toBe("rst");
+    expect(data!.sort).toBe("manual");
+    expect(data!.posts).toEqual(["second-post", "first-post"]);
+  });
+
+  test("getSeriesData rejects unsafe series slugs", () => {
+    expect(() => getSeriesData("../etc/passwd")).toThrow();
+    expect(() => getSeriesData("nested/slug")).toThrow();
+  });
+
+  test("rST series indexes reject impossible dates", () => {
+    expect(() => parseRstDocument([
+      "Broken rST Series",
+      "=================",
+      "",
+      ":date: 2021-16-15",
+      "",
+      "Body.",
+      "",
+    ].join("\n"))).toThrow(RstParseError);
+  });
+
   test("getSeriesPosts returns posts in manual order for manual series", () => {
     const seriesData = getSeriesData("nextjs-deep-dive");
     expect(seriesData?.sort).toBe("manual");
@@ -62,6 +112,49 @@ describe("Integration: Series", () => {
     expect(posts).toEqual([]);
   });
 
+  test("getSeriesPosts returns rST posts in manual order", () => {
+    const posts = getSeriesPosts("rst-legacy");
+    expect(posts.map(post => post.slug)).toEqual(["getting-started", "deeper-notes"]);
+    expect(posts.every(post => post.sourceFormat === "rst")).toBe(true);
+  });
+
+  test("getSeriesPosts loads posts for README.rst-based series", () => {
+    const posts = getSeriesPosts("rst-readme");
+    expect(posts.map(post => post.slug)).toEqual(["readme-index-post"]);
+    expect(posts[0]?.sourceFormat).toBe("rst");
+  });
+
+  test("getSeriesPosts follows rST toctree order when posts metadata is absent", () => {
+    const posts = getSeriesPosts("rst-toctree");
+    expect(posts.map(post => post.slug)).toEqual(["second-post", "first-post"]);
+    expect(posts.every(post => post.sourceFormat === "rst")).toBe(true);
+  });
+
+  test("getSeriesLatestPostDate uses the newest post date instead of manual series order", () => {
+    expect(getSeriesData("nextjs-deep-dive")?.sort).toBe("manual");
+    expect(getSeriesPosts("nextjs-deep-dive").map(post => post.date)).toEqual(["2026-01-30", "2026-01-31"]);
+    expect(getSeriesLatestPostDate("nextjs-deep-dive")).toBe("2026-01-31");
+  });
+
+  test("getAdjacentPosts follows rST series order instead of global post date order", () => {
+    const first = getAdjacentPosts("getting-started");
+    expect(first.prev?.slug ?? null).toBeNull();
+    expect(first.next?.slug).toBe("deeper-notes");
+
+    const second = getAdjacentPosts("deeper-notes");
+    expect(second.prev?.slug).toBe("getting-started");
+    expect(second.next?.slug ?? null).toBeNull();
+  });
+
+  test("explicit rST posts metadata takes precedence over toctree order", () => {
+    const data = getSeriesData("rst-toctree-precedence");
+    expect(data).not.toBeNull();
+    expect(data!.posts).toEqual(["first-post", "second-post"]);
+
+    const posts = getSeriesPosts("rst-toctree-precedence");
+    expect(posts.map(post => post.slug)).toEqual(["first-post", "second-post"]);
+  });
+
   test("getFeaturedPosts returns only posts with featured: true", () => {
     const featured = getFeaturedPosts();
     featured.forEach((post) => {

package/tests/tooling/build-pagefind.test.ts

@@ -0,0 +1,66 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import fs from "fs";
+import os from "os";
+import path from "path";
+import {
+  collectHtmlFileHashes,
+  getPagefindManifestPathForTests,
+  shouldSkipPagefindBuild,
+} from "../../scripts/build-pagefind";
+
+const createdDirs: string[] = [];
+
+afterEach(() => {
+  for (const dir of createdDirs.splice(0)) {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+  fs.rmSync(path.join(process.cwd(), ".cache", "pagefind"), { recursive: true, force: true });
+});
+
+function makeTempDir(prefix: string): string {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), prefix));
+  createdDirs.push(dir);
+  return dir;
+}
+
+describe("Tooling: build-pagefind", () => {
+  test("collectHtmlFileHashes hashes HTML files by relative path", () => {
+    const siteDir = makeTempDir("amytis-pagefind-site-");
+    fs.mkdirSync(path.join(siteDir, "posts"), { recursive: true });
+    fs.writeFileSync(path.join(siteDir, "index.html"), "<html><body>Home</body></html>", "utf8");
+    fs.writeFileSync(path.join(siteDir, "posts", "hello.html"), "<html><body>Hello</body></html>", "utf8");
+    fs.writeFileSync(path.join(siteDir, "notes.txt"), "ignore", "utf8");
+
+    const hashes = collectHtmlFileHashes(siteDir);
+
+    expect(Object.keys(hashes)).toEqual(["index.html", "posts/hello.html"]);
+    expect(hashes["index.html"]).toBeTruthy();
+    expect(hashes["posts/hello.html"]).toBeTruthy();
+  });
+
+  test("skips Pagefind when HTML hashes and output path are unchanged", () => {
+    const siteDir = makeTempDir("amytis-pagefind-site-");
+    const outputDir = makeTempDir("amytis-pagefind-out-");
+    fs.writeFileSync(path.join(siteDir, "index.html"), "<html><body>Home</body></html>", "utf8");
+    fs.writeFileSync(path.join(outputDir, "pagefind.js"), "stub", "utf8");
+
+    const hashes = collectHtmlFileHashes(siteDir);
+    const manifestPath = getPagefindManifestPathForTests(siteDir, outputDir);
+    fs.mkdirSync(path.dirname(manifestPath), { recursive: true });
+    fs.writeFileSync(
+      manifestPath,
+      JSON.stringify({
+        version: "1",
+        sitePath: path.resolve(siteDir),
+        outputPath: path.resolve(outputDir),
+        files: hashes,
+      }),
+      "utf8",
+    );
+
+    expect(shouldSkipPagefindBuild(siteDir, outputDir, hashes)).toBe(true);
+
+    fs.writeFileSync(path.join(siteDir, "index.html"), "<html><body>Changed</body></html>", "utf8");
+    expect(shouldSkipPagefindBuild(siteDir, outputDir, collectHtmlFileHashes(siteDir))).toBe(false);
+  });
+});

package/tests/unit/static-params.test.ts

@@ -131,6 +131,7 @@ beforeAll(() => {
     getSeriesData: (slug: string) => mockedSeriesData[slug] ?? null,
     getSeriesPosts: () => [],
     getSeriesAuthors: () => [],
+    getCollectionsForPost: () => [],
 
     getAuthorSlug: (name: string) =>
       name.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, ''),
@@ -254,11 +255,101 @@ describe('generateStaticParams — placeholder when content is empty', () => {
       expect(params).toContainEqual({ slug: 'old-name' });
     });
 
+    test('series/[slug] includes raw and encoded Unicode slug in non-production', async () => {
+      mockedSeries = { '软件构架设计': [] };
+      process.env.NODE_ENV = 'development';
+      const { generateStaticParams } = await import('../../src/app/series/[slug]/page');
+      const params = await generateStaticParams();
+      expect(params).toContainEqual({ slug: '软件构架设计' });
+      expect(params).toContainEqual({ slug: '%E8%BD%AF%E4%BB%B6%E6%9E%84%E6%9E%B6%E8%AE%BE%E8%AE%A1' });
+    });
+
+    test('series/[slug] includes only raw Unicode slug in production', async () => {
+      mockedSeries = { '软件构架设计': [] };
+      process.env.NODE_ENV = 'production';
+      const { generateStaticParams } = await import('../../src/app/series/[slug]/page');
+      const params = await generateStaticParams();
+      expect(params).toContainEqual({ slug: '软件构架设计' });
+      expect(params).not.toContainEqual({ slug: '%E8%BD%AF%E4%BB%B6%E6%9E%84%E6%9E%B6%E8%AE%BE%E8%AE%A1' });
+    });
+
     test('series/[slug]/page/[page] returns [{ slug: "_", page: "2" }]', async () => {
       const { generateStaticParams } = await import('../../src/app/series/[slug]/page/[page]/page');
       const params = await generateStaticParams();
       expect(params).toEqual([{ slug: '_', page: '2' }]);
     });
+
+    test('series/[slug]/page/[page] includes encoded Unicode slug in non-production', async () => {
+      mockedSeries = { '软件构架设计': Array.from({ length: 6 }, (_, i) => ({ slug: `p${i + 1}` })) };
+      process.env.NODE_ENV = 'development';
+      const { generateStaticParams } = await import('../../src/app/series/[slug]/page/[page]/page');
+      const params = await generateStaticParams();
+      expect(params).toContainEqual({ slug: '软件构架设计', page: '2' });
+      expect(params).toContainEqual({ slug: '%E8%BD%AF%E4%BB%B6%E6%9E%84%E6%9E%B6%E8%AE%BE%E8%AE%A1', page: '2' });
+    });
+
+    test('series/[slug]/page/[page] includes redirectFrom slug when series is renamed', async () => {
+      mockedSeries = { 'new-name': Array.from({ length: 6 }, (_, i) => ({ slug: `p${i + 1}` })) };
+      mockedSeriesData = { 'new-name': { redirectFrom: ['/series/old-name'], title: 'New Series' } };
+      const { generateStaticParams } = await import('../../src/app/series/[slug]/page/[page]/page');
+      const params = await generateStaticParams();
+      expect(params).toContainEqual({ slug: 'new-name', page: '2' });
+      expect(params).toContainEqual({ slug: 'old-name', page: '2' });
+    });
+
+    test('series/[slug]/page/[page] redirects old alias slugs to the canonical paginated path', async () => {
+      mockedSeries = { 'new-name': Array.from({ length: 6 }, (_, i) => ({ slug: `p${i + 1}` })) };
+      mockedSeriesData = { 'new-name': { redirectFrom: ['/series/old-name'], title: 'New Series' } };
+      const page = await import('../../src/app/series/[slug]/page/[page]/page');
+      await expect(page.default({
+        params: Promise.resolve({ slug: 'old-name', page: '2' }),
+      })).resolves.toBeDefined();
+    });
+
+    test('series routes match percent-encoded redirectFrom aliases after normalization', async () => {
+      mockedSeries = { '软件构架设计': Array.from({ length: 6 }, (_, i) => ({ slug: `p${i + 1}` })) };
+      mockedSeriesData = {
+        '软件构架设计': {
+          redirectFrom: ['/series/%E8%BD%AF%E4%BB%B6%E8%AE%BE%E8%AE%A1'],
+          title: '软件构架设计',
+        },
+      };
+
+      const seriesPage = await import('../../src/app/series/[slug]/page');
+      await expect(seriesPage.default({
+        params: Promise.resolve({ slug: '%E8%BD%AF%E4%BB%B6%E8%AE%BE%E8%AE%A1' }),
+      })).resolves.toBeDefined();
+
+      const paginatedPage = await import('../../src/app/series/[slug]/page/[page]/page');
+      await expect(paginatedPage.default({
+        params: Promise.resolve({ slug: '%E8%BD%AF%E4%BB%B6%E8%AE%BE%E8%AE%A1', page: '2' }),
+      })).resolves.toBeDefined();
+    });
+
+    test('series/[slug]/page/[page] throws when redirectFrom alias conflicts with an existing series slug', async () => {
+      mockedSeries = {
+        'existing-slug': Array.from({ length: 6 }, (_, i) => ({ slug: `a${i + 1}` })),
+        'new-name': Array.from({ length: 6 }, (_, i) => ({ slug: `b${i + 1}` })),
+      };
+      mockedSeriesData = {
+        'new-name': { redirectFrom: ['/series/existing-slug'], title: 'New Series' },
+      };
+      const { generateStaticParams } = await import('../../src/app/series/[slug]/page/[page]/page');
+      await expect(generateStaticParams()).rejects.toThrow(/conflicts with an existing series slug/i);
+    });
+
+    test('series/[slug]/page/[page] throws when two series claim the same redirectFrom alias', async () => {
+      mockedSeries = {
+        'first-series': Array.from({ length: 6 }, (_, i) => ({ slug: `a${i + 1}` })),
+        'second-series': Array.from({ length: 6 }, (_, i) => ({ slug: `b${i + 1}` })),
+      };
+      mockedSeriesData = {
+        'first-series': { redirectFrom: ['/series/old-name'], title: 'First' },
+        'second-series': { redirectFrom: ['/series/old-name'], title: 'Second' },
+      };
+      const { generateStaticParams } = await import('../../src/app/series/[slug]/page/[page]/page');
+      await expect(generateStaticParams()).rejects.toThrow(/claimed by both/i);
+    });
   });
 
   describe('posts routes', () => {
@@ -504,6 +595,26 @@ describe('generateStaticParams — placeholder when content is empty', () => {
       expect(params).toContainEqual({ slug: 'old-prefix', postSlug: encodeURIComponent('中文文章') });
     });
 
+    test('[slug]/[postSlug] includes encoded Unicode prefix variants in non-production', async () => {
+      mockedSeries = { '软件构架设计': [{ slug: 'architecture-post' }] };
+      process.env.NODE_ENV = 'development';
+      const { generateStaticParams } = await import('../../src/app/[slug]/[postSlug]/page');
+      const params = await generateStaticParams();
+      expect(params).toContainEqual({ slug: '软件构架设计', postSlug: 'architecture-post' });
+      expect(params).toContainEqual({ slug: encodeURIComponent('软件构架设计'), postSlug: 'architecture-post' });
+    });
+
+    test('[slug]/[postSlug] includes encoded Unicode prefix and postSlug variants together in non-production', async () => {
+      mockedSeries = { '软件构架设计': [{ slug: '中文文章' }] };
+      process.env.NODE_ENV = 'development';
+      const { generateStaticParams } = await import('../../src/app/[slug]/[postSlug]/page');
+      const params = await generateStaticParams();
+      expect(params).toContainEqual({ slug: '软件构架设计', postSlug: '中文文章' });
+      expect(params).toContainEqual({ slug: encodeURIComponent('软件构架设计'), postSlug: '中文文章' });
+      expect(params).toContainEqual({ slug: '软件构架设计', postSlug: encodeURIComponent('中文文章') });
+      expect(params).toContainEqual({ slug: encodeURIComponent('软件构架设计'), postSlug: encodeURIComponent('中文文章') });
+    });
+
     test('[slug]/[postSlug] does not include encoded Unicode postSlug variants in production', async () => {
       mockedPosts = [{ slug: 'my-post', redirectFrom: ['/old-prefix/中文文章'] }];
       process.env.NODE_ENV = 'production';
@@ -513,6 +624,35 @@ describe('generateStaticParams — placeholder when content is empty', () => {
       expect(params).not.toContainEqual({ slug: 'old-prefix', postSlug: encodeURIComponent('中文文章') });
     });
 
+    test('[slug]/[postSlug] page resolves encoded Unicode series prefix without notFound', async () => {
+      mockedSeries = { '软件构架设计': [{ slug: 'my-post' }] };
+      mockedSeriesData = { '软件构架设计': { title: '软件构架设计' } };
+      mockedPosts = [{
+        slug: 'my-post',
+        title: 'My Post',
+        excerpt: 'Excerpt',
+        date: '2026-01-01',
+        authors: ['Author'],
+        series: '软件构架设计',
+        redirectFrom: ['/软件构架设计/my-post'],
+        layout: 'post',
+        content: 'Body',
+        headings: [],
+        imageBaseSlug: 'posts',
+        category: 'Test',
+        tags: [],
+        readingTime: '1 min read',
+      }];
+
+      const page = await import('../../src/app/[slug]/[postSlug]/page');
+      await expect(page.default({
+        params: Promise.resolve({
+          slug: encodeURIComponent('软件构架设计'),
+          postSlug: 'my-post',
+        }),
+      })).resolves.toBeDefined();
+    });
+
     test('[slug]/page/[page]/page returns placeholder when no custom paths', async () => {
       const { generateStaticParams } = await import('../../src/app/[slug]/page/[page]/page');
       const params = await generateStaticParams();