@iyulab/canopy-page 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,80 @@
+# Changelog
+
+Notable changes to canopy-page. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and versions follow
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+The `settings.json` contract is what consuming projects plan their upgrades around, so changes
+to it — its fields, its validation, and what the checks reject — are what this file is about.
+
+## [0.1.0] — 2026-08-07
+
+First release. Development before it is recorded here in one block rather than reconstructed as
+versions that never shipped.
+
+### Added
+
+- `settings.json`: one file beside the markdown holding everything a site needs to build. Every
+  field is an override, so `{}` is valid and a folder of markdown builds with navigation derived
+  from its folder tree. Fields: `title`, `description`, `lang`, `icon`, `exclude`, `sections`
+- Strict, positional validation. An unknown key is rejected rather than ignored, since a mistyped
+  one that is quietly dropped presents as a tool disobeying its configuration, and every message
+  names the position it is about (`sections[0].items[1]`). Paths are normalized and refused if
+  they leave the site, at the setting that named them rather than later at a missing file
+- `sections`: ordered regions of one site — a guide, a release log — with `label`, `order`
+  (`asc`/`desc`), or an explicit `items` list. Entries are page paths or nested groups, written
+  with or without an extension; `dir/*` and `dir/**` expand to the pages there that are not
+  placed already, so `["guide/install", "guide/*"]` reads as "this page first, then the rest".
+  Pages no section mentions are placed inside their own section and reported, rather than left
+  unreachable
+- `canopy-page build [site-dir] [-o out]`: checks the site, then publishes it in one pass, so
+  links and backlinks resolve across the whole of it
+- `canopy-page check [site-dir]`: the same checks without building — a settings reference
+  matching no page, a page placed twice, a link pointing at nothing published, an image that is
+  not there, a wikilink matching no page (which renders as plain text rather than as a broken
+  link, so the message says so). Findings name the page and line. Non-zero exit on any error,
+  which is its whole contract with a pipeline
+- Warnings, which are reported without stopping a build: a root-absolute reference
+  (`/assets/logo.png`) with nothing published at that path, and an `exclude` pattern that matched
+  nothing. Where a root-absolute path resolves depends on what the site is served from, so it
+  cannot be called an error — but a site served from its own root is the ordinary case, and the
+  `public/`-style folder other generators map onto the root does not exist here, so such
+  references silently 404. An exclusion written from the wrong place — `_archive` for what is
+  really `docs/_archive` — leaves the folder published while the file reads as though it does not.
+  Extension patterns are left alone: `*.tmp` in a site with no scratch files states a rule about
+  what may never ship, not a claim that something is there
+- `canopy-page init [site-dir]`: a settings file naming the site after its folder, and a home
+  page when there is nothing to publish yet. It never replaces an existing settings file, and
+  writes no page into a folder that already holds markdown
+
+### Notes
+
+- A page is shown under the name canopy gives it — its frontmatter `title`, else the heading it
+  opens with, else its filename — and a section whose directory holds an index page is named by
+  that page. No `label` is written for those, because writing one would override the document's
+  own name with a directory name every time. `label` remains for the cases the documents cannot
+  answer, and still wins when written
+- A reference target is percent-decoded before it is resolved, so `a%20b/note.md` and
+  `<a b/note.md>` are checked as the one document they address. Editors write the first 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`, which it would otherwise have rejected.
+  Decoding is per segment, so `%2F` stays a character inside a name; a malformed escape leaves
+  the reference alone, which is what the renderer does with it
+- Canopy is driven through its command line rather than its library API: it is the same door
+  every other consumer uses, and a door only stays wide enough if the people who could have gone
+  around it do not
+- References inside fenced or inline code are not checked — a fenced example of a broken link is
+  documentation, not a broken link
+- The settings file is never published. A file of the same name deeper in the site is content,
+  and ships
+- The exclusion dialect is four shapes and no more: a directory, that directory and everything
+  beneath it, an extension at any depth, and one exact path. A pattern outside it — `images/*.md`
+  — is refused at validation rather than left to match nothing, which is the answer an unknown key
+  gets and for the same reason
+- A link whose destination stops at a space is reported as that. An unbracketed destination ends
+  at the first space, so `[x](../a b/c.md)` links `../a`, and naming the truncated target alone
+  would describe something the author never wrote
+- A section's heading links its own index page, so naming that page in `items` is not a second
+  placement. A page the settings genuinely list twice still is
+- A reference ending in `/` names a directory, and is answered by the index page that directory is
+  entered by

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 iyulab
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,189 @@
+# canopy-page
+
+> One settings file, one command, one documentation site.
+
+**canopy-page** turns a folder of markdown into a published documentation site. It owns the
+authoring pipeline around the rendering: the settings a site is configured by, the checks that
+keep broken references from shipping, and the build that ties them together. The rendering
+itself is [canopy](https://github.com/iyulab/canopy)'s job, and canopy-page drives it.
+
+---
+
+## Why
+
+Documentation sites in a product repository tend to be rebuilt from scratch each time: a site
+generator, a hand-maintained sidebar, a script that checks images, another that lists release
+notes newest-first. The parts that differ between products are small. The parts that repeat are
+the ones this package holds.
+
+- **One contract.** A `settings.json` beside the markdown, so a site is reproducible from its
+  source tree rather than from a build script holding half the configuration.
+- **Checks that run before publishing.** A dead link costs nothing to find now and is expensive
+  to find after deployment, where it presents as a reader hitting a 404.
+- **One site, built in one pass.** Links and backlinks resolve across the whole of it, so a guide
+  and the release notes it refers to stay connected.
+
+## Install
+
+```sh
+npm install --save-dev @iyulab/canopy-page
+```
+
+Node 22 or newer.
+
+## Getting started
+
+```sh
+npx canopy-page init docs/site     # write a settings file (and a home page, if needed)
+npx canopy-page check docs/site    # report anything broken, without building
+npx canopy-page build docs/site -o dist/help
+```
+
+`init` never replaces a settings file that is already there, and writes no page into a folder
+that already holds markdown — an existing set of documents is being adopted, not started.
+
+`build` runs the same checks `check` does, on the same view of the site, and stops if any of them
+fail. Both leave with a non-zero exit code when they do, which is all a pipeline needs.
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `canopy-page init [site-dir]` | Write a settings file naming the site after its folder |
+| `canopy-page check [site-dir]` | Check settings and references; build nothing |
+| `canopy-page build [site-dir] [-o out]` | Check, then publish to `out` (default `./site`) |
+
+`[site-dir]` is the folder holding `settings.json`, and defaults to the current one.
+
+## settings.json
+
+Every field is an override, so `{}` is a valid settings file: a folder of markdown builds with
+its navigation derived from the folder tree. Settings exist for what a tree cannot say by itself
+— the order of a release log, a label that is not a directory name, a draft folder that stays
+unpublished.
+
+```json
+{
+  "title": "Product Help",
+  "description": "How to use it",
+  "lang": "en-GB",
+  "icon": "assets/favicon.png",
+  "exclude": ["_drafts", "*.tmp"],
+  "sections": [
+    { "path": "guide", "label": "Guide", "items": [
+      { "label": "Orders", "items": ["guide/orders/list", "guide/orders/detail"] },
+      "guide/settings/*"
+    ]},
+    { "path": "release-notes", "label": "Release notes", "order": "desc" }
+  ]
+}
+```
+
+| Field | Meaning |
+|---|---|
+| `title` | Site name. Defaults to the folder's name |
+| `description` | Fills `<meta name="description">`, which is what link previews show |
+| `lang` | BCP 47 tag for `<html lang>`. Worth setting for any non-English site: assistive technology reads pronunciation from it |
+| `icon` | Favicon, relative to the settings file. Must be a published file |
+| `exclude` | Paths to leave unpublished: a directory (`_drafts` or `_drafts/**`), an extension at any depth (`*.tmp`), or one exact path. Patterns are relative to the settings file, and a shape outside that list — `images/*.md` — is refused rather than left to match nothing |
+| `sections` | Ordered regions of the site — see below |
+
+The settings file itself is never published, and neither is anything `exclude` names. A file
+named `settings.json` deeper in the site is content, and ships.
+
+Validation is strict: an unknown key is rejected rather than ignored, because a mistyped one that
+is quietly dropped looks like a tool disobeying its configuration. Every message names the
+position it is about, down to `sections[0].items[1]`.
+
+### Sections
+
+A settings file describes **one site**, built in one pass. `sections` name ordered regions within
+it — a guide, a release log — rather than separate builds. Two genuinely independent sites are
+two settings files.
+
+| Field | Meaning |
+|---|---|
+| `path` | The directory this section covers |
+| `label` | Heading shown for it. Defaults to the directory name |
+| `order` | `asc` or `desc` for the pages inside. `desc` is what a release log wants |
+| `items` | Explicit contents, in display order. Cannot be combined with `order` — a list *is* an order |
+
+An entry in `items` is a page path, or a group:
+
+```json
+{ "label": "Orders", "items": ["guide/orders/list", "guide/orders/detail"] }
+```
+
+Paths may be written with or without their extension. Two glob shapes are understood: `dir/*` is
+the pages directly in a directory, `dir/**` is every page beneath it. A glob means the pages there
+**that are not placed already**, which is what makes `["guide/install", "guide/*"]` read the way
+it looks — this page first, then the rest.
+
+Pages no section mentions are placed anyway, inside their own section where they have one, and
+reported. A page that exists but cannot be reached is a worse outcome than one shown in an order
+nobody chose, and listing three pages of a folder and forgetting the fourth describes an
+oversight rather than a decision to hide it.
+
+Where no ordering is asked for at all, no navigation spec is produced and canopy derives the
+navigation itself. Ordering derived here follows file names rather than page titles.
+
+A page is shown under the name canopy gives it: its frontmatter `title`, else the heading it opens
+with, else its filename. That usually means a section needs no `label` at all — `label` is for the
+cases the documents cannot answer, and it still overrides them when written. A section whose
+directory holds an `index` page is named by that page for the same reason.
+
+A section's heading already links its own index page, so naming that page in `items` asks for what
+is there rather than for a second copy of it, and is not counted as placing it twice.
+
+## What `check` reports
+
+Errors — these stop a build:
+
+- A settings reference that matches no page, or a page placed more than once
+- A link that points at nothing published, naming the page and the line
+- An image that is not a published file
+- A wikilink that matches no page. It renders as plain text rather than as a broken link, so the
+  message says so — otherwise nobody knows what they are looking for
+
+A link whose destination stops at a space is reported as that, rather than as the truncated path
+it becomes. An unbracketed destination ends at the first space — `[x](../a b/c.md)` links `../a`
+and leaves the rest as text — so the target the message would otherwise name is one nobody wrote.
+
+Warnings — reported, and the build continues:
+
+- Pages no section covers
+- A root-absolute reference (`/assets/logo.png`) with nothing published at that path. Where such a
+  path resolves depends on what the site is served from, which is not a checker's to know — but a
+  site served from its own root is the ordinary case, and a `public/`-style folder that other
+  generators map onto the root does not exist here, so these silently 404. A warning rather than
+  an error, because mounting the site elsewhere would make it right
+- An `exclude` pattern that matched nothing, which usually means a path written from the wrong
+  place. Extension patterns are left alone: `*.tmp` in a site with no scratch files is a rule
+  about what may never ship, not a claim that something is there
+
+Checking reads the settings and each page. It never renders, so it is fast enough to sit at the
+front of a pipeline, at the scale a product manual reaches. References inside fenced
+or inline code are ignored: a fenced example of a broken link is documentation, not a broken link.
+What canopy states it leaves alone is left alone here too — absolute URLs, protocol-relative URLs,
+bare fragments, and paths above the site root. A target ending in `/` names a directory, and is
+answered by the index page that directory is entered by.
+
+## What belongs where
+
+canopy-page owns the authoring pipeline; canopy owns the rendering.
+
+| | canopy-page | canopy |
+|---|---|---|
+| Configuration | `settings.json` and its validation | — |
+| Structure | sections, order, labels, globs | navigation tree, link resolution |
+| Integrity | reference checks, exit codes | — |
+| Output | — | HTML, assets, backlinks, outlines, site shell |
+
+canopy is driven through its command line rather than its library API, on purpose: it is the same
+door every other consumer uses, and a door only stays wide enough if the people who could have
+gone around it do not. Where the command line cannot express something, that is worth raising
+with canopy rather than working around here.
+
+## License
+
+MIT

package/dist/build.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Building a site: check first, then hand the whole of it to canopy in one pass.
+ *
+ * Checking before building is the order every documentation set that has been
+ * burned by this arrives at. A broken reference costs nothing to find now and
+ * is expensive to find after deployment, where it presents as a reader hitting
+ * a 404 rather than as a build saying which line is wrong.
+ */
+/** Where a build reads from and writes to. */
+export interface BuildOptions {
+    /** Directory holding the settings file. */
+    dir: string;
+    /** Directory to write the site into. */
+    out: string;
+}
+/** Build the site in `dir` into `out`, returning the exit code to leave with. */
+export declare function buildSite({ dir, out }: BuildOptions): Promise<number>;

