Skip to content

A local-first multi-agent app development platform, built on PenguinHarness

6.4 KB
Raw Blame
/**
 * Content integrity: the sidebar (DOCS_NAV) and the content/ directory must agree —
 * every navigated slug has both zh and en files with a frontmatter title, and every
 * content file belongs to the navigation (an orphan file would be unreachable).
 * Also guards the links pages navigate each other and themselves with. Heading ids come
 * from the heading text, so two identical headings collide into one id (the TOC then
 * renders two entries pointing at the same place) and a "#..." link naming no heading
 * scrolls nowhere. An absolute "/..." link is handed to the router as a doc route, so a
 * target that is not a slug renders nothing at all — the way "/docs/goal-mode" did,
 * carrying the deployed base path that the router already supplies. A "/slug#anchor"
 * link carries both halves, and the anchor half is the one that rots quietly: a heading
 * renamed on the target page leaves the link working and the reader on the wrong part of
 * it. Each language links its own twin, since the headings are translated. The sidebar's
 * section labels are checked here too: `S.sections` is a Record, so a section id with no
 * label typechecks and renders an empty heading. Reads the files via fs so the check runs
 * under plain node (no Vite glob).
 */
import { readdirSync, readFileSync } from "node:fs";
import { join } from "node:path";
import { describe, expect, it } from "vitest";
import { DOCS_NAV, DOC_SLUGS, pagerFor } from "../src/lib/nav";
import { parseFrontmatter } from "../src/lib/frontmatter";
import { hashTargetId } from "../src/lib/hash";
import { en } from "../src/lib/strings-en";
import { zh } from "../src/lib/strings";
import { extractToc } from "../src/lib/toc";

const contentDir = join(__dirname, "..", "content");
const files = readdirSync(contentDir).filter((f) => f.endsWith(".md"));

/** In-page targets of Markdown links, i.e. "[label](#anchor)", resolved as the router does. */
function inPageAnchors(body: string): string[] {
  return [...body.matchAll(/\]\(#([^)\s]+)\)/g)].map((match) => hashTargetId(match[1]!));
}

/** Absolute doc links, i.e. "[label](/slug)" or "[label](/slug#anchor)", both halves resolved as the router does. */
function docLinks(body: string): Array<{ slug: string; anchor: string | null }> {
  return [...body.matchAll(/\]\((\/[^)\s]*)\)/g)].map((match) => {
    const [path, hash] = match[1]!.split("#");
    return {
      slug: path!.replace(/^\//, "").replace(/\/$/, ""),
      anchor: hash === undefined ? null : hashTargetId(hash),
    };
  });
}

/** Heading ids of every content file, by file name. */
const headingIds = new Map<string, Set<string>>(
  files.map((file) => {
    const { body } = parseFrontmatter(readFileSync(join(contentDir, file), "utf8"));
    return [file, new Set(extractToc(body).map((entry) => entry.id))];
  }),
);

describe("docs navigation / content integrity", () => {
  it("has unique slugs in DOCS_NAV", () => {
    expect(new Set(DOC_SLUGS).size).toBe(DOC_SLUGS.length);
    expect(DOCS_NAV.length).toBeGreaterThan(0);
  });

  it("paginates every page to real neighbours, and never to itself", () => {
    for (const slug of DOC_SLUGS) {
      const { prev, next } = pagerFor(slug);
      for (const [dir, target] of [
        ["prev", prev],
        ["next", next],
      ] as const) {
        if (target === null) continue;
        expect(DOC_SLUGS, `${slug} paginates ${dir} to a non-existent page`).toContain(target);
        expect(target, `${slug} paginates ${dir} to itself`).not.toBe(slug);
      }
    }
  });

  it("labels every navigation section in both dictionaries", () => {
    for (const { id } of DOCS_NAV) {
      expect(zh.sections[id], `missing zh label for the ${id} section`).toBeTruthy();
      expect(en.sections[id], `missing en label for the ${id} section`).toBeTruthy();
    }
  });

  it("provides zh and en files with a title for every navigated slug", () => {
    for (const slug of DOC_SLUGS) {
      for (const lang of ["zh", "en"] as const) {
        const name = `${slug}.${lang}.md`;
        expect(files, `missing content file ${name}`).toContain(name);
        const { meta, body } = parseFrontmatter(readFileSync(join(contentDir, name), "utf8"));
        expect(meta.title, `missing title in ${name}`).toBeTruthy();
        expect(body.length, `empty body in ${name}`).toBeGreaterThan(0);
      }
    }
  });

  it("has no content file outside the navigation", () => {
    for (const file of files) {
      const slug = /^(.+)\.(zh|en)\.md$/.exec(file)?.[1];
      expect(slug, `unparsable content file name ${file}`).toBeTruthy();
      expect(DOC_SLUGS, `orphan content file ${file}`).toContain(slug!);
    }
  });

  it("gives every heading on a page its own anchor", () => {
    for (const file of files) {
      const { body } = parseFrontmatter(readFileSync(join(contentDir, file), "utf8"));
      const ids = extractToc(body).map((entry) => entry.id);
      const duplicates = [...new Set(ids.filter((id, index) => ids.indexOf(id) !== index))];
      expect(duplicates, `colliding heading anchors in ${file}`).toEqual([]);
    }
  });

  it("resolves every in-page anchor link to a heading on the same page", () => {
    for (const file of files) {
      const { body } = parseFrontmatter(readFileSync(join(contentDir, file), "utf8"));
      const ids = headingIds.get(file)!;
      const dangling = inPageAnchors(body).filter((anchor) => !ids.has(anchor));
      expect(dangling, `dangling in-page anchors in ${file}`).toEqual([]);
    }
  });

  it("points every absolute doc link at a navigated slug", () => {
    for (const file of files) {
      const { body } = parseFrontmatter(readFileSync(join(contentDir, file), "utf8"));
      const dangling = docLinks(body)
        .map((link) => link.slug)
        .filter((slug) => !DOC_SLUGS.includes(slug));
      expect(dangling, `links to non-existent doc pages in ${file}`).toEqual([]);
    }
  });

  it("resolves every cross-page anchor to a heading of the target page in the same language", () => {
    for (const file of files) {
      const lang = /\.(zh|en)\.md$/.exec(file)![1]!;
      const { body } = parseFrontmatter(readFileSync(join(contentDir, file), "utf8"));
      const dangling = docLinks(body)
        .filter((link) => link.anchor !== null && DOC_SLUGS.includes(link.slug))
        .filter((link) => !headingIds.get(`${link.slug}.${lang}.md`)?.has(link.anchor!))
        .map((link) => `/${link.slug}#${link.anchor}`);
      expect(dangling, `dangling cross-page anchors in ${file}`).toEqual([]);
    }
  });
});