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

package/core/{logging.js → logging/index.js}

@@ -1,5 +1,8 @@
 import chalk from 'kleur';
 
+export * from './banner.js';
+export * from './quips.js';
+
 /**
  * Logger (runtime substrate)
  *
@@ -36,11 +39,12 @@ import chalk from 'kleur';
  * @property {(...args: unknown[]) => void} info   Verbose-only.
  * @property {(...args: unknown[]) => void} warn   Always visible.
  * @property {(...args: unknown[]) => void} error  Always visible.
+ * @property {(content: string) => void}   print  Unprefixed pass-through (used by the banner).
  */
 
 /**
  * Create a namespaced logger. Prefix is `[baseline]` at plugin root and
- * `[baseline:<namespace>]` inside modules. `info` is gated behind `verbose`;
+ * `[baseline/<namespace>]` inside modules. `info` is gated behind `verbose`;
  * `warn` and `error` always emit.
  *
  * @param {string | null | undefined} namespace
@@ -49,15 +53,28 @@ import chalk from 'kleur';
  */
 export function createLogger(namespace, { verbose = false } = {}) {
 	const label = namespace ? `[baseline/${namespace}]` : '[baseline]';
+
+	// Pre-pass gate: silence baseline's own info during the inner Eleventy
+	// run so modules don't double-log every line they emit again during the
+	// real build. Env-var contract scoped to runPrepass's execution (set in
+	// try, cleared in finally). Eleventy's own `[11ty]` output is governed
+	// by its `quietMode` and stays untouched here.
+	const isPrepass = () => process.env.BASELINE_PREPASS_ACTIVE === '1';
+
 	return {
 		info: (...args) => {
-			if (verbose) console.log(chalk.gray(label), ...args);
+			if (!verbose) return;
+			if (isPrepass()) return;
+			console.log(chalk.gray(label), ...args);
 		},
 		warn: (...args) => {
 			console.warn(chalk.yellow().bold(label), ...args);
 		},
 		error: (...args) => {
 			console.error(chalk.red().bold(label), ...args);
+		},
+		print: (content) => {
+			console.log(chalk.gray(content));
 		}
 	};
 }

package/core/logging/quips.js

@@ -0,0 +1,30 @@
+/**
+ * Logging quips (personality)
+ *
+ * A small set of one-liners used at the pre-pass boundary. The pre-pass
+ * runs Eleventy inside Eleventy, so each line is a nod to that idea of
+ * repetition or recursion. Picked at random per build.
+ *
+ * Architecture layer:
+ *   runtime substrate (logging)
+ *
+ * Why this exists:
+ *   Build logs are dry by default. A single playful line at a recurring
+ *   moment makes the narrative feel like the project, not a config dump.
+ */
+
+const REPETITION_QUIPS = [
+	'Somewhere, a bowl of petunias is thinking: oh no, not again.',
+	'Déjà vu is usually a glitch in the Matrix.',
+	'All of this has happened before, and all of it will happen again.',
+	'Yo dawg, I heard you like Eleventy, so I put Eleventy in your Eleventy…'
+];
+
+/**
+ * Return a random repetition quip.
+ *
+ * @returns {string}
+ */
+export function pickRepetitionQuip() {
+	return REPETITION_QUIPS[Math.floor(Math.random() * REPETITION_QUIPS.length)];
+}

package/core/markdown/auto-heading-ids.js

