@warlock.js/sitemap 5.15.0 → 5.16.0

package/skills/sitemap-overview/SKILL.md

@@ -1,194 +1,174 @@
 ---
 name: sitemap-overview
-description: 'Front-door orientation for `@warlock.js/sitemap` — three usage modes (standalone any Node app, Warlock API-only via `sitemapConnector({ entries })`, Warlock web via the page registry), the `sitemapConnector()` + `src/config/sitemap.ts` (`SitemapConfig`: `enabled`, `path`, `defaults.changefreq`/`defaults.priority`) wiring, exclusion rules (not-found, error page, `metadata.robots: noindex`, `sitemap: false`), the page-level `sitemap` export for dynamic routes, the app-supplied/page-derived entries merge-and-dedupe rule, `NoPageRegistryError`, and the dev-mode diagnostic for a dynamic route with no `sitemap` export. TRIGGER when: code imports anything from `@warlock.js/sitemap`; user asks "what does @warlock.js/sitemap do", "how do I add a page to the sitemap", "why is my dynamic route missing from sitemap.xml", "sitemap changefreq/priority", "sitemapConnector", "SitemapConfig", "sitemap without @warlock.js/web", "NoPageRegistryError"; package.json adds `@warlock.js/sitemap`; user is scaffolding `warlock add sitemap`; user is building an API-only Warlock app or a plain Node app and wants a sitemap. Skip: user wants to PARSE or fetch a remote sitemap — this package only generates one, in this release; the `app.publicUrl`/`PUBLIC_APP_URL` config key itself lives in `@warlock.js/core/configure-app/SKILL.md`.'
+description: 'Front-door orientation for `@warlock.js/sitemap` — the framework-blind `Sitemap` builder class (`new Sitemap({ baseUrl, changefreq, priority, lastmod })`, `add`/`addMany`/`declareRoute`, `size`/`entries()`/`routes()`/`duplicates()`, sync `toXML()`, `saveTo()`), the constructor-time `baseUrl` validation and `InvalidBaseUrlError`, entry validation and `InvalidSitemapEntryError`, the keyed-by-path silent last-write-wins rule and how `duplicates()` makes it visible, the `count: 0` route diagnostic that `declareRoute()` exists to make possible, `hreflang` alternates via `xhtml:link`, and the 50,000-URL / 50MB protocol ceiling that separates this bounded builder from the streaming writer. TRIGGER when: code imports anything from `@warlock.js/sitemap`; user asks "what does @warlock.js/sitemap do", "how do I generate a sitemap", "how do I add a URL to the sitemap", "why is my dynamic route missing from sitemap.xml", "sitemap changefreq/priority", "sitemap hreflang", "sitemap baseUrl", "InvalidBaseUrlError", "sitemap without Warlock", "sitemap in Express"; package.json adds `@warlock.js/sitemap`; user is scaffolding `warlock add sitemap`. Skip: user wants to PARSE or fetch a remote sitemap — this package only generates one; the Warlock page-registry discovery, locale expansion, the `/sitemap.xml` route and `robots.txt` live in `@warlock.js/web`, not here.'
 ---
 
 # `@warlock.js/sitemap` — overview
 
-Builds `sitemap.xml` at RUNTIME, against whatever source of URLs the app has
-— a page registry, app-supplied entries, or both — a build-time walk can
-read neither. Generation only; no remote sitemap parser in this release.
+A sitemap builder that knows nothing about any framework. Entries in, a valid
+sitemaps.org document out. **Zero runtime dependencies.** Generation only; no
+remote sitemap parser.
 
-## `@warlock.js/core` and `@warlock.js/web` are optional peers
+## It does not import Warlock
 
-Both are declared in `peerDependenciesMeta` as optional. Everything in the
-package except `src/sitemap-connector.ts` imports nothing from either, and
-the connector itself only reaches them through a lazy `import()` inside
-`boot()` — never at module load. This is what makes all three modes below
-possible from one package.
+There is no connector, no config module, no lifecycle and no page registry in
+this package. It owns the sitemap PROTOCOL and every byte it emits, and
+nothing else. `@warlock.js/web` is a CALLER of it, exactly like an Express app
+or a cron script is — which is what makes the same three lines work everywhere.
 
-## Three ways to use it
+If you are looking for page discovery, `sitemap: false` exclusion, locale
+expansion, the `/sitemap.xml` route or `robots.txt`, those belong to
+`@warlock.js/web`, not here.
 
-1. **Standalone, any Node app** — no Warlock at all. Build a
-   `RoutablePage[]` yourself and call `collectSitemapEntries` +
-   `buildSitemapXml` directly. Nothing on this path resolves
-   `@warlock.js/core` or `@warlock.js/web`.
-2. **Warlock, API-only** — an API-only app has no page registry for
-   `listRoutablePages()` to read. Pass `sitemapConnector({ entries })` with
-   an app-supplied entries function instead; `@warlock.js/web` is not
-   required on this path.
-3. **Warlock web** — `warlock add sitemap` wires `sitemapConnector()`
-   against the page registry `@warlock.js/web` exposes, plus the page-level
-   `sitemap` export for dynamic routes.
+## The whole common case
 
