@ultimat3/seo 1.0.0

package/src/sitemap.ts

@@ -0,0 +1,179 @@
+// Sitemap generation from the route table. Dynamic routes contribute the URLs
+// their `prerender()` enumerates, so the sitemap can never drift from what the
+// build actually produced. Splits into an index past the 50,000-URL protocol cap.
+
+import { sitemapTooLarge } from './errors';
+import { type ChangeFreq, expandRoute, indexableRoutes, type RouteRecord } from './routes';
+import { absoluteUrl, attributes, escapeXml } from './xml';
+
+/** Both limits are from the sitemaps.org protocol. */
+export const SITEMAP_MAX_URLS = 50_000;
+export const SITEMAP_INDEX_MAX_FILES = 50_000;
+
+export interface SitemapAlternate {
+  hreflang: string;
+  href: string;
+}
+
+export interface SitemapUrl {
+  loc: string;
+  lastmod?: string;
+  changefreq?: ChangeFreq;
+  priority?: number;
+  alternates?: readonly SitemapAlternate[];
+}
+
+export interface SitemapFile {
+  /** Path relative to the site root, e.g. `/sitemap-1.xml`. */
+  path: string;
+  xml: string;
+  urlCount: number;
+}
+
+export interface SitemapResult {
+  readonly files: readonly SitemapFile[];
+  /** Present only when the URLs did not fit in a single file. */
+  readonly index: SitemapFile | undefined;
+  readonly urlCount: number;
+}
+
+export interface BuildSitemapOptions {
+  baseUrl: string;
+  /** Locales to emit `xhtml:link` alternates for. */
+  locales?: readonly string[];
+  /** Defaults to `/{locale}{path}`. */
+  localizePath?: (path: string, locale: string) => string;
+  /** The locale whose URLs are unprefixed and become `x-default`. */
+  defaultLocale?: string;
+  maxUrls?: number;
+  lastmod?: string;
+}
+
+function localize(path: string, locale: string, options: BuildSitemapOptions): string {
+  if (locale === options.defaultLocale) return path;
+  const fn = options.localizePath ?? ((p: string, l: string) => `/${l}${p === '/' ? '' : p}`);
+  return fn(path, locale);
+}
+
+/** Every concrete URL the route table produces, with per-locale alternates. */
+export async function sitemapUrls(
+  routes: readonly RouteRecord[],
+  options: BuildSitemapOptions,
+): Promise<readonly SitemapUrl[]> {
+  const urls: SitemapUrl[] = [];
+  const locales = options.locales ?? [];
+
+  for (const route of indexableRoutes(routes)) {
+    for (const path of await expandRoute(route)) {
+      const alternates: SitemapAlternate[] = locales.map((locale) => ({
+        hreflang: locale,
+        href: absoluteUrl(options.baseUrl, localize(path, locale, options)),
+      }));
+      if (alternates.length > 0) {
+        alternates.push({
+          hreflang: 'x-default',
+          href: absoluteUrl(options.baseUrl, path),
+        });
+      }
+
+      const lastmod = route.lastmod ?? options.lastmod;
+      const emitFor =
+        locales.length === 0 ? [path] : locales.map((l) => localize(path, l, options));
+      for (const localised of emitFor) {
+        urls.push({
+          loc: absoluteUrl(options.baseUrl, localised),
+          ...(lastmod === undefined ? {} : { lastmod }),
+          ...(route.changefreq === undefined ? {} : { changefreq: route.changefreq }),
+          ...(route.priority === undefined ? {} : { priority: route.priority }),
+          ...(alternates.length === 0 ? {} : { alternates }),
+        });
+      }
+    }
+  }
+  return urls;
+}
+
+function renderUrlSet(urls: readonly SitemapUrl[]): string {
+  const needsXhtml = urls.some((url) => (url.alternates?.length ?? 0) > 0);
+  const ns = needsXhtml
+    ? ' xmlns="http://www.sitemaps.org/schemas/sitemap/0.9" xmlns:xhtml="http://www.w3.org/1999/xhtml"'
+    : ' xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"';
+  const body = urls
+    .map((url) => {
+      const parts = [`    <loc>${escapeXml(url.loc)}</loc>`];
+      if (url.lastmod !== undefined) parts.push(`    <lastmod>${escapeXml(url.lastmod)}</lastmod>`);
+      if (url.changefreq !== undefined) {
+        parts.push(`    <changefreq>${url.changefreq}</changefreq>`);
+      }
+      if (url.priority !== undefined) {
+        parts.push(`    <priority>${url.priority.toFixed(1)}</priority>`);
+      }
+      for (const alternate of url.alternates ?? []) {
+        parts.push(
+          `    <xhtml:link${attributes({ rel: 'alternate', hreflang: alternate.hreflang, href: alternate.href })}/>`,
+        );
+      }
+      return `  <url>\n${parts.join('\n')}\n  </url>`;
+    })
+    .join('\n');
+  return `<?xml version="1.0" encoding="UTF-8"?>\n<urlset${ns}>\n${body}\n</urlset>\n`;
+}
+
+function renderIndex(files: readonly SitemapFile[], options: BuildSitemapOptions): string {
+  const body = files
+    .map((file) => {
+      const loc = escapeXml(absoluteUrl(options.baseUrl, file.path));
+      const lastmod =
+        options.lastmod === undefined
+          ? ''
+          : `\n    <lastmod>${escapeXml(options.lastmod)}</lastmod>`;
+      return `  <sitemap>\n    <loc>${loc}</loc>${lastmod}\n  </sitemap>`;
+    })
+    .join('\n');
+  return `<?xml version="1.0" encoding="UTF-8"?>\n<sitemapindex xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">\n${body}\n</sitemapindex>\n`;
+}
+
+export function chunk<T>(items: readonly T[], size: number): T[][] {
+  const out: T[][] = [];
+  for (let index = 0; index < items.length; index += size) {
+    out.push(items.slice(index, index + size));
+  }
+  return out;
+}
+
+export async function buildSitemap(
+  routes: readonly RouteRecord[],
+  options: BuildSitemapOptions,
+): Promise<SitemapResult> {
+  const urls = await sitemapUrls(routes, options);
+  const maxUrls = options.maxUrls ?? SITEMAP_MAX_URLS;
+
+  if (urls.length <= maxUrls) {
+    return {
+      files: [{ path: '/sitemap.xml', xml: renderUrlSet(urls), urlCount: urls.length }],
+      index: undefined,
+      urlCount: urls.length,
+    };
+  }
+
+  const groups = chunk(urls, maxUrls);
+  if (groups.length > SITEMAP_INDEX_MAX_FILES) {
+    throw sitemapTooLarge(groups.length, SITEMAP_INDEX_MAX_FILES);
+  }
+
+  const files: SitemapFile[] = groups.map((group, position) => ({
+    path: `/sitemap-${position + 1}.xml`,
+    xml: renderUrlSet(group),
+    urlCount: group.length,
+  }));
+
+  return {
+    files,
+    index: {
+      path: '/sitemap.xml',
+      xml: renderIndex(files, options),
+      urlCount: files.length,
+    },
+    urlCount: urls.length,
+  };
+}

