@apleasantview/eleventy-plugin-baseline 0.1.0-next.32 → 0.1.0-next.39

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;
+}

package/core/wikilinks.js

@@ -0,0 +1,152 @@
+import { slugify } from './utils/helpers.js';
+
+/**
+ * WIKILINKS (filter)
+ *
+ * MediaWiki-style inline link syntax for body markdown. Recognises
+ * [[slug]], [[slug#anchor]], [[slug:lang]], [[slug|alias]], and any
+ * combination. Resolves slugs against the slug index and, when a lang
+ * suffix is given, hops to the requested translation. Misses render as
+ * the original literal text.
+ *
+ * Architecture layer:
+ *   runtime substrate
+ *
+ * System role:
+ *   Markdown-it plugin registered by the composition root via
+ *   amendLibrary('md', ...). Reads the slug index, page-context registry,
+ *   and translation-map store; writes nothing back.
+ *
+ * Lifecycle:
+ *   transform-time → parses [[...]] in body markdown and emits link or
+ *                    text tokens
+ *
+ * Why this exists:
+ *   Markdown-it has no wiki-link syntax. Eleventy resolves all
+ *   eleventyComputed values before any body renders, so the slug index
+ *   and translation map are complete by the time this rule fires —
+ *   resolution is deterministic without a two-pass build.
+ *
+ * Scope:
+ *   Owns syntax parsing, slug-to-href resolution, the lang hop, and link
+ *   rendering with class/lang/hreflang attributes.
+ *   Does not own slug derivation (page-context), index population, or the
+ *   translation-map shape (multilang module).
+ *
+ * Data flow:
+ *   markdown-it inline state → slug index + page context + translation map → link tokens
+ *
+ * @param {import('markdown-it').default} md
+ * @param {Object} deps
+ * @param {{getBySlug: (slug: string) => string | null}} deps.slugIndex
+ * @param {{getByKey: (url: string) => any}} deps.pageContextRegistry
+ * @param {{get: () => Record<string, Record<string, {url: string, title?: string}>> | null}} [deps.translationMapStore]
+ */
+export function wikilinks(md, { slugIndex, pageContextRegistry, translationMapStore } = {}) {
+	if (!slugIndex || !pageContextRegistry) {
+		throw new Error('wikilinks plugin requires { slugIndex, pageContextRegistry }');
+	}
+
+	function parse(inner) {
+		// [[target|alias]]
+		const pipeIdx = inner.indexOf('|');
+		const target = pipeIdx === -1 ? inner : inner.slice(0, pipeIdx);
+		const alias = pipeIdx === -1 ? null : inner.slice(pipeIdx + 1).trim() || null;
+
+		// [[slug-or-langed#anchor]]
+		const hashIdx = target.indexOf('#');
+		const slugAndLang = hashIdx === -1 ? target : target.slice(0, hashIdx);
+		const rawAnchor = hashIdx === -1 ? null : target.slice(hashIdx + 1).trim() || null;
+		const anchor = rawAnchor ? slugify(rawAnchor) : null;
+
+		// [[slug:lang]]
+		const colonIdx = slugAndLang.indexOf(':');
+		const rawSlug = colonIdx === -1 ? slugAndLang : slugAndLang.slice(0, colonIdx);
+		const rawLang = colonIdx === -1 ? null : slugAndLang.slice(colonIdx + 1).trim() || null;
+
+		return { rawSlug: rawSlug.trim(), rawLang, anchor, alias };
+	}
+
+	function resolve({ rawSlug, rawLang, anchor, alias }) {
+		const slug = slugify(rawSlug);
+		if (!slug) return null;
+
+		const url = slugIndex.getBySlug(slug);
+		if (!url) return null;
+
+		const ctx = pageContextRegistry.getByKey(url);
+		const defaultTitle = ctx?.entry?.title ?? rawSlug;
+
+		const withAnchor = (u) => (anchor ? `${u}#${anchor}` : u);
+
+		if (!rawLang) {
+			return {
+				href: withAnchor(url),
+				label: alias ?? defaultTitle,
+				lang: null
+			};
+		}
+
+		const lang = rawLang.toLowerCase();
+		const translationKey = ctx?.page?.locale?.translationKey;
+		if (!translationKey) return null;
+
+		const map = translationMapStore?.get?.();
+		const entry = map?.[translationKey]?.[lang];
+		if (!entry) return null;
+
+		return {
+			href: withAnchor(entry.url),
+			label: alias ?? entry.title ?? defaultTitle,
+			lang
+		};
+	}
+
+	function tokenize(state, silent) {
+		const start = state.pos;
+		const src = state.src;
+
+		if (src.charCodeAt(start) !== 0x5b /* [ */) return false;
+		if (src.charCodeAt(start + 1) !== 0x5b) return false;
+
+		const end = src.indexOf(']]', start + 2);
+		if (end === -1) return false;
+
+		const inner = src.slice(start + 2, end);
+		// Reject nested brackets to keep the rule unambiguous.
+		if (inner.includes('[') || inner.includes(']')) return false;
+
+		if (silent) {
+			state.pos = end + 2;
+			return true;
+		}
+
+		const literal = src.slice(start, end + 2);
+		const parsed = parse(inner);
+		const result = resolve(parsed);
+
+		if (!result) {
+			const t = state.push('text', '', 0);
+			t.content = literal;
+		} else {
+			const open = state.push('link_open', 'a', 1);
+			const attrs = [
+				['href', result.href],
+				['class', 'wikilink']
+			];
+			if (result.lang) {
+				attrs.push(['lang', result.lang]);
+				attrs.push(['hreflang', result.lang]);
+			}
+			open.attrs = attrs;
+			const text = state.push('text', '', 0);
+			text.content = result.label;
+			state.push('link_close', 'a', -1);
+		}
+
+		state.pos = end + 2;
+		return true;
+	}
+
+	md.inline.ruler.before('link', 'wikilink', tokenize);
+}

