@apleasantview/eleventy-plugin-baseline 0.1.0-next.40 → 0.1.0-next.42

package/README.md

@@ -2,24 +2,16 @@
 
 Baseline makes the structural decisions that Eleventy leaves open: directory layout, asset pipeline, image handling, SEO, sitemaps.
 
-If you've started a new Eleventy project and found yourself wiring up the same things for the third time, this is for you. Directory structure, template engine, image formats, meta tags, asset bundling, sitemap — decisions that are individually small but collectively slow you down. Baseline makes them together, so they fit together. You get to skip the setup and start building.
+If you've started a new Eleventy project and found yourself wiring up the same things for the third time, this is for you. Directory structure, template engine, image formats, meta tags, asset bundling, sitemap – decisions that are individually small but collectively slow you down. Baseline makes them together, so they fit together. You get to skip the setup and start building.
 
-You still own your site. Baseline handles the infrastructure — the parts that have well-tested answers. Your design, your content, the things that make your site yours — those stay yours.
+You still own your site. Baseline handles the infrastructure – the parts that have well-tested answers. Your design, your content, the things that make your site yours – those stay yours.
 
 This is a working plugin, not a finished product. Things might shift, break, or get renamed.
 
 ## Install
 
-If you already have Eleventy and eleventy-img installed:
-
-```bash
-npm install @apleasantview/eleventy-plugin-baseline
-```
-
-For a fresh project (install Eleventy and eleventy-img too):
-
 ```bash
-npm install @11ty/eleventy @11ty/eleventy-img @apleasantview/eleventy-plugin-baseline
+npm install @11ty/eleventy @apleasantview/eleventy-plugin-baseline @11ty/eleventy-img
 ```
 
 Requires Eleventy 3.x and Node >=20.
@@ -30,33 +22,36 @@ Add the plugin and re-export the config. The config export sets the directory st
 
 ```js
 import baseline, { config as baselineConfig } from '@apleasantview/eleventy-plugin-baseline';
+import settings from './src/_data/settings.js';
 
-export default function (eleventyConfig) {
-	eleventyConfig.addPlugin(baseline());
+export default async function (eleventyConfig) {
+	await eleventyConfig.addPlugin(baseline(settings, {}));
 }
 
 export const config = baselineConfig;
 ```
 
