@janga/norna 0.7.0

package/scripts/lib/site-content.mjs

@@ -0,0 +1,392 @@
+import { access, readdir, readFile } from 'node:fs/promises';
+import path from 'node:path';
+import {
+	siteContentLabel,
+	siteContentPath,
+	siteDir,
+	siteImagesDir,
+	siteImagesLabel,
+	siteRoutesDir,
+	siteRoutesLabel,
+	siteThemeLabel,
+} from './site-paths.mjs';
+
+export const supportedImageExtensions = new Set(['.jpg', '.jpeg', '.png']);
+
+const h2Regex = /^##\s+.*$/gm;
+const explicitHeadingIdRegex = /\s*\{#([a-z0-9-]+)\}\s*$/;
+const inlineStyleReferenceRegex = /\[[^\]\n]+\]\{\.([a-z][a-z0-9-]*)\}/g;
+const frontmatterDelimiterRegex = /^---\s*$/;
+const knownContentTopLevelFrontmatterKeys = new Set(['title', 'description', 'slug', 'navigation', 'presentation', 'frame', 'sections']);
+const knownThemeTopLevelFrontmatterKeys = new Set(['presentation', 'frame']);
+const knownNestedFrontmatterKeys = new Set([
+	'align',
+	'alt',
+	'backgroundColor',
+	'body',
+	'caption',
+	'carousel',
+	'color',
+	'colors',
+	'desktop',
+	'from',
+	'gallery',
+	'heading',
+	'id',
+	'include',
+	'image',
+	'inlineStyles',
+	'label',
+	'lineHeight',
+	'mobile',
+	'navigation',
+	'overrides',
+	'order',
+	'paragraphSpacing',
+	'preset',
+	'presentation',
+	'sections',
+	'size',
+	'spacing',
+	'textColor',
+	'theme',
+	'typography',
+	'until',
+	'visible',
+]);
+
+export const toPosixPath = (filePath) => filePath.split(path.sep).join('/');
+
+const fileExists = async (filePath) => access(filePath).then(() => true, () => false);
+
+export const getContentFiles = async () => {
+	const contentFiles = [{
+		contentLabel: siteContentLabel,
+		contentPath: siteContentPath,
+		imagesDir: siteImagesDir,
+		imagesLabel: siteImagesLabel,
+		isHome: true,
+		routeFolder: null,
+	}];
+	const routeEntries = await readdir(siteRoutesDir, { withFileTypes: true }).catch((error) => {
+		if (error?.code === 'ENOENT') {
+			return [];
+		}
+
+		throw error;
+	});
+
+	for (const entry of routeEntries) {
+		if (!entry.isDirectory()) continue;
+
+		const routeFolder = entry.name;
+		const routeDir = path.join(siteRoutesDir, routeFolder);
+		const routeContentPath = path.join(routeDir, 'route-content.md');
+
+		if (!(await fileExists(routeContentPath))) continue;
+
+		contentFiles.push({
+			contentLabel: `${siteRoutesLabel}/${routeFolder}/route-content.md`,
+			contentPath: routeContentPath,
+			imagesDir: path.join(routeDir, 'images'),
+			imagesLabel: `${siteRoutesLabel}/${routeFolder}/images`,
+			isHome: false,
+			routeFolder,
+		});
+	}
+
+	return contentFiles;
+};
+
+export const splitSiteFile = (source, label = siteContentLabel) => {
+	const match = source.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?/);
+
+	if (!match) {
+		throw new Error(`${label} is missing frontmatter delimited by ---.`);
+	}
+
+	return {
+		frontmatter: match[0],
+		frontmatterBody: match[1],
+		body: source.slice(match[0].length),
+	};
+};
+
+export const readSiteFile = async (sitePath, label = siteContentLabel) => splitSiteFile(await readFile(sitePath, 'utf8'), label);
+
+const getIndentInfo = (line) => {
+	const characters = Array.from(line);
+	const indentCharacters = [];
+
+	for (const character of characters) {
+		if (character === ' ' || character === '\t' || character === '\u00a0' || character === '\uFFFD' || character === '\u00c2') {
+			indentCharacters.push(character);
+			continue;
+		}
+
+		break;
+	}
+
+	return {
+		indent: indentCharacters.length,
+		hasInvalidWhitespace: indentCharacters.some((character) => character !== ' '),
+	};
+};
+
+const getNextFrontmatterEntry = (lines, startIndex) => {
+	for (let index = startIndex + 1; index < lines.length; index += 1) {
+		const line = lines[index];
+		if (!line.trim() || line.trim().startsWith('#') || frontmatterDelimiterRegex.test(line)) {
+			continue;
+		}
+
+		return {
+			index,
+			line,
+			...getIndentInfo(line),
+		};
+	}
+
+	return null;
+};
+
+export const validateFrontmatterIndentation = (frontmatter, addIssue) => {
+	const lines = frontmatter.split(/\r?\n/);
+
+	for (const [index, line] of lines.entries()) {
+		const lineNumber = index + 1;
+		const trimmed = line.trim();
+
+		if (!trimmed || trimmed.startsWith('#') || frontmatterDelimiterRegex.test(line)) {
+			continue;
+		}
+
+		const { indent, hasInvalidWhitespace } = getIndentInfo(line);
+
+		if (hasInvalidWhitespace) {
+			addIssue({
+				severity: 'error',
+				message: `Frontmatter line ${lineNumber} uses tabs, non-breaking spaces, or invalid whitespace for indentation.`,
+				fix: 'Replace the indentation on that line with ordinary spaces.',
+			});
+			continue;
+		}
+
+		if (indent % 2 !== 0) {
+			addIssue({
+				severity: 'error',
+				message: `Frontmatter line ${lineNumber} is indented with ${indent} spaces.`,
+				fix: 'Use 2-space indentation levels in frontmatter.',
+			});
+		}
+
+		const keyValueMatch = line.match(/^(\s*)[A-Za-z][A-Za-z0-9-]*:\s+(.+)$/);
+		if (!keyValueMatch) continue;
+
+		const value = keyValueMatch[2].trim();
+		if (value === '|' || value === '>' || value.startsWith('|') || value.startsWith('>')) {
+			continue;
+		}
+
+		const nextEntry = getNextFrontmatterEntry(lines, index);
+		if (!nextEntry || nextEntry.indent <= indent) continue;
+
+		addIssue({
+			severity: 'error',
+			message: `Frontmatter line ${nextEntry.index + 1} is indented under line ${lineNumber}, but line ${lineNumber} already has a value.`,
+			fix: 'Move the later line to the same indentation level as its sibling, or place it under a key that has no value.',
+		});
+	}
+};
+
+export const validateFrontmatterStructure = (frontmatter, addIssue, {
+	knownTopLevelFrontmatterKeys = knownContentTopLevelFrontmatterKeys,
+	fileKind = 'content',
+} = {}) => {
+	const lines = frontmatter.split(/\r?\n/);
+
+	for (const [index, line] of lines.entries()) {
+		const lineNumber = index + 1;
+		const trimmed = line.trim();
+
+		if (!trimmed || trimmed.startsWith('#') || frontmatterDelimiterRegex.test(line)) {
+			continue;
+		}
+
+		const { indent, hasInvalidWhitespace } = getIndentInfo(line);
+		if (hasInvalidWhitespace || indent !== 0) continue;
+
+		const keyMatch = line.match(/^([A-Za-z][A-Za-z0-9-]*):/);
+		if (!keyMatch) continue;
+
+		const key = keyMatch[1];
+		if (knownTopLevelFrontmatterKeys.has(key)) continue;
+
+		const fix = knownNestedFrontmatterKeys.has(key)
+			? `Indent "${key}:" under the section or object it belongs to. For gallery rows, "gallery:" normally belongs under a "sections" item.`
+			: `Move "${key}:" under the correct parent key, or remove it if it is not part of the ${fileKind} schema.`;
+
+		addIssue({
+			severity: 'error',
+			message: `Frontmatter line ${lineNumber} defines "${key}" at the top level, but it is not a valid top-level ${fileKind} field.`,
+			fix,
+		});
+	}
+};
+
+export const validateContentFrontmatterStructure = (frontmatter, addIssue) =>
+	validateFrontmatterStructure(frontmatter, addIssue, {
+		knownTopLevelFrontmatterKeys: knownContentTopLevelFrontmatterKeys,
+		fileKind: 'content',
+	});
+
+export const validateThemeFrontmatterStructure = (frontmatter, addIssue) =>
+	validateFrontmatterStructure(frontmatter, addIssue, {
+		knownTopLevelFrontmatterKeys: knownThemeTopLevelFrontmatterKeys,
+		fileKind: 'theme',
+	});
+
+export const readThemeFile = async (sitePath) => readSiteFile(sitePath, siteThemeLabel);
+
+export const getFrontmatterSections = (frontmatter) => {
+	const sections = [];
+	const lines = frontmatter.split(/\r?\n/);
+	let inSections = false;
+	let currentSection = null;
+
+	for (const [index, line] of lines.entries()) {
+		if (/^sections:\s*$/.test(line)) {
+			inSections = true;
+			continue;
+		}
+
+		if (!inSections) continue;
+		if (/^[a-zA-Z0-9_-]+:/.test(line)) break;
+
+		const sectionMatch = line.match(/^\s{2}-\s+id:\s*([a-z0-9-]+)\s*$/);
+		if (sectionMatch) {
+			currentSection = { id: sectionMatch[1], images: [], imageReferences: [], carousels: [] };
+			sections.push(currentSection);
+			continue;
+		}
+
+		const carouselMatch = line.match(/^\s{6}-\s+carousel:\s*$/);
+		if (carouselMatch && currentSection) {
+			currentSection.carousels.push({ images: [], imageReferences: [], line: index + 1 });
+			continue;
+		}
+
+		const imageMatch = line.match(/^\s{6,}-\s+image:\s*["']?([^"'\n]+)["']?\s*$/);
+		if (imageMatch && currentSection) {
+			const image = imageMatch[1].trim();
+			const isCarouselImage = /^\s{10}-\s+image:/.test(line);
+			const carousel = isCarouselImage ? currentSection.carousels.at(-1) : null;
+			currentSection.images.push(image);
+			currentSection.imageReferences.push({ image, line: index + 1 });
+			if (carousel) {
+				carousel.images.push(image);
+				carousel.imageReferences.push({ image, line: index + 1 });
+			}
+		}
+	}
+
+	return sections;
+};
+
+export const getFrontmatterInlineStyleNames = (frontmatter) => {
+	const names = new Set();
+	const lines = frontmatter.split(/\r?\n/);
+	let inlineStylesIndent = null;
+
+	for (const line of lines) {
+		const inlineStylesMatch = line.match(/^(\s*)inlineStyles:\s*$/);
+
+		if (inlineStylesMatch) {
+			inlineStylesIndent = inlineStylesMatch[1].length;
+			continue;
+		}
+
+		if (inlineStylesIndent === null) continue;
+		if (!line.trim() || line.trim().startsWith('#')) continue;
+
+		const indent = line.match(/^\s*/)?.[0].length ?? 0;
+		if (indent <= inlineStylesIndent) {
+			inlineStylesIndent = null;
+			continue;
+		}
+
+		const nameMatch = line.match(new RegExp(`^\\s{${inlineStylesIndent + 2}}([a-z][a-z0-9-]*):\\s*$`));
+		if (nameMatch) {
+			names.add(nameMatch[1]);
+		}
+	}
+
+	return names;
+};
+
+export const getInlineStyleReferences = (body) => Array.from(body.matchAll(inlineStyleReferenceRegex))
+	.map((match) => match[1]);
+
+export const getHeadingId = (heading) => heading.match(explicitHeadingIdRegex)?.[1];
+
+export const getBodySections = (body) => {
+	const matches = Array.from(body.matchAll(h2Regex));
+	const prelude = matches.length > 0 ? body.slice(0, matches[0].index) : body;
+	const sections = [];
+
+	for (let index = 0; index < matches.length; index += 1) {
+		const match = matches[index];
+		const start = match.index ?? 0;
+		const next = matches[index + 1];
+		const end = next?.index ?? body.length;
+		const text = body.slice(start, end).trimEnd();
+		const heading = match[0];
+		const id = getHeadingId(heading);
+
+		sections.push({ id, heading, text });
+	}
+
+	return { prelude, sections };
+};
+
+export const getImageFiles = async (directory) => {
+	const entries = await readdir(directory, { withFileTypes: true }).catch((error) => {
+		if (error?.code === 'ENOENT') {
+			return [];
+		}
+
+		throw error;
+	});
+	const files = [];
+
+	for (const entry of entries) {
+		const entryPath = path.join(directory, entry.name);
+
+		if (entry.isDirectory()) {
+			files.push(...await getImageFiles(entryPath));
+		} else if (entry.isFile() && supportedImageExtensions.has(path.extname(entry.name).toLowerCase())) {
+			files.push(entryPath);
+		}
+	}
+
+	return files;
+};
+
+export const getImageIndex = async (contentDir, fail) => {
+	const imageFiles = await getImageFiles(contentDir);
+	const imagesByName = new Map();
+
+	for (const imagePath of imageFiles) {
+		const imageName = path.basename(imagePath);
+		const existingPath = imagesByName.get(imageName);
+
+		if (existingPath) {
+			fail(`Duplicate image filename "${imageName}" found at ${siteImagesLabel}/${toPosixPath(path.relative(contentDir, existingPath))} and ${siteImagesLabel}/${toPosixPath(path.relative(contentDir, imagePath))}. Image filenames must be globally unique.`);
+			continue;
+		}
+
+		imagesByName.set(imageName, imagePath);
+	}
+
+	return imagesByName;
+};