-Modes 2 and 3 aren't exclusive: `entries` and a page registry can both be
-present on the same connector — see "Merging page-derived and app-supplied
-entries" below.
+```ts
+import { Sitemap } from "@warlock.js/sitemap";
 
-## Server-only package
+const sitemap = new Sitemap({
+  baseUrl: "https://example.com",
+  changefreq: "weekly",
+  priority: 0.5,
+});
 
-`@warlock.js/sitemap`'s entire runtime surface is server-only — its
-`package.json` declares `"warlock": { "environment": "server" }`. It reads
-the page registry and mounts a route; it has no reason to reach the client
-bundle.
+sitemap.add({ path: "/" });
 
-## Wiring it up — `sitemapConnector()` and `src/config/sitemap.ts` (Modes 2 and 3)
+declare const posts: { slug: string; updatedAt: Date }[];
 
-`warlock add sitemap` (`requires: ["web"]`) writes both halves for Mode 3.
-Doing it by hand is the same two pieces:
+for (const post of posts) {
+  sitemap.add({
+    name: "post-details",
+    route: "/posts/:id",
+    path: `/posts/${post.slug}`,
+    lastmod: post.updatedAt,
+    priority: 0.8,
+  });
+}
 
-```ts
-// warlock.config.ts
-import { defineConfig } from "@warlock.js/core";
-import { sitemapConnector } from "@warlock.js/sitemap";
+const xml = sitemap.toXML();
 
-export default defineConfig({ connectors: [sitemapConnector()] });
+await sitemap.saveTo("public/sitemap.xml");
 ```
 
-```ts
-// src/config/sitemap.ts
-import type { SitemapConfig } from "@warlock.js/sitemap";
+## `baseUrl` is validated in the CONSTRUCTOR
 
-const sitemapConfig: SitemapConfig = {
-  enabled: true,
-  path: "/sitemap.xml",
-  defaults: { changefreq: "weekly", priority: 0.5 },
-};
+A `Sitemap` that cannot produce a valid URL should not exist. Anything that is
+not an absolute `http(s)` URL throws `InvalidBaseUrlError` at construction, so
+a typo surfaces at the line that wrote it rather than at the first request.
+`new URL()` accepts `mailto:` and `file:` happily, so the protocol is checked
+explicitly.
 
-export default sitemapConfig;
-```
+This replaces the 5.15.0 config key, its `PUBLIC_APP_URL` env fallback and its
+boot refusal entirely: the origin is an argument now, so it cannot be missing.
 
-`SitemapConfig` is `{ enabled: boolean; path: string; defaults?: SitemapDefaults }`
-— `defaults` (`changefreq`/`priority`) backs any entry that omits them.
-`sitemapConnector({ config })` accepts the config object directly instead of
-reading the `sitemap` config key, for tests or non-standard wiring.
-
-At `boot()` (priority `5.6` — after HTTP's `5` and web's `5.5`, so the route
-it registers lands on the router web already populated) it is a no-op unless
-`enabled` is `true`. When enabled, it resolves `app.publicUrl` /
-`PUBLIC_APP_URL` **once, at boot** via `resolveOrigin()` — throwing
-`MissingPublicUrlError` and refusing to start rather than falling back to a
-request-derived host — then attempts a lazy `import("@warlock.js/web/build")` to
-get `listRoutablePages`. If that import fails **and** no `entries` option
-was supplied, it throws `NoPageRegistryError` — there is nothing to serve.
-Otherwise it registers `GET <path>`. The route itself re-reads the page
-graph on every request via `listRoutablePages()`, not once at boot, so it
-never goes stale under `warlock dev`.
-
-### `NoPageRegistryError`
-
-Raised at `boot()`, before the route is registered, when `@warlock.js/web`
-is not installed and no `entries` option was supplied. Refuses to boot
-rather than registering a route that would silently serve an empty
-`<urlset>` — the same reasoning as `MissingPublicUrlError` above. Fix by
-installing `@warlock.js/web`, or by passing `sitemapConnector({ entries })`.
-
-### Merging page-derived and app-supplied entries
-
-When both a page registry (Mode 3) and `entries` (Mode 2's option, usable
-alongside Mode 3) are present, `mergeSitemapEntries` (`src/collect-entries.ts`)
-combines them, deduplicated by `path` — not one replacing the other. Where
-the same `path` appears in both, the `entries` version wins, since it was
-written for that exact path on purpose.
-
-## The exclusion rules — read these once and you know the shape
-
-| case | behaviour |
+## The entry
+
+Only `path` is required, and it must be a **concrete path** — `/posts/123`,
+never `/posts/:id`. A pattern is not a URL.
+
+| Field | Meaning |
 | --- | --- |
-| static route | included |
-| not-found route | excluded |
-| error page | excluded — it isn't a routable page at all |
-| page whose `metadata.robots` says `noindex` | excluded |
-| page exporting `sitemap: false` | excluded |
-| dynamic route (`[id]`, `[...slug]`) **with** a `sitemap` export | the entries that export returns |
-| dynamic route **without** a `sitemap` export | **omitted, and named in a dev-mode diagnostic** |
+| `path` | Required. Resolved against `baseUrl`; an absolute URL is used as given. |
+| `name` | Optional route label, for your own diagnostics. Never serialised. |
+| `route` | Optional pattern this URL came from. Feeds `routes()` and `duplicates()`. |
+| `lastmod` | `Date` → W3C datetime. A string is passed through UNTOUCHED, never re-parsed. |
+| `changefreq` | One of the seven protocol values; anything else throws. |
+| `priority` | `0.0`–`1.0`; anything else throws. |
+| `alternates` | `{ hreflang, path }[]` — language versions of this page. |
+
+Invalid entries throw `InvalidSitemapEntryError` from `add()`. Paths are
+normalised to carry a leading slash, so `a` and `/a` are ONE entry.
 
-That last row is the whole reason this package exists: a dynamic route cannot
-be enumerated without application data, so silence there would mean a
-sitemap that looks complete while it quietly omits every product page on the
-site. `describeUnresolvedDynamicRoutes` (`src/diagnostic.ts`) is the message a
-developer sees when that happens.
+## Duplicates: silent, but not hidden
 
-## Standalone usage (Mode 1) — no `sitemapConnector()` at all
+Entries are stored keyed by `path`. Adding the same path twice keeps the later
+one, silently — a duplicate `<loc>` makes the document invalid, and two loops
+legitimately covering an overlapping set is the normal cause.
 
-Call the building blocks directly against a hand-built `RoutablePage[]`:
+`duplicates()` reports every collision with its count and the `route` of each
+contributing add, so a caller who cares can fail their own build:
 
 ```ts