package/dist/build.js

@@ -0,0 +1,57 @@
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { runCanopy } from "./canopy.js";
+import { siteFindings } from "./check.js";
+import { loadSite, reportFindings } from "./site.js";
+/**
+ * Translate settings into canopy's arguments.
+ *
+ * Everything a settings file says about the site itself is already something
+ * canopy takes: this is a translation, not a layer of behaviour of its own. The
+ * navigation spec is the one thing that has to be materialized, since canopy
+ * reads it from a file.
+ */
+function canopyArgs(site, out, navPath) {
+    const { settings } = site;
+    return [
+        "build",
+        site.root,
+        out,
+        ...(settings.title === undefined ? [] : ["--site-title", settings.title]),
+        ...(settings.description === undefined ? [] : ["--site-description", settings.description]),
+        ...(settings.lang === undefined ? [] : ["--lang", settings.lang]),
+        ...(settings.icon === undefined ? [] : ["--site-icon", settings.icon]),
+        ...(navPath === undefined ? [] : ["--nav", navPath]),
+        // The settings file is configuration rather than content, and canopy has no
+        // reason to know it exists; excluding it keeps it off the published site.
+        ...["--exclude", "settings.json"],
+        ...(settings.exclude ?? []).flatMap((pattern) => ["--exclude", pattern]),
+    ];
+}
+/** Build the site in `dir` into `out`, returning the exit code to leave with. */
+export async function buildSite({ dir, out }) {
+    const site = await loadSite(dir);
+    // The same checks `check` runs, on the same view of the site, so a build can
+    // never publish something a passing check said was sound.
+    if (reportFindings(await siteFindings(site)))
+        return 1;
+    // The spec is derived from settings and means nothing on its own, so it lives
+    // in a temporary file rather than in the site or its output: writing it beside
+    // the source would leave a generated file for someone to edit by hand, and
+    // writing it into the output would ship it.
+    let workDir;
+    let navPath;
+    try {
+        if (site.nav.spec !== undefined) {
+            workDir = await mkdtemp(path.join(tmpdir(), "canopy-page-"));
+            navPath = path.join(workDir, "nav.json");
+            await writeFile(navPath, JSON.stringify(site.nav.spec, null, 2), "utf8");
+        }
+        return await runCanopy(canopyArgs(site, path.resolve(out), navPath));
+    }
+    finally {
+        if (workDir !== undefined)
+            await rm(workDir, { recursive: true, force: true });
+    }
+}