package/scripts/lib/site-paths.mjs

@@ -0,0 +1,127 @@
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const siteDirectoryEnvName = 'NORNA_SITE_DIR';
+const invocationRootEnvName = 'NORNA_INVOCATION_ROOT';
+const defaultSiteDirectory = 'site';
+
+const currentFile = fileURLToPath(import.meta.url);
+const currentDirectory = path.dirname(currentFile);
+
+export const engineRoot = path.resolve(currentDirectory, '..', '..');
+export const siteDirectoryEnv = siteDirectoryEnvName;
+
+const normalizeSiteDirectory = (value) => String(value ?? '').trim();
+const normalizeInvocationRoot = (value) => String(value ?? '').trim();
+
+const configuredInvocationRoot = normalizeInvocationRoot(process.env[invocationRootEnvName]);
+export const invocationRoot = configuredInvocationRoot
+	? path.resolve(configuredInvocationRoot)
+	: process.cwd();
+
+const hasSiteFiles = (projectRoot, siteDirectory) => {
+	const siteDir = path.resolve(projectRoot, siteDirectory);
+
+	return (
+		existsSync(path.join(siteDir, 'config.mjs'))
+		&& existsSync(path.join(siteDir, 'content.md'))
+	);
+};
+
+const findSiteProjectRoot = (startDirectory, siteDirectory) => {
+	let current = path.resolve(startDirectory);
+
+	while (true) {
+		if (hasSiteFiles(current, siteDirectory)) {
+			return current;
+		}
+
+		const parent = path.dirname(current);
+		if (parent === current) {
+			return null;
+		}
+
+		current = parent;
+	}
+};
+
+const hasSiteDirectoryEnv = Object.hasOwn(process.env, siteDirectoryEnvName);
+const configuredSiteDirectory = normalizeSiteDirectory(process.env[siteDirectoryEnvName]);
+const hasConfiguredSiteDirectory = hasSiteDirectoryEnv && configuredSiteDirectory !== '';
+const fallbackSiteDirectory = hasConfiguredSiteDirectory ? configuredSiteDirectory : defaultSiteDirectory;
+
+if (hasSiteDirectoryEnv && !configuredSiteDirectory) {
+	throw new Error(`${siteDirectoryEnvName} must not be empty.`);
+}
+
+const resolveSitePaths = () => {
+	if (path.isAbsolute(fallbackSiteDirectory)) {
+		const siteDir = path.resolve(fallbackSiteDirectory);
+		const siteProjectRoot = path.dirname(siteDir);
+
+		return {
+			siteDirectory: path.relative(siteProjectRoot, siteDir) || path.basename(siteDir),
+			siteDir,
+			siteProjectRoot,
+		};
+	}
+
+	const discoveredRoot = findSiteProjectRoot(invocationRoot, fallbackSiteDirectory);
+	const siteProjectRoot = discoveredRoot ?? invocationRoot;
+
+	return {
+		siteDirectory: fallbackSiteDirectory,
+		siteDir: path.resolve(siteProjectRoot, fallbackSiteDirectory),
+		siteProjectRoot,
+	};
+};
+
+const resolvedSitePaths = resolveSitePaths();
+
+export const siteProjectRoot = resolvedSitePaths.siteProjectRoot;
+export const root = siteProjectRoot;
+export const siteDirectory = resolvedSitePaths.siteDirectory;
+
+if (!siteDirectory) {
+	throw new Error(`${siteDirectoryEnvName} must not be empty.`);
+}
+
+const toPosixPath = (filePath) => filePath.split(path.sep).join('/');
+const getPathLabel = (filePath) => {
+	const relativePath = path.relative(siteProjectRoot, filePath);
+
+	if (relativePath && !relativePath.startsWith('..') && !path.isAbsolute(relativePath)) {
+		return toPosixPath(relativePath);
+	}
+
+	return toPosixPath(filePath);
+};
+
+export const siteDir = resolvedSitePaths.siteDir;
+export const siteConfigPath = path.join(siteDir, 'config.mjs');
+export const siteThemePath = path.join(siteDir, 'theme.md');
+export const siteContentPath = path.join(siteDir, 'content.md');
+export const siteImagesDir = path.join(siteDir, 'images');
+export const siteRoutesDir = path.join(siteDir, 'routes');
+export const sitePublicDir = path.join(siteDir, 'public');
+export const siteStateDir = path.join(siteDir, '.norna');
+export const astroPublicDir = path.join(siteStateDir, 'public');
+export const astroDistDir = path.join(siteProjectRoot, 'dist');
+export const astroCacheDir = path.join(siteProjectRoot, '.astro');
+export const generatedImagesDir = path.join(astroPublicDir, 'images', 'generated');
+export const originalImagesDir = path.join(astroPublicDir, 'images', 'original');
+export const generatedImagesManifestPath = path.join(siteStateDir, 'generated-images.json');
+
+export const engineRootLabel = getPathLabel(engineRoot);
+export const invocationRootLabel = getPathLabel(invocationRoot);
+export const siteProjectRootLabel = getPathLabel(siteProjectRoot);
+export const siteDirLabel = getPathLabel(siteDir);
+export const siteConfigLabel = getPathLabel(siteConfigPath);
+export const siteThemeLabel = getPathLabel(siteThemePath);
+export const siteContentLabel = getPathLabel(siteContentPath);
+export const siteImagesLabel = getPathLabel(siteImagesDir);
+export const siteRoutesLabel = getPathLabel(siteRoutesDir);
+export const sitePublicLabel = getPathLabel(sitePublicDir);
+export const astroPublicLabel = getPathLabel(astroPublicDir);
+export const generatedImagesManifestLabel = getPathLabel(generatedImagesManifestPath);

