@iyulab/canopy-page 0.1.0

package/dist/references.js

@@ -0,0 +1,181 @@
+/**
+ * Finding the references a document makes: links, images, wikilinks.
+ *
+ * A checker needs to know what a page points at before anything is built, which
+ * means reading markdown without rendering it. This is deliberately a smaller
+ * job than parsing: it looks for the shapes that address a file and ignores
+ * everything else about the document.
+ *
+ * Code is skipped — fenced blocks and inline spans — because a fenced example
+ * of a broken link is documentation, not a broken link. That is the one place a
+ * naive scan gets it loudly wrong, and it is the case documentation sites hit
+ * most, since they are full of examples.
+ *
+ * What this does *not* do is decide which page a reference resolves to when
+ * several could match. That question belongs to the renderer, and answering it
+ * differently here would produce a checker that disagrees with the build. The
+ * checker only ever asks whether anything is there.
+ */
+const FENCE = /^\s{0,3}(`{3,}|~{3,})/;
+const INLINE_CODE = /`[^`]*`/g;
+// `![alt](url)` and `[text](url)`, with the URL taken up to whitespace or `)`.
+// Angle-bracketed URLs (`[x](<a b.md>)`) are the escape hatch for spaces.
+const INLINE_LINK = /(!?)\[[^\]]*\]\(\s*(<[^>]*>|[^\s)]*)/g;
+// `[id]: url "optional title"` — where a reference-style link's target lives.
+const LINK_DEFINITION = /^\s{0,3}\[[^\]]+\]:\s*(<[^>]*>|\S+)/;
+const WIKILINK = /\[\[([^\]|#]+)(?:#[^\]|]*)?(?:\|[^\]]*)?\]\]/g;
+const HTML_IMG = /<img\b[^>]*\bsrc\s*=\s*["']([^"']*)["']/gi;
+function unwrap(url) {
+    return url.startsWith("<") && url.endsWith(">") ? url.slice(1, -1) : url;
+}
+/**
+ * Did this destination stop at a space that was meant to be part of it?
+ *
+ * An unbracketed destination ends at the first space, so `(../a b/c.md)` links
+ * `../a` and leaves ` b/c.md` as text. What follows a real destination is
+ * optional whitespace, an optional quoted title, and `)`. Anything else means
+ * the path was cut, which is worth saying — the alternative is a message about
+ * a target the author never wrote.
+ */
+function cutAtSpace(raw, after) {
+    if (raw.startsWith("<"))
+        return false;
+    const remainder = after.slice(0, after.indexOf(")") === -1 ? undefined : after.indexOf(")"));
+    const title = remainder.trim();
+    return title !== "" && !/^["'(]/.test(title);
+}
+/**
+ * Extract every reference in a markdown document, in document order.
+ *
+ * Frontmatter is left alone: it is metadata for the renderer, and a path in it
+ * means whatever the consuming site decides it means.
+ */
+export function extractReferences(markdown) {
+    const references = [];
+    const lines = markdown.split(/\r?\n/);
+    let fence;
+    let inFrontmatter = lines[0]?.trim() === "---";
+    lines.forEach((rawLine, i) => {
+        const line = i + 1;
+        if (inFrontmatter) {
+            if (i > 0 && rawLine.trim() === "---")
+                inFrontmatter = false;
+            return;
+        }
+        const fenceMatch = FENCE.exec(rawLine);
+        if (fence !== undefined) {
+            // A fence closes on a marker of the same kind and at least the same length,
+            // so a longer fence can quote a shorter one.
+            if (fenceMatch?.[1]?.startsWith(fence[0]) && fenceMatch[1].length >= fence.length) {
+                fence = undefined;
+            }
+            return;
+        }
+        if (fenceMatch?.[1] !== undefined) {
+            fence = fenceMatch[1];
+            return;
+        }
+        const text = rawLine.replace(INLINE_CODE, "");
+        const definition = LINK_DEFINITION.exec(text);
+        if (definition?.[1] !== undefined) {
+            references.push({ target: unwrap(definition[1]), kind: "link", line });
+            return;
+        }
+        for (const match of text.matchAll(INLINE_LINK)) {
+            const raw = match[2] ?? "";
+            const target = unwrap(raw);
+            if (target === "")
+                continue;
+            references.push({
+                target,
+                kind: match[1] === "!" ? "image" : "link",
+                line,
+                ...(cutAtSpace(raw, text.slice(match.index + match[0].length)) ? { cutAtSpace: true } : {}),
+            });
+        }
+        for (const match of text.matchAll(HTML_IMG)) {
+            const target = match[1] ?? "";
+            if (target !== "")
+                references.push({ target, kind: "image", line });
+        }
+        for (const match of text.matchAll(WIKILINK)) {
+            const target = (match[1] ?? "").trim();
+            if (target !== "")
+                references.push({ target, kind: "wikilink", line });
+        }
+    });
+    return references;
+}
+/**
+ * True when a URL addresses something outside the site and must not be checked.
+ *
+ * These are the cases canopy states it leaves exactly as written: a scheme
+ * (`https:`, `mailto:`), a protocol-relative URL, a root-absolute path — a
+ * deployment path whose meaning depends on where the site is mounted — and a
+ * bare fragment, which addresses the page it is on.
+ */
+export function isExternalUrl(url) {
+    return (url === "" || url.startsWith("#") || url.startsWith("/") || /^[a-z][a-z0-9+.-]*:/i.test(url));
+}
+/** Strip a query string or fragment, which address a place *within* a target. */
+export function targetPath(url) {
+    const cut = url.search(/[?#]/);
+    return cut === -1 ? url : url.slice(0, cut);
+}
+/**
+ * Turn a URL path into the site path it addresses, undoing percent-encoding.
+ *
+ * A reference is a URL and the site is files, so the two spellings of one path —
+ * `a%20b/note.md` and `a b/note.md` — have to meet before anything is compared.
+ * Editors write the encoded form on their own for any path containing a space,
+ * and this checker's own advice for a destination that stops at a space is to
+ * "write the space as %20", so without this it rejects what it just recommended.
+ *
+ * Decoded per segment, never across the whole path: `%2F` is a slash inside one
+ * name rather than a directory boundary. A malformed escape comes back
+ * undefined, and the reference is left alone — which is what the renderer does
+ * with it, and the checker's job is to agree with the renderer.
+ *
+ * TODO(upstream: claudedocs/upstream-issues/ISSUE-canopy-20260807-link-target-resolution.md)
+ * — canopy applies this same rule when it rewrites links, and does not expose
+ * it, so the rule is spelled out twice and can drift. It just did: canopy
+ * learned to read this encoding one release before this file did.
+ */
+export function decodeTarget(path) {
+    const segments = [];
+    for (const segment of path.split("/")) {
+        let decoded;
+        try {
+            decoded = decodeURIComponent(segment);
+        }
+        catch {
+            return undefined;
+        }
+        if (decoded.includes("/"))
+            return undefined;
+        segments.push(decoded);
+    }
+    return segments.join("/");
+}
+/**
+ * Resolve a site-relative target against the document holding it.
+ *
+ * `..` is honoured so a page can point at a sibling folder. A target that walks
+ * above the site root addresses something the site was never given, so it comes
+ * back undefined and is left alone rather than reported.
+ */
+export function resolveFrom(documentPath, target) {
+    const segments = documentPath.split("/").slice(0, -1);
+    for (const part of target.replace(/\\/g, "/").split("/")) {
+        if (part === "" || part === ".")
+            continue;
+        if (part === "..") {
+            if (segments.length === 0)
+                return undefined;
+            segments.pop();
+            continue;
+        }
+        segments.push(part);
+    }
+    return segments.join("/");
+}

package/dist/settings.d.ts

@@ -0,0 +1,81 @@
+/**
+ * `settings.json` — the one file a documentation set hands to canopy-page.
+ *
+ * Everything a site needs to build lives here, next to the markdown it
+ * describes, so the build is reproducible from the source tree alone: no build
+ * script holds half the configuration, and the file can be read by a person
+ * deciding what the site is supposed to look like.
+ *
+ * The whole file is optional in the sense that every field is: a directory of
+ * markdown with an empty `{}` builds, with navigation derived from the folder
+ * tree. Settings exist to override what a source tree cannot express by itself —
+ * the display order of a release log, a label that is not a directory name, a
+ * draft folder that must stay unpublished.
+ *
+ * ## One site, not several builds
+ *
+ * A settings file describes a single site, built in one pass from the directory
+ * that holds it. `sections` name ordered regions *within* that site — a guide, a
+ * release log — rather than separate builds of their own.
+ *
+ * The alternative, building each region separately, would break the thing the
+ * site is for: links and backlinks resolve across one build, so splitting a
+ * guide from the release notes it refers to would leave those cross-references
+ * dangling — the fragmentation this tool exists to remove. A favicon or an
+ * excluded path is likewise stated once for the site, which is only meaningful
+ * if there is one. Two genuinely independent sites are two settings files.
+ */
+/** Why a settings file was rejected, phrased for someone editing it. */
+export declare class SettingsError extends Error {
+}
+/** One ordered region of the site: a guide, a release log, a reference section. */
+export interface SettingsSection {
+    /** Directory this section covers, relative to the settings file. */
+    path: string;
+    /** Heading shown for the section. Defaults to the directory name. */
+    label?: string;
+    /**
+     * Order for the pages inside, when they are not listed one by one.
+     * `desc` is what a release log wants: newest first, which no folder tree says.
+     */
+    order?: "asc" | "desc";
+    /** Explicit contents, in display order. Overrides `order`. */
+    items?: SettingsNavItem[];
+}
+/**
+ * One entry in a section's contents: a page, or a group of entries.
+ *
+ * The common case is a bare path, so a string is accepted as shorthand for
+ * `{ path }` and normalized away here — the rest of the code sees one shape.
+ */
+export interface SettingsNavItem {
+    /** Display text. Defaults to the page's title, then its filename. */
+    label?: string;
+    /** Path of the page, relative to the settings file, with or without `.md`. */
+    path?: string;
+    /** Nested entries, in display order. */
+    items?: SettingsNavItem[];
+}
+/** A validated settings file. Absent fields mean "use canopy's default". */
+export interface Settings {
+    /** Site name. Defaults to the directory name. */
+    title?: string;
+    /** Fills `<meta name="description">`, which is what link previews show. */
+    description?: string;
+    /** BCP 47 language tag for `<html lang>`. Worth setting for any non-English site. */
+    lang?: string;
+    /** Favicon, relative to the settings file. Must be a published file. */
+    icon?: string;
+    /** Paths to leave unpublished: a directory, an extension (`*.tmp`), or one exact path. */
+    exclude?: string[];
+    /** Ordered regions of the site. Without them, navigation follows the folder tree. */
+    sections?: SettingsSection[];
+}
+/**
+ * Parse and validate a settings file from JSON text.
+ *
+ * Validation is strict and every message names the position it is about, since
+ * this file is written by hand: a setting that is half-applied looks like a tool
+ * that ignores its configuration.
+ */
+export declare function parseSettings(json: string): Settings;

package/dist/settings.js

@@ -0,0 +1,236 @@
+/**
+ * `settings.json` — the one file a documentation set hands to canopy-page.
+ *
+ * Everything a site needs to build lives here, next to the markdown it
+ * describes, so the build is reproducible from the source tree alone: no build
+ * script holds half the configuration, and the file can be read by a person
+ * deciding what the site is supposed to look like.
+ *
+ * The whole file is optional in the sense that every field is: a directory of
+ * markdown with an empty `{}` builds, with navigation derived from the folder
+ * tree. Settings exist to override what a source tree cannot express by itself —
+ * the display order of a release log, a label that is not a directory name, a
+ * draft folder that must stay unpublished.
+ *
+ * ## One site, not several builds
+ *
+ * A settings file describes a single site, built in one pass from the directory
+ * that holds it. `sections` name ordered regions *within* that site — a guide, a
+ * release log — rather than separate builds of their own.
+ *
+ * The alternative, building each region separately, would break the thing the
+ * site is for: links and backlinks resolve across one build, so splitting a
+ * guide from the release notes it refers to would leave those cross-references
+ * dangling — the fragmentation this tool exists to remove. A favicon or an
+ * excluded path is likewise stated once for the site, which is only meaningful
+ * if there is one. Two genuinely independent sites are two settings files.
+ */
+/** Why a settings file was rejected, phrased for someone editing it. */
+export class SettingsError extends Error {
+}
+function fail(message) {
+    throw new SettingsError(message);
+}
+/**
+ * Keys that are allowed but carry no meaning for the build.
+ *
+ * `$schema` is how an editor knows to offer completion and inline validation,
+ * so it has to survive a strict key check.
+ */
+const IGNORED_KEYS = new Set(["$schema"]);
+const SETTINGS_KEYS = new Set([
+    "title",
+    "description",
+    "lang",
+    "icon",
+    "exclude",
+    "sections",
+]);
+const SECTION_KEYS = new Set(["path", "label", "order", "items"]);
+const NAV_ITEM_KEYS = new Set(["label", "path", "items"]);
+/**
+ * Unknown keys are rejected rather than ignored.
+ *
+ * A settings file is hand-edited, and a typo in a key (`titel`, `execlude`) that
+ * is quietly dropped presents as canopy-page ignoring an instruction it was
+ * given — the hardest kind of problem to see, because the file looks right.
+ */
+function rejectUnknownKeys(value, allowed, where) {
+    for (const key of Object.keys(value)) {
+        if (allowed.has(key) || IGNORED_KEYS.has(key))
+            continue;
+        fail(`${where}: unknown key "${key}"`);
+    }
+}
+function asObject(value, where, expectation) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        fail(`${where}: ${expectation}`);
+    }
+    return value;
+}
+function asString(value, where) {
+    if (typeof value !== "string")
+        fail(`${where}: must be a string`);
+    if (value.trim() === "")
+        fail(`${where}: must not be empty`);
+    return value;
+}
+/**
+ * Normalize a path written in a settings file to the form the rest of the code
+ * uses: forward slashes, no leading slash, no trailing slash.
+ *
+ * Authors on Windows write backslashes, and both `guide` and `guide/` mean the
+ * same directory. Paths that leave the site are refused here rather than at the
+ * point they fail to resolve, where the message would be about a missing file
+ * instead of about the setting that named it.
+ */
+function asRelativePath(value, where) {
+    const raw = asString(value, where);
+    const normalized = raw.replace(/\\/g, "/").replace(/\/+$/, "");
+    if (normalized.startsWith("/")) {
+        fail(`${where}: must be relative to the settings file, not "${raw}"`);
+    }
+    if (/^[A-Za-z]:/.test(normalized)) {
+        fail(`${where}: must be relative to the settings file, not an absolute path`);
+    }
+    if (normalized.split("/").includes("..")) {
+        fail(`${where}: must stay inside the site, so it cannot contain ".."`);
+    }
+    if (normalized === "" || normalized === ".") {
+        fail(`${where}: must name a path inside the site`);
+    }
+    return normalized;
+}
+/**
+ * Check an exclusion pattern against the dialect that is actually implemented.
+ *
+ * Four shapes, and nothing else: `drafts`, `drafts/**`, `*.tmp`, and one exact
+ * path. A wildcard anywhere else — `images/*.md`, `guide/*` — matches nothing,
+ * and a pattern that quietly excludes nothing is the failure strict validation
+ * exists to prevent: the file reads as if it said something, and the folder
+ * ships anyway. Refusing it here is the same answer an unknown key gets.
+ */
+function asExclusionPattern(value, where) {
+    const pattern = asString(value, where);
+    const normalized = pattern.replace(/\\/g, "/").replace(/^\.\//, "");
+    // `*.tmp` is the extension form; `drafts/**` is the whole-tree form. Strip
+    // whichever applies and nothing else may hold a wildcard.
+    const rest = normalized.startsWith("*.")
+        ? normalized.slice(2)
+        : normalized.replace(/\/\*\*$/, "");
+    if (rest.includes("*")) {
+        fail(`${where}: "${pattern}" is not a pattern canopy-page understands. ` +
+            'Use a directory ("drafts"), a whole tree ("drafts/**"), ' +
+            'an extension ("*.tmp"), or one exact path ("notes/scratch.md")');
+    }
+    return pattern;
+}
+function parseNavItem(value, where) {
+    // A bare string is the common case — a page in the order it should appear.
+    if (typeof value === "string") {
+        return { path: asRelativePath(value, where) };
+    }
+    const item = asObject(value, where, 'expected a page path or an object with "label", "path", or "items"');
+    rejectUnknownKeys(item, NAV_ITEM_KEYS, where);
+    const { label, path, items } = item;
+    if (label !== undefined)
+        asString(label, `${where}.label`);
+    if (items !== undefined && !Array.isArray(items))
+        fail(`${where}.items: must be an array`);
+    if (path === undefined && items === undefined) {
+        fail(`${where}: needs a "path" (a page) or "items" (a group)`);
+    }
+    // A group with no label renders as an unnamed heading, which reads as a bug in
+    // the site rather than as the omission in the file that it is.
+    if (path === undefined && label === undefined) {
+        fail(`${where}: a group needs a "label"`);
+    }
+    const children = items?.map((child, i) => parseNavItem(child, `${where}.items[${i}]`));
+    return {
+        ...(label === undefined ? {} : { label: label }),
+        ...(path === undefined ? {} : { path: asRelativePath(path, `${where}.path`) }),
+        ...(children === undefined ? {} : { items: children }),
+    };
+}
+function parseSection(value, where) {
+    const section = asObject(value, where, 'expected an object with a "path"');
+    rejectUnknownKeys(section, SECTION_KEYS, where);
+    const { path, label, order, items } = section;
+    if (path === undefined)
+        fail(`${where}: needs a "path" naming the directory it covers`);
+    if (label !== undefined)
+        asString(label, `${where}.label`);
+    if (order !== undefined && order !== "asc" && order !== "desc") {
+        fail(`${where}.order: must be "asc" or "desc"`);
+    }
+    if (items !== undefined && !Array.isArray(items))
+        fail(`${where}.items: must be an array`);
+    // Listing the contents *is* the order. Accepting both would mean silently
+    // honouring one and dropping the other, and either choice surprises someone.
+    if (items !== undefined && order !== undefined) {
+        fail(`${where}: "items" already gives the order, so "order" cannot be set too`);
+    }
+    return {
+        path: asRelativePath(path, `${where}.path`),
+        ...(label === undefined ? {} : { label: label }),
+        ...(order === undefined ? {} : { order: order }),
+        ...(items === undefined
+            ? {}
+            : { items: items.map((item, i) => parseNavItem(item, `${where}.items[${i}]`)) }),
+    };
+}
+/**
+ * Parse and validate a settings file from JSON text.
+ *
+ * Validation is strict and every message names the position it is about, since
+ * this file is written by hand: a setting that is half-applied looks like a tool
+ * that ignores its configuration.
+ */
+export function parseSettings(json) {
+    let raw;
+    try {
+        raw = JSON.parse(json);
+    }
+    catch (error) {
+        fail(`not valid JSON: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    const value = asObject(raw, "settings", "expected a JSON object");
+    rejectUnknownKeys(value, SETTINGS_KEYS, "settings");
+    const { title, description, lang, icon, exclude, sections } = value;
+    if (title !== undefined)
+        asString(title, "settings.title");
+    if (description !== undefined)
+        asString(description, "settings.description");
+    if (lang !== undefined) {
+        const tag = asString(lang, "settings.lang");
+        // A language tag is subtags of letters and digits joined by hyphens. This
+        // catches the shapes people actually mistype — "ko KR", "ko_KR" — without
+        // pretending to be a registry of valid tags.
+        if (!/^[A-Za-z0-9]+(-[A-Za-z0-9]+)*$/.test(tag)) {
+            fail(`settings.lang: "${tag}" is not a language tag like "en" or "ko-KR"`);
+        }
+    }
+    if (exclude !== undefined && !Array.isArray(exclude))
+        fail("settings.exclude: must be an array");
+    if (sections !== undefined && !Array.isArray(sections))
+        fail("settings.sections: must be an array");
+    return {
+        ...(title === undefined ? {} : { title: title }),
+        ...(description === undefined ? {} : { description: description }),
+        ...(lang === undefined ? {} : { lang: lang }),
+        ...(icon === undefined ? {} : { icon: asRelativePath(icon, "settings.icon") }),
+        ...(exclude === undefined
+            ? {}
+            : {
+                // Exclusions are patterns, not paths: `*.tmp` and `drafts/**` are both
+                // valid to canopy, so they are passed through rather than normalized
+                // into a path shape they do not have.
+                exclude: exclude.map((pattern, i) => asExclusionPattern(pattern, `settings.exclude[${i}]`)),
+            }),
+        ...(sections === undefined
+            ? {}
+            : {
+                sections: sections.map((section, i) => parseSection(section, `settings.sections[${i}]`)),
+            }),
+    };
+}

package/dist/site.d.ts

@@ -0,0 +1,54 @@
+import { type NavTranslation } from "./nav.js";
+import { type Settings } from "./settings.js";
+import { type PageIndex } from "./vault.js";
+/**
+ * Loading a site: settings, the files they describe, and the navigation that
+ * falls out of putting the two together.
+ *
+ * Every command works from this one view, so `build` and a check cannot disagree
+ * about what the site contains — a checker that inspects something other than
+ * what the build ships is worse than no checker, because it reports confidence
+ * it has not earned.
+ */
+/** Why a site could not be loaded, phrased for whoever runs the command. */
+export declare class SiteError extends Error {
+}
+/** A site read from disk, ready to be checked or built. */
+export interface LoadedSite {
+    /** Absolute path of the directory holding the settings file. */
+    root: string;
+    settings: Settings;
+    index: PageIndex;
+    nav: NavTranslation;
+    /** Exclusion patterns that left the site exactly as they found it. */
+    unusedExclusions: string[];
+}
+/** Something worth telling the author about their site. */
+export interface Finding {
+    /** `error` stops a build; `warning` is reported and the build continues. */
+    level: "error" | "warning";
+    message: string;
+}
+/** Read a site directory into settings, files, and a navigation translation. */
+export declare function loadSite(dir: string): Promise<LoadedSite>;
+/**
+ * What the settings themselves got wrong, beyond what they say about navigation.
+ *
+ * An exclusion that excluded nothing is a warning rather than an error: the site
+ * is publishable and every page in it is sound. What is wrong is that the file
+ * claims to hold something back and does not, which the author can only find out
+ * by being told.
+ */
+export declare function settingsFindings(site: LoadedSite): Finding[];
+/**
+ * What the navigation translation found, as findings.
+ *
+ * A reference to a page that does not exist and a page placed twice are both
+ * mistakes *in the settings file*: nothing in the site can make them right, so
+ * they stop a build. A page no section mentions is different — the site is
+ * complete, it is the description that is behind, and the page is placed anyway
+ * — so it is said out loud and the build continues.
+ */
+export declare function navFindings(nav: NavTranslation): Finding[];
+/** Print findings in the order given, and report whether any of them stops a build. */
+export declare function reportFindings(findings: readonly Finding[]): boolean;

package/dist/site.js

@@ -0,0 +1,108 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { translateNav } from "./nav.js";
+import { parseSettings, SettingsError } from "./settings.js";
+import { indexSite, listSite, SETTINGS_FILENAME } from "./vault.js";
+/**
+ * Loading a site: settings, the files they describe, and the navigation that
+ * falls out of putting the two together.
+ *
+ * Every command works from this one view, so `build` and a check cannot disagree
+ * about what the site contains — a checker that inspects something other than
+ * what the build ships is worse than no checker, because it reports confidence
+ * it has not earned.
+ */
+/** Why a site could not be loaded, phrased for whoever runs the command. */
+export class SiteError extends Error {
+}
+/** Read a site directory into settings, files, and a navigation translation. */
+export async function loadSite(dir) {
+    const root = path.resolve(dir);
+    const settingsPath = path.join(root, SETTINGS_FILENAME);
+    let raw;
+    try {
+        raw = await readFile(settingsPath, "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            throw new SiteError(`no ${SETTINGS_FILENAME} in ${root}\n` +
+                "A site is configured by that file; run canopy-page in the folder that holds it.");
+        }
+        throw error;
+    }
+    let settings;
+    try {
+        settings = parseSettings(raw);
+    }
+    catch (error) {
+        if (error instanceof SettingsError) {
+            // Name the file: a message about `sections[0]` is only actionable if the
+            // reader knows which file to open.
+            throw new SiteError(`${settingsPath}: ${error.message}`);
+        }
+        throw error;
+    }
+    const listing = await listSite(root, settings.exclude);
+    const index = indexSite(listing.files);
+    return {
+        root,
+        settings,
+        index,
+        nav: translateNav(settings, index),
+        unusedExclusions: listing.unusedExclusions,
+    };
+}
+/**
+ * What the settings themselves got wrong, beyond what they say about navigation.
+ *
+ * An exclusion that excluded nothing is a warning rather than an error: the site
+ * is publishable and every page in it is sound. What is wrong is that the file
+ * claims to hold something back and does not, which the author can only find out
+ * by being told.
+ */
+export function settingsFindings(site) {
+    return site.unusedExclusions.map((pattern) => ({
+        level: "warning",
+        message: `settings: exclude "${pattern}" matched nothing, so everything it names is published. ` +
+            "Patterns are relative to the settings file",
+    }));
+}
+/**
+ * What the navigation translation found, as findings.
+ *
+ * A reference to a page that does not exist and a page placed twice are both
+ * mistakes *in the settings file*: nothing in the site can make them right, so
+ * they stop a build. A page no section mentions is different — the site is
+ * complete, it is the description that is behind, and the page is placed anyway
+ * — so it is said out loud and the build continues.
+ */
+export function navFindings(nav) {
+    const findings = [];
+    for (const reference of nav.missing) {
+        findings.push({ level: "error", message: `settings: "${reference}" matches no page` });
+    }
+    for (const page of nav.duplicates) {
+        findings.push({ level: "error", message: `settings: "${page}" is placed more than once` });
+    }
+    if (nav.orphans.length > 0) {
+        // One page per line. A real site's uncovered pages run to dozens, and a list
+        // joined onto one line is a wall nobody reads to the end of — which loses
+        // the whole point of naming them.
+        findings.push({
+            level: "warning",
+            message: `${nav.orphans.length} page(s) no section covers, placed at the end of their section:\n` +
+                nav.orphans.map((page) => `  ${page}`).join("\n"),
+        });
+    }
+    return findings;
+}
+/** Print findings in the order given, and report whether any of them stops a build. */
+export function reportFindings(findings) {
+    for (const finding of findings) {
+        if (finding.level === "error")
+            console.error(`error: ${finding.message}`);
+        else
+            console.warn(`warning: ${finding.message}`);
+    }
+    return findings.some((finding) => finding.level === "error");
+}