@janga/norna 0.7.27 → 0.7.29

package/scripts/lib/documentation-routes.json

@@ -1,58 +1,66 @@
 {
   "sources": {
-    "site/files/": "site/pages/032-reference/pages/010-site/pages/010-files/content.md",
-    "site/pages/": "site/pages/032-reference/pages/010-site/pages/020-pages/content.md",
-    "site/urls/": "site/pages/032-reference/pages/010-site/pages/030-urls/content.md",
-    "site/metadata/": "site/pages/032-reference/pages/010-site/pages/040-metadata/content.md",
-    "site/images/": "site/pages/032-reference/pages/010-site/pages/050-images/content.md",
-    "site/public-files/": "site/pages/032-reference/pages/010-site/pages/060-public-files/content.md",
-    "site/requirements/": "site/pages/032-reference/pages/010-site/pages/070-requirements/content.md",
-    "configuration/site/": "site/pages/032-reference/pages/020-configuration/pages/010-site/content.md",
-    "configuration/language/": "site/pages/032-reference/pages/020-configuration/pages/020-language/content.md",
-    "configuration/navigation/": "site/pages/032-reference/pages/020-configuration/pages/030-navigation/content.md",
-    "configuration/search/": "site/pages/032-reference/pages/020-configuration/pages/040-search/content.md",
-    "configuration/source-links/": "site/pages/032-reference/pages/020-configuration/pages/050-source-links/content.md",
-    "configuration/theme/": "site/pages/032-reference/pages/020-configuration/pages/060-theme/content.md",
-    "configuration/presets/": "site/pages/032-reference/pages/020-configuration/pages/065-presets/content.md",
-    "configuration/palettes/": "site/pages/032-reference/pages/020-configuration/pages/070-palettes/content.md",
-    "configuration/appearance/": "site/pages/032-reference/pages/020-configuration/pages/080-appearance/content.md",
-    "configuration/layout/": "site/pages/032-reference/pages/020-configuration/pages/090-layout/content.md",
-    "configuration/images/": "site/pages/032-reference/pages/020-configuration/pages/100-images/content.md",
-    "configuration/typography/": "site/pages/032-reference/pages/020-configuration/pages/110-typography/content.md",
-    "configuration/sections/": "site/pages/032-reference/pages/020-configuration/pages/120-sections/content.md",
-    "configuration/shared-content/": "site/pages/032-reference/pages/020-configuration/pages/130-shared-content/content.md",
-    "content/markdown/": "site/pages/032-reference/pages/030-content/pages/010-markdown/content.md",
-    "content/structured-blocks/": "site/pages/032-reference/pages/030-content/pages/015-structured-blocks/content.md",
-    "content/images/": "site/pages/032-reference/pages/030-content/pages/020-images/content.md",
-    "content/cards/": "site/pages/032-reference/pages/030-content/pages/030-cards/content.md",
-    "content/child-lists/": "site/pages/032-reference/pages/030-content/pages/040-child-lists/content.md",
-    "content/callouts/": "site/pages/032-reference/pages/030-content/pages/050-callouts/content.md",
-    "content/tabs/": "site/pages/032-reference/pages/030-content/pages/060-tabs/content.md",
-    "content/details/": "site/pages/032-reference/pages/030-content/pages/070-details/content.md",
-    "content/tables/": "site/pages/032-reference/pages/030-content/pages/080-tables/content.md",
-    "content/code/": "site/pages/032-reference/pages/030-content/pages/090-code/content.md",
-    "content/sidenotes/": "site/pages/032-reference/pages/030-content/pages/100-sidenotes/content.md",
-    "content/footnotes/": "site/pages/032-reference/pages/030-content/pages/110-footnotes/content.md",
-    "commands/invocation/": "site/pages/032-reference/pages/040-commands/pages/010-invocation/content.md",
-    "commands/init/": "site/pages/032-reference/pages/040-commands/pages/020-init/content.md",
-    "commands/create/": "site/pages/032-reference/pages/040-commands/pages/030-create/content.md",
-    "commands/move/": "site/pages/032-reference/pages/040-commands/pages/040-move/content.md",
-    "commands/validate/": "site/pages/032-reference/pages/040-commands/pages/050-validate/content.md",
-    "commands/navigation/": "site/pages/032-reference/pages/040-commands/pages/055-navigation/content.md",
-    "commands/development/": "site/pages/032-reference/pages/040-commands/pages/060-development/content.md",
-    "commands/build/": "site/pages/032-reference/pages/040-commands/pages/070-build/content.md",
-    "commands/publishing/": "site/pages/032-reference/pages/040-commands/pages/080-publishing/content.md",
-    "commands/theme/": "site/pages/032-reference/pages/040-commands/pages/090-theme/content.md",
-    "commands/engine/": "site/pages/032-reference/pages/040-commands/pages/100-engine/content.md",
-    "commands/migration-audit/": "site/pages/032-reference/pages/040-commands/pages/110-migration-audit/content.md",
-    "reader/display/": "site/pages/032-reference/pages/050-reader/pages/010-display/content.md",
-    "reader/accessibility/": "site/pages/032-reference/pages/050-reader/pages/020-accessibility/content.md",
-    "workflows/editor/": "site/pages/032-reference/pages/060-workflows/pages/010-editor/content.md",
-    "workflows/editor-ai-suggestions/": "site/pages/032-reference/pages/060-workflows/pages/015-editor-ai-suggestions/content.md",
-    "workflows/publishing/": "site/pages/032-reference/pages/060-workflows/pages/020-publishing/content.md",
-    "workflows/embedded-publishing/": "site/pages/032-reference/pages/060-workflows/pages/030-embedded-publishing/content.md",
-    "workflows/upgrading/": "site/pages/032-reference/pages/060-workflows/pages/040-upgrading/content.md",
-    "workflows/legacy-source/": "site/pages/032-reference/pages/060-workflows/pages/050-legacy-source/content.md"
+    "": "site/root/pages/reference/content.md",
+    "site/": "site/root/pages/reference/pages/site/content.md",
+    "site/files/": "site/root/pages/reference/pages/site/pages/files/content.md",
+    "site/pages/": "site/root/pages/reference/pages/site/pages/pages/content.md",
+    "site/urls/": "site/root/pages/reference/pages/site/pages/urls/content.md",
+    "site/metadata/": "site/root/pages/reference/pages/site/pages/metadata/content.md",
+    "site/images/": "site/root/pages/reference/pages/site/pages/images/content.md",
+    "site/attachments/": "site/root/pages/reference/pages/site/pages/attachments/content.md",
+    "site/public-files/": "site/root/pages/reference/pages/site/pages/public-files/content.md",
+    "site/requirements/": "site/root/pages/reference/pages/site/pages/requirements/content.md",
+    "configuration/": "site/root/pages/reference/pages/configuration/content.md",
+    "configuration/site/": "site/root/pages/reference/pages/configuration/pages/site/content.md",
+    "configuration/language/": "site/root/pages/reference/pages/configuration/pages/language/content.md",
+    "configuration/navigation/": "site/root/pages/reference/pages/configuration/pages/navigation/content.md",
+    "configuration/search/": "site/root/pages/reference/pages/configuration/pages/search/content.md",
+    "configuration/source-links/": "site/root/pages/reference/pages/configuration/pages/source-links/content.md",
+    "configuration/theme/": "site/root/pages/reference/pages/configuration/pages/theme/content.md",
+    "configuration/presets/": "site/root/pages/reference/pages/configuration/pages/presets/content.md",
+    "configuration/palettes/": "site/root/pages/reference/pages/configuration/pages/palettes/content.md",
+    "configuration/appearance/": "site/root/pages/reference/pages/configuration/pages/appearance/content.md",
+    "configuration/layout/": "site/root/pages/reference/pages/configuration/pages/layout/content.md",
+    "configuration/images/": "site/root/pages/reference/pages/configuration/pages/images/content.md",
+    "configuration/typography/": "site/root/pages/reference/pages/configuration/pages/typography/content.md",
+    "configuration/sections/": "site/root/pages/reference/pages/configuration/pages/sections/content.md",
+    "configuration/shared-content/": "site/root/pages/reference/pages/configuration/pages/shared-content/content.md",
+    "content/": "site/root/pages/reference/pages/content/content.md",
+    "content/markdown/": "site/root/pages/reference/pages/content/pages/markdown/content.md",
+    "content/structured-blocks/": "site/root/pages/reference/pages/content/pages/structured-blocks/content.md",
+    "content/images/": "site/root/pages/reference/pages/content/pages/images/content.md",
+    "content/cards/": "site/root/pages/reference/pages/content/pages/cards/content.md",
+    "content/child-lists/": "site/root/pages/reference/pages/content/pages/child-lists/content.md",
+    "content/callouts/": "site/root/pages/reference/pages/content/pages/callouts/content.md",
+    "content/tabs/": "site/root/pages/reference/pages/content/pages/tabs/content.md",
+    "content/details/": "site/root/pages/reference/pages/content/pages/details/content.md",
+    "content/tables/": "site/root/pages/reference/pages/content/pages/tables/content.md",
+    "content/code/": "site/root/pages/reference/pages/content/pages/code/content.md",
+    "content/sidenotes/": "site/root/pages/reference/pages/content/pages/sidenotes/content.md",
+    "content/footnotes/": "site/root/pages/reference/pages/content/pages/footnotes/content.md",
+    "commands/": "site/root/pages/reference/pages/commands/content.md",
+    "commands/invocation/": "site/root/pages/reference/pages/commands/pages/invocation/content.md",
+    "commands/init/": "site/root/pages/reference/pages/commands/pages/init/content.md",
+    "commands/create/": "site/root/pages/reference/pages/commands/pages/create/content.md",
+    "commands/move/": "site/root/pages/reference/pages/commands/pages/move/content.md",
+    "commands/validate/": "site/root/pages/reference/pages/commands/pages/validate/content.md",
+    "commands/navigation/": "site/root/pages/reference/pages/commands/pages/navigation/content.md",
+    "commands/development/": "site/root/pages/reference/pages/commands/pages/development/content.md",
+    "commands/build/": "site/root/pages/reference/pages/commands/pages/build/content.md",
+    "commands/publishing/": "site/root/pages/reference/pages/commands/pages/publishing/content.md",
+    "commands/theme/": "site/root/pages/reference/pages/commands/pages/theme/content.md",
+    "commands/engine/": "site/root/pages/reference/pages/commands/pages/engine/content.md",
+    "commands/migration-audit/": "site/root/pages/reference/pages/commands/pages/migration-audit/content.md",
+    "reader/": "site/root/pages/reference/pages/reader/content.md",
+    "reader/display/": "site/root/pages/reference/pages/reader/pages/display/content.md",
+    "reader/accessibility/": "site/root/pages/reference/pages/reader/pages/accessibility/content.md",
+    "workflows/": "site/root/pages/reference/pages/workflows/content.md",
+    "workflows/editor/": "site/root/pages/reference/pages/workflows/pages/editor/content.md",
+    "workflows/editor-ai-suggestions/": "site/root/pages/reference/pages/workflows/pages/editor-ai-suggestions/content.md",
+    "workflows/publishing/": "site/root/pages/reference/pages/workflows/pages/publishing/content.md",
+    "workflows/embedded-publishing/": "site/root/pages/reference/pages/workflows/pages/embedded-publishing/content.md",
+    "workflows/upgrading/": "site/root/pages/reference/pages/workflows/pages/upgrading/content.md",
+    "workflows/legacy-source/": "site/root/pages/reference/pages/workflows/pages/legacy-source/content.md"
   },
   "legacy": {
     "site-files.md": "site/files/",
@@ -78,13 +86,13 @@
     "site-files.md#selecting-the-site-directory": "commands/invocation/#site-selection",
     "site-files.md#versioned-files": "site/files/#generated-files",
     "site-files.md#generated-files": "site/files/#generated-files",
-    "pages.md#homepage-and-top-level-entries": "site/pages/#page-or-category",
-    "pages.md#choose-a-section-page-or-category": "site/pages/#page-or-category",
+    "pages.md#homepage-and-top-level-entries": "site/pages/#choose-pages-and-sections",
+    "pages.md#choose-a-section-page-or-category": "site/pages/#choose-pages-and-sections",
     "pages.md#review-an-existing-hierarchy": "commands/navigation/",
-    "pages.md#navigation-categories": "site/pages/#page-or-category",
-    "pages.md#opening-a-category-url": "site/pages/#opening-a-category-url",
-    "pages.md#reachable-content-and-stable-links": "site/pages/#opening-a-category-url",
-    "pages.md#nested-pages": "site/pages/#page-or-category",
+    "pages.md#navigation-categories": "site/pages/#choose-pages-and-sections",
+    "pages.md#opening-a-category-url": "site/pages/#list-child-pages",
+    "pages.md#reachable-content-and-stable-links": "site/pages/#list-child-pages",
+    "pages.md#nested-pages": "site/pages/#choose-pages-and-sections",
     "pages.md#directory-names-order-and-urls": "site/pages/#names-and-order",
     "pages.md#preserve-old-page-urls": "site/urls/#keep-an-old-url",
     "pages.md#move-or-reconcile-a-page": "commands/move/",
@@ -148,10 +156,10 @@
     "public-files.md#navigation-logo": "site/public-files/#recognized-files",
     "public-files.md#browser-icons": "site/public-files/#recognized-files",
     "public-files.md#social-sharing-image": "site/public-files/#social-previews",
-    "public-files.md#github-pages-custom-domain": "site/public-files/#downloads-and-hosting-files",
+    "public-files.md#github-pages-custom-domain": "site/public-files/#allowed-files",
     "public-files.md#generated-sitemap": "site/public-files/#generated-sitemap",
     "public-files.md#generated-404-page": "site/public-files/#generated-404-page",
-    "public-files.md#other-static-files": "site/public-files/#downloads-and-hosting-files",
+    "public-files.md#other-static-files": "site/public-files/#allowed-files",
     "public-files.md#generated-copy": "site/public-files/#preparation-and-reserved-paths",
     "theme.md#theme-presets": "configuration/presets/",
     "theme.md#choose-a-preset": "configuration/theme/#presets-and-root-overrides",
@@ -169,7 +177,7 @@
     "theme.md#palette": "configuration/palettes/",
     "theme.md#appearance": "configuration/appearance/",
     "theme.md#reader-display-controls": "reader/display/",
-    "theme.md#corners": "configuration/theme/#site-wide-settings",
+    "theme.md#corners": "configuration/theme/#visual-settings",
     "theme.md#section-backgrounds": "configuration/sections/",
     "theme.md#page-themes": "configuration/theme/#page-themes",
     "typography.md#typography-profiles": "configuration/typography/#font-profile-and-rhythm",

package/scripts/lib/docusaurus-migration-audit.mjs

@@ -1,3 +1,4 @@
+import { getSiteSourcePaths } from './site-conventions.mjs';
 import { execFile } from 'node:child_process';
 import { createHash } from 'node:crypto';
 import { access, mkdir, readdir, readFile, writeFile } from 'node:fs/promises';
@@ -312,11 +313,11 @@ const inspectPage = async ({ absolutePath, relativePath, root }) => {
 		if (node.type === 'code') codeRanges.push(nodeRange(node));
 		if (node.type === 'image') {
 			collector.add({
-				action: 'Move the asset beside the Norna page and convert the reference to image-stack or image-carousel syntax.',
+				action: "Place the local asset in the Norna page's images/ folder and update its Markdown path if needed; review external images separately.",
 				classification: 'rewrite',
 				code: 'managed-image-rewrite',
 				line: nodeRange(node).line,
-				message: 'A Markdown image needs conversion to a Norna-managed image block.',
+				message: 'Review the image location and supported format; ordinary Markdown images can use Norna-managed files.',
 			});
 		}
 		if (node.type === 'html') inspectHtmlNode(node, collector);
@@ -559,12 +560,12 @@ const renderReportHome = (report) => {
 		+ (problemRows || '| None | No findings | 0 | copy |') + '\n';
 };
 
-const renderProblemPage = (report, problem) => {
+const renderProblemPage = (report, problem, order) => {
 	const rows = problem.sample.map((occurrence) => {
 		const link = sourceLink(report, occurrence);
 		return '| ' + occurrence.pageTitle.replaceAll('|', '\\|') + ' | ' + codeMark + occurrence.sourceFile + codeMark + ' | ' + occurrence.line + ' | ' + (link ? '[Open source](' + link + ')' : 'Unavailable') + ' |';
 	}).join('\n');
-	return '---\npage:\n  description: ' + problemDescription(problem) + '.\n---\n\n'
+	return '---\nnavigation:\n  order: ' + order + '\npage:\n  description: ' + problemDescription(problem) + '.\n---\n\n'
 		+ '# ' + problem.id + '\n\n'
 		+ problem.message + '\n\n'
 		+ 'Classification: **' + problem.classification + '**. Occurrences: **' + problem.occurrences + '**.\n\n'
@@ -584,18 +585,20 @@ export const writeMigrationReport = async (report, reportDir, { sourceRoot = nul
 		const entries = await readdir(resolvedReportDir);
 		if (entries.length > 0) throw new Error('Migration report directory must be empty: ' + resolvedReportDir);
 	} else await mkdir(resolvedReportDir, { recursive: true });
-	await mkdir(path.join(resolvedReportDir, 'pages', '000-home'), { recursive: true });
-	await writeFile(path.join(resolvedReportDir, 'config.yaml'), 'url: https://example.invalid/\n');
-	await writeFile(path.join(resolvedReportDir, 'theme.yaml'), 'preset: documentation\n');
-	await writeFile(path.join(resolvedReportDir, 'pages', '000-home', 'content.md'), renderReportHome(report));
+	const source = getSiteSourcePaths(resolvedReportDir);
+	await mkdir(source.pages, { recursive: true });
+	await mkdir(path.join(resolvedReportDir, 'site-config'), { recursive: true });
+	await writeFile(path.join(resolvedReportDir, 'site-config/settings.yaml'), 'sourceFormat: 2\nurl: https://example.invalid/\n');
+	await writeFile(path.join(resolvedReportDir, 'root', 'tree-theme.yaml'), 'preset: documentation\n');
+	await writeFile(source.content, renderReportHome(report));
 	if (report.problemTypes.length > 0) {
-		const categoryDir = path.join(resolvedReportDir, 'pages', '010-problems');
+		const categoryDir = path.join(source.pages, 'problems');
 		await mkdir(path.join(categoryDir, 'pages'), { recursive: true });
-		await writeFile(path.join(categoryDir, 'category.yaml'), 'label: Problems\n');
+		await writeFile(path.join(categoryDir, 'content.md'), '---\nnavigation:\n  order: 1000\npage:\n  listChildren: true\n---\n\n# Problems\n');
 		for (const [index, problem] of report.problemTypes.entries()) {
-			const pageDir = path.join(categoryDir, 'pages', String((index + 1) * 10).padStart(3, '0') + '-' + problemPageId(problem));
+			const pageDir = path.join(categoryDir, 'pages', problemPageId(problem));
 			await mkdir(pageDir, { recursive: true });
-			await writeFile(path.join(pageDir, 'content.md'), renderProblemPage(report, problem));
+			await writeFile(path.join(pageDir, 'content.md'), renderProblemPage(report, problem, (index + 1) * 1000));
 		}
 	}
 	await writeFile(path.join(resolvedReportDir, 'migration-report.json'), JSON.stringify(report, null, 2) + '\n');

package/scripts/lib/editor-attachments.mjs

@@ -0,0 +1,69 @@
+import { lstat, readdir } from 'node:fs/promises';
+import path from 'node:path';
+import { markdownToMdast } from 'satteri';
+import { checkedPath, snapshot } from './editor-site-files.mjs';
+import { readEditorLinkState } from './editor-site-links.mjs';
+import { attachmentPathname, attachmentOutputIssues, validateAttachmentName, encodeAttachmentPath } from './page-attachments.mjs';
+
+export const siteAttachmentsApiVersion = 1;
+const info = filename => lstat(filename).catch(error => { if (error.code === 'ENOENT') return null; throw error; });
+export const planEditorAttachmentCopy = async ({ siteRoot, sourcePath, filePath, filename, replace = false, pending = [], sources = new Map() }) => {
+	validateAttachmentName(filename);
+	await checkedPath(siteRoot, sourcePath);
+	const state = await readEditorLinkState({ siteRoot, sources });
+	if (state.incomplete.length) throw new Error(`Repair the site before importing attachments. ${state.incomplete.join('\n')}`);
+	const page = state.graph.pages.find(page => page.contentFile.contentPath === sourcePath);
+	if (!page) throw new Error('Choose a content page for these attachments.');
+	const source = path.resolve(filePath), sourceInfo = await info(source);
+	if (!sourceInfo?.isFile() || sourceInfo.isSymbolicLink()) throw new Error('Choose a regular file to import.');
+	const directory = path.join(path.dirname(sourcePath), 'downloads');
+	const destination = await checkedPath(siteRoot, path.join(directory, filename));
+	if (source === destination) throw new Error('This attachment is already on the page. Use Insert Link in Page.');
+	const key = value => value.normalize('NFC').toLowerCase();
+	const entries = await readdir(directory).catch(error => { if (error.code === 'ENOENT') return []; throw error; });
+	const occupied = entries.find(name => key(name) === key(filename));
+	const existing = await info(destination);
+	if (replace ? !existing?.isFile() || existing.isSymbolicLink() : Boolean(occupied)) throw new Error(replace ? 'The file to replace no longer exists.' : `“${occupied}” already exists. Choose Replace, another filename or Ignore.`);
+	if (occupied && occupied !== filename) throw new Error(`Use the exact existing filename “${occupied}” to replace it, or choose a different name.`);
+	if (pending.some(name => key(name) === key(filename))) throw new Error('Two selected files use this name. Rename or ignore one.');
+	const pendingPaths = new Set(pending.map(name => path.join(directory, name)));
+	const files = state.graph.attachments.files.filter(file => file.filePath !== destination && !pendingPaths.has(file.filePath));
+	for (const name of [...pending, filename]) files.push({ filePath: path.join(directory, name), pathname: attachmentPathname(page.pathname, name) });
+	const problems = attachmentOutputIssues({ files, pages: state.graph.pages, publicFiles: state.publicFiles, generatedRoutes: state.generatedRoutes });
+	if (problems.length) throw new Error(problems.map(issue => issue.message).join('\n'));
+	return { source, sourcePath, destination, filename, replace,
+		sourceInfo: { size: sourceInfo.size, modified: sourceInfo.mtimeMs },
+		existingInfo: existing ? { size: existing.size, modified: existing.mtimeMs } : null,
+		fingerprint: JSON.stringify([await snapshot(source), existing ? await snapshot(destination) : null, state.graph.pages.map(page => [page.pathname, page.document.fullSource]), files.map(file => file.pathname).sort()]) };
+};
+
+export const createEditorAttachmentInsertion = ({ source, items, offset = source.length }) => {
+	if (!items.length) return { start: offset, text: '' };
+	if (!Number.isInteger(offset) || offset < 0 || offset > source.length) throw new Error('The insertion position is no longer valid.');
+	const ast = markdownToMdast(source, { features: { gfm: true, frontmatter: true } });
+	const visit = node => {
+		if (node.position && offset >= node.position.start.offset && offset < node.position.end.offset && ['yaml', 'toml', 'code', 'inlineCode', 'html', 'link', 'image', 'definition', 'linkReference', 'imageReference', 'table'].includes(node.type)) throw new Error('Place the cursor in ordinary page text, outside code, links, HTML, tables and page settings, then insert again.');
+		for (const child of node.children ?? []) visit(child);
+	};
+	visit(ast);
+	const newline = source.includes('\r\n') ? '\r\n' : '\n';
+	const links = items.map(item => {
+		validateAttachmentName(item.filename);
+		if (typeof item.text !== 'string' || !item.text.trim() || /[\r\n]/.test(item.text)) throw new Error('Enter link text on one line for each inserted attachment.');
+		const text = item.text.replace(/[\\`*_[\]<>]/g, '\\$&');
+		const href = `downloads/${encodeAttachmentPath(item.filename)}`;
+		return `[${text}](${href})`;
+	});
+	const multiple = links.length > 1;
+	const text = multiple ? links.map(link => '- ' + link).join(newline) : links[0];
+	const insertion = multiple ? newline + newline + text + newline + newline : (offset === source.length ? newline + newline : '') + text + (offset === source.length ? newline : '');
+	const result = markdownToMdast(source.slice(0, offset) + insertion + source.slice(offset), { features: { gfm: true, frontmatter: true } });
+	const inserted = [];
+	const collect = node => {
+		if (node.type === 'link' && node.position.start.offset >= offset && node.position.end.offset <= offset + insertion.length) inserted.push(node);
+		for (const child of node.children ?? []) collect(child);
+	};
+	collect(result);
+	if (inserted.length !== items.length) throw new Error('Place the cursor in ordinary page text outside code, HTML and page settings, then insert again.');
+	return { start: offset, text: insertion };
+};

package/scripts/lib/editor-file-policy.mjs

@@ -0,0 +1,20 @@
+import { getSiteSourcePaths } from './site-conventions.mjs';
+import path from 'node:path';
+import { getSourcePageLocation } from './source-files.mjs';
+import { getSourceFileDefinition } from './source-files.mjs';
+import { isInside } from './editor-site-links.mjs';
+
+export const editorFileRemovalPolicy = ({ siteRoot, sourcePath, filePath }) => {
+	const directory = path.dirname(sourcePath);
+	const siteOwner = sourcePath === siteRoot || directory === getSiteSourcePaths(siteRoot).root;
+	const definition = getSourceFileDefinition(siteRoot, filePath);
+	if (definition && !definition.required && definition.removalEffect
+		&& (path.dirname(filePath) === directory || definition.location === 'site-config' && siteOwner)) {
+		return { kind: definition.schemaKind === 'sitewideContent' ? 'shared-content' : 'theme', effect: definition.removalEffect };
+	}
+	if (siteOwner && isInside(path.join(siteRoot, 'public'), filePath)) return {
+		kind: 'public', effect: 'This file will no longer be published. Links to it may break; an icon or logo may disappear. References outside page content are not checked.',
+	};
+	if (getSourcePageLocation(siteRoot, directory) && path.dirname(filePath) === path.join(directory, 'downloads')) return { kind: 'attachment', effect: 'Links to this attachment will stop working. Restore its file from Trash if needed.' };
+	return null;
+};

package/scripts/lib/editor-language-service.mjs

@@ -1,3 +1,4 @@
+import { extractMarkdownImageReferences } from './markdown-images.mjs';
 import { access, readdir, readFile } from 'node:fs/promises';
 import path from 'node:path';
 import { isDeepStrictEqual } from 'node:util';
@@ -17,11 +18,14 @@ import {
 	socialImageAssetFilenames,
 } from './public-asset-conventions.mjs';
 import { parsePageMarkdownSource } from './page-markdown.mjs';
+import { selectPageTheme } from './theme-packages.mjs';
+import { getSourcePageLocation } from './source-files.mjs';
+import { assertSectionBackgroundPatternCompatibility } from './presentation.mjs';
 import { siteSchema } from './schema-definitions.mjs';
-import { homePageDirectory } from './site-conventions.mjs';
+import { getSiteSourcePaths, homePageDirectory } from './site-conventions.mjs';
 
 const supportedImageExtensions = new Set(['.jpg', '.jpeg', '.png', '.svg']);
-const siteConfigNames = ['config.yaml'];
+const siteConfigNames = ['site-config/settings.yaml'];
 const fileExists = (filePath) => access(filePath).then(() => true, () => false);
 const toPosixPath = (filePath) => filePath.split(path.sep).join('/');
 
@@ -79,45 +83,35 @@ const getNavigationNodesForEditor = async (siteRoot) => {
 		for (const entry of entries) {
 			const nodeDirectory = path.join(pagesDirectory, entry.name);
 			const contentPath = path.join(nodeDirectory, 'content.md');
-			const categoryPath = path.join(nodeDirectory, 'category.yaml');
-			const [hasContent, hasCategory] = await Promise.all([
-				fileExists(contentPath),
-				fileExists(categoryPath),
-			]);
-
-			if (hasContent !== hasCategory) {
-				if (hasCategory) {
-					nodes.push({
-						depth,
-						headings: [],
-						isHome: false,
-						kind: 'category',
-						listed: true,
-					});
-				} else {
-					const source = await readFile(contentPath, 'utf8');
-					const data = readContentFrontmatterForEditor(source);
-					const document = await parsePageMarkdownSource(source, { label: contentPath });
-					nodes.push({
-						depth,
-						headings: document.navigationHeadings,
-						isHome: depth === 1 && entry.name === homePageDirectory,
-						kind: 'page',
-						listed: data.navigation?.listed !== false,
-					});
-				}
+			if (await fileExists(contentPath)) {
+				const source = await readFile(contentPath, 'utf8');
+				const data = readContentFrontmatterForEditor(source);
+				const document = await parsePageMarkdownSource(source, { label: contentPath });
+				nodes.push({
+					depth,
+					headings: document.navigationHeadings,
+					isHome: false,
+					kind: 'page',
+					listed: data.navigation?.listed !== false,
+				});
 			}
 
 			await visit(path.join(nodeDirectory, 'pages'), depth + 1);
 		}
 	};
 
-	await visit(path.join(siteRoot, 'pages'));
+	const homeContent = getSiteSourcePaths(siteRoot).content;
+	if (await fileExists(homeContent)) {
+		const source = await readFile(homeContent, 'utf8');
+		const document = await parsePageMarkdownSource(source, { label: homeContent });
+		nodes.unshift({ depth: 0, headings: document.navigationHeadings, isHome: true, kind: 'page', listed: true });
+	}
+	await visit(getSiteSourcePaths(siteRoot).pages);
 	return nodes;
 };
 
 const getNavigationModeForEditor = async (siteRoot) => {
-	const config = await readEditorYaml(path.join(siteRoot, 'config.yaml'));
+	const config = await readEditorYaml(path.join(siteRoot, 'site-config', 'settings.yaml'));
 	if (!config) return null;
 	const requestedMode = config.navigation?.mode ?? 'automatic';
 	if (requestedMode !== 'automatic') return requestedMode;
@@ -148,30 +142,33 @@ const findNestedYamlPropertyLine = (source, parentKey, propertyKey) => {
 	return 1;
 };
 
-export const getThemeDiagnostics = async ({ documentPath, source }) => {
-	let theme;
+export const getThemeDiagnostics = async ({ siteRoot, documentPath, source, sources = new Map() }) => {
+	// Parse errors are reported by the YAML provider/schema validator.
+	try { const value = load(source); if (value && (typeof value !== 'object' || Array.isArray(value))) return []; }
+	catch { return []; }
+	siteRoot ??= await findNornaSiteRoot(documentPath);
+	if (!siteRoot) return [];
+	const location = getSourcePageLocation(siteRoot, path.dirname(documentPath));
+	if (!location) return [];
 	try {
-		theme = load(source) ?? {};
-	} catch {
+		const overlays = new Map(sources); overlays.set(documentPath, source);
+		const { treeTheme, selected } = await selectPageTheme({
+			siteRoot, pageDirectory: location.pageDirectory, sources: overlays,
+			includePageTheme: path.basename(documentPath) === 'page-theme.yaml',
+		});
+		const theme = path.basename(documentPath) === 'tree-theme.yaml' ? treeTheme : selected;
+		assertSectionBackgroundPatternCompatibility(theme.config, documentPath, await getNavigationModeForEditor(siteRoot));
 		return [];
+	} catch (error) {
+		const surface = error.message.includes('backgroundPattern');
+		return [{ code: surface ? 'tree-section-background-pattern' : 'invalid-resolved-theme',
+			line: surface ? findNestedYamlPropertyLine(source, 'sections', 'backgroundPattern') : 1,
+			message: error.message, severity: 'error' }];
 	}
-	if (!theme || typeof theme !== 'object' || Array.isArray(theme)) return [];
-
-	const backgroundPattern = theme.sections?.backgroundPattern;
-	if (backgroundPattern === undefined || backgroundPattern === 'uniform') return [];
-	const siteRoot = await findNornaSiteRoot(documentPath);
-	if (!siteRoot || await getNavigationModeForEditor(siteRoot) !== 'tree') return [];
-
-	return [{
-		code: 'tree-section-background-pattern',
-		line: findNestedYamlPropertyLine(source, 'sections', 'backgroundPattern'),
-		message: `sections.backgroundPattern "${backgroundPattern}" cannot be used because this site resolves to tree navigation. Tree navigation uses one uniform reading surface so the navigation rail and page content remain distinct. Remove sections.backgroundPattern or set it to uniform.`,
-		severity: 'error',
-	}];
 };
 
 const readSitewideLogoForEditor = async (siteRoot) => {
-	const filename = await findFile(siteRoot, ['sitewide-content.yaml']);
+	const filename = await findFile(siteRoot, ['site-config/shared-content.yaml']);
 	if (!filename) return null;
 	const absolutePath = path.join(siteRoot, filename);
 	const source = await readFile(absolutePath, 'utf8');
@@ -262,13 +259,14 @@ export const getSitePublicAssetStatus = async (documentPath) => {
 const getPageContext = (siteRoot, documentPath) => {
 	const absoluteDocumentPath = path.resolve(documentPath);
 	const relativePath = toPosixPath(path.relative(siteRoot, absoluteDocumentPath));
-	const match = relativePath.match(/^pages\/(.+)\/content\.md$/);
+	if (relativePath === 'root/content.md') return { contentPath: absoluteDocumentPath, imagesRoot: getSiteSourcePaths(siteRoot).images, pageLabel: 'Home', pageDirectory: homePageDirectory };
+	const match = relativePath.match(/^root\/pages\/(.+)\/content\.md$/);
 	if (!match) return null;
 
 	const pageDirectory = match[1];
 	return {
 		contentPath: absoluteDocumentPath,
-		imagesRoot: path.join(siteRoot, 'pages', ...pageDirectory.split('/'), 'images'),
+		imagesRoot: path.join(getSiteSourcePaths(siteRoot).pages, ...pageDirectory.split('/'), 'images'),
 		pageLabel: pageDirectory,
 		pageDirectory,
 	};
@@ -492,7 +490,7 @@ const collectPageImageRoots = async (directory, siteRoot, roots) => {
 		if (!entry.isDirectory()) continue;
 		const absolutePath = path.join(directory, entry.name);
 		if (entry.name === 'images') {
-			const pageDirectory = toPosixPath(path.relative(path.join(siteRoot, 'pages'), path.dirname(absolutePath)));
+			const pageDirectory = toPosixPath(path.relative(getSiteSourcePaths(siteRoot).pages, path.dirname(absolutePath)));
 			roots.push({ imageRoot: absolutePath, pageLabel: pageDirectory });
 			continue;
 		}
@@ -515,7 +513,8 @@ const getContentFiles = async (siteRoot) => {
 		}
 	};
 
-	await visit(path.join(siteRoot, 'pages'));
+	if (await fileExists(getSiteSourcePaths(siteRoot).content)) files.push(getSiteSourcePaths(siteRoot).content);
+	await visit(getSiteSourcePaths(siteRoot).pages);
 	return files;
 };
 
@@ -534,8 +533,8 @@ const getReferencesByFilename = async (siteRoot) => {
 
 export const createSiteImageIndex = async (siteRoot) => {
 	const files = [];
-	const pageRoots = [];
-	await collectPageImageRoots(path.join(siteRoot, 'pages'), siteRoot, pageRoots);
+	const pageRoots = [{ imageRoot: getSiteSourcePaths(siteRoot).images, pageLabel: 'Home' }];
+	await collectPageImageRoots(getSiteSourcePaths(siteRoot).pages, siteRoot, pageRoots);
 	for (const root of pageRoots) {
 		await collectImageFiles(root.imageRoot, root.imageRoot, root.pageLabel, files);
 	}
@@ -566,7 +565,9 @@ const getEditorImageReferences = (source) => {
 		}
 		for (const child of node.children ?? []) visit(child);
 	};
-	visit(markdownToMdast(source, { features: { gfm: true, frontmatter: true } }));
+	const tree = markdownToMdast(source, { features: { gfm: true, frontmatter: true } });
+	visit(tree);
+	for (const reference of extractMarkdownImageReferences({ source, tree })) if (reference.image) names.add(reference.image);
 	return names;
 };
 
@@ -618,10 +619,17 @@ export const getImageCompletionContext = async ({ documentPath, source, line })
 	};
 };
 
-export const getImageDefinitionContext = async ({ documentPath, source, line }) => {
+export const getImageDefinitionContext = async ({ documentPath, source, line, character = 0 }) => {
 	const context = getNornaBlockFieldContext({ source, line });
-	if (context?.key !== 'image' || typeof context.value !== 'string') return null;
-	const filename = context.value;
+	let filename = context?.key === 'image' && typeof context.value === 'string' ? context.value : null;
+	const markdown = !filename;
+	if (markdown) {
+		const document = await parsePageMarkdownSource(source);
+		const offset = source.split('\n').slice(0, line).reduce((count, text) => count + text.length + 1, 0) + character;
+		const reference = document.markdownImages.find((ref) => [ref.range, ref.targetRange].some(range => range && offset >= range.start && offset < range.end));
+		filename = reference?.image;
+	}
+	if (!filename) return null;
 	if (!/^[a-z0-9][a-z0-9.-]*\.(jpe?g|png|svg)$/i.test(filename)) return null;
 	const siteRoot = await findNornaSiteRoot(documentPath);
 	const page = siteRoot ? getPageContext(siteRoot, documentPath) : null;
@@ -629,6 +637,7 @@ export const getImageDefinitionContext = async ({ documentPath, source, line })
 
 	const expectedPath = path.join(page.imagesRoot, filename);
 	if (await fileExists(expectedPath)) return { files: [expectedPath], filename, siteRoot };
+	if (markdown) return { files: [], filename, siteRoot };
 
 	const index = await createSiteImageIndex(siteRoot);
 	return {
@@ -680,14 +689,6 @@ export const getMarkdownDiagnostics = async ({ documentPath, source }) => {
 				: diagnostic.message,
 		})),
 	];
-	for (const reference of document.markdownImages) {
-		diagnostics.push({
-			code: 'local-markdown-image',
-			severity: 'warning',
-			line: reference.line,
-			message: `Local Markdown image "${reference.target}" is not managed by Norna. Use image-stack, image-carousel, or card-list for validated and synchronized site images.`,
-		});
-	}
 
 	const siteRoot = await findNornaSiteRoot(documentPath);
 	const pageContext = siteRoot ? getPageContext(siteRoot, documentPath) : null;
@@ -705,16 +706,16 @@ export const getMarkdownDiagnostics = async ({ documentPath, source }) => {
 				code: 'missing-image',
 				severity: 'error',
 				line: reference.line,
-				message: `Image "${filename}" was not found in this page's images folder or elsewhere in this Norna site.`,
+				message: `Image "${filename}" was not found at ${toPosixPath(expectedPath)}.`,
 			});
 			continue;
 		}
 		if (candidates.length > 1) {
 			diagnostics.push({
 				code: 'ambiguous-image',
-				severity: 'warning',
+				severity: 'error',
 				line: reference.line,
-				message: `Image "${filename}" is ambiguous. Found: ${candidates.map((candidate) => toPosixPath(path.relative(siteRoot, candidate.absolutePath))).join(', ')}.`,
+				message: `Image "${filename}" is missing at ${toPosixPath(expectedPath)}. Repair candidates: ${candidates.map((candidate) => toPosixPath(path.relative(siteRoot, candidate.absolutePath))).join(', ')}.`,
 			});
 			continue;
 		}
@@ -729,11 +730,11 @@ export const getMarkdownDiagnostics = async ({ documentPath, source }) => {
 				imagePath: candidate.absolutePath,
 				siteRoot,
 			},
-			severity: 'warning',
+			severity: 'error',
 			line: reference.line,
-			message: otherReferences.length > 0
+			message: `Image "${filename}" is missing at ${toPosixPath(expectedPath)}. ` + (otherReferences.length > 0
 				? `Image "${filename}" is stored at ${toPosixPath(path.relative(siteRoot, candidate.absolutePath))} and is still referenced by ${otherReferences.join(', ')}. Norna cannot relocate it safely.`
-				: `Image "${filename}" is stored at ${toPosixPath(path.relative(siteRoot, candidate.absolutePath))}. Run "norna content:sync" to relocate it to this page's images folder.`,
+				: `Image "${filename}" is stored at ${toPosixPath(path.relative(siteRoot, candidate.absolutePath))}. Run "norna content:sync" to relocate it to this page's images folder.`),
 		});
 	}