caracms 0.0.0-stage → 0.2.0

package/src/read.ts

@@ -0,0 +1,256 @@
+/**
+ * The render's read access to other documents (M5a Decision 9), and what a render
+ * needs to resolve: shared-block entries (Decision 8) and references (Decision 6).
+ *
+ * - **One source per render.** `documentReader(site, source)` reads through a
+ *   content.ts ContentSource: the disk at build (`main` as deployed), and in a
+ *   preview the editor's store with autosaves on top (the preview route hands its
+ *   store's source to the render through `Astro.locals`: `setRenderSource`). So a
+ *   preview never shows what the public page wouldn't once published, and both read
+ *   through the same parsing (content.ts).
+ * - **Per render, never module state:** a reader caches what it read for its own
+ *   render only, so a list block and a reference reading one collection read it once.
+ *   The exception is a production build on the disk source, where every reader shares
+ *   one cache (posts and tags, Decision 15: `shareBuildReads`).
+ * - **A reference to a document that doesn't exist reaches the component as `null`**
+ *   (Decision 6), in a list of references too (`[null, "tinder-press"]` keeps the
+ *   editor's indexes). `resolveRefs` does it, for a block's data and a fields
+ *   document's alike.
+ *
+ * Server-only (it reads files through content.ts).
+ */
+import { join } from 'node:path';
+import { DEFAULT_TITLE_SEPARATOR, type ResolvedSite } from './config.ts';
+import { DocumentError, diskSource, listDocuments, readDocument, type ContentSource } from './content.ts';
+import { own, parseFields, parseSettingsBrand, type DocumentBlock, type DocumentReader, type ReadEntry, type SharedDocument } from './document.ts';
+import { renderData, type Field, type Fields } from './fields.ts';
+import { renderMedia } from './media-value.ts';
+import { SITE_SETTINGS_FILE } from './reserved.ts';
+import { parseSeo } from './seo.ts';
+
+type Site = Pick<ResolvedSite, 'root' | 'collections' | 'blocks'> & Partial<Pick<ResolvedSite, 'titleSeparator'>>;
+
+const SOURCE = '__caracms_render_source';
+
+/** The preview route's source for this request's render (Decision 9). The build sets none: the disk. */
+export function setRenderSource(locals: object, source: ContentSource): void {
+	(locals as Record<string, unknown>)[SOURCE] = source;
+}
+
+/** The source this request's render reads other documents from: the preview's store, else the disk. */
+export function renderSourceOf(locals: object | undefined): ContentSource {
+	return ((locals as Record<string, unknown> | undefined)?.[SOURCE] as ContentSource | undefined) ?? diskSource;
+}
+
+/**
+ * Decision 15 (posts and tags): a production build reads each document once. The integration
+ * turns this on for `astro build` only (`astro:build:start`, off again at `astro:build:done`),
+ * on globalThis because the build's prerender runs a bundled copy of this module. Never in
+ * `astro dev`, where the disk-mode editor writes files between requests.
+ */
+const BUILD_READS = Symbol.for('caracms.buildReads');
+
+interface ReadCaches {
+	/** The source the reader reads through: in a build, the disk with each file's text and each folder's listing read once. */
+	source: ContentSource;
+	reads: Map<string, Promise<Awaited<ReturnType<typeof readDocument>> | null>>;
+	entries: Map<string, Promise<ReadEntry | null>>;
+	lists: Map<string, Promise<ReadEntry[]>>;
+}
+
+const newCaches = (source: ContentSource): ReadCaches => ({ source, reads: new Map(), entries: new Map(), lists: new Map() });
+
+/** A source that reads each file and lists each folder once (a listing and a document read the same file). */
+function onceSource(source: ContentSource): ContentSource {
+	const texts = new Map<string, Promise<string | null>>();
+	const lists = new Map<string, Promise<string[]>>();
+	const once = <T>(map: Map<string, Promise<T>>, key: string, read: () => Promise<T>) => {
+		let found = map.get(key);
+		if (!found) map.set(key, (found = read()));
+		return found;
+	};
+	return {
+		readText: (file) => once(texts, file, () => source.readText(file)),
+		listJson: (dir, recursive) => once(lists, `${recursive}\0${dir}`, () => source.listJson(dir, recursive)),
+	};
+}
+
+/** Share the disk's reads across every reader (on), or stop and forget them (off). Called by the integration's build hooks, and by tests. */
+export function shareBuildReads(on: boolean): void {
+	const g = globalThis as Record<symbol, unknown>;
+	if (on) g[BUILD_READS] = new Map<string, ReadCaches>();
+	else delete g[BUILD_READS];
+}
+
+/** The caches a reader uses: per site, shared across readers during a build on the disk source; else its own. */
+function cachesFor(site: Site, source: ContentSource): ReadCaches {
+	const shared = (globalThis as Record<symbol, unknown>)[BUILD_READS] as Map<string, ReadCaches> | undefined;
+	if (!shared || source !== diskSource) return newCaches(source);
+	let caches = shared.get(site.root);
+	if (!caches) shared.set(site.root, (caches = newCaches(onceSource(diskSource))));
+	return caches;
+}
+
+/**
+ * A reader over one source. Documents that can't be opened read as missing. Its reads are its
+ * own render's, except in a production build on the disk source, where every reader shares them
+ * (Decision 15: the disk doesn't change during a build).
+ */
+export function documentReader(site: Site, source: ContentSource): DocumentReader {
+	const caches = cachesFor(site, source);
+	const { reads, entries, lists } = caches;
+	source = caches.source;
+
+	/** The document as read, cached; no references resolved, so nothing here waits on another document. */
+	const raw = (collection: string, path: string) => {
+		const key = `${collection}\0${path}`;
+		let found = reads.get(key);
+		if (!found) {
+			found = readDocument(site, collection, path, source).catch((error: unknown) => {
+				if (error instanceof DocumentError) return null;
+				throw error;
+			});
+			reads.set(key, found);
+		}
+		return found;
+	};
+	const exists = async (collection: string, path: unknown) =>
+		typeof path === 'string' && path !== '' && !!own(site.collections, collection) && (await raw(collection, path)) !== null;
+
+	const reader: DocumentReader = {
+		document(collection, path) {
+			if (!own(site.collections, collection) || typeof path !== 'string' || path === '') return Promise.resolve(null);
+			const key = `${collection}\0${path}`;
+			let found = entries.get(key);
+			if (!found) {
+				found = raw(collection, path).then(async (read) => {
+					if (!read) return null;
+					const fields = own(site.collections, collection)!.fields ?? {};
+					// A fields document's fields; a section builder's page fields (M6c G2), when it has them.
+					const values = read.document.kind === 'fields' ? read.document.data : read.document.kind === undefined || read.document.kind === 'sections' ? read.document.data : undefined;
+					const data = values ? await resolveRefs(fields, renderData(fields, values), exists) : {};
+					return { collection, path, url: read.entry.url, title: read.entry.title, document: read.document, data };
+				});
+				entries.set(key, found);
+			}
+			return found;
+		},
+		documents(collection) {
+			if (!own(site.collections, collection)) return Promise.resolve([]);
+			let found = lists.get(collection);
+			if (!found) {
+				found = listDocuments(site, collection, source).then(async (listed) => {
+					// M9 Decision 7: a hidden page isn't on the site, so a listing of its collection leaves it out.
+					const read = await Promise.all(listed.filter((e) => !e.warning && !e.hidden).map((e) => reader.document(collection, e.path)));
+					return read.filter((r): r is ReadEntry => r !== null);
+				});
+				lists.set(collection, found);
+			}
+			return found;
+		},
+		exists: (collection, path) => exists(collection, path),
+	};
+	return reader;
+}
+
+/**
+ * Decision 14 (posts and tags): a route's reader on the disk, as `cms.read` gives a block, so
+ * `getStaticPaths` can count and filter documents by their fields. Shared across a production
+ * build, as every disk reader is. Exported from `caracms/content`.
+ */
+export function contentReader(site: Site): DocumentReader {
+	return documentReader(site, diskSource);
+}
+
+type Exists = (collection: string, path: unknown) => Promise<boolean>;
+
+/** A field's render value with references resolved: a missing one is null (Decision 6). */
+async function resolveValue(field: Field, value: unknown, exists: Exists): Promise<unknown> {
+	if (field.kind === 'reference') return (await exists(field.to, value)) ? value : null;
+	if (field.kind === 'list' && Array.isArray(value)) {
+		if (field.item) {
+			const item = field.item;
+			return Promise.all(value.map((v) => resolveValue(item, v, exists)));
+		}
+		const fields = field.fields ?? {};
+		return Promise.all(value.map((v) => (v && typeof v === 'object' ? resolveRefs(fields, v as Record<string, unknown>, exists) : v)));
+	}
+	if (field.kind === 'group' && value && typeof value === 'object' && !Array.isArray(value)) return resolveRefs(field.fields, value as Record<string, unknown>, exists);
+	return value;
+}
+
+/** Data with every reference to a missing document as null (Decision 6). */
+export async function resolveRefs(fields: Fields, data: Record<string, unknown>, exists: Exists): Promise<Record<string, unknown>> {
+	const out: Record<string, unknown> = { ...data };
+	for (const [key, field] of Object.entries(fields)) if (Object.hasOwn(data, key)) out[key] = await resolveValue(field, data[key], exists);
+	return out;
+}
+
+/** A block's or a fields document's parsed data as its component gets it: renderData, with missing references as null. */
+export function renderFields(fields: Fields, data: Record<string, unknown>, reader: DocumentReader): Promise<Record<string, unknown>> {
+	return resolveRefs(fields, renderData(fields, data), reader.exists);
+}
+
+/**
+ * M7 Decision 13: Site Settings as the page component gets it (document.ts → PageProps
+ * `settings`), read from the render's source (the disk at build, the editor's store in a
+ * preview, as Head reads it). The site's own `settings: { fields }` as a block's render data
+ * (links as render values, media resolved, a reference to a missing document as null),
+ * plus the package's `brand` (`name`, `logo`, `icon`) and `seo` (`title`, `description`,
+ * `image`, and the config's `titleSeparator`, so a code route can build its title as head.ts
+ * does: `${title}${seo.titleSeparator}${brand.name}`). `brand.name` is the site's name: Site Settings' brand name, else the default
+ * search title, else "Site" (as head.ts names the site). Never `editors`, `formRecipients`
+ * or `googleTag`, nor the document's own `title`. Never throws on content: a missing or
+ * broken file reads as empty.
+ */
+export async function settingsRenderData(site: Site, source: ContentSource, reader: DocumentReader = documentReader(site, source)): Promise<Record<string, unknown>> {
+	let raw: Record<string, unknown> = {};
+	try {
+		const text = await source.readText(join(site.root, SITE_SETTINGS_FILE));
+		const parsed = text ? (JSON.parse(text) as unknown) : null;
+		if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) raw = parsed as Record<string, unknown>;
+	} catch {
+		/* unreadable: the site's fields at their empty values, the name "Site" */
+	}
+	const fields = own(site.collections, 'settings')?.fields ?? {};
+	const data = await renderFields(fields, parseFields(fields, raw), reader);
+	const brand = parseSettingsBrand(raw.brand);
+	const seo = parseSeo(raw.seo);
+	return {
+		...data,
+		brand: { name: brand.name || seo.title || 'Site', logo: renderMedia(brand.logo, { only: 'image' }), icon: renderMedia(brand.icon, { only: 'image' }) },
+		seo: { title: seo.title ?? '', description: seo.description ?? '', image: renderMedia(seo.image ?? null, { only: 'image' }), titleSeparator: site.titleSeparator ?? DEFAULT_TITLE_SEPARATOR },
+	};
+}
+
+/**
+ * M8 trial (item 1): Site Settings for the site's own `.astro` routes, exactly as the page
+ * component gets `Astro.props.settings` (settingsRenderData: rich text parsed, media
+ * resolved, links as render values, `brand` and `seo`). Exported from `caracms/content`:
+ *
+ *   import { siteSettings } from 'caracms/content';
+ *   import { site } from 'virtual:caracms/config';
+ *   const settings = await siteSettings(site, Astro.locals);
+ *
+ * Read from the render's source (`locals`, as RenderDocument reads it): the disk, as deployed,
+ * unless an editor's preview set its store. `locals` may be left out (the disk).
+ */
+export function siteSettings(site: Site, locals?: object): Promise<Record<string, unknown>> {
+	return settingsRenderData(site, renderSourceOf(locals));
+}
+
+/** Why a shared-block entry doesn't render (Decision 8), or null when it does. */
+export type SharedSkip = 'missing' | 'unknown-type';
+
+/**
+ * A page's shared entry resolved from the render's source: the shared block's block
+ * (`source` as the entry's, so markers are the page's index), or why it's skipped:
+ * the shared block doesn't exist (or can't be opened), or its type isn't in the code.
+ */
+export async function resolveShared(entry: DocumentBlock, reader: DocumentReader): Promise<{ block: DocumentBlock } | { skip: SharedSkip; type: string }> {
+	const found = entry.shared ? await reader.document('shared', entry.shared) : null;
+	if (!found || found.document.kind !== 'shared') return { skip: 'missing', type: '' };
+	const block = (found.document as SharedDocument).block;
+	if (!block.known) return { skip: 'unknown-type', type: block.type };
+	return { block: { ...block, source: entry.source } };
+}