@@ -0,0 +1,86 @@
+/**
+ * Auto heading IDs (runtime substrate)
+ *
+ * Assigns stable id attributes to every heading that doesn't already have
+ * one. Manual ids (from markdown-it-attrs or any upstream plugin) win and
+ * seed the dedup map, so auto ids skip over names a manual id has claimed.
+ * Duplicate slugs get WordPress-style suffixes: foo, foo-2, foo-3, …
+ *
+ * Architecture layer:
+ *   runtime substrate
+ *
+ * System role:
+ *   Markdown-it plugin registered by the composition root via
+ *   amendLibrary('md', ...). Mutates heading_open tokens; reads nothing
+ *   from the runtime.
+ *
+ * Lifecycle:
+ *   transform-time → assigns id attrs on heading_open tokens during the
+ *                    core parsing phase
+ *
+ * Why this exists:
+ *   The content graph and deep-link consumers all need predictable heading
+ *   ids. Doing it inside the markdown engine means the rendered HTML and
+ *   the graph's heading record are guaranteed identical, instead of being
+ *   "usually equal because the same slugify helper runs on both sides".
+ *
+ * Scope:
+ *   Owns id assignment and dedup. Does not render permalink affordances;
+ *   that's a theme concern.
+ *
+ * @param {import('markdown-it').default} md
+ * @param {Object} deps
+ * @param {(text: string) => string | undefined} deps.slugify
+ */
+export function autoHeadingIds(md, { slugify } = {}) {
+	if (typeof slugify !== 'function') {
+		throw new Error('auto-heading-ids plugin requires { slugify }');
+	}
+
+	md.core.ruler.push('baseline_auto_heading_ids', (state) => {
+		const tokens = state.tokens;
+		const seen = new Set();
+		const counts = new Map();
+
+		// Pass 1: seed dedup with manual ids so autos never collide with them.
+		for (let i = 0; i < tokens.length; i++) {
+			const t = tokens[i];
+			if (t.type !== 'heading_open') continue;
+			const manual = t.attrGet('id');
+			if (manual) seen.add(manual);
+		}
+
+		// Pass 2: assign auto ids to headings that lack one.
+		for (let i = 0; i < tokens.length; i++) {
+			const t = tokens[i];
+			if (t.type !== 'heading_open') continue;
+			if (t.attrGet('id')) continue;
+
+			// Read from children rather than .content: markdown-it-attrs
+			// strips the {.class} from children tokens but leaves the parent
+			// inline .content untouched, so slugifying .content would fold
+			// the attribute text into the id.
+			const inline = tokens[i + 1];
+			const text = (inline?.children || [])
+				.filter((c) => c.type === 'text' || c.type === 'code_inline' || c.type === 'image')
+				.map((c) => (c.type === 'image' ? c.attrGet('alt') || c.content || '' : c.content))
+				.join('')
+				.trim();
+			if (!text) continue;
+
+			const base = slugify(text);
+			if (!base) continue;
+
+			let n = counts.get(base) || 0;
+			let id;
+			do {
+				id = n === 0 ? base : `${base}-${n + 1}`;
+				n += 1;
+			} while (seen.has(id));
+
+			counts.set(base, n);
+			seen.add(id);
+			t.attrSet('id', id);
+		}
+	});
+}

package/core/markdown/index.js

@@ -0,0 +1,5 @@
+// Markdown substrate barrel.
+export { autoHeadingIds } from './auto-heading-ids.js';
+export { wikilinks } from './wikilinks.js';
+export { safeUse } from './safe-use.js';
+export { markdownFilter } from './markdownify.js';

package/core/markdown/safe-use.js

@@ -0,0 +1,42 @@
+/**
+ * Safe markdown-it plugin registration
+ *
+ * Calls md.use(plugin, options) only when no rule with the given name is
+ * already registered on the core, block, or inline ruler. Lets Baseline
+ * coexist with user configs that loaded the same plugin themselves.
+ *
+ * Architecture layer:
+ *   utility
+ *
+ * System role:
+ *   Helper used by the composition root when amending the markdown-it
+ *   instance.
+ *
+ * Lifecycle:
+ *   transform-time (config load)
+ *
+ * Why this exists:
+ *   markdown-it has no built-in dedup. Calling .use() twice on a plugin
+ *   that pushes a parser rule runs it twice per render. Eleventy's
+ *   amendLibrary callbacks compose with whatever the user already wired,
+ *   so a guard at the seam keeps both sides intact.
+ *
+ * @param {import('markdown-it').default} md
+ * @param {string} ruleName - canonical rule name the plugin registers
+ * @param {(md: any, options?: any) => void} plugin
+ * @param {any} [options]
+ * @param {{ info?: (msg: string) => void }} [log]
+ */
+export function safeUse(md, ruleName, plugin, options, log) {
+	const rulers = [md.core?.ruler, md.block?.ruler, md.inline?.ruler];
+	const installed = rulers.some((r) =>
+		r?.__rules__?.some((rule) => rule.name === ruleName)
+	);
+
+	if (installed) {
+		log?.info?.(`markdown-it rule "${ruleName}" already registered, skipping`);
+		return;
+	}
+
+	md.use(plugin, options);
+}

