@janga/norna 0.7.0

package/scripts/sync-content-sections.mjs

@@ -0,0 +1,610 @@
+import { mkdir, rename, stat, writeFile } from 'node:fs/promises';
+import { createInterface } from 'node:readline/promises';
+import { stdin as input, stdout as output } from 'node:process';
+import path from 'node:path';
+import {
+	getBodySections,
+	getContentFiles,
+	getFrontmatterSections,
+	getFrontmatterInlineStyleNames,
+	getImageIndex,
+	getInlineStyleReferences,
+	readSiteFile,
+	readThemeFile,
+	toPosixPath,
+	validateContentFrontmatterStructure,
+	validateFrontmatterIndentation,
+	validateThemeFrontmatterStructure,
+} from './lib/site-content.mjs';
+import { readImageDimensions } from './lib/image-dimensions.mjs';
+import {
+	siteContentLabel,
+	siteContentPath,
+	siteImagesDir,
+	siteImagesLabel,
+	siteThemeLabel,
+	siteThemePath,
+} from './lib/site-paths.mjs';
+
+const args = new Set(process.argv.slice(2));
+const shouldWrite = args.has('--write');
+const shouldCheck = args.has('--check') || !shouldWrite;
+const skipPrompt = args.has('--yes');
+const issues = [];
+
+const addIssue = ({ severity, message, fix, sectionId, sectionLabel }) => {
+	issues.push({ severity, message, fix, sectionId, sectionLabel });
+};
+
+const fail = (message) => {
+	addIssue({ severity: 'error', message });
+};
+
+const warn = (message) => {
+	addIssue({ severity: 'warning', message });
+};
+
+const addSectionIssue = (sectionId, issue) => {
+	addIssue({
+		...issue,
+		sectionId,
+		sectionLabel: issue.sectionLabel ?? sectionId,
+	});
+};
+
+const hasErrors = () => issues.some((issue) => issue.severity === 'error');
+
+const promptForWrite = async () => {
+	if (skipPrompt) return true;
+	if (!process.stdin.isTTY) return false;
+
+	const rl = createInterface({ input, output });
+	const answer = await rl.question(`This will rewrite Markdown sections in ${siteContentLabel} and move gallery image files if needed. Continue? [y/N] `);
+	rl.close();
+
+	return answer.trim().toLowerCase() === 'y';
+};
+
+const { frontmatter, body } = await readSiteFile(siteContentPath);
+validateFrontmatterIndentation(frontmatter, addIssue);
+validateContentFrontmatterStructure(frontmatter, addIssue);
+let themeFrontmatter = null;
+try {
+	themeFrontmatter = (await readThemeFile(siteThemePath)).frontmatter;
+	validateFrontmatterIndentation(themeFrontmatter, addIssue);
+	validateThemeFrontmatterStructure(themeFrontmatter, addIssue);
+} catch (error) {
+	if (error?.code === 'ENOENT') {
+		themeFrontmatter = null;
+	} else {
+		throw error;
+	}
+}
+const frontmatterSections = getFrontmatterSections(frontmatter);
+const themeInlineStyleNames = themeFrontmatter
+	? getFrontmatterInlineStyleNames(themeFrontmatter)
+	: new Set();
+const frontmatterIds = frontmatterSections.map((section) => section.id);
+const { prelude, sections } = getBodySections(body);
+const sectionsById = new Map();
+const extraSections = [];
+const imageIndex = await getImageIndex(siteImagesDir, fail);
+const imageMoves = [];
+const referencedImages = new Map();
+
+const getUnreferencedImages = () => Array.from(imageIndex.entries())
+	.filter(([imageName]) => !referencedImages.has(imageName))
+	.map(([, imagePath]) => `${siteImagesLabel}/${toPosixPath(path.relative(siteImagesDir, imagePath))}`)
+	.sort((left, right) => left.localeCompare(right, 'sv'));
+
+const getSectionReportOrder = () => {
+	const order = new Map();
+	frontmatterIds.forEach((id, index) => order.set(id, index));
+	extraSections.forEach((section, index) => {
+		if (!order.has(section.id)) {
+			order.set(section.id, frontmatterIds.length + index);
+		}
+	});
+	return order;
+};
+
+const groupIssuesBySeverity = (groupedIssues) => [
+	['error', 'Errors'],
+	['warning', 'Warnings'],
+].map(([severity, label]) => ({
+	label,
+	issues: groupedIssues.filter((issue) => issue.severity === severity),
+})).filter((group) => group.issues.length > 0);
+
+const getGreatestCommonDivisor = (left, right) => {
+	let a = Math.abs(left);
+	let b = Math.abs(right);
+
+	while (b !== 0) {
+		const next = a % b;
+		a = b;
+		b = next;
+	}
+
+	return a || 1;
+};
+
+const getAspectRatioLabel = ({ width, height }) => {
+	const divisor = getGreatestCommonDivisor(width, height);
+	return `${width / divisor}:${height / divisor}`;
+};
+
+const warnAboutCarouselAspectRatios = async () => {
+	for (const section of frontmatterSections) {
+		for (const carousel of section.carousels ?? []) {
+			const imagesWithRatios = [];
+
+			for (const { image } of carousel.imageReferences ?? []) {
+				const imagePath = imageIndex.get(image);
+				if (!imagePath) continue;
+
+				const dimensions = await readImageDimensions(imagePath).catch(() => null);
+				if (!dimensions) continue;
+
+				imagesWithRatios.push({
+					image,
+					ratio: getAspectRatioLabel(dimensions),
+				});
+			}
+
+			const ratios = new Set(imagesWithRatios.map(({ ratio }) => ratio));
+			if (ratios.size <= 1) continue;
+
+			addSectionIssue(section.id, {
+				severity: 'warning',
+				message: `Carousel on line ${carousel.line} uses images with different aspect ratios: ${imagesWithRatios.map(({ image, ratio }) => `${image} (${ratio})`).join(', ')}.`,
+				fix: 'Use images with exactly matching proportions in the same carousel to avoid uneven layout and motion.',
+			});
+		}
+	}
+};
+
+const getFrontmatterSlug = (frontmatter) =>
+	frontmatter.match(/^slug:\s*["']?([^"'\n]+)["']?\s*$/m)?.[1]?.trim() ?? null;
+
+const validateRouteContentFiles = async () => {
+	const routeContentFiles = (await getContentFiles()).filter((contentFile) => !contentFile.isHome);
+
+	for (const contentFile of routeContentFiles) {
+		const { frontmatter: routeFrontmatter, body: routeBody } = await readSiteFile(contentFile.contentPath, contentFile.contentLabel);
+		validateFrontmatterIndentation(routeFrontmatter, addIssue);
+		validateContentFrontmatterStructure(routeFrontmatter, addIssue);
+
+		const slug = getFrontmatterSlug(routeFrontmatter);
+		if (slug && slug !== contentFile.routeFolder) {
+			addIssue({
+				severity: 'warning',
+				message: `${contentFile.contentLabel} has slug "${slug}" but its route folder is "${contentFile.routeFolder}".`,
+				fix: `Keep slug and route folder aligned unless the page intentionally needs to build at /${slug}/.`,
+			});
+		}
+
+		const routeFrontmatterSections = getFrontmatterSections(routeFrontmatter);
+		const routeFrontmatterIds = routeFrontmatterSections.map((section) => section.id);
+		const routeBodySections = getBodySections(routeBody).sections;
+		const routeSectionsById = new Map();
+		const routeImageIndex = await getImageIndex(contentFile.imagesDir, fail);
+
+		for (const section of routeBodySections) {
+			const sectionLabel = `${contentFile.contentLabel} [${section.id ?? section.heading}]`;
+
+			if (!section.id) {
+				addIssue({
+					severity: 'warning',
+					sectionLabel,
+					message: 'Markdown section is missing an explicit heading id.',
+					fix: `Write the heading with an explicit id, for example "${section.heading} {#section-id}".`,
+				});
+				continue;
+			}
+
+			if (routeSectionsById.has(section.id)) {
+				addIssue({
+					severity: 'error',
+					sectionId: `${contentFile.contentLabel}:${section.id}`,
+					sectionLabel,
+					message: `Duplicate Markdown section heading id "${section.id}".`,
+					fix: 'Each Markdown level 2 section heading must use a unique explicit id.',
+				});
+				continue;
+			}
+
+			routeSectionsById.set(section.id, section);
+		}
+
+		for (const id of routeFrontmatterIds) {
+			if (!routeSectionsById.has(id)) {
+				addIssue({
+					severity: 'error',
+					sectionId: `${contentFile.contentLabel}:${id}`,
+					sectionLabel: `${contentFile.contentLabel} [${id}]`,
+					message: `Cannot find a Markdown heading for section "${id}".`,
+					fix: `Add a level 2 Markdown heading, for example "## Heading {#${id}}".`,
+				});
+			}
+		}
+
+		for (const section of routeBodySections) {
+			if (section.id && !routeFrontmatterIds.includes(section.id)) {
+				addIssue({
+					severity: 'warning',
+					sectionId: `${contentFile.contentLabel}:${section.id}`,
+					sectionLabel: `${contentFile.contentLabel} [${section.id}]`,
+					message: `Markdown section "${section.id}" exists but is not used in frontmatter.`,
+					fix: 'Add it to frontmatter sections or remove the unused Markdown section.',
+				});
+			}
+		}
+
+		const currentOrder = routeBodySections.map((section) => section.id).filter(Boolean);
+		const expectedOrder = routeFrontmatterIds.filter((id) => routeSectionsById.has(id));
+		if (
+			currentOrder.length !== expectedOrder.length ||
+			currentOrder.some((id, index) => id !== expectedOrder[index])
+		) {
+			addIssue({
+				severity: 'warning',
+				message: `${contentFile.contentLabel} Markdown section order differs from frontmatter.`,
+			});
+		}
+
+		for (const section of routeFrontmatterSections) {
+			for (const imageName of section.images) {
+				if (imageName.includes('/') || imageName.includes('\\')) {
+					addIssue({
+						severity: 'error',
+						sectionId: `${contentFile.contentLabel}:${section.id}`,
+						sectionLabel: `${contentFile.contentLabel} [${section.id}]`,
+						message: `Image reference "${imageName}" must be a filename without a directory.`,
+						fix: `Use only the filename in ${contentFile.contentLabel} and keep the file in the matching ${contentFile.imagesLabel}/<section-id>/ directory.`,
+					});
+					continue;
+				}
+
+				if (referencedImages.has(imageName)) {
+					const previousSectionId = referencedImages.get(imageName);
+					const message = `Image "${imageName}" is referenced more than once, in "${previousSectionId}" and "${contentFile.contentLabel}:${section.id}".`;
+					const fix = 'Each image filename can be referenced by only one gallery row.';
+
+					addIssue({ severity: 'error', sectionId: previousSectionId, message, fix });
+					addIssue({
+						severity: 'error',
+						sectionId: `${contentFile.contentLabel}:${section.id}`,
+						sectionLabel: `${contentFile.contentLabel} [${section.id}]`,
+						message,
+						fix,
+					});
+					continue;
+				}
+
+				referencedImages.set(imageName, `${contentFile.contentLabel}:${section.id}`);
+
+				const imagePath = routeImageIndex.get(imageName);
+				if (!imagePath) {
+					addIssue({
+						severity: 'error',
+						sectionId: `${contentFile.contentLabel}:${section.id}`,
+						sectionLabel: `${contentFile.contentLabel} [${section.id}]`,
+						message: `Image "${imageName}" does not exist anywhere under ${contentFile.imagesLabel}/.`,
+						fix: `Add the source image to ${contentFile.imagesLabel}/${section.id}/ or remove the gallery row.`,
+					});
+					continue;
+				}
+
+				const currentDirectory = path.basename(path.dirname(imagePath));
+				if (currentDirectory !== section.id) {
+					addIssue({
+						severity: 'error',
+						sectionId: `${contentFile.contentLabel}:${section.id}`,
+						sectionLabel: `${contentFile.contentLabel} [${section.id}]`,
+						message: `Image "${imageName}" is used here but is located in ${contentFile.imagesLabel}/${currentDirectory}/.`,
+						fix: 'Move it to the matching section image directory.',
+					});
+				}
+			}
+
+			for (const carousel of section.carousels ?? []) {
+				const imagesWithRatios = [];
+
+				for (const { image } of carousel.imageReferences ?? []) {
+					const imagePath = routeImageIndex.get(image);
+					if (!imagePath) continue;
+
+					const dimensions = await readImageDimensions(imagePath).catch(() => null);
+					if (!dimensions) continue;
+
+					imagesWithRatios.push({
+						image,
+						ratio: getAspectRatioLabel(dimensions),
+					});
+				}
+
+				const ratios = new Set(imagesWithRatios.map(({ ratio }) => ratio));
+				if (ratios.size <= 1) continue;
+
+				addIssue({
+					severity: 'warning',
+					sectionId: `${contentFile.contentLabel}:${section.id}`,
+					sectionLabel: `${contentFile.contentLabel} [${section.id}]`,
+					message: `Carousel on line ${carousel.line} uses images with different aspect ratios: ${imagesWithRatios.map(({ image, ratio }) => `${image} (${ratio})`).join(', ')}.`,
+					fix: 'Use images with exactly matching proportions in the same carousel to avoid uneven layout and motion.',
+				});
+			}
+		}
+
+		for (const styleName of new Set(getInlineStyleReferences(routeBody))) {
+			if (!themeInlineStyleNames.has(styleName)) {
+				addIssue({
+					severity: 'error',
+					message: `Inline style ".${styleName}" is used in ${contentFile.contentLabel} but is not defined in ${siteThemeLabel} presentation.inlineStyles.`,
+					fix: `Add presentation.inlineStyles.${styleName} to ${siteThemeLabel} or remove "{.${styleName}}" from Markdown.`,
+				});
+			}
+		}
+	}
+};
+
+const formatIssue = (issue) => [
+	`- ${issue.message}`,
+	issue.fix ? `  Fix: ${issue.fix}` : null,
+].filter(Boolean);
+
+const getReportLines = (title) => {
+	const lines = [title];
+	const sectionIssues = issues.filter((issue) => issue.sectionId || issue.sectionLabel);
+	const globalIssues = issues.filter((issue) => !issue.sectionId && !issue.sectionLabel);
+
+	if (sectionIssues.length > 0) {
+		const sectionOrder = getSectionReportOrder();
+		const sectionGroups = new Map();
+
+		for (const issue of sectionIssues) {
+			const key = issue.sectionId ?? issue.sectionLabel;
+			const label = issue.sectionLabel ?? issue.sectionId;
+
+			if (!sectionGroups.has(key)) {
+				sectionGroups.set(key, { label, issues: [] });
+			}
+
+			sectionGroups.get(key).issues.push(issue);
+		}
+
+		const orderedSectionGroups = Array.from(sectionGroups.entries()).sort(([leftKey], [rightKey]) => (
+			(sectionOrder.get(leftKey) ?? Number.MAX_SAFE_INTEGER) -
+			(sectionOrder.get(rightKey) ?? Number.MAX_SAFE_INTEGER) ||
+			leftKey.localeCompare(rightKey, 'sv')
+		));
+
+		lines.push('', 'Section and Gallery Issues');
+
+		for (const [, group] of orderedSectionGroups) {
+			lines.push('', `[${group.label}]`);
+
+			for (const severityGroup of groupIssuesBySeverity(group.issues)) {
+				lines.push(`  ${severityGroup.label}:`);
+
+				for (const issue of severityGroup.issues) {
+					for (const line of formatIssue(issue)) {
+						lines.push(`  ${line}`);
+					}
+				}
+			}
+		}
+	}
+
+	if (globalIssues.length > 0) {
+		lines.push('', 'Global Content Issues');
+
+		for (const severityGroup of groupIssuesBySeverity(globalIssues)) {
+			lines.push('', `${severityGroup.label}:`);
+
+			for (const issue of severityGroup.issues) {
+				lines.push(...formatIssue(issue));
+			}
+		}
+	}
+
+	const unreferencedImages = getUnreferencedImages();
+
+	if (unreferencedImages.length > 0) {
+		lines.push(
+			'',
+			'Unreferenced Images',
+			`These files are kept in ${siteImagesLabel}/ but are not mounted on the site:`,
+		);
+
+		for (const imagePath of unreferencedImages) {
+			lines.push(`- ${imagePath}`);
+		}
+	}
+
+	return lines;
+};
+
+const printReport = (title) => {
+	const lines = getReportLines(title);
+	const output = hasErrors() ? console.error : console.log;
+	output(lines.join('\n'));
+};
+
+for (const section of sections) {
+	if (!section.id) {
+		addSectionIssue(null, {
+			severity: 'warning',
+			sectionLabel: section.heading,
+			message: 'Markdown section is missing an explicit heading id.',
+			fix: `Write the heading with an explicit id, for example "${section.heading} {#section-id}".`,
+		});
+		continue;
+	}
+
+	if (sectionsById.has(section.id)) {
+		addSectionIssue(section.id, {
+			severity: 'error',
+			message: `Duplicate Markdown section heading id "${section.id}".`,
+			fix: 'Each Markdown level 2 section heading must use a unique explicit id.',
+		});
+		continue;
+	}
+
+	sectionsById.set(section.id, section);
+}
+
+for (const id of frontmatterIds) {
+	if (!sectionsById.has(id)) {
+		addSectionIssue(id, {
+			severity: 'error',
+			message: `Cannot find a Markdown heading for section "${id}".`,
+			fix: `Add a level 2 Markdown heading, for example "## Heading {#${id}}".`,
+		});
+	}
+}
+
+for (const section of sections) {
+	if (section.id && !frontmatterIds.includes(section.id)) {
+		addSectionIssue(section.id, {
+			severity: 'warning',
+			message: `Markdown section "${section.id}" exists but is not used in frontmatter.`,
+			fix: 'Add it to frontmatter sections or remove the unused Markdown section.',
+		});
+		extraSections.push(section);
+	}
+}
+
+const orderedSections = [
+	...frontmatterIds.map((id) => sectionsById.get(id)).filter(Boolean),
+	...extraSections,
+];
+const currentOrder = sections.map((section) => section.id).filter(Boolean);
+const expectedOrder = orderedSections.map((section) => section.id).filter(Boolean);
+const hasOrderMismatch =
+	currentOrder.length !== expectedOrder.length ||
+	currentOrder.some((id, index) => id !== expectedOrder[index]);
+
+if (hasOrderMismatch) {
+	warn('Markdown section order differs from frontmatter.');
+}
+
+for (const section of frontmatterSections) {
+	for (const imageName of section.images) {
+		if (imageName.includes('/') || imageName.includes('\\')) {
+			addSectionIssue(section.id, {
+				severity: 'error',
+				message: `Image reference "${imageName}" must be a filename without a directory.`,
+				fix: `Use only the filename in ${siteContentLabel} and keep the file in the matching ${siteImagesLabel}/<section-id>/ directory.`,
+			});
+			continue;
+		}
+
+		if (referencedImages.has(imageName)) {
+			const previousSectionId = referencedImages.get(imageName);
+			const message = previousSectionId === section.id
+				? `Image "${imageName}" is referenced more than once in this section.`
+				: `Image "${imageName}" is referenced more than once, in sections "${previousSectionId}" and "${section.id}".`;
+			const fix = 'Each image filename can be referenced by only one gallery row.';
+
+			addSectionIssue(previousSectionId, { severity: 'error', message, fix });
+			if (previousSectionId !== section.id) {
+				addSectionIssue(section.id, { severity: 'error', message, fix });
+			}
+			continue;
+		}
+
+		referencedImages.set(imageName, section.id);
+
+		const imagePath = imageIndex.get(imageName);
+		if (!imagePath) {
+			addSectionIssue(section.id, {
+				severity: 'error',
+				message: `Image "${imageName}" does not exist anywhere under ${siteImagesLabel}/.`,
+				fix: `Add the source image to ${siteImagesLabel}/${section.id}/ or remove the gallery row.`,
+			});
+			continue;
+		}
+
+		const currentDirectory = path.basename(path.dirname(imagePath));
+		if (currentDirectory !== section.id) {
+			const targetPath = path.join(siteImagesDir, section.id, imageName);
+			const targetExists = await stat(targetPath).then((entry) => entry.isFile()).catch(() => false);
+
+			if (targetExists) {
+				addSectionIssue(section.id, {
+					severity: 'error',
+					message: `Cannot move image "${imageName}" to ${siteImagesLabel}/${section.id}/ because the target file already exists.`,
+					fix: 'Rename one of the files so image filenames remain globally unique.',
+				});
+				continue;
+			}
+
+			imageMoves.push({ imageName, from: imagePath, to: targetPath, sectionId: section.id });
+
+			if (!shouldWrite) {
+				addSectionIssue(section.id, {
+					severity: 'error',
+					message: `Image "${imageName}" is used here but is located in ${siteImagesLabel}/${currentDirectory}/.`,
+					fix: 'Run norna content:sync, or npm run norna:sync in starter-style repositories, to move it.',
+				});
+			}
+		}
+	}
+}
+
+await warnAboutCarouselAspectRatios();
+
+for (const styleName of new Set(getInlineStyleReferences(body))) {
+	if (!themeInlineStyleNames.has(styleName)) {
+		addIssue({
+			severity: 'error',
+			message: `Inline style ".${styleName}" is used in Markdown but is not defined in ${siteThemeLabel} presentation.inlineStyles.`,
+			fix: `Add presentation.inlineStyles.${styleName} to ${siteThemeLabel} or remove "{.${styleName}}" from Markdown.`,
+		});
+	}
+}
+
+await validateRouteContentFiles();
+
+if (hasErrors()) {
+	printReport(shouldWrite ? 'Content sync failed.' : 'Content check failed.');
+	process.exit(1);
+}
+
+if (shouldCheck) {
+	const title = issues.length > 0
+		? 'Content check completed with warnings.'
+		: 'Content check passed.';
+	printReport(title);
+	process.exit(0);
+}
+
+if (!hasOrderMismatch && imageMoves.length === 0) {
+	console.log(`${siteContentLabel}: no sync needed.`);
+	process.exit(0);
+}
+
+if (issues.length > 0) {
+	printReport('Content sync completed with warnings.');
+}
+
+const canWrite = await promptForWrite();
+
+if (!canWrite) {
+	console.log('Aborted. No file was changed.');
+	process.exit(1);
+}
+
+const nextBody = `${prelude}${orderedSections.map((section) => section.text).join('\n')}\n`;
+if (hasOrderMismatch) {
+	await writeFile(siteContentPath, `${frontmatter}${nextBody}`);
+	console.log(`${siteContentLabel}: Markdown sections were sorted according to frontmatter.`);
+}
+
+for (const move of imageMoves) {
+	await mkdir(path.dirname(move.to), { recursive: true });
+	await rename(move.from, move.to);
+	console.log(`Moved image "${move.imageName}" to ${siteImagesLabel}/${move.sectionId}/.`);
+}

