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

package/core/registry.js

@@ -0,0 +1,110 @@
+/**
+ * State isolation kernel (registry)
+ *
+ * Per-config scopes that hold caches, named values, and listener dedup sets.
+ * Every store and sub-registry in the substrate borrows a scope here; no
+ * feature data lives directly inside.
+ *
+ * Architecture layer:
+ *   registry
+ *
+ * System role:
+ *   Underpins virtual-dir, content-map store, translation-map store, and the
+ *   page-context registry. The seam between eleventyConfig and any long-lived
+ *   runtime state Baseline carries.
+ *
+ * Lifecycle:
+ *   build-time     → scopes created on demand
+ *   cascade-time   → values populated by store writers
+ *   transform-time → values read by transform-time consumers
+ *
+ * Why this exists:
+ *   Eleventy has no first-class place to hang per-config singletons. A
+ *   WeakMap keyed by eleventyConfig keeps state isolated across reloads and
+ *   parallel builds without leaks, and gives every consumer a stable slot.
+ *
+ * Scope:
+ *   Owns scope creation, listener dedup, and identity-keyed memoisation.
+ *   Does not own any feature data; only the containers feature code lives in.
+ *
+ * Data flow:
+ *   eleventyConfig → scope → { cache, values, listeners } → consumer
+ */
+
+const roots = new WeakMap();
+
+/**
+ * Get or create the per-eleventyConfig root that holds all named scopes.
+ */
+function getRoot(eleventyConfig) {
+	let root = roots.get(eleventyConfig);
+	if (!root) {
+		root = new Map();
+		roots.set(eleventyConfig, root);
+	}
+	return root;
+}
+
+/**
+ * Get or create a named scope bound to an Eleventy config instance.
+ *
+ * A scope is a per-config bag of state: a cache (for identity-keyed
+ * memoisation), a values map (for named entries), and a listeners set
+ * (for deduping event hookups).
+ *
+ * @param {import('@11ty/eleventy').UserConfig} eleventyConfig
+ * @param {string} name - Scope identifier (e.g. 'page-context', 'content-store').
+ * @returns {{cache: WeakMap, values: Map, listeners: Set<string>}}
+ */
+export function getScope(eleventyConfig, name) {
+	const root = getRoot(eleventyConfig);
+
+	if (!root.has(name)) {
+		root.set(name, {
+			cache: new WeakMap(),
+			values: new Map(),
+			listeners: new Set()
+		});
+	}
+
+	return root.get(name);
+}
+
+/**
+ * Attach an Eleventy event listener once per (event, key) pair within a scope.
+ *
+ * @param {import('@11ty/eleventy').UserConfig} eleventyConfig
+ * @param {string} scopeName
+ * @param {string} eventName - Eleventy event name (e.g. 'eleventy.contentMap').
+ * @param {string} listenerKey - Stable identifier for dedup.
+ * @param {(scope: object, payload: any) => void} handler
+ */
+export function addScopeListener(eleventyConfig, scopeName, eventName, listenerKey, handler) {
+	const scope = getScope(eleventyConfig, scopeName);
+	const dedupKey = `${eventName}::${listenerKey}`;
+
+	if (scope.listeners.has(dedupKey)) return;
+	scope.listeners.add(dedupKey);
+
+	eleventyConfig.on(eventName, (payload) => handler(scope, payload));
+}
+
+/**
+ * Memoise a value in the scope's cache by object identity.
+ */
+export function memoize(scope, key, factory) {
+	if (scope.cache.has(key)) {
+		return scope.cache.get(key);
+	}
+	const value = factory(key);
+	scope.cache.set(key, value);
+	return value;
+}
+
+export function setEntry(scope, name, value) {
+	scope.values.set(name, value);
+}
+
+export function getEntry(scope, name) {
+	return scope.values.get(name);
+}

package/core/schema.js

