@jxsuite/parser 1.8.2 → 2.0.1

package/src/content-loader.ts

@@ -18,9 +18,9 @@
  */
 
 import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
-import { basename, dirname, extname, resolve } from "node:path";
+import { basename, dirname, extname, relative, resolve } from "node:path";
 import { assetUrlFor } from "@jxsuite/schema/asset-paths";
-import { resolveI18n } from "@jxsuite/schema/locale";
+import { localeUrlPrefix, resolveI18n } from "@jxsuite/schema/locale";
 import type { AssetMount } from "@jxsuite/schema/asset-paths";
 import type { ExtensionRegistry } from "@jxsuite/schema/extension-registry";
 import type { FormatEntry, FormatHostIO, FormatRegistry } from "@jxsuite/schema/format-registry";
@@ -30,8 +30,25 @@ import type {
   JxMutableNode,
   ProjectConfig,
 } from "@jxsuite/schema/types";
+import { normalizeAlerts } from "./alerts.ts";
+import { rewriteLinks } from "./content-links.ts";
+import type { FileOutcome, LinkIndex } from "./content-links.ts";
+import {
+  directoryOf,
+  isDirectoryIndex,
+  parseRouteConfig,
+  renderRoute,
+  routeHref,
+  routeParams,
+  traversalReason,
+} from "./content-routes.ts";
+import type { RouteSpec } from "./content-routes.ts";
+import { compileExclude, compileWhere } from "./content-rules.ts";
+import type { ExcludeMatcher, WherePredicate } from "./content-rules.ts";
 import { coerceEntryDates, isCoercedDate, isDateFormat } from "./dates.ts";
+import type { ContentNodes } from "./inert.ts";
 import type { ContentLoaderEntry, ContentTypeDef } from "./types.ts";
+import { walkFiles } from "./walk.ts";
 
 export type { ContentEntry, ContentLoaderEntry, TocEntry } from "./types.ts";
 
@@ -63,6 +80,18 @@ export interface ResolvePathsContext {
    * reads it — it is the discriminator between two translations sharing an id.
    */
   locale?: string | null;
+  /**
+   * The URL pattern of the dynamic page being expanded (`/kb/:category/:slug`, `/kb/*`) and its
+   * parameter names in order. A content type with a `route` reads them to turn each entry's route
+   * into the parameters THIS page needs, so `$paths` never has to name a parameter.
+   */
+  urlPattern?: string;
+  params?: readonly string[];
+  /**
+   * The URL patterns of every dynamic page in the project, so a routed content type can report the
+   * entries no page at all would generate (a route no page shape produces is a dead link).
+   */
+  patterns?: readonly string[];
 }
 
 /** The `$paths` value shape routed to this extension by its `contentType` discriminator. */
@@ -101,18 +130,12 @@ function loadJSONEntries(filePath: string): ContentLoaderEntry[] {
   ];
 }
 
-/** Discover .json entry files for a source (single file or directory). */
-function discoverJSONFiles(resolvedSource: string): string[] {
+/** Discover .json entry files for a source (single file or directory), in sorted order. */
+function discoverJSONFiles(resolvedSource: string, exclude: ExcludeMatcher): string[] {
   if (extname(resolvedSource)) {
     return existsSync(resolvedSource) ? [resolvedSource] : [];
   }
-  try {
-    return readdirSync(resolvedSource, { recursive: true })
-      .filter((f) => String(f).endsWith(".json"))
-      .map((f) => resolve(resolvedSource, String(f)));
-  } catch {
-    return [];
-  }
+  return walkFiles(resolvedSource, (name) => name.toLowerCase().endsWith(".json"), exclude);
 }
 
 // ─── Asset mounts and content-relative references ────────────────────────────
@@ -201,6 +224,44 @@ function isNonRelativeRef(value: string): boolean {
   );
 }
 
