snappy-prerender 2.6.0 → 2.8.0

package/src/core/audit/links.js

@@ -0,0 +1,74 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { routeToFile } from '../output.js';
+import { matchesPattern, normaliseRoute } from '../routes.js';
+import { mapLimit } from '../scheduler.js';
+
+const LINK_CHECK_CONCURRENCY = 16;
+
+/**
+ * Audits every internal link the rendered pages emitted and warns about indexable pages
+ * no other page links to.
+ */
+export async function auditLinks({ report, config, outputDir, add }) {
+  const routes = new Set(report.routeDetails.map((detail) => detail.route));
+  const files = new Set(report.files.map((file) => file.file).filter(Boolean));
+  const cache = new Map();
+  const seenPairs = new Set();
+  let checkedLinks = 0;
+  const pending = [];
+
+  const exists = async (target) => {
+    if (cache.has(target)) return cache.get(target);
+    const result = await fs
+      .stat(path.join(outputDir, target))
+      .then((stats) => stats.isFile())
+      .catch(() => false);
+    cache.set(target, result);
+    return result;
+  };
+
+  for (const link of report.links) {
+    const key = `${link.from}|${link.to}`;
+    if (seenPairs.has(key)) continue;
+    seenPairs.add(key);
+    if (config.auditIgnoreLinks.some((pattern) => matchesPattern(link.to, pattern))) continue;
+    checkedLinks += 1;
+    const route = normaliseRoute(link.to);
+    if (routes.has(route)) continue;
+    const file = routeToFile(route, config);
+    if (files.has(file)) continue;
+    const asset = route.startsWith('/') ? route.slice(1) : route;
+    pending.push({ link, asset });
+  }
+
+  const targets = [...new Set(pending.map((entry) => entry.asset).filter(Boolean))];
+  const { results } = await mapLimit(targets, LINK_CHECK_CONCURRENCY, exists);
+  const existsSet = new Set(targets.filter((_target, index) => results[index] === true));
+  for (const { link, asset } of pending) {
+    if (asset && existsSet.has(asset)) continue;
+    add('error', 'broken-internal-link', `${link.from} links to missing ${link.to}`, {
+      from: link.from,
+      to: link.to,
+      reason: 'missing',
+    });
+  }
+  return { checked: checkedLinks };
+}
+
+/**
+ * Warns about indexable pages no rendered page links to. A link from a page outside the
+ * include list is legitimately absent, so this stays a warning.
+ */
+export function auditOrphans({ pages, report, add }) {
+  const linked = new Set();
+  for (const link of report.links) linked.add(normaliseRoute(link.to));
+  for (const page of pages) {
+    if (page.route === '/' || page.notFound || page.noindex) continue;
+    if (!linked.has(page.route)) {
+      add('warning', 'orphan-page', `${page.route} is not linked from another page`, {
+        route: page.route,
+      });
+    }
+  }
+}

package/src/core/audit/metadata.js

