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

package/core/dates/git-date.js

@@ -0,0 +1,71 @@
+import { execFileSync } from 'node:child_process';
+import path from 'node:path';
+
+let cache = null;
+
+// Build a { repoRelativePath: ISO date } map from one `git log` walk.
+// Each commit emits its date, then the files it touched; first date wins
+// because git log is newest-first.
+function buildCache() {
+	const map = new Map();
+	const marker = '__BASELINE_COMMIT__';
+	let raw;
+	try {
+		raw = execFileSync(
+			'git',
+			['log', '--name-only', '--no-renames', `--pretty=format:${marker}%cI`],
+			{ encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 }
+		);
+	} catch {
+		return map;
+	}
+
+	let currentDate = null;
+	for (const line of raw.split('\n')) {
+		if (line.startsWith(marker)) {
+			// Normalise to UTC so all outputs (sitemap, JSON-LD, schemamap) match.
+			currentDate = new Date(line.slice(marker.length)).toISOString();
+		} else if (line && currentDate && !map.has(line)) {
+			map.set(line, currentDate);
+		}
+	}
+	return map;
+}
+
+function normalize(inputPath) {
+	const abs = path.resolve(inputPath);
+	const rel = path.relative(process.cwd(), abs);
+	return rel.split(path.sep).join('/');
+}
+
+/**
+ * Last-commit date (UTC ISO) for a file, or `null` when git has no record of
+ * it (untracked, or no git history available — e.g. a shallow CI clone).
+ *
+ * Unlike the docs-site copy this carries no mtime/now fallback: the date floor
+ * is `page.date`, applied by `resolveDates`, so this stays a pure "what does
+ * git say, or nothing" lookup.
+ *
+ * @param {string} inputPath
+ * @returns {string | null}
+ */
+export function gitModified(inputPath) {
+	if (!cache) cache = buildCache();
+	return cache.get(normalize(inputPath)) ?? null;
+}
+
+/**
+ * The most recent `gitModified` across several paths, or `null` if none resolve.
+ *
+ * @param {Array<string | undefined | null>} inputPaths
+ * @returns {string | null}
+ */
+export function maxGitModified(inputPaths) {
+	let max = null;
+	for (const p of inputPaths) {
+		if (!p) continue;
+		const iso = gitModified(p);
+		if (iso && (!max || iso > max)) max = iso;
+	}
+	return max;
+}

package/core/dates/index.js

@@ -0,0 +1,55 @@
+/**
+ * Dates substrate
+ *
+ * One home for date concerns: the Nunjucks `date` global (formatting), the
+ * git-backed last-commit lookup, and `resolveDates` — the single source for a
+ * page's publish/modified dates that the seo-graph substrate and any other
+ * consumer read from instead of re-deriving the chain.
+ */
+
+import { gitModified, maxGitModified } from './git-date.js';
+
+export { registerDateGlobal } from './date-global.js';
+export { gitModified, maxGitModified };
+
+/** Coerce a value to a valid `Date`, or `undefined` if it can't be parsed. */
+function toDate(value) {
+	if (!value) return undefined;
+	const d = value instanceof Date ? value : new Date(value);
+	return Number.isNaN(d.getTime()) ? undefined : d;
+}
+
+/**
+ * Resolve a page's publish and modified dates from one place. All three author
+ * keys are optional; the chain degrades to `page.date`, which Eleventy always
+ * backfills (front matter, else file birthtime), so output is never empty.
+ *
+ * - `datePublished` → front-matter `datePublished` → `page.date` (the floor).
+ * - `dateModified` → front-matter `dateModified` → git last-commit → resolved
+ *   `datePublished`.
+ *
+ * `git-date` is the middle rung of the modified chain and is allowed to yield
+ * nothing; flooring `dateModified` to the *resolved* `datePublished` (not raw
+ * `page.date`) keeps the pair coherent when an author overrides `datePublished`.
+ * No clamp to `modified >= published`: a scheduled post can legitimately be
+ * modified before its publish date.
+ *
+ * Takes the full cascade `data` bag (matches the substrate convention) and
+ * returns normalised `Date` objects, ready for the seo-graph piece builders.
+ *
+ * `gitLookup` is an injection seam for tests; production calls pass `data` only
+ * and get the real git-backed lookup.
+ *
+ * @param {{ page?: any, datePublished?: unknown, dateModified?: unknown }} data
+ * @param {(inputPath: string) => string | null} [gitLookup]
+ * @returns {{ datePublished: Date | undefined, dateModified: Date | undefined }}
+ */
+export function resolveDates(data, gitLookup = gitModified) {
+	const page = data?.page ?? {};
+	const datePublished = toDate(data?.datePublished) ?? toDate(page.date);
+	const dateModified =
+		toDate(data?.dateModified) ??
+		toDate(page.inputPath ? gitLookup(page.inputPath) : null) ??
+		datePublished;
+	return { datePublished, dateModified };
+}

