caracms 0.0.0-stage → 0.2.0

package/src/cli/validate.ts

@@ -0,0 +1,471 @@
+/**
+ * `caracms validate [--fix] [--json]` (M8 Decisions 15–16): the site's content checked
+ * against its config itself (never the generated schema files, so a stale schema can't
+ * pass bad content), from the site's root, with no server, network or environment.
+ *
+ * - **Errors** would break a build, lose data, or are files the editor couldn't open: JSON
+ *   that doesn't parse, a file in no collection, a file the editor can't open (no title, a
+ *   nested `index.json`), an unknown block type or field, a value of the wrong shape (rich
+ *   text outside its grammar and a media value with no key among them), a missing required
+ *   key (a document's `title`, a page's `blocks`, a shared block's `block`, a block's
+ *   `type`), a reference to a document or shared block that isn't there, two documents at
+ *   one URL, a document on a code route (Decision 10), a list inside a list inside a list.
+ * - **Warnings** are what the editor itself only warns about (fields.ts → fieldWarnings:
+ *   half links, links to no page, missing alt text, too many buttons, numbers out of
+ *   range…), what renders with a fallback (an unknown select value or button style), a
+ *   lockup line too long for its box, schema files out of date, a content file with no
+ *   `$schema`, an image with no `w` or `h` (it renders, but can't keep its space while it
+ *   loads), and a file the editor's next save would reformat (serialize.ts → savedForm).
+ * - **`--fix`** runs `schemas`, then rewrites each content file a save would reformat in
+ *   the form a save writes, changing only whitespace, and prints each one.
+ *
+ * Exit 1 on errors only. Each finding is `file › path.in.the.json: what's wrong`.
+ */
+import { readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import type { ResolvedCollection, ResolvedSite } from '../config.ts';
+import { codeRouteAt, codeRouteMessage, shadowingMessage, shadowingRoutes, type CodeRoute } from '../code-routes.ts';
+import { pagesRoutes, readCodeRoutes, srcDirOf } from '../code-routes-disk.ts';
+import { listDocuments, type DocumentEntry } from '../content.ts';
+import { own } from '../document.ts';
+import { fieldWarnings, parseDay, richTextOptions, type Field, type Fields, type WarningContext } from '../fields.ts';
+import { measureLockup } from '../measure.ts';
+import { isFileKey } from '../files.ts';
+import { readRichText } from '../rich-text.ts';
+import { savedForm } from '../serialize.ts';
+import { SCHEMA_KEY, schemaRef } from '../schema-key.ts';
+import { sameAddress } from '../slug.ts';
+import { hiddenDocuments, hiddenPages } from '../links.ts';
+import { runSchemas, schemaFileChanges, schemasReport } from './schemas.ts';
+import { jsonFilesUnder, loadSite } from './site.ts';
+
+export interface Finding {
+	/** Relative to the site's root. */
+	file: string;
+	/** The JSON path, in dot and bracket form (`blocks[2].heading`); `''` for the file itself. */
+	path: string;
+	message: string;
+}
+
+export interface Report {
+	errors: Finding[];
+	warnings: Finding[];
+}
+
+type Site = Pick<ResolvedSite, 'root' | 'collections' | 'blocks' | 'textStyles' | 'phoneLinesWidth'>;
+
+const key = (path: string, k: string) => (path === '' ? k : `${path}.${k}`);
+const at = (path: string, i: number) => `${path}[${i}]`;
+/** fields.ts's dotted relative paths (`1.href`, `credits.0.name`) in dot and bracket form, under `base`. */
+function fromDotted(base: string, dotted: string): string {
+	if (dotted === '') return base;
+	return dotted.split('.').reduce((p, part) => (/^\d+$/.test(part) ? at(p, Number(part)) : key(p, part)), base);
+}
+
+const isObject = (v: unknown): v is Record<string, unknown> => !!v && typeof v === 'object' && !Array.isArray(v);
+
+/** A value as a person would name it in a sentence. */
+function what(v: unknown): string {
+	if (v === null) return 'null';
+	if (Array.isArray(v)) return 'a list';
+	switch (typeof v) {
+		case 'string':
+			return `text (${JSON.stringify(v.length > 40 ? `${v.slice(0, 40)}…` : v)})`;
+		case 'number':
+			return `the number ${v}`;
+		case 'boolean':
+			return v ? 'true' : 'false';
+		default:
+			return 'an object';
+	}
+}
+
+const quoteList = (values: readonly string[]) => values.map((v) => JSON.stringify(v)).join(', ');
+
+interface Context {
+	file: string;
+	site: Site;
+	report: Report;
+	warningContext: WarningContext;
+	/** Whether a document exists, for references (and shared entries). */
+	exists: (collection: string, path: string) => boolean;
+}
+
+const error = (c: Context, path: string, message: string) => c.report.errors.push({ file: c.file, path, message });
+const warning = (c: Context, path: string, message: string) => c.report.warnings.push({ file: c.file, path, message });
+
+/** Keys of `raw` that `known` doesn't have, each an error. */
+function unknownKeys(c: Context, raw: Record<string, unknown>, known: readonly string[], path: string, where: string) {
+	for (const k of Object.keys(raw)) {
+		if (!known.includes(k)) error(c, key(path, k), `"${k}" isn't a field of ${where}. Its fields are ${quoteList(known.filter((n) => n !== SCHEMA_KEY))}.`);
+	}
+}
+
+const strings = (v: unknown) => Array.isArray(v) && v.every((s) => typeof s === 'string');
+
+/**
+ * A field's stored value against its field: errors for a wrong shape (fields.ts's reader
+ * would show it as empty, and the next save of that field would lose it), warnings for
+ * what renders with a fallback. `inList`: how many lists this value sits inside.
+ */
+function checkValue(c: Context, field: Field, raw: unknown, path: string, inList: number) {
+	if (raw === undefined) return;
+	const wrong = (expected: string) => {
+		if (Array.isArray(raw) && inList >= 2) error(c, path, `This is a list inside a list inside a list; lists nest one level at most. Expected ${expected}.`);
+		else error(c, path, `Expected ${expected}, found ${what(raw)}.`);
+	};
+	switch (field.kind) {
+		case 'text':
+			if (typeof raw !== 'string') wrong('text (a string)');
+			return;
+		case 'lockup': {
+			const plain = strings(raw);
+			const withPhone = isObject(raw) && strings(raw.lines) && (raw.phone === undefined || strings(raw.phone)) && Object.keys(raw).every((k) => k === 'lines' || k === 'phone');
+			if (!plain && !withPhone) return wrong('a lockup: a list of lines (["First line", "Second line"]), or { "lines": […], "phone": […] }');
+			lockupWarnings(c, field.style, raw, path);
+			return;
+		}
+		case 'select':
+			if (typeof raw !== 'string') return wrong(`one of ${quoteList(field.options.map((o) => o.value))}`);
+			if (!field.options.some((o) => o.value === raw)) {
+				warning(c, path, `"${raw}" isn't one of this field's options (${quoteList(field.options.map((o) => o.value))}), so the page shows "${field.default}".`);
+			}
+			return;
+		case 'richText': {
+			if (typeof raw !== 'string' && !Array.isArray(raw)) return wrong('rich text: a list of { "p": "…" } entries, or a string');
+			// The grammar (rich-text.ts): what the reader couldn't read is lost on the next save.
+			const { issues } = readRichText(raw, richTextOptions(field));
+			for (const issue of issues) {
+				if (issue.code !== 'unreadable') continue;
+				const allowed = ['p', ...field.headings, 'ul', 'ol'];
+				error(c, at(path, issue.block), `This entry isn't rich text this field can read. Each entry is one of ${allowed.map((k) => `{ "${k}": ${k === 'ul' || k === 'ol' ? '[…]' : '"…"'} }`).join(', ')}.`);
+			}
+			return;
+		}
+		case 'link': {
+			const keys = field.addressOnly ? ['href'] : ['label', 'href'];
+			if (!isObject(raw)) return wrong(field.addressOnly ? 'a link: { "href": "…" }' : 'a link: { "label": "…", "href": "…" }');
+			unknownKeys(c, raw, keys, path, 'a link');
+			for (const k of keys) if (raw[k] !== undefined && typeof raw[k] !== 'string') error(c, key(path, k), `Expected text (a string), found ${what(raw[k])}.`);
+			return;
+		}
+		case 'buttons': {
+			if (!Array.isArray(raw)) return wrong('a list of buttons: [{ "label", "href", "style" }]');
+			const styles = field.styles.map((s) => s.value);
+			raw.forEach((b, i) => {
+				const p = at(path, i);
+				if (!isObject(b)) return error(c, p, `Expected a button ({ "label", "href", "style" }), found ${what(b)}.`);
+				unknownKeys(c, b, ['label', 'href', 'style'], p, 'a button');
+				for (const k of ['label', 'href', 'style']) if (b[k] !== undefined && typeof b[k] !== 'string') error(c, key(p, k), `Expected text (a string), found ${what(b[k])}.`);
+				if (typeof b.style === 'string' && !styles.includes(b.style)) warning(c, key(p, 'style'), `"${b.style}" isn't one of the button styles (${quoteList(styles)}), so it shows as "${styles[0]}".`);
+			});
+			return;
+		}
+		case 'toggle':
+			if (typeof raw !== 'boolean') wrong('true or false');
+			return;
+		case 'number':
+			if (raw !== null && (typeof raw !== 'number' || !Number.isFinite(raw))) wrong('a number');
+			return;
+		case 'date':
+			if (raw !== null && parseDay(raw) === null) wrong('a date in the form 2026-10-15');
+			return;
+		case 'reference':
+			if (raw === null) return;
+			if (typeof raw !== 'string') return wrong(`the path of a document in ${field.to}`);
+			if (raw.trim() !== '' && !c.exists(field.to, raw.trim())) error(c, path, `This points at "${raw}", which isn't a document in ${c.site.collections[field.to]?.label ?? field.to}.`);
+			return;
+		case 'media':
+			checkMedia(c, raw, path, wrong);
+			return;
+		case 'list': {
+			if (!Array.isArray(raw)) return wrong('a list');
+			raw.forEach((item, i) => {
+				const p = at(path, i);
+				if (field.item) return checkValue(c, field.item, item, p, inList + 1);
+				if (!isObject(item)) {
+					if (Array.isArray(item) && inList >= 1) return error(c, p, 'This is a list inside a list inside a list; lists nest one level at most. Expected an item of fields.');
+					return error(c, p, `Expected an item of fields (${quoteList(Object.keys(field.fields ?? {}))}), found ${what(item)}.`);
+				}
+				checkFields(c, field.fields ?? {}, item, p, 'this list\'s items', inList + 1);
+			});
+			return;
+		}
+		case 'group':
+			if (!isObject(raw)) return wrong(`a group of fields (${quoteList(Object.keys(field.fields))})`);
+			checkFields(c, field.fields, raw, path, 'this group', inList);
+			return;
+	}
+}
+
+const MEDIA_IMAGE_KEYS = ['key', 'alt', 'decorative', 'focal', 'w', 'h'];
+const MEDIA_CLIP_KEYS = ['video', 'play', 'poster', 'name', 'duration', 'w', 'h'];
+
+function checkMedia(c: Context, raw: unknown, path: string, wrong: (expected: string) => void) {
+	if (raw === null) return;
+	if (!isObject(raw)) return wrong('an image ({ "key", "alt", … }), a video ({ "video", … }) or null');
+	const isClip = raw.video !== undefined && raw.key === undefined;
+	if (isClip) {
+		if (typeof raw.video !== 'string' || raw.video.trim() === '') error(c, key(path, 'video'), 'A video needs its Mux playback ID in "video".');
+		unknownKeys(c, raw, MEDIA_CLIP_KEYS, path, 'a video');
+		if (raw.play !== undefined && raw.play !== 'loop' && raw.play !== 'player') error(c, key(path, 'play'), `Expected "loop" or "player", found ${what(raw.play)}.`);
+		return;
+	}
+	if (typeof raw.key !== 'string' || raw.key.trim() === '') return error(c, key(path, 'key'), 'This image has no "key": the bucket key of an image in the media library (`caracms media import` prints it).');
+	unknownKeys(c, raw, MEDIA_IMAGE_KEYS, path, 'an image');
+	if (raw.alt !== undefined && typeof raw.alt !== 'string') error(c, key(path, 'alt'), `Expected text (a string), found ${what(raw.alt)}.`);
+	if (raw.decorative !== undefined && typeof raw.decorative !== 'boolean') error(c, key(path, 'decorative'), `Expected true or false, found ${what(raw.decorative)}.`);
+	for (const k of ['w', 'h']) if (raw[k] !== undefined && (typeof raw[k] !== 'number' || !((raw[k] as number) > 0))) error(c, key(path, k), `Expected the size in pixels, found ${what(raw[k])}.`);
+	sizeWarning(c, raw, path);
+}
+
+/**
+ * MEC trial item 5: an image with no `w` or `h` still renders, but without its size the page
+ * can't reserve its box (no width and height on the `<img>`, media.ts → fluidImage), so the
+ * layout shifts as it loads. A file's key (a PDF in a media slot) has no size to give.
+ */
+function sizeWarning(c: Context, raw: Record<string, unknown>, path: string) {
+	if (typeof raw.key !== 'string' || isFileKey(raw.key)) return;
+	const missing = ['w', 'h'].filter((k) => raw[k] === undefined);
+	if (!missing.length) return;
+	const which = missing.length === 2 ? '"w" or "h"' : `"${missing[0]}"`;
+	warning(c, path, `This image (${raw.key}) has no ${which}, its size in pixels, so the page can't keep its space while it loads. \`caracms media import <the image's file>\` prints its key with "w" and "h": add them here.`);
+}
+
+/** A lockup line that can't stay at its style's smallest size even across a whole phone (or, for main lines over phone lines, across the phone-lines width). */
+function lockupWarnings(c: Context, styleName: string, raw: unknown, path: string) {
+	const style = own(c.site.textStyles, styleName);
+	if (!style) return;
+	const lines = Array.isArray(raw) ? (raw as string[]) : ((raw as { lines: string[] }).lines ?? []);
+	const phone = Array.isArray(raw) ? null : ((raw as { phone?: string[] }).phone ?? null);
+	const sets: [string, string[], number][] = phone?.length ? [['lines', lines, c.site.phoneLinesWidth], ['phone', phone, 375]] : [['', lines, 375]];
+	for (const [part, set, widthPx] of sets) {
+		const measured = measureLockup(set, style);
+		const p = part ? key(path, part) : path;
+		if (measured.longest > 0 && widthPx / measured.longest < style.minSizePx) {
+			warning(c, p, `The longest line is too long for its box: even ${widthPx}px wide it would be under ${style.minSizePx}px, ${style.name}'s smallest size. Break it into shorter lines${part === '' ? ' or add phone lines' : ''}.`);
+		}
+		const uncovered = measured.uncovered;
+		if (uncovered.length) warning(c, p, `${quoteList(uncovered)} ${uncovered.length === 1 ? "isn't" : "aren't"} in ${style.name}'s font, so the line may not fit.`);
+	}
+}
+
+/** An object of fields: unknown keys are errors; each field's value is checked, then the editor's own warnings. */
+function checkFields(c: Context, fields: Fields, raw: Record<string, unknown>, path: string, where: string, inList: number, extra: readonly string[] = []) {
+	unknownKeys(c, raw, [...extra, ...Object.keys(fields)], path, where);
+	for (const [k, f] of Object.entries(fields)) {
+		if (!Object.hasOwn(raw, k)) continue;
+		checkValue(c, f, raw[k], key(path, k), inList);
+		editorWarnings(c, f, raw[k], key(path, k));
+	}
+}
+
+/** The editor's field warnings (fields.ts), minus what the shape checks already reported. */
+function editorWarnings(c: Context, field: Field, raw: unknown, path: string) {
+	// Nested fields are reached through their own checkFields call: only this field's own here.
+	if (field.kind === 'group' || (field.kind === 'list' && !field.item)) {
+		for (const w of fieldWarnings(field, raw, c.warningContext)) if (w.path === '' && (w.code === 'too-few' || w.code === 'too-many')) warning(c, path, w.message);
+		return;
+	}
+	for (const w of fieldWarnings(field, raw, c.warningContext)) {
+		const p = fromDotted(path, w.path);
+		if (w.code === 'unreadable' || w.code === 'missing-reference') continue;
+		// Rich text outside the field's grammar (an h1, a heading or a link the field doesn't take) is an error: Decision 15.
+		if (w.code === 'disallowed-kind' || w.code === 'link-off' || w.code === 'italic-off') error(c, p, w.message);
+		else warning(c, p, w.message);
+	}
+}
+
+function checkBlock(c: Context, raw: unknown, path: string, collection: ResolvedCollection | null) {
+	if (!isObject(raw)) return error(c, path, `Expected a block ({ "type": "…", … }), found ${what(raw)}.`);
+	if (Object.hasOwn(raw, 'shared') && collection) {
+		if (typeof raw.shared !== 'string' || raw.shared.trim() === '') return error(c, key(path, 'shared'), 'Expected the path of a shared block.');
+		unknownKeys(c, raw, ['shared', 'type'], path, 'a shared block\'s entry');
+		if (!c.exists('shared', raw.shared)) error(c, key(path, 'shared'), `There's no shared block "${raw.shared}" (content/shared/${raw.shared}.json).`);
+		return;
+	}
+	if (typeof raw.type !== 'string' || raw.type === '') return error(c, key(path, 'type'), `This block has no "type". The site's blocks are ${quoteList(Object.keys(c.site.blocks))}.`);
+	const block = own(c.site.blocks, raw.type);
+	if (!block) return error(c, key(path, 'type'), `There's no block type "${raw.type}". The site's blocks are ${quoteList(Object.keys(c.site.blocks))}.`);
+	checkFields(c, block.fields, raw, path, `the ${block.label} block`, 0, ['type']);
+}
+
+const SEO_KEYS = ['title', 'description', 'image'];
+function checkSeo(c: Context, raw: unknown, path: string) {
+	if (raw === undefined) return;
+	if (!isObject(raw)) return error(c, path, `Expected { "title", "description", "image" }, found ${what(raw)}.`);
+	unknownKeys(c, raw, SEO_KEYS, path, 'seo');
+	for (const k of ['title', 'description']) if (raw[k] !== undefined && typeof raw[k] !== 'string') error(c, key(path, k), `Expected text (a string), found ${what(raw[k])}.`);
+	if (raw.image !== undefined && raw.image !== null) {
+		if (!isObject(raw.image) || typeof raw.image.key !== 'string' || raw.image.key.trim() === '') error(c, key(path, 'image'), 'The share image needs the "key" of an image in the media library.');
+	}
+}
+
+function checkDocument(c: Context, collection: ResolvedCollection, raw: unknown) {
+	if (!isObject(raw)) return error(c, '', `Expected a JSON object, found ${what(raw)}.`);
+	const own = collection.fields ?? {};
+	if (raw[SCHEMA_KEY] !== undefined && typeof raw[SCHEMA_KEY] !== 'string') error(c, SCHEMA_KEY, 'Expected the relative path of its schema file.');
+	if (raw.title !== undefined && typeof raw.title !== 'string') error(c, 'title', `Expected text (a string), found ${what(raw.title)}.`);
+	switch (collection.kind) {
+		case 'sections': {
+			checkFields(c, own, raw, '', `a ${collection.label} page`, 0, [SCHEMA_KEY, 'title', 'hidden', 'blocks', 'seo']);
+			// M9 Decision 7.
+			if (raw.hidden !== undefined && raw.hidden !== true) error(c, 'hidden', `Expected true (hidden from the site) or no "hidden" at all, found ${what(raw.hidden)}.`);
+			if (!Object.hasOwn(raw, 'blocks')) error(c, 'blocks', 'This page has no "blocks". Every page has a list of blocks, even an empty one ([]).');
+			else if (!Array.isArray(raw.blocks)) error(c, 'blocks', `Expected a list of blocks, found ${what(raw.blocks)}.`);
+			else raw.blocks.forEach((b, i) => checkBlock(c, b, at('blocks', i), collection));
+			checkSeo(c, raw.seo, 'seo');
+			return;
+		}
+		case 'fields':
+			checkFields(c, own, raw, '', `a ${collection.label} document`, 0, [SCHEMA_KEY, 'title', 'seo']);
+			checkSeo(c, raw.seo, 'seo');
+			return;
+		case 'shared':
+			unknownKeys(c, raw, [SCHEMA_KEY, 'title', 'block'], '', 'a shared block');
+			if (!Object.hasOwn(raw, 'block')) error(c, 'block', 'This shared block has no "block".');
+			else checkBlock(c, raw.block, 'block', null);
+			return;
+		case 'settings': {
+			checkFields(c, own, raw, '', 'Site Settings', 0, [SCHEMA_KEY, 'title', 'editors', 'brand', 'seo', 'googleTag', 'formRecipients', 'redirects']);
+			if (raw.editors !== undefined && !strings(raw.editors)) error(c, 'editors', `Expected a list of email addresses, found ${what(raw.editors)}.`);
+			if (raw.brand !== undefined) {
+				if (!isObject(raw.brand)) error(c, 'brand', `Expected { "name", "accent", "logo", "icon" }, found ${what(raw.brand)}.`);
+				else {
+					unknownKeys(c, raw.brand, ['name', 'accent', 'logo', 'icon'], 'brand', 'the brand');
+					for (const k of ['name', 'accent']) if (raw.brand[k] !== undefined && typeof raw.brand[k] !== 'string') error(c, key('brand', k), `Expected text (a string), found ${what(raw.brand[k])}.`);
+					for (const k of ['logo', 'icon']) {
+						const v = raw.brand[k];
+						if (v !== undefined && v !== null && (!isObject(v) || typeof v.key !== 'string' || v.key.trim() === '')) error(c, key('brand', k), 'Expected an image from the media library ({ "key", "w", "h" }) or null.');
+						else if (isObject(v)) sizeWarning(c, v, key('brand', k));
+					}
+				}
+			}
+			checkSeo(c, raw.seo, 'seo');
+			if (raw.googleTag !== undefined && typeof raw.googleTag !== 'string') error(c, 'googleTag', `Expected a tag ID (text), found ${what(raw.googleTag)}.`);
+			if (raw.formRecipients !== undefined && !(isObject(raw.formRecipients) && Object.values(raw.formRecipients).every(strings))) {
+				error(c, 'formRecipients', 'Expected { "<form id>": ["address", …] }.');
+			}
+			if (raw.redirects !== undefined && !(Array.isArray(raw.redirects) && raw.redirects.every((r) => isObject(r) && typeof r.from === 'string' && typeof r.to === 'string'))) {
+				error(c, 'redirects', 'Expected a list of { "from": "/old", "to": "/new" }.');
+			}
+			return;
+		}
+	}
+}
+
+/** Every finding for the site's content. `codeRoutes`: the site's own (default: read from its src/pages). */
+export async function validateSite(site: Site, codeRoutes: readonly CodeRoute[] = readCodeRoutes(site.root, srcDirOf(site.root), Object.values(site.collections))): Promise<Report> {
+	const report: Report = { errors: [], warnings: [] };
+	const entries = await listDocuments(site);
+	const ids = new Set(entries.map((e) => `${e.collection}\0${e.path}`));
+	const exists = (collection: string, path: string) => ids.has(`${collection}\0${path}`);
+	const warningContext: WarningContext = { addresses: entries.map((e) => e.url), documentExists: exists, codeRoutes, hiddenPages: hiddenPages(entries), hiddenDocuments: hiddenDocuments(entries) };
+
+	// Files in no collection: under content/ and every collection's folder.
+	const listed = new Set(entries.map((e) => e.file));
+	const scanned = new Set<string>();
+	for (const dir of [join(site.root, 'content'), ...Object.values(site.collections).map((c) => c.dir)]) {
+		for (const file of jsonFilesUnder(site.root, dir)) scanned.add(file);
+	}
+	for (const file of [...scanned].sort()) {
+		if (!listed.has(file)) report.errors.push({ file, path: '', message: "This file isn't in any collection, so nothing reads it. Move it into a collection's folder, or delete it." });
+	}
+
+	// A second route with parameters at a collection's base hides its documents (code-routes.ts → one per base).
+	for (const s of shadowingRoutes(pagesRoutes(site.root, srcDirOf(site.root)), Object.values(site.collections))) {
+		report.errors.push({ file: s.route.file, path: '', message: shadowingMessage(s) });
+	}
+
+	const urls = new Map<string, DocumentEntry>();
+	for (const entry of entries) {
+		const c: Context = { file: entry.file, site, report, warningContext, exists };
+		const collection = site.collections[entry.collection]!;
+		if (entry.warning) {
+			if (entry.warning.code === 'no-title') error(c, 'title', 'This document has no "title", so the editor can\'t open it. Add one.');
+			else error(c, '', entry.warning.message);
+			if (entry.warning.code !== 'no-title') continue;
+		}
+		let text: string;
+		try {
+			text = readFileSync(join(site.root, entry.file), 'utf8');
+		} catch {
+			continue;
+		}
+		const raw = JSON.parse(text) as unknown;
+		checkDocument(c, collection, raw);
+		// M9 Decision 7: as in Tina, the home page can't be hidden (content.ts reads it as shown).
+		if (collection.kind === 'sections' && entry.path === 'index' && isObject(raw) && raw.hidden === true) warning(c, 'hidden', 'The home page can’t be hidden, so it’s shown. Remove "hidden".');
+		if (isObject(raw) && raw[SCHEMA_KEY] === undefined) warning(c, '', `This file has no "$schema" (${JSON.stringify(schemaRef(collection, entry.file))}). \`caracms validate --fix\` adds it.`);
+		const saved = savedForm(text, collection, site);
+		if (saved !== null && saved !== text) warning(c, '', REFORMAT_MESSAGE);
+		if (entry.url !== null && collection.urlBase !== null) {
+			const route = codeRouteAt(entry.url, codeRoutes);
+			if (route) error(c, '', `${codeRouteMessage(entry.url, route)} Delete ${route.file} if this document replaces it, or move the document.`);
+			const same = sameAddress(entry.url);
+			const first = urls.get(same);
+			if (first) error(c, '', `${first.file} is at ${entry.url} too. Two documents can't share an address: move one.`);
+			else urls.set(same, entry);
+		}
+	}
+
+	for (const change of schemaFileChanges(site)) {
+		report.warnings.push({
+			file: change.file,
+			path: '',
+			message: change.text === null ? 'The config no longer makes this schema. `caracms schemas` removes it.' : change.before === null ? 'This schema file is missing. `caracms schemas` writes it.' : "This schema file is out of date with caracms.config.ts. `caracms schemas` rewrites it.",
+		});
+	}
+	return report;
+}
+
+const REFORMAT_MESSAGE = "This file isn't laid out the way the editor saves it (two-space JSON, a trailing newline), so the editor's next save would reformat it and mix the two. `caracms validate --fix` rewrites it the editor's way, changing no values.";
+
+/**
+ * MEC trial item 7: every content file the editor can open rewritten in the form a save
+ * writes (serialize.ts → savedForm), only whitespace changing. Returns the files changed.
+ */
+export async function reformatContent(site: Pick<ResolvedSite, 'root' | 'collections' | 'blocks'>): Promise<string[]> {
+	const changed: string[] = [];
+	for (const entry of await listDocuments(site)) {
+		if (entry.warning) continue;
+		const file = join(site.root, entry.file);
+		let text: string;
+		try {
+			text = readFileSync(file, 'utf8');
+		} catch {
+			continue;
+		}
+		const saved = savedForm(text, site.collections[entry.collection]!, site);
+		if (saved === null || saved === text) continue;
+		writeFileSync(file, saved);
+		changed.push(entry.file);
+	}
+	return changed;
+}
+
+const reformatReport = (files: readonly string[]) =>
+	files.length ? `caracms validate --fix:\n${files.map((f) => `  reformatted ${f} (as the editor saves it)`).join('\n')}\n` : '';
+
+const line = (f: Finding) => `${f.file}${f.path ? ` › ${f.path}` : ''}: ${f.message}`;
+
+/** The plain report: errors, then warnings, then a count. */
+export function formatReport(report: Report): string {
+	const parts: string[] = [];
+	if (report.errors.length) parts.push(`Errors:\n${report.errors.map((f) => `  ${line(f)}`).join('\n')}`);
+	if (report.warnings.length) parts.push(`Warnings:\n${report.warnings.map((f) => `  ${line(f)}`).join('\n')}`);
+	const count = (n: number, word: string) => `${n} ${word}${n === 1 ? '' : 's'}`;
+	parts.push(report.errors.length || report.warnings.length ? `caracms validate: ${count(report.errors.length, 'error')}, ${count(report.warnings.length, 'warning')}.` : 'caracms validate: no problems.');
+	return `${parts.join('\n\n')}\n`;
+}
+
+/** The command's entry (bin/caracms.mjs loads this module through the site's Vite). */
+export async function command(root: string, options: { fix?: boolean; json?: boolean } = {}): Promise<{ code: number; out: string; err?: string }> {
+	const site = await loadSite(root);
+	let fixed = '';
+	if (options.fix) fixed = schemasReport(await runSchemas(site)) + reformatReport(await reformatContent(site));
+	const report = await validateSite(site);
+	const code = report.errors.length ? 1 : 0;
+	if (options.json) return { code, out: `${JSON.stringify(report, null, 2)}\n`, err: options.fix ? fixed : undefined };
+	return { code, out: `${options.fix ? `${fixed}\n` : ''}${formatReport(report)}` };
+}

package/src/code-routes-disk.ts

@@ -0,0 +1,67 @@
+/**
+ * Reading the site's pages folder for its code routes (M8 Decision 10; code-routes.ts
+ * has the rules). Server-only. The integration passes Astro's own `srcDir`; `validate`,
+ * with no Astro running, reads it from the site's astro.config (`srcDirOf`).
+ */
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import { isAbsolute, join, relative, sep } from 'node:path';
+import { codeRoutesFrom, routeOf, type CodeRoute } from './code-routes.ts';
+
+const posix = (path: string) => path.split(sep).join('/');
+
+/** Every route under `<srcDir>/pages` (each one, collections' own included), in file order. */
+export function pagesRoutes(root: string, srcDir: string): CodeRoute[] {
+	const pages = join(isAbsolute(srcDir) ? srcDir : join(root, srcDir), 'pages');
+	const out: CodeRoute[] = [];
+	const walk = (dir: string) => {
+		let names: string[];
+		try {
+			names = readdirSync(dir).sort();
+		} catch {
+			return;
+		}
+		for (const name of names) {
+			if (name.startsWith('_') || name.startsWith('.')) continue;
+			const path = join(dir, name);
+			let isDir = false;
+			try {
+				isDir = statSync(path).isDirectory();
+			} catch {
+				continue;
+			}
+			if (isDir) walk(path);
+			else {
+				const route = routeOf(posix(relative(pages, path)), posix(relative(root, path)));
+				if (route) out.push(route);
+			}
+		}
+	};
+	walk(pages);
+	return out;
+}
+
+/** The routes that reserve URLs (the collections' own left out). */
+export function readCodeRoutes(root: string, srcDir: string, collections: readonly { urlBase: string | null }[]): CodeRoute[] {
+	return codeRoutesFrom(pagesRoutes(root, srcDir), collections);
+}
+
+export const ASTRO_CONFIG_FILES = ['astro.config.mjs', 'astro.config.ts', 'astro.config.mts', 'astro.config.js', 'astro.config.cjs', 'astro.config.cts'] as const;
+
+/**
+ * The site's `srcDir` as its astro.config writes it (`srcDir: './app'`), else `./src`,
+ * Astro's default. Read from the text: a computed value isn't seen (and `validate` says
+ * nothing about it), which is the price of needing no running Astro.
+ */
+export function srcDirOf(root: string): string {
+	for (const name of ASTRO_CONFIG_FILES) {
+		let text: string;
+		try {
+			text = readFileSync(join(root, name), 'utf8');
+		} catch {
+			continue;
+		}
+		const m = /\bsrcDir\s*:\s*(['"`])([^'"`]+)\1/.exec(text);
+		return m ? m[2]! : './src';
+	}
+	return './src';
+}