@warlock.js/sitemap 5.19.1 → 5.20.0

package/CHANGELOG.md

@@ -4,6 +4,21 @@ All notable changes to `@warlock.js/sitemap` are documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). `@warlock.js/*` packages are released in lockstep — every package shares the same version number, so a version below may list only the changes that affected this package.
 
+## 5.20.0 - 2026-09-24
+
+### Added
+
+- `SitemapEntry.images` emits the Google image sitemap extension, validates
+  absolute HTTP(S) image URLs, and limits each URL to 1,000 images with a
+  caller-visible diagnostic.
+- `SitemapIndexOptions.shardPathPrefix` controls public shard links in an
+  index without changing the files written by `saveTo()`.
+
+### Changed
+
+- Refined grouped skill discovery guidance and regenerated package llms
+  projections.
+
 ## 5.19.0 - 2026-09-23
 
 ### Changed

package/cjs/index.cjs

@@ -206,6 +206,7 @@ const CHANGE_FREQS = [
 	"yearly",
 	"never"
 ];
+const MAX_IMAGES_PER_URL = 1e3;
 function assertChangeFreq(value) {
 	if (!CHANGE_FREQS.includes(value)) throw new InvalidSitemapEntryError(`changefreq ${JSON.stringify(value)} is not one of ${CHANGE_FREQS.join(", ")}`);
 }
@@ -238,6 +239,22 @@ function normalizeEntry(entry, defaults) {
 			path: normalizePath(alternate.path)
 		};
 	});
+	if (entry.images !== void 0 && !Array.isArray(entry.images)) throw new InvalidSitemapEntryError("images must be an array");
+	const images = entry.images?.slice(0, MAX_IMAGES_PER_URL).map((image) => {
+		if (typeof image?.loc !== "string" || image.loc.trim() === "") throw new InvalidSitemapEntryError("image loc is required");
+		let url;
+		try {
+			url = new URL(image.loc);
+		} catch {
+			throw new InvalidSitemapEntryError("image loc must be an absolute HTTP(S) URL");
+		}
+		if (url.protocol !== "http:" && url.protocol !== "https:") throw new InvalidSitemapEntryError("image loc must be an absolute HTTP(S) URL");
+		return { loc: image.loc };
+	});
+	if ((entry.images?.length ?? 0) > MAX_IMAGES_PER_URL) defaults.onImageLimitExceeded?.({
+		...entry.route === void 0 ? {} : { route: entry.route },
+		dropped: entry.images.length - MAX_IMAGES_PER_URL
+	});
 	return {
 		path,
 		...entry.name !== void 0 ? { name: entry.name } : {},
@@ -245,7 +262,8 @@ function normalizeEntry(entry, defaults) {
 		...lastmod !== void 0 ? { lastmod: formatLastmod(lastmod) } : {},
 		...changefreq !== void 0 ? { changefreq } : {},
 		...priority !== void 0 ? { priority } : {},
-		...alternates !== void 0 ? { alternates } : {}
+		...alternates !== void 0 ? { alternates } : {},
+		...images !== void 0 ? { images } : {}
 	};
 }
 