package/src/validate.ts

@@ -0,0 +1,146 @@
+// The build gate. A `site/` route without a title or description does not warn —
+// it throws X_SEO_META_MISSING naming the exact file and the exact edit. Also
+// catches the three failures that only show up weeks later in Search Console:
+// duplicate meta, an over-length title, and a canonical that lies.
+
+import {
+  canonicalMismatch,
+  duplicateMeta,
+  metaMissing,
+  metaTooLong,
+  SeoError,
+  type SeoErrorCode,
+} from './errors';
+import { applyTitleTemplate, DESCRIPTION_MAX_LENGTH, TITLE_MAX_LENGTH } from './meta';
+import { indexableRoutes, isDynamic, type RouteRecord } from './routes';
+import { absoluteUrl } from './xml';
+
+export interface MetaIssue {
+  readonly code: string;
+  readonly route: string;
+  readonly file: string;
+  readonly cause: string;
+  readonly fix: string;
+}
+
+/** `--json`-shaped: the CLI prints this verbatim under `x verify --json`. */
+export interface MetaValidationReport {
+  readonly ok: boolean;
+  readonly checked: number;
+  readonly issues: readonly MetaIssue[];
+}
+
+export interface ValidateMetaOptions {
+  /** Required to check canonicals. Without it, canonical checks are skipped. */
+  baseUrl?: string;
+  titleMaxLength?: number;
+  descriptionMaxLength?: number;
+  /** Report duplicates across routes. On by default. */
+  checkDuplicates?: boolean;
+}
+
+function issueOf(error: SeoError, route: string, file: string): MetaIssue {
+  return { code: error.code, route, file, cause: error.cause, fix: error.fix };
+}
+
+export function validateMeta(
+  routes: readonly RouteRecord[],
+  options: ValidateMetaOptions = {},
+): MetaValidationReport {
+  const titleMax = options.titleMaxLength ?? TITLE_MAX_LENGTH;
+  const descriptionMax = options.descriptionMaxLength ?? DESCRIPTION_MAX_LENGTH;
+  const checked = indexableRoutes(routes);
+  const issues: MetaIssue[] = [];
+
+  const titles = new Map<string, string[]>();
+  const descriptions = new Map<string, string[]>();
+
+  for (const route of checked) {
+    const meta = route.meta ?? {};
+
+    if (meta.title === undefined || meta.title.trim() === '') {
+      issues.push(issueOf(metaMissing(route.file, route.path, 'title'), route.path, route.file));
+    } else {
+      const rendered = applyTitleTemplate(meta.title, meta.titleTemplate);
+      if (rendered.length > titleMax) {
+        issues.push(
+          issueOf(
+            metaTooLong(route.file, 'title', rendered.length, titleMax),
+            route.path,
+            route.file,
+          ),
+        );
+      }
+      push(titles, rendered, route.file);
+    }
+
+    if (meta.description === undefined || meta.description.trim() === '') {
+      issues.push(
+        issueOf(metaMissing(route.file, route.path, 'description'), route.path, route.file),
+      );
+    } else {
+      if (meta.description.length > descriptionMax) {
+        issues.push(
+          issueOf(
+            metaTooLong(route.file, 'description', meta.description.length, descriptionMax),
+            route.path,
+            route.file,
+          ),
+        );
+      }
+      push(descriptions, meta.description, route.file);
+    }
+
+    // A canonical is only checkable for a static path: a dynamic route's
+    // canonical is produced per-item at render time.
+    if (meta.canonical !== undefined && options.baseUrl !== undefined && !isDynamic(route.path)) {
+      const expected = absoluteUrl(options.baseUrl, route.path);
+      const actual = absoluteUrl(options.baseUrl, meta.canonical);
+      if (actual !== expected) {
+        issues.push(
+          issueOf(canonicalMismatch(route.file, actual, expected), route.path, route.file),
+        );
+      }
+    }
+  }
+
+  if (options.checkDuplicates !== false) {
+    issues.push(...duplicates(titles, 'title'), ...duplicates(descriptions, 'description'));
+  }
+
+  return { ok: issues.length === 0, checked: checked.length, issues };
+}
+
+function push(index: Map<string, string[]>, key: string, file: string): void {
+  const existing = index.get(key);
+  if (existing === undefined) index.set(key, [file]);
+  else existing.push(file);
+}
+
+function duplicates(index: Map<string, string[]>, field: string): MetaIssue[] {
+  const out: MetaIssue[] = [];
+  for (const [value, files] of index) {
+    if (files.length < 2) continue;
+    const error = duplicateMeta(field, value, files);
+    out.push({
+      code: error.code,
+      route: files.join(', '),
+      file: files[0] ?? '',
+      cause: error.cause,
+      fix: error.fix,
+    });
+  }
+  return out;
+}
+
+/** Fails the build on the first issue. `x verify` calls this. */
+export function assertMeta(report: MetaValidationReport): void {
+  const first = report.issues[0];
+  if (first === undefined) return;
+  throw new SeoError({
+    code: first.code as SeoErrorCode,
+    cause: first.cause,
+    fix: first.fix,
+    meta: { route: first.route, file: first.file, totalIssues: report.issues.length },
+  });
+}

