@cogenta/seo 0.1.0

package/dist/sitemap.js

@@ -0,0 +1,197 @@
+import { CogentaError } from '@cogenta/core';
+import { buildHreflangMap } from './hreflang.js';
+import { indexableResources } from './indexable.js';
+import { absoluteUrl, canonicalUrl } from './url.js';
+import { renderXmlDocument, xmlElementByteLength } from './xml.js';
+/**
+ * `sitemap.xml`, split and indexed when it has to be.
+ *
+ * The two limits are the protocol's, not a preference: sitemaps.org caps a
+ * single file at **50 000 URLs and 50 MB uncompressed**, and a file that
+ * exceeds either is rejected whole. Both are enforced, because a site can hit
+ * the byte limit well before the URL limit once `xhtml:link` alternates are
+ * included — twelve languages multiply the size of every entry by roughly
+ * thirteen while the URL count stays put.
+ */
+/** sitemaps.org: 50 000 URLs per file, and the same cap on entries in an index. */
+export const SITEMAP_MAX_URLS = 50_000;
+/** sitemaps.org: 50 MB uncompressed, counted as 50 × 2²⁰ bytes. */
+export const SITEMAP_MAX_BYTES = 52_428_800;
+const SITEMAP_NS = 'http://www.sitemaps.org/schemas/sitemap/0.9';
+const XHTML_NS = 'http://www.w3.org/1999/xhtml';
+const DEFAULT_INDEX_PATH = '/sitemap.xml';
+const defaultChunkPath = (index) => `/sitemap-${index}.xml`;
+function urlElement(url) {
+    const children = [{ name: 'loc', text: url.loc }];
+    if (url.lastmod !== undefined)
+        children.push({ name: 'lastmod', text: url.lastmod });
+    if (url.changefreq !== undefined)
+        children.push({ name: 'changefreq', text: url.changefreq });
+    if (url.priority !== undefined) {
+        children.push({ name: 'priority', text: clampPriority(url.priority) });
+    }
+    for (const alternate of url.alternates ?? []) {
+        children.push({
+            name: 'xhtml:link',
+            attributes: { rel: 'alternate', hreflang: alternate.hreflang, href: alternate.href },
+        });
+    }
+    return { name: 'url', children };
+}
+function clampPriority(priority) {
+    const bounded = Math.min(1, Math.max(0, priority));
+    return bounded.toFixed(1);
+}
+/**
+ * Bytes a chunk costs before any URL: declaration, root tag with both
+ * namespaces, closing tag and newlines. Measured rather than estimated so the
+ * budget stays right if the header ever changes.
+ */
+function chunkOverhead() {
+    return Buffer.byteLength(renderXmlDocument(urlsetElement([])), 'utf8');
+}
+function urlsetElement(urls) {
+    return {
+        name: 'urlset',
+        attributes: { xmlns: SITEMAP_NS, 'xmlns:xhtml': XHTML_NS },
+        children: urls.map(urlElement),
+    };
+}
+function splitIntoChunks(urls, maxUrls, maxBytes) {
+    const overhead = chunkOverhead();
+    const chunks = [];
+    let current = [];
+    let size = overhead;
+    for (const url of urls) {
+        // +1 for the newline the renderer puts between siblings.
+        const cost = xmlElementByteLength(urlElement(url), 1) + 1;
+        if (overhead + cost > maxBytes) {
+            throw new CogentaError({
+                code: 'CONTENT_INVALID',
+                message: `A single sitemap entry for "${url.loc}" exceeds the ${maxBytes}-byte file limit.`,
+                hint: 'It almost certainly carries far too many hreflang alternates. A sitemap entry cannot be split across files.',
+                details: { loc: url.loc, bytes: cost, maxBytes },
+            });
+        }
+        if (current.length >= maxUrls || size + cost > maxBytes) {
+            chunks.push(current);
+            current = [];
+            size = overhead;
+        }
+        current.push(url);
+        size += cost;
+    }
+    if (current.length > 0 || chunks.length === 0)
+        chunks.push(current);
+    return chunks;
+}
+/**
+ * The files to write for a set of URLs.
+ *
+ * One file below the limits, an index plus N chunks above them. The caller
+ * writes what it gets and never has to know which case it is in — a shape that
+ * makes the split untestable in production is how sites discover at 60 000 URLs
+ * that nobody ever exercised the second branch.
+ */
+export function buildSitemap(site, urls, options = {}) {
+    const maxUrls = options.maxUrls ?? SITEMAP_MAX_URLS;
+    const maxBytes = options.maxBytes ?? SITEMAP_MAX_BYTES;
+    if (maxUrls < 1 || maxBytes < 1) {
+        throw new CogentaError({
+            code: 'CONFIG_INVALID',
+            message: 'A sitemap file must allow at least one URL and one byte.',
+            hint: `Leave maxUrls and maxBytes unset to use the protocol limits (${SITEMAP_MAX_URLS} URLs, ${SITEMAP_MAX_BYTES} bytes).`,
+            details: { maxUrls, maxBytes },
+        });
+    }
+    const indexPath = options.indexPath ?? DEFAULT_INDEX_PATH;
+    const chunkPath = options.chunkPath ?? defaultChunkPath;
+    const chunks = splitIntoChunks(urls, maxUrls, maxBytes);
+    if (chunks.length === 1) {
+        const only = chunks[0] ?? [];
+        return [
+            {
+                path: indexPath,
+                contents: renderXmlDocument(urlsetElement(only)),
+                isIndex: false,
+                urlCount: only.length,
+            },
+        ];
+    }
+    // The index cap is the protocol's own, deliberately *not* `maxUrls`. The two
+    // limits happen to share a number, and conflating them means that lowering
+    // `maxUrls` — which a caller does to force a split, and a test does to
+    // exercise one — also lowers how many files an index may list, so the split
+    // it just asked for is rejected.
+    const maxIndexEntries = options.maxIndexEntries ?? SITEMAP_MAX_URLS;
+    if (chunks.length > maxIndexEntries) {
+        throw new CogentaError({
+            code: 'CONTENT_INVALID',
+            message: `The site needs ${chunks.length} sitemap files, more than the ${maxIndexEntries} an index may list.`,
+            hint: 'A sitemap index cannot itself be indexed. Split the site across several hosts, or raise maxUrls so each file holds more.',
+            details: { files: chunks.length, maxIndexEntries },
+        });
+    }
+    const files = chunks.map((chunk, position) => ({
+        path: chunkPath(position + 1),
+        contents: renderXmlDocument(urlsetElement(chunk)),
+        isIndex: false,
+        urlCount: chunk.length,
+    }));
+    const lastmod = options.lastmod ?? newestLastmod(urls);
+    const index = {
+        name: 'sitemapindex',
+        attributes: { xmlns: SITEMAP_NS },
+        children: files.map((file) => ({
+            name: 'sitemap',
+            children: [
+                { name: 'loc', text: absoluteUrl(site, file.path) },
+                lastmod === undefined ? null : { name: 'lastmod', text: lastmod },
+            ],
+        })),
+    };
+    return [
+        {
+            path: indexPath,
+            contents: renderXmlDocument(index),
+            isIndex: true,
+            urlCount: files.length,
+        },
+        ...files,
+    ];
+}
+function newestLastmod(urls) {
+    let newest;
+    for (const url of urls) {
+        if (url.lastmod === undefined)
+            continue;
+        if (newest === undefined || url.lastmod > newest)
+            newest = url.lastmod;
+    }
+    return newest;
+}
+/**
+ * Sitemap URLs for a set of resources: published only, alternates attached.
+ *
+ * `lastmod` is `updatedAt` rather than `publishedAt`: the field answers "has
+ * this changed since you last fetched it", which is what makes a crawler come
+ * back for a corrected article.
+ */
+export function sitemapUrlsFor(site, resources, options = {}) {
+    const published = indexableResources(site, resources, options);
+    const hreflang = buildHreflangMap(site, resources, options);
+    const urls = [];
+    for (const resource of published) {
+        const loc = canonicalUrl(site, resource);
+        if (loc === null)
+            continue;
+        const alternates = hreflang.get(resource.entry.id);
+        urls.push({
+            loc,
+            lastmod: resource.entry.updatedAt,
+            ...(alternates === undefined ? {} : { alternates }),
+        });
+    }
+    return urls;
+}
+//# sourceMappingURL=sitemap.js.map