package/core/{wikilinks.js → markdown/wikilinks.js}

@@ -1,4 +1,4 @@
-import { slugify } from './utils/helpers.js';
+import { slugify } from '../utils/slugify.js';
 
 /**
  * Wikilinks (runtime substrate)
@@ -38,7 +38,7 @@ import { slugify } from './utils/helpers.js';
  *
  * @param {import('markdown-it').default} md
  * @param {Object} deps
- * @param {{getBySlug: (slug: string) => string | null}} deps.slugIndex
+ * @param {{getBySlug: (slug: string) => string | undefined}} deps.slugIndex
  * @param {{getByKey: (url: string) => any}} deps.pageContextRegistry
  * @param {{get: () => Record<string, Record<string, {url: string, title?: string}>> | null}} [deps.translationMapStore]
  */
@@ -148,5 +148,5 @@ export function wikilinks(md, { slugIndex, pageContextRegistry, translationMapSt
 		return true;
 	}
 
-	md.inline.ruler.before('link', 'wikilink', tokenize);
+	md.inline.ruler.before('link', 'baseline_wikilinks', tokenize);
 }

package/core/page-context/build.js

@@ -0,0 +1,239 @@
+import { setEntry } from '../registry.js';
+import { slugify } from '../utils/slugify.js';
+import { uniqueBy } from '../utils/unique-by.js';
+import { resolveField } from '../utils/resolve-field.js';
+import { extractFirstParagraph, normalizeCanonical } from './seo-helpers.js';
+
+/**
+ * Page context — builder factory
+ *
+ * Returns a `buildPageContext` function bound to the runtime dependencies
+ * it needs (scope, slug index, resolved settings, runtime substrate handles,
+ * options). Each top-level key in the page context (`site`, `page`, `entry`,
+ * `query`, `meta`, `render`, `head`) has its own builder inside the closure.
+ *
+ * Architecture layer:
+ *   runtime substrate (page-context internal)
+ *
+ * System role:
+ *   Pure transformation of Eleventy data → normalised page context. The
+ *   factory keeps cross-builder dependencies (separator, site.url, contentMap)
+ *   in one place without threading them through every builder signature.
+ *
+ * @param {{
+ *   scope: { values: Map },
+ *   slugIndex: { set: (slug: string, url: string, inputPath: string) => void } | null,
+ *   settings: import('../types.js').BaselineSettings,
+ *   runtime: { contentMap: any },
+ *   options: import('../types.js').BaselineOptions,
+ *   log?: { warn: (...args: unknown[]) => void }
+ * }} deps
+ * @returns {(data: any) => object}
+ */
+export function createPageContext({ scope, slugIndex, settings, runtime, options, log }) {
+	const separator = options.head?.titleSeparator ?? ' – ';
+
+	function buildSite(lang, userSettings) {
+		const langEntry = lang ? userSettings.languages?.[lang] : undefined;
+		return {
+			title: langEntry?.title ?? userSettings.title ?? '',
+			tagline: langEntry?.tagline ?? userSettings.tagline ?? '',
+			description: langEntry?.description ?? userSettings.description ?? '',
+			url: userSettings.url ?? '',
+			noindex: userSettings.noindex === true
+		};
+	}
+
+	function buildPage(pageInput) {
+		return {
+			inputPath: pageInput?.inputPath,
+			fileSlug: pageInput?.fileSlug,
+			filePathStem: pageInput?.filePathStem,
+			outputFileExtension: pageInput?.outputFileExtension,
+			templateSyntax: pageInput?.templateSyntax,
+			date: pageInput?.date,
+			url: pageInput?.url,
+			outputPath: pageInput?.outputPath,
+			lang: pageInput?.lang,
+			locale: pageInput?.locale,
+			sitemap: pageInput?.sitemap
+		};
+	}
+
+	/**
+	 * Build the `entry` branch — the author's view of the page.
+	 *
+	 * Holds the content's self-description (title, description, excerpt), its
+	 * identity (slug), structural classification (section as a hierarchical
+	 * path array, type as a free-form classifier), and per-page head extras.
+	 * Values pass through raw; consumers normalise.
+	 */
+	function buildEntry(data) {
+		const rawSlug = data?.slug ?? data?.page?.fileSlug;
+
+		// Coerce a string section to a single-element array, with a dev warning.
+		// Strict contract is "section is always an array"; runtime stays forgiving.
+		let section = data?.section;
+		if (typeof section === 'string') {
+			if (process.env.NODE_ENV !== 'production') {
+				log?.warn(
+					`entry.section should be an array, got string "${section}" at ${data?.page?.url ?? data?.page?.inputPath}. Use ['${section}'] instead.`
+				);
+			}
+			section = [section];
+		}
+
+		return {
+			title: data?.seo?.title ?? data?.title,
+			description: data?.seo?.description ?? data?.description,
+			excerpt: data?.excerpt,
+			slug: slugify(rawSlug),
+			section,
+			type: data?.type,
+			head: data?.head
+		};
+	}
+
+	function buildQuery({ page }) {
+		return {
+			isHome: page.url === '/'
+		};
+	}
+
+	function buildMeta({ data, site, page, query }) {
+		const noindex = site.noindex || data?.noindex === true;
+
+		const robots = noindex
+			? 'noindex, nofollow'
+			: 'index, follow, max-snippet:-1, max-image-preview:large, max-video-preview:-1';
+
+		const contentMap = runtime.contentMap;
+
+		const siteTitle = site.title;
+		const siteDescription = site.description;
+		const tagline = site.tagline;
+
+		const pageTitle = data?.seo?.title ?? data?.title ?? siteTitle;
+		const pageDescription = data?.seo?.description ?? data?.description ?? data?.excerpt ?? extractFirstParagraph(data);
+
+		function enhance(value) {
+			if (query.isHome && !data?.seo?.title && tagline) {
+				return `${siteTitle}${separator}${tagline}`;
+			}
+
+			if (!query.isHome && pageTitle && siteTitle && pageTitle !== siteTitle) {
+				return `${pageTitle}${separator}${siteTitle}`;
+			}
+
+			return value;
+		}
+
+		// ---- DESCRIPTION ----
+		const description = resolveField({
+			pageValue: pageDescription,
+			siteValue: siteDescription,
+			isHome: query.isHome
+		});
+
+		// ---- TITLE ----
+		const base = resolveField({
+			pageValue: pageTitle,
+			siteValue: siteTitle
+		});
+
+		const title = enhance(base);
+
+		// ---- CANONICAL ----
+		let canonical;
+
+		if (!noindex) {
+			const rawCanonical =
+				data?.canonical ?? page.url ?? (page.inputPath && contentMap?.inputPathToUrl?.[page.inputPath]?.[0]);
+
+			canonical = normalizeCanonical(rawCanonical, site.url);
+		}
+
+		return {
+			title,
+			description,
+			canonical,
+			robots,
+			noindex
+		};
+	}
+
+	function buildRender(data) {
+		return {
+			generator: data?.eleventy?.generator
+		};
+	}
+
+	// --- HEAD (global + page-level merge + dedupe) ---
+	function buildHead({ userSettings, data, siteUrl }) {
+		const userHead = userSettings.head ?? {};
+		const pageHead = data?.head ?? {};
+
+		const link = uniqueBy([...(userHead.link ?? []), ...(pageHead.link ?? [])], (item) => {
+			if (item?.rel === 'canonical') {
+				try {
+					return normalizeCanonical(item.href, siteUrl);
+				} catch {
+					return item?.href;
+				}
+			}
+			return item?.href;
+		});
+
+		const script = uniqueBy([...(userHead.script ?? []), ...(pageHead.script ?? [])], 'src');
+
+		const style = uniqueBy([...(userHead.style ?? []), ...(pageHead.style ?? [])], 'href');
+
+		const meta = uniqueBy([...(userHead.meta ?? []), ...(pageHead.meta ?? [])], 'name');
+
+		return {
+			link,
+			script,
+			style,
+			meta
+		};
+	}
+
+	/**
+	 * Main context builder.
+	 * Pure transformation: Eleventy data → normalised page context.
+	 */
+	return function buildPageContext(data) {
+		const pageInput = data.page ?? {};
+		const userSettings = data.settings ?? settings;
+
+		const page = buildPage(pageInput);
+		const site = buildSite(page.lang, userSettings);
+		const entry = buildEntry(data);
+		const query = buildQuery({ entry, page });
+		const meta = buildMeta({ data, site, page, query });
+		const render = buildRender(data);
+		const head = buildHead({ userSettings, data, siteUrl: site.url });
+
+		const context = {
+			site,
+			page,
+			entry,
+			query,
+			meta,
+			render,
+			head
+		};
+
+		const inspectionKey = context.page.url ?? context.page.inputPath;
+		if (inspectionKey) setEntry(scope, inspectionKey, context);
+
+		if (slugIndex && entry.slug && page.url) {
+			const eligible = page.locale?.isDefaultLang === true;
+			if (eligible) {
+				slugIndex.set(entry.slug, page.url, page.inputPath);
+			}
+		}
+
+		return context;
+	};
+}

