@jant/core 0.7.0 → 0.7.1

package/src/__tests__/export-feed-ids.test.ts

@@ -0,0 +1,184 @@
+/**
+ * An exported site's feeds keep the entry IDs Jant's feeds served.
+ *
+ * A feed reader recognises an entry it has already shown by its `<id>` alone.
+ * The Hugo page a post moves to has a different URL — a trailing slash
+ * always, and the slug where Jant used a custom path — so a feed that took
+ * `<id>` from the page URL would show every post again to every subscriber
+ * after a site moves to its export. This serves Jant's feed and builds the
+ * export with the real Hugo binary from the same database, and compares the
+ * IDs.
+ *
+ * Skips when `hugo` is not on PATH, like the other Hugo build tests.
+ */
+
+import { readFile, rm } from "node:fs/promises";
+import { join } from "node:path";
+import { Hono } from "hono";
+import { afterAll, describe, expect, it } from "vitest";
+import { createTestDatabase, DEFAULT_TEST_SITE_ID } from "./helpers/db.js";
+import { makeSiteConfig } from "./helpers/export-fixtures.js";
+import { buildHugoSite, hugoAvailable } from "./helpers/hugo-site.js";
+import { resolveConfig } from "../lib/resolve-config.js";
+import { latestRoutes } from "../routes/pages/latest.js";
+import { createCollectionService } from "../services/collection.js";
+import { createExportService } from "../services/export.js";
+import { createMediaService } from "../services/media.js";
+import { createPathService } from "../services/path.js";
+import { createPostService } from "../services/post.js";
+import { createSettingsService } from "../services/settings.js";
+import type { Database } from "../db/index.js";
+import type { Bindings } from "../types.js";
+import type { AppVariables } from "../types/app-context.js";
+
+type Env = { Bindings: Bindings; Variables: AppVariables };
+
+const ORIGIN = "https://example.com";
+const CUSTOM_PATH = "/blog/links/2024-06-09-4";
+const CUSTOM_SLUG = "blog-links-2024-06-09-4";
+const at = (iso: string) => Math.floor(Date.parse(iso) / 1000);
+
+interface Entry {
+  id: string;
+  alternate: string;
+}
+
+/** Each entry's `<id>` and `<link rel="alternate">`, in document order. */
+function readEntries(xml: string): Entry[] {
+  return [...xml.matchAll(/<entry>([\s\S]*?)<\/entry>/g)].map(([, body]) => ({
+    id: body?.match(/<id>([^<]*)<\/id>/)?.[1] ?? "",
+    alternate:
+      body?.match(/<link href="([^"]*)" rel="alternate"\/>/)?.[1] ?? "",
+  }));
+}
+
+const ids = (entries: Entry[]) => entries.map((entry) => entry.id).sort();
+
+describe.skipIf(!hugoAvailable)("feed entry IDs on an exported site", () => {
+  const siteDirs: string[] = [];
+
+  afterAll(async () => {
+    for (const dir of siteDirs) await rm(dir, { recursive: true, force: true });
+  });
+
+  it.each([
+    { where: "at the domain root", prefix: "" },
+    { where: "under a site path prefix", prefix: "/journal" },
+  ])(
+    "match what Jant's feed served, $where",
+    async ({ prefix }) => {
+      const { db: testDb } = createTestDatabase();
+      const db = testDb as unknown as Database;
+      const siteId = DEFAULT_TEST_SITE_ID;
+      const paths = createPathService(db, siteId);
+      const posts = createPostService(db, { slugIdLength: 5 }, siteId, paths);
+      const collections = createCollectionService(db, siteId, paths);
+      const media = createMediaService(db, siteId);
+      const settings = createSettingsService(db, siteId);
+
+      // Served at its random slug, which is what an untitled note gets.
+      const plain = await posts.create({
+        format: "note",
+        bodyMarkdown: "A plain note.",
+        status: "published",
+        publishedAt: at("2024-06-01T00:00:00Z"),
+      });
+      // Served at a custom path, which its entry is named by. Its slug is
+      // where the Hugo page goes.
+      const custom = await posts.create({
+        format: "link",
+        slug: CUSTOM_SLUG,
+        title: "A link",
+        url: "https://other.example/article",
+        status: "published",
+        publishedAt: at("2024-06-09T00:00:00Z"),
+      });
+      await paths.create({
+        path: CUSTOM_PATH,
+        kind: "alias",
+        postId: custom.id,
+      });
+
+      const env = {
+        SITE_ORIGIN: ORIGIN,
+        SITE_PATH_PREFIX: prefix,
+        RSS_PUBLISH_DELAY_SECONDS: 0,
+      } as Bindings;
+      const appConfig = resolveConfig(env, await settings.getAll());
+      const app = new Hono<Env>();
+      app.use("*", async (c, next) => {
+        c.env = env;
+        c.set("services", {
+          posts,
+          paths,
+          media,
+          settings,
+        } as unknown as AppVariables["services"]);
+        c.set("appConfig", appConfig);
+        c.set("i18n", {
+          _(value: string | { message?: string }) {
+            return typeof value === "string" ? value : (value.message ?? "");
+          },
+        } as AppVariables["i18n"]);
+        await next();
+      });
+      app.route("/latest", latestRoutes);
+      const served = readEntries(
+        await (await app.request("/latest/feed")).text(),
+      );
+
+      const siteDir = await buildHugoSite(
+        await createExportService(
+          { posts, paths, collections, media },
+          makeSiteConfig({
+            siteUrl: appConfig.siteUrl,
+            sitePathPrefix: appConfig.sitePathPrefix,
+          }),
+          { storage: null, bundleMedia: false },
+        ).generateHugoFiles(),
+      );
+      siteDirs.push(siteDir);
+      const readFeed = async (path: string) =>
+        readEntries(await readFile(join(siteDir, "public", path), "utf8"));
+      const exportedLatest = await readFeed("index.xml");
+      const exportedArchive = await readFeed("archive/index.xml");
+
+      // What Jant serves: the random slug, and the custom path in place of
+      // the slug, neither with a trailing slash.
+      const base = `${ORIGIN}${prefix}`;
+      expect(ids(served)).toEqual(
+        [`${base}/${plain.slug}`, `${base}${CUSTOM_PATH}`].sort(),
+      );
+
+      expect(ids(exportedLatest)).toEqual(ids(served));
+      expect(ids(exportedArchive)).toEqual(ids(served));
+
+      // The entry still links to the page the post now lives on, not to the
+      // alias page that redirects there.
+      const exportedCustom = exportedLatest.find(
+        (entry) => entry.id === `${base}${CUSTOM_PATH}`,
+      );
+      expect(exportedCustom?.alternate).toBe("https://other.example/article");
+      const exportedFeed = await readFile(
+        join(siteDir, "public", "index.xml"),
+        "utf8",
+      );
+      expect(exportedFeed).toContain(
+        `<link href="${base}/${CUSTOM_SLUG}/" rel="related"/>`,
+      );
+      expect(
+        exportedLatest.find((entry) => entry.id === `${base}/${plain.slug}`)
+          ?.alternate,
+      ).toBe(`${base}/${plain.slug}/`);
+      // The ID still resolves: the custom path is an alias page that sends
+      // its visitor on to the post.
+      expect(
+        await readFile(
+          join(siteDir, "public", CUSTOM_PATH, "index.html"),
+          "utf8",
+        ),
+      ).toContain(`${base}/${CUSTOM_SLUG}/`);
+    },
+    60_000,
+  );
+});