package/dist/sitemap.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sitemap.js","sourceRoot":"","sources":["../src/sitemap.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA;AAE5C,OAAO,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAA;AAChD,OAAO,EAAyB,kBAAkB,EAAE,MAAM,gBAAgB,CAAA;AAE1E,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,UAAU,CAAA;AACpD,OAAO,EAAE,iBAAiB,EAAmB,oBAAoB,EAAE,MAAM,UAAU,CAAA;AAEnF;;;;;;;;;GASG;AAEH,mFAAmF;AACnF,MAAM,CAAC,MAAM,gBAAgB,GAAG,MAAM,CAAA;AAEtC,mEAAmE;AACnE,MAAM,CAAC,MAAM,iBAAiB,GAAG,UAAU,CAAA;AAE3C,MAAM,UAAU,GAAG,6CAA6C,CAAA;AAChE,MAAM,QAAQ,GAAG,8BAA8B,CAAA;AA2C/C,MAAM,kBAAkB,GAAG,cAAc,CAAA;AACzC,MAAM,gBAAgB,GAAG,CAAC,KAAa,EAAU,EAAE,CAAC,YAAY,KAAK,MAAM,CAAA;AAE3E,SAAS,UAAU,CAAC,GAAe;IACjC,MAAM,QAAQ,GAA0B,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,CAAC,GAAG,EAAE,CAAC,CAAA;IAExE,IAAI,GAAG,CAAC,OAAO,KAAK,SAAS;QAAE,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,GAAG,CAAC,OAAO,EAAE,CAAC,CAAA;IACpF,IAAI,GAAG,CAAC,UAAU,KAAK,SAAS;QAAE,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,YAAY,EAAE,IAAI,EAAE,GAAG,CAAC,UAAU,EAAE,CAAC,CAAA;IAC7F,IAAI,GAAG,CAAC,QAAQ,KAAK,SAAS,EAAE,CAAC;QAC/B,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,aAAa,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAA;IACxE,CAAC;IAED,KAAK,MAAM,SAAS,IAAI,GAAG,CAAC,UAAU,IAAI,EAAE,EAAE,CAAC;QAC7C,QAAQ,CAAC,IAAI,CAAC;YACZ,IAAI,EAAE,YAAY;YAClB,UAAU,EAAE,EAAE,GAAG,EAAE,WAAW,EAAE,QAAQ,EAAE,SAAS,CAAC,QAAQ,EAAE,IAAI,EAAE,SAAS,CAAC,IAAI,EAAE;SACrF,CAAC,CAAA;IACJ,CAAC;IAED,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAA;AAClC,CAAC;AAED,SAAS,aAAa,CAAC,QAAgB;IACrC,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC,CAAA;IAClD,OAAO,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,CAAA;AAC3B,CAAC;AAED;;;;GAIG;AACH,SAAS,aAAa;IACpB,OAAO,MAAM,CAAC,UAAU,CAAC,iBAAiB,CAAC,aAAa,CAAC,EAAE,CAAC,CAAC,EAAE,MAAM,CAAC,CAAA;AACxE,CAAC;AAED,SAAS,aAAa,CAAC,IAA2B;IAChD,OAAO;QACL,IAAI,EAAE,QAAQ;QACd,UAAU,EAAE,EAAE,KAAK,EAAE,UAAU,EAAE,aAAa,EAAE,QAAQ,EAAE;QAC1D,QAAQ,EAAE,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC;KAC/B,CAAA;AACH,CAAC;AAED,SAAS,eAAe,CACtB,IAA2B,EAC3B,OAAe,EACf,QAAgB;IAEhB,MAAM,QAAQ,GAAG,aAAa,EAAE,CAAA;IAChC,MAAM,MAAM,GAAmB,EAAE,CAAA;IACjC,IAAI,OAAO,GAAiB,EAAE,CAAA;IAC9B,IAAI,IAAI,GAAG,QAAQ,CAAA;IAEnB,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,yDAAyD;QACzD,MAAM,IAAI,GAAG,oBAAoB,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,GAAG,CAAC,CAAA;QAEzD,IAAI,QAAQ,GAAG,IAAI,GAAG,QAAQ,EAAE,CAAC;YAC/B,MAAM,IAAI,YAAY,CAAC;gBACrB,IAAI,EAAE,iBAAiB;gBACvB,OAAO,EAAE,+BAA+B,GAAG,CAAC,GAAG,iBAAiB,QAAQ,mBAAmB;gBAC3F,IAAI,EAAE,6GAA6G;gBACnH,OAAO,EAAE,EAAE,GAAG,EAAE,GAAG,CAAC,GAAG,EAAE,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE;aACjD,CAAC,CAAA;QACJ,CAAC;QAED,IAAI,OAAO,CAAC,MAAM,IAAI,OAAO,IAAI,IAAI,GAAG,IAAI,GAAG,QAAQ,EAAE,CAAC;YACxD,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAA;YACpB,OAAO,GAAG,EAAE,CAAA;YACZ,IAAI,GAAG,QAAQ,CAAA;QACjB,CAAC;QAED,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;QACjB,IAAI,IAAI,IAAI,CAAA;IACd,CAAC;IAED,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAA;IACnE,OAAO,MAAM,CAAA;AACf,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,YAAY,CAC1B,IAAa,EACb,IAA2B,EAC3B,OAAO,GAAmB,EAAE;IAE5B,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,gBAAgB,CAAA;IACnD,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,iBAAiB,CAAA;IAEtD,IAAI,OAAO,GAAG,CAAC,IAAI,QAAQ,GAAG,CAAC,EAAE,CAAC;QAChC,MAAM,IAAI,YAAY,CAAC;YACrB,IAAI,EAAE,gBAAgB;YACtB,OAAO,EAAE,0DAA0D;YACnE,IAAI,EAAE,gEAAgE,gBAAgB,UAAU,iBAAiB,UAAU;YAC3H,OAAO,EAAE,EAAE,OAAO,EAAE,QAAQ,EAAE;SAC/B,CAAC,CAAA;IACJ,CAAC;IAED,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,kBAAkB,CAAA;IACzD,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,gBAAgB,CAAA;IACvD,MAAM,MAAM,GAAG,eAAe,CAAC,IAAI,EAAE,OAAO,EAAE,QAAQ,CAAC,CAAA;IAEvD,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACxB,MAAM,IAAI,GAAG,MAAM,CAAC,CAAC,CAAC,IAAI,EAAE,CAAA;QAC5B,OAAO;YACL;gBACE,IAAI,EAAE,SAAS;gBACf,QAAQ,EAAE,iBAAiB,CAAC,aAAa,CAAC,IAAI,CAAC,CAAC;gBAChD,OAAO,EAAE,KAAK;gBACd,QAAQ,EAAE,IAAI,CAAC,MAAM;aACtB;SACF,CAAA;IACH,CAAC;IAED,6EAA6E;IAC7E,2EAA2E;IAC3E,uEAAuE;IACvE,4EAA4E;IAC5E,iCAAiC;IACjC,MAAM,eAAe,GAAG,OAAO,CAAC,eAAe,IAAI,gBAAgB,CAAA;IACnE,IAAI,MAAM,CAAC,MAAM,GAAG,eAAe,EAAE,CAAC;QACpC,MAAM,IAAI,YAAY,CAAC;YACrB,IAAI,EAAE,iBAAiB;YACvB,OAAO,EAAE,kBAAkB,MAAM,CAAC,MAAM,iCAAiC,eAAe,qBAAqB;YAC7G,IAAI,EAAE,0HAA0H;YAChI,OAAO,EAAE,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,EAAE;SACnD,CAAC,CAAA;IACJ,CAAC;IAED,MAAM,KAAK,GAAkB,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,QAAQ,EAAE,EAAE,CAAC,CAAC;QAC5D,IAAI,EAAE,SAAS,CAAC,QAAQ,GAAG,CAAC,CAAC;QAC7B,QAAQ,EAAE,iBAAiB,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC;QACjD,OAAO,EAAE,KAAK;QACd,QAAQ,EAAE,KAAK,CAAC,MAAM;KACvB,CAAC,CAAC,CAAA;IAEH,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,aAAa,CAAC,IAAI,CAAC,CAAA;IACtD,MAAM,KAAK,GAAe;QACxB,IAAI,EAAE,cAAc;QACpB,UAAU,EAAE,EAAE,KAAK,EAAE,UAAU,EAAE;QACjC,QAAQ,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;YAC7B,IAAI,EAAE,SAAS;YACf,QAAQ,EAAE;gBACR,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,WAAW,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,CAAC,EAAE;gBACnD,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,OAAO,EAAE;aAClE;SACF,CAAC,CAAC;KACJ,CAAA;IAED,OAAO;QACL;YACE,IAAI,EAAE,SAAS;YACf,QAAQ,EAAE,iBAAiB,CAAC,KAAK,CAAC;YAClC,OAAO,EAAE,IAAI;YACb,QAAQ,EAAE,KAAK,CAAC,MAAM;SACvB;QACD,GAAG,KAAK;KACT,CAAA;AACH,CAAC;AAED,SAAS,aAAa,CAAC,IAA2B;IAChD,IAAI,MAA0B,CAAA;IAC9B,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,IAAI,GAAG,CAAC,OAAO,KAAK,SAAS;YAAE,SAAQ;QACvC,IAAI,MAAM,KAAK,SAAS,IAAI,GAAG,CAAC,OAAO,GAAG,MAAM;YAAE,MAAM,GAAG,GAAG,CAAC,OAAO,CAAA;IACxE,CAAC;IACD,OAAO,MAAM,CAAA;AACf,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,cAAc,CAC5B,IAAa,EACb,SAAiC,EACjC,OAAO,GAAmB,EAAE;IAE5B,MAAM,SAAS,GAAG,kBAAkB,CAAC,IAAI,EAAE,SAAS,EAAE,OAAO,CAAC,CAAA;IAC9D,MAAM,QAAQ,GAAG,gBAAgB,CAAC,IAAI,EAAE,SAAS,EAAE,OAAO,CAAC,CAAA;IAE3D,MAAM,IAAI,GAAiB,EAAE,CAAA;IAC7B,KAAK,MAAM,QAAQ,IAAI,SAAS,EAAE,CAAC;QACjC,MAAM,GAAG,GAAG,YAAY,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAA;QACxC,IAAI,GAAG,KAAK,IAAI;YAAE,SAAQ;QAE1B,MAAM,UAAU,GAAG,QAAQ,CAAC,GAAG,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,CAAA;QAClD,IAAI,CAAC,IAAI,CAAC;YACR,GAAG;YACH,OAAO,EAAE,QAAQ,CAAC,KAAK,CAAC,SAAS;YACjC,GAAG,CAAC,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC;SACpD,CAAC,CAAA;IACJ,CAAC;IACD,OAAO,IAAI,CAAA;AACb,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,67 @@
+import type { CollectionDefinition, ContentEntry } from '@cogenta/schema';
+/**
+ * What the SEO layer needs to know about the site.
+ *
+ * Deliberately not the whole site configuration: this package is consumed by
+ * the render process, which owns neither secrets nor a database connection
+ * (rule R5). Everything here is public information that already appears in the
+ * page source.
+ */
+export interface SeoSite {
+    /** Absolute origin, with or without a path prefix. `https://example.com`. */
+    readonly baseUrl: string;
+    /** The site name, used in `og:site_name` and as the feed title. */
+    readonly name: string;
+    readonly description?: string;
+    /** The language a URL carries when it has no locale prefix. */
+    readonly defaultLocale: string;
+    /** Every language the site serves. Used to validate what a family claims. */
+    readonly locales?: readonly string[];
+    /**
+     * Whether the default locale is served without its prefix — `/blog/hello`
+     * next to `/fr/blog/bonjour`.
+     *
+     * It has to be stated rather than guessed: `buildPath` always prefixes a
+     * localised route, while `matchPath` accepts both forms, so only the site
+     * knows which of the two a crawler will find. Guessing produces canonical
+     * URLs that 301 to themselves.
+     */
+    readonly unprefixedDefaultLocale?: boolean;
+    /** `@handle` for `twitter:site`. */
+    readonly twitterSite?: string;
+}
+/** An entry together with the collection that describes it. */
+export interface SeoResource<TEntry extends ContentEntry = ContentEntry> {
+    readonly collection: CollectionDefinition;
+    readonly entry: TEntry;
+}
+export interface SeoImage {
+    readonly url: string;
+    readonly width?: number;
+    readonly height?: number;
+    readonly alt?: string;
+    readonly mimeType?: string;
+}
+/** A related entity — an author, a tag — reduced to what a crawler can use. */
+export interface SeoReference {
+    readonly name: string;
+    readonly url?: string;
+    /** schema.org type, when the caller knows it. `Person` for an author. */
+    readonly type?: string;
+}
+/**
+ * How to turn an identifier into something publishable.
+ *
+ * A `media` field stores a media id and a `relation` field stores an entry id;
+ * neither is meaningful to a crawler. Resolution needs the media pipeline and
+ * the content store, which this package must not reach, so it is injected.
+ *
+ * Both are optional, and an unresolved id is **omitted** rather than emitted
+ * raw: `"image": "0192f3a1-…"` is worse than no image at all, because it makes
+ * structured data invalid rather than incomplete.
+ */
+export interface SeoResolvers {
+    readonly media?: (id: string) => SeoImage | null;
+    readonly reference?: (collection: string, id: string) => SeoReference | null;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAA;AAEzE;;;;;;;GAOG;AACH,MAAM,WAAW,OAAO;IACtB,6EAA6E;IAC7E,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,mEAAmE;IACnE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;IAC7B,+DAA+D;IAC/D,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAA;IAC9B,6EAA6E;IAC7E,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IACpC;;;;;;;;OAQG;IACH,QAAQ,CAAC,uBAAuB,CAAC,EAAE,OAAO,CAAA;IAC1C,oCAAoC;IACpC,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAC9B;AAED,+DAA+D;AAC/D,MAAM,WAAW,WAAW,CAAC,MAAM,SAAS,YAAY,GAAG,YAAY;IACrE,QAAQ,CAAC,UAAU,EAAE,oBAAoB,CAAA;IACzC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CACvB;AAED,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAC3B;AAED,+EAA+E;AAC/E,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAA;IACrB,yEAAyE;IACzE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CACvB;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,QAAQ,GAAG,IAAI,CAAA;IAChD,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,KAAK,YAAY,GAAG,IAAI,CAAA;CAC7E"}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/dist/url.d.ts

@@ -0,0 +1,41 @@
+import { type CollectionDefinition, type ContentEntry } from '@cogenta/schema';
+import type { SeoResource, SeoSite } from './types.js';
+/**
+ * Every URL this package emits is absolute, and every one of them is built
+ * here.
+ *
+ * Sitemaps, feeds and `hreflang` all reject relative URLs, and a canonical that
+ * disagrees with the sitemap by a trailing slash is treated as a different page
+ * — the single most common cause of "Google indexed the wrong URL". One
+ * function, one form.
+ */
+/** `https://example.com/blog/` and `https://example.com/blog` are the same origin. */
+export declare function normaliseBaseUrl(baseUrl: string): string;
+/**
+ * An absolute URL for a site-relative path.
+ *
+ * The path is expected to be already encoded — `buildPath` percent-encodes each
+ * segment — so it is concatenated rather than passed through `new URL`, which
+ * would double-encode a `%` that is already an escape.
+ */
+export declare function absoluteUrl(site: SeoSite, path: string): string;
+/**
+ * The route parameters an entry supplies.
+ *
+ * A pattern segment `:slug` reads `values.slug`; `:id` reads the system field,
+ * since it is the only parameter an entry always has and the natural fallback
+ * for a collection with no slug.
+ */
+export declare function routeParams(collection: CollectionDefinition, entry: ContentEntry): Record<string, string>;
+/** True when the collection can produce a URL at all. */
+export declare function hasRoute(collection: CollectionDefinition): boolean;
+/**
+ * The canonical, absolute URL of an entry, or null when it has no route.
+ *
+ * Null rather than an exception: a collection without `routing` is a perfectly
+ * ordinary thing — an author, a tag, a site setting — and asking "what is the
+ * canonical URL of every entry" must not blow up on the first one that has
+ * none.
+ */
+export declare function canonicalUrl(site: SeoSite, resource: SeoResource): string | null;
+//# sourceMappingURL=url.d.ts.map

package/dist/url.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"url.d.ts","sourceRoot":"","sources":["../src/url.ts"],"names":[],"mappings":"AACA,OAAO,EAAa,KAAK,oBAAoB,EAAE,KAAK,YAAY,EAAE,MAAM,iBAAiB,CAAA;AACzF,OAAO,KAAK,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,YAAY,CAAA;AAEtD;;;;;;;;GAQG;AAEH,sFAAsF;AACtF,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAwBxD;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAI/D;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CACzB,UAAU,EAAE,oBAAoB,EAChC,KAAK,EAAE,YAAY,GAClB,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAwBxB;AAED,yDAAyD;AACzD,wBAAgB,QAAQ,CAAC,UAAU,EAAE,oBAAoB,GAAG,OAAO,CAElE;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,WAAW,GAAG,MAAM,GAAG,IAAI,CAoBhF"}

