The 112-check SEO implementation checklist

/**
 * Code Kit: SEO primitives.
 * Implements checks: meta-canonical-absolute, meta-canonical-normalised,
 *                    meta-open-graph, meta-twitter-card, meta-title-template
 *
 * The only module in the kit permitted to read process.env, and it falls back
 * gracefully when the variable is absent.
 */

/** Resolve the site origin once. Callers should import this, never re-derive it. */
export function resolveSiteUrl(fallback: string): string {
  const fromEnv =
    process.env.NEXT_PUBLIC_SITE_URL ??
    (process.env.VERCEL_PROJECT_PRODUCTION_URL
      ? `https://${process.env.VERCEL_PROJECT_PRODUCTION_URL}`
      : undefined);
  return stripTrailingSlashes(fromEnv && fromEnv.length > 0 ? fromEnv : fallback);
}

function stripTrailingSlashes(value: string): string {
  return value.replace(/\/+$/, "");
}

/**
 * Normalise a path into an absolute canonical URL.
 *
 * Handles the cases that actually break in production:
 *   ""            -> origin
 *   "/"           -> origin
 *   "/a/"         -> origin + "/a"      (trailing slash stripped)
 *   "//a"         -> origin + "/a"      (protocol-relative path collapsed)
 *   "a/b"         -> origin + "/a/b"    (missing leading slash added)
 *   "/a?b=1#c"    -> query and fragment preserved, path normalised
 *   "https://x/y" -> returned unchanged (already absolute)
 */
