scavold 0.2.0-rc.1

package/lib/pages.js

@@ -0,0 +1,494 @@
+import { pathToFileURL } from "node:url";
+import { relative, resolve } from "node:path/posix";
+import { glob, readFile } from "node:fs/promises";
+import YAML from "yaml";
+
+const ptnIsIndexPage = /(^|\/)index\.md$/;
+
+/**
+ * Delivers absolute path name of folder containing Markdown documents per page.
+ *
+ * @param {UserConfig} config Vitepress site configuration
+ * @returns {string} absolute path name of folder containing all Markdown files each representing a page
+ */
+export function sourceFolder( config ) {
+	return resolve( config.srcDir ?? "." );
+}
+
+/**
+ * Qualifies a path name of some target page optionally relative to some given
+ * reference page into a path name relative to the same base as provided
+ * reference.
+ *
+ * @param {string} from path name of reference page
+ * @param {string} to path name of target page, might be absolute URL
+ * @param {boolean} localOnly if true, absolute URLs as target are rejected
+ * @returns {string} path name of target page relative to same base as reference page
+ * @throws TypeError if target page URL is an absolute URL and localOnly has been set
+ */
+export function qualifyRedirect( from, to, localOnly = false ) {
+	const cwd = resolve( "" );
+	const target = new URL( to, pathToFileURL( resolve( cwd, from ) ) );
+
+	if ( target.protocol === "file:" ) {
+		return relative( pathToFileURL( cwd ).toString(), target.toString() );
+	}
+
+	if ( localOnly ) {
+		throw new TypeError( `non-local redirect to ${to} rejected` );
+	}
+
+	return target.toString();
+}
+
+/**
+ * Caches list of page names meta has been collected for in cached promise.
+ */
+let cachedPages;
+
+/**
+ * Caches promise for collected meta information on a named set of pages.
+ */
+let cachedMeta;
+
+/**
+ * Caches the last compiled hierarchy promise, keyed by the same page list
+ * string as cachedPages. Invalidated together with cachedMeta.
+ */
+let cachedHierarchy;
+
+/**
+ * Clears the front matter and hierarchy caches. Intended for use in tests
+ * and dev-server invalidation.
+ */
+export function clearCache() {
+	cachedPages = undefined;
+	cachedMeta = undefined;
+	cachedHierarchy = undefined;
+}
+
+/**
+ * Reads front matter from every named or all discovered page file(s). Repeated
+ * invocations with the same set of pages is served from a cache.
+ *
+ * @param {UserConfig} config Vitepress site configuration
+ * @param {string[]} [pages] names of pages to read front matter from, omit to re-discover all page files in configured source
+ * @returns {Promise<Object<string, Object>>} promise for collection of front matter data per named page
+ */
+export async function collectFrontmatterOfAllPages( config, pages = undefined ) {
+	const cwd = sourceFolder( config );
+	const cacheKey = Array.isArray( pages ) ? pages.join( "," ) : null;
+
+	if ( cacheKey ) {
+		if ( cacheKey !== cachedPages ) {
+			cachedPages = cacheKey;
+			cachedMeta = collectFrontmatterOfPages( config, pages );
+		}
+
+		return cachedMeta;
+	}
+
+	pages = ( await Array.fromAsync( glob( "**/*.md", { cwd } ) ) ).map( name => name.replace( /\\/g, "/" ) );
+
+	return collectFrontmatterOfPages( config, pages );
+}
+
+/**
+ * Reads front matter from named page files.
+ *
+ * @param {UserConfig} config Vitepress site configuration
+ * @param {string[]} pages names of pages to read front matter from
+ * @returns {Promise<Object<string, Object>>} promise for collection of front matter data per named page
+ */
+async function collectFrontmatterOfPages( config, pages ) {
+	const cwd = sourceFolder( config );
+	const metas = {};
+
+	pages = [ ...pages ].sort( ( l, r ) => l.localeCompare( r ) );
+
+	const files = await Promise.all( pages.map( name => readFile( resolve( cwd, name ), "utf-8" ) ) );
+
+	for ( let i = 0; i < pages.length; i++ ) {
+		const page = pages[i];
+		const file = files[i];
+		const docs = YAML.parseAllDocuments( file ).filter( doc => !doc.empty && !doc.errors?.length );
+
+		const meta = { ...( docs[0]?.toJS?.() ?? {} ) };
+
+		// Extract the first ATX heading (# …) as a fallback title when none is
+		// declared in frontmatter. Strip the frontmatter block first so a heading
+		// inside YAML comments does not match.
+		if ( meta.title == null && meta.label == null ) {
+			const body = file.replace( /^---[\s\S]*?^---\s*/m, "" );
+			const headingMatch = body.match( /^#{1,6}\s+(.+)/m );
+
+			if ( headingMatch ) {
+				meta._firstHeading = headingMatch[1].trim();
+			}
+		}
+
+		metas[page] = meta;
+	}
+
+	return metas;
+}
+
+/**
+ * Compiles static unconditional redirects defined in front matter of pages for
+ * integration with site's configuration in property `rewrites`.
+ *
+ * @param {UserConfig} config Vitepress configuration
+ * @param {string[]} pages relative path names of markdown files discovered by vitepress for describing pages, omit for checking all markdown files
+ * @returns {Promise<Object<string,string>>} promise for set of unconditional static redirects defined in front matter of pages
+ */
+export async function compileRedirects( config, pages = undefined ) {
+	const metas = await collectFrontmatterOfAllPages( config, pages );
+	const redirects = {};
+
+	for ( const [ page, meta ] of Object.entries( metas ) ) {
+		const redirect = meta?.redirect;
+
+		try {
+			if ( redirect?.["*"] && typeof redirect === "object" && Object.keys( redirect ).length === 1 ) {
+				redirects[page] = qualifyRedirect( page, redirect["*"], true );
+			}
+			// String-form redirects ("redirect: other.md") are handled client-side by
+			// ScavoldSimpleRedirect and must NOT go into VitePress rewrites — a rewrite
+			// would remove the source URL from the build, making it a 404 instead of a
+			// redirect page.
+		} catch {}
+	}
+
+	const hierarchy = await compileHierarchy( config, pages );
+
+	forEachPage( hierarchy, ( node, index, siblings ) => {
+		if ( !ptnIsIndexPage.test( node.path ) ) {
+			if ( index !== 0 || siblings.some( ( { path } ) => ptnIsIndexPage.test( path ) ) ) {
+				return;
+			}
+		}
+
+		const target = node.path.replace( /\/index\.md$/, "/" );
+
+		for ( let iter = node.parent; iter; iter = iter.parent ) {
+			if ( !iter.isPage && iter.path && iter.path !== target && iter.path + "/" !== target ) {
+				redirects[iter.path] = target;
+			}
+		}
+	} );
+
+	// Merge url alias rewrites: source path → alias path (both .md-relative).
+	forEachPage( hierarchy, node => {
+		if ( node.url != null ) {
+			redirects[node.path] = node.url;
+		}
+	} );
+
+	return redirects;
+}
+
+/**
+ * Compiles hierarchy of site's pages based on named pages and their front
+ * matter data.
+ *
+ * @param {UserConfig} config Vitepress site configuration
+ * @param {string[]} pages names pages of site to consider
+ * @returns {Promise<{}>}
+ */
+export async function compileHierarchy( config, pages ) {
+	const cacheKey = Array.isArray( pages ) ? pages.join( "," ) : null;
+
+	if ( cacheKey && cacheKey === cachedPages && cachedHierarchy ) {
+		return cachedHierarchy;
+	}
+
+	const hierarchyPromise = _buildHierarchy( config, pages );
+
+	if ( cacheKey ) {
+		cachedHierarchy = hierarchyPromise;
+	}
+
+	return hierarchyPromise;
+}
+
+async function _buildHierarchy( config, pages ) {
+	const metas = await collectFrontmatterOfAllPages( config, pages );
+	const hierarchy = { isPage: false, path: "", subs: {} };
+
+	// create hierarchy of pages
+	for ( const [ page, meta ] of Object.entries( metas ) ) {
+		const segments = page.replace( /^\//, "" ).replace( /\/$/, "/index.md" ).split( "/" );
+		let parent = hierarchy;
+
+		const path = [];
+
+		while ( segments.length > 1 ) {
+			const lead = segments.shift();
+			path.push( lead );
+
+			let sub = parent.subs?.[lead];
+
+			if ( !sub ) {
+				sub = ( parent.subs ??= {} )[lead] = {
+					isPage: false,
+					path: path.join( "/" ),
+					frontmatter: {},
+				};
+
+				Object.defineProperty( sub, "parent", { value: parent, writable: true } );
+			}
+
+			parent = sub;
+		}
+
+		const name = segments[0];
+		let leaf = parent.subs?.[name];
+
+		if ( leaf?.isPage ) {
+			throw new TypeError( `ambiguous page ${leaf.path} exists as ${page}, too` );
+		}
+
+		if ( !leaf ) {
+			leaf = ( parent.subs ??= {} )[name] = {};
+
+			Object.defineProperty( leaf, "parent", { value: parent, writable: true } );
+		}
+
+		leaf.isPage = true;
+		leaf.path = page;
+		leaf.frontmatter = meta;
+	}
+
+	// Promote each index.md into its parent folder node: the folder node absorbs
+	// the index.md's path and frontmatter, becomes a page itself, and the index.md
+	// leaf is removed from subs so it no longer appears as a sibling of other pages
+	// in the same folder.
+	forEachPage( hierarchy, node => {
+		if ( !ptnIsIndexPage.test( node.path ) ) {
+			return;
+		}
+
+		const folder = node.parent;
+
+		// Root index.md has no meaningful folder node to promote into — leave it as-is.
+		if ( !folder || !folder.path ) {
+			return;
+		}
+
+		// Absorb: folder takes on the index.md's identity.
+		folder.isPage = true;
+		folder.path = node.path;
+		folder.frontmatter = { ...node.frontmatter, ...folder.frontmatter };
+
+		// Remove the index.md leaf from subs so it is not listed as a sibling.
+		const indexKey = Object.keys( folder.subs ?? {} ).find( k => folder.subs[k] === node );
+
+		if ( indexKey != null ) {
+			delete folder.subs[indexKey];
+		}
+	} );
+
+	// Derive display labels from frontmatter title, label, first heading, or path segment.
+	forEachPage( hierarchy, node => {
+		const fm = node.frontmatter ?? {};
+
+		if ( fm.title != null ) {
+			node.title = String( fm.title );
+		} else if ( fm._firstHeading != null ) {
+			node.title = String( fm._firstHeading );
+		}
+
+		if ( fm.label != null ) {
+			node.label = String( fm.label );
+		}
+	} );
+
+	// Collect url aliases and validate uniqueness. A `url` front matter value
+	// declares the desired output path for a page, hiding its source location.
+	// Conflicts (two pages targeting the same URL) are a build error.
+	const urlTargets = new Map(); // normalised target path → source path
+
+	forEachPage( hierarchy, node => {
+		const raw = node.frontmatter?.url;
+
+		if ( raw == null ) {
+			return;
+		}
+
+		// Normalise: strip leading slash, ensure .md extension.
+		const normalised = String( raw )
+			.replace( /^\//, "" )
+			.replace( /\/?$/, "" )
+			.replace( /\.md$/, "" ) + ".md";
+
+		const existing = urlTargets.get( normalised );
+
+		if ( existing != null ) {
+			throw new Error(
+				`[scavold] url alias conflict: both "${existing}" and "${node.path}" ` +
+				`declare url: ${raw} — each page must have a unique URL alias`
+			);
+		}
+
+		urlTargets.set( normalised, node.path );
+		node.url = normalised;
+	} );
+
+	// Recursively pulls down defined locale to given node from its ancestors.
+	// Own frontmatter takes precedence over inherited value.
+	// Prefer `locale` key; accept `lang` for backwards compatibility.
+	const pullLocale = node => {
+		const ownLocale = node.frontmatter?.locale ?? node.frontmatter?.lang ?? undefined;
+
+		if ( ownLocale != null ) {
+			node.locale = ownLocale;
+			return ownLocale;
+		}
+
+		if ( node.parent ) {
+			const inherited = pullLocale( node.parent );
+
+			if ( inherited != null ) {
+				node.locale = inherited;
+			}
+
+			return inherited;
+		}
+
+		return undefined;
+	};
+
+	forEachPage( hierarchy, pullLocale );
+
+	// Back-link pass: for every page that declares `translations`, check each
+	// target page and add the reverse link if the target has none yet for this
+	// locale. Warn when a conflicting explicit back-link points elsewhere.
+	forEachPage( hierarchy, node => {
+		const translations = node.frontmatter?.translations;
+
+		if ( !translations || typeof translations !== "object" ) {
+			return;
+		}
+
+		const sourceLocale = node.locale;
+
+		if ( !sourceLocale ) {
+			return;
+		}
+
+		for ( const [ targetLocale, targetPath ] of Object.entries( translations ) ) {
+			const target = findNodeByPath( hierarchy, String( targetPath ) );
+
+			if ( !target ) {
+				continue;
+			}
+
+			const existing = target.frontmatter?.translations?.[ sourceLocale ];
+
+			if ( existing != null ) {
+				// Target already has an explicit back-link. Warn if it points elsewhere.
+				if ( existing !== node.path ) {
+					console.warn(
+						`[scavold] translations conflict: ${target.path} declares ` +
+						`translations.${sourceLocale}=${existing} but ${node.path} ` +
+						`points back to itself. The explicit declaration on ${target.path} takes precedence.`
+					);
+				}
+			} else {
+				// Add the back-link.
+				( target.frontmatter ??= {} );
+				( target.frontmatter.translations ??= {} );
+				target.frontmatter.translations[ sourceLocale ] = node.path;
+			}
+		}
+	} );
+
+	// Sort children of every node: pages with an explicit `order` frontmatter
+	// value come first (ascending); the rest follow in filename order.
+	const sortSubs = node => {
+		if ( !node.subs ) {
+			return;
+		}
+
+		const entries = Object.entries( node.subs );
+
+		entries.sort( ( [ , a ], [ , b ] ) => {
+			const ao = a.frontmatter?.order;
+			const bo = b.frontmatter?.order;
+			const aHas = ao != null;
+			const bHas = bo != null;
+
+			if ( aHas && bHas ) {
+				return ao - bo;
+			}
+
+			if ( aHas ) {
+				return -1;
+			}
+
+			if ( bHas ) {
+				return 1;
+			}
+
+			return a.path.localeCompare( b.path );
+		} );
+
+		node.subs = Object.fromEntries( entries );
+
+		for ( const sub of Object.values( node.subs ) ) {
+			sortSubs( sub );
+		}
+	};
+
+	sortSubs( hierarchy );
+
+	return hierarchy;
+}
+
+/**
+ * Finds a node in the hierarchy by its exact path.
+ *
+ * @param {object} root
+ * @param {string} searchedPath
+ * @returns {object|undefined}
+ */
+function findNodeByPath( root, searchedPath ) {
+	if ( root.path === searchedPath ) {
+		return root;
+	}
+
+	for ( const sub of Object.values( root.subs ?? {} ) ) {
+		const match = findNodeByPath( sub, searchedPath );
+
+		if ( match != null ) {
+			return match;
+		}
+	}
+
+	return undefined;
+}
+
+/**
+ * Recursive iterates over every node of hierarchy which is representing a page.
+ *
+ * @param hierarchy full hierarchy or one of its subordinated nodes
+ * @param {function} fn callback invoked on nodes representing a particular page
+ * @param {boolean} depthFirst if true, subordinated nodes are invoked prior to their parent
+ */
+export function forEachPage( hierarchy, fn, depthFirst = false ) {
+	if ( hierarchy.isPage && !depthFirst ) {
+		const siblings = Object.values( hierarchy.parent?.subs ?? { hierarchy } );
+
+		fn( hierarchy, siblings.indexOf( hierarchy ), siblings );
+	}
+
+	for ( const sub of Object.values( hierarchy?.subs ?? {} ) ) {
+		forEachPage( sub, fn, depthFirst );
+	}
+
+	if ( hierarchy.isPage && depthFirst ) {
+		const siblings = Object.values( hierarchy.parent?.subs ?? { hierarchy } );
+
+		fn( hierarchy, siblings.indexOf( hierarchy ), siblings );
+	}
+}

package/lib/parser.js

@@ -0,0 +1,83 @@
+/**
+ * Accepts a string of key-value pairs and provides an object with found keys
+ * and their values featuring keys mentioned without an assigned value resulting
+ * in boolean value true.
+ *
+ * @param {string} string - Input string containing key-value pairs
+ * @returns {Object} - Object with found keys and their values
+ */
+export function parseKeyValuePairs( string ) {
+	const trimmed = String( string || "" ).trim();
+
+	if ( trimmed === "" ) {
+		return {};
+	}
+
+	const getQuotedPart = ( tokens, start ) => {
+		let end, quote;
+
+		if ( tokens[start] === "" && ( ( quote = tokens[start + 1] ) === '"' || quote === "'" ) ) {
+			start += 2;
+			end = tokens.indexOf( quote, start );
+		} else {
+			end = tokens.findIndex( ( token, i ) => i >= start && /\s/.test( token ) );
+		}
+
+		if ( end < 0 ) {
+			end = numTokens;
+		}
+
+		return [ tokens.slice( start, end ).join( "" ), end + 1 ];
+	};
+
+	const tokens = trimmed.split( /(\s+|[="'])/ );
+	let numTokens = tokens.length;
+	const found = {};
+
+	for ( let i = 0; i < numTokens; ) {
+		const lead = tokens[i++];
+		const sep = tokens[i++];
+
+		switch ( sep ) {
+			default :
+				if ( lead !== "" ) {
+					found[lead] = true;
+				}
+				break;
+
+			case "=" : {
+				[ found[lead], i ] = getQuotedPart( tokens, i );
+				break;
+			}
+
+			case "'" :
+			case '"' : {
+				if ( lead !== "" ) {
+					i -= 2;
+					numTokens -= 2;
+					tokens.splice( i, 3, tokens[i] + tokens[i + 1] + tokens[i + 2] );
+					break;
+				}
+
+				let end = tokens.indexOf( sep, i );
+
+				if ( end < 0 ) {
+					end = numTokens;
+				}
+
+				const key = tokens.slice( i, end ).join( "" );
+
+				if ( tokens[end + 1] === "" && tokens[end + 2] === "=" ) {
+					[ found[key], i ] = getQuotedPart( tokens, end + 3 );
+				} else {
+					found[key] = true;
+					i = end + 1;
+				}
+
+				break;
+			}
+		}
+	}
+
+	return found;
+}

package/lib/redirectTarget.js

@@ -0,0 +1,46 @@
+/**
+ * Returns true for absolute URLs (any scheme, e.g. "https://", "mailto:") and
+ * protocol-relative URLs ("//cdn.example.com").  These must be redirected
+ * as-is and must never be treated as repository-relative paths.
+ *
+ * @param {string} value
+ * @returns {boolean}
+ */
+export function isExternalUrl( value ) {
+	return typeof value === "string" && ( /^[a-z][a-z0-9+.-]*:/i.test( value ) || value.startsWith( "//" ) );
+}
+
+/**
+ * Normalises a redirect target so it resolves on a plain static file server.
+ *
+ * VitePress builds leaf pages as `<name>.html` and folder pages as
+ * `<dir>/index.html`. Clean URLs like `/de/leistungen` are only resolved by
+ * VitePress' in-app router during SPA navigation. A redirect is a *hard*
+ * navigation (`location.replace`, an injected `location.replace(...)` head
+ * script, or a `<meta http-equiv="refresh">` fallback): it bypasses the router
+ * and asks the static server — the editor preview service worker or a bare
+ * `file_server` web server — for that exact path. A clean leaf URL maps to no
+ * file there and 404s.
+ *
+ * Appending `.html` to leaf paths (while leaving trailing-slash folder URLs to
+ * the server's `index.html` rule) yields a path that maps to a real file on any
+ * static server. Absolute/external URLs, query strings and fragments are left
+ * untouched.
+ *
+ * @param {string} target site-relative path or absolute URL
+ * @returns {string} a path/URL a plain static server can serve directly
+ */
+export function servableRedirectTarget( target ) {
+	if ( typeof target !== "string" || target === "" ) return target;
+
+	if ( isExternalUrl( target ) ) return target;
+
+	// Split off any query string / fragment so the extension lands on the path.
+	const [ , path, suffix ] = /^([^?#]*)([?#].*)?$/.exec( target );
+
+	// Folder URLs ("/de/jobs/") rely on the server's index.html rule; paths that
+	// already carry the ".html" extension are served as-is.
+	if ( path === "" || path.endsWith( "/" ) || path.endsWith( ".html" ) ) return path + ( suffix ?? "" );
+
+	return path + ".html" + ( suffix ?? "" );
+}