-import { buildSitemapXml, collectSitemapEntries, type RoutablePage } from "@warlock.js/sitemap";
-
-const pages: RoutablePage[] = [
-  { routeName: "home", routePath: "/" },
-  {
-    routeName: "post-details",
-    routePath: "/posts/:id",
-    sitemap: async () => (await db.posts.find()).map((post) => ({ path: `/posts/${post.slug}` })),
-  },
-];
-
-const { entries } = await collectSitemapEntries(pages, { defaults: { changefreq: "weekly" } });
-const xml = buildSitemapXml(entries, "https://example.com");
+sitemap.duplicates();
+// [ { path: "/posts/1", count: 2, routes: ["/posts/:id", "/:slug"] } ]
 ```
 
-This is the only mode where `buildSitemapXml`'s `origin` argument is
-supplied by hand instead of `resolveOrigin()` — there is no `app.publicUrl`
-to read without `@warlock.js/core`.
-
-## The page-level `sitemap` export
+## `routes()` and why `declareRoute()` exists
 
 ```ts
-// any *.page.tsx — only needed for a dynamic route
-export const sitemap: SitemapEntries = async () => [
-  { path: "/posts/hello-world", lastmod: "2026-09-17", priority: 0.8 },
-];
+sitemap.declareRoute("/products/:slug");
 