package/dist/url.js

@@ -0,0 +1,110 @@
+import { CogentaError } from '@cogenta/core';
+import { buildPath } from '@cogenta/schema';
+/**
+ * Every URL this package emits is absolute, and every one of them is built
+ * here.
+ *
+ * Sitemaps, feeds and `hreflang` all reject relative URLs, and a canonical that
+ * disagrees with the sitemap by a trailing slash is treated as a different page
+ * — the single most common cause of "Google indexed the wrong URL". One
+ * function, one form.
+ */
+/** `https://example.com/blog/` and `https://example.com/blog` are the same origin. */
+export function normaliseBaseUrl(baseUrl) {
+    let parsed;
+    try {
+        parsed = new URL(baseUrl);
+    }
+    catch {
+        throw new CogentaError({
+            code: 'CONFIG_INVALID',
+            message: `The site base URL "${baseUrl}" is not a URL.`,
+            hint: 'Give an absolute origin, protocol included: https://example.com',
+            details: { baseUrl },
+        });
+    }
+    if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+        throw new CogentaError({
+            code: 'CONFIG_INVALID',
+            message: `The site base URL uses "${parsed.protocol}", which no crawler follows.`,
+            hint: 'Use http or https. Sitemaps and feeds carry absolute http(s) URLs only.',
+            details: { baseUrl },
+        });
+    }
+    const path = parsed.pathname.replace(/\/+$/u, '');
+    return `${parsed.origin}${path}`;
+}
+/**
+ * An absolute URL for a site-relative path.
+ *
+ * The path is expected to be already encoded — `buildPath` percent-encodes each
+ * segment — so it is concatenated rather than passed through `new URL`, which
+ * would double-encode a `%` that is already an escape.
+ */
+export function absoluteUrl(site, path) {
+    const base = normaliseBaseUrl(site.baseUrl);
+    if (path.length === 0 || path === '/')
+        return `${base}/`;
+    return `${base}${path.startsWith('/') ? path : `/${path}`}`;
+}
+/**
+ * The route parameters an entry supplies.
+ *
+ * A pattern segment `:slug` reads `values.slug`; `:id` reads the system field,
+ * since it is the only parameter an entry always has and the natural fallback
+ * for a collection with no slug.
+ */
+export function routeParams(collection, entry) {
+    const pattern = collection.routing?.pattern ?? '';
+    const params = {};
+    for (const segment of pattern.split('/')) {
+        if (!segment.startsWith(':'))
+            continue;
+        const name = segment.slice(1);
+        if (name === 'id') {
+            params[name] = entry.id;
+            continue;
+        }
+        const value = entry.values[name];
+        if (typeof value === 'string' && value.length > 0) {
+            params[name] = value;
+            continue;
+        }
+        if (typeof value === 'number') {
+            params[name] = String(value);
+        }
+    }
+    return params;
+}
+/** True when the collection can produce a URL at all. */
+export function hasRoute(collection) {
+    return collection.routing !== undefined;
+}
+/**
+ * The canonical, absolute URL of an entry, or null when it has no route.
+ *
+ * Null rather than an exception: a collection without `routing` is a perfectly
+ * ordinary thing — an author, a tag, a site setting — and asking "what is the
+ * canonical URL of every entry" must not blow up on the first one that has
+ * none.
+ */
+export function canonicalUrl(site, resource) {
+    const { collection, entry } = resource;
+    const routing = collection.routing;
+    if (routing === undefined)
+        return null;
+    const params = routeParams(collection, entry);
+    for (const segment of routing.pattern.split('/')) {
+        if (segment.startsWith(':') && params[segment.slice(1)] === undefined)
+            return null;
+    }
+    const localised = routing.locale === true;
+    const path = buildPath(collection, params, localised ? entry.locale : undefined);
+    if (localised && site.unprefixedDefaultLocale === true && entry.locale === site.defaultLocale) {
+        const prefix = `/${encodeURIComponent(entry.locale)}`;
+        const stripped = path.slice(prefix.length);
+        return absoluteUrl(site, stripped.length === 0 ? '/' : stripped);
+    }
+    return absoluteUrl(site, path);
+}
+//# sourceMappingURL=url.js.map