package/dist/canopy.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Running canopy.
+ *
+ * canopy-page drives canopy through its command line rather than importing its
+ * library, deliberately: it is the same door every other consumer uses, and a
+ * door only stays wide enough if the people who could have gone around it do
+ * not. A gap in the CLI that canopy-page routed around would be a gap nobody
+ * else gets fixed either.
+ *
+ * The executable is located through the dependency itself, so the version that
+ * runs is the version this package resolved — not whatever a `canopy` on the
+ * PATH happens to be.
+ */
+/**
+ * Absolute path of canopy's executable.
+ *
+ * Resolved as a sibling of the package entry point, because the package does not
+ * expose its own `package.json` and so its `bin` declaration cannot be read.
+ * Spawning the JavaScript file with this process's Node is what keeps this
+ * working the same on every platform: `node_modules/.bin/canopy` is a shell
+ * script on one and a `.cmd` on another, and running either would mean handing
+ * arguments to a shell to re-parse.
+ */
+export declare function canopyExecutable(): string;
+/** Run canopy with the given arguments, inheriting stdio, and return its exit code. */
+export declare function runCanopy(args: readonly string[]): Promise<number>;

package/dist/canopy.js

@@ -0,0 +1,44 @@
+import { spawn } from "node:child_process";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+/**
+ * Running canopy.
+ *
+ * canopy-page drives canopy through its command line rather than importing its
+ * library, deliberately: it is the same door every other consumer uses, and a
+ * door only stays wide enough if the people who could have gone around it do
+ * not. A gap in the CLI that canopy-page routed around would be a gap nobody
+ * else gets fixed either.
+ *
+ * The executable is located through the dependency itself, so the version that
+ * runs is the version this package resolved — not whatever a `canopy` on the
+ * PATH happens to be.
+ */
+/**
+ * Absolute path of canopy's executable.
+ *
+ * Resolved as a sibling of the package entry point, because the package does not
+ * expose its own `package.json` and so its `bin` declaration cannot be read.
+ * Spawning the JavaScript file with this process's Node is what keeps this
+ * working the same on every platform: `node_modules/.bin/canopy` is a shell
+ * script on one and a `.cmd` on another, and running either would mean handing
+ * arguments to a shell to re-parse.
+ */
+export function canopyExecutable() {
+    const entry = fileURLToPath(import.meta.resolve("@iyulab/canopy"));
+    return path.join(path.dirname(entry), "cli.js");
+}
+/** Run canopy with the given arguments, inheriting stdio, and return its exit code. */
+export async function runCanopy(args) {
+    const child = spawn(process.execPath, [canopyExecutable(), ...args], {
+        stdio: "inherit",
+    });
+    return new Promise((resolve, reject) => {
+        child.on("error", reject);
+        child.on("close", (code, signal) => {
+            // A signal death has no exit code, and reporting success for it would let
+            // a killed build pass a pipeline.
+            resolve(code ?? (signal === null ? 1 : 1));
+        });
+    });
+}