package/core/locale/derive-lang.js

@@ -0,0 +1,19 @@
+/**
+ * Extract the short language subtag from a BCP 47 tag.
+ *
+ * `'en-US'` → `'en'`, `'zh-Hant-HK'` → `'zh'`. Normalises via `Intl.Locale`;
+ * null for empty input or tags it rejects.
+ *
+ * @param {unknown} locale
+ * @returns {string | null}
+ */
+export function deriveLang(locale) {
+	if (locale == null) return null;
+	const str = String(locale).trim();
+	if (str === '') return null;
+	try {
+		return new Intl.Locale(str).language;
+	} catch {
+		return null;
+	}
+}

package/core/locale/index.js

@@ -0,0 +1,6 @@
+export { normalizeLang } from './normalize-lang.js';
+export { normalizeLocale } from './normalize-locale.js';
+export { deriveLang } from './derive-lang.js';
+export { resolveDefault } from './resolve-default.js';
+export { resolveLocale } from './resolve-locale.js';
+export { toOpenGraphLocale } from './open-graph-locale.js';

package/core/locale/normalize-lang.js

@@ -0,0 +1,13 @@
+/**
+ * Normalize a short language code: lowercase and trim.
+ *
+ * The substrate's lightest helper. Empty string for null/undefined; coerces
+ * non-string input via `String()`.
+ *
+ * @param {unknown} raw
+ * @returns {string}
+ */
+export function normalizeLang(raw) {
+	if (raw == null) return '';
+	return String(raw).toLowerCase().trim();
+}

package/core/locale/normalize-locale.js

@@ -0,0 +1,20 @@
+/**
+ * Normalize a BCP 47 locale tag to conventional casing using `Intl.Locale`.
+ *
+ * `Intl.Locale` handles language-script-region casing and subtag rules without
+ * reimplementing the spec. Returns null for empty/whitespace input or tags it
+ * rejects.
+ *
+ * @param {unknown} raw
+ * @returns {string | null}
+ */
+export function normalizeLocale(raw) {
+	if (raw == null) return null;
+	const str = String(raw).trim();
+	if (str === '') return null;
+	try {
+		return new Intl.Locale(str).toString();
+	} catch {
+		return null;
+	}
+}

package/core/locale/open-graph-locale.js

@@ -0,0 +1,14 @@
+import { normalizeLocale } from './normalize-locale.js';
+
+/**
+ * Format a BCP 47 tag in Open Graph's `language_TERRITORY` form (`en-US` →
+ * `en_US`). Normalises casing first; null for tags `Intl.Locale` rejects.
+ * `replaceAll` so script+region tags convert fully (`zh-Hant-HK` → `zh_Hant_HK`).
+ *
+ * @param {unknown} raw  A BCP 47 locale tag.
+ * @returns {string | null}
+ */
+export function toOpenGraphLocale(raw) {
+	const normalized = normalizeLocale(raw);
+	return normalized ? normalized.replaceAll('-', '_') : null;
+}

package/core/locale/resolve-default.js