package/dist/url.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"url.js","sourceRoot":"","sources":["../src/url.ts"],"names":[],"mappings":"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"}

package/dist/xml.d.ts

@@ -0,0 +1,32 @@
+export declare function stripIllegalXmlChars(value: string): string;
+/**
+ * Text content.
+ *
+ * `>` is escaped although it is only required inside a `]]>` run. Escaping it
+ * unconditionally costs three bytes and removes the need for anyone to reason
+ * about where the exception applies.
+ */
+export declare function escapeXmlText(value: string): string;
+export declare function escapeXmlAttribute(value: string): string;
+export type XmlAttributes = Readonly<Record<string, string | number | undefined>>;
+export interface XmlElement {
+    readonly name: string;
+    readonly attributes?: XmlAttributes;
+    /** Text content. Ignored when `children` holds anything. */
+    readonly text?: string;
+    /** `null` entries are dropped, so a conditional child needs no array surgery. */
+    readonly children?: readonly (XmlElement | null | undefined)[];
+}
+/**
+ * A whole document, declaration included.
+ *
+ * UTF-8 is stated rather than assumed: a sitemap served without a charset
+ * header and without a declaration is read as US-ASCII by a conforming parser,
+ * which mangles every non-Latin slug on the site.
+ */
+export declare function renderXmlDocument(root: XmlElement): string;
+/** The serialised size of one element, used to keep a sitemap file under its byte budget. */
+export declare function xmlElementByteLength(element: XmlElement, depth: number): number;
+/** Exposed so a caller measuring a document can measure exactly what will be written. */
+export declare function renderXmlElement(element: XmlElement, depth?: number): string;
+//# sourceMappingURL=xml.d.ts.map

