@janga/norna 0.7.6 → 0.7.8

package/scripts/sync-content-sections.mjs

@@ -1,13 +1,20 @@
-import { mkdir, rename, stat, writeFile } from 'node:fs/promises';
+import { execFile } from 'node:child_process';
+import { mkdir, rename, stat } 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 { promisify } from 'node:util';
+import {
+	extractMarkdownImageReferences,
+	extractNornaMarkdownBlockDiagnostics,
+	getNornaBlockImageReferences,
+} from './lib/norna-markdown-blocks.mjs';
 import {
 	getBodySections,
 	getContentFiles,
-	getFrontmatterSections,
 	getFrontmatterInlineStyleNames,
-	getImageIndex,
+	getFrontmatterSections,
+	getImageCandidatesByName,
 	getInlineStyleReferences,
 	readSiteFile,
 	readThemeFile,
@@ -18,96 +25,52 @@ import {
 } from './lib/site-content.mjs';
 import { readImageDimensions } from './lib/image-dimensions.mjs';
 import {
-	siteContentLabel,
-	siteContentPath,
-	siteImagesDir,
-	siteImagesLabel,
 	siteThemeLabel,
 	siteThemePath,
+	siteProjectRoot,
 } from './lib/site-paths.mjs';
 
+const execFileAsync = promisify(execFile);
+
 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 imageMoves = [];
+const referencedImagePaths = new Set();
 
 const addIssue = ({ severity, message, fix, sectionId, sectionLabel }) => {
 	issues.push({ severity, message, fix, sectionId, sectionLabel });
 };
 
-const fail = (message) => {
-	addIssue({ severity: 'error', message });
-};
+const hasErrors = () => issues.some((issue) => issue.severity === 'error');
 
-const warn = (message) => {
-	addIssue({ severity: 'warning', message });
-};
+const formatSectionLabel = (contentFile, section) => `${contentFile.contentLabel} [${section.id ?? section.heading}]`;
 
-const addSectionIssue = (sectionId, issue) => {
-	addIssue({
-		...issue,
-		sectionId,
-		sectionLabel: issue.sectionLabel ?? sectionId,
-	});
-};
+const addContentIssue = (contentFile, issue) => addIssue({
+	...issue,
+	sectionId: issue.sectionId ?? contentFile.contentLabel,
+	sectionLabel: issue.sectionLabel ?? contentFile.contentLabel,
+});
 
-const hasErrors = () => issues.some((issue) => issue.severity === 'error');
+const addSectionIssue = (contentFile, section, issue) => addIssue({
+	...issue,
+	sectionId: issue.sectionId ?? `${contentFile.contentLabel}:${section.id ?? section.heading}`,
+	sectionLabel: issue.sectionLabel ?? formatSectionLabel(contentFile, section),
+});
 
 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 image files if needed. Continue? [y/N] `);
+	const answer = await rl.question('This will move image files into the page or route image roots where Norna references them. 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'],
@@ -116,239 +79,17 @@ const groupIssuesBySeverity = (groupedIssues) => [
 	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 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 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 image 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 image 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 getReportLines = (title, unreferencedImages) => {
 	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) {
@@ -362,15 +103,9 @@ const getReportLines = (title) => {
 			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 Image Issues');
+		lines.push('', 'Content Issues');
 
-		for (const [, group] of orderedSectionGroups) {
+		for (const [, group] of Array.from(sectionGroups.entries()).sort(([left], [right]) => left.localeCompare(right, 'sv'))) {
 			lines.push('', `[${group.label}]`);
 
 			for (const severityGroup of groupIssuesBySeverity(group.issues)) {
@@ -397,13 +132,11 @@ const getReportLines = (title) => {
 		}
 	}
 
-	const unreferencedImages = getUnreferencedImages();
-
 	if (unreferencedImages.length > 0) {
 		lines.push(
 			'',
 			'Unreferenced Images',
-			`These files are kept in ${siteImagesLabel}/ but are not mounted on the site:`,
+			'These files are kept under page or route image roots but are not referenced by Norna-managed image references:',
 		);
 
 		for (const imagePath of unreferencedImages) {
@@ -414,185 +147,454 @@ const getReportLines = (title) => {
 	return lines;
 };
 
-const printReport = (title) => {
-	const lines = getReportLines(title);
-	const output = hasErrors() ? console.error : console.log;
-	output(lines.join('\n'));
+const printReport = (title, unreferencedImages) => {
+	const lines = getReportLines(title, unreferencedImages);
+	const target = hasErrors() ? console.error : console.log;
+	target(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}".`,
+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 getExpectedImagePath = (contentFile, sectionId, imageName) =>
+	path.join(contentFile.imagesDir, sectionId, imageName);
+
+const getExpectedImageLabel = (contentFile, sectionId, imageName) =>
+	`${contentFile.imagesLabel}/${sectionId}/${imageName}`;
+
+const getGlobalImageCandidates = (globalImageCandidatesByName, imageName, expectedPath) =>
+	(globalImageCandidatesByName.get(imageName) ?? []).filter(({ imagePath }) => imagePath !== expectedPath);
+
+const getReferenceLabel = (contentFile, section) => `${contentFile.contentLabel} [${section.id}]`;
+
+const getRootLabel = (contentFile) => contentFile.isHome
+	? contentFile.imagesLabel
+	: contentFile.imagesLabel.replace(/\/images$/, '');
+
+const getCandidateLabel = ({ contentFile, imagePath }) =>
+	`${contentFile.imagesLabel}/${toPosixPath(path.relative(contentFile.imagesDir, imagePath))}`;
+
+const addExpectedReference = (expectedReferencesByPath, expectedPath, expectedReference) => {
+	if (!expectedReferencesByPath.has(expectedPath)) {
+		expectedReferencesByPath.set(expectedPath, []);
+	}
+
+	expectedReferencesByPath.get(expectedPath).push(expectedReference);
+};
+
+const addGlobalImageCandidate = (globalImageCandidatesByName, imageName, candidate) => {
+	if (!globalImageCandidatesByName.has(imageName)) {
+		globalImageCandidatesByName.set(imageName, []);
+	}
+
+	globalImageCandidatesByName.get(imageName).push(candidate);
+};
+
+const assertCleanGitForCrossRootSync = async (moves) => {
+	if (!moves.some((move) => move.crossRoot)) return;
+
+	let stdout = '';
+	try {
+		({ stdout } = await execFileAsync('git', ['status', '--short'], {
+			cwd: siteProjectRoot,
+			maxBuffer: 1024 * 1024,
+		}));
+	} catch (error) {
+		addIssue({
+			severity: 'error',
+			message: 'Cross-route content sync requires a clean git working tree, but git status could not be checked.',
+			fix: 'Run content:sync inside a Git worktree, or move cross-route image files manually.',
 		});
-		continue;
+		return;
 	}
 
-	if (sectionsById.has(section.id)) {
-		addSectionIssue(section.id, {
+	if (!stdout.trim()) return;
+
+	addIssue({
+		severity: 'error',
+		message: 'Cross-route content sync requires a clean git working tree before moving files between page or route image roots.',
+		fix: `Commit or stash your current changes, then run content:sync again. Current changes:\n${stdout.trim()}`,
+	});
+};
+
+const addConflictingMoveIssues = () => {
+	const movesBySource = new Map();
+	const movesByDestination = new Map();
+
+	for (const move of imageMoves) {
+		const sourceKey = move.from;
+		const destinationKey = move.to;
+
+		if (!movesBySource.has(sourceKey)) {
+			movesBySource.set(sourceKey, []);
+		}
+		movesBySource.get(sourceKey).push(move);
+
+		if (!movesByDestination.has(destinationKey)) {
+			movesByDestination.set(destinationKey, []);
+		}
+		movesByDestination.get(destinationKey).push(move);
+	}
+
+	for (const moves of movesBySource.values()) {
+		const destinations = new Set(moves.map((move) => move.to));
+		if (destinations.size <= 1) continue;
+
+		const firstMove = moves[0];
+		addSectionIssue(firstMove.contentFile, { id: firstMove.sectionId, heading: firstMove.sectionId }, {
 			severity: 'error',
-			message: `Duplicate Markdown section heading id "${section.id}".`,
-			fix: 'Each Markdown level 2 section heading must use a unique explicit id.',
+			message: `Cannot relocate "${firstMove.imageName}" because the same source file is referenced from multiple destinations: ${moves.map((move) => getExpectedImageLabel(move.contentFile, move.sectionId, move.imageName)).join(', ')}.`,
+			fix: 'Duplicate the image manually or rename one of the image files so each move has a single destination.',
 		});
-		continue;
 	}
 
-	sectionsById.set(section.id, section);
-}
+	for (const moves of movesByDestination.values()) {
+		const sources = new Set(moves.map((move) => move.from));
+		if (sources.size <= 1) continue;
 
-for (const id of frontmatterIds) {
-	if (!sectionsById.has(id)) {
-		addSectionIssue(id, {
+		const firstMove = moves[0];
+		addSectionIssue(firstMove.contentFile, { id: firstMove.sectionId, heading: firstMove.sectionId }, {
 			severity: 'error',
-			message: `Cannot find a Markdown heading for section "${id}".`,
-			fix: `Add a level 2 Markdown heading, for example "## Heading {#${id}}".`,
+			message: `Cannot relocate "${firstMove.imageName}" because multiple source files would move to ${getExpectedImageLabel(firstMove.contentFile, firstMove.sectionId, firstMove.imageName)}: ${moves.map((move) => getCandidateLabel(move.sourceContentFile ? { contentFile: move.sourceContentFile, imagePath: move.from } : move)).join(', ')}.`,
+			fix: 'Move the intended file manually or rename files so the destination is unambiguous.',
 		});
 	}
-}
+};
 
-for (const section of sections) {
-	if (section.id && !frontmatterIds.includes(section.id)) {
-		addSectionIssue(section.id, {
+const validateImageReference = async (
+	contentFile,
+	section,
+	reference,
+	globalImageCandidatesByName,
+	expectedReferencesByPath,
+) => {
+	const imageName = reference.image;
+	const expectedPath = getExpectedImagePath(contentFile, section.id, imageName);
+	const expectedLabel = getExpectedImageLabel(contentFile, section.id, imageName);
+	const expectedExists = await stat(expectedPath).then((entry) => entry.isFile()).catch(() => false);
+
+	if (expectedExists) {
+		referencedImagePaths.add(expectedPath);
+		return expectedPath;
+	}
+
+	const candidates = getGlobalImageCandidates(globalImageCandidatesByName, imageName, expectedPath);
+	if (candidates.length === 0) {
+		addSectionIssue(contentFile, section, {
+			severity: 'error',
+			message: `Image "${imageName}" does not exist at ${expectedLabel} or anywhere under any page or route image root.`,
+			fix: `Add the source image to ${contentFile.imagesLabel}/${section.id}/ or remove the Norna-managed image reference.`,
+		});
+		return null;
+	}
+
+	if (candidates.length > 1) {
+		addSectionIssue(contentFile, section, {
+			severity: 'error',
+			message: `Cannot relocate "${imageName}". Multiple files with this filename were found: ${candidates.map(getCandidateLabel).join(', ')}.`,
+			fix: 'Move the intended file manually or rename files so the move is unambiguous.',
+		});
+		return null;
+	}
+
+	const sourceCandidate = candidates[0];
+	const sourcePath = sourceCandidate.imagePath;
+	const referencesAtCurrentLocation = (expectedReferencesByPath.get(sourcePath) ?? [])
+		.filter((expectedReference) => expectedReference.contentFile !== contentFile || expectedReference.section.id !== section.id);
+
+	if (referencesAtCurrentLocation.length > 0) {
+		addSectionIssue(contentFile, section, {
+			severity: 'error',
+			message: `Cannot relocate "${imageName}" from ${getCandidateLabel(sourceCandidate)} because it is still referenced from ${referencesAtCurrentLocation.map((expectedReference) => getReferenceLabel(expectedReference.contentFile, expectedReference.section)).join(', ')}.`,
+			fix: 'Remove the extra reference, duplicate the image file manually, or rename one of the image files so the intended move is unambiguous.',
+		});
+		return null;
+	}
+
+	imageMoves.push({
+		imageName,
+		from: sourcePath,
+		to: expectedPath,
+		contentFile,
+		sourceContentFile: sourceCandidate.contentFile,
+		sectionId: section.id,
+		crossRoot: sourceCandidate.contentFile !== contentFile,
+	});
+	referencedImagePaths.add(sourcePath);
+
+	if (!shouldWrite) {
+		addSectionIssue(contentFile, section, {
+			severity: 'error',
+			message: `Image "${imageName}" is used here but is located in ${getCandidateLabel(sourceCandidate)}.`,
+			fix: sourceCandidate.contentFile === contentFile
+				? 'Run norna content:sync to move it inside the current page or route image root.'
+				: `Run norna content:sync to move it from ${getRootLabel(sourceCandidate.contentFile)} to ${getRootLabel(contentFile)}. Cross-route sync requires a clean git working tree when files are moved.`,
+		});
+	}
+
+	return sourcePath;
+};
+
+const warnAboutCarouselAspectRatios = async (contentFile, section, block, sourcePathsByImage) => {
+	if (block.type !== 'image-carousel') return;
+
+	const imagesWithRatios = [];
+	const imagesWithoutRatios = [];
+	for (const image of block.images) {
+		const imagePath = sourcePathsByImage.get(image.image);
+		if (!imagePath) continue;
+
+		const dimensions = await readImageDimensions(imagePath).catch(() => null);
+		if (!dimensions) {
+			imagesWithoutRatios.push(image.image);
+			continue;
+		}
+
+		imagesWithRatios.push({
+			image: image.image,
+			ratio: getAspectRatioLabel(dimensions),
+		});
+	}
+
+	if (imagesWithoutRatios.length > 0) {
+		addSectionIssue(contentFile, section, {
 			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.',
+			message: `Carousel on line ${block.line} uses images without an intrinsic aspect ratio: ${imagesWithoutRatios.join(', ')}.`,
+			fix: 'For SVG images, add a viewBox or numeric width and height when stable carousel sizing matters.',
 		});
-		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.');
+	const ratios = new Set(imagesWithRatios.map(({ ratio }) => ratio));
+	if (ratios.size <= 1) return;
+
+	addSectionIssue(contentFile, section, {
+		severity: 'warning',
+		message: `Carousel on line ${block.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.',
+	});
+};
+
+let themeFrontmatter = null;
+try {
+	themeFrontmatter = (await readThemeFile(siteThemePath)).frontmatter;
+	validateFrontmatterIndentation(themeFrontmatter, addIssue);
+	validateThemeFrontmatterStructure(themeFrontmatter, addIssue);
+} catch (error) {
+	if (error?.code !== 'ENOENT') {
+		throw error;
+	}
 }
 
-for (const section of frontmatterSections) {
-	for (const imageName of section.images) {
-		if (imageName.includes('/') || imageName.includes('\\')) {
-			addSectionIssue(section.id, {
+const themeInlineStyleNames = themeFrontmatter
+	? getFrontmatterInlineStyleNames(themeFrontmatter)
+	: new Set();
+
+const contentFiles = await getContentFiles();
+const allImageFiles = [];
+const contentFileContexts = [];
+const globalImageCandidatesByName = new Map();
+const globalExpectedReferencesByPath = new Map();
+
+for (const contentFile of contentFiles) {
+	const { frontmatter, body } = await readSiteFile(contentFile.contentPath, contentFile.contentLabel);
+	const bodyLineOffset = frontmatter.split(/\r?\n/).length - 1;
+	validateFrontmatterIndentation(frontmatter, addIssue);
+	validateContentFrontmatterStructure(frontmatter, addIssue);
+
+	const frontmatterSections = getFrontmatterSections(frontmatter);
+	const frontmatterIds = new Set(frontmatterSections.map((section) => section.id));
+	const { sections } = getBodySections(body);
+	const sectionsById = new Map();
+	const blockResultsBySectionId = new Map();
+	const imageCandidatesByName = await getImageCandidatesByName(contentFile.imagesDir);
+
+	for (const [imageName, candidates] of imageCandidatesByName) {
+		for (const imagePath of candidates) {
+			const candidate = { contentFile, imagePath };
+			allImageFiles.push(candidate);
+			addGlobalImageCandidate(globalImageCandidatesByName, imageName, candidate);
+		}
+	}
+
+	for (const section of sections) {
+		if (!section.id) {
+			addSectionIssue(contentFile, section, {
 				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.`,
+				message: `Section heading "${section.heading.replace(/^##\s+/, '')}" is missing an explicit id.`,
+				fix: `Write it as: ${section.heading} {#section-id}`,
 			});
 			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 image row.';
-
-			addSectionIssue(previousSectionId, { severity: 'error', message, fix });
-			if (previousSectionId !== section.id) {
-				addSectionIssue(section.id, { severity: 'error', message, fix });
-			}
+		if (sectionsById.has(section.id)) {
+			addSectionIssue(contentFile, section, {
+				severity: 'error',
+				message: `Duplicate Markdown section heading id "${section.id}".`,
+				fix: 'Each Markdown level 2 section heading must use a unique explicit id within the page.',
+			});
 			continue;
 		}
 
-		referencedImages.set(imageName, section.id);
+		sectionsById.set(section.id, section);
+	}
+
+	for (const section of sections) {
+		if (!section.id || !sectionsById.has(section.id)) continue;
+
+		const blockResults = extractNornaMarkdownBlockDiagnostics(section.text, {
+			label: contentFile.contentLabel,
+			lineOffset: bodyLineOffset + section.line - 1,
+		});
+		blockResultsBySectionId.set(section.id, blockResults);
+
+		for (const reference of getNornaBlockImageReferences(blockResults.blocks)) {
+			const expectedPath = getExpectedImagePath(contentFile, section.id, reference.image);
+			addExpectedReference(globalExpectedReferencesByPath, expectedPath, { contentFile, section, reference });
+		}
+	}
+
+	contentFileContexts.push({
+		contentFile,
+		frontmatterIds,
+		sections,
+		sectionsById,
+		blockResultsBySectionId,
+		body,
+	});
+}
 
-		const imagePath = imageIndex.get(imageName);
-		if (!imagePath) {
-			addSectionIssue(section.id, {
+for (const context of contentFileContexts) {
+	const {
+		contentFile,
+		frontmatterIds,
+		sections,
+		sectionsById,
+		blockResultsBySectionId,
+		body,
+	} = context;
+
+	for (const id of frontmatterIds) {
+		if (!sectionsById.has(id)) {
+			addContentIssue(contentFile, {
 				severity: 'error',
-				message: `Image "${imageName}" does not exist anywhere under ${siteImagesLabel}/.`,
-				fix: `Add the source image to ${siteImagesLabel}/${section.id}/ or remove the image row.`,
+				message: `Section metadata "${id}" does not match any Markdown section.`,
+				fix: `Add a level 2 Markdown heading, for example "## Heading {#${id}}", or remove sections.${id}.`,
 			});
-			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);
+	for (const styleName of new Set(getInlineStyleReferences(body))) {
+		if (!themeInlineStyleNames.has(styleName)) {
+			addContentIssue(contentFile, {
+				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.`,
+			});
+		}
+	}
 
-			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;
-			}
+	for (const section of sections) {
+		if (!section.id || !sectionsById.has(section.id)) continue;
 
-			imageMoves.push({ imageName, from: imagePath, to: targetPath, sectionId: section.id });
+		const markdownImages = extractMarkdownImageReferences(section.text);
+		for (const reference of markdownImages) {
+			addSectionIssue(contentFile, section, {
+				severity: 'warning',
+				message: `Markdown image "${reference.target}" references a local image that is not managed by Norna.`,
+				fix: 'Use a norna-image-stack, norna-image-carousel, or norna-card-list block for site images that should be validated, processed and synced.',
+			});
+		}
+
+		const { blocks, errors: blockErrors } = blockResultsBySectionId.get(section.id) ?? { blocks: [], errors: [] };
+		for (const error of blockErrors) {
+			addSectionIssue(contentFile, section, {
+				severity: 'error',
+				message: error.message,
+			});
+		}
 
-			if (!shouldWrite) {
-				addSectionIssue(section.id, {
+		for (const block of blocks) {
+			if (block.type === 'image-carousel' && block.images.length < 2) {
+				addSectionIssue(contentFile, section, {
 					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.',
+					message: `norna-image-carousel on line ${block.line} contains ${block.images.length} image. A carousel needs at least two images.`,
+					fix: 'Add another image entry, or use norna-image-stack for a single image.',
 				});
 			}
 		}
-	}
-}
 
-await warnAboutCarouselAspectRatios();
+		const sourcePathsByImage = new Map();
+		for (const reference of getNornaBlockImageReferences(blocks)) {
+			const sourcePath = await validateImageReference(
+				contentFile,
+				section,
+				reference,
+				globalImageCandidatesByName,
+				globalExpectedReferencesByPath,
+			);
+			if (sourcePath) {
+				sourcePathsByImage.set(reference.image, sourcePath);
+			}
+		}
 
-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.`,
-		});
+		for (const block of blocks) {
+			await warnAboutCarouselAspectRatios(contentFile, section, block, sourcePathsByImage);
+		}
 	}
 }
 
-await validateRouteContentFiles();
+const unreferencedImages = allImageFiles
+	.filter(({ imagePath }) => !referencedImagePaths.has(imagePath))
+	.map(({ contentFile, imagePath }) => `${contentFile.imagesLabel}/${toPosixPath(path.relative(contentFile.imagesDir, imagePath))}`)
+	.sort((left, right) => left.localeCompare(right, 'sv'));
+
+addConflictingMoveIssues();
+
+if (shouldWrite) {
+	await assertCleanGitForCrossRootSync(imageMoves);
+}
 
 if (hasErrors()) {
-	printReport(shouldWrite ? 'Content sync failed.' : 'Content check failed.');
+	printReport(shouldWrite ? 'Content sync failed.' : 'Content check failed.', unreferencedImages);
 	process.exit(1);
 }
 
 if (shouldCheck) {
-	const title = issues.length > 0
+	const title = issues.length > 0 || unreferencedImages.length > 0
 		? 'Content check completed with warnings.'
 		: 'Content check passed.';
-	printReport(title);
+	printReport(title, unreferencedImages);
 	process.exit(0);
 }
 
-if (!hasOrderMismatch && imageMoves.length === 0) {
-	console.log(`${siteContentLabel}: no sync needed.`);
+if (imageMoves.length === 0) {
+	console.log('No content 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}/.`);
+	console.log(`Moved image "${move.imageName}" to ${move.contentFile.imagesLabel}/${move.sectionId}/.`);
 }