package/core/page-context/index.js

@@ -0,0 +1 @@
+export { registerPageContext } from './register.js';

package/core/page-context/register.js

@@ -0,0 +1,73 @@
+import { createLogger } from '../logging/index.js';
+import { getScope, memoize } from '../registry.js';
+import { createPageContext } from './build.js';
+
+const SCOPE_NAME = 'core:page-context';
+const LOG_NAME = 'page-context';
+const COMPUTED_KEY = 'eleventyComputed._pageContext';
+
+/**
+ * Page context (runtime substrate)
+ *
+ * A normalised per-page object built once at cascade-time and cached for
+ * transform-time consumers. The shape downstream modules read instead of
+ * re-deriving from raw cascade data.
+ *
+ * Architecture layer:
+ *   runtime substrate
+ *
+ * System role:
+ *   Lifecycle bridge between Eleventy's data cascade and the htmlTransformer.
+ *   Head reads it via `getByKey`; navigator snapshots it for inspection.
+ *
+ * Lifecycle:
+ *   cascade-time   → eleventyComputed._pageContext builds and caches the context
+ *   transform-time → consumers retrieve the cached context by page.url
+ *
+ * Why this exists:
+ *   Eleventy's htmlTransformer context exposes only page metadata, not the
+ *   data cascade. The cache lets transform-time consumers read the same
+ *   normalised view that cascade-time produced.
+ *
+ * Scope:
+ *   Owns the page-context shape, memoisation, key-based lookup, and snapshot.
+ *   Does not own the meaning of any field; modules consume them as they see fit.
+ *   Templates with `_internal: true` are skipped (synthetic sitemap pages, etc.).
+ *
+ * Data flow:
+ *   data cascade → buildPageContext → registry scope → head, navigator
+ *
+ * @param {import("@11ty/eleventy").UserConfig} eleventyConfig
+ * @param {Object} coreContext - Resolved baseline core context (state, runtime, helpers).
+ */
+export function registerPageContext(eleventyConfig, coreContext) {
+	const { state, runtime } = coreContext;
+	const { slugIndex } = runtime;
+	const { settings, options } = state;
+
+	const log = createLogger(LOG_NAME, { verbose: options.verbose });
+	const scope = getScope(eleventyConfig, SCOPE_NAME);
+
+	const buildPageContext = createPageContext({ scope, slugIndex, settings, runtime, options, log });
+
+	function shouldSkip(data) {
+		if (data._internal) return true;
+		if (data.page?.outputFileExtension !== 'html') return true;
+		return false;
+	}
+
+	eleventyConfig.addGlobalData(COMPUTED_KEY, () => {
+		return (data) => {
+			if (shouldSkip(data)) return null;
+			return memoize(scope, data, buildPageContext);
+		};
+	});
+
+	log.info('Page context registered');
+
+	return {
+		get: (data) => scope.cache.get(data),
+		getByKey: (key) => scope.values.get(key),
+		snapshot: () => Object.fromEntries(scope.values)
+	};
+}