-// or, to keep a page out of the sitemap deliberately
-export const sitemap = false;
+sitemap.routes();
+// [ { route: "/posts/:id", count: 400 }, { route: "/products/:slug", count: 0 } ]
 ```
 
-`changefreq` and `priority` are per-entry and optional, falling back to the
-config's `defaults`. They are not part of `PageMetadata` — they mean nothing
-outside a sitemap.
-
-## Building blocks
-
-- `sitemapConnector(options?)` (`src/sitemap-connector.ts`) — the connector
-  `warlock.config.ts` registers; `options.entries` for Mode 2; see "Wiring it
-  up" above. The only module that imports `@warlock.js/core`/`@warlock.js/web`,
-  and only lazily.
-- `NoPageRegistryError` (`src/sitemap-connector.ts`) — see above.
-- `collectSitemapEntries(pages, options)` (`src/collect-entries.ts`) — applies
-  every exclusion rule above and returns `{ entries, unresolvedDynamicRoutes }`.
-  Takes a `RoutablePage[]` — a minimal shape either the runtime wiring adapts
-  from `@warlock.js/web`'s page registry (Mode 3), or an app builds by hand
-  (Mode 1) — not `@warlock.js/web`'s own discovery type.
-- `mergeSitemapEntries(pageEntries, appEntries)` / `withDefaults(entry, defaults)`
-  (`src/collect-entries.ts`) — the dedupe-by-`path` merge (app-supplied wins
-  on collision) and the per-entry default-applying helper, shared by
-  page-derived and app-supplied entries alike.
-- `buildSitemapXml(entries, origin)` (`src/xml.ts`) — serialises entries into
-  the sitemaps.org `urlset` document: correct namespace, element order
-  (`loc`/`lastmod`/`changefreq`/`priority`), and XML escaping of `&`, `<`,
-  `>`, `"`, `'` in every URL (a URL with a query string contains `&`).
-- `resolveOrigin(options)` / `joinOrigin(origin, path)` (`src/url.ts`) — the
-  configured public origin (`app.publicUrl`, env fallback `PUBLIC_APP_URL`),
-  and joining it to a route path with exactly one slash regardless of
-  trailing slashes on either side. Throws `MissingPublicUrlError` when the
-  sitemap is enabled and no origin is configured — a boot-time failure, not a
-  request-time fallback.
-- `describeUnresolvedDynamicRoutes(routeNames)` (`src/diagnostic.ts`) — the
-  dev-mode message for the row above.
-
-## See also
-
-- [`@warlock.js/core/warlock-conventions/SKILL.md`](@warlock.js/core/warlock-conventions/SKILL.md) — the parent framework's conventions.
-- `mongez-agent-kit-authoring-skills` (load via agent-kit sync) — how this `sitemap-overview/SKILL.md` becomes the front-door skill in `.claude/skills/warlock-js-sitemap-overview/`.
+**The zero is the interesting row.** It means a route you expected to
+contribute URLs contributed none, and a whole section of the site is missing
+from a document that otherwise looks perfect.
+
+Without `declareRoute()` a route only becomes known by appearing on an entry,
+so every route has at least one URL, `count: 0` can never occur and the
+diagnostic is decorative. Declaring the pattern is what turns a silent loss
+into a visible one.
+
+**This package reports; it never prints.** Whether a zero is a warning or a
+build failure is the caller's decision.
+
+## Alternates
+
+`alternates` emits `<xhtml:link rel="alternate" hreflang="…">` inside each
+`<url>`. Two rules:
+
+1. **Every language version is also its own `<url>`, carrying the complete
+   alternate set including itself.** Listing alternates on only one of them is
+   the usual way this ships broken.
+2. **The package does not know what a locale is.** `hreflang` is any string —
+   `en`, `en-GB`, `x-default` — and it never derives `/{locale}/…` for you.
+   Each path is supplied explicitly, which is the only thing that works when
+   slugs diverge between languages.
+
+The `xhtml` namespace is declared only when something uses it. `SitemapIndex`
+applies the same rule PER SHARD — a shard declares `xmlns:xhtml` only when its
+own entries carry alternates — and an alternate's `<xhtml:link>` bytes count
+toward that shard's byte ceiling exactly like the rest of its `<url>` block.
+
+## `toXML()` is pure, repeatable and synchronous
+
+Calling it twice returns the same string; it mutates nothing and drains
+nothing. It has no I/O and stays synchronous.
+
+## The ceiling
+
+The protocol caps one file at **50,000 URLs or 50MB uncompressed**. `Sitemap`
+retains every entry — that is what makes `entries()` and a repeatable
+`toXML()` possible — so it is right up to that ceiling and wrong above it. A
+site past it needs the streaming writer, which retains nothing and emits shards
+plus an index.
+
+`maxBytesPerFile` is enforced at shard boundaries, not within an entry: a
+single entry too large for the ceiling is written alone in its own shard
+rather than split — an entry can't be split.
+
+## `SitemapIndex.saveTo(outDir)` owns the whole directory
+
+It publishes atomically by swapping `outDir` for a freshly written temp
+directory in one `rename` — which means `outDir` must be a directory
+dedicated to this sitemap set, never an app's `public/` or anything else
+something else writes to. Every publish marks `outDir` with
+`.sitemap-set.json`; a later call only swaps a directory that is absent,
+empty, or already carries that marker. A non-empty, unmarked `outDir` gets
+`UnownedOutputDirectoryError` instead, and is left completely untouched.
+
+## Errors
+
+| Error | When |
+| --- | --- |
+| `InvalidBaseUrlError` | `baseUrl` missing, relative, or not `http(s)`. From the constructor. |
+| `InvalidSitemapEntryError` | No path, priority outside `0.0`–`1.0`, unknown `changefreq`, invalid `Date`, alternate with no `hreflang`. From `add()`. |
+| `UnownedOutputDirectoryError` | `SitemapIndex.saveTo(outDir)`: `outDir` is non-empty with no `.sitemap-set.json` marker. From `saveTo()`, before anything is written. |
+
+## Also exported
+
+`buildSitemapXml(entries, baseUrl)`, `escapeXml(value)`, `joinOrigin(origin,
+path)` — the pieces the class is built from, for a caller who wants the
+serialiser without the builder.

package/esm/collect-entries.d.mts

