@gusnips/vite 0.1.0

package/src/sitemap.test.ts

@@ -0,0 +1,124 @@
+import { describe, expect, it } from "vitest";
+import {
+  ogImagePath,
+  pageFile,
+  pageSlug,
+  robotsTxt,
+  siteOrigin,
+  sitemapFor,
+  sitemapXml,
+} from "./sitemap.ts";
+
+describe("pageFile", () => {
+  // Invariant 5: Cloudflare Pages serves `pricing/index.html` at `/pricing/` and answers
+  // `/pricing` with a 308 — so every address the canonical and the sitemap advertise would be
+  // a redirect rather than a page.
+  it("is flat, never a directory index", () => {
+    expect(pageFile("/pricing")).toBe("pricing.html");
+    expect(pageFile("/pricing")).not.toBe("pricing/index.html");
+  });
+
+  it("names the front page index.html", () => {
+    expect(pageFile("/")).toBe("index.html");
+  });
+
+  it("keeps a nested route's folders", () => {
+    expect(pageFile("/guides/errors")).toBe("guides/errors.html");
+  });
+
+  it("ignores a trailing slash rather than writing `pricing/.html`", () => {
+    expect(pageFile("/pricing/")).toBe("pricing.html");
+  });
+});
+
+describe("pageSlug", () => {
+  it("flattens a path into one name a card and a catalog can both use", () => {
+    expect(pageSlug("/")).toBe("home");
+    expect(pageSlug("/pricing")).toBe("pricing");
+    expect(pageSlug("/guides/errors")).toBe("guides-errors");
+    expect(ogImagePath("/pricing")).toBe("/og/pricing.png");
+  });
+});
+
+describe("siteOrigin", () => {
+  it("drops the trailing slash the caller's path would double", () => {
+    expect(siteOrigin("https://acme.com/")).toBe("https://acme.com");
+    expect(`${siteOrigin("https://acme.com/")}/pricing`).toBe("https://acme.com/pricing");
+  });
+
+  // `VITE_SITE_URL=acme.com` looks right in a .env and turns every canonical on the site into
+  // a relative URL. That is a bad build, not a bad page.
+  it("refuses a value with no scheme", () => {
+    expect(() => siteOrigin("acme.com")).toThrow(/absolute origin/);
+  });
+});
+
+describe("sitemapXml", () => {
+  it("carries each entry's own alternates, so a crawler that never reads the head has them", () => {
+    const xml = sitemapXml([
+      {
+        loc: "https://acme.com/pricing",
+        changefreq: "weekly",
+        priority: "0.9",
+        lastmod: "2026-09-07",
+        alternates: [{ hreflang: "pt-BR", href: "https://acme.com/pt/pricing" }],
+      },
+    ]);
+    expect(xml).toContain('xmlns:xhtml="http://www.w3.org/1999/xhtml"');
+    expect(xml).toContain("<loc>https://acme.com/pricing</loc>");
+    expect(xml).toContain('<xhtml:link rel="alternate" hreflang="pt-BR"');
+    expect(xml).toContain("<lastmod>2026-09-07</lastmod>");
+  });
+
+  it("leaves lastmod out when there is none to state", () => {
+    const xml = sitemapXml([{ loc: "https://acme.com/", changefreq: "weekly", priority: "1.0" }]);
+    expect(xml).not.toContain("lastmod");
+  });
+
+  // A bare `&` is not valid XML, and an invalid sitemap is rejected whole rather than per entry.
+  it("escapes an address that carries a query string", () => {
+    const xml = sitemapXml([
+      { loc: "https://acme.com/s?a=1&b=2", changefreq: "daily", priority: "0.5" },
+    ]);
+    expect(xml).toContain("<loc>https://acme.com/s?a=1&amp;b=2</loc>");
+  });
+
+  it("prints a computed priority to one decimal", () => {
+    const xml = sitemapFor("https://acme.com/", [
+      { path: "/pricing", priority: 0.1 + 0.2, changeFrequency: "weekly" },
+    ]);
+    expect(xml).toContain("<priority>0.3</priority>");
+    expect(xml).toContain("<loc>https://acme.com/pricing</loc>");
+  });
+});
+
+describe("robotsTxt", () => {
+  // A crawler reads only the robots.txt at the origin ROOT, so an app served from a
+  // subdirectory cannot ship its own — this one file has to name every sitemap on the origin,
+  // or nothing ever finds the second one.
+  it("lists every sitemap on the origin, on the origin", () => {
+    const txt = robotsTxt({
+      origin: "https://acme.com/",
+      sitemaps: ["/sitemap.xml", "/docs/sitemap.xml"],
+    });
+    expect(txt).toContain("Sitemap: https://acme.com/sitemap.xml");
+    expect(txt).toContain("Sitemap: https://acme.com/docs/sitemap.xml");
+  });
+
+  // The bug this shape prevents: a donor's static robots.txt and its build's fallback name
+  // different domains, and neither is checked against the other.
+  it("cannot name a host it is not served from", () => {
+    const txt = robotsTxt({ origin: "https://acme.com", sitemaps: ["/sitemap.xml"] });
+    expect(txt.match(/https:\/\//g)).toHaveLength(1);
+  });
+
+  it("keeps a private path out of every index", () => {
+    const txt = robotsTxt({
+      origin: "https://acme.com",
+      sitemaps: ["/sitemap.xml"],
+      disallow: ["/opt-out/"],
+    });
+    expect(txt).toContain("Disallow: /opt-out/");
+    expect(txt.startsWith("User-agent: *\nAllow: /\n")).toBe(true);
+  });
+});

package/src/sitemap.ts

@@ -0,0 +1,159 @@
+/**
+ * The three build outputs that are addresses rather than pages: where a rendered page lands,
+ * `sitemap.xml`, and `robots.txt`.
+ *
+ * Pure string work, like `head.ts` — no `node:` import, so every rule here is unit-testable.
+ */
+import { escapeAttr } from "./escape.ts";
+// Type-only, so this file carries no runtime dependency on the head baker: a sitemap alternate
+// and an `hreflang` link are the same claim, stated in two places a crawler reads separately.
+import type { Alternate } from "./head.ts";
+
+/**
+ * Where a rendered page lands.
+ *
+ * FLAT (`pricing.html`), not directory-style (`pricing/index.html`). Cloudflare Pages serves
+ * the directory form at `/pricing/` and answers `/pricing` with a 308 to it — so every address
+ * the app advertises in its canonical and its sitemap would be a redirect rather than a page.
+ * A flat file is served at `/pricing` AND `/pricing/`, 200 either way.
+ *
+ * A nested route keeps its folders: `/guides/errors` → `guides/errors.html`.
+ */
+export function pageFile(routePath: string): string {
+  const trimmed = routePath.replace(/^\/+/, "").replace(/\/+$/, "");
+  return trimmed === "" ? "index.html" : `${trimmed}.html`;
+}
+
+/**
+ * The origin every canonical, share URL and sitemap entry is built on.
+ *
+ * The trailing slash is dropped because the caller appends a path that starts with one, and
+ * `https://example.com//pricing` is a different address to every crawler that reads it. The
+ * scheme is demanded because the value normally comes from an env var: `VITE_SITE_URL=acme.com`
+ * looks right in a `.env`, and it silently turns every canonical on the site into a relative
+ * URL. That is a bad build, not a bad page, so it fails here.
+ */
+export function siteOrigin(url: string): string {
+  if (!/^https?:\/\/[^/]+/.test(url))
+    throw new Error(
+      `prerender: "${url}" is not an absolute origin — it needs a scheme, as in https://example.com`,
+    );
+  return url.replace(/\/+$/, "");
+}
+
+/**
+ * The three things about a public page that do not translate: where it is, how often it
+ * changes, and how it ranks against its siblings.
+ *
+ * A product's registry extends this with its own copy fields — one donor names an i18n key per
+ * page, another keys its locale catalogs by `pageSlug` and stores no copy here at all. Where
+ * the copy lives is the product's call. These three are what a sitemap needs from every one of
+ * them, and the registry is the single source the prerender, the sitemap and the share cards
+ * all walk, so a page can never be in one and missing from another.
+ */
+export interface PublicPage {
+  path: string;
+  /** Relative crawl priority, 0.0–1.0. */
+  priority: number;
+  changeFrequency: "always" | "hourly" | "daily" | "weekly" | "monthly" | "yearly" | "never";
+}
+
+/** URL slug for a page path (`/pricing` → `pricing`, `/` → `home`), used to name its share
+ *  card and to key a locale catalog's copy. */
+export function pageSlug(path: string): string {
+  const trimmed = path.replace(/^\/+|\/+$/g, "");
+  return trimmed === "" ? "home" : trimmed.replaceAll("/", "-");
+}
+
+/** Public path of a page's generated share card (`/pricing` → `/og/pricing.png`). */
+export function ogImagePath(path: string): string {
+  return `/og/${pageSlug(path)}.png`;
+}
+
+export interface SitemapEntry {
+  loc: string;
+  changefreq: string;
+  /** Already formatted — an app ranks its own pages, and that rule does not belong here. */
+  priority: string;
+  /** `YYYY-MM-DD`. The one hint in a sitemap Google actually reads. One date for the whole
+   *  build is the honest answer: these pages ship together. */
+  lastmod?: string;
+  /** The same reciprocal set the page's `<head>` carries. Stated twice on purpose: a crawler
+   *  that reaches an address through the sitemap has not read the head yet. */
+  alternates?: readonly Alternate[];
+}
+
+/** `sitemap.xml`, from whichever registry the caller walks. */
+export function sitemapXml(entries: readonly SitemapEntry[]): string {
+  const urls = entries
+    .map((entry) => {
+      const links = (entry.alternates ?? []).map(
+        (alt) =>
+          `    <xhtml:link rel="alternate" hreflang="${escapeAttr(alt.hreflang)}" href="${escapeAttr(alt.href)}" />\n`,
+      );
+      return (
+        `  <url>\n` +
+        // Escaped like every other URL here: a query string with an `&` in it is not valid XML,
+        // and an invalid sitemap is rejected whole rather than per entry.
+        `    <loc>${escapeAttr(entry.loc)}</loc>\n` +
+        links.join("") +
+        (entry.lastmod ? `    <lastmod>${entry.lastmod}</lastmod>\n` : "") +
+        `    <changefreq>${entry.changefreq}</changefreq>\n` +
+        `    <priority>${entry.priority}</priority>\n` +
+        `  </url>`
+      );
+    })
+    .join("\n");
+  return (
+    `<?xml version="1.0" encoding="UTF-8"?>\n` +
+    `<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"` +
+    ` xmlns:xhtml="http://www.w3.org/1999/xhtml">\n${urls}\n</urlset>\n`
+  );
+}
+
+/**
+ * `sitemap.xml` for a single-language site, straight from the registry — the common case, and
+ * the reason a registry exists: the sitemap can never drift from the routes the app serves.
+ *
+ * A localized site walks its own locales and calls {@link sitemapXml}, because only it knows
+ * how an address carries a language.
+ */
+export function sitemapFor(origin: string, pages: readonly PublicPage[], lastmod?: string): string {
+  const root = siteOrigin(origin);
+  return sitemapXml(
+    pages.map((page) => ({
+      loc: `${root}${page.path}`,
+      changefreq: page.changeFrequency,
+      // One decimal, always. `<priority>` is a number a crawler compares, and floating-point
+      // noise from a computed rank would print as `0.7000000000000001`.
+      priority: page.priority.toFixed(1),
+      ...(lastmod !== undefined && { lastmod }),
+    })),
+  );
+}
+
+export interface RobotsOptions {
+  /** The origin this file is served from. Every sitemap path is resolved against it, so the
+   *  file can never advertise a host it is not on — a mistake one donor is still shipping,
+   *  where a static `robots.txt` and the build's fallback name different domains. */
+  origin: string;
+  /** Every sitemap on this ORIGIN, as paths (`/sitemap.xml`, `/docs/sitemap.xml`).
+   *
+   *  A crawler reads only the robots.txt at the origin root. An app served from a
+   *  subdirectory therefore cannot ship its own — the one file at the root has to list its
+   *  sitemap too, or nothing ever finds it. */
+  sitemaps: readonly string[];
+  /** Paths to keep out of every index. A page nobody should be able to find by searching —
+   *  a per-request status page, an unsubscribe link — belongs here AND in `noindex`. */
+  disallow?: readonly string[];
+}
+
+export function robotsTxt({ origin, sitemaps, disallow = [] }: RobotsOptions): string {
+  const root = siteOrigin(origin);
+  return (
+    `User-agent: *\nAllow: /\n` +
+    disallow.map((path) => `Disallow: ${path}\n`).join("") +
+    `\n` +
+    sitemaps.map((path) => `Sitemap: ${root}${path}\n`).join("")
+  );
+}