@janga/norna 0.7.18 → 0.7.22

package/scripts/lib/site-content.mjs

@@ -1,18 +1,13 @@
-import { access, readdir, readFile } from 'node:fs/promises';
+import { readdir, readFile } from 'node:fs/promises';
 import path from 'node:path';
 import {
 	siteContentLabel,
-	siteDir,
-	siteDirLabel,
-	homePageDirectory,
-	siteImagesLabel,
-	sitePagesDir,
-	sitePagesLabel,
 	sitewideContentLabel,
 } from './site-paths.mjs';
-import { parsePageDirectoryPath } from './page-model.mjs';
-import { getMarkdownHeadings } from './heading-ids.mjs';
 import { schemaTopLevelKeys } from './schema-definitions.mjs';
+import { getIndentInfo, validateYamlIndentation } from './yaml-indentation.mjs';
+
+export { getContentFiles } from './site-structure.mjs';
 
 export const rasterImageExtensions = new Set(['.jpg', '.jpeg', '.png']);
 export const staticImageExtensions = new Set(['.svg']);
@@ -33,9 +28,11 @@ const knownNestedFrontmatterKeys = new Set([
 	'body',
 	'blockGap',
 	'caption',
+	'colorMode',
 	'carousel',
 	'contentSpacing',
 	'desktop',
+	'default',
 	'fontFamily',
 	'from',
 	'finalSectionBottom',
@@ -64,11 +61,14 @@ const knownNestedFrontmatterKeys = new Set([
 	'palette',
 	'preset',
 	'profile',
+	'readerControls',
+	'readingWidth',
 	'rhythm',
 	'sectionGap',
 	'backgroundPattern',
 	'sections',
-	'shape',
+	'corners',
+	'focusReading',
 	'size',
 	'spacingAfter',
 	'spacingBefore',
@@ -82,107 +82,6 @@ const knownNestedFrontmatterKeys = new Set([
 
 export const toPosixPath = (filePath) => filePath.split(path.sep).join('/');
 
-const fileExists = async (filePath) => access(filePath).then(() => true, () => false);
-
-export const getContentFiles = async () => {
-	const legacyContentPath = path.join(siteDir, 'content.md');
-	const legacyImagesPath = path.join(siteDir, 'images');
-	const legacyPaths = [];
-	if (await fileExists(legacyContentPath)) legacyPaths.push(`${siteDirLabel}/content.md`);
-	if (await fileExists(legacyImagesPath)) legacyPaths.push(`${siteDirLabel}/images`);
-	if (legacyPaths.length > 0) {
-		throw new Error([
-			`The old root-page structure is no longer supported: ${legacyPaths.join(', ')}.`,
-			`Move the homepage content to ${sitePagesLabel}/${homePageDirectory}/content.md and its images to ${sitePagesLabel}/${homePageDirectory}/images/.`,
-		].join('\n'));
-	}
-
-	const legacyRoutesDir = path.join(siteDir, 'routes');
-	const legacyRoutes = await readdir(legacyRoutesDir).catch((error) => {
-		if (error?.code === 'ENOENT') return null;
-		throw error;
-	});
-	if (legacyRoutes !== null) {
-		throw new Error(`${siteDirLabel}/routes is no longer supported. Rename it to ${sitePagesLabel} and use NNN-page-id directory names.`);
-	}
-
-	const contentFiles = [];
-	const collectPageContentFiles = async (pagesDir, pagesLabel, parentPageDirectory = '') => {
-		const pageEntries = await readdir(pagesDir, { withFileTypes: true }).catch((error) => {
-		if (error?.code === 'ENOENT') {
-			return [];
-		}
-
-		throw error;
-		});
-
-		for (const entry of pageEntries.sort((left, right) => left.name.localeCompare(right.name, 'en'))) {
-			if (!entry.isDirectory()) continue;
-
-			const pageDirectory = parentPageDirectory
-				? `${parentPageDirectory}/pages/${entry.name}`
-				: entry.name;
-			const pageLabel = `${pagesLabel}/${entry.name}`;
-			const pageDir = path.join(pagesDir, entry.name);
-			const pageContentPath = path.join(pageDir, 'content.md');
-
-			if (!(await fileExists(pageContentPath))) {
-				const childPageEntries = await readdir(path.join(pageDir, 'pages'), { withFileTypes: true }).catch((error) => {
-					if (error?.code === 'ENOENT') return [];
-					throw error;
-				});
-				if (childPageEntries.some((childEntry) => childEntry.isDirectory())) {
-					throw new Error(`${pageLabel} contains nested pages but has no content.md of its own.`);
-				}
-				continue;
-			}
-			const pageMetadata = parsePageDirectoryPath(pageDirectory, pageLabel);
-			const isHome = pageDirectory === homePageDirectory;
-
-			contentFiles.push({
-				contentLabel: `${pageLabel}/content.md`,
-				contentPath: pageContentPath,
-				imagesDir: path.join(pageDir, 'images'),
-				imagesLabel: `${pageLabel}/images`,
-				isHome,
-				...pageMetadata,
-				pagePath: isHome ? '' : pageMetadata.pagePath,
-				parentPagePath: isHome ? null : pageMetadata.parentPagePath,
-			});
-
-			if (isHome) {
-				const homePagesDir = path.join(pageDir, 'pages');
-				const homeChildEntries = await readdir(homePagesDir, { withFileTypes: true }).catch((error) => {
-					if (error?.code === 'ENOENT') return [];
-					throw error;
-				});
-				const homeChildDirectories = homeChildEntries.filter((childEntry) => childEntry.isDirectory());
-				if (homeChildDirectories.length > 0) {
-					throw new Error([
-						`${pageLabel} is the homepage and cannot contain child pages.`,
-						`Move these page directories beside ${homePageDirectory} under ${sitePagesLabel}/, or below another non-home page:`,
-						...homeChildDirectories.map(({ name }) => `- ${pageLabel}/pages/${name}`),
-					].join('\n'));
-				}
-				continue;
-			}
-
-			await collectPageContentFiles(
-				path.join(pageDir, 'pages'),
-				`${pageLabel}/pages`,
-				pageDirectory,
-			);
-		}
-	};
-
-	await collectPageContentFiles(sitePagesDir, sitePagesLabel);
-	if (!contentFiles.some(({ isHome }) => isHome)) {
-		throw new Error(`Homepage content is missing. Create ${siteContentLabel}.`);
-	}
-
-	return contentFiles;
-};
-
 export const splitSiteFile = (source, label = siteContentLabel) => {
 	const match = source.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?/);
 
@@ -207,89 +106,12 @@ export const splitSiteFile = (source, label = siteContentLabel) => {
 
 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.',
-		});
-	}
+	validateYamlIndentation(frontmatter, (issue) => addIssue({
+		...issue,
+		message: issue.message.replace(/^YAML/, 'Frontmatter'),
+		fix: issue.fix.replace(/YAML/g, 'frontmatter'),
+	}));
 };
 
 export const validateFrontmatterStructure = (frontmatter, addIssue, {
@@ -328,7 +150,14 @@ export const validateFrontmatterStructure = (frontmatter, addIssue, {
 		} else if ((fileKind === 'theme' || fileKind === 'page theme') && key === 'navigation') {
 			message = `Frontmatter line ${lineNumber}: navigation is technical, site-wide configuration and does not belong in ${fileKind}. Set it in config.yaml.`;
 			fix = 'Set the navigation mode under "navigation:" in config.yaml.';
-		} else if (fileKind === 'page theme' && ['preset', 'shape', 'palette', 'typography'].includes(key)) {
+		} else if ((fileKind === 'theme' || fileKind === 'page theme') && key === 'shape') {
+			message = fileKind === 'page theme'
+				? `Frontmatter line ${lineNumber}: "shape" was replaced by the site-wide "corners" setting, which page themes cannot override.`
+				: `Frontmatter line ${lineNumber}: "shape" was replaced by "corners". Use "square" or replace the old "soft" value with "rounded".`;
+			fix = fileKind === 'page theme'
+				? 'Remove "shape:" from this page theme. Set "corners: square" or "corners: rounded" in the root theme.yaml when an override is needed.'
+				: 'Replace "shape:" with "corners:". Use "square" or replace the old "soft" value with "rounded".';
+		} else if (fileKind === 'page theme' && ['preset', 'corners', 'palette', 'typography'].includes(key)) {
 			message = `Frontmatter line ${lineNumber}: page themes may not define site-wide visual identity through "${key}".`;
 			fix = `Move "${key}:" to the root theme.yaml. Page themes may set only layout.textWidth, layout.contentSpacing, images, and sections.backgroundPattern.`;
 		} else if ((fileKind === 'theme' || fileKind === 'page theme') && ['logo', 'site'].includes(key)) {
@@ -389,31 +218,6 @@ export const readThemeFile = async (sitePath) => {
 export const getDeprecatedInlineStyleReferences = (body) => Array.from(body.matchAll(deprecatedInlineStyleReferenceRegex))
 	.map((match) => match[1]);
 
-export const getBodySections = async (body) => {
-	const { headings, source } = await getMarkdownHeadings(body);
-	const structuralHeadings = headings.filter((heading) => heading.depth <= 2);
-	const prelude = structuralHeadings.length > 0 ? source.slice(0, structuralHeadings[0].index) : source;
-	const sections = structuralHeadings.map((heading, index) => {
-		const next = structuralHeadings[index + 1];
-		const end = next?.index ?? source.length;
-
-		return {
-			...heading,
-			heading: heading.source,
-			isPageTitle: heading.depth === 1,
-			level: heading.depth,
-			text: source.slice(heading.index, end).trimEnd(),
-		};
-	});
-
-	return {
-		headings,
-		pageHeadings: sections.filter((section) => section.isPageTitle),
-		prelude,
-		sections,
-	};
-};
-
 export const getImageFiles = async (directory) => {
 	const entries = await readdir(directory, { withFileTypes: true }).catch((error) => {
 		if (error?.code === 'ENOENT') {
@@ -437,25 +241,6 @@ export const getImageFiles = async (directory) => {
 	return files;
 };
 
-export const getImageIndex = async (contentDir, fail, contentLabel = siteImagesLabel) => {
-	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 ${contentLabel}/${toPosixPath(path.relative(contentDir, existingPath))} and ${contentLabel}/${toPosixPath(path.relative(contentDir, imagePath))}. The filename is ambiguous within this page image root.`);
-			continue;
-		}
-
-		imagesByName.set(imageName, imagePath);
-	}
-
-	return imagesByName;
-};
-
 export const getImageCandidatesByName = async (contentDir) => {
 	const imageFiles = await getImageFiles(contentDir);
 	const imagesByName = new Map();

package/scripts/lib/site-paths.mjs

@@ -100,7 +100,6 @@ const resolveSitePaths = () => {
 const resolvedSitePaths = resolveSitePaths();
 
 export const siteProjectRoot = resolvedSitePaths.siteProjectRoot;
-export const root = siteProjectRoot;
 export const siteDirectory = resolvedSitePaths.siteDirectory;
 
 if (!siteDirectory) {
@@ -130,13 +129,13 @@ 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 astroRootDir = siteStateDir;
+export const astroCacheDir = path.join(astroRootDir, '.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);

package/scripts/lib/site-structure.mjs

@@ -0,0 +1,189 @@
+import { access, readdir, readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { categorySchema } from './schema-definitions.mjs';
+import { parsePageDirectoryPath } from './page-model.mjs';
+import {
+	homePageDirectory,
+	siteContentLabel,
+	siteDir,
+	siteDirLabel,
+	sitePagesDir,
+	sitePagesLabel,
+} from './site-paths.mjs';
+import { parseYamlConfig } from './yaml-config.mjs';
+
+const fileExists = async (filePath) => access(filePath).then(() => true, () => false);
+
+const readDirectory = async (directory) => readdir(directory, { withFileTypes: true }).catch((error) => {
+	if (error?.code === 'ENOENT') return [];
+	throw error;
+});
+
+const compareNodeMetadata = (left, right) => (
+	left.pageOrder - right.pageOrder
+	|| left.pageId.localeCompare(right.pageId, 'en')
+);
+
+const assertLegacyStructureIsAbsent = async () => {
+	const legacyContentPath = path.join(siteDir, 'content.md');
+	const legacyImagesPath = path.join(siteDir, 'images');
+	const legacyPaths = [];
+	if (await fileExists(legacyContentPath)) legacyPaths.push(`${siteDirLabel}/content.md`);
+	if (await fileExists(legacyImagesPath)) legacyPaths.push(`${siteDirLabel}/images`);
+	if (legacyPaths.length > 0) {
+		throw new Error([
+			`The old root-page structure is no longer supported: ${legacyPaths.join(', ')}.`,
+			`Move the homepage content to ${sitePagesLabel}/${homePageDirectory}/content.md and its images to ${sitePagesLabel}/${homePageDirectory}/images/.`,
+		].join('\n'));
+	}
+
+	if (await fileExists(path.join(siteDir, 'routes'))) {
+		throw new Error(`${siteDirLabel}/routes is no longer supported. Rename it to ${sitePagesLabel} and use NNN-page-id directory names.`);
+	}
+};
+
+const assertUniqueSiblings = (nodes, pagesLabel) => {
+	const byId = new Map();
+	const byOrder = new Map();
+
+	for (const node of nodes) {
+		const existingId = byId.get(node.pageId);
+		if (existingId) {
+			throw new Error([
+				`${pagesLabel} contains duplicate sibling id "${node.pageId}".`,
+				`- ${existingId.nodeLabel}`,
+				`- ${node.nodeLabel}`,
+			].join('\n'));
+		}
+		byId.set(node.pageId, node);
+
+		const existingOrder = byOrder.get(node.pageOrder);
+		if (existingOrder) {
+			throw new Error([
+				`${pagesLabel} contains duplicate sibling order "${String(node.pageOrder).padStart(3, '0')}".`,
+				`- ${existingOrder.nodeLabel}`,
+				`- ${node.nodeLabel}`,
+			].join('\n'));
+		}
+		byOrder.set(node.pageOrder, node);
+	}
+};
+
+const readCategory = async (categoryPath, categorySourceLabel) => {
+	const source = await readFile(categoryPath, 'utf8');
+	return parseYamlConfig(source, categorySourceLabel, { schema: categorySchema });
+};
+
+export const getSiteStructure = async () => {
+	await assertLegacyStructureIsAbsent();
+
+	const nodes = [];
+	const warnings = [];
+
+	const collectNodes = async (pagesDir, pagesLabel, parentNodeDirectory = '') => {
+		const entries = (await readDirectory(pagesDir))
+			.filter((entry) => entry.isDirectory())
+			.sort((left, right) => left.name.localeCompare(right.name, 'en'));
+		const siblingNodes = [];
+
+		for (const entry of entries) {
+			const pageDirectory = parentNodeDirectory
+				? `${parentNodeDirectory}/pages/${entry.name}`
+				: entry.name;
+			const nodeLabel = `${pagesLabel}/${entry.name}`;
+			const nodeDir = path.join(pagesDir, entry.name);
+			const contentPath = path.join(nodeDir, 'content.md');
+			const categoryPath = path.join(nodeDir, 'category.yaml');
+			const [hasContent, hasCategory] = await Promise.all([
+				fileExists(contentPath),
+				fileExists(categoryPath),
+			]);
+			const metadata = parsePageDirectoryPath(pageDirectory, nodeLabel);
+
+			if (hasContent === hasCategory) {
+				const problem = hasContent
+					? 'contains both content.md and category.yaml'
+					: 'contains neither content.md nor category.yaml';
+				throw new Error(`${nodeLabel} ${problem}. Keep exactly one: content.md for a page, or category.yaml for a navigation category.`);
+			}
+
+			const isHome = pageDirectory === homePageDirectory;
+			if (isHome && hasCategory) {
+				throw new Error(`${nodeLabel}/category.yaml is invalid. The homepage must be a page with content.md.`);
+			}
+
+			const node = {
+				...metadata,
+				isHome,
+				kind: hasCategory ? 'category' : 'page',
+				nodeDir,
+				nodeLabel,
+				pagePath: isHome ? '' : metadata.pagePath,
+				parentPagePath: isHome ? null : metadata.parentPagePath,
+			};
+
+			if (hasCategory) {
+				if (await fileExists(path.join(nodeDir, 'images'))) {
+					throw new Error(`${nodeLabel} is a navigation category and cannot contain images/. Use content.md when the collection needs editorial content or images.`);
+				}
+				const category = await readCategory(categoryPath, `${nodeLabel}/category.yaml`);
+				Object.assign(node, {
+					categorySourceLabel: `${nodeLabel}/category.yaml`,
+					categoryPath,
+					label: category.label,
+				});
+			} else {
+				Object.assign(node, {
+					contentLabel: `${nodeLabel}/content.md`,
+					contentPath,
+					imagesDir: path.join(nodeDir, 'images'),
+					imagesLabel: `${nodeLabel}/images`,
+				});
+			}
+
+			siblingNodes.push(node);
+		}
+
+		assertUniqueSiblings(siblingNodes, pagesLabel);
+
+		for (const node of siblingNodes.sort(compareNodeMetadata)) {
+			nodes.push(node);
+			const childPagesDir = path.join(node.nodeDir, 'pages');
+			const childDirectories = (await readDirectory(childPagesDir)).filter((entry) => entry.isDirectory());
+
+			if (node.isHome && childDirectories.length > 0) {
+				throw new Error([
+					`${node.nodeLabel} is the homepage and cannot contain child pages.`,
+					`Move these page directories beside ${homePageDirectory} under ${sitePagesLabel}/, or below another non-home page:`,
+					...childDirectories.map(({ name }) => `- ${node.nodeLabel}/pages/${name}`),
+				].join('\n'));
+			}
+
+			if (node.kind === 'category' && childDirectories.length === 0) {
+				warnings.push({
+					code: 'empty-category',
+					label: node.categorySourceLabel,
+					message: `${node.categorySourceLabel} defines an empty navigation category. Add at least one child page under ${node.nodeLabel}/pages/.`,
+				});
+			}
+
+			if (!node.isHome && childDirectories.length > 0) {
+				await collectNodes(childPagesDir, `${node.nodeLabel}/pages`, node.pageDirectory);
+			}
+		}
+	};
+
+	await collectNodes(sitePagesDir, sitePagesLabel);
+	if (!nodes.some(({ isHome }) => isHome)) {
+		throw new Error(`Homepage content is missing. Create ${siteContentLabel}.`);
+	}
+
+	return {
+		categories: nodes.filter(({ kind }) => kind === 'category'),
+		contentFiles: nodes.filter(({ kind }) => kind === 'page'),
+		nodes,
+		warnings,
+	};
+};
+
+export const getContentFiles = async () => (await getSiteStructure()).contentFiles;