@@ -1,44 +0,0 @@
-import { SitemapDefaults, SitemapEntry } from "./types.mjs";
-import { RoutablePage } from "./routable-page.mjs";
-
-//#region ../sitemap/src/collect-entries.d.ts
-/** A route path carries a dynamic segment (`[id]` -> `:id`) it cannot enumerate on its own. */
-declare function isDynamicRoutePath(routePath: string): boolean;
-/** Applies the config's `defaults` to any entry that omits `changefreq`/`priority` — shared by page-derived and app-supplied entries alike. */
-declare function withDefaults(entry: SitemapEntry, defaults: SitemapDefaults | undefined): SitemapEntry;
-/**
- * Combines page-derived entries with app-supplied ones (`SitemapConnectorOptions.entries`),
- * deduplicating by `path`. App-supplied entries are ADDED, not substituted — an
- * app with both a page graph and extra URLs (e.g. rows the page graph can't
- * see) wants both — but where the same path appears in both, the app-supplied
- * entry wins, since it was written for that exact path on purpose.
- */
-declare function mergeSitemapEntries(pageEntries: readonly SitemapEntry[], appEntries: readonly SitemapEntry[]): SitemapEntry[];
-type CollectSitemapEntriesOptions = {
-  defaults?: SitemapDefaults;
-};
-type CollectSitemapEntriesResult = {
-  entries: SitemapEntry[]; /** Route names of dynamic routes with no `sitemap` export — feed to `describeUnresolvedDynamicRoutes`. */
-  unresolvedDynamicRoutes: string[];
-};
-/**
- * Walks the routable pages and produces the entries + the unresolved-dynamic
- * diagnostic input, applying every exclusion rule:
- *
- * - `metadata.robots` says `noindex` -> excluded.
- * - `sitemap: false` -> excluded.
- * - a `sitemap` export (any route) -> its returned entries, in place of the
- *   page's own route path.
- * - a dynamic route with no `sitemap` export -> omitted, name collected.
- * - everything else (static routes) -> one entry at the page's own route path.
- *
- * Not-found and error pages are excluded by construction: the caller is
- * expected to hand this only `DiscoveredRoutablePage`-derived entries, and
- * the not-found route is never one of those (`@warlock.js/web`'s discovery
- * reports it as a routable page for the client matcher, but the runtime
- * wiring filters it out before calling here — see the sitemap README).
- */
-declare function collectSitemapEntries(pages: readonly RoutablePage[], options?: CollectSitemapEntriesOptions): Promise<CollectSitemapEntriesResult>;
-//#endregion
-export { CollectSitemapEntriesOptions, CollectSitemapEntriesResult, collectSitemapEntries, isDynamicRoutePath, mergeSitemapEntries, withDefaults };
-//# sourceMappingURL=collect-entries.d.mts.map

package/esm/collect-entries.mjs

@@ -1,73 +0,0 @@
-//#region ../sitemap/src/collect-entries.ts
-const DYNAMIC_SEGMENT = /(^|\/):[A-Za-z_][A-Za-z0-9_]*/;
-/** A route path carries a dynamic segment (`[id]` -> `:id`) it cannot enumerate on its own. */
-function isDynamicRoutePath(routePath) {
-	return DYNAMIC_SEGMENT.test(routePath);
-}
-function isNoindex(robots) {
-	return robots !== void 0 && /noindex/i.test(robots);
-}
-/** Applies the config's `defaults` to any entry that omits `changefreq`/`priority` — shared by page-derived and app-supplied entries alike. */
-function withDefaults(entry, defaults) {
-	return {
-		...entry,
-		changefreq: entry.changefreq ?? defaults?.changefreq,
-		priority: entry.priority ?? defaults?.priority
-	};
-}
-/**
-* Combines page-derived entries with app-supplied ones (`SitemapConnectorOptions.entries`),
-* deduplicating by `path`. App-supplied entries are ADDED, not substituted — an
-* app with both a page graph and extra URLs (e.g. rows the page graph can't
-* see) wants both — but where the same path appears in both, the app-supplied
-* entry wins, since it was written for that exact path on purpose.
-*/
-function mergeSitemapEntries(pageEntries, appEntries) {
-	const byPath = /* @__PURE__ */ new Map();
-	for (const entry of pageEntries) byPath.set(entry.path, entry);
-	for (const entry of appEntries) byPath.set(entry.path, entry);
-	return Array.from(byPath.values());
-}
-/**
-* Walks the routable pages and produces the entries + the unresolved-dynamic
-* diagnostic input, applying every exclusion rule:
-*
-* - `metadata.robots` says `noindex` -> excluded.
-* - `sitemap: false` -> excluded.
-* - a `sitemap` export (any route) -> its returned entries, in place of the
-*   page's own route path.
-* - a dynamic route with no `sitemap` export -> omitted, name collected.
-* - everything else (static routes) -> one entry at the page's own route path.
-*
-* Not-found and error pages are excluded by construction: the caller is
-* expected to hand this only `DiscoveredRoutablePage`-derived entries, and
-* the not-found route is never one of those (`@warlock.js/web`'s discovery
-* reports it as a routable page for the client matcher, but the runtime
-* wiring filters it out before calling here — see the sitemap README).
-*/
-async function collectSitemapEntries(pages, options = {}) {
-	const entries = [];
-	const unresolvedDynamicRoutes = [];
-	for (const page of pages) {
-		if (isNoindex(page.robots)) continue;
-		if (page.sitemap === false) continue;
-		if (typeof page.sitemap === "function") {
-			const produced = await page.sitemap();
-			for (const entry of produced) entries.push(withDefaults(entry, options.defaults));
-			continue;
-		}
-		if (isDynamicRoutePath(page.routePath)) {
-			unresolvedDynamicRoutes.push(page.routeName);
-			continue;
-		}
-		entries.push(withDefaults({ path: page.routePath }, options.defaults));
-	}
-	return {
-		entries,
-		unresolvedDynamicRoutes
-	};
-}
-
-//#endregion
-export { collectSitemapEntries, isDynamicRoutePath, mergeSitemapEntries, withDefaults };
-//# sourceMappingURL=collect-entries.mjs.map