@@ -0,0 +1,70 @@
+import * as z from 'zod';
+
+/**
+ * Schemas (runtime substrate)
+ *
+ * Zod schemas for the two user-facing inputs Baseline validates: the
+ * directory `config` export and the `settings` argument. Structural only.
+ * Value-level preferences stay permissive.
+ *
+ * Architecture layer:
+ *   runtime substrate
+ *
+ * System role:
+ *   Validation seam at the public boundary. The composition root parses
+ *   `settings` non-fatally at init; the directory `config` is checked in
+ *   the test suite, not at runtime.
+ *
+ * Lifecycle:
+ *   build-time → composition root calls `settingsSchema.safeParse(settings)`
+ *                and logs structural mismatches under `info`
+ *
+ * Why this exists:
+ *   Eleventy accepts almost anything users pass through `addPlugin`. A
+ *   structural gate catches typos and shape drift early without forcing
+ *   a hard failure on imperfect input.
+ *
+ * Scope:
+ *   Owns the structural shape of `settings` and `config`. Does not own
+ *   defaults, value semantics, or required-field policy; those live in
+ *   the composition root and individual modules.
+ *
+ * Data flow:
+ *   user input → safeParse → issues logged or accepted
+ */
+
+export const configSchema = z.object({
+	dir: z.object({
+		input: z.string().min(1),
+		output: z.string().min(1),
+		data: z.string().min(1),
+		includes: z.string().min(1),
+		assets: z.string().min(1),
+		public: z.string().min(1)
+	}),
+	htmlTemplateEngine: z.string().min(1),
+	markdownTemplateEngine: z.string().min(1),
+	templateFormats: z
+		.array(z.string().min(1))
+		.min(1)
+		.refine((templateFormats) => templateFormats.includes('njk'), {
+			error: 'Baseline requires njk in templateFormats'
+		})
+});
+
+export const settingsSchema = z.object({
+	title: z.string().optional(),
+	tagline: z.string().optional(),
+	url: z.string().optional(),
+	noindex: z.boolean().optional(),
+	defaultLanguage: z.string().optional(),
+	languages: z.record(z.string(), z.looseObject({})).optional(),
+	head: z
+		.object({
+			link: z.array(z.looseObject({})).optional(),
+			script: z.array(z.looseObject({})).optional(),
+			meta: z.array(z.looseObject({})).optional(),
+			style: z.array(z.looseObject({})).optional()
+		})
+		.optional()
+});

package/core/shortcodes/image.js

@@ -1,5 +1,10 @@
 import path from 'node:path';
 import Image from '@11ty/eleventy-img';
+import { createLogger } from '../logging.js';
+
+// Module-level logger. Image shortcode only uses `.warn`, which emits regardless
+// of verbose, so we don't thread verbose through the shortcode signature.
+const log = createLogger('image');
 
 const DEFAULT_WIDTHS = [320, 640, 960, 1280, 1920, 'auto'];
 const DEFAULT_FORMATS = ['avif', 'webp'];
@@ -59,13 +64,13 @@ export async function imageShortcode(options = {}) {
 	} = options;
 	// Read from global data set during plugin init. When true, `eleventy:ignore`
 	// is added to the <img> (line 140) to prevent double-processing.
-	const hasImageTransformPlugin = this.ctx._baseline.hasImageTransformPlugin;
+	const hasImageTransformPlugin = this.ctx._baseline.features.hasImageTransformPlugin;
 
 	// --- Validation and normalization ---
 
 	if (!src) throw new Error(`imageShortcode: src is required (received ${JSON.stringify(src)})`);
 	if (alt == null) {
-		console.warn('imageShortcode: alt is required (use empty string for decorative images)');
+		log.warn('alt is required (use empty string for decorative images)');
 	}
 
 	const normalizedCaption = String(caption);