package/index.js

@@ -0,0 +1,364 @@
+import 'dotenv/config';
+import { createRequire } from 'node:module';
+
+import { HtmlBasePlugin } from '@11ty/eleventy';
+import { eleventyImageOnRequestDuringServePlugin } from '@11ty/eleventy-img';
+
+import { createLogger } from './core/logging.js';
+import { createContentMapStore } from './core/content-map-store.js';
+import { createTranslationMapStore } from './core/translation-map-store.js';
+import { createSlugIndex } from './core/slug-index.js';
+import { registerVirtualDir } from './core/virtual-dir.js';
+import { registerPageContext } from './core/page-context.js';
+import { wikilinks } from './core/wikilinks.js';
+import { settingsSchema } from './core/schema.js';
+
+import { registerGlobals } from './core/global-functions/index.js';
+import { markdownFilter, relatedPostsFilter, isStringFilter } from './core/filters/index.js';
+import { imageShortcode } from './core/shortcodes/index.js';
+import { assetsCore, headCore, multilangCore, navigatorCore, sitemapCore } from './modules.js';
+
+const __require = createRequire(import.meta.url);
+const { name, version } = __require('./package.json');
+
+const mode = process.env.ELEVENTY_ENV;
+const isDev = mode === 'development';
+const isProd = mode === 'production';
+
+const LEGACY_OPTION_KEYS = [
+	'verbose',
+	'enableNavigatorTemplate',
+	'enableSitemapTemplate',
+	'assetsESBuild',
+	'multilingual'
+];
+
+// Whitelist of reserved global data keys used internally across the plugin.
+// Positive side effect is they all get listed in order and merge data to the same key.
+// Also prevents name collision with filters.
+const INTERNAL_KEYS = [
+	'_baseline',
+	'_assets',
+	'_head',
+	'_multilang',
+	'_navigator',
+	'_sitemap',
+	'_snapshot',
+	'_pageContext'
+];
+
+/**
+ * Detect legacy single-object plugin invocation.
+ *
+ * The original plugin API accepted a single merged configuration object.
+ * This helper detects that shape and enables safe normalization into
+ * the current (settings, options) contract.
+ *
+ * NOTE: arguments.length is required because default parameters mask arity.
+ */
+function looksLikeLegacyOptions(firstArg, argsLength) {
+	if (argsLength >= 2) return false;
+	if (!firstArg || typeof firstArg !== 'object') return false;
+	return LEGACY_OPTION_KEYS.some((key) => key in firstArg);
+}
+
+/**
+ * Normalize legacy plugin input into the current structured contract.
+ *
+ * - settings → site identity (content + SEO concerns)
+ * - options  → runtime behavior flags
+ */
+function splitLegacyOptions(legacy) {
+	const { defaultLanguage, languages, ...rest } = legacy;
+	return {
+		settings: { defaultLanguage, languages },
+		options: rest
+	};
+}
+
+/**
+ * Baseline (composition root)
+ *
+ * Eleventy plugin entry point. Normalises user input, builds the runtime
+ * substrate (stores + page-context registry), and registers feature modules
+ * in deterministic order.
+ *
+ * Architecture layer:
+ *   composition root
+ *
+ * System role:
+ *   The single place that wires settings + options into state, attaches
+ *   lifecycle stores, registers the page-context registry, and hands a
+ *   uniform module context to each module. No feature behaviour lives here.
+ *
+ * Lifecycle:
+ *   build-time → legacy-shape detection, state computation, virtual dir
+ *                registration, store and page-context registration, module
+ *                wiring
+ *
+ * Why this exists:
+ *   Modules need a stable, normalised input contract and a shared runtime
+ *   surface. Centralising the wiring keeps activation rules, option
+ *   inference, and registration order in one auditable place.
+ *
+ * Scope:
+ *   Owns the legacy-shape compatibility shim, state computation, runtime
+ *   store creation, page-context registration, and the module registry.
+ *   Does not own any feature behaviour; modules implement that.
+ *
+ * Data flow:
+ *   settings + options → state → runtime stores + page-context registry →
+ *   modules
+ *
+ * Typedefs (BaselineSettings, BaselineOptions, BaselineState, BaselineContext)
+ * live in core/types.js.
+ *
+ * @param {import('./core/types.js').BaselineSettings} [settings]
+ * @param {import('./core/types.js').BaselineOptions} [options]
+ */
+export default function baseline(settings = {}, options = {}) {
+	// --- Legacy compatibility layer ---
+	const argsLength = arguments.length;
+	const wasLegacy = looksLikeLegacyOptions(settings, argsLength);
+
+	if (wasLegacy) {
+		const split = splitLegacyOptions(settings);
+		settings = split.settings;
+		options = split.options;
+	}
+
+	// Base logger outputs regardless of options.
+	const baseLog = createLogger(null, { verbose: true });
+
+	// Scoped logging.
+	function scopedLog(name) {
+		return createLogger(name, { verbose: options.verbose });
+	}
+
+	if (wasLegacy) {
+		baseLog.info('DEPRECATED: single-object plugin arg. Use baseline(settings, options) instead.');
+	}
+
+	// Validate configuration shape (non-fatal).
+	const parsed = settingsSchema.safeParse(settings);
+	if (!parsed.success) {
+		for (const issue of parsed.error.issues) {
+			baseLog.info('settings:', `${issue.path.join('.')} — ${issue.message}`);
+		}
+	}
+
+	baseLog.info('Eleventy Baseline', version);
+
+	/**
+	 * Eleventy plugin initializer.
+	 *
+	 * This function is executed during Eleventy configuration time and
+	 * composes global APIs, filters, shortcodes, and feature modules.
+	 */
+	const plugin = async function (eleventyConfig) {
+		// --- Eleventy compatibility check ---
+		try {
+			eleventyConfig.versionCheck('>=3.0');
+		} catch (e) {
+			baseLog.error('Eleventy version mismatch:', e.message);
+		}
+
+		INTERNAL_KEYS.forEach((key) => {
+			eleventyConfig.addGlobalData(key, {});
+		});
+
+		const env = {
+			name: 'Eleventy Baseline',
+			package: name,
+			version,
+			mode
+		};
+
+		eleventyConfig.addGlobalData('_baseline', {
+			env
+		});
+
+		if (!settings.url) {
+			baseLog.warn('settings.url missing — canonical URLs will be relative');
+		}
+
+		registerGlobals(eleventyConfig);
+
+		eleventyConfig.addPlugin(HtmlBasePlugin, {
+			baseHref: process.env.URL || eleventyConfig.pathPrefix
+		});
+
+		// --- State layer (authoritative configuration) ---
+		const hasImageTransformPlugin = eleventyConfig.hasPlugin('eleventyImageTransformPlugin');
+
+		const state = {
+			settings: {
+				title: settings.title,
+				tagline: settings.tagline,
+				url: settings.url,
+				noindex: settings.noindex ?? false,
+				defaultLanguage: settings.defaultLanguage,
+				languages: settings.languages,
+				head: settings.head
+			},
+
+			options: {
+				verbose: options.verbose ?? false,
+				multilang: options.multilingual ?? false,
+				sitemap: options.sitemap ?? options.enableSitemapTemplate ?? true,
+				navigator: options.navigator ?? options.enableNavigatorTemplate ?? isDev,
+				head: {
+					titleSeparator: options.head?.titleSeparator,
+					showGenerator: options.head?.showGenerator
+				},
+				assets: {
+					esbuild: options.assets?.esbuild ?? options.assetsESBuild ?? {}
+				}
+			}
+		};
+
+		eleventyConfig.addGlobalData('_baseline', {
+			features: {
+				...state.options,
+				hasImageTransformPlugin
+			}
+		});
+
+		// --- Virtual directories ---
+		registerVirtualDir(eleventyConfig, {
+			key: 'assets'
+		});
+
+		const publicDir = registerVirtualDir(eleventyConfig, {
+			key: 'public',
+			outputDir: ''
+		});
+
+		const directories = {
+			input: eleventyConfig.directories?.input,
+			output: eleventyConfig.directories?.output,
+			includes: eleventyConfig.directories?.includes,
+			data: eleventyConfig.directories?.data,
+			assets: eleventyConfig.directories?.assets,
+			public: eleventyConfig.directories?.public
+		};
+
+		eleventyConfig.addPassthroughCopy({ [publicDir.input]: '/' });
+
+		// Add paths to global.
+		eleventyConfig.addGlobalData('_baseline', {
+			paths: {
+				...directories
+			}
+		});
+
+		// --- Draft filtering (build-time concern) ---
+		if (!eleventyConfig.preprocessors.drafts) {
+			eleventyConfig.addPreprocessor('drafts', '*', (data) => {
+				if (data.draft && process.env.ELEVENTY_RUN_MODE === 'build') {
+					return false;
+				}
+			});
+		}
+
+		// --- Runtime stores (self-attach their lifecycle listeners) ---
+		const contentMapStore = createContentMapStore(eleventyConfig);
+		const translationMapStore = createTranslationMapStore(eleventyConfig);
+		const slugIndex = createSlugIndex(eleventyConfig);
+
+		// --- Module helpers (derived state) ---
+		const helpers = {};
+
+		// --- Core context (lazy access layer) ---
+		const coreContext = {
+			env,
+			state,
+			runtime: {
+				get contentMap() {
+					return contentMapStore.get();
+				},
+				translationMap: translationMapStore,
+				slugIndex
+			},
+			directories,
+			helpers
+		};
+
+		// Page context registry
+		const pageContextRegistry = registerPageContext(eleventyConfig, coreContext);
+
+		// Wikilinks: [[slug]] / [[slug | lang]] in body markdown.
+		eleventyConfig.amendLibrary('md', (md) => {
+			md.use(wikilinks, { slugIndex, pageContextRegistry, translationMapStore });
+		});
+
+		coreContext.snapshots = {
+			contentMap: () => contentMapStore.snapshot(),
+			pageContext: () => pageContextRegistry.snapshot()
+		};
+
+		// --- Module activation ---
+		const features = {
+			multilang: Boolean(state.options.multilang),
+			sitemap: Boolean(state.options.sitemap),
+			navigator: Boolean(state.options.navigator),
+			head: true,
+			assets: true
+		};
+
+		// --- Module registry ---
+		const moduleRegistry = [
+			{ when: features.multilang, name: 'multilang', plugin: multilangCore },
+			{ when: features.sitemap, name: 'sitemap', plugin: sitemapCore },
+			{ name: 'navigator', plugin: navigatorCore },
+			{ when: features.head, name: 'head', plugin: headCore, consumes: { pageContext: true } },
+			{ when: features.assets, name: 'assets', plugin: assetsCore }
+		];
+
+		for (const entry of moduleRegistry) {
+			const { when = true, name, plugin, consumes = {} } = entry;
+			if (!when) continue;
+			const moduleContext = {
+				...coreContext,
+				log: scopedLog(name),
+				resolvePageContext: consumes.pageContext ? pageContextRegistry : null
+			};
+
+			eleventyConfig.addPlugin(plugin, moduleContext);
+		}
+
+		// --- Filters ---
+		eleventyConfig.addFilter('markdownify', markdownFilter);
+		eleventyConfig.addFilter('relatedPosts', relatedPostsFilter);
+		eleventyConfig.addFilter('isString', isStringFilter);
+
+		// --- Shortcodes ---
+		eleventyConfig.addShortcode('image', imageShortcode);
+
+		// --- Dev image pipeline ---
+		eleventyConfig.addPlugin(eleventyImageOnRequestDuringServePlugin);
+	};
+
+	// Set a named function identity so eleventyConfig.hasPlugin() can detect this plugin.
+	Object.defineProperty(plugin, 'name', { value: name });
+	return plugin;
+}
+
+/**
+ * Eleventy directory configuration (external contract)
+ *
+ * Defines input/output structure for the build system.
+ */
+export const config = {
+	dir: {
+		input: 'src',
+		output: 'dist',
+		data: '_data',
+		includes: '_includes',
+		assets: 'assets',
+		public: 'static'
+	},
+	htmlTemplateEngine: 'njk',
+	markdownTemplateEngine: 'njk',
+	templateFormats: ['html', 'njk', 'md']
+};