package/esm/collect-entries.mjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"collect-entries.mjs","names":[],"sources":["../../../../../../sitemap/src/collect-entries.ts"],"sourcesContent":["import type { RoutablePage } from \"./routable-page\";\r\nimport type { SitemapDefaults, SitemapEntry } from \"./types\";\r\n\r\nconst DYNAMIC_SEGMENT = /(^|\\/):[A-Za-z_][A-Za-z0-9_]*/;\r\n\r\n/** A route path carries a dynamic segment (`[id]` -> `:id`) it cannot enumerate on its own. */\r\nexport function isDynamicRoutePath(routePath: string): boolean {\r\n  return DYNAMIC_SEGMENT.test(routePath);\r\n}\r\n\r\nfunction isNoindex(robots: string | undefined): boolean {\r\n  return robots !== undefined && /noindex/i.test(robots);\r\n}\r\n\r\n/** Applies the config's `defaults` to any entry that omits `changefreq`/`priority` — shared by page-derived and app-supplied entries alike. */\r\nexport function withDefaults(entry: SitemapEntry, defaults: SitemapDefaults | undefined): SitemapEntry {\r\n  return {\r\n    ...entry,\r\n    changefreq: entry.changefreq ?? defaults?.changefreq,\r\n    priority: entry.priority ?? defaults?.priority,\r\n  };\r\n}\r\n\r\n/**\r\n * Combines page-derived entries with app-supplied ones (`SitemapConnectorOptions.entries`),\r\n * deduplicating by `path`. App-supplied entries are ADDED, not substituted — an\r\n * app with both a page graph and extra URLs (e.g. rows the page graph can't\r\n * see) wants both — but where the same path appears in both, the app-supplied\r\n * entry wins, since it was written for that exact path on purpose.\r\n */\r\nexport function mergeSitemapEntries(\r\n  pageEntries: readonly SitemapEntry[],\r\n  appEntries: readonly SitemapEntry[],\r\n): SitemapEntry[] {\r\n  const byPath = new Map<string, SitemapEntry>();\r\n\r\n  for (const entry of pageEntries) byPath.set(entry.path, entry);\r\n  for (const entry of appEntries) byPath.set(entry.path, entry);\r\n\r\n  return Array.from(byPath.values());\r\n}\r\n\r\nexport type CollectSitemapEntriesOptions = {\r\n  defaults?: SitemapDefaults;\r\n};\r\n\r\nexport type CollectSitemapEntriesResult = {\r\n  entries: SitemapEntry[];\r\n  /** Route names of dynamic routes with no `sitemap` export — feed to `describeUnresolvedDynamicRoutes`. */\r\n  unresolvedDynamicRoutes: string[];\r\n};\r\n\r\n/**\r\n * Walks the routable pages and produces the entries + the unresolved-dynamic\r\n * diagnostic input, applying every exclusion rule:\r\n *\r\n * - `metadata.robots` says `noindex` -> excluded.\r\n * - `sitemap: false` -> excluded.\r\n * - a `sitemap` export (any route) -> its returned entries, in place of the\r\n *   page's own route path.\r\n * - a dynamic route with no `sitemap` export -> omitted, name collected.\r\n * - everything else (static routes) -> one entry at the page's own route path.\r\n *\r\n * Not-found and error pages are excluded by construction: the caller is\r\n * expected to hand this only `DiscoveredRoutablePage`-derived entries, and\r\n * the not-found route is never one of those (`@warlock.js/web`'s discovery\r\n * reports it as a routable page for the client matcher, but the runtime\r\n * wiring filters it out before calling here — see the sitemap README).\r\n */\r\nexport async function collectSitemapEntries(\r\n  pages: readonly RoutablePage[],\r\n  options: CollectSitemapEntriesOptions = {},\r\n): Promise<CollectSitemapEntriesResult> {\r\n  const entries: SitemapEntry[] = [];\r\n  const unresolvedDynamicRoutes: string[] = [];\r\n\r\n  for (const page of pages) {\r\n    if (isNoindex(page.robots)) continue;\r\n    if (page.sitemap === false) continue;\r\n\r\n    if (typeof page.sitemap === \"function\") {\r\n      const produced = await page.sitemap();\r\n\r\n      for (const entry of produced) entries.push(withDefaults(entry, options.defaults));\r\n\r\n      continue;\r\n    }\r\n\r\n    if (isDynamicRoutePath(page.routePath)) {\r\n      unresolvedDynamicRoutes.push(page.routeName);\r\n      continue;\r\n    }\r\n\r\n    entries.push(withDefaults({ path: page.routePath }, options.defaults));\r\n  }\r\n\r\n  return { entries, unresolvedDynamicRoutes };\r\n}\r\n"],"mappings":";AAGA,MAAM,kBAAkB;;AAGxB,SAAgB,mBAAmB,WAA4B;CAC7D,OAAO,gBAAgB,KAAK,SAAS;AACvC;AAEA,SAAS,UAAU,QAAqC;CACtD,OAAO,WAAW,UAAa,WAAW,KAAK,MAAM;AACvD;;AAGA,SAAgB,aAAa,OAAqB,UAAqD;CACrG,OAAO;EACL,GAAG;EACH,YAAY,MAAM,cAAc,UAAU;EAC1C,UAAU,MAAM,YAAY,UAAU;CACxC;AACF;;;;;;;;AASA,SAAgB,oBACd,aACA,YACgB;CAChB,MAAM,yBAAS,IAAI,IAA0B;CAE7C,KAAK,MAAM,SAAS,aAAa,OAAO,IAAI,MAAM,MAAM,KAAK;CAC7D,KAAK,MAAM,SAAS,YAAY,OAAO,IAAI,MAAM,MAAM,KAAK;CAE5D,OAAO,MAAM,KAAK,OAAO,OAAO,CAAC;AACnC;;;;;;;;;;;;;;;;;;AA6BA,eAAsB,sBACpB,OACA,UAAwC,CAAC,GACH;CACtC,MAAM,UAA0B,CAAC;CACjC,MAAM,0BAAoC,CAAC;CAE3C,KAAK,MAAM,QAAQ,OAAO;EACxB,IAAI,UAAU,KAAK,MAAM,GAAG;EAC5B,IAAI,KAAK,YAAY,OAAO;EAE5B,IAAI,OAAO,KAAK,YAAY,YAAY;GACtC,MAAM,WAAW,MAAM,KAAK,QAAQ;GAEpC,KAAK,MAAM,SAAS,UAAU,QAAQ,KAAK,aAAa,OAAO,QAAQ,QAAQ,CAAC;GAEhF;EACF;EAEA,IAAI,mBAAmB,KAAK,SAAS,GAAG;GACtC,wBAAwB,KAAK,KAAK,SAAS;GAC3C;EACF;EAEA,QAAQ,KAAK,aAAa,EAAE,MAAM,KAAK,UAAU,GAAG,QAAQ,QAAQ,CAAC;CACvE;CAEA,OAAO;EAAE;EAAS;CAAwB;AAC5C"}