package/dist/xml.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"xml.d.ts","sourceRoot":"","sources":["../src/xml.ts"],"names":[],"mappings":"AA8CA,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAE1D;AAQD;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEnD;AAiBD,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAKxD;AAED,MAAM,MAAM,aAAa,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC,CAAC,CAAA;AAEjF,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,UAAU,CAAC,EAAE,aAAa,CAAA;IACnC,4DAA4D;IAC5D,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;IACtB,iFAAiF;IACjF,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,CAAC,UAAU,GAAG,IAAI,GAAG,SAAS,CAAC,EAAE,CAAA;CAC/D;AAsDD;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,CAE1D;AAED,6FAA6F;AAC7F,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAE/E;AAED,yFAAyF;AACzF,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,UAAU,EAAE,KAAK,SAAI,GAAG,MAAM,CAEvE"}

package/dist/xml.js

@@ -0,0 +1,134 @@
+import { CogentaError } from '@cogenta/core';
+/**
+ * XML serialisation, written by hand and on purpose (rule R9).
+ *
+ * The reason this file exists rather than a dependency: the whole of Cogenta's
+ * XML output is four fixed document shapes — sitemap, sitemap index, RSS, Atom
+ * — and the only hard part is escaping. A library would bring a parser, a DOM
+ * and a stream API to solve a problem that is one substitution table wide.
+ *
+ * Escaping is where sitemaps and feeds actually break. A crawler does not
+ * repair a malformed document: it rejects the file whole, so one article whose
+ * title contains `<` silently removes every other URL in the same file from the
+ * index. That failure is invisible in production — the file is served with a
+ * 200 and looks fine in a browser — which is why it is tested here against a
+ * real parse rather than against a snapshot.
+ */
+/**
+ * Characters XML 1.0 forbids outright, escaped or not.
+ *
+ * `&#0;` is not a legal escape for a NUL: the character is simply not
+ * representable, so the only correct handling is removal. Content reaches us
+ * from imports and from agents, both of which produce stray control bytes, and
+ * a single one of them makes the document unparsable.
+ */
+// Assembled from code points rather than written as a regex literal. A literal
+// is what a reader would expect, and it is the one form that cannot be used: it
+// puts control characters in the source, where every editor, diff and terminal
+// renders them differently, and the linter rejects it for exactly that reason.
+// Tab (09), newline (0A) and carriage return (0D) are absent from the ranges —
+// XML allows all three, and stripping them would silently reflow content.
+const ILLEGAL_XML_RANGES = [
+    [0x00, 0x08],
+    [0x0b, 0x0c],
+    [0x0e, 0x1f],
+    [0xfffe, 0xffff],
+];
+const ILLEGAL_XML_CHARS = new RegExp(`[${ILLEGAL_XML_RANGES.map(([from, to]) => `${String.fromCodePoint(from)}-${String.fromCodePoint(to)}`).join('')}]`, 'gu');
+export function stripIllegalXmlChars(value) {
+    return value.replace(ILLEGAL_XML_CHARS, '');
+}
+const TEXT_ESCAPES = {
+    '&': '&amp;',
+    '<': '&lt;',
+    '>': '&gt;',
+};
+/**
+ * Text content.
+ *
+ * `>` is escaped although it is only required inside a `]]>` run. Escaping it
+ * unconditionally costs three bytes and removes the need for anyone to reason
+ * about where the exception applies.
+ */
+export function escapeXmlText(value) {
+    return stripIllegalXmlChars(value).replace(/[&<>]/gu, (char) => TEXT_ESCAPES[char] ?? char);
+}
+const ATTRIBUTE_ESCAPES = {
+    '&': '&amp;',
+    '<': '&lt;',
+    '>': '&gt;',
+    '"': '&quot;',
+    "'": '&apos;',
+    // Attribute-value normalisation turns a literal tab, newline or carriage
+    // return into a space before the application ever sees it. A title that wraps
+    // would come back out of the parser silently different, so the whitespace is
+    // written as a character reference, which normalisation leaves alone.
+    '\t': '&#9;',
+    '\n': '&#10;',
+    '\r': '&#13;',
+};
+export function escapeXmlAttribute(value) {
+    return stripIllegalXmlChars(value).replace(/[&<>"'\t\n\r]/gu, (char) => ATTRIBUTE_ESCAPES[char] ?? char);
+}
+/**
+ * A conservative subset of the XML `Name` production: ASCII letters, digits,
+ * `_`, `-`, `.` and one `:` for a namespace prefix. Every tag this package
+ * emits is a literal, so this only ever fires on a programming mistake — but a
+ * mistake that would produce a document no crawler can read.
+ */
+const XML_NAME = /^[A-Za-z_][\w.-]*(?::[A-Za-z_][\w.-]*)?$/;
+function assertName(name) {
+    if (XML_NAME.test(name))
+        return;
+    throw new CogentaError({
+        code: 'CONTENT_INVALID',
+        message: `"${name}" is not a usable XML element or attribute name.`,
+        hint: 'Element and attribute names are fixed by the feed format; they are never built from content.',
+        details: { name },
+    });
+}
+function renderAttributes(attributes) {
+    if (attributes === undefined)
+        return '';
+    let rendered = '';
+    for (const [name, value] of Object.entries(attributes)) {
+        if (value === undefined)
+            continue;
+        assertName(name);
+        rendered += ` ${name}="${escapeXmlAttribute(String(value))}"`;
+    }
+    return rendered;
+}
+function renderElement(element, depth) {
+    assertName(element.name);
+    const pad = '  '.repeat(depth);
+    const open = `${pad}<${element.name}${renderAttributes(element.attributes)}`;
+    const children = (element.children ?? []).filter((child) => child !== null && child !== undefined);
+    if (children.length > 0) {
+        const inner = children.map((child) => renderElement(child, depth + 1)).join('\n');
+        return `${open}>\n${inner}\n${pad}</${element.name}>`;
+    }
+    if (element.text !== undefined) {
+        return `${open}>${escapeXmlText(element.text)}</${element.name}>`;
+    }
+    return `${open} />`;
+}
+/**
+ * A whole document, declaration included.
+ *
+ * UTF-8 is stated rather than assumed: a sitemap served without a charset
+ * header and without a declaration is read as US-ASCII by a conforming parser,
+ * which mangles every non-Latin slug on the site.
+ */
+export function renderXmlDocument(root) {
+    return `<?xml version="1.0" encoding="UTF-8"?>\n${renderElement(root, 0)}\n`;
+}
+/** The serialised size of one element, used to keep a sitemap file under its byte budget. */
+export function xmlElementByteLength(element, depth) {
+    return Buffer.byteLength(renderElement(element, depth), 'utf8');
+}
+/** Exposed so a caller measuring a document can measure exactly what will be written. */
+export function renderXmlElement(element, depth = 0) {
+    return renderElement(element, depth);
+}
+//# sourceMappingURL=xml.js.map

package/dist/xml.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"xml.js","sourceRoot":"","sources":["../src/xml.ts"],"names":[],"mappings":"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"}