@@ -0,0 +1,197 @@
+import { toPublicPath } from '../routes.js';
+import { pagePath } from '../url-policy.js';
+
+/**
+ * Checks the metadata a crawler reads on every written page: titles, descriptions,
+ * canonicals, headings, build-origin leakage and duplicate values across routes.
+ */
+export function auditMetadata({ pages, config, add }) {
+  const titles = new Map();
+  const descriptions = new Map();
+  for (const page of pages) {
+    const meta = page.meta ?? {};
+    if (!meta.title) {
+      add('warning', 'missing-title', `no <title> on ${page.route}`, { route: page.route });
+    }
+    if (!meta.description) {
+      add('warning', 'missing-description', `no meta description on ${page.route}`, {
+        route: page.route,
+      });
+    }
+    if (!meta.canonical) {
+      add('warning', 'missing-canonical', `no canonical link on ${page.route}`, {
+        route: page.route,
+      });
+    }
+    if (meta.titleCount > 1) {
+      add('error', 'multiple-titles', `${page.route} contains more than one <title>`, {
+        route: page.route,
+      });
+    }
+    if (meta.h1Count !== 1) {
+      add('warning', 'heading-count', `${page.route} has ${meta.h1Count} <h1> element(s)`, {
+        route: page.route,
+      });
+    }
+    if ((page.buildOriginUrls ?? []).length > 0) {
+      add(
+        'warning',
+        'build-origin-metadata',
+        `${page.route} still points at the build server: ${page.buildOriginUrls.join(', ')}`,
+        { route: page.route },
+      );
+    }
+    if (meta.title) titles.set(meta.title, [...(titles.get(meta.title) ?? []), page.route]);
+    if (meta.description) {
+      descriptions.set(meta.description, [
+        ...(descriptions.get(meta.description) ?? []),
+        page.route,
+      ]);
+    }
+    if (config.metadata?.siteUrl && meta.canonical) {
+      const expected = expectedPageUrl(page.route, config, page.locale);
+      if (expected && meta.canonical !== expected) {
+        add(
+          'warning',
+          'canonical-mismatch',
+          `${page.route} canonical is ${meta.canonical}, expected ${expected}`,
+          { route: page.route },
+        );
+      }
+    }
+  }
+  auditHreflang({ pages, config, add });
+  for (const [title, routes] of titles) {
+    if (routes.length < 2) continue;
+    add('error', 'duplicate-title', `routes share the title "${title}": ${routes.join(', ')}`, {
+      routes,
+    });
+  }
+  for (const [description, routes] of descriptions) {
+    if (routes.length < 2) continue;
+    add(
+      'warning',
+      'duplicate-description',
+      `routes share the meta description "${description}": ${routes.join(', ')}`,
+      { routes },
+    );
+  }
+}
+
+/**
+ * Checks generated and app-owned hreflang links for validity, self-reference, x-default
+ * and reciprocal links inside the run.
+ * @param {{ pages: Array<object>, config: object, add: Function }} input
+ */
+function auditHreflang({ pages, config, add }) {
+  if (!config.locales) return;
+  const byUrl = new Map();
+  for (const page of pages) {
+    if (page.noindex || page.notFound) continue;
+    const url = expectedPageUrl(page.route, config, page.locale) ?? page.meta?.canonical;
+    if (url) byUrl.set(url, page);
+  }
+  for (const page of pages) {
+    if (page.noindex || page.notFound) continue;
+    const meta = page.meta ?? {};
+    const code = page.locale ?? config.locales.active ?? config.locales.default;
+    const locale = config.locales.list.find((entry) => entry.code === code) ?? null;
+    const expectedLang = locale?.htmlLang ?? code;
+    if (!meta.lang) {
+      add('warning', 'html-lang-missing', `${page.route} has no <html lang>`, {
+        route: page.route,
+      });
+    } else if (meta.lang !== expectedLang && meta.lang !== code) {
+      add(
+        'warning',
+        'html-lang-mismatch',
+        `${page.route} has <html lang="${meta.lang}">, expected "${expectedLang}"`,
+        { route: page.route },
+      );
+    }
+    if (locale?.ogLocale && !meta.ogLocale) {
+      add('warning', 'og-locale-missing', `${page.route} has no og:locale for ${code}`, {
+        route: page.route,
+      });
+    }
+    if (config.locales.hreflang === false) continue;
+    const alternates = meta.alternates ?? [];
+    const seen = new Set();
+    for (const alternate of alternates) {
+      const value = String(alternate.hreflang);
+      if (value !== 'x-default' && !validHreflang(value)) {
+        add('error', 'hreflang-invalid', `${page.route} has invalid hreflang "${value}"`, {
+          route: page.route,
+        });
+      }
+      const key = value.toLowerCase();
+      if (seen.has(key)) {
+        add('error', 'hreflang-duplicate', `${page.route} repeats hreflang "${value}"`, {
+          route: page.route,
+        });
+      }
+      seen.add(key);
+    }
+    const selfUrl = meta.canonical ?? expectedPageUrl(page.route, config, page.locale);
+    const self = alternates.find((alternate) => alternate.hreflang === code);
+    if (!self) {
+      add('warning', 'hreflang-missing-self', `${page.route} has no self hreflang "${code}"`, {
+        route: page.route,
+      });
+    } else if (selfUrl && self.href !== selfUrl) {
+      add(
+        'warning',
+        'hreflang-canonical-mismatch',
+        `${page.route} hreflang "${code}" points at ${self.href}, expected ${selfUrl}`,
+        { route: page.route },
+      );
+    }
+    if (!seen.has('x-default') && config.locales.xDefault !== false) {
+      add('warning', 'hreflang-missing-x-default', `${page.route} has no x-default hreflang`, {
+        route: page.route,
+      });
+    }
+    for (const alternate of alternates) {
+      const target = byUrl.get(alternate.href);
+      if (!target) continue;
+      const targetSelf = target.meta?.alternates?.some(
+        (entry) => entry.hreflang === code && entry.href === selfUrl,
+      );
+      if (!targetSelf) {
+        add(
+          'error',
+          'hreflang-missing-return',
+          `${page.route} links to ${target.route} for ${alternate.hreflang}, but ${target.route} does not link back`,
+          { route: page.route, to: target.route },
+        );
+      }
+    }
+  }
+}
+
+/**
+ * Reports whether a value is a valid hreflang language tag.
+ * @param {string} code
+ * @returns {boolean}
+ */
+function validHreflang(code) {
+  try {
+    return Intl.getCanonicalLocales(code).length === 1;
+  } catch {
+    return false;
+  }
+}
+
+// Resolves the public URL a page should canonicalise and be listed at.
+export function expectedPageUrl(route, config, localeCode = null) {
+  const locale = localeCode
+    ? config.locales?.list?.find((entry) => entry.code === localeCode)
+    : null;
+  const baseUrl = locale?.url ?? config.metadata?.siteUrl;
+  if (!baseUrl) return null;
+  const path = pagePath(route, {
+    flatOutput: config.flatOutput,
+    trailingSlash: config.metadata.trailingSlash,
+  });
+  return `${baseUrl.replace(/\/$/, '')}${toPublicPath(path, config.base)}`;
+}