package/esm/diagnostic.d.mts

@@ -1,13 +0,0 @@
-//#region ../sitemap/src/diagnostic.d.ts
-/**
- * The dev-mode diagnostic for dynamic routes {@link collectSitemapEntries}
- * (`collect-entries.ts`) could not enumerate — the whole reason this package
- * is written carefully. A dynamic route cannot be enumerated without
- * application data; what the framework controls is whether the developer
- * finds out. Returns `undefined` when there is nothing to report, so a caller
- * can `if (message) console.warn(message)` without an extra length check.
- */
-declare function describeUnresolvedDynamicRoutes(routeNames: readonly string[]): string | undefined;
-//#endregion
-export { describeUnresolvedDynamicRoutes };
-//# sourceMappingURL=diagnostic.d.mts.map

package/esm/diagnostic.mjs

@@ -1,19 +0,0 @@
-//#region ../sitemap/src/diagnostic.ts
-/**
-* The dev-mode diagnostic for dynamic routes {@link collectSitemapEntries}
-* (`collect-entries.ts`) could not enumerate — the whole reason this package
-* is written carefully. A dynamic route cannot be enumerated without
-* application data; what the framework controls is whether the developer
-* finds out. Returns `undefined` when there is nothing to report, so a caller
-* can `if (message) console.warn(message)` without an extra length check.
-*/
-function describeUnresolvedDynamicRoutes(routeNames) {
-	if (routeNames.length === 0) return void 0;
-	const plural = routeNames.length === 1 ? "" : "s";
-	const named = routeNames.map((name) => `  - ${name}`).join("\n");
-	return `[warlock:sitemap] ${routeNames.length} dynamic route${plural} ${routeNames.length === 1 ? "has" : "have"} no \`sitemap\` export and ${routeNames.length === 1 ? "is" : "are"} OMITTED from sitemap.xml:\n${named}\nA dynamic route cannot be enumerated without application data. Add \`export const sitemap: SitemapEntries = async () => [...]\` to each page above, or \`export const sitemap = false\` to keep it out of the sitemap deliberately.`;
-}
-
-//#endregion
-export { describeUnresolvedDynamicRoutes };
-//# sourceMappingURL=diagnostic.mjs.map

package/esm/diagnostic.mjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"diagnostic.mjs","names":[],"sources":["../../../../../../sitemap/src/diagnostic.ts"],"sourcesContent":["/**\n * The dev-mode diagnostic for dynamic routes {@link collectSitemapEntries}\n * (`collect-entries.ts`) could not enumerate — the whole reason this package\n * is written carefully. A dynamic route cannot be enumerated without\n * application data; what the framework controls is whether the developer\n * finds out. Returns `undefined` when there is nothing to report, so a caller\n * can `if (message) console.warn(message)` without an extra length check.\n */\nexport function describeUnresolvedDynamicRoutes(routeNames: readonly string[]): string | undefined {\n  if (routeNames.length === 0) return undefined;\n\n  const plural = routeNames.length === 1 ? \"\" : \"s\";\n  const named = routeNames.map((name) => `  - ${name}`).join(\"\\n\");\n\n  return (\n    `[warlock:sitemap] ${routeNames.length} dynamic route${plural} ` +\n    `${routeNames.length === 1 ? \"has\" : \"have\"} no \\`sitemap\\` export and ` +\n    `${routeNames.length === 1 ? \"is\" : \"are\"} OMITTED from sitemap.xml:\\n${named}\\n` +\n    \"A dynamic route cannot be enumerated without application data. Add \" +\n    \"`export const sitemap: SitemapEntries = async () => [...]` to each page above, \" +\n    \"or `export const sitemap = false` to keep it out of the sitemap deliberately.\"\n  );\n}\n"],"mappings":";;;;;;;;;AAQA,SAAgB,gCAAgC,YAAmD;CACjG,IAAI,WAAW,WAAW,GAAG,OAAO;CAEpC,MAAM,SAAS,WAAW,WAAW,IAAI,KAAK;CAC9C,MAAM,QAAQ,WAAW,KAAK,SAAS,OAAO,MAAM,CAAC,CAAC,KAAK,IAAI;CAE/D,OACE,qBAAqB,WAAW,OAAO,gBAAgB,OAAO,GAC3D,WAAW,WAAW,IAAI,QAAQ,OAAO,6BACzC,WAAW,WAAW,IAAI,OAAO,MAAM,8BAA8B,MAAM;AAKlF"}

