scavold 0.2.0-rc.5 → 0.2.0-rc.7

package/CHANGELOG.md

@@ -9,6 +9,85 @@ changes may occur in any release.
 
 ## [Unreleased]
 
+## [0.2.0-rc.7] — 2026-09-29
+
+### Fixed
+
+- A link to a media file whose extension VitePress does not know, such as `.diff`,
+  pointed at the file name with `.html` appended and therefore at nothing. It now names
+  the file as published.
+
+## [0.2.0-rc.6] — 2026-09-13
+
+### Added
+
+- `aliases` in a page's front matter names the former addresses it replaces, and
+  `retired_urls` in `.cratly.config.yaml` those that are not coming back. A site taking
+  over from an existing website declares them once and the build writes
+  `cratly-redirects.json` into its output: an address, where it went, and `301` or `410`.
+  The format names no server — only a server-side redirect passes a ranking on, and which
+  server that is cratly does not assume, so the deploy step translates the file for its
+  target. Keeping an address is still better than redirecting to it, which is what `url`
+  is for; the build refuses an alias that two pages claim, or that the site serves itself
+  and the redirect would therefore hide.
+- Every build now ends by reading its own result. A page that the generator listed but
+  never wrote, or a script a built page names and the output does not contain, ends the
+  build with the file named — the two states a bundling fault leaves behind while the log
+  says "build complete". Links and images pointing at absent files are reported and left
+  to the site, since one may legitimately name a path the web server provides. Turn it
+  down with `verify: { content: false }` or off with `verify: false`. A reference is read
+  the way a browser reads it: a relative one against the address of the page holding it, so
+  a link that forgot its protocol — `[Website](./www.example.com)`, which the build turns
+  into a sibling page nobody wrote — is seen as well. Proven against the
+  case-collision that used to build green: the page missing from the output is the only
+  trace it leaves on a file system that ignores letter case, and that is now enough.
+  Everything found also goes to `.cratly/build-report.json`, written before the build is
+  ended rather than after, each entry naming the source file an author would open. A build
+  log is read by whoever has access to it; a file can be handed to whoever wrote the page.
+- `ignoreDeadLinks` now defaults to `true`. VitePress ends a build on a dead link and does
+  so before writing anything, which leaves the reason in a job log that whoever wrote the
+  link often cannot read, and lets one typo stand between a finished page and its
+  publication. Scavold finds the same mistake in the finished output and reports it there
+  instead. Whether it should also stop a pipeline is a question whose answer differs per
+  branch, so it is left to CI: the site template fails a merge request over it and lets the
+  default branch deploy, since blocking there would answer a broken link with a stale site.
+  Ask for VitePress' abort back with `ignoreDeadLinks: false`.
+- A site whose page paths collide in VitePress's eyes now learns that from Scavold, by
+  name, before the build starts. VitePress identifies a page by its path flattened into
+  a single name — slash becomes underscore, and the page-hash map lower-cases it — and
+  uses that name for the page's bundle entry, its server module and its client chunk.
+  Two pages meeting there overwrite each other: either the build dies at render time in
+  `pageChunk.imports`, naming no file, or it succeeds and ships two pages pointing at a
+  script that was never written. Scavold now reproduces that identity when it reads the
+  config and aborts with both file names, whether they collide through an underscore in
+  a file name (`de_kontakt.md` beside `de/kontakt.md`), through letter case alone, or
+  through a `url` alias landing on a path another page already owns as its file — the
+  case the previous alias check, which compared aliases only with each other, let pass.
+- `date` and `datetime` join the type vocabulary of `frontmatter_fields` and of a
+  container's `props`. Scavold passes such a value through as the ISO 8601 text it is;
+  what changes is that the cratly editor now offers a date picker for it instead of a
+  plain text box. A `datetime` always carries an offset — a time of day without one is
+  a different moment on every machine that builds the site.
+
+### Changed
+
+- `@cepharum/vue3-i18n` moves to `2.0.0`, two majors on from the `0.5.4` a site would
+  have installed. Scavold uses `useL10n`, `setLocale` and `setLoader`, none of which
+  changed; what 2.0 breaks are the locale helpers now returning full BCP-47 tags, and
+  Scavold calls none of them. A site inherits the new version with its next install, and
+  gains what 2.0 adds along the way: regional locales overlaying a bare language, plural
+  and gender selection resolved through `Intl`, and `Intl`-backed formatters in
+  placeholders.
+
+### Fixed
+
+- `lib/href.js` ships the declarations it had been missing since it was split out, so
+  `typecheck` passes again — and the pipeline runs it now, which is why it could go
+  unnoticed at all. Nothing about the module changed; TypeScript simply had nothing to
+  read about it, and treated every href the hierarchy composes as `any`.
+
+## [0.2.0-rc.5] — 2026-08-17
+
 ### Added
 
 - `:::pagelist` dates its entries the way the site wants them: `time-style` adds the
@@ -179,7 +258,11 @@ First published release. Version `0.1.0` existed in-tree only.
 - Only images are processed out of `media_folder`; other file types (video, documents)
   are never copied into the build output and have to live in the static folder.
 
-[0.2.0-rc.4]: https://gitlab.com/cepharum-foss/cratly/scavold/-/compare/v0.2.0-rc.3...v0.2.0-rc.4
-[0.2.0-rc.3]: https://gitlab.com/cepharum-foss/cratly/scavold/-/compare/v0.2.0-rc.2...v0.2.0-rc.3
-[0.2.0-rc.2]: https://gitlab.com/cepharum-foss/cratly/scavold/-/compare/v0.2.0-rc.1...v0.2.0-rc.2
-[0.2.0-rc.1]: https://gitlab.com/cepharum-foss/cratly/scavold/-/tags/v0.2.0-rc.1
+[Unreleased]: https://gitlab.com/cratly/scavold/-/compare/v0.2.0-rc.7...main
+[0.2.0-rc.7]: https://gitlab.com/cratly/scavold/-/compare/v0.2.0-rc.6...v0.2.0-rc.7
+[0.2.0-rc.6]: https://gitlab.com/cratly/scavold/-/compare/v0.2.0-rc.5...v0.2.0-rc.6
+[0.2.0-rc.5]: https://gitlab.com/cratly/scavold/-/compare/v0.2.0-rc.4...v0.2.0-rc.5
+[0.2.0-rc.4]: https://gitlab.com/cratly/scavold/-/compare/v0.2.0-rc.3...v0.2.0-rc.4
+[0.2.0-rc.3]: https://gitlab.com/cratly/scavold/-/compare/v0.2.0-rc.2...v0.2.0-rc.3
+[0.2.0-rc.2]: https://gitlab.com/cratly/scavold/-/compare/v0.2.0-rc.1...v0.2.0-rc.2
+[0.2.0-rc.1]: https://gitlab.com/cratly/scavold/-/tags/v0.2.0-rc.1