package/src/__tests__/export-feed-order.test.ts

@@ -0,0 +1,294 @@
+/**
+ * An exported site lists Latest and Featured the way Jant does.
+ *
+ * The theme's `latest-members` and `featured-members` partials restate the
+ * order Jant's home page, `/latest/feed`, Featured page, and `/featured/feed`
+ * read from the database: pins first on the home page only, Thread activity
+ * (which a reply moves and a quiet reply doesn't), the newest featured post in
+ * a Thread, and the root ID when times tie. This builds the export with the
+ * real Hugo binary and compares every page, page by page, and both feeds with
+ * what Jant's services return.
+ *
+ * Skips when `hugo` is not on PATH, like the other Hugo build tests.
+ */
+
+import { rm } from "node:fs/promises";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { createTestDatabase, DEFAULT_TEST_SITE_ID } from "./helpers/db.js";
+import { makeSiteConfig } from "./helpers/export-fixtures.js";
+import {
+  buildHugoSite,
+  hugoAvailable,
+  readFeedSlugs,
+  readRootSlugsByPage,
+} from "./helpers/hugo-site.js";
+import { createCollectionService } from "../services/collection.js";
+import { createExportService } from "../services/export.js";
+import { createMediaService } from "../services/media.js";
+import { createPathService } from "../services/path.js";
+import { createPostService } from "../services/post.js";
+import {
+  featuredFeedSelection,
+  latestFeedSelection,
+} from "../lib/feed-policy.js";
+import type { Database } from "../db/index.js";
+import type { CreatePost } from "../types/operations.js";
+
+const SITE_URL = "https://example.com";
+const PAGE_SIZE = 4;
+const FEED_LIMIT = 6;
+const at = (iso: string) => Math.floor(Date.parse(iso) / 1000);
+/** No RSS delay: the static site has none to apply. */
+const NO_DELAY = at("2100-01-01T00:00:00Z");
+
+const chunk = (list: string[], size: number) =>
+  Array.from({ length: Math.ceil(list.length / size) }, (_, index) =>
+    list.slice(index * size, index * size + size),
+  );
+
+describe.skipIf(!hugoAvailable)(
+  "Latest and Featured on an exported site",
+  () => {
+    let siteDir: string;
+    const roots = new Set<string>();
+    const expected: Record<string, string[]> = {};
+    const built: Record<string, string[]> = {};
+    const expectedPages: Record<string, string[][]> = {};
+    const builtPages: Record<string, string[][]> = {};
+
+    beforeAll(async () => {
+      const { db: testDb } = createTestDatabase();
+      const db = testDb as unknown as Database;
+      const siteId = DEFAULT_TEST_SITE_ID;
+      const paths = createPathService(db, siteId);
+      const posts = createPostService(db, { slugIdLength: 5 }, siteId);
+      const collections = createCollectionService(db, siteId, paths);
+      const media = createMediaService(db, siteId);
+
+      const slugById = new Map<string, string>();
+      async function post(slug: string, data: Omit<CreatePost, "slug">) {
+        const created = await posts.create({
+          slug,
+          format: "note",
+          bodyMarkdown: `Body of ${slug}.`,
+          status: "published",
+          ...data,
+          createdAt: data.createdAt ?? data.publishedAt,
+        });
+        slugById.set(created.id, slug);
+        if (!data.replyToId) roots.add(slug);
+        return created;
+      }
+      const reply = (
+        root: { id: string },
+        slug: string,
+        data: Omit<CreatePost, "slug" | "replyToId" | "format">,
+      ) => post(slug, { format: "note", replyToId: root.id, ...data });
+
+      // Older posts, so the feeds and pages run past their limits.
+      for (const [index, month] of ["02", "03", "04", "05"].entries()) {
+        await post(`k${index}-filler`, {
+          format: "note",
+          publishedAt: at(`2024-${month}-01T00:00:00Z`),
+        });
+      }
+
+      // A reply brings an old Thread back to the top of Latest.
+      const bumped = await post("a-bumped-by-reply", {
+        format: "note",
+        publishedAt: at("2025-01-01T00:00:00Z"),
+      });
+      await reply(bumped, "a-reply", {
+        publishedAt: at("2025-08-01T00:00:00Z"),
+      });
+
+      // A quiet reply doesn't.
+      const quiet = await post("b-quiet-reply", {
+        format: "note",
+        publishedAt: at("2025-02-01T00:00:00Z"),
+      });
+      await reply(quiet, "b-reply", {
+        publishedAt: at("2025-09-01T00:00:00Z"),
+        quietReply: true,
+      });
+
+      await post("c-featured", {
+        format: "note",
+        publishedAt: at("2025-03-01T00:00:00Z"),
+        featuredAt: at("2025-03-02T00:00:00Z"),
+      });
+
+      // Published in the same second, and both featured: the ID decides.
+      await post("d-tied", {
+        format: "note",
+        publishedAt: at("2025-04-01T12:00:00Z"),
+        featuredAt: at("2025-04-02T00:00:00Z"),
+      });
+      await post("e-tied", {
+        format: "note",
+        publishedAt: at("2025-04-01T12:00:00Z"),
+        featuredAt: at("2025-04-02T00:00:00Z"),
+      });
+
+      // Featured, but Hidden from Latest: on Featured, not on Latest.
+      await post("f-hidden-featured", {
+        format: "note",
+        visibility: "latest_hidden",
+        publishedAt: at("2025-05-01T00:00:00Z"),
+        featuredAt: at("2025-05-02T00:00:00Z"),
+      });
+
+      // An old root whose featured post is a recent reply.
+      const replyFeatured = await post("g-reply-featured", {
+        format: "note",
+        publishedAt: at("2024-01-01T00:00:00Z"),
+      });
+      await reply(replyFeatured, "g-featured-reply", {
+        publishedAt: at("2025-06-15T00:00:00Z"),
+        featuredAt: at("2025-06-16T00:00:00Z"),
+        quietReply: true,
+      });
+
+      // Pinned: first on the home page, most recent pin first; not in the feed.
+      await post("p-pinned-early", {
+        format: "note",
+        publishedAt: at("2024-06-01T00:00:00Z"),
+        pinnedAt: at("2025-06-01T00:00:00Z"),
+      });
+      await post("q-pinned-late", {
+        format: "note",
+        publishedAt: at("2024-07-01T00:00:00Z"),
+        pinnedAt: at("2025-07-01T00:00:00Z"),
+      });
+      // Pinned but Hidden from Latest: not on the home page at all.
+      await post("r-hidden-pinned", {
+        format: "note",
+        visibility: "latest_hidden",
+        publishedAt: at("2024-08-01T00:00:00Z"),
+        pinnedAt: at("2025-07-15T00:00:00Z"),
+      });
+
+      // On none of them.
+      await post("s-private-featured", {
+        format: "note",
+        visibility: "private",
+        publishedAt: at("2025-05-15T00:00:00Z"),
+        featuredAt: at("2025-05-16T00:00:00Z"),
+      });
+      await post("t-draft", { format: "note", status: "draft" });
+
+      const slugs = (ids: string[]) =>
+        ids.map((id) => slugById.get(id) as string);
+
+      // The home page, as `assembleTimeline` asks for it.
+      const home = await posts.list({
+        status: "published",
+        excludeReplies: true,
+        excludeLatestHidden: true,
+        excludePrivate: true,
+        limit: 1000,
+      });
+      expected.home = slugs(home.map((item) => item.id));
+      expectedPages.home = chunk(expected.home, PAGE_SIZE);
+
+      // `/latest/feed`, as `buildLatestFeedData` asks for it.
+      const latestFeed = await posts.list({
+        ...latestFeedSelection({ publishedBefore: NO_DELAY }),
+        ignorePinnedSort: true,
+        limit: FEED_LIMIT,
+      });
+      expected.latestFeed = slugs(latestFeed.map((item) => item.id));
+
+      // The Featured page, as `assembleFeaturedTimeline` asks for it.
+      expected.featured = slugs(
+        await posts.listFeaturedThreadRootIds({
+          status: "published",
+          excludePrivate: true,
+        }),
+      );
+      expectedPages.featured = chunk(expected.featured, PAGE_SIZE);
+
+      // `/featured/feed`, as `buildFeaturedFeedData` asks for it.
+      expected.featuredFeed = slugs(
+        await posts.listFeaturedThreadRootIds({
+          ...featuredFeedSelection({ publishedBefore: NO_DELAY }),
+          limit: FEED_LIMIT,
+        }),
+      );
+
+      siteDir = await buildHugoSite(
+        await createExportService(
+          { posts, paths, collections, media },
+          makeSiteConfig({
+            siteUrl: SITE_URL,
+            pageSize: PAGE_SIZE,
+            rssFeedLimit: FEED_LIMIT,
+          }),
+          { storage: null, bundleMedia: false },
+        ).generateHugoFiles(),
+      );
+      builtPages.home = await readRootSlugsByPage(siteDir, "", roots);
+      builtPages.featured = await readRootSlugsByPage(
+        siteDir,
+        "featured",
+        roots,
+      );
+      built.latestFeed = await readFeedSlugs(siteDir, "", SITE_URL);
+      built.featuredFeed = await readFeedSlugs(siteDir, "featured", SITE_URL);
+    }, 60_000);
+
+    afterAll(async () => {
+      if (siteDir) await rm(siteDir, { recursive: true, force: true });
+    });
+
+    it("lists the home page as Jant does, page by page", () => {
+      expect(builtPages.home).toEqual(expectedPages.home);
+    });
+
+    it("carries Jant's Latest feed", () => {
+      expect(built.latestFeed).toEqual(expected.latestFeed);
+    });
+
+    it("lists the Featured page as Jant does, page by page", () => {
+      expect(builtPages.featured).toEqual(expectedPages.featured);
+    });
+
+    it("carries Jant's Featured feed", () => {
+      expect(built.featuredFeed).toEqual(expected.featuredFeed);
+    });
+
+    // Equal lists prove nothing if the fixture can't tell the rules apart.
+    it("runs on a fixture where each rule changes the order", () => {
+      // Pins lead the home page, most recent first; Hidden from Latest stays
+      // off it even when pinned.
+      expect(expected.home?.slice(0, 3)).toEqual([
+        "q-pinned-late",
+        "p-pinned-early",
+        "a-bumped-by-reply",
+      ]);
+      expect(expected.home).not.toContain("r-hidden-pinned");
+      expect(expected.home).not.toContain("f-hidden-featured");
+      // A reply moves its Thread up; a quiet one doesn't. The feed ignores
+      // pins and stops at its limit.
+      expect(expected.latestFeed).toEqual([
+        "a-bumped-by-reply",
+        "e-tied",
+        "d-tied",
+        "c-featured",
+        "b-quiet-reply",
+        "q-pinned-late",
+      ]);
+      // A featured reply dates its Thread; same-second Threads go by ID;
+      // Hidden from Latest is on Featured, private isn't.
+      expect(expected.featured).toEqual([
+        "g-reply-featured",
+        "f-hidden-featured",
+        "e-tied",
+        "d-tied",
+        "c-featured",
+      ]);
+      // Enough roots to run past a page and the feed limit.
+      expect(expectedPages.home?.length).toBeGreaterThan(2);
+    });
+  },
+);