package/scripts/lib/typography.mjs

@@ -0,0 +1,166 @@
+export const typographyPresetNames = [
+	'quiet-gallery',
+	'compact-gallery',
+	'text-forward',
+	'statement',
+];
+
+export const typographyPresets = {
+	'quiet-gallery': {
+		heading: {
+			align: { desktop: 'left', mobile: 'left' },
+			size: 'medium',
+			lineHeight: 1.08,
+			spacing: '0.65em',
+		},
+		body: {
+			align: { desktop: 'left', mobile: 'left' },
+			size: 'medium',
+			lineHeight: 1.5,
+			paragraphSpacing: '0.85em',
+		},
+		caption: {
+			align: { desktop: 'center', mobile: 'center' },
+			size: 'small',
+			lineHeight: 1.35,
+			spacing: '0.5em',
+		},
+	},
+	'compact-gallery': {
+		heading: {
+			align: { desktop: 'left', mobile: 'left' },
+			size: 'small',
+			lineHeight: 1.08,
+			spacing: '0.45em',
+		},
+		body: {
+			align: { desktop: 'left', mobile: 'left' },
+			size: 'small',
+			lineHeight: 1.42,
+			paragraphSpacing: '0.6em',
+		},
+		caption: {
+			align: { desktop: 'center', mobile: 'center' },
+			size: 'small',
+			lineHeight: 1.25,
+			spacing: '0.35em',
+		},
+	},
+	'text-forward': {
+		heading: {
+			align: { desktop: 'left', mobile: 'left' },
+			size: 'medium',
+			lineHeight: 1.12,
+			spacing: '0.8em',
+		},
+		body: {
+			align: { desktop: 'left', mobile: 'left' },
+			size: 'large',
+			lineHeight: 1.62,
+			paragraphSpacing: '1em',
+		},
+		caption: {
+			align: { desktop: 'left', mobile: 'left' },
+			size: 'small',
+			lineHeight: 1.4,
+			spacing: '0.6em',
+		},
+	},
+	statement: {
+		heading: {
+			align: { desktop: 'left', mobile: 'left' },
+			size: 'large',
+			lineHeight: 1.04,
+			spacing: '0.5em',
+		},
+		body: {
+			align: { desktop: 'left', mobile: 'left' },
+			size: 'large',
+			lineHeight: 1.42,
+			paragraphSpacing: '0.75em',
+		},
+		caption: {
+			align: { desktop: 'center', mobile: 'center' },
+			size: 'small',
+			lineHeight: 1.3,
+			spacing: '0.45em',
+		},
+	},
+};
+
+export const defaultTypography = {
+	preset: 'quiet-gallery',
+};
+
+const isPlainObject = (value) => (
+	value !== null &&
+	typeof value === 'object' &&
+	!Array.isArray(value)
+);
+
+export const mergeDeep = (base, override) => {
+	if (!isPlainObject(override)) return structuredClone(base);
+
+	const merged = structuredClone(base);
+
+	for (const [key, value] of Object.entries(override)) {
+		if (isPlainObject(value) && isPlainObject(merged[key])) {
+			merged[key] = mergeDeep(merged[key], value);
+		} else if (value !== undefined) {
+			merged[key] = value;
+		}
+	}
+
+	return merged;
+};
+
+export const resolveTypographyConfig = (typography = defaultTypography) => {
+	const presetName = typography?.preset ?? defaultTypography.preset;
+	const preset = typographyPresets[presetName];
+
+	if (!preset) {
+		throw new Error(`Unknown typography preset: ${presetName}`);
+	}
+
+	return {
+		preset: presetName,
+		values: mergeDeep(preset, typography?.overrides),
+	};
+};
+
+export const resolveTypographyOverride = (baseResolved, typographyConfig) => {
+	if (typographyConfig?.preset) {
+		return resolveTypographyConfig(typographyConfig);
+	}
+
+	if (typographyConfig?.overrides) {
+		return {
+			preset: baseResolved.preset,
+			values: mergeDeep(baseResolved.values, typographyConfig.overrides),
+		};
+	}
+
+	return baseResolved;
+};
+
+export const resolveSectionTypography = (defaultTypographyConfig, sectionTypographyConfig) => {
+	const defaultResolved = resolveTypographyConfig(defaultTypographyConfig);
+
+	return resolveTypographyOverride(defaultResolved, sectionTypographyConfig);
+};
+
+const quoteString = (value) => typeof value === 'string' && !/^[a-z0-9.-]+$/i.test(value)
+	? JSON.stringify(value)
+	: value;
+
+export const toYamlLines = (value, indent = 0) => {
+	const prefix = ' '.repeat(indent);
+
+	return Object.entries(value).flatMap(([key, entry]) => {
+		if (isPlainObject(entry)) {
+			return [`${prefix}${key}:`, ...toYamlLines(entry, indent + 2)];
+		}
+
+		return `${prefix}${key}: ${quoteString(entry)}`;
+	});
+};