package/scripts/sync-site-public.mjs

@@ -0,0 +1,42 @@
+import { cp, mkdir, readdir, rm } from 'node:fs/promises';
+import path from 'node:path';
+import {
+	astroPublicDir,
+	astroPublicLabel,
+	sitePublicDir,
+	sitePublicLabel,
+} from './lib/site-paths.mjs';
+
+const keepAstroPublicEntries = new Set(['images']);
+
+const readDirectory = async (directory) => {
+	try {
+		return await readdir(directory, { withFileTypes: true });
+	} catch (error) {
+		if (error?.code === 'ENOENT') {
+			return [];
+		}
+
+		throw error;
+	}
+};
+
+await mkdir(astroPublicDir, { recursive: true });
+
+for (const entry of await readDirectory(astroPublicDir)) {
+	if (keepAstroPublicEntries.has(entry.name)) {
+		continue;
+	}
+
+	await rm(path.join(astroPublicDir, entry.name), { force: true, recursive: true });
+}
+
+for (const entry of await readDirectory(sitePublicDir)) {
+	await cp(
+		path.join(sitePublicDir, entry.name),
+		path.join(astroPublicDir, entry.name),
+		{ force: true, recursive: true },
+	);
+}
+
+console.log(`Synced ${sitePublicLabel}/ to ${astroPublicLabel}/.`);