package/src/__tests__/export-hugo-build.test.ts

@@ -90,6 +90,7 @@ function buildFixtureServices(): ServicesArg {
           ["pst_root", "hello-world"],
           ["pst_reply", "hello-reply"],
         ]),
+      listStandalonePaths: async () => [],
       getPostAliases: async () => new Map(),
       getCollectionSlugMap: async () => new Map([["col-1", "ideas"]]),
     },
@@ -325,6 +326,7 @@ describe("Hugo smoke build", () => {
             ["pst_long", "blue-long"],
             ["pst_short", "blue-short"],
           ]),
+        listStandalonePaths: async () => [],
         getPostAliases: async () => new Map(),
         getCollectionSlugMap: async () => new Map(),
       },
@@ -387,6 +389,133 @@ describe("Hugo smoke build", () => {
     }
   }, 60_000);
 
+  it("never emits an alias page that redirects to nowhere", async () => {
+    if (!hugoOk) {
+      console.log("hugo binary not found on PATH — skipping hugo build test");
+      return;
+    }
+
+    const root = makePost({
+      id: "pst_root",
+      slug: "hello-world",
+      title: "Hello World",
+      threadId: "pst_root",
+    });
+    const draft = makePost({
+      id: "pst_draft",
+      slug: "secret-plan",
+      title: "Secret Plan",
+      threadId: "pst_draft",
+      status: "draft",
+    });
+    const services = {
+      posts: { list: async () => [root, draft] },
+      paths: {
+        getPostSlugMap: async () =>
+          new Map([
+            ["pst_root", "hello-world"],
+            ["pst_draft", "secret-plan"],
+          ]),
+        listStandalonePaths: async () => [],
+        getPostAliases: async () =>
+          new Map([
+            ["pst_root", ["/blog/hello-world/"]],
+            ["pst_draft", ["/blog/nixos-setup/"]],
+          ]),
+        getCollectionSlugMap: async () => new Map(),
+      },
+      collections: {
+        list: async () => [],
+        listDirectoryData: async () => ({
+          collections: [],
+          items: [],
+          directoryItems: [],
+        }),
+        getCollectionsByPostIds: async () => new Map(),
+        getCollectionEntriesByThreadIds: async () => new Map(),
+      },
+      media: { getByPostIds: async () => new Map() },
+    } as unknown as ServicesArg;
+
+    const siteDir = await mkdtemp(join(tmpdir(), "jant-hugo-alias-"));
+    try {
+      const files = await createExportService(
+        services,
+        makeSiteConfig(),
+      ).generateHugoFiles();
+      for (const file of files) {
+        const target = join(siteDir, file.path);
+        await mkdir(dirname(target), { recursive: true });
+        const data =
+          typeof file.content === "string"
+            ? new TextEncoder().encode(file.content)
+            : file.content;
+        await writeFile(target, data);
+      }
+      // A page whose `aliases:` were written by hand rather than by Jant —
+      // editing content on GitHub is a supported workflow, so the theme
+      // cannot assume every alias came from the exporter.
+      await mkdir(join(siteDir, "content/hand-written"), { recursive: true });
+      await writeFile(
+        join(siteDir, "content/hand-written/_index.md"),
+        [
+          "---",
+          'title: "Hand written"',
+          'date: "2026-03-09T00:00:00.000Z"',
+          'slug: "hand-written"',
+          'type: "post"',
+          "draft: true",
+          "aliases:",
+          '  - "/blog/hand-written/"',
+          "---",
+          "",
+          "Body.",
+          "",
+        ].join("\n"),
+      );
+
+      const { code, stdout, stderr } = await runHugo(siteDir);
+      if (code !== 0) {
+        console.error("hugo stdout:", stdout);
+        console.error("hugo stderr:", stderr);
+      }
+      expect(code).toBe(0);
+
+      // The published thread's alias redirects where it always did.
+      const liveAlias = await readFile(
+        join(siteDir, "public/blog/hello-world/index.html"),
+        "utf-8",
+      );
+      expect(liveAlias).toContain(
+        'content="0; url=https://example.com/hello-world/"',
+      );
+      // `jsonify` alone is escaped into a JS string by Hugo's contextual
+      // escaping, which leaves the historical-root-alias branch comparing
+      // single characters and never taking. `safeJS` keeps it an array.
+      expect(liveAlias).toContain('["/blog/hello-world/"]');
+      expect(liveAlias).not.toContain("'[\"/blog/hello-world/\"]'");
+
+      // The unpublished thread gets no alias page at all: the exporter left
+      // `aliases:` off a root Hugo was never going to build.
+      expect(
+        await fileExists(join(siteDir, "public/blog/nixos-setup/index.html")),
+      ).toBe(false);
+
+      // The hand-written one does get a page, and it has to be inert. An
+      // empty `url=` is read as "reload this page", so the alias would
+      // refresh itself forever.
+      const orphanAlias = await readFile(
+        join(siteDir, "public/blog/hand-written/index.html"),
+        "utf-8",
+      );
+      expect(orphanAlias).not.toContain("http-equiv");
+      expect(orphanAlias).toContain("This page is not available");
+      expect(orphanAlias).toContain('content="noindex,nofollow"');
+    } finally {
+      await rm(siteDir, { recursive: true, force: true });
+    }
+  }, 60_000);
+
   it("folds a long thread's preview the way the site does", async () => {
     if (!hugoOk) {
       console.log("hugo binary not found on PATH — skipping hugo build test");
@@ -432,6 +561,7 @@ describe("Hugo smoke build", () => {
               `fold-${word}`,
             ]),
           ]),
+        listStandalonePaths: async () => [],
         getPostAliases: async () => new Map(),
         getCollectionSlugMap: async () => new Map(),
       },