-The plugin takes two arguments: `settings` (site identity — title, url, languages, head extras) and `options` (runtime behavior — verbose, sitemap, navigator).
+`baseline()` returns an async closure (Eleventy's documented async-plugin pattern), so the call to `addPlugin` is awaited.
+
+The plugin takes two arguments: `settings` (site identity – title, url, languages, head extras, SEO defaults) and `options` (runtime behavior – verbose, sitemap, navigator).
 
 ```js
 const settings = {
 	title: 'My Site',
 	tagline: 'Built with Baseline',
 	url: 'https://www.example.com/',
-	defaultLanguage: 'en',
+	defaultLocale: 'en-US',
 	languages: {
 		en: { title: 'My Site' },
 		nl: { title: 'Mijn Site' }
 	}
 };
 
-eleventyConfig.addPlugin(
+await eleventyConfig.addPlugin(
 	baseline(settings, {
-		verbose: false, // extra logging during builds
-		sitemap: true, // XML sitemap generation
-		navigator: false // debug page for inspecting template data
+		verbose: true, // build-narrative logging (default: true)
+		sitemap: true, // XML sitemap generation (default: true)
+		navigator: false // debug page for inspecting template data (default: on in development)
 	})
 );
 ```
@@ -65,28 +60,31 @@ eleventyConfig.addPlugin(
 
 The plugin registers everything on load. No setup beyond the config above.
 
-**Core** — always active:
+**Core** – always active:
 
-- An image shortcode (via eleventy-img) — AVIF and WebP, responsive widths, lazy loading. Alt text is required — the build warns if you skip it.
+- An image shortcode (via eleventy-img) – AVIF and WebP, responsive widths, lazy loading. Alt text is required – the build warns if you skip it.
+- Wikilinks in Markdown – `[[slug]]`, `[[slug:lang]]`, `[[slug#anchor]]`, `[[slug|alias]]`, combinable. Forward links only.
+- Auto heading IDs – every heading gets a stable slugified `id` with WordPress-style dedup; manual `{#id}` always wins.
+- Element attributes in Markdown – `{#id .class key="value"}` syntax attaches attributes to any block element (via `markdown-it-attrs`).
 - Filters: `markdownify`, `relatedPosts`, `isString`
 - A date-formatting global
-- Drafts preprocessor — drafts stay out of production builds automatically
+- Drafts preprocessor – drafts stay out of production builds automatically
 - Static passthrough (`src/static/` → site root)
 
-**Modules** — opt-in, loaded individually:
+**Modules** – `head` and `assets` are always on; `sitemap` is on by default; `navigator` is on in development; `multilang` is opt-in.
 
-| Module      | What it does                                                                                                                                                                        |
-| ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `assets`    | The asset pipeline. One entry point per directory (`index.css`, `index.js`). Bundles JS via esbuild and processes CSS via PostCSS. Inline filters (`inlinePostCSS`, `inlineESbuild`) for critical-path assets |
-| `head`      | `<head>` tags (charset, viewport, title, description, robots, canonical, hreflang) handled for you by dropping `<baseline-head>` in your layout                                     |
-| `multilang` | Directory-based multilingual support. Per-language collections, translation mapping, i18n filters. Wraps Eleventy's I18n plugin                                                     |
-| `navigator` | Debug tooling. Globals for inspecting template data, plus debug filters (`_inspect`, `_json`, `_keys`). Optional virtual debug page                                                 |
-| `sitemap`   | XML sitemap. Every page is included unless you exclude it. Multilingual sites get per-language sitemaps plus an index                                                               |
+| Module      | What it does                                                                                                                                                                                                                             |
+| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `assets`    | The asset pipeline. One entry point per directory (`index.css`, `index.js`). Bundles JS via esbuild and processes CSS via PostCSS. Inline filters (`inlinePostCSS`, `inlineESbuild`) for critical-path assets                            |
+| `head`      | `<head>` tags handled for you by dropping `<baseline-head>` in your layout: charset, viewport, title, description, robots, canonical, hreflang, plus a full SEO payload (Open Graph, Twitter Cards, and a JSON-LD structured-data graph) |
+| `multilang` | Directory-based multilingual support. Per-language collections, translation mapping, i18n filters. Wraps Eleventy's I18n plugin                                                                                                          |
+| `navigator` | The content-graph read surface (`_navigator`: nodes, edges, backlinks), plus debug tooling: globals for inspecting template data, debug filters (`_inspect`, `_json`, `_keys`), and an optional virtual debug page                       |
+| `sitemap`   | XML sitemap. Every page is included unless you exclude it. Multilingual sites get per-language sitemaps plus an index                                                                                                                    |
 
 ## Docs
 
-Full documentation — tutorials, how-to guides, and reference — lives at:
-[https://eleventy-plugin-baseline.netlify.app/](https://eleventy-plugin-baseline.netlify.app/)
+Full documentation – tutorials, how-to guides, and reference – lives at:
+[https://www.eleventy-baseline.dev/](https://www.eleventy-baseline.dev/)
 
 ## Contributing
 

package/core/back-compat/options.js

@@ -0,0 +1,69 @@
+/**
+ * Back-compat: legacy options shape (composition root helper)
+ *
+ * The original plugin API accepted a single merged configuration object.
+ * The current contract splits site identity (`settings`) from runtime
+ * behaviour (`options`). This shim detects the old shape and converts it.
+ *
+ * Architecture layer:
+ *   composition root (back-compat helper)
+ *
+ * System role:
+ *   Pure shape detection and normalisation. Lets the entry point accept
+ *   either the legacy single-object form or the current two-arg form
+ *   without conditional logic at every read site.
+ *
+ * Why this exists:
+ *   Past-me changed the plugin's input contract. This file keeps that
+ *   change non-breaking for anyone (including past-me) still on the old
+ *   shape. Removable once nobody's calling baseline() with a single object.
+ *
+ * Scope:
+ *   Owns the legacy-key whitelist, shape detection, and the split into
+ *   the canonical pair. Does not log; the caller decides whether and how
+ *   to surface the deprecation.
+ *
+ * Data flow:
+ *   legacy-shaped object → { settings, options }
+ */
+
+export const LEGACY_OPTION_KEYS = [
+	'verbose',
+	'enableNavigatorTemplate',
+	'enableSitemapTemplate',
+	'assetsESBuild',
+	'multilingual'
+];
+
+/**
+ * Detect the legacy single-object plugin invocation.
+ *
+ * NOTE: arguments.length is required because default parameters mask arity.
+ *
+ * @param {unknown} firstArg
+ * @param {number} argsLength
+ * @returns {boolean}
+ */
+export function isLegacyShape(firstArg, argsLength) {
+	if (argsLength >= 2) return false;
+	if (!firstArg || typeof firstArg !== 'object') return false;
+	return LEGACY_OPTION_KEYS.some((key) => key in firstArg);
+}
+
+/**
+ * Convert a legacy single-object input into the current (settings, options)
+ * pair.
+ *
+ * - settings → site identity (content + SEO concerns)
+ * - options  → runtime behaviour flags
+ *
+ * @param {object} legacy
+ * @returns {{ settings: object, options: object }}
+ */
+export function normalizeLegacyShape(legacy) {
+	const { defaultLanguage, languages, ...rest } = legacy;
+	return {
+		settings: { defaultLanguage, languages },
+		options: rest
+	};
+}

package/core/content-graph/backlinks.js

@@ -0,0 +1,65 @@
+/**
+ * Backlink index (runtime substrate)
+ *
+ * Inverts the per-page outbound links into a target-keyed lookup. Built
+ * once at graph time so accessor reads are a hash lookup, not a scan
+ * over every page.
+ *
+ * Architecture layer:
+ *   runtime substrate
+ *
+ * System role:
+ *   Cross-page index built alongside the per-page records. Lives outside
+ *   the per-page extractors because A's backlinks can only be known
+ *   after walking B, C, D's outgoing links.
+ *
+ * Lifecycle:
+ *   build-time → buildGraph calls this once over the records map
+ *
+ * Why this exists:
+ *   Eleventy has no notion of inverse references. Templates that want
+ *   to render "what links here" need this index built up front.
+ *
+ * Scope:
+ *   Owns the inversion logic and fragment-stripping rule (so /foo/#x
+ *   folds into /foo/).
+ *   Does not own outbound link extraction (extractors.js) or how the
+ *   index is exposed to templates (graph.js / index.js).
+ *
+ * Data flow:
+ *   per-page records → inverted lookup keyed by target url
+ */
+
+/**
+ * @param {Record<string, { links: Array<{ href: string, internal: boolean }>, excerpt?: string }>} nodes
+ * @param {Record<string, { title?: string }>} [sourceMeta] - Per-source metadata to enrich entries with.
+ * @returns {Record<string, Array<{ url: string, title?: string, excerpt?: string }>>}
+ */
+export function buildBacklinkIndex(edges, nodes = {}, sourceMeta = {}) {
+	const index = {};
+	const seen = {};
+
+	for (const edge of edges) {
+		if (!edge.internal) continue;
+		if (!edge.to || !edge.from) continue;
+
+		// Strip fragments so /foo/#section folds into /foo/
+		const target = edge.to.split('#')[0];
+
+		if (!index[target]) {
+			index[target] = [];
+			seen[target] = new Set();
+		}
+
+		if (seen[target].has(edge.from)) continue;
+		seen[target].add(edge.from);
+
+		index[target].push({
+			url: edge.from,
+			title: sourceMeta[edge.from]?.title || nodes[edge.from]?.title,
+			excerpt: nodes[edge.from]?.excerpt
+		});
+	}
+
+	return index;
+}

package/core/content-graph/extractors.js

@@ -0,0 +1,185 @@
+import { slugify } from '../utils/slugify.js';
+
+/**
+ * Extractors (runtime substrate)
+ *
+ * Pulls structured records out of a rendered HTML document. One pure
+ * function per concern (headings, links, images, excerpt) plus the
+ * boundary rule that decides which root the page-level extract reads.
+ *
+ * Architecture layer:
+ *   runtime substrate
+ *
+ * System role:
+ *   The fixed v1 extractor set called by the graph builder. Side-effect
+ *   free; one document in, one record out.
+ *
+ * Lifecycle:
+ *   build-time → buildGraph parses each page and calls extractGraph
+ *
+ * Why this exists:
+ *   Eleventy doesn't expose rendered HTML as data. These extractors give
+ *   the cascade something queryable: link graphs, headings, excerpts.
+ *
+ * Scope:
+ *   Owns the per-page extractor shape and the article/main/body boundary
+ *   rule.
+ *   Does not own backlink inversion (backlinks.js) or origin assembly
+ *   (the composition root passes knownOrigins in).
+ *
+ * Data flow:
+ *   parsed document + knownOrigins → per-page record
+ */
+
+// Live DOM id wins (matches anchored markup); fall back to a slugified id
+// so consumers always have a stable handle, even when the rendering pipeline
+// did not auto-anchor headings.
+function headingRecord(el) {
+	const text = (el.textContent || '').trim();
+	return {
+		level: Number(el.tagName[1]),
+		text,
+		id: el.id || slugify(text) || null
+	};
+}
+
+function extractHeadings(root) {
+	const nodes = root.querySelectorAll('h1, h2, h3, h4, h5, h6');
+	return Array.from(nodes).map(headingRecord);
+}
+
+function extractSections(root) {
+	const rootLevel = 2;
+	const sections = [];
+	let current = null;
+
+	// Shallow walk: markdown-rendered HTML keeps headings as siblings of
+	// their prose, which is the shape sections need.
+	for (const el of Array.from(root.children)) {
+		const isHeading = /^H[1-6]$/.test(el.tagName);
+		const level = isHeading ? Number(el.tagName[1]) : null;
+
+		if (isHeading && level === rootLevel) {
+			if (current) sections.push(finalizeSection(current));
+			current = { heading: headingRecord(el), parts: [] };
+			continue;
+		}
+
+		// H1 is the document title. Never opens a section, never folds in.
+		if (isHeading && level < rootLevel) continue;
+
+		// Pre-H2 content has no section to attach to; `excerpt` covers the lead.
+		if (current) current.parts.push(el);
+	}
+
+	if (current) sections.push(finalizeSection(current));
+	return sections;
+}
+
+function finalizeSection({ heading, parts }) {
+	const text = parts
+		.map((el) => el.textContent || '')
+		.join(' ')
+		.replace(/\s+/g, ' ')
+		.trim();
+	return { heading, text };
+}
+
+function extractLinks(root, currentPage, knownOrigins) {
+	const anchors = root.querySelectorAll('a[href]');
+
+	return Array.from(anchors).map((a) => {
+		const raw = a.getAttribute('href');
+		const href = normaliseHref(raw, knownOrigins);
+
+		return {
+			internal: isInternal(href),
+			from: currentPage,
+			to: href,
+			text: (a.textContent || '').trim(),
+			rel: extractRel(a)
+		};
+	});
+}
+
+// HTML `rel` is a space-separated token list, case-insensitive per spec.
+// Lowercased and deduped so consumers can do membership checks without
+// caring about author-side whitespace or casing.
+function extractRel(el) {
+	const raw = el.getAttribute('rel');
+	if (!raw) return [];
+	return Array.from(new Set(raw.trim().toLowerCase().split(/\s+/).filter(Boolean)));
+}
+
+// HtmlBasePlugin rewrites internal hrefs to absolute URLs at render time
+// (using process.env.URL or the dev server origin). Strip a known origin
+// so hrefs land back as path-only; leave external URLs alone.
+function normaliseHref(href, knownOrigins) {
+	if (!href) return href;
+	try {
+		const url = new URL(href);
+		if (knownOrigins?.has(url.origin)) {
+			return url.pathname + url.search + url.hash;
+		}
+		return href;
+	} catch {
+		return href;
+	}
+}
+
+function isInternal(href) {
+	if (!href) return false;
+	return href.startsWith('/') || href.startsWith('#');
+}
+
+function extractImages(root) {
+	const imgs = root.querySelectorAll('img[src]');
+
+	return Array.from(imgs).map((img) => ({
+		src: img.getAttribute('src'),
+		alt: img.getAttribute('alt') || null
+	}));
+}
+
+function extractExcerpt(root, text) {
+	const firstP = root.querySelector('p');
+	const fromP = firstP?.textContent?.trim();
+	if (fromP) return fromP;
+
+	if (!text) return;
+	return text.length > 200 ? text.slice(0, 200).trimEnd() + '…' : text;
+}
+
+/**
+ * Extract per-page records from rendered HTML.
+ *
+ * Scope rule:
+ *   - Single `<article>` inside `<main>` → article is the boundary.
+ *     Encourages semantic HTML; keeps chapter TOCs and sibling nav out.
+ *   - Multiple `<article>`s (listing pages) → fall back to `<main>`,
+ *     because the listing as a whole is the page's content.
+ *   - No `<main>` → fall back to `<body>`. Defensive only; a site without
+ *     `<main>` is giving up the semantic boundary that makes any of this
+ *     meaningful.
+ */
+export function extractGraph(document, options = {}) {
+	const main = document.querySelector('main');
+	const articles = main?.querySelectorAll('article') ?? [];
+	const root = articles.length === 1 ? articles[0] : (main ?? document.body);
+
+	if (!root) return { text: undefined, excerpt: undefined, headings: [], links: [], images: [] };
+
+	const text = root.textContent?.trim();
+	const currentpage = options.url;
+	const knownOrigins = options.knownOrigins;
+
+	return {
+		node: {
+			excerpt: extractExcerpt(root, text),
+			headings: extractHeadings(root),
+			sections: extractSections(root),
+			images: extractImages(root)
+		},
+		edges: extractLinks(root, currentpage, knownOrigins)
+	};
+}

package/core/content-graph/graph.js

@@ -0,0 +1,121 @@
+import { parseHTML } from 'linkedom';
+
+import { extractGraph } from './extractors.js';
+import { buildBacklinkIndex } from './backlinks.js';
+
+/**
+ * Content graph (runtime substrate)
+ *
+ * Turns rendered HTML into the `{ nodes, edges, backlinks }` graph that
+ * templates query through the cascade. Node shape carries identity
+ * (from page-context) merged with extracted fields (excerpt, headings,
+ * images). Edges are flat anchor records. Backlinks is the target-keyed
+ * inverse index, pre-enriched with the source page's title and excerpt.
+ *
+ * Architecture layer:
+ *   runtime substrate
+ *
+ * System role:
+ *   The transformation between rendered output and the queryable
+ *   per-page records the cascade exposes. Backlink index is built here
+ *   so accessor reads stay O(1).
+ *
+ * Lifecycle:
+ *   build-time → buildGraph runs once over the pre-pass output
+ *   transform-time → createAccessors hands the cascade a live read surface
+ *
+ * Why this exists:
+ *   Eleventy's cascade can't see across pages or into rendered bodies.
+ *   This is the layer that lets it.
+ *
+ * Scope:
+ *   Owns the per-page record shape, the backlink index, and the
+ *   getter-backed accessor surface.
+ *   Does not own the synthetic Eleventy run (prepass.js) or the
+ *   per-page extraction logic (extractors.js).
+ *
+ * Data flow:
+ *   pre-pass pages → linkedom parse → extractors → records + backlinks
+ */
+
+/**
+ * @param {Array<{ url: string, content?: string, data?: object }>} pages
+ * @param {{ knownOrigins?: Set<string>, log?: { warn: (...args: unknown[]) => void } }} [options] - Origins to strip from internal hrefs (HtmlBasePlugin rewrites them at render time). `log` routes dev-mode extraction warnings through the scoped logger.
+ * @returns {{ nodes: Record<string, object>, edges: Array<{ internal: boolean, from: string, to: string, text: string, rel: string[] }>, backlinks: Record<string, Array<{ url: string, title?: string, excerpt?: string }>> }}
+ */
+export function buildGraph(pages, options = {}) {
+	const { log } = options;
+	const nodes = {};
+	const edges = [];
+	const sourceMeta = {};
+
+	for (const page of pages) {
+		if (!page?.url || typeof page.content !== 'string') continue;
+		if (!page.outputPath?.endsWith('.html')) continue;
+		// Honour the same opt-out 404s, drafts and internal templates already use.
+		if (page.data?._internal === true) continue;
+		if (page.data?.baselineExcludeFromGraph === true) continue;
+
+		try {
+			const { document } = parseHTML(page.content);
+			const ctx = page.data?._pageContext ?? {};
+			const url = ctx.page?.url ?? page.url;
+
+			const graph = extractGraph(document, { ...options, url });
+
+			const nodeIdentity = {
+				title: ctx.entry?.title,
+				slug: ctx.entry?.slug,
+				description: ctx.entry?.description,
+				section: ctx.entry?.section,
+				breadcrumbs: ctx.entry?.breadcrumbs,
+				type: ctx.entry?.type,
+				lang: ctx.page?.lang,
+				locale: ctx.page?.locale,
+				translationKey: ctx.page?.translationKey,
+				isDefaultLang: ctx.page?.isDefaultLang,
+				date: ctx.page?.date,
+				url
+			};
+
+			nodes[url] = {
+				...nodeIdentity,
+				...graph.node
+			};
+
+			edges.push(...graph.edges);
+
+			sourceMeta[url] = { title: nodeIdentity.title };
+		} catch (err) {
+			if (process.env.NODE_ENV !== 'production') {
+				log?.warn(`Graph extraction failed for ${page.url}`, err);
+			}
+			continue;
+		}
+	}
+
+	const backlinks = buildBacklinkIndex(edges, nodes, sourceMeta);
+
+	return { nodes: nodes, edges: edges, backlinks };
+}
+
+/**
+ * Build the accessor surface templates see through the cascade. Closes
+ * over a getter so the underlying graph reference can be swapped (e.g.
+ * on serve-mode rebuilds) without re-registering global data.
+ *
+ * @param {() => ({ nodes: Record<string, object>, edges: Array<object>, backlinks: Record<string, Array<{ url: string, title?: string, excerpt?: string }>> } | null)} getGraph
+ */
+export function createAccessors(getGraph) {
+	return {
+		isReady: () => getGraph() !== null,
+		getPage: (url) => getGraph()?.nodes[url],
+		getHeadings: (url) => getGraph()?.nodes[url]?.headings ?? [],
+		getOutgoingLinks: (url) => getGraph()?.nodes[url]?.links ?? [],
+		getImages: (url) => getGraph()?.nodes[url]?.images ?? [],
+		getText: (url) => getGraph()?.nodes[url]?.text,
+		getExcerpt: (url) => getGraph()?.nodes[url]?.excerpt,
+		getBacklinks: (url) => getGraph()?.backlinks[url] ?? [],
+		all: () => getGraph()?.nodes ?? {}
+	};
+}

package/core/content-graph/index.js

@@ -0,0 +1,2 @@
+export { buildGraph, createAccessors } from './graph.js';
+export { runPrepass, readGraphFromDisk, GRAPH_CACHE_PATH, PREPASS_SENTINEL } from './prepass.js';

package/core/content-graph/prepass.js

@@ -0,0 +1,121 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+
+import Eleventy from '@11ty/eleventy';
+import chalk from 'kleur';
+
+import { pickRepetitionQuip } from '../logging/index.js';
+import { buildGraph } from './graph.js';
+
+/**
+ * Pre-pass (runtime substrate)
+ *
+ * Runs a programmatic Eleventy in dryRun mode, hands its rendered output
+ * to the graph builder, and writes the result to disk for serve-mode
+ * rebuilds to read between cycles.
+ *
+ * Architecture layer:
+ *   runtime substrate
+ *
+ * System role:
+ *   Build-time entry point for the content graph. Owns the re-entry
+ *   sentinel, the log-suppression scope, and the cache file path.
+ *
+ * Lifecycle:
+ *   build-time → fires on each Eleventy `eleventy.before` event; spawns a
+ *                synthetic Eleventy, captures rendered HTML via toJSON(),
+ *                and persists the graph before the outer cycle renders.
+ *
+ * Why this exists:
+ *   Eleventy's data cascade is blind to rendered output. A pre-pass is the
+ *   way to read the rendered shape of every page before the real build
+ *   composes its templates. Running it every cycle keeps the graph current
+ *   in serve mode without a separate merge mechanic.
+ *
+ * Scope:
+ *   Owns the synthetic Eleventy run, sentinel handling, and cache I/O.
+ *   Does not own extraction or the graph shape (graph.js owns those).
+ *
+ * Data flow:
+ *   inner Eleventy toJSON() → buildGraph → cache file + in-memory graph
+ */
+
+// Re-entry guard: set once by the outer process, read at call-time on
+// the inner re-entry to skip the pre-pass. Permanent for the life of
+// the outer process — the pre-pass runs exactly once.
+export const PREPASS_SENTINEL = 'BASELINE_PREPASS_RUNNING';
+
+// Log-suppression scope: set only while runPrepass is executing. Read by
+// the logger to silence baseline's own info-level chatter during the
+// inner build. Different lifetime to PREPASS_SENTINEL on purpose.
+export const PREPASS_ACTIVE = 'BASELINE_PREPASS_ACTIVE';
+
+export const GRAPH_CACHE_PATH = resolve(process.cwd(), '.cache/_baseline/content-graph.json');
+
+/**
+ * Run a programmatic Eleventy, extract the content graph, write it to disk,
+ * return the in-memory graph.
+ *
+ * Sets the sentinel before constructing Eleventy so the inner re-entry into
+ * baseline() skips its own pre-pass.
+ *
+ * Always runs — there is no skip-if-cache-exists check. The pre-pass is fast
+ * enough today that unconditional execution is the honest default, and the
+ * cache file's primary job is the serve-mode handoff between rebuilds, not
+ * build-skip caching. When the cost earns it, mtime-based skip belongs at the
+ * call site (compare cache mtime to newest input mtime), not baked in here —
+ * keeps mechanic and policy separated.
+ *
+ * @param {string} input
+ * @param {string} output
+ * @param {(namespace: string) => { info: Function, warn: Function, error: Function }} scopedLog - Factory the composition root passes through so the pre-pass and the cache-write step can be scoped separately.
+ * @param {object} [options]
+ * @param {Set<string>} [options.knownOrigins] - Origins to strip from internal hrefs during extraction.
+ * @returns {Promise<object>}
+ */
+export async function runPrepass(input, output, scopedLog, options = {}) {
+	const log = scopedLog('pre-pass');
+	const graphLog = scopedLog('content-graph');
+
+	log.info('Pre-pass starting');
+	log.info(chalk.cyan(pickRepetitionQuip()));
+	graphLog.info('Caching content graph');
+	process.env[PREPASS_SENTINEL] = '1';
+	process.env[PREPASS_ACTIVE] = '1';
+
+	// knownOrigins is consumed by the graph builder, not Eleventy.
+	const { knownOrigins, ...elevOptions } = options;
+
+	let graph;
+	try {
+		const elev = new Eleventy(input, output, {
+			...elevOptions,
+			dryRun: true,
+			// Surface fields the graph and backlink enrichment read off `data`.
+			config: function (eleventyConfig) {
+				eleventyConfig.dataFilterSelectors.add('_pageContext'); // -> Future pass.
+				eleventyConfig.dataFilterSelectors.add('eleventyExcludeFromCollections');
+				eleventyConfig.dataFilterSelectors.add('baselineExcludeFromGraph');
+			}
+		});
+		const pages = await elev.toJSON();
+		graph = buildGraph(pages, { knownOrigins, log: graphLog });
+
+		await mkdir(dirname(GRAPH_CACHE_PATH), { recursive: true });
+		await writeFile(GRAPH_CACHE_PATH, JSON.stringify(graph), 'utf8');
+	} finally {
+		process.env[PREPASS_ACTIVE] = '0';
+		log.info('Pre-pass done');
+	}
+
+	return graph;
+}
+
+export async function readGraphFromDisk() {
+	try {
+		const raw = await readFile(GRAPH_CACHE_PATH, 'utf8');
+		return JSON.parse(raw);
+	} catch {
+		return null;
+	}
+}