@@ -301,12 +319,15 @@ function escapeXml(value) {
 	return value.replace(/[&<>"']/g, (char) => XML_ESCAPES[char] ?? char);
 }
 const XHTML_NAMESPACE = "http://www.w3.org/1999/xhtml";
+const IMAGE_NAMESPACE = "http://www.google.com/schemas/sitemap-image/1.1";
 /**
 * The `xmlns:xhtml` attribute exactly as it appears on `<urlset>`, including
 * its leading space. Exported so the shard writer can charge its byte length
 * against the ceiling without duplicating the string it measures.
 */
 const XHTML_NAMESPACE_ATTR = ` xmlns:xhtml="${XHTML_NAMESPACE}"`;
+/** See {@link XHTML_NAMESPACE_ATTR}; measured by the shard writer before roll-over. */
+const IMAGE_NAMESPACE_ATTR = ` xmlns:image="${IMAGE_NAMESPACE}"`;
 /**
 * Renders one `<url>` block. Exported so the streaming writer can measure the
 * exact bytes it is about to append before deciding whether the byte ceiling
@@ -322,6 +343,11 @@ function renderUrlBlock(entry, baseUrl) {
 		const href = escapeXml(resolveAgainstBase(baseUrl, alternate.path));
 		lines.push(`    <xhtml:link rel="alternate" hreflang="${escapeXml(alternate.hreflang)}" href="${href}"/>`);
 	}
+	for (const image of entry.images ?? []) {
+		lines.push(`    <image:image>`);
+		lines.push(`      <image:loc>${escapeXml(resolveAgainstBase(baseUrl, image.loc))}</image:loc>`);
+		lines.push(`    </image:image>`);
+	}
 	lines.push(`  </url>`);
 	return lines.join("\n");
 }
@@ -335,7 +361,9 @@ function renderUrlBlock(entry, baseUrl) {
 * alternate — an unused namespace on every single-language sitemap is noise.
 */
 function buildSitemapXml(entries, baseUrl) {
-	const namespaces = entries.some((entry) => (entry.alternates?.length ?? 0) > 0) ? XHTML_NAMESPACE_ATTR : "";
+	const hasAlternates = entries.some((entry) => (entry.alternates?.length ?? 0) > 0);
+	const hasImages = entries.some((entry) => (entry.images?.length ?? 0) > 0);
+	const namespaces = `${hasAlternates ? XHTML_NAMESPACE_ATTR : ""}${hasImages ? IMAGE_NAMESPACE_ATTR : ""}`;
 	const body = entries.map((entry) => renderUrlBlock(entry, baseUrl)).join("\n");
 	return `<?xml version="1.0" encoding="UTF-8"?>\n<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"${namespaces}>\n` + (body.length > 0 ? `${body}\n` : "") + `</urlset>\n`;
 }
@@ -355,6 +383,8 @@ function buildSitemapXml(entries, baseUrl) {
 var Sitemap = class {
 	baseUrl;
 	defaults;
+	warnedImageRoutes = /* @__PURE__ */ new Set();
+	optionsImageReporter;
 	/** Keyed by path: a duplicate `<loc>` makes the document invalid, so the later add wins. */
 	entriesByPath = /* @__PURE__ */ new Map();
 	/** Insertion order per path, so `duplicates()` can name every colliding source. */
@@ -363,12 +393,21 @@ var Sitemap = class {
 	declaredRoutes = /* @__PURE__ */ new Set();
 	constructor(options) {
 		this.baseUrl = normalizeBaseUrl(options?.baseUrl);
+		this.optionsImageReporter = options.onImageLimitExceeded;
 		this.defaults = {
 			changefreq: options.changefreq,
 			priority: options.priority,
-			lastmod: options.lastmod
+			lastmod: options.lastmod,
+			onImageLimitExceeded: (event) => this.reportImageLimit(event)
 		};
 	}
+	reportImageLimit(event) {
+		const key = event.route ?? "unattributed";
+		if (this.warnedImageRoutes.has(key)) return;
+		this.warnedImageRoutes.add(key);
+		if (this.optionsImageReporter) this.optionsImageReporter(event);
+		else console.warn(`[warlock:sitemap] ${key} exceeded the 1,000-image limit; dropped ${event.dropped} image(s).`);
+	}
 	add(entry) {
 		const resolved = normalizeEntry(entry, this.defaults);
 		this.entriesByPath.set(resolved.path, resolved);
@@ -467,6 +506,7 @@ const PROTOCOL_MAX_BYTES_PER_FILE = 50 * 1024 * 1024;
 /** Validates and folds in defaults, once, at the constructor — the same discipline as `Sitemap`. */
 function normalizeSitemapIndexOptions(options) {
 	const baseUrl = normalizeBaseUrl(options?.baseUrl);
+	const shardPathPrefix = normalizeShardPathPrefix(options.shardPathPrefix);
 	const maxUrlsPerFile = options.maxUrlsPerFile ?? 5e4;
 	const maxBytesPerFile = options.maxBytesPerFile ?? 52428800;
 	if (!Number.isInteger(maxUrlsPerFile) || maxUrlsPerFile < 1 || maxUrlsPerFile > 5e4) throw new RangeError(`maxUrlsPerFile must be an integer between 1 and the sitemaps.org ceiling of ${PROTOCOL_MAX_URLS_PER_FILE}, got ${JSON.stringify(maxUrlsPerFile)}.`);
@@ -475,16 +515,24 @@ function normalizeSitemapIndexOptions(options) {
 		baseUrl,
 		filePrefix: options.filePrefix ?? "sitemap",
 		indexFileName: options.indexFileName ?? "sitemap_index.xml",
+		shardPathPrefix,
 		gzip: options.gzip ?? false,
 		maxUrlsPerFile,
 		maxBytesPerFile,
 		defaults: {
 			changefreq: options.changefreq,
 			priority: options.priority,
-			lastmod: options.lastmod
+			lastmod: options.lastmod,
+			onImageLimitExceeded: options.onImageLimitExceeded
 		}
 	};
 }
+function normalizeShardPathPrefix(value) {
+	if (value === void 0 || value === "" || value === "/") return "";
+	const prefix = value.replace(/^\//, "").replace(/\/$/, "");
+	if (prefix.length === 0 || prefix.split("/").some((segment) => !/^[A-Za-z0-9_-]+$/.test(segment))) throw new TypeError("shardPathPrefix must contain only safe URL path segments.");
+	return `${prefix}/`;
+}
 
 //#endregion
 //#region ../sitemap/src/shard-name.ts
@@ -525,6 +573,7 @@ function envelopeBytes(baseUrl) {
 * shard's real bytes on disk exceed the ceiling it was rolled against.
 */
 const NAMESPACE_BYTES = Buffer.byteLength(XHTML_NAMESPACE_ATTR, "utf8");
+const IMAGE_NAMESPACE_BYTES = Buffer.byteLength(IMAGE_NAMESPACE_ATTR, "utf8");
 async function writeShardFile(ctx, fileName, entries) {
 	const xml = buildSitemapXml(entries, ctx.baseUrl);
 	const filePath = (0, node_path.join)(ctx.tempDir, fileName);
@@ -546,6 +595,7 @@ async function writeShardGroup(group, ctx) {
 	let buffer = [];
 	let bufferBytes = envelopeBytes(ctx.baseUrl);
 	let bufferHasAlternates = false;
+	let bufferHasImages = false;
 	let ordinal = 1;
 	const flush = async () => {
 		if (buffer.length === 0) return;
@@ -562,6 +612,7 @@ async function writeShardGroup(group, ctx) {
 		buffer = [];
 		bufferBytes = envelopeBytes(ctx.baseUrl);
 		bufferHasAlternates = false;
+		bufferHasImages = false;
 	};
 	for (const factory of group.factories) {
 		const source = await factory();
@@ -569,15 +620,18 @@ async function writeShardGroup(group, ctx) {
 			const resolved = normalizeEntry(rawEntry, ctx.defaults);
 			if (!ctx.duplicates.attempt(resolved.path, resolved.route)) continue;
 			const entryHasAlternates = (resolved.alternates?.length ?? 0) > 0;
+			const entryHasImages = (resolved.images?.length ?? 0) > 0;
 			const blockBytes = Buffer.byteLength(renderUrlBlock(resolved, ctx.baseUrl), "utf8") + 1;
-			const addedBytes = blockBytes + (entryHasAlternates && !bufferHasAlternates ? NAMESPACE_BYTES : 0);
+			const addedBytes = blockBytes + (entryHasAlternates && !bufferHasAlternates ? NAMESPACE_BYTES : 0) + (entryHasImages && !bufferHasImages ? IMAGE_NAMESPACE_BYTES : 0);
 			const hitsUrlCeiling = buffer.length >= ctx.maxUrlsPerFile;
 			const hitsByteCeiling = buffer.length > 0 && bufferBytes + addedBytes > ctx.maxBytesPerFile;
 			if (hitsUrlCeiling || hitsByteCeiling) await flush();
 			const addsNamespaceNow = entryHasAlternates && !bufferHasAlternates;
+			const addsImageNamespaceNow = entryHasImages && !bufferHasImages;
 			buffer.push(resolved);
-			bufferBytes += blockBytes + (addsNamespaceNow ? NAMESPACE_BYTES : 0);
+			bufferBytes += blockBytes + (addsNamespaceNow ? NAMESPACE_BYTES : 0) + (addsImageNamespaceNow ? IMAGE_NAMESPACE_BYTES : 0);
 			if (addsNamespaceNow) bufferHasAlternates = true;
+			if (addsImageNamespaceNow) bufferHasImages = true;
 			ctx.routes.record(resolved.route);
 		}
 	}
@@ -600,9 +654,9 @@ async function writeShardGroup(group, ctx) {
 * nested per-group indexes, and never a zero-url row (that is a diagnostic
 * for `files`, not something a crawler should be told to fetch).
 */
-function buildSitemapIndexXml(files, baseUrl) {
+function buildSitemapIndexXml(files, baseUrl, shardPathPrefix = "") {
 	const body = files.filter((file) => file.urls > 0).map((file) => {
-		return `  <sitemap>\n    <loc>${escapeXml(joinOrigin(baseUrl, file.fileName))}</loc>\n  </sitemap>`;
+		return `  <sitemap>\n    <loc>${escapeXml(joinOrigin(baseUrl, `${shardPathPrefix}${file.fileName}`))}</loc>\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.length > 0 ? `${body}\n` : "") + `</sitemapindex>\n`;
 }
@@ -674,6 +728,7 @@ var SitemapIndex = class {
 	namedGroups = [];
 	/** Canonical (lowercased) keys already registered, so a case collision is caught at `addSource()`. */
 	registeredKeys = /* @__PURE__ */ new Set();
+	warnedImageRoutes = /* @__PURE__ */ new Set();
 	constructor(options) {
 		this.options = normalizeSitemapIndexOptions(options);
 	}
@@ -713,13 +768,16 @@ var SitemapIndex = class {
 					gzip: this.options.gzip,
 					maxUrlsPerFile: this.options.maxUrlsPerFile,
 					maxBytesPerFile: this.options.maxBytesPerFile,
-					defaults: this.options.defaults,
+					defaults: {
+						...this.options.defaults,
+						onImageLimitExceeded: (event) => this.reportImageLimit(event)
+					},
 					duplicates,
 					routes
 				});
 				shardFiles.push(...files);
 			}
-			const indexXml = buildSitemapIndexXml(shardFiles, this.options.baseUrl);
+			const indexXml = buildSitemapIndexXml(shardFiles, this.options.baseUrl, this.options.shardPathPrefix);
 			await (0, node_fs_promises.writeFile)((0, node_path.join)(tempDir, this.options.indexFileName), indexXml, "utf8");
 			return [...shardFiles.filter((file) => file.urls > 0).map((file) => file.fileName), this.options.indexFileName];
 		};
@@ -739,17 +797,143 @@ var SitemapIndex = class {
 			routes: routes.summary()
 		};
 	}
+	reportImageLimit(event) {
+		const key = event.route ?? "unattributed";
+		if (this.warnedImageRoutes.has(key)) return;
+		this.warnedImageRoutes.add(key);
+		if (this.options.defaults.onImageLimitExceeded) this.options.defaults.onImageLimitExceeded(event);
+		else console.warn(`[warlock:sitemap] ${key} exceeded the 1,000-image limit; dropped ${event.dropped} image(s).`);
+	}
+};
+
+//#endregion
+//#region ../sitemap/src/generation-manifest.ts
+/** Storage-independent schema and key helpers for immutable sitemap generations. */
+const GENERATION_MANIFEST_VERSION = 1;
+const MANIFEST_FENCE_WIDTH = 16;
+var InvalidSitemapGenerationManifestError = class extends Error {
+	constructor(message) {
+		super(`Invalid sitemap generation manifest: ${message}`);
+		this.name = "InvalidSitemapGenerationManifestError";
+	}
 };
+const SAFE_IDENTIFIER = /^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$/;
+const SAFE_FILE_NAME = /^[A-Za-z0-9][A-Za-z0-9._-]{0,255}$/;
+const SHA256 = /^[a-f0-9]{64}$/;
+const ISO_DATE_TIME = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,9})?(?:Z|[+-]\d{2}:\d{2})$/;
+const MANIFEST_KEY = /^manifests\/(\d{16})-([A-Za-z0-9][A-Za-z0-9_-]{0,127})\.json$/;
+function fail(message) {
+	throw new InvalidSitemapGenerationManifestError(message);
+}
+function object(value, label) {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return fail(`${label} must be an object.`);
+	return value;
+}
+function nonNegativeInteger(value, label) {
+	if (!Number.isSafeInteger(value) || value < 0) return fail(`${label} must be a safe non-negative integer.`);
+	return value;
+}
+function generationIdentifier(value, label) {
+	if (typeof value !== "string" || !SAFE_IDENTIFIER.test(value)) return fail(`${label} must be a safe generation identifier.`);
+	return value;
+}
+function generatedAt(value) {
+	if (typeof value !== "string" || !ISO_DATE_TIME.test(value) || Number.isNaN(Date.parse(value))) return fail("generatedAt must be a valid ISO-8601 date-time.");
+	return value;
+}
+function artifactPath(value, generationId, label) {
+	if (typeof value !== "string") return fail(`${label} must be a string.`);
+	const prefix = `generations/${generationId}/`;
+	if (!value.startsWith(prefix)) return fail(`${label} must be contained in ${prefix}.`);
+	const fileName = value.slice(prefix.length);
+	if (!SAFE_FILE_NAME.test(fileName) || fileName.includes("/") || fileName === "." || fileName === "..") return fail(`${label} must name one safe, flat artifact file.`);
+	return value;
+}
+function manifestFile(value, generationId, index) {
+	const record = object(value, `files[${index}]`);
+	const path = artifactPath(record.path, generationId, `files[${index}].path`);
+	const bytes = nonNegativeInteger(record.bytes, `files[${index}].bytes`);
+	if (typeof record.sha256 !== "string" || !SHA256.test(record.sha256)) return fail(`files[${index}].sha256 must be a lowercase SHA-256 hex digest.`);
+	return {
+		path,
+		bytes,
+		sha256: record.sha256
+	};
+}
+/** Parse untrusted JSON into the v1 manifest contract. It does not touch storage. */
+function parseSitemapGenerationManifest(value) {
+	const record = object(value, "manifest");
+	if (record.version !== 1) return fail(`version must be ${1}.`);
+	const fence = nonNegativeInteger(record.fence, "fence");
+	const generationId = generationIdentifier(record.generationId, "generationId");
+	const coversRev = nonNegativeInteger(record.coversRev, "coversRev");
+	if (record.kind !== "single" && record.kind !== "index") return fail("kind must be \"single\" or \"index\".");
+	if (!Array.isArray(record.files) || record.files.length === 0) return fail("files must be a non-empty array.");
+	const files = record.files.map((file, index) => manifestFile(file, generationId, index));
+	const paths = /* @__PURE__ */ new Set();
+	const fileNames = /* @__PURE__ */ new Set();
+	for (const file of files) {
+		const fileName = file.path.slice(`generations/${generationId}/`.length);
+		if (paths.has(file.path)) return fail(`files contains duplicate path ${JSON.stringify(file.path)}.`);
+		if (fileNames.has(fileName)) return fail(`files contains duplicate public file name ${JSON.stringify(fileName)}.`);
+		paths.add(file.path);
+		fileNames.add(fileName);
+	}
+	const mainFile = artifactPath(record.mainFile, generationId, "mainFile");
+	if (!paths.has(mainFile)) return fail("mainFile must match one files[].path.");
+	return {
+		version: 1,
+		fence,
+		generationId,
+		coversRev,
+		kind: record.kind,
+		mainFile,
+		files,
+		entries: nonNegativeInteger(record.entries, "entries"),
+		generatedAt: generatedAt(record.generatedAt)
+	};
+}
+/** Build the immutable v1 manifest object key for a generation fence. */
+function sitemapManifestKey(fence, generationId) {
+	const safeFence = nonNegativeInteger(fence, "fence");
+	if (safeFence >= 10 ** 16) return fail(`fence must fit within ${16} decimal digits.`);
+	return `manifests/${String(safeFence).padStart(16, "0")}-${generationIdentifier(generationId, "generationId")}.json`;
+}
+/** Parse only the shape of a manifest object key; artifact validation belongs to the storage adapter. */
+function parseSitemapManifestKey(key) {
+	if (typeof key !== "string") return void 0;
+	const match = MANIFEST_KEY.exec(key);
+	if (!match) return void 0;
+	const fence = Number(match[1]);
+	const generationId = match[2];
+	if (!Number.isSafeInteger(fence) || generationId === void 0) return void 0;
+	return {
+		key,
+		fence,
+		generationId
+	};
+}
+/** Numeric-fence-descending candidates; callers validate storage contents before adoption. */
+function sortSitemapManifestCandidates(keys) {
+	return keys.map(parseSitemapManifestKey).filter((candidate) => candidate !== void 0).sort((left, right) => right.fence - left.fence || right.generationId.localeCompare(left.generationId));
+}
 
 //#endregion
 exports.DuplicateSourceKeyError = DuplicateSourceKeyError;
+exports.GENERATION_MANIFEST_VERSION = GENERATION_MANIFEST_VERSION;
 exports.InvalidBaseUrlError = InvalidBaseUrlError;
 exports.InvalidSitemapEntryError = InvalidSitemapEntryError;
+exports.InvalidSitemapGenerationManifestError = InvalidSitemapGenerationManifestError;
+exports.MANIFEST_FENCE_WIDTH = MANIFEST_FENCE_WIDTH;
 exports.Sitemap = Sitemap;
 exports.SitemapIndex = SitemapIndex;
 exports.UnownedOutputDirectoryError = UnownedOutputDirectoryError;
 exports.buildSitemapXml = buildSitemapXml;
 exports.escapeXml = escapeXml;
 exports.joinOrigin = joinOrigin;
+exports.parseSitemapGenerationManifest = parseSitemapGenerationManifest;
+exports.parseSitemapManifestKey = parseSitemapManifestKey;
 exports.renderUrlBlock = renderUrlBlock;
+exports.sitemapManifestKey = sitemapManifestKey;
+exports.sortSitemapManifestCandidates = sortSitemapManifestCandidates;
 //# sourceMappingURL=index.cjs.map