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

package/core/schema.js

@@ -1,5 +1,38 @@
 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),
@@ -25,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);

package/core/state.js

@@ -0,0 +1,73 @@
+/**
+ * State derivation (composition root helper)
+ *
+ * Pure normalisation of user-supplied `settings` and `options` into the
+ * resolved `state` shape modules read from. No eleventyConfig, no
+ * environment reads beyond the `mode` argument, no side effects.
+ *
+ * Architecture layer:
+ *   composition root (pure helper)
+ *
+ * System role:
+ *   The single place that applies defaults, fallbacks, and feature
+ *   inference. Extracted from the entry point so it can be reasoned
+ *   about — and tested — without booting Eleventy.
+ *
+ * Why this exists:
+ *   Keeping defaults and feature derivation tangled with eleventyConfig
+ *   wiring made the entry point hard to scan. Pulling the pure half out
+ *   leaves the composition root as a list of registration steps.
+ *
+ * Scope:
+ *   Owns settings/options normalisation and the derived `features` map.
+ *   Does not own validation (see core/schema.js) or any runtime wiring.
+ *
+ * Data flow:
+ *   settings + options + { mode } → { settings, options, features }
+ *
+ * @param {import('./types.js').BaselineSettings} settings
+ * @param {import('./types.js').BaselineOptions} options
+ * @param {{ mode?: string }} [env]
+ * @returns {import('./types.js').BaselineState & { features: Readonly<Record<string, boolean>> }}
+ */
+export function deriveBaselineState(settings, options, { mode } = {}) {
+	const isDev = mode === 'development';
+
+	const resolvedSettings = {
+		title: settings.title,
+		tagline: settings.tagline,
+		url: settings.url,
+		noindex: settings.noindex ?? false,
+		defaultLanguage: settings.defaultLanguage,
+		languages: settings.languages,
+		head: settings.head
+	};
+
+	const resolvedOptions = {
+		verbose: options.verbose ?? true,
+		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 ?? {}
+		}
+	};
+
+	const features = Object.freeze({
+		multilang: Boolean(resolvedOptions.multilang),
+		sitemap: Boolean(resolvedOptions.sitemap),
+		navigator: Boolean(resolvedOptions.navigator),
+		head: true,
+		assets: true
+	});
+
+	return Object.freeze({
+		settings: Object.freeze(resolvedSettings),
+		options: Object.freeze(resolvedOptions),
+		features
+	});
+}

package/core/{shortcodes/image.js → surface/image-shortcode.js}

@@ -1,10 +1,10 @@
 import path from 'node:path';
 import Image from '@11ty/eleventy-img';
-import { createLogger } from '../logging.js';
+import { createLogger } from '../logging/index.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 log = createLogger('image-shortcode');
 
 const DEFAULT_WIDTHS = [320, 640, 960, 1280, 1920, 'auto'];
 const DEFAULT_FORMATS = ['avif', 'webp'];