package/core/page-context/seo-helpers.js

@@ -0,0 +1,56 @@
+/**
+ * Page context — SEO helpers
+ *
+ * Pure URL/content normalisation used when building the `meta` slice of
+ * the page context. No Eleventy, no registry.
+ *
+ * Architecture layer:
+ *   runtime substrate (page-context internal)
+ */
+
+/**
+ * Strip common tracking query params and the URL fragment.
+ *
+ * @param {URL} urlObj
+ * @returns {URL}
+ */
+export function stripTrackingParams(urlObj) {
+	['utm_source', 'utm_medium', 'utm_campaign', 'utm_term', 'utm_content', 'fbclid', 'gclid'].forEach((p) =>
+		urlObj.searchParams.delete(p)
+	);
+
+	urlObj.hash = '';
+	return urlObj;
+}
+
+/**
+ * Pull the first paragraph's inner HTML out of a rendered page's content.
+ * Used as the last-resort source for meta descriptions.
+ *
+ * @param {{ content?: string }} data
+ * @returns {string | undefined}
+ */
+export function extractFirstParagraph(data) {
+	const html = data?.content;
+	if (!html) return;
+	const match = html.match(/<p>(.*?)<\/p>/i);
+	return match?.[1];
+}
+
+/**
+ * Resolve a path against the site URL, strip the fragment, and remove
+ * tracking params. Returns undefined when inputs are missing or invalid.
+ *
+ * @param {string | undefined} path
+ * @param {string | undefined} siteUrl
+ * @returns {string | undefined}
+ */
+export function normalizeCanonical(path, siteUrl) {
+	if (!path || !siteUrl) return;
+
+	const url = new URL(path, siteUrl);
+
+	url.hash = '';
+
+	return stripTrackingParams(url).href;
+}