+/** Document extensions: an entry of a collection is never an asset of it. */
+const DOCUMENT_EXTENSIONS = new Set([".md", ".markdown", ".mdx"]);
+
+/**
+ * What a content type's asset mount may serve, or `undefined` for "everything under the directory"
+ * (today's behavior, which every type that declares none of the vault options keeps).
+ *
+ * A type that declares `exclude`, `where` or `route` is publishing a folder of notes, and there the
+ * mount is the collection's front door, so it must not be a way around the collection's own rules:
+ * a file `exclude` names is not served however a page refers to it, nothing whose path has a dot
+ * segment is (`.git`, `.env` and `.obsidian` are what a source set to the repository root also
+ * contains), and a document is not (a note `where` left out would otherwise leave as a raw
+ * download, frontmatter and all). The paths it is asked about are relative to the mount directory,
+ * which is the source directory.
+ */
+function mountFilterFor(def: ContentTypeDef | undefined): ((path: string) => boolean) | undefined {
+  if (!def || (def.exclude === undefined && def.where === undefined && def.route === undefined)) {
+    return undefined;
+  }
+  let exclude: ExcludeMatcher;
+  try {
+    exclude = compileExclude(def.exclude);
+  } catch {
+    // The same list fails the build when the type loads; until then, serve nothing.
+    return () => false;
+  }
+  return (path) => {
+    const segments = path.split("/");
+    if (segments.some((segment) => segment.startsWith("."))) {
+      return false;
+    }
+    if (DOCUMENT_EXTENSIONS.has(extname(path).toLowerCase())) {
+      return false;
+    }
+    return exclude.excludedBy(path) === undefined;
+  };
+}
+
 /**
  * Asset mounts for a `content` section: every content type whose source is a local **directory**
  * publishes that directory at `/content/<type>`, so files sitting beside the entries (images,
@@ -218,6 +279,10 @@ export function contentAssetMounts(
 ): AssetMount[] {
   const mounts: AssetMount[] = [];
   const locales = localesForExpansion(projectConfig);
+  const filterOf = (def: ContentTypeDef | undefined): { filter?: (path: string) => boolean } => {
+    const filter = mountFilterFor(def);
+    return filter === undefined ? {} : { filter };
+  };
   for (const [name, contentTypeDef] of Object.entries(section ?? {})) {
     const source = contentTypeDef?.source;
     if (!source || source.startsWith("http://") || source.startsWith("https://")) {
@@ -237,7 +302,11 @@ export function contentAssetMounts(
           .split("\\")
           .join("/");
         if (SAFE_TYPE_NAME.test(name) && existsSync(dir) && statSync(dir).isDirectory()) {
-          mounts.push({ dir, urlPrefix: `/${SECTION_KEY}/${name}/${locale}` });
+          mounts.push({
+            dir,
+            urlPrefix: `/${SECTION_KEY}/${name}/${locale}`,
+            ...filterOf(contentTypeDef),
+          });
         }
       }
       continue;
@@ -253,22 +322,31 @@ export function contentAssetMounts(
     if (extname(source) || !existsSync(resolvedSource) || !statSync(resolvedSource).isDirectory()) {
       continue;
     }
-    mounts.push({ dir: resolvedSource, urlPrefix: `/${SECTION_KEY}/${name}` });
+    mounts.push({
+      dir: resolvedSource,
+      urlPrefix: `/${SECTION_KEY}/${name}`,
+      ...filterOf(contentTypeDef),
+    });
   }
   return mounts;
 }
 
+/** Why a content-relative reference was left as written. */
+type RefProblem = "missing" | "refused";
+
 /**
  * Rewrite one content-relative reference to its mounted URL, or null to leave the value untouched.
  * A value is rewritten only when it is relative, resolves against the entry's own directory to a
- * file that exists, and lands inside the mount — so nothing an existing project authored (a
- * project-root-relative path, an absolute URL, a bound template) changes meaning.
+ * file that exists, and lands inside the mount and where the mount serves — so nothing an existing
+ * project authored (a project-root-relative path, an absolute URL, a bound template) changes
+ * meaning. A file inside the collection that its mount refuses to serve (excluded, hidden or a
+ * document) is reported and left as written, so a published note cannot pull it into the site.
  */
 function rewriteRef(
   value: string,
   entryDir: string,
   mount: AssetMount,
-  onMissing: (value: string) => void,
+  onProblem: (value: string, problem: RefProblem) => void,
 ): string | null {
   if (isNonRelativeRef(value)) {
     return null;
@@ -282,10 +360,13 @@ function rewriteRef(
   }
   const url = assetUrlFor([mount], target);
   if (!url) {
-    return null; // Resolves outside the collection — not ours to publish
+    if (relativeTo(mount.dir, target) !== null && existsSync(target)) {
+      onProblem(value, "refused");
+    }
+    return null; // Resolves outside the collection, or is not served — not ours to publish
   }
   if (!existsSync(target)) {
-    onMissing(value);
+    onProblem(value, "missing");
     return null;
   }
   const suffix = value.slice(bare.length);
@@ -294,11 +375,17 @@ function rewriteRef(
 
 /** Rewrite media references on one node and its children, in place. */
 function rewriteNodeAssets(
-  node: JxElement | string | undefined,
+  node: JxElement | string | ContentNodes | undefined,
   entryDir: string,
   mount: AssetMount,
-  onMissing: (value: string) => void,
+  onProblem: (value: string, problem: RefProblem) => void,
 ) {
+  if (Array.isArray(node)) {
+    for (const child of node) {
+      rewriteNodeAssets(child, entryDir, mount, onProblem);
+    }
+    return;
+  }
   if (!node || typeof node !== "object") {
     return;
   }
@@ -308,7 +395,7 @@ function rewriteNodeAssets(
     for (const holder of [record, attributes]) {
       const value = holder?.[key];
       if (typeof value === "string") {
-        const rewritten = rewriteRef(value, entryDir, mount, onMissing);
+        const rewritten = rewriteRef(value, entryDir, mount, onProblem);
         if (rewritten) {
           holder![key] = rewritten;
         }
@@ -318,7 +405,7 @@ function rewriteNodeAssets(
   const { children } = record;
   if (Array.isArray(children)) {
     for (const child of children) {
-      rewriteNodeAssets(child as JxElement | string, entryDir, mount, onMissing);
+      rewriteNodeAssets(child as JxElement | string | ContentNodes, entryDir, mount, onProblem);
     }
   }
 }
@@ -351,22 +438,26 @@ export function rewriteEntryAssets(
     .map(([field]) => field);
 
   for (const entry of entries) {
-    const onMissing = (value: string) =>
+    const onProblem = (value: string, problem: RefProblem) =>
       console.warn(
-        `Content type "${typeName}": entry "${entry.id}" references missing asset "${value}"`,
+        problem === "missing"
+          ? `Content type "${typeName}": entry "${entry.id}" references missing asset "${value}"`
+          : `Content type "${typeName}": entry "${entry.id}" references "${value}", which the ` +
+              `collection does not publish (it is excluded, hidden or a document), so the ` +
+              `reference is left as written`,
       );
 
     for (const child of entry.$children ?? []) {
-      rewriteNodeAssets(child, entryDir, mount, onMissing);
+      rewriteNodeAssets(child, entryDir, mount, onProblem);
     }
 
     for (const field of uriFields) {
       const value = entry.data[field];
       if (typeof value === "string") {
-        entry.data[field] = rewriteRef(value, entryDir, mount, onMissing) ?? value;
+        entry.data[field] = rewriteRef(value, entryDir, mount, onProblem) ?? value;
       } else if (Array.isArray(value)) {
         entry.data[field] = value.map((item) =>
-          typeof item === "string" ? (rewriteRef(item, entryDir, mount, onMissing) ?? item) : item,
+          typeof item === "string" ? (rewriteRef(item, entryDir, mount, onProblem) ?? item) : item,
         );
       }
     }
@@ -425,7 +516,10 @@ export async function loadContentSection(
   for (const [name, contentTypeDef] of Object.entries(section)) {
     const source = contentTypeDef?.source;
     if (typeof source !== "string" || !source.includes(LOCALE_PLACEHOLDER)) {
-      const entries = await loadContentType(name, contentTypeDef, root, formats, mounts.get(name));
+      const entries = await loadContentType(name, contentTypeDef, root, formats, {
+        mount: mounts.get(name),
+        projectConfig,
+      });
       contentTypes.set(name, entries);
       continue;
     }
@@ -445,13 +539,11 @@ export async function loadContentSection(
     const all: ContentLoaderEntry[] = [];
     for (const locale of locales) {
       const localized = { ...contentTypeDef, source: localeSource(root, source, locale) };
-      const entries = await loadContentType(
-        name,
-        localized,
-        root,
-        formats,
-        mounts.get(`${name}/${locale}`),
-      );
+      const entries = await loadContentType(name, localized, root, formats, {
+        locale,
+        mount: mounts.get(`${name}/${locale}`),
+        projectConfig,
+      });
       for (const entry of entries) {
         entry._meta = { ...entry._meta, locale };
       }
@@ -481,6 +573,526 @@ export function getContentTypeElements(
   return def?.$elements;
 }
 
+// ─── Per-type rules ──────────────────────────────────────────────────────────
+
+/** How a link that has no page is reported (`links`). */
+type LinkMode = "warn" | "error" | "ignore";
+
+/** A content type's declarative options, validated once per load. */
+interface TypeRules {
+  exclude: ExcludeMatcher;
+  where: WherePredicate | null;
+  idField: string | undefined;
+  route: RouteSpec | null;
+  links: LinkMode;
+  alerts: unknown;
+}
+
+/** Every key a content type's definition means something by. */
+const KNOWN_TYPE_KEYS = [
+  "$elements",
+  "alerts",
+  "exclude",
+  "format",
+  "idField",
+  "indexRoute",
+  "links",
+  "route",
+  "schema",
+  "source",
+  "where",
+] as const;
+
+/** Edit distance between two short strings, for the "did you mean" of a misspelled option. */
+function editDistance(a: string, b: string): number {
+  let previous = Array.from({ length: b.length + 1 }, (_, i) => i);
+  for (let i = 1; i <= a.length; i++) {
+    const row = [i];
+    for (let j = 1; j <= b.length; j++) {
+      row[j] = Math.min(
+        row[j - 1]! + 1,
+        previous[j]! + 1,
+        previous[j - 1]! + (a[i - 1] === b[j - 1] ? 0 : 1),
+      );
+    }
+    previous = row;
+  }
+  return previous[b.length]!;
+}
+
+/**
+ * The option a misspelled key most plausibly meant, or undefined when none is close.
+ *
+ * The options exist to keep things OUT of a published site, so a typo in one fails open: `excludes`
+ * would be ignored and the private folder it was meant to hide would be published. That is why a
+ * near miss is a build error and not a note.
+ */
+function nearestOption(key: string): string | undefined {
+  const lower = key.toLowerCase();
+  let best: string | undefined;
+  let bestDistance = 3;
+  for (const known of KNOWN_TYPE_KEYS) {
+    const distance = editDistance(lower, known.toLowerCase());
+    if (distance < bestDistance) {
+      best = known;
+      bestDistance = distance;
+    }
+  }
+  return best;
+}
+
+/**
+ * Validate and compile a content type's `exclude`, `where`, `idField`, `route`, `links` and
+ * `alerts`. A malformed option is a build failure that names the content type, never a silently
+ * ignored key: `where: { publish: "yes" }` that quietly matched nothing would publish an empty site
+ * and say nothing, and neither would `excludes` (for `exclude`) say it was being ignored.
+ */
+function compileTypeRules(name: string, def: ContentTypeDef): TypeRules {
+  const at = `Content type "${name}"`;
+  try {
+    for (const key of Object.keys(def)) {
+      if ((KNOWN_TYPE_KEYS as readonly string[]).includes(key) || key === "$comment") {
+        continue;
+      }
+      const suggestion = nearestOption(key);
+      if (suggestion !== undefined) {
+        throw new TypeError(`unknown option "${key}", did you mean "${suggestion}"?`);
+      }
+      console.warn(
+        `${at}: ignores the unknown option "${key}" (the options are ${KNOWN_TYPE_KEYS.join(", ")})`,
+      );
+    }
+    if (def.idField !== undefined && (typeof def.idField !== "string" || def.idField === "")) {
+      throw new TypeError(`"idField" must be a field name`);
+    }
+    const links = def.links ?? "warn";
+    if (links !== "warn" && links !== "error" && links !== "ignore") {
+      throw new TypeError(
+        `"links" must be "warn", "error" or "ignore", got ${JSON.stringify(links)}`,
+      );
+    }
+    normalizeAlerts(def.alerts, `"alerts"`);
+    return {
+      alerts: def.alerts,
+      exclude: compileExclude(def.exclude),
+      idField: def.idField,
+      links,
+      route: parseRouteConfig(def.route, def.indexRoute, name),
+      where: def.where === undefined ? null : compileWhere(def.where),
+    };
+  } catch (error) {
+    const message = errorMessage(error);
+    throw new Error(message.startsWith(at) ? message : `${at}: ${message}`, { cause: error });
+  }
+}
+
+/** The path of a file relative to a source directory, `/`-separated, or null when it is outside. */
+function relativeTo(root: string, file: string): string | null {
+  const rel = relative(root, file).split("\\").join("/");
+  return rel === "" || rel === ".." || rel.startsWith("../") ? null : rel;
+}
+
+/** One source file and the entries it yielded, before the collection-wide rules run. */
+interface LoadedFile {
+  filePath: string;
+  /** Relative to the source directory; null for a single-file or remote source. */
+  rel: string | null;
+  entries: ContentLoaderEntry[];
+}
+
+/** Everything {@link finishEntries} needs that is not the entries themselves. */
+interface FinishContext {
+  name: string;
+  schema: ContentTypeSchema | undefined;
+  rules: TypeRules;
+  mount: AssetMount | undefined;
+  projectConfig: ProjectConfig | undefined;
+  locale: string | undefined;
+  /** Whether the format branch's date-coercion pass applies (it does not for JSON and remote). */
+  coerceDates: boolean;
+  /** Extensions of the collection's entry files, for link resolution. */
+  entryExtensions: Set<string>;
+  /** The source directory, when there is one. */
+  sourceRoot: string | undefined;
+}
+
+/**
+ * The collection-wide pass every source kind goes through once its files are loaded.
+ *
+ * Order matters and is the whole design. `where` runs first, so an entry that is not published is
+ * never validated, coerced, given a route or counted as a duplicate. Ids are settled before
+ * anything keyed by id (relationships, duplicate checks, routes that read `{id}`). Routes are
+ * computed before links, because a link can only be resolved once the page it points at has a URL.
+ *
+ * @returns {ContentLoaderEntry[]} The kept entries, in load order
+ */
+function finishEntries(files: LoadedFile[], ctx: FinishContext): ContentLoaderEntry[] {
+  const { name, rules } = ctx;
+
+  // 1. where: split every file's entries into kept and left out.
+  const kept: LoadedFile[] = [];
+  const unpublished = new Map<string, string>();
+  let loadedCount = 0;
+  for (const file of files) {
+    const keep: ContentLoaderEntry[] = [];
+    for (const entry of file.entries) {
+      loadedCount += 1;
+      if (rules.where && !rules.where(entry.data)) {
+        if (file.rel !== null && file.entries.length === 1) {
+          unpublished.set(file.rel, `left out by where.${rules.where.why(entry.data) ?? "filter"}`);
+        }
+      } else {
+        keep.push(entry);
+      }
+    }
+    if (keep.length > 0) {
+      kept.push({ ...file, entries: keep });
+    }
+  }
+  /* A filter that removes every document is nearly always a mistake in the filter (`publish: "true"`
+     against a YAML boolean), and the result is an empty site that builds without complaint. */
+  if (rules.where && loadedCount > 0 && kept.length === 0) {
+    const [first] = files.flatMap((file) => file.entries);
+    console.warn(
+      `Content type "${name}": "where" left out all ${loadedCount} entries, so the collection is ` +
+        `empty (it failed on "${first ? (rules.where.why(first.data) ?? "?") : "?"}" for the first one). ` +
+        `Check the field names and the value types: YAML \`true\` is a boolean, "true" is text.`,
+    );
+  }
+
+  // 2. Per kept entry: where it came from, and content-relative assets onto the mount.
+  for (const file of kept) {
+    for (const entry of file.entries) {
+      if (file.rel !== null) {
+        entry._meta = { ...entry._meta, path: file.rel };
+      }
+    }
+    if (ctx.mount) {
+      rewriteEntryAssets(file.entries, file.filePath, ctx.mount, name, ctx.schema);
+    }
+  }
+  const entries = kept.flatMap((file) => file.entries);
+
+  // 3. Ids: a README beside an index, then the frontmatter field the type names, then duplicates.
+  settleIndexIds(name, entries);
+  if (rules.idField) {
+    for (const entry of entries) {
+      const value = entry.data[rules.idField];
+      if ((typeof value === "string" && value !== "") || typeof value === "number") {
+        /* An id becomes a directory name under the output (`$paths` hands it to a page), and a
+           frontmatter value is not trusted to stay inside it. */
+        const unsafe = traversalReason(String(value));
+        if (unsafe === null) {
+          entry.id = String(value);
+        } else {
+          console.warn(
+            `Content ids: "${name}/${entry.id}" has a "${rules.idField}" that ${unsafe}, ` +
+              `so it keeps its path id`,
+          );
+        }
+      } else {
+        console.warn(
+          `Content ids: "${name}/${entry.id}" has no usable "${rules.idField}" field, ` +
+            `so it keeps its path id`,
+        );
+      }
+    }
+  }
+  const byId = new Map<string, ContentLoaderEntry>();
+  for (const entry of entries) {
+    const prior = byId.get(entry.id);
+    if (prior) {
+      console.warn(
+        `Content ids: "${name}" has two entries with the id "${entry.id}" ` +
+          `(${prior._meta?.path ?? "an earlier entry"} and ${entry._meta?.path ?? "a later entry"}). ` +
+          `A lookup finds only the first; give one of them a distinct ${rules.idField ? `"${rules.idField}"` : "name"}.`,
+      );
+    } else {
+      byId.set(entry.id, entry);
+    }
+  }
+
+  // 4. Dates, then validation: kept entries only.
+  if (ctx.schema) {
+    if (ctx.coerceDates) {
+      for (const warning of coerceEntryDates(entries, ctx.schema, name)) {
+        console.warn(warning.message);
+      }
+    }
+    validateEntries(entries, ctx.schema, name);
+  }
+
+  // 5. Routes, and links over the finished routes.
+  if (rules.route) {
+    assignRoutes(entries, unpublished, ctx, rules.route);
+    if (ctx.sourceRoot) {
+      resolveEntryLinks(kept, unpublished, ctx);
+    }
+    /* An entry the template could not route, or whose route another entry holds, has no page, and
+       a collection is what every consumer (a listing, the search index, a feed) publishes from. Left
+       in, each of them would invent a URL for it from its own idea of one and point readers at a
+       404, and the document the build calls unpublished would be in the public search index. The
+       link index above already knows why it has no page; the collection does not carry it. */
+    return entries.filter((entry) => entry._meta?.route !== undefined);
+  }
+  return entries;
+}
+
+/**
+ * Keep a folder's id for its `index` file when its `README` would also claim it.
+ *
+ * A README maps to its folder (`Frappe/README.md` is `Frappe`), and so has `index.md` since before
+ * READMEs did. A folder holding both used to give them two ids and now would give them one, with
+ * whichever sorted first (README, by case) silently winning an `index.md` that is older and means
+ * the same thing. The index keeps the folder's id, as links and routes already assume, and the
+ * README keeps the id it had before the mapping existed.
+ */
+function settleIndexIds(name: string, entries: ContentLoaderEntry[]): void {
+  const indexFolders = new Set<string>();
+  for (const entry of entries) {
+    const path = entry._meta?.path;
+    if (path !== undefined && isDirectoryIndex(path) && !/^readme\./i.test(basename(path))) {
+      indexFolders.add(directoryOf(path));
+    }
+  }
+  for (const entry of entries) {
+    const path = entry._meta?.path;
+    if (path === undefined || !/^readme\./i.test(basename(path))) {
+      continue;
+    }
+    const folder = directoryOf(path);
+    if (folder !== "" && entry.id === folder && indexFolders.has(folder)) {
+      entry.id = path.slice(0, path.length - extname(path).length);
+      console.warn(
+        `Content ids: "${name}" has both "${path}" and an index file in "${folder}"; the index ` +
+          `keeps the id "${folder}" and the README is "${entry.id}".`,
+      );
+    }
+  }
+}
+
+/** The site's `build.trailingSlash`, defaulting to `"always"` exactly as the build does. */
+function trailingSlashOf(projectConfig: ProjectConfig | undefined): string {
+  const value = projectConfig?.build?.trailingSlash;
+  return typeof value === "string" ? value : "always";
+}
+
+/** The URL prefix a collection's locale puts in front of its routes (`/fr`), or `""`. */
+function localePrefixOf(ctx: FinishContext): string {
+  const { i18n } = resolveI18n(ctx.projectConfig ?? {});
+  return localeUrlPrefix(ctx.locale, i18n);
+}
+
+/**
+ * Stamp `_meta.route` and `_meta.url` on every entry whose route template renders.
+ *
+ * An entry the template cannot render (a missing `category`) and an entry whose route another
+ * already holds are both left without a route and reported with the file names involved: the second
+ * would otherwise overwrite the first's page, or hand a link to the wrong document. Both are
+ * recorded as unpublished so a link to one says why it has no page.
+ */
+function assignRoutes(
+  entries: ContentLoaderEntry[],
+  unpublished: Map<string, string>,
+  ctx: FinishContext,
+  spec: RouteSpec,
+): void {
+  const trailingSlash = trailingSlashOf(ctx.projectConfig);
+  const prefix = localePrefixOf(ctx);
+  const owner = new Map<string, string>();
+  /* One line per entry says what is wrong with it, until there are enough that one line per entry
+     is a wall: a template naming a field no document has (`{slugg}`) fails for every entry with the
+     same reason, and naming the reason once with a count and a few examples is the useful report. */
+  const unrouted = new Map<string, { id: string; path: string }[]>();
+  for (const entry of entries) {
+    const path = entry._meta?.path ?? entry.id;
+    const rendered = renderRoute(spec, { data: entry.data, id: entry.id, path });
+    if ("error" in rendered) {
+      unrouted.set(rendered.error, [
+        ...(unrouted.get(rendered.error) ?? []),
+        { id: entry.id, path },
+      ]);
+      unpublished.set(path, "it has no route");
+      continue;
+    }
+    const prior = owner.get(rendered.route);
+    if (prior !== undefined) {
+      console.warn(
+        `Content routes: "${ctx.name}" has two entries at ${rendered.route} (${prior} and ${path}). ` +
+          `Only ${prior} is routed; make the route unique, for example by adding a field to the template.`,
+      );
+      unpublished.set(path, `its route ${rendered.route} is already used by ${prior}`);
+      continue;
+    }
+    owner.set(rendered.route, path);
+    entry._meta = {
+      ...entry._meta,
+      route: rendered.route,
+      url: routeHref(rendered.route, trailingSlash, prefix),
+    };
+  }
+  for (const [reason, list] of unrouted) {
+    if (list.length <= UNROUTED_LISTED) {
+      for (const { id, path } of list) {
+        console.warn(`Content routes: "${ctx.name}/${id}" (${path}) has no route: ${reason}`);
+      }
+    } else {
+      const shown = list.slice(0, UNROUTED_LISTED).map(({ path }) => path);
+      console.warn(
+        `Content routes: "${ctx.name}": ${list.length} entries have no route: ${reason} ` +
+          `(for example ${shown.join(", ")})`,
+      );
+    }
+  }
+}
+
+/** How many entries a "has no route" report lists by name before it summarizes. */
+const UNROUTED_LISTED = 3;
+
+/** One broken link, for the error-mode summary. */
+interface BrokenLink {
+  from: string;
+  href: string;
+  reason: string;
+}
+
+/**
+ * Rewrite the relative links of every kept entry to the routes of the entries they name.
+ *
+ * Builds the {@link LinkIndex} the resolver needs from what the loader knows (every file it loaded,
+ * which of them are published, which directory each README or index stands for), then reports each
+ * link that has no page at the severity `links` asks for. In `error` mode all of them are gathered
+ * and thrown together, so one build names every broken link instead of one per run.
+ */
+function resolveEntryLinks(
+  kept: LoadedFile[],
+  unpublished: Map<string, string>,
+  ctx: FinishContext,
+): void {
+  const { name, rules, sourceRoot } = ctx;
+  const files = new Map<string, FileOutcome>();
+  const indexes = new Map<string, string>();
+  const isReadme = (rel: string) => /^readme\./i.test(rel.slice(rel.lastIndexOf("/") + 1));
+  const noteIndex = (rel: string) => {
+    const dir = directoryOf(rel);
+    const prior = indexes.get(dir);
+    // `index` beats `README` when a directory has both, matching how ids are derived.
+    if (prior === undefined || (isReadme(prior) && !isReadme(rel))) {
+      indexes.set(dir, rel);
+    }
+  };
+  for (const file of kept) {
+    const [entry] = file.entries;
+    if (file.rel === null || file.entries.length !== 1 || !entry) {
+      continue;
+    }
+    const route = entry._meta?.route;
+    files.set(
+      file.rel,
+      route === undefined
+        ? { unpublished: unpublished.get(file.rel) ?? "it has no route" }
+        : { route },
+    );
+    if (isDirectoryIndex(file.rel)) {
+      noteIndex(file.rel);
+    }
+  }
+  for (const [rel, reason] of unpublished) {
+    if (!files.has(rel)) {
+      files.set(rel, { unpublished: reason });
+      if (isDirectoryIndex(rel)) {
+        noteIndex(rel);
+      }
+    }
+  }
+
+  const onDisk = (path: string) => resolve(sourceRoot!, path);
+  const index: LinkIndex = {
+    asset: (path) => {
+      const absolute = onDisk(path);
+      if (!ctx.mount || !existsSync(absolute) || statSync(absolute).isDirectory()) {
+        return;
+      }
+      const pattern = rules.exclude.excludedBy(path);
+      if (pattern !== undefined) {
+        return { unpublished: `excluded by "${pattern}"` };
+      }
+      const url = assetUrlFor([ctx.mount], absolute);
+      return url === null ? { unpublished: "the collection does not serve a file there" } : { url };
+    },
+    entryExtensions: ctx.entryExtensions,
+    excludedBy: (path) => rules.exclude.excludedBy(path),
+    excludesDir: (path) => rules.exclude.excludesDir(path),
+    exists: (path) => existsSync(onDisk(path)),
+    files,
+    indexes,
+    isDirectory: (path) => {
+      try {
+        return statSync(onDisk(path)).isDirectory();
+      } catch {
+        return false;
+      }
+    },
+    localePrefix: localePrefixOf(ctx),
+    trailingSlash: trailingSlashOf(ctx.projectConfig),
+  };
+
+  const broken: BrokenLink[] = [];
+  const seen = new Set<string>();
+  for (const file of kept) {
+    for (const entry of file.entries) {
+      if (!entry.$children || file.rel === null) {
+        continue;
+      }
+      rewriteLinks(entry.$children as ContentNodes, file.rel, index, (problem) => {
+        const key = `${file.rel}\0${problem.href}`;
+        if (!seen.has(key)) {
+          seen.add(key);
+          broken.push({ from: file.rel!, href: problem.href, reason: problem.reason });
+        }
+      });
+    }
+  }
+  if (rules.links === "ignore" || broken.length === 0) {
+    return;
+  }
+  const lines = broken.map(
+    ({ from, href, reason }) => `"${from}" links to "${href}", which ${reason}`,
+  );
+  if (rules.links === "error") {
+    const plural = broken.length === 1 ? "" : "s";
+    const list = lines.map((line) => `  - ${line}`).join("\n");
+    throw new Error(`Content links: "${name}" has ${broken.length} broken link${plural}:\n${list}`);
+  }
+  /* A cause that is not in the links themselves (a template naming a field nobody has leaves every
+     entry unrouted) turns into a line per link, which buries the cause. Past a screenful the rest is
+     counted, and `links: "error"` still lists every one. */
+  for (const line of lines.slice(0, LINK_WARNINGS_LISTED)) {
+    console.warn(`Content links: "${name}": ${line}; it renders as plain text.`);
+  }
+  if (lines.length > LINK_WARNINGS_LISTED) {
+    console.warn(
+      `Content links: "${name}": and ${lines.length - LINK_WARNINGS_LISTED} more broken links ` +
+        `(set "links": "error" to fail the build with every one listed).`,
+    );
+  }
+}
+
+/** How many broken links a `links: "warn"` build names before it counts the rest. */
+const LINK_WARNINGS_LISTED = 25;
+
+// ─── Content Type Loading ────────────────────────────────────────────────────
+
+/** Per-load context a caller threads into {@link loadContentType}. */
+interface LoadOptions {
+  /** The type's asset mount; content-relative references remap onto it. */
+  mount?: AssetMount | undefined;
+  /** The project config: `build.trailingSlash` and the i18n routing rules. */
+  projectConfig?: ProjectConfig | undefined;
+  /** The locale this load is for, when the source carried `{locale}`. */
+  locale?: string | undefined;
+}
+
 /**
  * Load a single content type by its definition, dispatching through the format registry.
  *
@@ -488,7 +1100,7 @@ export function getContentTypeElements(
  * @param {ContentTypeDef} contentTypeDef - Content type definition from the `content` section
  * @param {string} projectRoot - Absolute path to project root directory
  * @param {FormatRegistry} registry - Format-dispatch view of the extension registry
- * @param {AssetMount} [mount] - The type's asset mount; content-relative references remap onto it
+ * @param {LoadOptions} [options] - Asset mount, project config and locale for this load
  * @returns {Promise<ContentLoaderEntry[]>} Array of ContentEntry
  */
 async function loadContentType(
@@ -496,13 +1108,27 @@ async function loadContentType(
   contentTypeDef: ContentTypeDef,
   projectRoot: string,
   registry: FormatRegistry,
-  mount?: AssetMount,
+  options: LoadOptions = {},
 ) {
   const { source } = contentTypeDef;
   if (!source) {
     return [];
   }
+  const { mount, projectConfig, locale } = options;
   const schema = contentTypeDef.schema as ContentTypeSchema | undefined;
+  const rules = compileTypeRules(name, contentTypeDef);
+  const finishContext = (extra: Partial<FinishContext>): FinishContext => ({
+    coerceDates: false,
+    entryExtensions: new Set<string>(),
+    locale,
+    mount,
+    name,
+    projectConfig,
+    rules,
+    schema,
+    sourceRoot: undefined,
+    ...extra,
+  });
 
   // Derive directive allowedNames from content type $elements (tag names from npm packages)
   const directiveOptions = contentTypeDef.$elements?.length
@@ -542,39 +1168,46 @@ async function loadContentType(
           `(its format block lacks "remote": true).`,
       );
     }
+    let remote: ContentLoaderEntry[];
     try {
-      const entries = (await entry.call("load", source, {
+      remote = (await entry.call("load", source, {
         directiveOptions,
         schema,
+        ...(rules.idField !== undefined && { idField: rules.idField }),
       })) as ContentLoaderEntry[];
-      if (schema) {
-        validateEntries(entries, schema, name);
-      }
-      return entries;
     } catch (error) {
       console.warn(`Content type "${name}": ${errorMessage(error)}`);
       return [];
     }
+    return finishEntries([{ entries: remote, filePath: source, rel: null }], finishContext({}));
   }
 
   const resolvedSource = resolve(projectRoot, source).split("\\").join("/");
   const ext = extname(source).toLowerCase();
+  // Directory sources pass their resolved root so formats can derive path-based ids for nested files
+  const sourceRoot = extname(source) ? undefined : resolvedSource;
+  /** Whether a discovered file is left out by `exclude` (a format class may not honor the option). */
+  const isExcluded = (file: string) => {
+    const rel = sourceRoot === undefined ? null : relativeTo(sourceRoot, file);
+    return rel !== null && rules.exclude.excludedBy(rel) !== undefined;
+  };
+  const relOf = (file: string) => (sourceRoot === undefined ? null : relativeTo(sourceRoot, file));
 
   // JSON — the native built-in
   if (formatName === "json" || (!entry && ext === ".json")) {
-    const files = discoverJSONFiles(resolvedSource);
-    const entries: ContentLoaderEntry[] = [];
-    for (const filePath of files) {
-      const fileEntries = loadJSONEntries(filePath);
-      if (mount) {
-        rewriteEntryAssets(fileEntries, filePath, mount, name, schema);
+    const loaded: LoadedFile[] = [];
+    for (const filePath of discoverJSONFiles(resolvedSource, rules.exclude)) {
+      const rel = relOf(filePath);
+      try {
+        loaded.push({ entries: loadJSONEntries(filePath), filePath, rel });
+      } catch (error) {
+        throw unreadableFile(name, rel ?? filePath, error);
       }
-      entries.push(...fileEntries);
     }
-    if (schema) {
-      validateEntries(entries, schema, name);
-    }
-    return entries;
+    return finishEntries(
+      loaded,
+      finishContext({ entryExtensions: new Set([".json"]), sourceRoot }),
+    );
   }
 
   // Derive the format from the source extension when no explicit format is named
@@ -589,25 +1222,43 @@ async function loadContentType(
   }
 
   // Discover entry files via the class, then load each
-  const files = entry.capabilities.discover
+  const discovered = entry.capabilities.discover
     ? ((await entry.call("discover", source, {
         baseDir: projectRoot,
+        ...(rules.exclude.empty ? {} : { exclude: contentTypeDef.exclude }),
       })) as string[])
     : [resolvedSource];
+  const files = discovered.filter((file) => !isExcluded(file));
 
-  // Directory sources pass their resolved root so formats can derive path-based ids for nested files
-  const sourceRoot = extname(source) ? undefined : resolvedSource;
-  const entries: ContentLoaderEntry[] = [];
+  const fileExtensions = files.map((file) => extname(file).toLowerCase());
+  const loaded: LoadedFile[] = [];
   for (const filePath of files) {
-    const fileEntries = (await entry.call("load", filePath, {
-      directiveOptions,
-      schema,
-      ...(sourceRoot !== undefined && { sourceRoot }),
-    })) as ContentLoaderEntry[];
-    if (mount) {
-      rewriteEntryAssets(fileEntries, filePath, mount, name, schema);
+    const rel = relOf(filePath);
+    let fileEntries: ContentLoaderEntry[];
+    try {
+      fileEntries = (await entry.call("load", filePath, {
+        directiveOptions,
+        schema,
+        ...(sourceRoot !== undefined && { sourceRoot }),
+        ...(rules.alerts !== undefined && { alerts: rules.alerts }),
+        ...(rules.idField !== undefined && { idField: rules.idField }),
+        onUnknownAlert: (type: string) =>
+          console.warn(
+            `Content callouts: "${name}": "${rel ?? filePath}" has a [!${type}] callout, but ` +
+              `"${type.toLowerCase()}" is not an enabled type, so it stays a blockquote with the ` +
+              `marker showing. Add "alerts": { "${type.toUpperCase()}": true } to render it.`,
+          ),
+      })) as ContentLoaderEntry[];
+    } catch (error) {
+      throw unreadableFile(name, rel ?? filePath, error);
     }
-    entries.push(...fileEntries);
+    loaded.push({ entries: fileEntries, filePath, rel });
+  }
+  if (loaded.length === 0 && !rules.exclude.empty) {
+    console.warn(
+      `Content type "${name}": no file was loaded from "${source}" with "exclude" set; if the ` +
+        `folder is not empty, an exclude pattern is hiding all of it.`,
+    );
   }
 
   /*
@@ -615,14 +1266,26 @@ async function loadContentType(
    * both the entries and the schema: `Csv.load` receives a schema and `Markdown.load` does not, so
    * doing it per-format would mean doing it twice and missing every third-party format class.
    */
-  if (schema) {
-    for (const warning of coerceEntryDates(entries, schema, name)) {
-      console.warn(warning.message);
-    }
-    validateEntries(entries, schema, name);
-  }
+  return finishEntries(
+    loaded,
+    finishContext({
+      coerceDates: true,
+      entryExtensions: new Set([...entry.extensions, ...fileExtensions]),
+      sourceRoot,
+    }),
+  );
+}
 
-  return entries;
+/**
+ * The error for one file that would not load, with its path: a parse failure names a line and a
+ * reason but never the file, and a vault is hundreds of them.
+ */
+function unreadableFile(type: string, path: string, error: unknown): Error {
+  return new Error(
+    `Content type "${type}": cannot read "${path}": ${errorMessage(error)}. Fix the file, or add it ` +
+      `to "exclude" if it is not a document (a templates folder, for example).`,
+    { cause: error },
+  );
 }
 
 /** Error message for an unregistered non-JSON extension, naming the fix. */
@@ -782,6 +1445,102 @@ export function resolveContentTypeRefs(
   }
 }
 
+/** The page patterns of a project with their locale prefix taken off (`/fr/kb/*` → `/kb/*`). */
+function withoutLocalePrefix(urlPattern: string, prefix: string): string {
+  return prefix !== "" && (urlPattern === prefix || urlPattern.startsWith(`${prefix}/`))
+    ? urlPattern.slice(prefix.length) || "/"
+    : urlPattern;
+}
+
+/** Content types whose unserved routes were already reported, per loaded section (once per build). */
+const REPORTED_UNSERVED = new WeakMap<object, Set<string>>();
+
+/**
+ * Report the routed entries that no dynamic page of the project produces.
+ *
+ * Each page expands the routes its own pattern fits, so a project with a `[category]/[slug]` page
+ * and a `[category]` page serves different entries from each, and one page skipping an entry is
+ * normal. An entry NO page serves is different: it has a route, links to it were rewritten to that
+ * route, and nothing generates it. It is reported once per content type, with a few of the routes.
+ */
+function reportUnservedRoutes(
+  contentType: string,
+  entries: ContentLoaderEntry[],
+  ctx: ResolvePathsContext,
+  prefix: string,
+): void {
+  if (ctx.patterns === undefined) {
+    return;
+  }
+  const reported = REPORTED_UNSERVED.get(ctx.data) ?? new Set<string>();
+  if (reported.has(contentType)) {
+    return;
+  }
+  const patterns = ctx.patterns.map((pattern) => withoutLocalePrefix(pattern, prefix));
+  const unserved = entries
+    .map((entry) => entry._meta?.route)
+    .filter(
+      (route): route is string =>
+        route !== undefined &&
+        !patterns.some((pattern) => routeParams(route, pattern, []) !== null),
+    );
+  if (unserved.length === 0) {
+    return;
+  }
+  reported.add(contentType);
+  REPORTED_UNSERVED.set(ctx.data, reported);
+  const shown = unserved.slice(0, 3).join(", ");
+  console.warn(
+    `Warning: $paths for content type "${contentType}": ${unserved.length} routed ` +
+      `${unserved.length === 1 ? "entry has" : "entries have"} a route that no dynamic page ` +
+      `produces (${shown}${unserved.length > 3 ? ", ..." : ""}), so ` +
+      `${unserved.length === 1 ? "it is" : "they are"} not generated and links to ` +
+      `${unserved.length === 1 ? "it" : "them"} lead nowhere. Add a page whose URL pattern fits ` +
+      `them, or change the "route" template.`,
+  );
+}
+
+/**
+ * `$paths` for a content type with a `route`: one parameter map per entry the page can serve.
+ *
+ * The page pattern arrives with the locale prefix still on it (`/fr/kb/*`) while an entry's route
+ * is locale-free, so the prefix is taken off first. An entry the pattern cannot produce is skipped,
+ * and a page that serves none of them is reported once with an example route, because the usual
+ * cause is a template and a page that were never meant for each other. Entries that NO page of the
+ * project serves are reported too (see {@link reportUnservedRoutes}).
+ */
+function routedPaths(
+  contentType: string,
+  entries: ContentLoaderEntry[],
+  ctx: ResolvePathsContext,
+  urlPattern: string,
+): Record<string, unknown>[] {
+  const { i18n } = resolveI18n(ctx.projectConfig ?? {});
+  const prefix = localeUrlPrefix(ctx.locale, i18n);
+  const pattern = withoutLocalePrefix(urlPattern, prefix);
+  const paths: Record<string, unknown>[] = [];
+  let example: string | undefined;
+  for (const entry of entries) {
+    const route = entry._meta?.route;
+    if (route === undefined) {
+      continue;
+    }
+    example ??= route;
+    const params = routeParams(route, pattern, ctx.params ?? []);
+    if (params) {
+      paths.push({ ...params, ...(entry._meta === undefined ? {} : { _meta: entry._meta }) });
+    }
+  }
+  if (paths.length === 0 && example !== undefined) {
+    console.warn(
+      `Warning: $paths for content type "${contentType}": no entry route fits the page pattern ` +
+        `"${urlPattern}" (for example ${example}), so this page generates nothing`,
+    );
+  }
+  reportUnservedRoutes(contentType, entries, ctx, prefix);
+  return paths;
+}
+
 // ─── The Content project-section class ───────────────────────────────────────
 
 /**
@@ -831,8 +1590,18 @@ export class Content {
   }
 
   /**
-   * Expand a content-type `$paths` source into route-param maps: one `{ [param]: value }` per
-   * entry, with `param` defaulting to "slug" and `field` to "id" (the entry id).
+   * Expand a content-type `$paths` source into route-param maps.
+   *
+   * **With `param` or `field`** (or on a type with no `route`): one `{ [param]: value }` per entry,
+   * `param` defaulting to "slug" and `field` to "id" (the entry id). Unchanged since before routes
+   * existed, and still the right shape for a flat `[slug]` collection.
+   *
+   * **With neither, on a type that declares a `route`:** the page's own URL pattern decides. Each
+   * entry's route is matched against the pattern the host passes (`/kb/:category/:slug`, `/kb/*`)
+   * and the parameters that pattern needs are derived from it, so the same `$paths: {
+   * "contentType": "kb" }` serves `[category]/[slug].json`, `[...path].json` or a `[category].json`
+   * section page, and the page generated for an entry is always at the URL its links point to. An
+   * entry whose route the pattern cannot produce belongs to another page and is skipped here.
    *
    * Each map also carries the entry's own `_meta`, under that reserved name. `_meta` is not a route
    * parameter and the host strips it before substitution — it is how a fact about the _entry_
@@ -841,7 +1610,7 @@ export class Content {
    * timestamp in `<lastmod>`, so the whole archive looks edited whenever the template is.
    *
    * @param {ContentPathsSource} pathsDef - The `$paths` value ({ contentType, param?, field? })
-   * @param {ResolvePathsContext} ctx - Host context ({ data, projectConfig, root })
+   * @param {ResolvePathsContext} ctx - Host context ({ data, projectConfig, root, urlPattern })
    * @returns {Promise<Record<string, unknown>[]>} Array of route-param objects
    */
   static async resolvePaths(
@@ -869,12 +1638,31 @@ export class Content {
       localized && typeof wanted === "string"
         ? entries.filter((entry) => entry._meta?.locale === wanted)
         : entries;
+    if (
+      pathsDef.param === undefined &&
+      pathsDef.field === undefined &&
+      ctx.urlPattern !== undefined &&
+      scoped.some((entry) => entry._meta?.route !== undefined)
+    ) {
+      return routedPaths(pathsDef.contentType, scoped, ctx, ctx.urlPattern);
+    }
     const paths: Record<string, unknown>[] = [];
     for (const entry of scoped) {
       const value = field === "id" ? entry.id : (entry.data[field] ?? entry.id);
       if (!value) {
         continue;
       }
+      /* The value becomes a directory under the output. It may be frontmatter (`field`, or an id
+         taken from `idField`), so a value that would climb out of the output directory does not
+         get a page. */
+      const unsafe = traversalReason(String(value));
+      if (unsafe !== null) {
+        console.warn(
+          `Warning: $paths for content type "${pathsDef.contentType}": the ${field === "id" ? "id" : `"${field}"`} ` +
+            `of "${entry.id}" ${unsafe}, so no page is generated for it`,
+        );
+        continue;
+      }
       const pathEntry: Record<string, unknown> = { [param]: value };
       if (entry._meta !== undefined) {
         pathEntry._meta = entry._meta;