package/src/core/audit/sitemap.js

@@ -0,0 +1,39 @@
+import { expectedPageUrl } from './metadata.js';
+
+/**
+ * Ensures the sitemap and the indexable pages describe the same set of URLs. A page
+ * missing from the sitemap, a loc with no page, or a noindex page listed are all errors.
+ */
+export function auditSitemap({ pages, config, report, add }) {
+  if (!config.sitemap) return;
+  const indexable = new Map();
+  const noindex = new Map();
+  for (const page of pages) {
+    const loc = expectedPageUrl(page.route, config, page.locale);
+    if (!loc) continue;
+    if (page.noindex || page.notFound) {
+      noindex.set(loc, page.route);
+      continue;
+    }
+    indexable.set(loc, page.route);
+  }
+  const locs = new Set(report.sitemap?.locs ?? []);
+  for (const [loc, route] of indexable) {
+    if (!locs.has(loc)) {
+      add('error', 'sitemap-missing-page', `${route} is missing from the sitemap`, { route });
+    }
+  }
+  for (const loc of locs) {
+    if (noindex.has(loc)) {
+      add('error', 'sitemap-noindex-page', `sitemap lists noindex ${noindex.get(loc)}`, {
+        route: noindex.get(loc),
+      });
+      continue;
+    }
+    if (!indexable.has(loc)) {
+      add('error', 'sitemap-unknown-page', `sitemap lists ${loc} with no indexable page`, {
+        to: loc,
+      });
+    }
+  }
+}

package/src/core/clock.js

@@ -0,0 +1,60 @@
+/**
+ * Resolves the fixed build time used by both the render and verification passes. Explicit
+ * values win, then SOURCE_DATE_EPOCH, then the supplied fallback (the run start time).
+ * @param {object} config
+ * @param {number} fallbackTime
+ * @returns {number | null}
+ */
+export function resolveFixedTime(config, fallbackTime = Date.now()) {
+  if (config.freezeTime === false) return null;
+  if (typeof config.freezeTime === 'number') return config.freezeTime;
+  if (typeof config.freezeTime === 'string') {
+    const parsed = Date.parse(config.freezeTime);
+    return Number.isNaN(parsed) ? null : parsed;
+  }
+  const rawSourceDate = process.env.SOURCE_DATE_EPOCH;
+  if (rawSourceDate && /^\d+$/.test(rawSourceDate)) {
+    return Number.parseInt(rawSourceDate, 10) * 1000;
+  }
+  return fallbackTime;
+}
+
+/**
+ * Fixes Date in one page while leaving real timers running, so settling and scheduled
+ * work keep the same timing they have in a normal browser.
+ * @param {import('playwright-core').Page} page
+ * @param {number | null} fixedTime
+ */
+export async function installClock(page, fixedTime) {
+  if (fixedTime === null) return;
+  await page.clock.setFixedTime(fixedTime);
+}
+
+/**
+ * Adds the build-time globals and an optional deterministic Math.random. The PRNG is for
+ * reproducible demo content, never for security-sensitive values.
+ * @param {import('playwright-core').Page} page
+ * @param {{ fixedTime: number | null, randomSeed: number | null }} options
+ */
+export async function installClockScripts(page, { fixedTime, randomSeed }) {
+  if (fixedTime === null && randomSeed === null) return;
+  await page.addInitScript(
+    ({ time, seed }) => {
+      if (time !== null) {
+        window.__SNAPPY_NOW__ = time;
+        window.__SNAPPY_NOW_ISO__ = new Date(time).toISOString();
+      }
+      if (seed !== null) {
+        let state = seed >>> 0;
+        Math.random = () => {
+          state = (state + 0x6d2b79f5) >>> 0;
+          let value = state;
+          value = Math.imul(value ^ (value >>> 15), value | 1);
+          value ^= value + Math.imul(value ^ (value >>> 7), value | 61);
+          return ((value ^ (value >>> 14)) >>> 0) / 4294967296;
+        };
+      }
+    },
+    { time: fixedTime, seed: randomSeed },
+  );
+}