@@ -0,0 +1,27 @@
+import { normalizeLang } from './normalize-lang.js';
+import { normalizeLocale } from './normalize-locale.js';
+import { deriveLang } from './derive-lang.js';
+
+/**
+ * Resolve the effective `{ lang, locale }` default from settings.
+ *
+ * defaultLocale wins; defaultLanguage is a writer-side alias. Given only
+ * defaultLanguage, locale is derived via `Intl.Locale`.
+ *
+ * @param {{ defaultLanguage?: string, defaultLocale?: string }} settings
+ * @returns {{ lang: string, locale: string | null }}
+ */
+export function resolveDefault(settings) {
+	const explicitLang = normalizeLang(settings?.defaultLanguage);
+	const explicitLocale = normalizeLocale(settings?.defaultLocale);
+
+	if (explicitLocale) {
+		return { lang: deriveLang(explicitLocale) ?? explicitLang, locale: explicitLocale };
+	}
+
+	if (explicitLang) {
+		return { lang: explicitLang, locale: normalizeLocale(explicitLang) ?? explicitLang };
+	}
+
+	return { lang: '', locale: null };
+}

package/core/locale/resolve-locale.js

@@ -0,0 +1,16 @@
+/**
+ * Pick the page's BCP 47 locale out of the cascade.
+ *
+ * Reads, never normalises — trusts multilang's already-resolved `page.locale`
+ * first, then bag-level locale, the language's configured locale, and the bare
+ * `lang` tag last.
+ *
+ * @param {{ locale?: string } | undefined} node  The navigator node, if any.
+ * @param {Record<string, any>} data  The Eleventy cascade data bag.
+ * @param {{ languages?: Record<string, { locale?: string }> } | undefined} settings
+ * @param {string} lang  Resolved language subtag; the final fallback.
+ * @returns {string}
+ */
+export function resolveLocale(node, data, settings, lang) {
+	return node?.locale || data?.page?.locale || data?.locale || settings?.languages?.[lang]?.locale || lang;
+}

package/core/logging/banner.js

@@ -0,0 +1,49 @@
+import chalk from 'kleur';
+
+const BANNER_GLOBAL_KEY = Symbol.for('eleventy:baseline:banner');
+const FALLBACK_NAME = 'Eleventy Baseline';
+const MARGIN = 4;
+
+/**
+ * Resolve the label shown inside the banner. Reads `npm_package_name`
+ * (set by npm when Baseline runs under `npm run …`) and falls back to
+ * the plugin's own name when the env var is absent (raw `npx`, direct
+ * node, programmatic use).
+ *
+ * @returns {string}
+ */
+function resolveBannerLabel() {
+	return process.env.npm_package_name || FALLBACK_NAME;
+}
+
+/**
+ * Render the boxed startup banner string. Pure, label-only.
+ * Width scales with the label so any project name fits.
+ *
+ * @param {string} [label]
+ * @returns {string}
+ */
+export function baselineBanner(label = resolveBannerLabel()) {
+	const inner = label.length + MARGIN * 2;
+	const top = '╔' + '═'.repeat(inner) + '╗';
+	const middle = '║' + ' '.repeat(MARGIN) + chalk.bold().white(label) + ' '.repeat(MARGIN) + '║';
+	const bottom = '╚' + '═'.repeat(inner) + '╝';
+
+	return ['', top, middle, bottom, ''].join('\n');
+}
+
+/**
+ * Print the banner and an intro line once per process. Guarded by a global
+ * symbol so repeated plugin invocations (inner pre-pass Eleventy,
+ * multi-instance setups) don't re-print.
+ *
+ * @param {import('./index.js').BaselineLogger} log
+ * @param {{ version: string, eleventyVersion?: string }} versions
+ */
+export function printBannerOnce(log, { version, eleventyVersion } = {}) {
+	if (globalThis[BANNER_GLOBAL_KEY]) return;
+	globalThis[BANNER_GLOBAL_KEY] = true;
+	log.print(baselineBanner());
+	const tail = eleventyVersion ? `, running Eleventy v${eleventyVersion}` : '';
+	log.info(`Baseline v${version}${tail}`);
+}

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]
  */
@@ -88,7 +88,7 @@ export function wikilinks(md, { slugIndex, pageContextRegistry, translationMapSt
 		}
 
 		const lang = rawLang.toLowerCase();
-		const translationKey = ctx?.page?.locale?.translationKey;
+		const translationKey = ctx?.page?.translationKey;
 		if (!translationKey) return null;
 
 		const map = translationMapStore?.get?.();
@@ -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);
 }