@@ -68,7 +68,7 @@ export async function imageShortcode(options = {}) {
 
 	// --- Validation and normalization ---
 
-	if (!src) throw new Error(`imageShortcode: src is required (received ${JSON.stringify(src)})`);
+	if (!src) throw new Error(`[baseline/image-shortcode] src is required (received ${JSON.stringify(src)})`);
 	if (alt == null) {
 		log.warn('alt is required (use empty string for decorative images)');
 	}
@@ -106,7 +106,7 @@ export async function imageShortcode(options = {}) {
 		});
 	} catch (error) {
 		if (process.env.ELEVENTY_RUN_MODE === 'serve') {
-			log.warn(`transformOnRequest failed for ${src}, retrying.\n > ${error?.message || error}`);
+			log.warn(`transformOnRequest failed for ${src}, retrying. ${error?.message || error}`);
 			metadata = await Image(resolvedSrc, imageOptions);
 		} else {
 			throw error;

package/core/surface/index.js

@@ -0,0 +1,22 @@
+/**
+ * Surface barrel
+ *
+ * Single entry point for everything Baseline registers against Eleventy that
+ * user templates can reach: filters, global functions, shortcodes.
+ */
+
+import { registerDateGlobal } from './global-date-function.js';
+
+// --- Filters ---
+export { markdownFilter } from '../markdown/markdownify.js';
+export { relatedPostsFilter } from './filters/related-posts.js';
+export { isStringFilter } from './filters/isString.js';
+
+// --- Shortcodes ---
+export { imageShortcode } from './image-shortcode.js';
+
+// --- Global functions (aggregator) ---
+/** @param {import("@11ty/eleventy").UserConfig} eleventyConfig */
+export function registerGlobals(eleventyConfig) {
+	registerDateGlobal(eleventyConfig);
+}

package/core/types.js

@@ -43,7 +43,7 @@
  * Head module options.
  *
  * @property {{ esbuild?: { minify?: boolean, target?: string } }} [assets]
- * Assets module options. The esbuild slice is permissive — any esbuild
+ * Assets module options. The esbuild slice is permissive: any esbuild
  * option is accepted; only `minify` and `target` are typed.
  */
 

package/core/utils/add-trailing-slash.js

@@ -0,0 +1,11 @@
+/**
+ * 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 + '/';
+}

package/core/utils/ensure-dot-slash-dir.js

@@ -0,0 +1,13 @@
+import { TemplatePath } from '@11ty/eleventy-utils';
+
+/**
+ * Normalise a directory path to a `./`-prefixed form, defaulting empty/missing
+ * input to the current directory. Thin wrapper over
+ * `TemplatePath.addLeadingDotSlash` that bakes in the empty-string fallback.
+ *
+ * @param {string | undefined} dir
+ * @returns {string}
+ */
+export function ensureDotSlashDir(dir) {
+	return TemplatePath.addLeadingDotSlash(dir || './');
+}

package/core/utils/normalize-languages.js

@@ -0,0 +1,28 @@
+/**
+ * Normalize language input to an object map.
+ * Accepts an array of language codes or an object keyed by language code.
+ * Returns undefined if input is invalid or empty.
+ *
+ * @param {Object} settings - Options object containing languages.
+ * @param {import('../logging/index.js').BaselineLogger} [logger] - Logger for dropped-entry notice.
+ * @returns {Record<string, Object>|undefined} Normalized language map, or undefined.
+ */
+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
+			: undefined;
+
+	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/resolve-field.js

@@ -0,0 +1,9 @@
+/**
+ * Resolve a field with a page → site → fallback precedence chain.
+ *
+ * @param {{ pageValue?: any, siteValue?: any, fallbackValue?: any, isHome?: boolean }} args
+ * @returns {any}
+ */
+export function resolveField({ pageValue, siteValue, fallbackValue }) {
+	return pageValue ?? siteValue ?? fallbackValue;
+}

package/core/utils/resolve-subdir.js

@@ -0,0 +1,20 @@
+import { TemplatePath } from '@11ty/eleventy-utils';
+import { addTrailingSlash } from './add-trailing-slash.js';
+
+/**
+ * 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))
+	};
+}

package/core/utils/slugify.js

@@ -0,0 +1,15 @@
+import slugifyLib from 'slugify';
+
+/**
+ * Slugify a string into a wikilink-friendly key.
+ * Lowercases, strips diacritics, replaces non-alphanumerics with hyphens,
+ * trims leading/trailing hyphens. Returns undefined for empty input.
+ *
+ * @param {string|null|undefined} input
+ * @returns {string|undefined}
+ */
+export function slugify(input) {
+	if (input == null) return;
+	const slug = slugifyLib(String(input), { lower: true, strict: true, trim: true });
+	return slug || undefined;
+}

package/core/utils/unique-by.js

@@ -0,0 +1,25 @@
+/**
+ * Deduplicate an array by a key (string property name or selector function).
+ * Items without a derivable key are kept via their JSON-stringified shape.
+ *
+ * @template T
+ * @param {T[]} arr
+ * @param {string | ((item: T) => string | undefined)} keyFn
+ * @returns {T[]}
+ */
+export const uniqueBy = (arr, keyFn) =>
+	Object.values(
+		(arr ?? []).reduce((acc, item) => {
+			if (!item) return acc;
+
+			const id = typeof keyFn === 'function' ? keyFn(item) : item?.[keyFn];
+
+			if (!id) {
+				acc[JSON.stringify(item)] = item;
+				return acc;
+			}
+
+			acc[id] = item;
+			return acc;
+		}, {})
+	);

package/core/virtual-dir.js

@@ -1,8 +1,11 @@
-import { TemplatePath } from '@11ty/eleventy-utils';
-import { resolveSubdir } from './utils/helpers.js';
-import { createLogger } from './logging.js';
+import { ensureDotSlashDir } from './utils/ensure-dot-slash-dir.js';
+import { resolveSubdir } from './utils/resolve-subdir.js';
+import { createLogger } from './logging/index.js';
 import { getScope, addScopeListener, setEntry } from './registry.js';
 
+const SCOPE_NAME = 'core:virtual-dir';
+const LOG_NAME = 'virtual-dir';
+
 /**
  * Virtual directories (runtime substrate)
  *
@@ -40,8 +43,6 @@ import { getScope, addScopeListener, setEntry } from './registry.js';
  *   live { input, output } cache → consumers
  */
 
-const SCOPE_NAME = 'core:virtual-dir';
-
 /**
  * Register a virtual directory on eleventyConfig.directories.
  *
@@ -56,10 +57,10 @@ const SCOPE_NAME = 'core:virtual-dir';
  */
 export function registerVirtualDir(eleventyConfig, { key, outputDir } = {}) {
 	if (!key) {
-		throw new Error('registerVirtualDir: `name` is required');
+		throw new Error('[baseline/virtual-dir] `name` is required');
 	}
 
-	const log = createLogger(SCOPE_NAME);
+	const log = createLogger(LOG_NAME);
 	const scope = getScope(eleventyConfig, SCOPE_NAME);
 	const rawDir = eleventyConfig.dir?.[key] || key;
 	const rawOutputDir = outputDir ?? rawDir;
@@ -75,7 +76,7 @@ export function registerVirtualDir(eleventyConfig, { key, outputDir } = {}) {
 	// 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`);
+		log.info(`directories.${key} already defined, skipping`);
 	} else {
 		Object.defineProperty(eleventyConfig.directories, key, {
 			get() {
@@ -101,8 +102,8 @@ export function registerVirtualDir(eleventyConfig, { key, outputDir } = {}) {
 }
 
 function syncCache(cache, dirs, rawDir, rawOutputDir) {
-	const inputDir = TemplatePath.addLeadingDotSlash(dirs.input || './');
-	const outputDir = TemplatePath.addLeadingDotSlash(dirs.output || './');
+	const inputDir = ensureDotSlashDir(dirs.input);
+	const outputDir = ensureDotSlashDir(dirs.output);
 
 	// resolveSubdir symmetrically resolves against input and output; call twice
 	// so input and output subdirs can differ (e.g. `public` copies to root).