@@ -101,7 +106,7 @@ export async function imageShortcode(options = {}) {
 		});
 	} catch (error) {
 		if (process.env.ELEVENTY_RUN_MODE === 'serve') {
-			console.warn(`imageShortcode: transformOnRequest failed for ${src}, retrying.\n > ${error?.message || error}`);
+			log.warn(`transformOnRequest failed for ${src}, retrying.\n > ${error?.message || error}`);
 			metadata = await Image(resolvedSrc, imageOptions);
 		} else {
 			throw error;

package/core/shortcodes/index.js

@@ -0,0 +1,2 @@
+// Shortcodes barrel.
+export { imageShortcode } from './image.js';

package/core/slug-index.js

@@ -0,0 +1,61 @@
+import { getScope, setEntry, getEntry } from './registry.js';
+
+const SCOPE_NAME = 'core:slug-index';
+
+/**
+ * Slug index (runtime substrate)
+ *
+ * Maps wikilink-friendly slugs to canonical page URLs. Populated by the
+ * page-context builder as each page resolves; read by the wikilinks
+ * markdown-it plugin during body render.
+ *
+ * Architecture layer:
+ *   runtime substrate
+ *
+ * System role:
+ *   Forward-link index for the wikilinks plugin. In multilingual sites
+ *   only defaultLanguage pages register; the wikilinks plugin uses the
+ *   translation map to hop to other languages.
+ *
+ * Lifecycle:
+ *   cascade-time   → page-context registers slugs as templates compute
+ *   transform-time → wikilinks plugin resolves slugs during body render
+ *
+ * Why this exists:
+ *   Eleventy's data cascade resolves all eleventyComputed values before any
+ *   body renders, so the index is complete by the time wikilinks need it.
+ *   A dedicated scope keeps slug→url out of the page-context values map
+ *   (which holds url→pageContext).
+ *
+ * Scope:
+ *   Owns slug registration with collision detection and slug-keyed lookup.
+ *   Does not own slug derivation (page-context) or link rendering (wikilinks).
+ *
+ * Data flow:
+ *   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}>}}
+ */
+export function createSlugIndex(eleventyConfig) {
+	const scope = getScope(eleventyConfig, SCOPE_NAME);
+
+	return {
+		set(slug, url, inputPath) {
+			if (!slug || !url) return;
+			const existing = getEntry(scope, slug);
+			if (existing && existing.url !== url) {
+				throw new Error(
+					`Wikilink slug collision: "${slug}" used by both ${existing.inputPath ?? existing.url} and ${inputPath ?? url}`
+				);
+			}
+			setEntry(scope, slug, { url, inputPath });
+		},
+		getBySlug(slug) {
+			return getEntry(scope, slug)?.url ?? null;
+		},
+		snapshot() {
+			return Object.fromEntries(scope.values);
+		}
+	};
+}

package/core/translation-map-store.js

@@ -0,0 +1,46 @@
+import { getScope, setEntry, getEntry } from './registry.js';
+
+const SCOPE_NAME = 'core:translation-map-store';
+const KEY = 'translationMap';
+
+/**
+ * Translation map store (runtime substrate)
+ *
+ * Hand-off point for the translations map: written by multilang at
+ * cascade-time, read by head at transform-time.
+ *
+ * Architecture layer:
+ *   runtime substrate
+ *
+ * System role:
+ *   Bridge between the multilang module (writer) and the head module (reader).
+ *   The set/get pair lives in a registry scope rather than the data cascade
+ *   because head's PostHTML plugin runs outside the cascade.
+ *
+ * Lifecycle:
+ *   cascade-time   → multilang's translationsMap collection writes via set()
+ *   transform-time → head reads via get() to build hreflang alternates
+ *
+ * Why this exists:
+ *   The translations map is built inside an Eleventy collection, but head
+ *   needs it inside an htmlTransformer plugin where collections aren't
+ *   available.
+ *
+ * Scope:
+ *   Owns set/get on a per-config scope.
+ *   Does not own the map's shape, how it's built, or how head uses it.
+ *
+ * Data flow:
+ *   multilang translationsMap collection → set() → registry scope → head get()
+ *
+ * @param {import('@11ty/eleventy').UserConfig} eleventyConfig
+ * @returns {{set: (map: object) => void, get: () => object | null}}
+ */
+export function createTranslationMapStore(eleventyConfig) {
+	const scope = getScope(eleventyConfig, SCOPE_NAME);
+
+	return {
+		set: (map) => setEntry(scope, KEY, map),
+		get: () => getEntry(scope, KEY) ?? null
+	};
+}

package/core/types.js

@@ -0,0 +1,73 @@
+/**
+ * Baseline shared typedefs.
+ *
+ * Extracted from the composition root so file-level headers stay scannable.
+ * No runtime exports; this file exists for IDE and JSDoc tooling only.
+ */
+
+/**
+ * @typedef {Object} BaselineSettings
+ * Site identity and SEO configuration.
+ *
+ * @property {string} [title]
+ * @property {string} [tagline]
+ * @property {string} [url]
+ * @property {boolean} [noindex]
+ * @property {string} [defaultLanguage]
+ * @property {Record<string, unknown>} [languages]
+ * @property {Object} [head]
+ */
+
+/**
+ * @typedef {Object} BaselineOptions
+ * Runtime feature flags and behaviour configuration.
+ *
+ * User-facing input. Each module reads its own slice from `state.options.<module>`.
+ *
+ * @property {boolean} [verbose]
+ * Enables structured debug logging across modules.
+ *
+ * @property {boolean} [multilingual]
+ * Enables multilingual mode. Requires settings.defaultLanguage and
+ * settings.languages; the multilang module bails with a log otherwise.
+ *
+ * @property {boolean} [sitemap]
+ * Enables sitemap generation module (default: true).
+ *
+ * @property {boolean | { template?: boolean, inspectorDepth?: number }} [navigator]
+ * Controls navigator tooling. Boolean shorthand activates the module and
+ * the virtual debug page. Object form lets the page render flag and the
+ * inspector depth be tuned independently. Defaults to true in dev mode.
+ *
+ * @property {{ titleSeparator?: string, showGenerator?: boolean }} [head]
+ * Head module options.
+ *
+ * @property {{ esbuild?: { minify?: boolean, target?: string } }} [assets]
+ * Assets module options. The esbuild slice is permissive: any esbuild
+ * option is accepted; only `minify` and `target` are typed.
+ */
+
+/**
+ * @typedef {Object} BaselineState
+ * Fully resolved internal plugin state.
+ *
+ * @property {Object} settings
+ * @property {Object} options
+ */
+
+/**
+ * @typedef {Object} BaselineContext
+ * Shared module boundary contract.
+ *
+ * This context is the only supported interface between:
+ * - Eleventy configuration runtime
+ * - baseline core
+ * - feature modules
+ *
+ * @property {BaselineState} state
+ * @property {Object} runtime
+ * @property {Object} runtime.contentMap
+ * @property {Object} runtime.site
+ */
+
+export {};

package/core/utils/helpers.js

@@ -0,0 +1,75 @@
+import { TemplatePath } from '@11ty/eleventy-utils';
+import slugifyLib from 'slugify';
+
+/**
+ * Helper function to add trailing slash to a path
+ * @param {string} path
+ * @returns {string}
+ */
+export function addTrailingSlash(path) {
+	if (path.slice(-1) === '/') {
+		return path;
+	}
+	return path + '/';
+}
+
+/**
+ * Resolve a subdirectory under input and output.
+ * Joins inputDir/outputDir with rawDir, normalises, and adds trailing slashes.
+ * @param {string} inputDir - The input directory (e.g., "./src/").
+ * @param {string} outputDir - The output directory (e.g., "./dist/").
+ * @param {string} rawDir - Raw subdirectory value (e.g., "assets", "static").
+ * @returns {{input: string, output: string}}
+ */
+export function resolveSubdir(inputDir, outputDir, rawDir) {
+	const joinedInput = TemplatePath.join(inputDir, rawDir || '');
+	const joinedOutput = TemplatePath.join(outputDir, rawDir || '');
+
+	return {
+		input: addTrailingSlash(TemplatePath.standardizeFilePath(joinedInput)),
+		output: addTrailingSlash(TemplatePath.standardizeFilePath(joinedOutput))
+	};
+}
+
+/**
+ * Slugify a string into a wikilink-friendly key.
+ * Lowercases, strips diacritics, replaces non-alphanumerics with hyphens,
+ * trims leading/trailing hyphens. Returns null for empty input.
+ *
+ * @param {string|null|undefined} input
+ * @returns {string|null}
+ */
+export function slugify(input) {
+	if (input == null) return null;
+	const slug = slugifyLib(String(input), { lower: true, strict: true, trim: true });
+	return slug || null;
+}
+
+/**
+ * Normalize language input to an object map.
+ * Accepts an array of language codes or an object keyed by language code.
+ * Returns null if input is invalid or empty.
+ *
+ * @param {Object} settings - Options object containing languages.
+ * @param {import('../logging.js').BaselineLogger} [logger] - Logger for dropped-entry notice.
+ * @returns {Record<string, Object>|null} Normalized language map, or null.
+ */
+export function normalizeLanguages(settings, logger) {
+	const normalizedLanguages = Array.isArray(settings.languages)
+		? Object.fromEntries(
+				settings.languages
+					.filter((lang) => typeof lang === 'string' && lang.trim())
+					.map((lang) => [lang.toLowerCase().trim(), {}])
+			)
+		: settings.languages && typeof settings.languages === 'object'
+			? settings.languages
+			: null;
+
+	if (logger && Array.isArray(settings.languages)) {
+		const normalizedCount = normalizedLanguages ? Object.keys(normalizedLanguages).length : 0;
+		if (normalizedCount !== settings.languages.length) {
+			logger.info('Some languages entries were invalid and were dropped.');
+		}
+	}
+	return normalizedLanguages;
+}

package/core/utils/pick.js

@@ -0,0 +1,7 @@
+/**
+ * Return the first value that is neither undefined nor null.
+ * @param {...*} values
+ * @returns {*}
+ */
+const pick = (...values) => values.find((v) => v !== undefined && v !== null);
+export default pick;

package/core/virtual-dir.js

@@ -0,0 +1,111 @@
+import { TemplatePath } from '@11ty/eleventy-utils';
+import { resolveSubdir } from './utils/helpers.js';
+import { createLogger } from './logging.js';
+import { getScope, addScopeListener, setEntry } from './registry.js';
+
+/**
+ * Virtual directories (runtime substrate)
+ *
+ * Synthesises extra keys on eleventyConfig.directories (e.g. `assets`,
+ * `public`) that Eleventy itself won't accept, and keeps them in sync once
+ * Eleventy finalises its real directory map.
+ *
+ * Architecture layer:
+ *   runtime substrate
+ *
+ * System role:
+ *   Adds virtual dir keys consumed by modules (assets reads
+ *   `directories.assets`) and by the composition root (passthrough copy from
+ *   `directories.public`).
+ *
+ * Lifecycle:
+ *   build-time → synthesise key, pre-populate cache from eleventyConfig.dir
+ *   build-time → on `eleventy.directories`, refresh the cache to final paths
+ *
+ * Why this exists:
+ *   Eleventy's ProjectDirectories.setViaConfigObject() only honours input,
+ *   output, data, includes, and layouts. Extra `dir.*` keys are silently
+ *   ignored, and the `eleventy.directories` event exposes only the same set.
+ *   Synthesis fills the gap so consumers can read additional dirs the same
+ *   way they read the real ones.
+ *
+ * Scope:
+ *   Owns synthesis of extra `eleventyConfig.directories` keys, the live
+ *   cache, and a single shared listener for sync.
+ *   Does not own passthrough copy or watch wiring (composition root and
+ *   modules own those).
+ *
+ * Data flow:
+ *   { name, outputDir } → eleventyConfig.directories[name] getter →
+ *   live { input, output } cache → consumers
+ */
+
+const SCOPE_NAME = 'core:virtual-dir';
+
+/**
+ * Register a virtual directory on eleventyConfig.directories.
+ *
+ * @param {import('@11ty/eleventy').UserConfig} eleventyConfig
+ * @param {Object} options
+ * @param {string} options.key - Key to synthesise (e.g. 'assets', 'public').
+ * @param {string} [options.outputDir] - Override the output subdirectory. Defaults
+ *   to the raw dir value (symmetric with input). Pass `''` to resolve to the
+ *   output root (used by `public`, which copies to `/`).
+ * @returns {{input: string, output: string}} Live cache; properties refresh when
+ *   eleventy.directories fires. Safe to read at plugin-init time.
+ */
+export function registerVirtualDir(eleventyConfig, { key, outputDir } = {}) {
+	if (!key) {
+		throw new Error('registerVirtualDir: `name` is required');
+	}
+
+	const log = createLogger(SCOPE_NAME);
+	const scope = getScope(eleventyConfig, SCOPE_NAME);
+	const rawDir = eleventyConfig.dir?.[key] || key;
+	const rawOutputDir = outputDir ?? rawDir;
+	const cache = { input: null, output: null };
+
+	// Pre-populate from eleventyConfig.dir so synchronous readers at plugin-init
+	// time (watch globs, ignores, compile-guard prefixes) see a valid path.
+	syncCache(cache, eleventyConfig.dir || {}, rawDir, rawOutputDir);
+
+	setEntry(scope, key, { rawDir, rawOutputDir, cache });
+
+	// Define the virtual key once. The getter reads the live cache, which the
+	// shared listener below refreshes when Eleventy emits its final directories.
+	const existing = Object.getOwnPropertyDescriptor(eleventyConfig.directories, key);
+	if (existing && existing.configurable === false) {
+		log.info(`directories[${key}] already defined; skipping`);
+	} else {
+		Object.defineProperty(eleventyConfig.directories, key, {
+			get() {
+				return cache.input;
+			},
+			enumerable: true,
+			configurable: false
+		});
+	}
+
+	// One listener services all virtual dirs registered on this config.
+	// addScopeListener dedupes on ('eleventy.directories', 'sync'), so
+	// subsequent registerVirtualDir calls don't stack handlers.
+	addScopeListener(eleventyConfig, SCOPE_NAME, 'eleventy.directories', 'sync', (scope, dirs) => {
+		for (const entry of scope.values.values()) {
+			syncCache(entry.cache, dirs, entry.rawDir, entry.rawOutputDir);
+		}
+	});
+
+	log.info('Virtual directories mounted');
+
+	return cache;
+}
+
+function syncCache(cache, dirs, rawDir, rawOutputDir) {
+	const inputDir = TemplatePath.addLeadingDotSlash(dirs.input || './');
+	const outputDir = TemplatePath.addLeadingDotSlash(dirs.output || './');
+
+	// resolveSubdir symmetrically resolves against input and output; call twice
+	// so input and output subdirs can differ (e.g. `public` copies to root).
+	cache.input = resolveSubdir(inputDir, outputDir, rawDir).input;
+	cache.output = resolveSubdir(inputDir, outputDir, rawOutputDir).output;
+}