package/src/xml.ts

@@ -0,0 +1,39 @@
+// XML/HTML escaping and tag emission. One implementation, because a sitemap, a
+// feed, and a <head> tag all fail the same way on an unescaped ampersand.
+
+const XML_ESCAPES: Readonly<Record<string, string>> = {
+  '&': '&amp;',
+  '<': '&lt;',
+  '>': '&gt;',
+  '"': '&quot;',
+  "'": '&apos;',
+};
+
+export function escapeXml(value: string): string {
+  return value.replace(/[&<>"']/g, (char) => XML_ESCAPES[char] ?? char);
+}
+
+/** Attribute values only ever need these three; apostrophes stay readable. */
+export function escapeAttribute(value: string): string {
+  return value.replace(/[&<>"]/g, (char) => XML_ESCAPES[char] ?? char);
+}
+
+export function xmlElement(name: string, text: string): string {
+  return `<${name}>${escapeXml(text)}</${name}>`;
+}
+
+export function cdata(value: string): string {
+  return `<![CDATA[${value.replaceAll(']]>', ']]]]><![CDATA[>')}]]>`;
+}
+
+export function attributes(attrs: Readonly<Record<string, string>>): string {
+  return Object.entries(attrs)
+    .map(([key, value]) => ` ${key}="${escapeAttribute(value)}"`)
+    .join('');
+}
+
+/** Join a base URL and a path without producing `//` or dropping a segment. */
+export function absoluteUrl(baseUrl: string, path: string): string {
+  if (/^https?:\/\//.test(path)) return path;
+  return `${baseUrl.replace(/\/+$/, '')}/${path.replace(/^\/+/, '')}`.replace(/\/$/, '') || baseUrl;
+}