package/esm/routable-page.d.mts

@@ -1,27 +0,0 @@
-import { SitemapEntries } from "./types.mjs";
-
-//#region ../sitemap/src/routable-page.d.ts
-/**
- * A page's `sitemap` export: the entries function, an explicit opt-out
- * (`export const sitemap = false`), or absent entirely.
- */
-type SitemapPageExport = SitemapEntries | false | undefined;
-/**
- * The minimal facts {@link collectSitemapEntries} (`collect-entries.ts`) needs
- * about one routable page.
- *
- * Deliberately NOT `DiscoveredRoutablePage` from `@warlock.js/web` — that type
- * carries filesystem paths, layout chains and middleware wiring this package
- * has no business reading. The runtime wiring (a separate package, adapting
- * `discoverPages()` and each page module's exports) builds this shape; this
- * package only ever consumes it.
- */
-type RoutablePage = {
-  /** Unique route identity — named in the dynamic-route diagnostic when unresolved. */routeName: string; /** The effective route path, `:param` for a dynamic segment (e.g. `/posts/:id`). */
-  routePath: string; /** `metadata.robots`, when the page's `metadata` export is a static object. */
-  robots?: string;
-  sitemap?: SitemapPageExport;
-};
-//#endregion
-export { RoutablePage, SitemapPageExport };
-//# sourceMappingURL=routable-page.d.mts.map

package/esm/sitemap-connector.d.mts

@@ -1,60 +0,0 @@
-import { SitemapConfig, SitemapEntries } from "./types.mjs";
-import { Connector } from "@warlock.js/core";
-
-//#region ../sitemap/src/sitemap-connector.d.ts
-/** Default path when `src/config/sitemap.ts` does not set one. */
-declare const DEFAULT_SITEMAP_PATH = "/sitemap.xml";
-/**
- * Boots after the HTTP connector (`ConnectorPriority.HTTP` is `5`) and after
- * web (`5.5`, `web-connector-factory.ts`) — the route it registers has to
- * land on the same router web's pages already share, and `listRoutablePages`
- * only has a page graph to read once web has scanned it.
- */
-declare const SITEMAP_CONNECTOR_PRIORITY = 5.6;
-type SitemapConnectorOptions = {
-  /** Supply the configuration directly instead of reading the `sitemap` config key (`src/config/sitemap.ts`). */config?: SitemapConfig;
-  /**
-   * App-supplied entries — the only source of entries in a Warlock **API-only**
-   * project, which has no `@warlock.js/web` page registry for `listRoutablePages()`
-   * to read. When `@warlock.js/web` IS installed, these are ADDED to the
-   * page-derived entries (see {@link mergeSitemapEntries}), not substituted, so an
-   * app with both pages and extra URLs (e.g. rows a database holds) gets both.
-   */
-  entries?: SitemapEntries;
-};
-/**
- * Raised at `boot()` when the sitemap is enabled but has no way to produce
- * entries: `@warlock.js/web` is not installed, so there is no page registry
- * for `listRoutablePages()` to read, AND no `entries` option was supplied.
- * Refuses to boot rather than registering a route that would silently serve
- * an empty `<urlset>` — the same reasoning as {@link MissingPublicUrlError}:
- * a sitemap that looks complete while producing nothing is worse than one
- * that never started.
- */
-declare class NoPageRegistryError extends Error {
-  constructor();
-}
-/**
- * Construct the sitemap connector.
- *
- * At `boot()`: reads the `sitemap` config (a no-op when `enabled` is not
- * `true`), resolves the public origin ONCE — failing loud via
- * {@link resolveOrigin}'s {@link MissingPublicUrlError} rather than falling
- * back to a request-derived host — and registers `GET <config.path>`.
- *
- * The route itself re-reads the page graph on every request via
- * `listRoutablePages()`, not once at boot: the registry can change under
- * `warlock dev`, and a sitemap that only reflects the app's shape at the
- * moment it booted is stale in exactly the way that made `2ede40cf`-class
- * defects expensive.
- *
- * @example
- * // warlock.config.ts
- * import { sitemapConnector } from "@warlock.js/sitemap";
- *
- * export default defineConfig({ connectors: [sitemapConnector()] });
- */
-declare function sitemapConnector(options?: SitemapConnectorOptions): Connector;
-//#endregion
-export { DEFAULT_SITEMAP_PATH, NoPageRegistryError, SITEMAP_CONNECTOR_PRIORITY, SitemapConnectorOptions, sitemapConnector };
-//# sourceMappingURL=sitemap-connector.d.mts.map