package/FRONTMATTER.md

@@ -107,6 +107,20 @@ Menu links and breadcrumbs produced by Scavold automatically use the alias URL.
 with an error naming both conflicting files. Each alias must be unique across the
 entire site.
 
+The same applies when an alias lands on a path another page already owns as its own
+file — a `url: de/kontakt` next to a `pages/de/kontakt.md`. VitePress identifies a
+page by its path flattened into one name, slash becoming underscore, and it uses that
+name for the page's bundle entry, its server module and its client chunk. Two pages
+meeting there overwrite each other's output; the alias does not win, it collides. So
+does a page whose file name spells out a path another page reaches through folders
+(`de_kontakt.md` beside `de/kontakt.md`), and a pair differing only in letter case.
+Scavold checks all of these when it reads the config and names both files. Prefer `-`
+over `_` as the word separator in page names and the class cannot arise.
+
+To move a page and keep its URL, rename the file and declare the old URL as its
+alias — the alias belongs to the page that carries the content, not to a second file
+left behind at the old location.
+
 ---
 
 ## `locale` / `lang`
@@ -260,6 +274,44 @@ in the hierarchy tree — they are only excluded from rendered navigation.
 
 ---
 
+## `aliases`
+
+**Type:** `string | string[]`
+
+Former addresses this page replaces. Declared when a cratly site takes over from an
+existing website: every address a search engine already knows and the new site does not
+answer is a result its owner loses.
+
+```yaml
+---
+aliases:
+  - /kontakt.html
+  - kontakt.php
+---
+```
+
+Values are written as they stood in the browser, with or without a leading slash. A
+fragment is dropped — it never reaches a server. A query string is kept; whether it can
+be matched is up to whoever serves the site.
+
+Scavold collects them and writes `cratly-redirects.json` into the build output: an
+address, where it went, and a status — `301` for an inherited address, `410` for one a
+site declares as gone for good in
+[`retired_urls`](./docs/reference/config.md#retired-urls). Turning that into server
+configuration is the deploy step's job, because cratly does not assume who serves the
+site. Nothing about the file is Scavold-specific: another adapter writes the same format.
+
+**Keeping the address beats redirecting to it.** A permanent redirect passes a ranking on;
+a page that simply answers at the old address never spends it. Where the legacy path can
+be a file, [`url`](#url) is the better tool, and it works on every static server, whether
+or not it can redirect at all.
+
+**Conflict detection:** the build stops when two pages claim the same former address, and
+when a former address is one the new site serves itself — the redirect would win over the
+page, leaving it unreachable while every menu still links to it.
+
+---
+
 ## `redirect`
 
 **Type:** `string | object`

package/lib/config.js

@@ -1,7 +1,9 @@
 import { dirname as dirnameOfPath, join, relative, resolve } from "node:path";
 import { dirname, join as joinPosix } from "node:path/posix";
 import { readdirSync, readFileSync } from "node:fs";
-import { clearCache, compileHierarchy, compileRedirects, resolveHierarchyImages, sourceFolder } from "./pages.js";
+import {
+	clearCache, collectFrontmatterOfAllPages, compileHierarchy, compileRedirects, resolveHierarchyImages, sourceFolder,
+} from "./pages.js";
 import { extractFrontmatterMediaSrcs } from "./excerpt.js";
 import { DEFAULT_FEED_LIMIT, collectFeedPages, renderRss } from "./feed.js";
 import { useMedia } from "./media.js";
@@ -9,6 +11,13 @@ import { patchRenderer } from "./markdown.js";
 import { extractContainerMediaSrcs, mediaPropsOf, registerContainers, resolveContainerMap } from "./containers.js";
 import { buildSectionManifest, writeSectionManifest } from "./sectionManifest.js";
 import { isExternalUrl, servableRedirectTarget } from "./redirectTarget.js";
+import { assertUniquePageKeys } from "./pageKeys.js";
+import {
+	BUILD_REPORT_DIR, BUILD_REPORT_FILE, formatProblems, renderBuildReport, verifyBuild,
+} from "./verifyBuild.js";
+import {
+	REDIRECT_MANIFEST_FILE, assertLegacyRedirects, compileLegacyRedirects, renderRedirectManifest,
+} from "./legacyUrls.js";
 import { pageHref, servableUrl } from "./href.js";
 
 // Scavold's own version, reported under `adapter.version` in the emitted
@@ -180,6 +189,7 @@ export async function augmentConfig( rawConfig, options = {} ) {
 	let declaredImageSizes = null;
 	let declaredImageWidths = null;
 	let declaredExcerptLength = null;
+	let declaredRetiredUrls = [];
 
 	try {
 		const { readFile } = await import( "node:fs/promises" );
@@ -193,6 +203,7 @@ export async function augmentConfig( rawConfig, options = {} ) {
 		declaredImageSizes = cratlyConfig.image_sizes ?? null;
 		declaredImageWidths = cratlyConfig.image_widths ?? null;
 		declaredExcerptLength = cratlyConfig.excerpt_length ?? null;
+		declaredRetiredUrls = cratlyConfig.retired_urls ?? [];
 	} catch {
 		// file absent or unparseable — proceed with defaults
 	}
@@ -376,6 +387,99 @@ export async function augmentConfig( rawConfig, options = {} ) {
 		await writeFile( target, xml, "utf-8" );
 	}
 
+	/**
+	 * Writes what the check found next to the section manifest, for readers that are
+	 * not a terminal — the cratly editor shows it to whoever wrote the page.
+	 *
+	 * A report that cannot be written must not replace the finding it describes, so
+	 * failure here is a warning and the build carries on to its own verdict.
+	 *
+	 * @param {{pages: object[], assets: object[], content: object[]}} problems what verifyBuild found
+	 * @param {Object<string,string>} sources built page path → source file an author edits
+	 * @returns {Promise<void>}
+	 */
+	async function writeBuildReport( problems, sources ) {
+		try {
+			const { writeFile, mkdir } = await import( "node:fs/promises" );
+			const dir = join( process.cwd(), BUILD_REPORT_DIR );
+
+			await mkdir( dir, { recursive: true } );
+			await writeFile(
+				join( dir, BUILD_REPORT_FILE ),
+				renderBuildReport( problems, {
+					adapter: { name: "scavold", version: SCAVOLD_VERSION },
+					sources,
+				} ),
+				"utf-8",
+			);
+		} catch ( error ) {
+			console.warn( `[scavold] could not write ${BUILD_REPORT_DIR}/${BUILD_REPORT_FILE} —`, error.message );
+		}
+	}
+
+	/**
+	 * Reads the finished build and refuses one that references files it does not
+	 * contain — the shape a framework bug takes when it does not announce itself.
+	 *
+	 * A site can turn the content half off (`verify: { content: false }`) or the whole
+	 * check (`verify: false`) when it links to paths its web server provides rather
+	 * than its build.
+	 *
+	 * @param {object} siteConfig VitePress site configuration, as handed to buildEnd
+	 * @returns {Promise<void>}
+	 */
+	async function verifyBuiltSite( siteConfig ) {
+		if ( options.verify === false ) {
+			return;
+		}
+
+		const { content = true } = options.verify === true || options.verify == null ? {} : options.verify;
+
+		// What VitePress said it would write, in the spelling it serves it under —
+		// and, the other way round, which file an author would open to fix a page.
+		const sources = {};
+
+		for ( const page of siteConfig.pages ?? [] ) {
+			sources[( siteConfig.rewrites?.map?.[page] || page ).replace( /\.md$/, ".html" )] = page;
+		}
+
+		const problems = verifyBuild( siteConfig.outDir, {
+			base: siteConfig.site?.base ?? "/",
+			content,
+			pages: Object.keys( sources ),
+		} );
+
+		// Written before anything is thrown: the failure this check exists to cause
+		// would otherwise take the reason with it, leaving a red pipeline and a log
+		// only some people may read.
+		await writeBuildReport( problems, sources );
+
+		if ( problems.content.length ) {
+			console.warn(
+				`[scavold] ${problems.content.length} link(s) or image(s) point at files this build does not contain:\n` +
+			`${formatProblems( problems.content )}`
+			);
+		}
+
+		if ( problems.pages.length ) {
+			throw new Error(
+				`[scavold] ${problems.pages.length} page(s) the build listed were never written:\n` +
+			`${formatProblems( problems.pages )}\n` +
+			"Two pages sharing one build identity are the known cause — on a file system that ignores letter " +
+			"case, this is the only trace they leave."
+			);
+		}
+
+		if ( problems.assets.length ) {
+			throw new Error(
+				`[scavold] ${problems.assets.length} script(s) or stylesheet(s) named by a built page are missing from the ` +
+			`output:\n${formatProblems( problems.assets )}\n` +
+			"Pages in that state render but stay dead in the browser. This is a bundling fault, not a content " +
+			"mistake — two pages sharing one build identity are the known cause."
+			);
+		}
+	}
+
 	const pagesDir = sourceFolder( resolvedConfig );
 
 	// Emit the section-type manifest (.cratly/sections.json) so the cratly
@@ -405,9 +509,87 @@ export async function augmentConfig( rawConfig, options = {} ) {
 		},
 	};
 
+	// ─── Page identity guard ─────────────────────────────────────────────────
+	// VitePress identifies a page by its path flattened into a single name, and
+	// two pages colliding there quietly overwrite each other — see pageKeys.js.
+	// Checked here, on every config load, so dev server and build both report the
+	// pair by name instead of dying later on a chunk that was never emitted.
+
+	/**
+	 * Lists the page files VitePress will pick up, relative to srcDir.
+	 *
+	 * `srcExclude` is honoured for plain paths and for prefix patterns ending in
+	 * `/*` or `/**` — the shapes a site actually writes. A more exotic pattern
+	 * just leaves its file in the list, which at worst reports a collision the
+	 * site had excluded anyway.
+	 *
+	 * @returns {Promise<string[]>} page paths, posix-style, relative to srcDir
+	 */
+	async function listPageFiles() {
+		const { glob } = await import( "node:fs/promises" );
+		const excluded = ( resolvedConfig.srcExclude ?? [] ).map( pattern => pattern.replace( /\/\*{1,2}$/, "/" ) );
+
+		return ( await Array.fromAsync( glob( "**/*.md", {
+			cwd: sourceFolder( resolvedConfig ),
+			exclude: name => name === "node_modules" || name === "dist",
+		} ) ) )
+			.map( name => name.replace( /\\/g, "/" ) )
+			// Dynamic routes stand for pages named by their paths file, not by
+			// their own name — their identity is not this file's path.
+			.filter( name => !name.includes( "[" ) )
+			.filter( name => !excluded.some( pattern => ( pattern.endsWith( "/" ) ? name.startsWith( pattern ) : name === pattern ) ) );
+	}
+
+	const rewrites = {
+		...rawConfig?.rewrites,
+		...await compileRedirects( resolvedConfig ),
+	};
+
+	assertUniquePageKeys( await listPageFiles(), rewrites );
+
+	// ─── Former addresses ────────────────────────────────────────────────────
+	// Compiled here so a declaration a server could not honour is refused while the
+	// author is still looking at it, and written out at the end of the build for
+	// whoever configures the server. What Scavold produces is data, not server
+	// configuration: cratly does not assume who serves the site.
+	const legacyRedirects = compileLegacyRedirects(
+		await collectFrontmatterOfAllPages( resolvedConfig ),
+		{ rewrites, retired: declaredRetiredUrls },
+	);
+
+	assertLegacyRedirects( legacyRedirects.problems );
+
+	/**
+	 * Writes the redirect manifest, unless the site declares no former addresses.
+	 *
+	 * @param {object} siteConfig VitePress site configuration, as handed to buildEnd
+	 * @returns {Promise<void>}
+	 */
+	async function writeRedirectManifest( siteConfig ) {
+		if ( !legacyRedirects.rules.length ) {
+			return;
+		}
+
+		const { writeFile } = await import( "node:fs/promises" );
+
+		await writeFile(
+			join( siteConfig.outDir, REDIRECT_MANIFEST_FILE ),
+			renderRedirectManifest( legacyRedirects.rules, { name: "scavold", version: SCAVOLD_VERSION } ),
+			"utf-8",
+		);
+	}
+
 	return {
 		...resolvedConfig,
 
+		// VitePress ends a build on a dead link, and ends it before writing anything —
+		// so the reason lives in a job log, which whoever wrote the link often cannot
+		// read, and a single typo stands between a finished page and its publication.
+		// Scavold finds the same mistake in the finished output (see verifyBuiltSite)
+		// and reports it there, where it can be handed to the author. A site that
+		// wants the abort back asks for it: ignoreDeadLinks: false.
+		ignoreDeadLinks: rawConfig.ignoreDeadLinks ?? true,
+
 		// Without this, VitePress writes its page-to-hash map into an inline script whose
 		// content changes with every build. Under a content security policy that names
 		// script hashes, that one hash has to be updated on the server for every deploy —
@@ -440,13 +622,14 @@ export async function augmentConfig( rawConfig, options = {} ) {
 				createExternalRedirectMapPlugin( pagesDir ),
 			],
 		},
-		rewrites: {
-			...rawConfig?.rewrites,
-			...await compileRedirects( resolvedConfig ),
-		},
+		rewrites,
 		async buildEnd( siteConfig ) {
 			await writeFeed( siteConfig );
+			await writeRedirectManifest( siteConfig );
 			await rawConfig.buildEnd?.( siteConfig );
+
+			// Last, so it sees what every other hand has written.
+			await verifyBuiltSite( siteConfig );
 		},
 		async transformPageData( pageData, context ) {
 			clearCache();
@@ -470,7 +653,7 @@ export async function augmentConfig( rawConfig, options = {} ) {
 			//   during in-app use.
 			//
 			// The redirect value can be either:
-			//   - a site-relative URL  ("/de/jobs")  — written by the Cratly editor
+			//   - a site-relative URL  ("/de/jobs")  — written by the cratly editor
 			//   - a relative .md path  ("jobs.md")   — written by hand in frontmatter
 			//   - an absolute external URL            — e.g. "https://example.com"
 			const redirect = pageData.frontmatter?.redirect;
@@ -531,14 +714,31 @@ export async function augmentConfig( rawConfig, options = {} ) {
 				// offers, which is relative to that folder. Rewrite it to the URL the
 				// built site serves. Targets that are not media files (ordinary page
 				// links, anchors, remote URLs) resolve to null and stay untouched.
-				patchRenderer( md, "link_open", ( defaultHandler, tokens, idx, ...args ) => {
-					const published = media.collectAsset( tokens[idx].attrGet( "href" ) );
+				//
+				// VitePress then takes any extension missing from its own list of file
+				// types (`.diff`, say) for part of a page name and appends `.html`. The
+				// published URL is final, so that suffix is taken back — after VitePress
+				// ran, which leaves prefixing the site's base to it.
+				patchRenderer( md, "link_open", ( defaultHandler, tokens, idx, mdOptions, env, slf ) => {
+					const token = tokens[idx];
+					const published = media.collectAsset( token.attrGet( "href" ) );
+
+					if ( !published ) {
+						return defaultHandler( tokens, idx, mdOptions, env, slf );
+					}
+
+					token.attrSet( "href", published );
+
+					const rendered = defaultHandler( tokens, idx, mdOptions, env, slf );
+					const href = token.attrGet( "href" );
+
+					if ( !published.endsWith( ".html" ) && href?.endsWith( published + ".html" ) ) {
+						token.attrSet( "href", href.slice( 0, -".html".length ) );
 
-					if ( published ) {
-						tokens[idx].attrSet( "href", published );
+						return slf.renderToken( tokens, idx, mdOptions );
 					}
 
-					return defaultHandler( tokens, idx, ...args );
+					return rendered;
 				} );
 
 				registerContainers( md, containerMap, {

package/lib/href.d.ts

@@ -0,0 +1,21 @@
+import type { Scavold } from "../index";
+
+/** Extension every page is built into and therefore linked with. */
+export const PAGE_EXTENSION: string;
+
+/**
+ * Converts a page's source path into the root-relative URL the built site serves.
+ */
+export function pageHref( path: string ): string;
+
+/**
+ * Converts a hierarchy node into the URL the built site serves it under, preferring
+ * the alias URL when the page declares one.
+ */
+export function nodePath( node: Scavold.HierarchyNode | undefined ): string;
+
+/**
+ * Rewrites a site-relative URL to the file that answers it: a folder URL to the index
+ * page inside it, an extension-less path to its page.
+ */
+export function servableUrl( url: string ): string;

package/lib/legacyUrls.js

@@ -0,0 +1,179 @@
+// ─── Legacy URLs ─────────────────────────────────────────────────────────────
+// A site that replaces an existing one inherits its addresses. Every one of them
+// that a search engine knows and the new site does not answer is a result the
+// customer loses, and no build notices — the old URL simply is not there any more.
+//
+// Only the web server can answer an address that is not a file, and only a
+// permanent redirect passes the ranking on; a redirect run by the browser is
+// followed but counts for less. So the pages declare which old addresses they
+// replace, and the build writes them out as data. What turns that data into
+// server configuration is the deploy step of whoever serves the site — cratly
+// does not assume any particular server, so this file knows about none.
+//
+// Where an old address can simply be kept, `url` in front matter is the better
+// answer: a page served at the legacy path needs no redirect at all, and works on
+// every static server there is.
+
+import { pageKey } from "./pageKeys.js";
+
+// Version of the cratly redirect-manifest grammar this writes, and its canonical
+// URL — cratly owns the format, Scavold is one adapter producing it.
+export const REDIRECT_MANIFEST_VERSION = 0;
+export const REDIRECT_MANIFEST_SCHEMA = "https://cratly.io/schema/redirects/v0.json";
+
+// Name of the file the build writes into its output folder.
+export const REDIRECT_MANIFEST_FILE = "cratly-redirects.json";
+
+/**
+ * Turns a page's source path into the URL its build is served under.
+ *
+ * @param {string} page path of the page's markdown file, relative to srcDir
+ * @param {Object<string,string>} [rewrites] VitePress `rewrites` map, source path → served path
+ * @returns {string} site-absolute URL of the built page
+ */
+export function servedPathOf( page, rewrites = {} ) {
+	const served = rewrites?.[page] || page;
+
+	return `/${served.replace( /\.md$/, ".html" )}`;
+}
+
+/**
+ * Reads a declared legacy address into the shape a redirect rule uses.
+ *
+ * Authors write these as they appeared in the browser, so a leading slash may be
+ * missing and a fragment may be attached — a fragment never reaches the server and
+ * is dropped. A query string is kept: whether it can be matched is the consuming
+ * server's business, not this format's.
+ *
+ * @param {string} value legacy address as declared
+ * @returns {string|null} site-absolute address, or null when the value says nothing
+ */
+export function normaliseLegacyPath( value ) {
+	if ( typeof value !== "string" ) {
+		return null;
+	}
+
+	const [withoutFragment] = value.trim().split( "#" );
+
+	if ( !withoutFragment ) {
+		return null;
+	}
+
+	return withoutFragment.startsWith( "/" ) ? withoutFragment : `/${withoutFragment}`;
+}
+
+/**
+ * Compiles the redirect rules a site's own declarations amount to.
+ *
+ * Two mistakes are worth stopping a build over, and both are reported rather than
+ * resolved: an old address that two pages claim, and one that collides with an
+ * address the new site itself serves. The latter is the interesting one — a
+ * redirect would shadow a real page, so the page would be unreachable while every
+ * link to it still points there.
+ *
+ * @param {Object<string,object>} frontmatter map of page path → front matter
+ * @param {object} [options] what the site declares elsewhere
+ * @param {Object<string,string>} [options.rewrites] VitePress `rewrites` map
+ * @param {string[]} [options.retired] addresses declared as gone for good
+ * @returns {{rules: {from: string, to?: string, status: number}[], problems: string[]}}
+ *          rules in address order, and what a site has to fix first
+ */
+export function compileLegacyRedirects( frontmatter, { rewrites = {}, retired = [] } = {} ) {
+	const problems = [];
+	const claimedBy = new Map();    // legacy address → page claiming it
+	const rules = new Map();        // legacy address → rule
+
+	// Addresses the new site answers itself. A redirect must never cover one.
+	const served = new Map();
+
+	for ( const page of Object.keys( frontmatter ) ) {
+		served.set( pageKey( servedPathOf( page, rewrites ).slice( 1 ) ), page );
+	}
+
+	for ( const [ page, meta ] of Object.entries( frontmatter ) ) {
+		const declared = meta?.aliases == null ? [] : [meta.aliases].flat();
+
+		for ( const value of declared ) {
+			const from = normaliseLegacyPath( value );
+
+			if ( !from ) {
+				continue;
+			}
+
+			const owner = claimedBy.get( from );
+
+			if ( owner ) {
+				problems.push( `both "${owner}" and "${page}" declare the former address ${from}` );
+				continue;
+			}
+
+			const shadowed = served.get( pageKey( from.slice( 1 ) ) );
+
+			if ( shadowed ) {
+				problems.push(
+					`"${page}" declares the former address ${from}, which "${shadowed}" is served at — ` +
+					"a redirect there would hide that page"
+				);
+				continue;
+			}
+
+			claimedBy.set( from, page );
+			rules.set( from, { from, to: servedPathOf( page, rewrites ), status: 301 } );
+		}
+	}
+
+	for ( const value of retired ) {
+		const from = normaliseLegacyPath( value );
+
+		if ( !from ) {
+			continue;
+		}
+
+		if ( rules.has( from ) ) {
+			problems.push( `${from} is declared as retired and at the same time as a former address of "${claimedBy.get( from )}"` );
+			continue;
+		}
+
+		rules.set( from, { from, status: 410 } );
+	}
+
+	return {
+		rules: [...rules.values()].sort( ( a, b ) => ( a.from < b.from ? -1 : 1 ) ),
+		problems,
+	};
+}
+
+/**
+ * Refuses a set of declarations a server could not serve as meant.
+ *
+ * @param {string[]} problems what compileLegacyRedirects found
+ * @returns {void}
+ * @throws {Error} naming every problem
+ */
+export function assertLegacyRedirects( problems ) {
+	if ( problems.length ) {
+		throw new Error( `[scavold] former addresses cannot be served as declared: ${problems.join( "; " )}` );
+	}
+}
+
+/**
+ * Renders the redirect manifest, the artifact a deploy step reads.
+ *
+ * Deliberately free of any server's vocabulary: an address, where it went, and the
+ * status that says so. Translating that into a Caddyfile, an nginx map, an
+ * `.s3-http.config.yaml` or a bucket's routing rules is the deploy's job.
+ *
+ * @param {{from: string, to?: string, status: number}[]} rules compiled rules
+ * @param {object} [adapter] what produced the file
+ * @param {string} [adapter.name] name of the adapter
+ * @param {string} [adapter.version] its version
+ * @returns {string} the manifest as JSON text, newline-terminated
+ */
+export function renderRedirectManifest( rules, adapter = {} ) {
+	return `${JSON.stringify( {
+		$schema: REDIRECT_MANIFEST_SCHEMA,
+		specVersion: REDIRECT_MANIFEST_VERSION,
+		adapter,
+		rules,
+	}, null, "\t" )}\n`;
+}

package/lib/pageKeys.js

@@ -0,0 +1,111 @@
+// ─── Page identity guard ─────────────────────────────────────────────────────
+// VitePress does not carry a page's path through its build. It flattens the path
+// into a single name and uses that name as the page's identity in four places:
+//
+//   * the key of the page's entry in `rollupOptions.input` (the rewritten path
+//     wins here — `config.rewrites.map[file] || file`),
+//   * the file name of the page's SSR module in the temp folder,
+//   * the key of the page's entry in `pageToHashMap` — lower-cased,
+//   * the name of the page's client chunk, hence its `.lean.js` file name.
+//
+// Two pages whose paths flatten to the same name therefore share one identity
+// and one set of output files. VitePress neither detects nor reports this:
+// depending on which of the four collides, the build either dies at render time
+// with `undefined is not an object (evaluating 'pageChunk.imports')`, naming no
+// file, or it succeeds and ships two pages pointing at one script file that was
+// never written.
+//
+// The guard below reproduces that identity and demands it stays unique, so the
+// site learns which two files disagree instead of what VitePress makes of them.
+
+// Copied from VitePress (which copies it from Vite) — the characters its
+// `sanitizeFileName()` replaces with an underscore.
+
+const INVALID_CHAR_RE = /[\u0000-\u001F"#$&*+,:;<=>?[\]^`{|}\u007F]/g;
+
+/**
+ * Reproduces the identity VitePress derives from a page path.
+ *
+ * Lower-casing goes beyond what the bundle entry key does — it is what
+ * `pageToHashMap` keys on, and a pair colliding only there is the worse of the
+ * two failures, so the strictest of the four rules is the one to enforce.
+ *
+ * @param {string} page path of a page's markdown file, relative to srcDir
+ * @returns {string} the name VitePress identifies that page by
+ */
+export function pageKey( page ) {
+	return String( page )
+		.replace( /\\/g, "/" )
+		.replace( /\//g, "_" )
+		.replace( INVALID_CHAR_RE, "_" )
+		// VitePress strips underscores that a leading invalid character produced.
+		.replace( /^_+/, "" )
+		.toLowerCase();
+}
+
+/**
+ * Groups pages that VitePress cannot tell apart.
+ *
+ * @param {string[]} pages paths of all page files, relative to srcDir
+ * @param {Object<string,string>} [rewrites] VitePress `rewrites` map, source path → served path
+ * @returns {{key: string, sources: {page: string, alias: string}[]}[]} one entry per colliding identity, in path order
+ */
+export function findPageKeyCollisions( pages, rewrites = {} ) {
+	const byKey = new Map();
+
+	for ( const page of [...pages].sort() ) {
+		const alias = rewrites?.[page] || page;
+		const key = pageKey( alias );
+		const group = byKey.get( key );
+
+		if ( group ) {
+			group.push( { page, alias } );
+		} else {
+			byKey.set( key, [{ page, alias }] );
+		}
+	}
+
+	return [...byKey.entries()]
+		.filter( ( [ , sources ] ) => sources.length > 1 )
+		.map( ( [ key, sources ] ) => ( { key, sources } ) );
+}
+
+/**
+ * Renders one collision as a line naming both files and, where a rewrite or a
+ * `url` alias is what makes them collide, the path each is served at.
+ *
+ * @param {{key: string, sources: {page: string, alias: string}[]}} collision
+ * @returns {string} single-line description
+ */
+function describeCollision( { key, sources } ) {
+	const named = sources
+		.map( ( { page, alias } ) => ( alias === page ? `"${page}"` : `"${page}" (served as "${alias}")` ) )
+		.join( " and " );
+
+	return `${named} share the build identity "${key}"`;
+}
+
+/**
+ * Throws when two pages flatten to the same VitePress identity.
+ *
+ * @param {string[]} pages paths of all page files, relative to srcDir
+ * @param {Object<string,string>} [rewrites] VitePress `rewrites` map, source path → served path
+ * @returns {void}
+ * @throws {Error} naming every colliding pair and how to resolve it
+ */
+export function assertUniquePageKeys( pages, rewrites = {} ) {
+	const collisions = findPageKeyCollisions( pages, rewrites );
+
+	if ( collisions.length === 0 ) {
+		return;
+	}
+
+	throw new Error(
+		`[scavold] colliding page paths: ${collisions.map( describeCollision ).join( "; " )}. ` +
+		"VitePress flattens a page path into a single name — slash becomes underscore — and " +
+		"identifies the page by it, so pages colliding there overwrite each other's bundle " +
+		"entry and output files. Rename one of them; prefer \"-\" over \"_\" as the word " +
+		"separator in page names, and keep an existing URL alive with front matter `url` " +
+		"instead of the old file name."
+	);
+}

package/lib/verifyBuild.js

@@ -0,0 +1,324 @@
+// ─── Build verification ──────────────────────────────────────────────────────
+// A static site can be wrong in ways its generator does not notice. VitePress
+// identifies a page by its path flattened into one name and reuses that name for
+// the page's script files; where two pages meet there, one of them ends up
+// preloading a file that was never written — and the build reports success. The
+// same silence covers a renamed page still linked from elsewhere and an image
+// whose file went away.
+//
+// None of that is visible in the build log, and all of it is visible in the
+// finished output: the pages name the files they need, and either those files are
+// there or they are not. So the last thing Scavold does is read its own result.
+//
+// Three classes, treated differently:
+//
+//   * A page the generator listed but did not write is never intentional either —
+//     and it is the only symptom left when two pages collide on a file system that
+//     ignores letter case, which is what the machine writing the page usually has.
+//   * A missing script or stylesheet is never intentional. It means the framework
+//     produced an inconsistent bundle, and the page is dead in the browser while
+//     the pre-rendered HTML still shows. That fails the build.
+//   * A missing link or image target is a content mistake, and one a site may make
+//     on purpose — a link to a path the web server provides rather than the build.
+//     That is reported and left to the site to decide on.
+//
+// All three go into .cratly/build-report.json as well, written before the build is
+// ended rather than after, so what happened survives the failure. A build log is
+// read by whoever has access to it; a file can be handed to whoever wrote the page.
+
+import { readFileSync, readdirSync } from "node:fs";
+import { join, posix, resolve } from "node:path";
+
+// Where the report goes, and which shape a reader may expect. The version is
+// bumped when a reader would have to be changed — the cratly editor is one.
+export const BUILD_REPORT_DIR = ".cratly";
+export const BUILD_REPORT_FILE = "build-report.json";
+export const BUILD_REPORT_VERSION = 0;
+
+// Attributes that name a file the browser must load for the page to work at all.
+const ASSET_ATTR_RE = /<(?:script|link)\b[^>]*?\b(?:src|href)\s*=\s*["']([^"']+)["'][^>]*>/gi;
+const ASSET_TAG_RE = /^<(?:script\b[^>]*\bsrc|link\b[^>]*\brel\s*=\s*["'](?:modulepreload|preload|stylesheet)["'])/i;
+const LINK_RE = /<a\b[^>]*?\bhref\s*=\s*["']([^"']+)["']/gi;
+const IMG_SRC_RE = /<(?:img|source|video)\b[^>]*?\b(?:src|poster)\s*=\s*["']([^"']+)["']/gi;
+const SRCSET_RE = /<(?:img|source)\b[^>]*?\bsrcset\s*=\s*["']([^"']+)["']/gi;
+
+// A reference naming its own protocol addresses something outside this build:
+// http:, mailto:, tel: and every other scheme.
+const SCHEME_RE = /^[a-z][a-z0-9+.-]*:/i;
+
+/**
+ * Tells references that leave the site from those the build has to satisfy.
+ *
+ * Relative references count. A markdown link that forgot its protocol —
+ * `[Website](./www.example.com)` — leaves the build as a relative href pointing
+ * at a sibling page nobody wrote, and that is the mistake authors actually make.
+ * Where such a reference points is a question only the page holding it can
+ * answer, which is why resolving is left to {@link resolveReference}.
+ *
+ * @param {string} reference value of an href, src or srcset entry
+ * @returns {boolean} true when the reference names something this build produced
+ */
+function isLocalReference( reference ) {
+	return reference !== ""
+		&& !reference.startsWith( "//" )
+		&& !SCHEME_RE.test( reference )
+		&& !reference.includes( "?" );
+}
+
+/**
+ * Collects the scripts and stylesheets a page cannot work without.
+ *
+ * @param {string} html contents of one built page
+ * @returns {string[]} referenced paths, in document order and de-duplicated
+ */
+export function collectAssetRefs( html ) {
+	const found = new Set();
+
+	for ( const [ tag, reference ] of html.matchAll( ASSET_ATTR_RE ) ) {
+		if ( ASSET_TAG_RE.test( tag ) && isLocalReference( reference ) ) {
+			found.add( reference );
+		}
+	}
+
+	return [...found];
+}
+
+/**
+ * Collects the pages and files a page links to.
+ *
+ * @param {string} html contents of one built page
+ * @returns {string[]} referenced paths, de-duplicated
+ */
+export function collectLinkRefs( html ) {
+	const found = new Set();
+
+	for ( const [ , reference ] of html.matchAll( LINK_RE ) ) {
+		const [path] = reference.split( "#" );
+
+		if ( path && isLocalReference( path ) ) {
+			found.add( path );
+		}
+	}
+
+	return [...found];
+}
+
+/**
+ * Collects the images and media a page displays.
+ *
+ * Every candidate of a `srcset` counts: a browser on a wide screen asks for the
+ * widest one, so a variant missing from the set breaks the page for some readers
+ * and not for others — the worst kind to leave unreported.
+ *
+ * @param {string} html contents of one built page
+ * @returns {string[]} referenced paths, de-duplicated
+ */
+export function collectImageRefs( html ) {
+	const found = new Set();
+
+	for ( const [ , reference ] of html.matchAll( IMG_SRC_RE ) ) {
+		if ( isLocalReference( reference ) ) {
+			found.add( reference );
+		}
+	}
+
+	for ( const [ , srcset ] of html.matchAll( SRCSET_RE ) ) {
+		for ( const candidate of srcset.split( "," ) ) {
+			const [reference] = candidate.trim().split( /\s+/ );
+
+			if ( reference && isLocalReference( reference ) ) {
+				found.add( reference );
+			}
+		}
+	}
+
+	return [...found];
+}
+
+/**
+ * Turns a reference as written into the path below the output folder it addresses.
+ *
+ * A site-absolute reference is read the way the web server reads it, with the
+ * site's base path stripped. A relative one means nothing on its own: the browser
+ * resolves it against the address of the page it stands in, so that is what this
+ * resolves it against too. One that climbs above the site root stays as it is —
+ * no file of this build can satisfy it, and saying so is the point.
+ *
+ * @param {string} reference reference as written in the HTML
+ * @param {string} page output path of the page holding it, relative and posix-style
+ * @param {string} base site's base path, as configured
+ * @returns {string} path relative to the output folder, posix-style and without a leading slash
+ */
+function resolveReference( reference, page, base ) {
+	const decoded = decodeURI( reference );
+
+	if ( decoded.startsWith( "/" ) ) {
+		const withoutBase = base !== "/" && decoded.startsWith( base )
+			? decoded.slice( base.length - 1 )
+			: decoded;
+
+		return withoutBase.replace( /^\//, "" );
+	}
+
+	return posix.normalize( posix.join( posix.dirname( page ), decoded ) ).replace( /^\//, "" );
+}
+
+/**
+ * Tells whether a build wrote something a static server could answer a reference with.
+ *
+ * The three spellings are the ones every static server tries, cratly's own
+ * `s3-http` included: the path itself, an `index.html` inside it, and the path
+ * plus `.html`.
+ *
+ * The comparison runs against the names the build actually wrote, never against
+ * the file system — macOS and Windows answer `existsSync` case-insensitively, so a
+ * page preloading `de_Kontakt.md.js` while only `de_kontakt.md.js` exists would
+ * look sound on the machine of whoever wrote the page and break in production.
+ * That pair is one of the two ways two pages end up sharing a build identity.
+ *
+ * @param {string} reference reference as written in the HTML
+ * @param {string} page output path of the page holding it, relative and posix-style
+ * @param {Set<string>} files paths of every file in the output, relative and posix-style
+ * @param {string} base site's base path, as configured
+ * @returns {boolean} true when one of those files was written
+ */
+function resolvesToFile( reference, page, files, base ) {
+	const relativePath = resolveReference( reference, page, base );
+
+	if ( relativePath === "" || relativePath === "." ) {
+		return files.has( "index.html" );
+	}
+
+	return [ relativePath, posix.join( relativePath, "index.html" ), `${relativePath}.html` ]
+		.some( candidate => files.has( candidate ) );
+}
+
+/**
+ * Lists everything a build wrote.
+ *
+ * @param {string} outDir absolute path of the build output folder
+ * @returns {Set<string>} every file below outDir, relative and posix-style
+ */
+function collectFiles( outDir ) {
+	const files = new Set();
+
+	/**
+	 * @param {string} dir folder to descend into
+	 * @param {string} prefix path of that folder relative to outDir
+	 * @returns {void}
+	 */
+	function walk( dir, prefix ) {
+		for ( const entry of readdirSync( dir, { withFileTypes: true } ) ) {
+			const relativePath = prefix ? `${prefix}/${entry.name}` : entry.name;
+
+			if ( entry.isDirectory() ) {
+				walk( join( dir, entry.name ), relativePath );
+			} else {
+				files.add( relativePath );
+			}
+		}
+	}
+
+	walk( outDir, "" );
+
+	return files;
+}
+
+/**
+ * Reads a finished build and reports what it references but does not contain.
+ *
+ * @param {string} outDir absolute path of the build output folder
+ * @param {object} [options] what to look at
+ * @param {string} [options.base] site's base path
+ * @param {boolean} [options.content] also check links and images, not just scripts
+ * @param {string[]} [options.pages] output files the generator said it would write, relative and posix-style
+ * @returns {{pages: object[], assets: object[], content: object[]}}
+ *          what the output does not contain, split by how much it matters
+ */
+export function verifyBuild( outDir, { base = "/", content = true, pages = [] } = {} ) {
+	const root = resolve( outDir );
+	const files = collectFiles( root );
+	const problems = { pages: [], assets: [], content: [] };
+
+	for ( const page of pages ) {
+		if ( !files.has( page ) ) {
+			problems.pages.push( { page, reference: page } );
+		}
+	}
+
+	for ( const page of [...files].filter( file => file.endsWith( ".html" ) ).sort() ) {
+		const html = readFileSync( join( root, page ), "utf-8" );
+
+		for ( const reference of collectAssetRefs( html ) ) {
+			if ( !resolvesToFile( reference, page, files, base ) ) {
+				problems.assets.push( { page, reference } );
+			}
+		}
+
+		if ( content ) {
+			for ( const reference of [ ...collectLinkRefs( html ), ...collectImageRefs( html ) ] ) {
+				if ( !resolvesToFile( reference, page, files, base ) ) {
+					problems.content.push( { page, reference } );
+				}
+			}
+		}
+	}
+
+	return problems;
+}
+
+/**
+ * Renders a set of problems as one line per reference, capped so a systematic
+ * mistake does not bury the terminal.
+ *
+ * @param {{page: string, reference: string}[]} problems what verifyBuild found
+ * @param {number} [limit] how many to name
+ * @returns {string} indented, newline-separated list
+ */
+export function formatProblems( problems, limit = 10 ) {
+	const lines = problems.slice( 0, limit ).map( ( { page, reference } ) => `  ${page} → ${reference}` );
+
+	if ( problems.length > limit ) {
+		lines.push( `  … and ${problems.length - limit} more` );
+	}
+
+	return lines.join( "\n" );
+}
+
+/**
+ * Renders what a build found as the report file readers other than a terminal get.
+ *
+ * `fatal` says which of the two situations the file describes: a build that ended
+ * without writing a usable site, or one that finished and carries a content
+ * mistake. A reader showing this to whoever wrote the page needs that distinction
+ * and should not have to re-derive it from which array is empty.
+ *
+ * @param {{pages: object[], assets: object[], content: object[]}} problems what verifyBuild found
+ * @param {object} [options]
+ * @param {object} [options.adapter] name and version of what produced the build
+ * @param {Object<string,string>} [options.sources] built page path → source file an author edits
+ * @param {Date} [options.generated] when the build ran
+ * @returns {string} the file's content, newline-terminated
+ */
+export function renderBuildReport( problems, { adapter = {}, sources = {}, generated = new Date() } = {} ) {
+	/**
+	 * @param {{page: string, reference: string}[]} entries one class of problem
+	 * @returns {object[]} the same entries, each naming its source file where known
+	 */
+	const withSources = entries => entries.map( entry => ( {
+		...entry,
+		...sources[entry.page] != null && { source: sources[entry.page] },
+	} ) );
+
+	return `${JSON.stringify( {
+		specVersion: BUILD_REPORT_VERSION,
+		adapter,
+		generated: generated.toISOString(),
+		fatal: problems.pages.length > 0 || problems.assets.length > 0,
+		problems: {
+			pages: withSources( problems.pages ),
+			assets: withSources( problems.assets ),
+			content: withSources( problems.content ),
+		},
+	}, null, "\t" )}\n`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "scavold",
-	"version": "0.2.0-rc.5",
+	"version": "0.2.0-rc.7",
 	"type": "module",
 	"description": "VitePress theme framework — a scaffold for building custom VitePress themes with Vue at the core",
 	"keywords": [
@@ -18,10 +18,10 @@
 	"license": "MIT",
 	"repository": {
 		"type": "git",
-		"url": "https://gitlab.com/cepharum-foss/cratly/scavold.git"
+		"url": "https://gitlab.com/cratly/scavold.git"
 	},
 	"homepage": "https://scavold.io",
-	"bugs": "https://gitlab.com/cepharum-foss/cratly/scavold/-/issues",
+	"bugs": "https://gitlab.com/cratly/scavold/-/issues",
 	"engines": {
 		"node": ">=20"
 	},
@@ -72,7 +72,7 @@
 		"vue": ">=3.0.0"
 	},
 	"dependencies": {
-		"@cepharum/vue3-i18n": "^0.5.4",
+		"@cepharum/vue3-i18n": "^2.0.0",
 		"markdown-it-container": "^4.0.0",
 		"sharp": "^0.34.5",
 		"yaml": "^2.8.3"

package/scripts/check-fixture.js

@@ -53,7 +53,7 @@ function linkSelf() {
 
 /**
  * Creates the fixture's media files. Images are real (the pipeline reads their
- * dimensions); the other two only ever get copied, so a few bytes carrying the right
+ * dimensions); the others only ever get copied, so a few bytes carrying the right
  * extension are enough.
  */
 async function writeMedia() {
@@ -76,6 +76,8 @@ async function writeMedia() {
 
 	writeFileSync( join( media, "doc.pdf" ), "%PDF-1.4\n% fixture placeholder\n" );
 	writeFileSync( join( media, "clip.mp4" ), "fixture placeholder\n" );
+	// An extension VitePress does not know, so its link rules take the file for a page.
+	writeFileSync( join( media, "patch.diff" ), "--- a\n+++ b\n" );
 }
 
 /**
@@ -194,6 +196,8 @@ console.log( "\nmedia that is not an image" );
 expect( published.includes( "doc.pdf" ), "copies a document into the site output" );
 expect( published.includes( "clip.mp4" ), "copies a video into the site output" );
 expect( media.includes( 'href="/media/doc.pdf"' ), "rewrites a link to a media file" );
+expect( media.includes( 'href="/media/patch.diff"' ),
+	"links a media file of an extension VitePress does not know as that file, not as a page" );
 // On the entry page, where the fixture's page links live. VitePress resolves them to
 // .html; what matters is that the media pipeline did not touch them.
 expect( built( "index.html" ).includes( 'href="/containers.html"' ), "leaves a link to a page alone" );
@@ -321,6 +325,33 @@ expect( [ "Sunday", "21", "June", "2026" ].every( part => ownDate.includes( part
 	"hands a site's own component the timestamp formatting as well",
 	`the entry reads ${JSON.stringify( ownDate )}` );
 
+// ── build report ─────────────────────────────────────────────────────────────
+
+console.log( "\nbuild report" );
+
+// pages/dead-link.md links to two files this build does not contain, one written
+// relative and one site-absolute. Neither ends the build — a content mistake must
+// not stand between a finished page and its publication — and both have to be
+// findable afterwards by someone who cannot read a job log.
+expect( /1 dead link|dead link\(s\) found/.test( log ) === false,
+	"lets a dead link through instead of ending the build over it" );
+expect( /2 link\(s\) or image\(s\) point at files this build does not contain/.test( log ),
+	"names both spellings of a dead link in the build log" );
+
+const report = JSON.parse( readFileSync( join( SITE, ".cratly", "build-report.json" ), "utf-8" ) );
+
+expect( report.adapter?.version === version, "reports this package's version as the adapter version",
+	`found ${report.adapter?.version}` );
+expect( report.fatal === false, "says the build survived what it found" );
+expect( report.problems?.content?.map( p => p.reference ).sort().join( " " ) === "./www.example.com.html /tour.html",
+	"carries both dead references",
+	`found ${report.problems?.content?.map( p => p.reference ).join( " " ) || "nothing"}` );
+expect( report.problems.content.every( p => p.source === "dead-link.md" ),
+	"names the file an author would open, not just the file the build wrote",
+	`found ${report.problems.content.map( p => p.source ).join( " " )}` );
+expect( report.problems?.pages?.length === 0 && report.problems?.assets?.length === 0,
+	"leaves the fatal classes empty on a build that finished" );
+
 // ── content security policy ──────────────────────────────────────────────────
 
 console.log( "\ncontent security policy" );