package/src/redirect-middleware.ts

@@ -0,0 +1,49 @@
+/**
+ * Site Settings' redirects, served (pre-M7 item 8): a public GET or HEAD that would be
+ * a 404 and matches a redirect's `from` is answered 301 to its `to`, the query kept.
+ * **A real page always wins**: the redirect is only looked at once the site has
+ * answered 404, so a page made at an old address is served, redirect or not.
+ *
+ * - **Read from the file the public site is built from**, the site's own
+ *   `content/site-settings.json` (local mode: the file the editor writes; a production
+ *   server: `main` as built), never live mode's drafts: a redirect added by a move
+ *   goes out with the Publish that moves the page. Re-read when the file changes
+ *   (its modification time), so local edits apply at once.
+ * - The editor's own paths (`/admin`, `/_caracms/`) are never redirected.
+ */
+import { readFile, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import type { MiddlewareHandler } from 'astro';
+import { site } from 'virtual:caracms/config';
+import { SITE_SETTINGS_FILE } from './reserved.ts';
+import { parseRedirects, redirectFor, type Redirect } from './redirects.ts';
+
+let kept: { mtimeMs: number; list: Redirect[] } | null = null;
+
+/** The redirects in the site's Site Settings file, re-read when it changes. Empty when it's missing or unreadable. */
+export async function siteRedirects(root: string): Promise<Redirect[]> {
+	const file = join(root, SITE_SETTINGS_FILE);
+	const info = await stat(file).catch(() => null);
+	if (!info) return [];
+	if (kept && kept.mtimeMs === info.mtimeMs) return kept.list;
+	let list: Redirect[] = [];
+	try {
+		list = parseRedirects((JSON.parse(await readFile(file, 'utf8')) as { redirects?: unknown }).redirects);
+	} catch {
+		list = [];
+	}
+	kept = { mtimeMs: info.mtimeMs, list };
+	return list;
+}
+
+const editorPath = (pathname: string) => pathname === '/admin' || pathname.startsWith('/admin/') || pathname.startsWith('/_caracms/');
+
+export const onRequest: MiddlewareHandler = async (context, next) => {
+	const { request, url } = context;
+	if ((request.method !== 'GET' && request.method !== 'HEAD') || editorPath(url.pathname)) return next();
+	const response = await next();
+	if (response.status !== 404) return response;
+	const to = redirectFor(await siteRedirects(site.root), url.pathname);
+	if (!to) return response;
+	return new Response(null, { status: 301, headers: { Location: `${to}${url.search}`, 'Cache-Control': 'no-cache' } });
+};

package/src/redirects.ts

@@ -0,0 +1,76 @@
+/**
+ * Redirects (pre-M7 item 8): Site Settings' `redirects`, a list of `{ from, to }`
+ * site addresses. Changing a document's address adds one, from the old address to
+ * the new; the package serves them as 301s on the public site (redirect-middleware.ts).
+ * Browser-safe (no imports beyond links.ts): the Redirects section reads them too.
+ *
+ *   parseRedirects(raw)                        the list as the file holds it, cleaned
+ *   redirectsAfterMove(list, from, to, add)    the list once a document moves
+ *   redirectFor(list, pathname)                where a request for `pathname` goes, or null
+ *
+ * - **Both ends are `/paths`**, without a trailing slash (`/` stays `/`). An entry that
+ *   isn't, or that goes nowhere (`from` = `to`), is dropped; so is a second entry for
+ *   the same `from` (the first wins).
+ * - **Chains collapse** when a document moves: every entry that went to its old
+ *   address goes to the new one, so `/a → /b` then `/b → /c` is `/a → /c` and
+ *   `/b → /c`, never two hops.
+ * - **A real page wins**: an entry whose `from` is the moved document's new address
+ *   is dropped (its page is back). The server also checks: it only redirects a
+ *   request that would otherwise be a 404.
+ */
+import { normaliseAddress } from './links.ts';
+
+export interface Redirect {
+	from: string;
+	to: string;
+}
+
+/** A site address as a redirect holds it: `/path`, no trailing slash, no query or anchor. Null when it isn't one. */
+export function redirectAddress(value: unknown): string | null {
+	if (typeof value !== 'string') return null;
+	const v = value.trim();
+	if (!/^\/(?!\/)[^\s?#]*$/.test(v)) return null;
+	return normaliseAddress(v);
+}
+
+const same = (a: string, b: string) => a.toLowerCase() === b.toLowerCase();
+
+/** The list as the file holds it: entries that aren't two addresses, go nowhere, or repeat a `from` are dropped. */
+export function parseRedirects(raw: unknown): Redirect[] {
+	if (!Array.isArray(raw)) return [];
+	const out: Redirect[] = [];
+	for (const entry of raw) {
+		if (!entry || typeof entry !== 'object' || Array.isArray(entry)) continue;
+		const from = redirectAddress((entry as Record<string, unknown>).from);
+		const to = redirectAddress((entry as Record<string, unknown>).to);
+		if (!from || !to || same(from, to) || out.some((r) => same(r.from, from))) continue;
+		out.push({ from, to });
+	}
+	return out;
+}
+
+/**
+ * The list once a document moves from `from` to `to` (both its public addresses):
+ * entries to `from` go to `to` (chains collapse), an entry from `to` goes (a page is
+ * there now), and, when `add`, `from → to` is added (replacing any entry from `from`).
+ * `add` is false for a document that was never live (made since the last Publish).
+ */
+export function redirectsAfterMove(list: readonly Redirect[], from: string, to: string, add: boolean): Redirect[] {
+	const next = list
+		.filter((r) => !same(r.from, to) && !(add && same(r.from, from)))
+		.map((r) => (same(r.to, from) ? { from: r.from, to } : r))
+		.filter((r) => !same(r.from, r.to));
+	if (add && !same(from, to)) next.push({ from, to });
+	return next;
+}
+
+/** Where a request for `pathname` goes, or null. Matched without a trailing slash; letter case counts, as it does for pages. */
+export function redirectFor(list: readonly Redirect[], pathname: string): string | null {
+	let path: string;
+	try {
+		path = normaliseAddress(decodeURI(pathname));
+	} catch {
+		path = normaliseAddress(pathname);
+	}
+	return list.find((r) => r.from === path)?.to ?? null;
+}

package/src/relink.ts

@@ -0,0 +1,293 @@
+/**
+ * Rewriting links when a document's address changes (pre-M7 item 8): one document's
+ * file text in, the same text out with every link to the old address pointing at the
+ * new one. **Only those strings change**: the rest of the file is its own text, byte
+ * for byte (the change is spliced in, as serialize.ts splices an edited key).
+ *
+ What counts as a link to the old address is found **by the schema** (block types by
+ * their `type`, lists by index), so only real links change, never a text that happens
+ * to read the same, nor a key the schema doesn't know:
+ *
+ * - **A link field's or a button's `href`** that is a `/path` to it: `/studio/visit`,
+ *   `/studio/visit/`, `/studio/visit#hours`, `/studio/visit?x=1`. The path is swapped;
+ *   a trailing slash, query or anchor stays.
+ * - **Rich text's links** (`[text](/studio/visit)`, rich-text.ts's on-disk form), with
+ *   the same rule for the href and its escapes kept.
+ * - **A reference** to the document (`reference({ to })`, stored as its path in its
+ *   collection, M5a Decision 6).
+ *
+ * Shared-block uses (`{ "shared": "footer" }`) never change: a shared block has no
+ * address, so it never moves. Site Settings' own `redirects` are the caller's
+ * (redirects.ts), never rewritten here. A file that isn't valid JSON is left as it is.
+ *
+ * M6c G4: the same walk finds and rewrites **links to files** (`/files/…`, caracms/files):
+ * `fileLinksIn` lists a text's file links by schema (the library's "linked from",
+ * Decision 8), and `refileText` points every link to one file at another (Replace…,
+ * Decision 9), `?download` and a fragment kept. A plain-text mention of an address is
+ * never a link: only link fields, buttons and rich text count.
+ */
+import type { ResolvedCollection, ResolvedSite } from './config.ts';
+import { own } from './document.ts';
+import type { Field } from './fields.ts';
+import { fileAddress, fileKeyOf } from './files.ts';
+import { internalLinkPath, normaliseAddress } from './links.ts';
+import { parseSource, type JsonNode } from './json-source.ts';
+
+export interface AddressMove {
+	/** The document's collection. */
+	collection: string;
+	/** Its path in the collection, before and after. */
+	fromPath: string;
+	toPath: string;
+	/** Its public address, before and after (`/studio/visit`). */
+	fromUrl: string;
+	toUrl: string;
+}
+
+type Segment = string | number;
+
+/** An href pointing at the old address, pointed at the new one; null when it doesn't point there. */
+export function relinkHref(href: string, move: Pick<AddressMove, 'fromUrl' | 'toUrl'>): string | null {
+	const path = internalLinkPath(href);
+	if (path === null || path !== normaliseAddress(move.fromUrl)) return null;
+	const typed = href.trim();
+	const pathPart = typed.replace(/[?#].*$/, '');
+	const rest = typed.slice(pathPart.length);
+	// A trailing slash as typed stays (`/studio/visit/` → `/visit/`), except on `/`.
+	const slash = pathPart.length > 1 && pathPart.endsWith('/') && move.toUrl !== '/';
+	return `${move.toUrl}${slash ? '/' : ''}${rest}`;
+}
+
+/** Rich text's `](href)`: the href runs to the first unescaped `)`, with `\` and `)` escaped inside it. */
+const MARKDOWN_HREF = /\]\(((?:\\[\\)]|[^\\)])*)\)/g;
+
+/** Rewrites one href: the new one, or null to leave it. */
+type HrefRewrite = (href: string) => string | null;
+
+/** A rich-text string's hrefs, unescaped, in order. */
+export function richTextHrefs(value: string): string[] {
+	if (!value.includes('](')) return [];
+	return [...value.matchAll(MARKDOWN_HREF)].map((m) => m[1]!.replace(/\\([\\)])/g, '$1'));
+}
+
+/** A rich-text string with `rewrite` applied to each link, its escapes kept; null when none changed. */
+function rewriteRichText(value: string, rewrite: HrefRewrite): { text: string; links: number } | null {
+	if (!value.includes('](')) return null;
+	let links = 0;
+	const out = value.replace(MARKDOWN_HREF, (whole, escaped: string) => {
+		const href = escaped.replace(/\\([\\)])/g, '$1');
+		const next = rewrite(href);
+		if (next === null || next === href) return whole;
+		links++;
+		return `](${next.replace(/[\\)]/g, '\\$&')})`;
+	});
+	return links ? { text: out, links } : null;
+}
+
+/** A string with its rich-text links to the old address rewritten; null when none were. */
+export function relinkRichText(value: string, move: Pick<AddressMove, 'fromUrl' | 'toUrl'>): string | null {
+	return rewriteRichText(value, (href) => relinkHref(href, move))?.text ?? null;
+}
+
+/**
+ * The field a value in the file belongs to, by its path from the file's root (blocks by
+ * their `type`, into lists by index), with the rest of the path inside the field's
+ * value (`['href']` in a link, `[0, 'href']` in buttons); null where the schema has none.
+ */
+function fieldAt(site: Pick<ResolvedSite, 'blocks'>, collection: Pick<ResolvedCollection, 'kind' | 'fields'>, raw: unknown, path: Segment[]): { field: Field; rest: Segment[] } | null {
+	const obj = (v: unknown) => (v && typeof v === 'object' && !Array.isArray(v) ? (v as Record<string, unknown>) : null);
+	const blockField = (block: unknown, key: Segment | undefined) => {
+		const type = obj(block)?.type;
+		const config = typeof type === 'string' ? own(site.blocks, type) : undefined;
+		return typeof key === 'string' && config ? (own(config.fields, key) ?? null) : null;
+	};
+	let field: Field | null;
+	let rest: Segment[];
+	switch (collection.kind) {
+		case 'sections': {
+			// M6c (G2): a page field, a top-level key beside the blocks.
+			if (typeof path[0] === 'string' && path[0] !== 'blocks') {
+				field = path[0] !== 'seo' ? (own(collection.fields ?? {}, path[0]) ?? null) : null;
+				rest = path.slice(1);
+				break;
+			}
+			if (path[0] !== 'blocks' || typeof path[1] !== 'number') return null;
+			const blocks = obj(raw)?.blocks;
+			field = blockField(Array.isArray(blocks) ? blocks[path[1]] : null, path[2]);
+			rest = path.slice(3);
+			break;
+		}
+		case 'shared':
+			if (path[0] !== 'block') return null;
+			field = blockField(obj(raw)?.block, path[1]);
+			rest = path.slice(2);
+			break;
+		default:
+			field = typeof path[0] === 'string' ? (own(collection.fields ?? {}, path[0]) ?? null) : null;
+			rest = path.slice(1);
+	}
+	// Into lists (an index, then, a list of several fields, the item's key) and groups (a key).
+	while (field && (field.kind === 'list' || field.kind === 'group') && rest.length) {
+		if (field.kind === 'group') {
+			field = typeof rest[0] === 'string' ? (own(field.fields, rest[0]) ?? null) : null;
+			rest = rest.slice(1);
+			continue;
+		}
+		if (typeof rest[0] !== 'number') return null;
+		if (field.item) {
+			field = field.item;
+			rest = rest.slice(1);
+		} else {
+			field = typeof rest[1] === 'string' ? (own(field.fields ?? {}, rest[1]) ?? null) : null;
+			rest = rest.slice(2);
+		}
+	}
+	return field ? { field, rest } : null;
+}
+
+/** A string at `rest` inside a field's value, with its links to the old address rewritten; null when it isn't a link there or doesn't point there. */
+function relinkIn(field: Field, rest: Segment[], value: string, move: AddressMove): string | null {
+	switch (field.kind) {
+		case 'link':
+			return rest.length === 1 && rest[0] === 'href' ? relinkHref(value, move) : null;
+		case 'buttons':
+			return rest.length === 2 && typeof rest[0] === 'number' && rest[1] === 'href' ? relinkHref(value, move) : null;
+		case 'richText':
+			return relinkRichText(value, move);
+		case 'reference':
+			return rest.length === 0 && field.to === move.collection && value.trim() === move.fromPath ? move.toPath : null;
+		default:
+			return null;
+	}
+}
+
+/**
+ * Every string in the file that the schema places in a field, depth first in file order,
+ * with that field and the rest of the path inside its value. Site Settings' `redirects`
+ * are skipped (redirects.ts's own). Null when the text isn't JSON.
+ */
+function fieldStrings(
+	text: string,
+	site: Pick<ResolvedSite, 'blocks'>,
+	collection: Pick<ResolvedCollection, 'kind' | 'fields'>,
+	visit: (field: Field, rest: Segment[], value: string, node: { start: number; end: number }) => void,
+): boolean {
+	let source;
+	try {
+		source = parseSource(text);
+	} catch {
+		return false;
+	}
+	const walk = (node: JsonNode, path: Segment[]) => {
+		if (node.kind === 'object') {
+			for (const m of node.members) {
+				// Site Settings' redirects are redirects.ts's to change, never a link to rewrite.
+				if (collection.kind === 'settings' && path.length === 0 && m.key === 'redirects') continue;
+				walk(m.value, [...path, m.key]);
+			}
+			return;
+		}
+		if (node.kind === 'array') {
+			node.items.forEach((item, i) => walk(item, [...path, i]));
+			return;
+		}
+		if (typeof node.value !== 'string') return;
+		const at = fieldAt(site, collection, source.value, path);
+		if (at) visit(at.field, at.rest, node.value, node);
+	};
+	walk(source.root, []);
+	return true;
+}
+
+/** A string's links where it sits in its field: a link's or a button's href, or rich text's hrefs. */
+function hrefsAt(field: Field, rest: Segment[], value: string): 'href' | 'rich' | null {
+	if (field.kind === 'link') return rest.length === 1 && rest[0] === 'href' ? 'href' : null;
+	if (field.kind === 'buttons') return rest.length === 2 && typeof rest[0] === 'number' && rest[1] === 'href' ? 'href' : null;
+	if (field.kind === 'richText') return value.includes('](') ? 'rich' : null;
+	return null;
+}
+
+/** Splice edits into a text, latest first. */
+function splice(text: string, edits: { start: number; end: number; text: string }[]): string {
+	let out = text;
+	for (const e of edits.sort((a, b) => b.start - a.start)) out = out.slice(0, e.start) + e.text + out.slice(e.end);
+	return out;
+}
+
+/**
+ * The file's text with every link and reference to the moved document pointing at
+ * its new address (or path); `text` itself when nothing points there. `collection` is
+ * the file's own collection (for its schema).
+ */
+export function relinkText(
+	text: string,
+	move: AddressMove,
+	site: Pick<ResolvedSite, 'blocks'>,
+	collection: Pick<ResolvedCollection, 'kind' | 'fields'>,
+): { text: string; links: number } {
+	const edits: { start: number; end: number; text: string }[] = [];
+	const ok = fieldStrings(text, site, collection, (field, rest, value, node) => {
+		const next = relinkIn(field, rest, value, move);
+		if (next !== null && next !== value) edits.push({ start: node.start, end: node.end, text: JSON.stringify(next) });
+	});
+	if (!ok || edits.length === 0) return { text, links: 0 };
+	return { text: splice(text, edits), links: edits.length };
+}
+
+/**
+ * M6c G4: every file link in the file's text, by schema (link fields, buttons, rich text),
+ * as the key and download flag `fileKeyOf` reads, in file order. A text that isn't JSON has none.
+ */
+export function fileLinksIn(text: string, site: Pick<ResolvedSite, 'blocks'>, collection: Pick<ResolvedCollection, 'kind' | 'fields'>): { key: string; download: boolean }[] {
+	const out: { key: string; download: boolean }[] = [];
+	fieldStrings(text, site, collection, (field, rest, value) => {
+		const how = hrefsAt(field, rest, value);
+		const hrefs = how === 'href' ? [value] : how === 'rich' ? richTextHrefs(value) : [];
+		for (const href of hrefs) {
+			const file = fileKeyOf(href.trim());
+			if (file) out.push(file);
+		}
+	});
+	return out;
+}
+
+/** A link to the file `from` pointed at `to`, `?download` and a fragment kept; null when it isn't a link to `from`. */
+export function refileHref(href: string, from: string, to: string): string | null {
+	const typed = href.trim();
+	const file = fileKeyOf(typed);
+	if (!file || file.key !== from) return null;
+	const hash = typed.indexOf('#');
+	return `${fileAddress(to, { download: file.download })}${hash === -1 ? '' : typed.slice(hash)}`;
+}
+
+/**
+ * M6c G4 (Replace…, Decision 9): the file's text with every link to the file `from` (a
+ * key) pointing at `to`, by schema, spliced in as relinkText does; `links` counts the
+ * links rewritten (a rich text holding two counts two).
+ */
+export function refileText(
+	text: string,
+	from: string,
+	to: string,
+	site: Pick<ResolvedSite, 'blocks'>,
+	collection: Pick<ResolvedCollection, 'kind' | 'fields'>,
+): { text: string; links: number } {
+	const edits: { start: number; end: number; text: string }[] = [];
+	let links = 0;
+	const ok = fieldStrings(text, site, collection, (field, rest, value, node) => {
+		const how = hrefsAt(field, rest, value);
+		if (how === 'href') {
+			const next = refileHref(value, from, to);
+			if (next === null) return;
+			links++;
+			edits.push({ start: node.start, end: node.end, text: JSON.stringify(next) });
+		} else if (how === 'rich') {
+			const next = rewriteRichText(value, (href) => refileHref(href, from, to));
+			if (!next) return;
+			links += next.links;
+			edits.push({ start: node.start, end: node.end, text: JSON.stringify(next.text) });
+		}
+	});
+	if (!ok || edits.length === 0) return { text, links: 0 };
+	return { text: splice(text, edits), links };
+}