package/dist/check.d.ts

@@ -0,0 +1,10 @@
+import { type Finding, type LoadedSite } from "./site.js";
+/** Check every page's references, returning one finding per broken reference. */
+export declare function referenceFindings(site: LoadedSite): Promise<Finding[]>;
+/**
+ * Everything worth saying about a site, in the order a reader wants it: what
+ * the settings got wrong first, then what the pages point at.
+ */
+export declare function siteFindings(site: LoadedSite): Promise<Finding[]>;
+/** Check the site in `dir`, returning the exit code to leave with. */
+export declare function checkSite(dir: string): Promise<number>;

package/dist/check.js

@@ -0,0 +1,157 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { decodeTarget, extractReferences, isExternalUrl, resolveFrom, targetPath, } from "./references.js";
+import { loadSite, navFindings, reportFindings, settingsFindings, } from "./site.js";
+import { toPageKey } from "./vault.js";
+/**
+ * Checking a site's references before it is published.
+ *
+ * Every finding here is something a reader would meet as a 404 or a missing
+ * image after deployment — the most expensive place to learn about it, and the
+ * one where nobody is watching a build log. Finding it costs a directory listing
+ * and a read of each page.
+ *
+ * The checker asks whether *anything* is at the other end of a reference, never
+ * which of several candidates the renderer would choose. That question has an
+ * answer only the renderer owns, and a checker that answered it differently
+ * would report failures on links that build perfectly well.
+ */
+/**
+ * A path anchored to wherever the site is served from, rather than to the page.
+ *
+ * canopy leaves these exactly as written, because only the deployment knows what
+ * `/` is. That is a reason not to rewrite one — not a reason to say nothing
+ * about it. A site served from the root, which is the ordinary case, resolves
+ * these against its own root, and whether anything is there is a question this
+ * can answer.
+ */
+function isRootAbsolute(url) {
+    return url.startsWith("/") && !url.startsWith("//");
+}
+/**
+ * Does anything published sit at this path — a page, a copied file, or the index
+ * page a directory is entered by?
+ *
+ * A target written with a trailing slash names a directory, and a directory is
+ * served by its index page. `/update-note/` is a correct link to a site holding
+ * `update-note/index.md`, so reading it as a missing file would report a working
+ * link as broken.
+ */
+function existsInSite(site, sitePath) {
+    const directory = sitePath.endsWith("/");
+    const bare = directory ? sitePath.replace(/\/+$/, "") : sitePath;
+    if (directory)
+        return site.index.resolve(`${bare}/index`) !== undefined;
+    if (site.index.resolve(bare) !== undefined)
+        return true;
+    const key = bare.toLowerCase();
+    return site.index.assets.some((asset) => asset.toLowerCase() === key);
+}
+/**
+ * Does any page answer to this wikilink target?
+ *
+ * Wikilinks address a note by name or by path, tree-wide. Which note wins when a
+ * name is ambiguous is the renderer's rule; whether one exists at all is not, so
+ * that is all this asks.
+ */
+function wikilinkExists(site, target) {
+    const key = toPageKey(target);
+    if (key.includes("/"))
+        return site.index.resolve(target) !== undefined;
+    return site.index.pages.some((page) => toPageKey(page).split("/").pop() === key);
+}
+/** Check every page's references, returning one finding per broken reference. */
+export async function referenceFindings(site) {
+    const findings = [];
+    for (const page of site.index.pages) {
+        const markdown = await readFile(path.join(site.root, page), "utf8");
+        for (const reference of extractReferences(markdown)) {
+            const where = `${page}:${reference.line}`;
+            if (reference.kind === "wikilink") {
+                if (!wikilinkExists(site, reference.target)) {
+                    findings.push({
+                        level: "error",
+                        // Naming the consequence matters: an unresolved wikilink is not left
+                        // visibly broken, it renders as plain text, so nobody notices.
+                        message: `${where}: [[${reference.target}]] matches no page, and will render as plain text`,
+                    });
+                }
+                continue;
+            }
+            const url = targetPath(reference.target);
+            if (isRootAbsolute(url)) {
+                const atRoot = decodeTarget(url.replace(/^\/+/, "")) ?? url.replace(/^\/+/, "");
+                if (atRoot === "" || existsInSite(site, atRoot))
+                    continue;
+                findings.push({
+                    level: "warning",
+                    message: `${where}: ${reference.kind} "${reference.target}" — ` +
+                        `nothing is published at "${atRoot}". A root-absolute path resolves ` +
+                        "against wherever the site is served from, so this is right only if " +
+                        "something else answers it there",
+                });
+                continue;
+            }
+            if (isExternalUrl(url))
+                continue;
+            // Classified as a URL above, resolved as a path from here — so the
+            // encoding an editor wrote is undone only after the cases that are about
+            // URL syntax have been answered.
+            const decoded = decodeTarget(url);
+            // An escape the renderer cannot read either: it leaves the link as
+            // written, so there is no published target to hold the page to.
+            if (decoded === undefined)
+                continue;
+            const resolved = resolveFrom(page, decoded);
+            // A target that walks above the site root addresses something outside it,
+            // which the renderer leaves alone and this has no standing to judge.
+            if (resolved === undefined || resolved === "")
+                continue;
+            // Resolution drops a trailing slash along with the empty segment it makes,
+            // and with it the fact that the target named a directory.
+            if (existsInSite(site, decoded.endsWith("/") ? `${resolved}/` : resolved))
+                continue;
+            if (reference.cutAtSpace) {
+                findings.push({
+                    level: "error",
+                    message: `${where}: ${reference.kind} destination stops at a space, so it addresses ` +
+                        `"${reference.target}" and the rest of the line is left as text. ` +
+                        "Wrap the path in <> or write the space as %20",
+                });
+                continue;
+            }
+            findings.push({
+                level: "error",
+                message: reference.kind === "image"
+                    ? `${where}: image "${reference.target}" is not a published file`
+                    : `${where}: link "${reference.target}" points at nothing published`,
+            });
+        }
+    }
+    return findings;
+}
+/**
+ * Everything worth saying about a site, in the order a reader wants it: what
+ * the settings got wrong first, then what the pages point at.
+ */
+export async function siteFindings(site) {
+    return [
+        ...settingsFindings(site),
+        ...navFindings(site.nav),
+        ...(await referenceFindings(site)),
+    ];
+}
+/** Check the site in `dir`, returning the exit code to leave with. */
+export async function checkSite(dir) {
+    const site = await loadSite(dir);
+    const findings = await siteFindings(site);
+    const failed = reportFindings(findings);
+    if (!failed) {
+        // "nothing broken" after a screen of warnings reads as a contradiction, so
+        // the closing line says which of the two happened.
+        const warnings = findings.length;
+        console.log(`canopy-page: ${site.index.pages.length} page(s) checked, ` +
+            (warnings === 0 ? "nothing broken" : `nothing broken, ${warnings} warning(s)`));
+    }
+    return failed ? 1 : 0;
+}

package/dist/cli-args.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Parsing the command line, kept apart from acting on it.
+ *
+ * Argument handling is where a tool is least forgiving and most tested: a
+ * mistyped flag has to say so rather than being ignored, since a build that
+ * quietly used a default nobody asked for is indistinguishable from a working
+ * one until the site is deployed.
+ */
+/** A parsed invocation, or the reason it could not be parsed. */
+export type ParsedArgs = {
+    ok: true;
+    command: "build";
+    dir: string;
+    out: string;
+} | {
+    ok: true;
+    command: "check" | "init";
+    dir: string;
+} | {
+    ok: false;
+    error: string;
+};
+export declare const USAGE: string;
+export declare function parseArgs(argv: readonly string[]): ParsedArgs;