export function canonicalUrl(path: string | undefined, siteUrl: string): string {
  const origin = stripTrailingSlashes(siteUrl);
  if (!path) return origin;

  if (/^https?:\/\//i.test(path)) return stripTrailingSlashes(path) || path;

  // Split off query and fragment before touching slashes.
  const queryIndex = path.search(/[?#]/);
  const rawPath = queryIndex === -1 ? path : path.slice(0, queryIndex);
  const suffix = queryIndex === -1 ? "" : path.slice(queryIndex);

  let normalised = rawPath.replace(/\/{2,}/g, "/");
  if (!normalised.startsWith("/")) normalised = `/${normalised}`;
  normalised = normalised.replace(/\/+$/, "");

  if (normalised === "" || normalised === "/") {
    return suffix ? `${origin}/${suffix}` : origin;
  }
  return `${origin}${normalised}${suffix}`;
}

export type OpenGraphImage = {
  url: string;
  width?: number;
  height?: number;
  alt: string;
  type?: string;
};

export type OpenGraphOptions = {
  title: string;
  description: string;
  url: string;
  siteName: string;
  locale?: string;
  type?: "website" | "article" | "profile" | "book";
  images?: OpenGraphImage[];
  publishedTime?: string;
  modifiedTime?: string;
  authors?: string[];
  section?: string;
  tags?: string[];
};

const DEFAULT_OG_IMAGE_WIDTH = 1200;
const DEFAULT_OG_IMAGE_HEIGHT = 630;

/** Open Graph object with the defaults that matter, omitting anything undefined. */
export function openGraph(opts: OpenGraphOptions) {
  const images = (opts.images ?? []).map((image) => ({
    url: image.url,
    width: image.width ?? DEFAULT_OG_IMAGE_WIDTH,
    height: image.height ?? DEFAULT_OG_IMAGE_HEIGHT,
    alt: image.alt,
    type: image.type ?? inferImageType(image.url),
  }));

  return compact({
    title: opts.title,
    description: opts.description,
    url: opts.url,
    siteName: opts.siteName,
    locale: opts.locale ?? "en_US",
    type: opts.type ?? "website",
    images: images.length > 0 ? images : undefined,
    publishedTime: opts.publishedTime,
    modifiedTime: opts.modifiedTime,
    authors: opts.authors?.length ? opts.authors : undefined,
    section: opts.section,
    tags: opts.tags?.length ? opts.tags : undefined,
  });
}

export type TwitterCardOptions = {
  title: string;
  description: string;
  images?: string[];
  creator?: string;
  site?: string;
};

export function twitterCard(opts: TwitterCardOptions) {
  return compact({
    card: "summary_large_image" as const,
    title: opts.title,
    description: opts.description,
    images: opts.images?.length ? opts.images : undefined,
    creator: opts.creator,
    site: opts.site,
  });
}

function inferImageType(url: string): string | undefined {
  const match = /\.(png|jpe?g|webp|avif|gif|svg)(?:\?|$)/i.exec(url);
  if (!match) return undefined;
  const ext = match[1]?.toLowerCase();
  switch (ext) {
    case "png":
      return "image/png";
    case "jpg":
    case "jpeg":
      return "image/jpeg";
    case "webp":
      return "image/webp";
    case "avif":
      return "image/avif";
    case "gif":
      return "image/gif";
    case "svg":
      return "image/svg+xml";
    default:
      return undefined;
  }
}

/**
 * Drop undefined, null and empty-string values recursively.
 *
 * Structured data with `"author": ""` is worse than structured data without an
 * author: it asserts a fact that is empty. Every factory in the kit runs its
 * output through this.
 */
export function compact<T>(value: T): T {
  if (Array.isArray(value)) {
    const cleaned = value
      .map((item) => compact(item))
      .filter((item) => item !== undefined && item !== null && item !== "");
    return cleaned as unknown as T;
  }
  if (value && typeof value === "object" && !(value instanceof Date)) {
    const entries = Object.entries(value as Record<string, unknown>)
      .map(([key, val]) => [key, compact(val)] as const)
      .filter(([, val]) => {
        if (val === undefined || val === null || val === "") return false;
        if (Array.isArray(val) && val.length === 0) return false;
        if (typeof val === "object" && Object.keys(val as object).length === 0) return false;
        return true;
      });
    return Object.fromEntries(entries) as T;
  }
  return value;
}

/**
 * Code Kit: entity gating.
 * Implements checks: pseo-entity-gate, found-404-returns-404
 *
 * An ungated dynamic route renders a page for any slug it is given, including
 * slugs a crawler invented by mangling a URL. Each one is an indexable page
 * with no content. This module is the gate.
 */

export type GatedEntity = { slug: string };

export type EntityGate<T extends GatedEntity> = {
  /** Every valid slug, for static generation. */
  slugs: () => string[];
  /** Returns undefined for anything not on the list. Never a partial match. */
  resolve: (slug: string) => T | undefined;
  /** Canonical slug to redirect to, or undefined. Aliases never render. */
  resolveAlias: (slug: string) => string | undefined;
  all: () => readonly T[];
  size: number;
};

export function createEntityGate<T extends GatedEntity>(
  entities: readonly T[],
  aliases: Readonly<Record<string, string>> = {},
): EntityGate<T> {
  const bySlug = new Map(entities.map((entity) => [entity.slug, entity]));

  // A duplicate slug means two entities compete for one URL. Fail loudly at
  // module load rather than serving whichever one won the Map insertion.
  if (bySlug.size !== entities.length) {
    const seen = new Set<string>();
    const duplicates = entities
      .map((entity) => entity.slug)
      .filter((slug) => (seen.has(slug) ? true : (seen.add(slug), false)));
    throw new Error(`Duplicate entity slugs: ${[...new Set(duplicates)].join(", ")}`);
  }

  return {
    slugs: () => entities.map((entity) => entity.slug),
    resolve: (slug) => bySlug.get(slug),
    resolveAlias: (slug) => {
      const target = aliases[slug];
      return target && bySlug.has(target) ? target : undefined;
    },
    all: () => entities,
    size: entities.length,
  };
}

/**
 * Slug normalisation for the URLs you generate, not for the ones you receive.
 * Receiving a slug that needs normalising means the link that produced it is
 * wrong; fix the link rather than accepting both forms.
 */
export function toSlug(value: string): string {
  return value
    .toLowerCase()
    .normalize("NFKD")
    .replace(/[̀-ͯ]/g, "")
    .replace(/[^a-z0-9]+/g, "-")
    .replace(/^-+|-+$/g, "");
}

/**
 * Code Kit: SEO primitives.
 * Implements checks: meta-canonical-absolute, meta-canonical-normalised,
 *                    meta-open-graph, meta-twitter-card, meta-title-template
 *
 * The only module in the kit permitted to read process.env, and it falls back
 * gracefully when the variable is absent.
 */

/** Resolve the site origin once. Callers should import this, never re-derive it. */
export function resolveSiteUrl(fallback: string): string {
  const fromEnv =
    process.env.NEXT_PUBLIC_SITE_URL ??
    (process.env.VERCEL_PROJECT_PRODUCTION_URL
      ? `https://${process.env.VERCEL_PROJECT_PRODUCTION_URL}`
      : undefined);
  return stripTrailingSlashes(fromEnv && fromEnv.length > 0 ? fromEnv : fallback);
}

function stripTrailingSlashes(value: string): string {
  return value.replace(/\/+$/, "");
}

/**
 * Normalise a path into an absolute canonical URL.
 *
 * Handles the cases that actually break in production:
 *   ""            -> origin
 *   "/"           -> origin
 *   "/a/"         -> origin + "/a"      (trailing slash stripped)
 *   "//a"         -> origin + "/a"      (protocol-relative path collapsed)
 *   "a/b"         -> origin + "/a/b"    (missing leading slash added)
 *   "/a?b=1#c"    -> query and fragment preserved, path normalised
 *   "https://x/y" -> returned unchanged (already absolute)
 */
export function canonicalUrl(path: string | undefined, siteUrl: string): string {
  const origin = stripTrailingSlashes(siteUrl);
  if (!path) return origin;

  if (/^https?:\/\//i.test(path)) return stripTrailingSlashes(path) || path;

  // Split off query and fragment before touching slashes.
  const queryIndex = path.search(/[?#]/);
  const rawPath = queryIndex === -1 ? path : path.slice(0, queryIndex);
  const suffix = queryIndex === -1 ? "" : path.slice(queryIndex);

  let normalised = rawPath.replace(/\/{2,}/g, "/");
  if (!normalised.startsWith("/")) normalised = `/${normalised}`;
  normalised = normalised.replace(/\/+$/, "");

  if (normalised === "" || normalised === "/") {
    return suffix ? `${origin}/${suffix}` : origin;
  }
  return `${origin}${normalised}${suffix}`;
}

export type OpenGraphImage = {
  url: string;
  width?: number;
  height?: number;
  alt: string;
  type?: string;
};

export type OpenGraphOptions = {
  title: string;
  description: string;
  url: string;
  siteName: string;
  locale?: string;
  type?: "website" | "article" | "profile" | "book";
  images?: OpenGraphImage[];
  publishedTime?: string;
  modifiedTime?: string;
  authors?: string[];
  section?: string;
  tags?: string[];
};

const DEFAULT_OG_IMAGE_WIDTH = 1200;
const DEFAULT_OG_IMAGE_HEIGHT = 630;

/** Open Graph object with the defaults that matter, omitting anything undefined. */
export function openGraph(opts: OpenGraphOptions) {
  const images = (opts.images ?? []).map((image) => ({
    url: image.url,
    width: image.width ?? DEFAULT_OG_IMAGE_WIDTH,
    height: image.height ?? DEFAULT_OG_IMAGE_HEIGHT,
    alt: image.alt,
    type: image.type ?? inferImageType(image.url),
  }));

  return compact({
    title: opts.title,
    description: opts.description,
    url: opts.url,
    siteName: opts.siteName,
    locale: opts.locale ?? "en_US",
    type: opts.type ?? "website",
    images: images.length > 0 ? images : undefined,
    publishedTime: opts.publishedTime,
    modifiedTime: opts.modifiedTime,
    authors: opts.authors?.length ? opts.authors : undefined,
    section: opts.section,
    tags: opts.tags?.length ? opts.tags : undefined,
  });
}

export type TwitterCardOptions = {
  title: string;
  description: string;
  images?: string[];
  creator?: string;
  site?: string;
};

export function twitterCard(opts: TwitterCardOptions) {
  return compact({
    card: "summary_large_image" as const,
    title: opts.title,
    description: opts.description,
    images: opts.images?.length ? opts.images : undefined,
    creator: opts.creator,
    site: opts.site,
  });
}

function inferImageType(url: string): string | undefined {
  const match = /\.(png|jpe?g|webp|avif|gif|svg)(?:\?|$)/i.exec(url);
  if (!match) return undefined;
  const ext = match[1]?.toLowerCase();
  switch (ext) {
    case "png":
      return "image/png";
    case "jpg":
    case "jpeg":
      return "image/jpeg";
    case "webp":
      return "image/webp";
    case "avif":
      return "image/avif";
    case "gif":
      return "image/gif";
    case "svg":
      return "image/svg+xml";
    default:
      return undefined;
  }
}

/**
 * Drop undefined, null and empty-string values recursively.
 *
 * Structured data with `"author": ""` is worse than structured data without an
 * author: it asserts a fact that is empty. Every factory in the kit runs its
 * output through this.
 */
export function compact<T>(value: T): T {
  if (Array.isArray(value)) {
    const cleaned = value
      .map((item) => compact(item))
      .filter((item) => item !== undefined && item !== null && item !== "");
    return cleaned as unknown as T;
  }
  if (value && typeof value === "object" && !(value instanceof Date)) {
    const entries = Object.entries(value as Record<string, unknown>)
      .map(([key, val]) => [key, compact(val)] as const)
      .filter(([, val]) => {
        if (val === undefined || val === null || val === "") return false;
        if (Array.isArray(val) && val.length === 0) return false;
        if (typeof val === "object" && Object.keys(val as object).length === 0) return false;
        return true;
      });
    return Object.fromEntries(entries) as T;
  }
  return value;
}

/**
 * Code Kit: SEO primitives.
 * Implements checks: meta-canonical-absolute, meta-canonical-normalised,
 *                    meta-open-graph, meta-twitter-card, meta-title-template
 *
 * The only module in the kit permitted to read process.env, and it falls back
 * gracefully when the variable is absent.
 */

/** Resolve the site origin once. Callers should import this, never re-derive it. */
export function resolveSiteUrl(fallback: string): string {
  const fromEnv =
    process.env.NEXT_PUBLIC_SITE_URL ??
    (process.env.VERCEL_PROJECT_PRODUCTION_URL
      ? `https://${process.env.VERCEL_PROJECT_PRODUCTION_URL}`
      : undefined);
  return stripTrailingSlashes(fromEnv && fromEnv.length > 0 ? fromEnv : fallback);
}

function stripTrailingSlashes(value: string): string {
  return value.replace(/\/+$/, "");
}

/**
 * Normalise a path into an absolute canonical URL.
 *
 * Handles the cases that actually break in production:
 *   ""            -> origin
 *   "/"           -> origin
 *   "/a/"         -> origin + "/a"      (trailing slash stripped)
 *   "//a"         -> origin + "/a"      (protocol-relative path collapsed)
 *   "a/b"         -> origin + "/a/b"    (missing leading slash added)
 *   "/a?b=1#c"    -> query and fragment preserved, path normalised
 *   "https://x/y" -> returned unchanged (already absolute)
 */
export function canonicalUrl(path: string | undefined, siteUrl: string): string {
  const origin = stripTrailingSlashes(siteUrl);
  if (!path) return origin;

  if (/^https?:\/\//i.test(path)) return stripTrailingSlashes(path) || path;

  // Split off query and fragment before touching slashes.
  const queryIndex = path.search(/[?#]/);
  const rawPath = queryIndex === -1 ? path : path.slice(0, queryIndex);
  const suffix = queryIndex === -1 ? "" : path.slice(queryIndex);

  let normalised = rawPath.replace(/\/{2,}/g, "/");
  if (!normalised.startsWith("/")) normalised = `/${normalised}`;
  normalised = normalised.replace(/\/+$/, "");

  if (normalised === "" || normalised === "/") {
    return suffix ? `${origin}/${suffix}` : origin;
  }
  return `${origin}${normalised}${suffix}`;
}

export type OpenGraphImage = {
  url: string;
  width?: number;
  height?: number;
  alt: string;
  type?: string;
};

export type OpenGraphOptions = {
  title: string;
  description: string;
  url: string;
  siteName: string;
  locale?: string;
  type?: "website" | "article" | "profile" | "book";
  images?: OpenGraphImage[];
  publishedTime?: string;
  modifiedTime?: string;
  authors?: string[];
  section?: string;
  tags?: string[];
};

const DEFAULT_OG_IMAGE_WIDTH = 1200;
const DEFAULT_OG_IMAGE_HEIGHT = 630;

/** Open Graph object with the defaults that matter, omitting anything undefined. */
export function openGraph(opts: OpenGraphOptions) {
  const images = (opts.images ?? []).map((image) => ({
    url: image.url,
    width: image.width ?? DEFAULT_OG_IMAGE_WIDTH,
    height: image.height ?? DEFAULT_OG_IMAGE_HEIGHT,
    alt: image.alt,
    type: image.type ?? inferImageType(image.url),
  }));

  return compact({
    title: opts.title,
    description: opts.description,
    url: opts.url,
    siteName: opts.siteName,
    locale: opts.locale ?? "en_US",
    type: opts.type ?? "website",
    images: images.length > 0 ? images : undefined,
    publishedTime: opts.publishedTime,
    modifiedTime: opts.modifiedTime,
    authors: opts.authors?.length ? opts.authors : undefined,
    section: opts.section,
    tags: opts.tags?.length ? opts.tags : undefined,
  });
}

export type TwitterCardOptions = {
  title: string;
  description: string;
  images?: string[];
  creator?: string;
  site?: string;
};

export function twitterCard(opts: TwitterCardOptions) {
  return compact({
    card: "summary_large_image" as const,
    title: opts.title,
    description: opts.description,
    images: opts.images?.length ? opts.images : undefined,
    creator: opts.creator,
    site: opts.site,
  });
}

function inferImageType(url: string): string | undefined {
  const match = /\.(png|jpe?g|webp|avif|gif|svg)(?:\?|$)/i.exec(url);
  if (!match) return undefined;
  const ext = match[1]?.toLowerCase();
  switch (ext) {
    case "png":
      return "image/png";
    case "jpg":
    case "jpeg":
      return "image/jpeg";
    case "webp":
      return "image/webp";
    case "avif":
      return "image/avif";
    case "gif":
      return "image/gif";
    case "svg":
      return "image/svg+xml";
    default:
      return undefined;
  }
}

/**
 * Drop undefined, null and empty-string values recursively.
 *
 * Structured data with `"author": ""` is worse than structured data without an
 * author: it asserts a fact that is empty. Every factory in the kit runs its
 * output through this.
 */
export function compact<T>(value: T): T {
  if (Array.isArray(value)) {
    const cleaned = value
      .map((item) => compact(item))
      .filter((item) => item !== undefined && item !== null && item !== "");
    return cleaned as unknown as T;
  }
  if (value && typeof value === "object" && !(value instanceof Date)) {
    const entries = Object.entries(value as Record<string, unknown>)
      .map(([key, val]) => [key, compact(val)] as const)
      .filter(([, val]) => {
        if (val === undefined || val === null || val === "") return false;
        if (Array.isArray(val) && val.length === 0) return false;
        if (typeof val === "object" && Object.keys(val as object).length === 0) return false;
        return true;
      });
    return Object.fromEntries(entries) as T;
  }
  return value;
}

/**
 * Code Kit: the sitewide @graph composer.
 * Implements checks: schema-graph-anchors, schema-single-script, schema-no-duplicates
 *
 * One <script type="application/ld+json"> per page holding one @graph array.
 * Nodes cross-reference each other by @id instead of duplicating themselves,
 * which is what stops a site from shipping the same Organization object 2,000
 * times and lets a crawler resolve one entity across every page.
 */

import { compact } from "../constants";
import { organization, website, type OrganizationOptions, type WebSiteOptions } from "./organization";
import { product, type ProductOptions } from "./commerce";
import { type JsonLdObject, SCHEMA_CONTEXT, nodeId, ref } from "./types";

export type SiteGraphOptions = {
  siteUrl: string;
  organization: Omit<OrganizationOptions, "siteUrl">;
  website: Omit<WebSiteOptions, "siteUrl" | "publisher">;
  /** Omit on sites that do not sell a product. */
  product?: Omit<ProductOptions, "siteUrl">;
  /** Page-level nodes: WebPage, BreadcrumbList, Article, FAQPage, and so on. */
  additionalNodes?: Array<JsonLdObject | undefined>;
};

/**
 * Compose the sitewide graph.
 *
 * The three anchors are stable and cross-referenced:
 *   #organization  is the publisher of #website and the brand of #product
 *   #website       is the isPartOf target for every page node
 *   #product       is the thing being sold
 */
export function siteGraph(opts: SiteGraphOptions): JsonLdObject {
  const orgId = nodeId(opts.siteUrl, "#organization");

  const nodes: Array<JsonLdObject | undefined> = [
    organization({ siteUrl: opts.siteUrl, ...opts.organization }),
    website({ siteUrl: opts.siteUrl, publisher: ref(orgId), ...opts.website }),
    opts.product
      ? product({
          siteUrl: opts.siteUrl,
          ...opts.product,
          brandName: opts.product.brandName,
        })
      : undefined,
    ...(opts.additionalNodes ?? []),
  ];

  return {
    "@context": SCHEMA_CONTEXT,
    "@graph": dedupeById(nodes.filter(isPresent)) as unknown as JsonLdObject[],
  } as unknown as JsonLdObject;
}

/**
 * Build a page-level graph that references the sitewide anchors without
 * repeating them. Use on every page that is not the home page.
 */
export function pageGraph(opts: {
  siteUrl: string;
  nodes: Array<JsonLdObject | undefined>;
}): JsonLdObject {
  return {
    "@context": SCHEMA_CONTEXT,
    "@graph": dedupeById(opts.nodes.filter(isPresent)) as unknown as JsonLdObject[],
  } as unknown as JsonLdObject;
}

function isPresent<T>(value: T | undefined | null): value is T {
  return value !== undefined && value !== null;
}

/** Two nodes with the same @id in one graph is a validation error. Last write wins. */
function dedupeById(nodes: JsonLdObject[]): JsonLdObject[] {
  const seen = new Map<string, JsonLdObject>();
  const anonymous: JsonLdObject[] = [];
  for (const node of nodes) {
    const id = typeof node["@id"] === "string" ? node["@id"] : undefined;
    if (id) seen.set(id, node);
    else anonymous.push(node);
  }
  return [...seen.values(), ...anonymous];
}

/**
 * Collect every @id declared in a graph and every @id referenced by it, so a
 * test can assert that no reference dangles.
 *
 * The distinction that matters: an object carrying `@id` plus other properties
 * DECLARES a node, at any nesting depth. An object carrying nothing but `@id`
 * REFERENCES one. A nested ImageObject with its own `@id` is a declaration, and
 * treating it as a dangling reference would be a false positive.
 */
export function graphIdIntegrity(graph: JsonLdObject): {
  declared: Set<string>;
  referenced: Set<string>;
  dangling: string[];
} {
  const declared = new Set<string>();
  const referenced = new Set<string>();
  const nodes = (graph["@graph"] as unknown as JsonLdObject[]) ?? [];

  const walk = (value: unknown): void => {
    if (Array.isArray(value)) {
      for (const item of value) walk(item);
      return;
    }
    if (!value || typeof value !== "object") return;

    const obj = value as Record<string, unknown>;
    const keys = Object.keys(obj);
    const id = typeof obj["@id"] === "string" ? obj["@id"] : undefined;

    if (id) {
      if (keys.length === 1) referenced.add(id);
      else declared.add(id);
    }

    for (const [key, val] of Object.entries(obj)) {
      if (key === "@id") continue;
      walk(val);
    }
  };

  for (const node of nodes) walk(node);

  return {
    declared,
    referenced,
    dangling: [...referenced].filter((id) => !declared.has(id)),
  };
}

export { compact };

/**
 * Code Kit: navigation and list schema factories.
 * Implements checks: schema-breadcrumb, schema-itemlist, nav-breadcrumb-visible
 */

import { compact } from "../constants";
import { type JsonLdObject } from "./types";

export type BreadcrumbItem = { name: string; url: string };

/**
 * BreadcrumbList.
 *
 * The last item is the current page and carries no `item` URL, per Google's
 * documented shape. A breadcrumb in schema without a matching visible
 * <nav aria-label="Breadcrumb"> is a mismatch between markup and page, so the
 * kit's page template renders both from the same array.
 */
export function breadcrumbList(opts: {
  url: string;
  items: BreadcrumbItem[];
}): JsonLdObject | undefined {
  if (opts.items.length === 0) return undefined;
  const lastIndex = opts.items.length - 1;
  return {
    "@type": "BreadcrumbList",
    "@id": `${opts.url}#breadcrumb`,
    itemListElement: opts.items.map((item, index) =>
      compact({
        "@type": "ListItem",
        position: index + 1,
        name: item.name,
        item: index === lastIndex ? undefined : item.url,
      }),
    ),
  };
}

export type ItemListEntry = {
  name: string;
  url: string;
  description?: string;
  position?: number;
};

export function itemList(opts: {
  url: string;
  name?: string;
  items: ItemListEntry[];
  /** Use "ItemList" for a ranked list, omit ordering for an unranked set. */
  ordered?: boolean;
}): JsonLdObject | undefined {
  if (opts.items.length === 0) return undefined;
  return compact({
    "@type": "ItemList",
    "@id": `${opts.url}#itemlist`,
    name: opts.name,
    numberOfItems: opts.items.length,
    itemListOrder: opts.ordered
      ? "https://schema.org/ItemListOrderAscending"
      : "https://schema.org/ItemListUnordered",
    itemListElement: opts.items.map((item, index) =>
      compact({
        "@type": "ListItem",
        position: item.position ?? index + 1,
        name: item.name,
        url: item.url,
        description: item.description,
      }),
    ),
  }) as JsonLdObject;
}

export type SiteNavigationOptions = {
  url: string;
  items: Array<{ name: string; url: string }>;
};

export function siteNavigationElement(opts: SiteNavigationOptions): JsonLdObject | undefined {
  if (opts.items.length === 0) return undefined;
  return {
    "@type": "SiteNavigationElement",
    "@id": `${opts.url}#navigation`,
    name: opts.items.map((item) => item.name),
    url: opts.items.map((item) => item.url),
  };
}

/**
 * Code Kit: content schema factories.
 * Implements checks: schema-article, schema-faqpage, schema-howto,
 *                    schema-speakable, content-faq-visible
 */

import { compact } from "../constants";
import { type JsonLdObject, type NodeRef, isoDate, ref } from "./types";

export type ArticleOptions = {
  type?: "Article" | "BlogPosting" | "TechArticle";
  url: string;
  headline: string;
  description: string;
  datePublished: string | Date;
  dateModified?: string | Date;
  author: JsonLdObject | NodeRef;
  publisher: NodeRef;
  imageUrl?: string;
  imageWidth?: number;
  imageHeight?: number;
  wordCount?: number;
  articleSection?: string;
  keywords?: string[];
  inLanguage?: string;
  isPartOf?: NodeRef;
  about?: { name: string; description?: string };
};

export function article(opts: ArticleOptions): JsonLdObject {
  // Google truncates headlines past 110 characters in rich results.
  const headline = opts.headline.length > 110 ? `${opts.headline.slice(0, 107)}...` : opts.headline;

  return compact({
    "@type": opts.type ?? "Article",
    "@id": `${opts.url}#article`,
    url: opts.url,
    mainEntityOfPage: { "@type": "WebPage", "@id": opts.url },
    headline,
    description: opts.description,
    datePublished: isoDate(opts.datePublished),
    dateModified: isoDate(opts.dateModified ?? opts.datePublished),
    author: opts.author,
    publisher: opts.publisher,
    image: opts.imageUrl
      ? compact({
          "@type": "ImageObject",
          url: opts.imageUrl,
          width: opts.imageWidth,
          height: opts.imageHeight,
        })
      : undefined,
    wordCount: opts.wordCount,
    articleSection: opts.articleSection,
    keywords: opts.keywords?.length ? opts.keywords.join(", ") : undefined,
    inLanguage: opts.inLanguage ?? "en-US",
    isPartOf: opts.isPartOf,
    about: opts.about
      ? compact({
          "@type": "Thing",
          name: opts.about.name,
          description: opts.about.description,
        })
      : undefined,
  }) as JsonLdObject;
}

export type FaqEntry = { question: string; answer: string };

/**
 * FAQPage.
 *
 * Every question and answer passed here MUST also be visible in the rendered
 * HTML. Schema-only FAQs are a manual action risk, and since 2023 Google shows
 * FAQ rich results for a narrow set of sites anyway. The value now is answer
 * extraction by AI engines, which read the visible text as well.
 */
export function faqPage(opts: { url: string; faqs: FaqEntry[] }): JsonLdObject | undefined {
  if (opts.faqs.length === 0) return undefined;
  return compact({
    "@type": "FAQPage",
    "@id": `${opts.url}#faq`,
    mainEntity: opts.faqs.map((faq) => ({
      "@type": "Question",
      name: faq.question,
      acceptedAnswer: { "@type": "Answer", text: faq.answer },
    })),
  }) as JsonLdObject;
}

export type HowToStep = {
  name: string;
  text: string;
  url?: string;
  imageUrl?: string;
};

export function howTo(opts: {
  url: string;
  name: string;
  description: string;
  steps: HowToStep[];
  totalTime?: string;
  tools?: string[];
  supplies?: string[];
}): JsonLdObject | undefined {
  if (opts.steps.length === 0) return undefined;
  return compact({
    "@type": "HowTo",
    "@id": `${opts.url}#howto`,
    name: opts.name,
    description: opts.description,
    totalTime: opts.totalTime,
    tool: opts.tools?.map((name) => ({ "@type": "HowToTool", name })),
    supply: opts.supplies?.map((name) => ({ "@type": "HowToSupply", name })),
    step: opts.steps.map((step, index) =>
      compact({
        "@type": "HowToStep",
        position: index + 1,
        name: step.name,
        text: step.text,
        url: step.url,
        image: step.imageUrl,
      }),
    ),
  }) as JsonLdObject;
}

/**
 * SpeakableSpecification.
 *
 * Names the CSS selectors that hold the canonical answer on a page. Voice
 * surfaces and some answer engines read it. Point it at short, self-contained
 * sentences that restate their subject, never at a heading alone.
 */
export function speakable(cssSelectors: string[]): JsonLdObject | undefined {
  if (cssSelectors.length === 0) return undefined;
  return {
    "@type": "SpeakableSpecification",
    cssSelector: cssSelectors,
  };
}

export type WebPageOptions = {
  url: string;
  name: string;
  description: string;
  isPartOf: NodeRef;
  breadcrumb?: NodeRef;
  primaryImageUrl?: string;
  datePublished?: string | Date;
  dateModified?: string | Date;
  inLanguage?: string;
  speakableSelectors?: string[];
  about?: NodeRef;
};

export function webPage(opts: WebPageOptions): JsonLdObject {
  return compact({
    "@type": "WebPage",
    "@id": `${opts.url}#webpage`,
    url: opts.url,
    name: opts.name,
    description: opts.description,
    isPartOf: opts.isPartOf,
    breadcrumb: opts.breadcrumb,
    primaryImageOfPage: opts.primaryImageUrl
      ? { "@type": "ImageObject", url: opts.primaryImageUrl }
      : undefined,
    datePublished: isoDate(opts.datePublished),
    dateModified: isoDate(opts.dateModified),
    inLanguage: opts.inLanguage ?? "en-US",
    about: opts.about,
    speakable: opts.speakableSelectors?.length
      ? speakable(opts.speakableSelectors)
      : undefined,
  }) as JsonLdObject;
}

export type CollectionPageOptions = {
  url: string;
  name: string;
  description: string;
  isPartOf: NodeRef;
  breadcrumb?: NodeRef;
  itemList?: JsonLdObject;
  dateModified?: string | Date;
};

export function collectionPage(opts: CollectionPageOptions): JsonLdObject {
  return compact({
    "@type": "CollectionPage",
    "@id": `${opts.url}#collection`,
    url: opts.url,
    name: opts.name,
    description: opts.description,
    isPartOf: opts.isPartOf,
    breadcrumb: opts.breadcrumb,
    dateModified: isoDate(opts.dateModified),
    mainEntity: opts.itemList,
  }) as JsonLdObject;
}

export { ref };

/**
 * Code Kit: bot-economics robots policy.
 * Implements checks: crawl-robots-generated, crawl-bot-economics,
 *                    crawl-private-routes-disallowed, crawl-sitemap-declared
 *
 * The decision nobody makes deliberately: which crawlers get your content.
 * The useful split is not "AI bots" versus "search bots". It is whether a
 * crawler can send you traffic or a citation in return for the bandwidth.
 *
 *   Search crawlers      index you and send clicks.            Allow.
 *   Citation crawlers    fetch a page to answer a live query
 *                        and name the source.                  Allow.
 *   Training crawlers    build a model. No link, no click,
 *                        no attribution.                       Your call.
 *
 * Blocking a training crawler does not remove you from that company's answer
 * engine if its citation crawler is a separate user agent, which for OpenAI,
 * Anthropic, Perplexity and Google it currently is. That asymmetry is the whole
 * mechanism.
 */

export type CrawlerClass = "search" | "citation" | "training" | "seo-tool" | "archive";

export type CrawlerProfile = {
  userAgent: string;
  operator: string;
  class: CrawlerClass;
  /** Does allowing this crawler produce visits or citations? */
  sendsReferralTraffic: boolean;
  purpose: string;
  documentationUrl?: string;
};

/**
 * Crawler registry.
 *
 * Verified against each operator's published documentation. Recheck quarterly:
 * user agent names change, and new ones appear faster than anyone updates
 * robots.txt.
 */
export const CRAWLERS: CrawlerProfile[] = [
  {
    userAgent: "Googlebot",
    operator: "Google",
    class: "search",
    sendsReferralTraffic: true,
    purpose: "Google Search index. Also feeds AI Overviews.",
    documentationUrl: "https://developers.google.com/search/docs/crawling-indexing/overview-google-crawlers",
  },
  {
    userAgent: "Bingbot",
    operator: "Microsoft",
    class: "search",
    sendsReferralTraffic: true,
    purpose: "Bing index. Also the retrieval layer behind Copilot.",
    documentationUrl: "https://www.bing.com/webmasters/help/which-crawlers-does-bing-use-8c184ec0",
  },
  {
    userAgent: "DuckDuckBot",
    operator: "DuckDuckGo",
    class: "search",
    sendsReferralTraffic: true,
    purpose: "DuckDuckGo index.",
  },
  {
    userAgent: "Applebot",
    operator: "Apple",
    class: "search",
    sendsReferralTraffic: true,
    purpose: "Siri and Spotlight suggestions.",
    documentationUrl: "https://support.apple.com/en-us/119829",
  },
  {
    userAgent: "OAI-SearchBot",
    operator: "OpenAI",
    class: "citation",
    sendsReferralTraffic: true,
    purpose: "ChatGPT search index. Links back to the source.",
    documentationUrl: "https://platform.openai.com/docs/bots",
  },
  {
    userAgent: "ChatGPT-User",
    operator: "OpenAI",
    class: "citation",
    sendsReferralTraffic: true,
    purpose: "Live fetch when a user asks ChatGPT about a specific URL.",
    documentationUrl: "https://platform.openai.com/docs/bots",
  },
  {
    userAgent: "PerplexityBot",
    operator: "Perplexity",
    class: "citation",
    sendsReferralTraffic: true,
    purpose: "Perplexity answer index. Cites sources inline.",
    documentationUrl: "https://docs.perplexity.ai/guides/bots",
  },
  {
    userAgent: "ClaudeBot",
    operator: "Anthropic",
    class: "citation",
    sendsReferralTraffic: true,
    purpose: "Claude retrieval and citation.",
    documentationUrl: "https://support.anthropic.com/en/articles/8896518",
  },
  {
    userAgent: "Claude-User",
    operator: "Anthropic",
    class: "citation",
    sendsReferralTraffic: true,
    purpose: "Live fetch when a Claude user asks about a specific URL.",
  },
  {
    userAgent: "Applebot-Extended",
    operator: "Apple",
    class: "training",
    sendsReferralTraffic: false,
    purpose: "Apple foundation model training. Opting out does not affect Siri.",
    documentationUrl: "https://support.apple.com/en-us/119829",
  },
  {
    userAgent: "GPTBot",
    operator: "OpenAI",
    class: "training",
    sendsReferralTraffic: false,
    purpose: "Model training corpus. Separate from OAI-SearchBot.",
    documentationUrl: "https://platform.openai.com/docs/bots",
  },
  {
    userAgent: "Google-Extended",
    operator: "Google",
    class: "training",
    sendsReferralTraffic: false,
    purpose: "Gemini training. Blocking it does not remove you from Search.",
    documentationUrl: "https://developers.google.com/search/docs/crawling-indexing/overview-google-crawlers",
  },
  {
    userAgent: "anthropic-ai",
    operator: "Anthropic",
    class: "training",
    sendsReferralTraffic: false,
    purpose: "Legacy training crawler identifier.",
  },
  {
    userAgent: "CCBot",
    operator: "Common Crawl",
    class: "training",
    sendsReferralTraffic: false,
    purpose: "Open crawl corpus used as training data by many labs.",
    documentationUrl: "https://commoncrawl.org/ccbot",
  },
  {
    userAgent: "Bytespider",
    operator: "ByteDance",
    class: "training",
    sendsReferralTraffic: false,
    purpose: "Training corpus. Widely reported to ignore robots.txt.",
  },
  {
    userAgent: "AhrefsBot",
    operator: "Ahrefs",
    class: "seo-tool",
    sendsReferralTraffic: false,
    purpose: "Backlink index. Allowing it makes your own backlink data visible to you and to competitors.",
  },
  {
    userAgent: "SemrushBot",
    operator: "Semrush",
    class: "seo-tool",
    sendsReferralTraffic: false,
    purpose: "Competitive index. Same trade as AhrefsBot.",
  },
  {
    userAgent: "ia_archiver",
    operator: "Internet Archive",
    class: "archive",
    sendsReferralTraffic: false,
    purpose: "Wayback Machine preservation.",
  },
];

export type RobotsPolicy = {
  /** Crawler classes permitted to crawl. */
  allowClasses: CrawlerClass[];
  /** Paths every permitted crawler is denied. */
  disallowPaths: string[];
  /** Absolute sitemap URLs. */
  sitemaps: string[];
  /** Canonical host, no scheme. Bing reads this; Google ignores it. */
  host?: string;
  /** Extra user agents to deny outright, beyond the class rules. */
  denyUserAgents?: string[];
  /** Emit the reasoning as comments. Leave on: people read this file. */
  annotate?: boolean;
  crawlers?: CrawlerProfile[];
};

export const RECOMMENDED_POLICY: Pick<RobotsPolicy, "allowClasses"> = {
  // Allow anything that can send a visit or a citation. Deny training-only
  // crawlers and commercial SEO indexes, which take bandwidth and return nothing.
  allowClasses: ["search", "citation"],
};

export type RobotsRule = {
  userAgent: string | string[];
  allow?: string | string[];
  disallow?: string | string[];
};

/** Structured output, for `app/robots.ts` in Next.js. */
export function robotsRules(policy: RobotsPolicy): RobotsRule[] {
  const crawlers = policy.crawlers ?? CRAWLERS;
  const allowed = crawlers.filter((c) => policy.allowClasses.includes(c.class));
  const denied = crawlers.filter((c) => !policy.allowClasses.includes(c.class));
  const denyList = [
    ...denied.map((c) => c.userAgent),
    ...(policy.denyUserAgents ?? []),
  ];

  const rules: RobotsRule[] = [
    // The wildcard rule governs every crawler not named below, including ones
    // that do not exist yet.
    { userAgent: "*", allow: "/", disallow: policy.disallowPaths },
  ];

  for (const crawler of allowed) {
    rules.push({ userAgent: crawler.userAgent, allow: "/", disallow: policy.disallowPaths });
  }
  for (const userAgent of denyList) {
    rules.push({ userAgent, disallow: "/" });
  }

  return rules;
}

/** Plain text output, for a static robots.txt or the generator tool. */
export function robotsTxt(policy: RobotsPolicy): string {
  const crawlers = policy.crawlers ?? CRAWLERS;
  const annotate = policy.annotate ?? true;
  const lines: string[] = [];

  if (annotate) {
    lines.push(
      "# robots.txt",
      "#",
      "# Policy: allow any crawler that can return a visit or a citation.",
      "# Deny crawlers that consume bandwidth and return neither.",
      "#",
    );
  }

  const emit = (rule: RobotsRule, comment?: string) => {
    if (annotate && comment) lines.push(`# ${comment}`);
    const agents = Array.isArray(rule.userAgent) ? rule.userAgent : [rule.userAgent];
    for (const agent of agents) lines.push(`User-agent: ${agent}`);
    for (const allow of toArray(rule.allow)) lines.push(`Allow: ${allow}`);
    for (const disallow of toArray(rule.disallow)) lines.push(`Disallow: ${disallow}`);
    lines.push("");
  };

  emit(
    { userAgent: "*", allow: "/", disallow: policy.disallowPaths },
    "Default policy for every crawler not named below.",
  );

  for (const crawler of crawlers.filter((c) => policy.allowClasses.includes(c.class))) {
    emit(
      { userAgent: crawler.userAgent, allow: "/", disallow: policy.disallowPaths },
      `${crawler.operator}: ${crawler.purpose}`,
    );
  }

  const denied = crawlers.filter((c) => !policy.allowClasses.includes(c.class));
  for (const crawler of denied) {
    emit(
      { userAgent: crawler.userAgent, disallow: "/" },
      `${crawler.operator}: ${crawler.purpose} No referral traffic.`,
    );
  }
  for (const userAgent of policy.denyUserAgents ?? []) {
    emit({ userAgent, disallow: "/" });
  }

  for (const sitemap of policy.sitemaps) lines.push(`Sitemap: ${sitemap}`);
  if (policy.host) lines.push(`Host: ${policy.host}`);

  return `${lines.join("\n").replace(/\n{3,}/g, "\n\n").trimEnd()}\n`;
}

function toArray(value: string | string[] | undefined): string[] {
  if (!value) return [];
  return Array.isArray(value) ? value : [value];
}