package/core/schema.js

@@ -58,7 +58,25 @@ export const settingsSchema = z.object({
 	url: z.string().optional(),
 	noindex: z.boolean().optional(),
 	defaultLanguage: z.string().optional(),
-	languages: z.record(z.string(), z.looseObject({})).optional(),
+	languages: z
+		.unknown()
+		.optional()
+		.superRefine((value, ctx) => {
+			if (value === undefined) return;
+
+			if (Array.isArray(value)) {
+				const arrayResult = z.array(z.string().min(1)).safeParse(value);
+				if (!arrayResult.success) {
+					for (const issue of arrayResult.error.issues) ctx.addIssue(issue);
+				}
+				return;
+			}
+
+			const recordResult = z.record(z.string(), z.looseObject({})).safeParse(value);
+			if (!recordResult.success) {
+				for (const issue of recordResult.error.issues) ctx.addIssue(issue);
+			}
+		}),
 	head: z
 		.object({
 			link: z.array(z.looseObject({})).optional(),

package/core/slug-index.js

@@ -35,7 +35,7 @@ const SCOPE_NAME = 'core:slug-index';
  *   page-context.buildPageContext → set() → registry scope → wikilinks getBySlug()
  *
  * @param {import('@11ty/eleventy').UserConfig} eleventyConfig
- * @returns {{set: (slug: string, url: string, inputPath?: string) => void, getBySlug: (slug: string) => string | null, snapshot: () => Record<string, {url: string, inputPath?: string}>}}
+ * @returns {{set: (slug: string, url: string, inputPath?: string) => void, getBySlug: (slug: string) => string | undefined, snapshot: () => Record<string, {url: string, inputPath?: string}>}}
  */
 export function createSlugIndex(eleventyConfig) {
 	const scope = getScope(eleventyConfig, SCOPE_NAME);
@@ -52,7 +52,7 @@ export function createSlugIndex(eleventyConfig) {
 			setEntry(scope, slug, { url, inputPath });
 		},
 		getBySlug(slug) {
-			return getEntry(scope, slug)?.url ?? null;
+			return getEntry(scope, slug)?.url;
 		},
 		snapshot() {
 			return Object.fromEntries(scope.values);