@iyulab/canopy-page 0.1.0

package/dist/cli-args.js

@@ -0,0 +1,70 @@
+/**
+ * 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.
+ */
+export const USAGE = [
+    "Usage: canopy-page <command> [site-dir] [options]",
+    "",
+    "  init  [site-dir]           Start a site: write a settings file",
+    "  check [site-dir]           Check the site without publishing it",
+    "  build [site-dir]           Check the site, then publish it",
+    "",
+    "  [site-dir]                 Folder holding settings.json (defaults to .)",
+    "  -o, --out <dir>            Where build writes the site (defaults to ./site)",
+].join("\n");
+const OUT_FLAGS = new Set(["-o", "--out"]);
+export function parseArgs(argv) {
+    const [command, ...rest] = argv;
+    if (command === undefined)
+        return { ok: false, error: USAGE };
+    if (command === "build" || command === "check" || command === "init") {
+        return parseCommand(command, rest);
+    }
+    if (command.startsWith("-")) {
+        // A flag where a command belongs usually means the command was forgotten,
+        // and "unknown command --out" would send someone looking for the wrong bug.
+        return { ok: false, error: `${USAGE}\n\nExpected a command before "${command}".` };
+    }
+    return { ok: false, error: `${USAGE}\n\nUnknown command "${command}".` };
+}
+function parseCommand(command, argv) {
+    const positional = [];
+    let out;
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (OUT_FLAGS.has(arg)) {
+            if (command !== "build") {
+                // Only build writes a site, so an output directory elsewhere is not a
+                // harmless extra: whoever passed it expects a site to appear somewhere.
+                return {
+                    ok: false,
+                    error: `${arg} is for build, which writes a site; ${command} does not.`,
+                };
+            }
+            const value = argv[i + 1];
+            if (value === undefined || value.startsWith("-")) {
+                return { ok: false, error: `${arg} needs a directory.` };
+            }
+            out = value;
+            i += 1;
+            continue;
+        }
+        if (arg.startsWith("-")) {
+            return { ok: false, error: `${USAGE}\n\nUnknown option "${arg}".` };
+        }
+        positional.push(arg);
+    }
+    if (positional.length > 1) {
+        // The output directory is a flag precisely so it cannot be confused with the
+        // input one; a second bare path is more likely a typo than an intention.
+        return { ok: false, error: `${USAGE}\n\nUnexpected argument "${positional[1]}".` };
+    }
+    const dir = positional[0] ?? ".";
+    if (command === "build")
+        return { ok: true, command, dir, out: out ?? "site" };
+    return { ok: true, command, dir };
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+import { buildSite } from "./build.js";
+import { checkSite } from "./check.js";
+import { initSite, InitError } from "./init.js";
+import { parseArgs } from "./cli-args.js";
+import { SiteError } from "./site.js";
+async function main() {
+    const args = parseArgs(process.argv.slice(2));
+    if (!args.ok) {
+        console.error(args.error);
+        process.exitCode = 1;
+        return;
+    }
+    if (args.command === "init") {
+        const { settingsPath, pagePath } = await initSite(args.dir);
+        console.log(`canopy-page: wrote ${settingsPath}`);
+        if (pagePath !== undefined)
+            console.log(`canopy-page: wrote ${pagePath}`);
+        console.log("canopy-page: run `canopy-page build` to publish it");
+        return;
+    }
+    process.exitCode =
+        args.command === "build"
+            ? await buildSite({ dir: args.dir, out: args.out })
+            : await checkSite(args.dir);
+}
+main().catch((error) => {
+    // A site error is about the site, not about canopy-page: the message is the
+    // whole of what a reader needs, and a stack trace on top of it only buries it.
+    if (error instanceof SiteError || error instanceof InitError) {
+        console.error(`error: ${error.message}`);
+    }
+    else
+        console.error(error);
+    process.exitCode = 1;
+});

package/dist/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * canopy-page — the authoring pipeline around a documentation site.
+ *
+ * Rendering markdown into a site is canopy's job; this package owns what
+ * surrounds it: the `settings.json` contract a documentation set is configured
+ * with, the integrity checks that keep a published site from shipping broken
+ * references, and the build that ties them together.
+ *
+ * The command line is the intended way in. This entry point exposes the same
+ * pieces for a caller that wants to run a check inside its own tooling.
+ */
+export { buildSite, type BuildOptions } from "./build.js";
+export { checkSite, referenceFindings, siteFindings } from "./check.js";
+export { initSite, InitError, type InitResult } from "./init.js";
+export { extractReferences, isExternalUrl, type Reference, } from "./references.js";
+export { loadSite, navFindings, reportFindings, SiteError, type Finding, type LoadedSite, } from "./site.js";
+export { parseSettings, SettingsError, type Settings, type SettingsNavItem, type SettingsSection, } from "./settings.js";

package/dist/index.js

@@ -0,0 +1,17 @@
+/**
+ * canopy-page — the authoring pipeline around a documentation site.
+ *
+ * Rendering markdown into a site is canopy's job; this package owns what
+ * surrounds it: the `settings.json` contract a documentation set is configured
+ * with, the integrity checks that keep a published site from shipping broken
+ * references, and the build that ties them together.
+ *
+ * The command line is the intended way in. This entry point exposes the same
+ * pieces for a caller that wants to run a check inside its own tooling.
+ */
+export { buildSite } from "./build.js";
+export { checkSite, referenceFindings, siteFindings } from "./check.js";
+export { initSite, InitError } from "./init.js";
+export { extractReferences, isExternalUrl, } from "./references.js";
+export { loadSite, navFindings, reportFindings, SiteError, } from "./site.js";
+export { parseSettings, SettingsError, } from "./settings.js";

package/dist/init.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Starting a site.
+ *
+ * `init` exists because the first minute is the one where a tool is judged, and
+ * a blank folder plus a file format is not a start. What it writes is
+ * deliberately small: a settings file naming the site, and a page to build if
+ * there is nothing to build yet.
+ *
+ * It writes no example sections. A preset that referenced folders the author
+ * does not have would fail the very first check, which teaches that the tool
+ * complains before it has been used for anything. Every setting is an override,
+ * so the honest starting point is the one with nothing overridden.
+ *
+ * ## About `$schema`
+ *
+ * The preset does not carry one. An editor resolves `$schema` by fetching it,
+ * and a URL that answers 404 is worse than no URL at all: it puts a permanent
+ * error in the author's editor and teaches them to ignore the one place
+ * mistakes in this file would be shown. Settings are validated strictly when
+ * they are read, naming the exact position of anything wrong, so nothing is
+ * unguarded in the meantime — and adding `$schema` later is a line in a file,
+ * for which the parser already makes room by accepting and ignoring the key.
+ */
+/** What `init` created, so the caller can say so. */
+export interface InitResult {
+    /** Absolute path of the settings file written. */
+    settingsPath: string;
+    /** Absolute path of the starter page, when one was needed. */
+    pagePath?: string;
+}
+/** Why a site could not be started here. */
+export declare class InitError extends Error {
+}
+/** A site title from a folder name: `product-help` reads as `Product help`. */
+export declare function titleFromDirectory(dir: string): string;
+/**
+ * Write a starting settings file into `dir`, creating the folder if needed.
+ *
+ * An existing settings file is never overwritten. Running `init` twice is
+ * usually a mistake about which folder one is in, and the cost of guessing
+ * wrong — a settings file replaced by a blank one — is far higher than the cost
+ * of saying so.
+ */
+export declare function initSite(dir: string): Promise<InitResult>;

package/dist/init.js

@@ -0,0 +1,54 @@
+import { access, mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { listSiteFiles, isPage, SETTINGS_FILENAME } from "./vault.js";
+/** Why a site could not be started here. */
+export class InitError extends Error {
+}
+async function exists(file) {
+    try {
+        await access(file);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** A site title from a folder name: `product-help` reads as `Product help`. */
+export function titleFromDirectory(dir) {
+    const name = path.basename(path.resolve(dir)).replace(/[-_]+/g, " ").trim();
+    if (name === "")
+        return "Site";
+    return name.charAt(0).toUpperCase() + name.slice(1);
+}
+const STARTER_PAGE = `# {title}
+
+This is the home page of the site. Everything in this folder is published with
+it: sub-folders become sections, and links between pages keep working.
+`;
+/**
+ * Write a starting settings file into `dir`, creating the folder if needed.
+ *
+ * An existing settings file is never overwritten. Running `init` twice is
+ * usually a mistake about which folder one is in, and the cost of guessing
+ * wrong — a settings file replaced by a blank one — is far higher than the cost
+ * of saying so.
+ */
+export async function initSite(dir) {
+    const root = path.resolve(dir);
+    await mkdir(root, { recursive: true });
+    const settingsPath = path.join(root, SETTINGS_FILENAME);
+    if (await exists(settingsPath)) {
+        throw new InitError(`${settingsPath} already exists, and init will not replace it.`);
+    }
+    const existing = await listSiteFiles(root);
+    const title = titleFromDirectory(root);
+    await writeFile(settingsPath, `${JSON.stringify({ title }, null, 2)}\n`, "utf8");
+    // A folder that already holds markdown is an existing set of documents being
+    // adopted, not a new site; writing a home page into it would be an opinion
+    // about content, which is not this tool's to have.
+    if (existing.some(isPage))
+        return { settingsPath };
+    const pagePath = path.join(root, "index.md");
+    await writeFile(pagePath, STARTER_PAGE.replace("{title}", title), "utf8");
+    return { settingsPath, pagePath };
+}

package/dist/nav.d.ts

@@ -0,0 +1,56 @@
+import type { Settings } from "./settings.js";
+import { type PageIndex } from "./vault.js";
+/**
+ * Translate a settings file into the navigation spec canopy consumes.
+ *
+ * Settings speak in the author's terms — sections of a site, a release log that
+ * reads newest-first, a folder listed page by page. Canopy consumes one flat
+ * spec of ordered items and knows nothing about where it came from. This module
+ * is the whole of the translation between the two, which is what keeps the
+ * author's vocabulary out of canopy and canopy's out of the settings file.
+ *
+ * ## Why a spec has to describe the whole site
+ *
+ * Canopy applies a spec instead of deriving navigation, not alongside it: pages
+ * a spec omits are left out and reported. So ordering one section means naming
+ * every other page too, and the pages an author did not order are derived here
+ * — a second derivation next to canopy's own, which is duplication with a drift
+ * risk rather than a design.
+ * TODO(upstream: claudedocs/issues/ISSUE-canopy-20260806-partial-nav-spec.md)
+ * proposes the partial spec that would retire it.
+ *
+ * When settings ask for no ordering at all, no spec is emitted and canopy
+ * derives navigation itself — the case where the duplication costs nothing.
+ */
+/** The navigation spec canopy reads from `--nav`: items in display order. */
+export interface NavSpec {
+    items: NavSpecItem[];
+}
+/** One spec entry: a page (`path`), a group (`items`), or a group with its own page. */
+export interface NavSpecItem {
+    label?: string;
+    path?: string;
+    items?: NavSpecItem[];
+}
+/** What the translation produced, and what it could not place. */
+export interface NavTranslation {
+    /** The spec to pass to canopy, or `undefined` to let canopy derive navigation. */
+    spec?: NavSpec;
+    /** Settings references that match no page in the site. */
+    missing: string[];
+    /** Published pages no section covers. */
+    orphans: string[];
+    /** Pages the settings place more than once. */
+    duplicates: string[];
+}
+/**
+ * Turn settings plus the site's pages into the spec canopy builds from.
+ *
+ * Pages no section mentions are appended rather than dropped — inside their own
+ * section when they have one, after the sections when they do not. A page that
+ * exists but cannot be reached is a worse outcome than one shown in an order
+ * nobody chose, and an author who lists three pages of a folder and forgets the
+ * fourth is describing an oversight, not a decision to hide it. They are
+ * reported as orphans either way, so the author can say which they meant.
+ */
+export declare function translateNav(settings: Settings, index: PageIndex): NavTranslation;

package/dist/nav.js

@@ -0,0 +1,235 @@
+import { toPageKey } from "./vault.js";
+/** The page a directory is entered by, if it has one. */
+function indexOf(dir, index) {
+    return index.resolve(dir === "" ? "index" : `${dir}/index`);
+}
+function stemOf(pagePath) {
+    return (pagePath.split("/").pop() ?? pagePath).replace(/\.md$/i, "");
+}
+function lastSegment(dir) {
+    return dir.split("/").pop() ?? dir;
+}
+/** Pages directly inside a directory, excluding nested ones. */
+function pagesDirectlyIn(dir, pages) {
+    const prefix = dir === "" ? "" : `${dir}/`;
+    return pages.filter((page) => {
+        if (!page.toLowerCase().startsWith(prefix.toLowerCase()))
+            return false;
+        return !page.slice(prefix.length).includes("/");
+    });
+}
+/** Pages anywhere beneath a directory. */
+function pagesUnder(dir, pages) {
+    const prefix = `${dir.toLowerCase()}/`;
+    return pages.filter((page) => page.toLowerCase().startsWith(prefix));
+}
+/** Immediate subdirectory names of a directory, in the order pages first named them. */
+function subdirectoriesOf(dir, pages) {
+    const prefix = dir === "" ? "" : `${dir}/`;
+    const names = new Set();
+    for (const page of pages) {
+        if (!page.toLowerCase().startsWith(prefix.toLowerCase()))
+            continue;
+        const rest = page.slice(prefix.length);
+        const slash = rest.indexOf("/");
+        if (slash > 0)
+            names.add(rest.slice(0, slash));
+    }
+    return [...names];
+}
+function byStem(order) {
+    const direction = order === "desc" ? -1 : 1;
+    return (a, b) => direction * stemOf(a).localeCompare(stemOf(b), undefined, { sensitivity: "base" });
+}
+function byName(order) {
+    const direction = order === "desc" ? -1 : 1;
+    return (a, b) => direction * a.localeCompare(b, undefined, { sensitivity: "base" });
+}
+/**
+ * Derive the contents of a directory the author did not list.
+ *
+ * Ordering follows file names rather than frontmatter titles. Canopy's own
+ * derivation prefers a title when a page has one, but reading titles means
+ * parsing every document, which is canopy's work and not worth duplicating for
+ * a sort key. File names are what an author sees in the folder they are
+ * ordering, and `desc` on a log of dated files is exactly the case this serves.
+ */
+function deriveItems(dir, index, order, place) {
+    const items = [];
+    // Folders before pages, mirroring how canopy derives a tree, so a site that
+    // orders one section does not reshuffle the others.
+    for (const name of subdirectoriesOf(dir, index.pages).sort(byName(order))) {
+        const childDir = dir === "" ? name : `${dir}/${name}`;
+        const childIndex = indexOf(childDir, index);
+        if (childIndex !== undefined)
+            place(childIndex);
+        items.push({
+            // A directory with an index page is named by that page — canopy asks the
+            // document first and falls back to this same directory name when it has
+            // no name of its own. Writing the label here would win over the document
+            // every time, which is this file answering a question it already delegates.
+            ...(childIndex === undefined ? { label: name } : { path: childIndex }),
+            items: deriveItems(childDir, index, order, place),
+        });
+    }
+    const ownIndex = indexOf(dir, index);
+    for (const page of pagesDirectlyIn(dir, index.pages).sort(byStem(order))) {
+        // A directory's index page is entered through the directory itself, so
+        // listing it again would show the same page twice under two names.
+        if (page === ownIndex)
+            continue;
+        place(page);
+        items.push({ path: page });
+    }
+    return items;
+}
+/** Expand one settings entry, which may be a page, a glob, or a group. */
+function expandItem(item, index, report) {
+    const children = item.items?.flatMap((child) => expandItem(child, index, report));
+    if (item.path === undefined) {
+        return [{ ...(item.label === undefined ? {} : { label: item.label }), items: children ?? [] }];
+    }
+    if (item.path.includes("*")) {
+        // A glob stands for the pages it matches, so it expands in place rather
+        // than becoming a node of its own — `guide/settings/*` means those pages,
+        // not a group containing them.
+        //
+        // It 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. It also keeps a section from listing its own index page a
+        // second time, since the section's label already links it.
+        const matched = expandGlob(item.path, index).filter((page) => !report.isPlaced(page));
+        if (matched.length === 0)
+            report.missing.push(item.path);
+        for (const page of matched)
+            report.place(page);
+        return matched.map((page) => ({ path: page }));
+    }
+    // The section heading is already a link to its index page, so listing it again
+    // would show one page twice under two names. A glob reaches this by filtering
+    // what is placed; an explicit mention is the same request spelled out, and
+    // used to come back as "placed more than once" — a contradiction to an author
+    // who named it once.
+    if (report.sectionIndex !== undefined && index.resolve(item.path) === report.sectionIndex) {
+        return children === undefined ? [] : children;
+    }
+    const resolved = index.resolve(item.path);
+    if (resolved === undefined) {
+        report.missing.push(item.path);
+        // A group survives losing its own page; a leaf has nothing left to show.
+        if (children === undefined)
+            return [];
+        return [{ ...(item.label === undefined ? {} : { label: item.label }), items: children }];
+    }
+    report.place(resolved);
+    return [
+        {
+            ...(item.label === undefined ? {} : { label: item.label }),
+            path: resolved,
+            ...(children === undefined ? {} : { items: children }),
+        },
+    ];
+}
+/**
+ * Expand a glob into pages, in file-name order.
+ *
+ * Two shapes, matching how small the exclusion dialect is kept: `dir/*` is the
+ * pages directly in a directory, `dir/**` is every page beneath it.
+ */
+function expandGlob(pattern, index) {
+    const normalized = pattern.replace(/\\/g, "/");
+    if (normalized.endsWith("/**")) {
+        return pagesUnder(normalized.slice(0, -3), index.pages).sort(byName("asc"));
+    }
+    if (normalized.endsWith("/*")) {
+        return pagesDirectlyIn(normalized.slice(0, -2), index.pages).sort(byStem("asc"));
+    }
+    // Any other use of `*` is a pattern this does not implement, and matching
+    // nothing would look like a site with missing pages rather than a settings
+    // file using a shape that was never supported.
+    return [];
+}
+function translateSection(section, index, report) {
+    const sectionIndex = indexOf(section.path, index);
+    if (sectionIndex !== undefined)
+        report.place(sectionIndex);
+    const items = section.items === undefined
+        ? deriveItems(section.path, index, section.order ?? "asc", report.place)
+        : section.items.flatMap((item) => expandItem(item, index, { ...report, sectionIndex }));
+    if (sectionIndex === undefined && items.length === 0) {
+        report.missing.push(section.path);
+    }
+    // Same rule as a derived directory: the page fronting a section names it, and
+    // only a section with no index page needs a name written for it here. A label
+    // in the settings file still wins — that is what writing one is for.
+    const label = section.label ?? (sectionIndex === undefined ? lastSegment(section.path) : undefined);
+    return {
+        ...(label === undefined ? {} : { label }),
+        ...(sectionIndex === undefined ? {} : { path: sectionIndex }),
+        items,
+    };
+}
+/** A view of the same site narrowed to a subset of its pages. */
+function narrowTo(pages, index) {
+    const keys = new Set(pages.map(toPageKey));
+    return {
+        pages,
+        assets: index.assets,
+        resolve: (reference) => (keys.has(toPageKey(reference)) ? index.resolve(reference) : undefined),
+    };
+}
+/**
+ * Turn settings plus the site's pages into the spec canopy builds from.
+ *
+ * Pages no section mentions are appended rather than dropped — inside their own
+ * section when they have one, after the sections when they do not. A page that
+ * exists but cannot be reached is a worse outcome than one shown in an order
+ * nobody chose, and an author who lists three pages of a folder and forgets the
+ * fourth is describing an oversight, not a decision to hide it. They are
+ * reported as orphans either way, so the author can say which they meant.
+ */
+export function translateNav(settings, index) {
+    const sections = settings.sections ?? [];
+    if (sections.length === 0) {
+        return { missing: [], orphans: [], duplicates: [] };
+    }
+    const placements = new Map();
+    const missing = [];
+    const place = (page) => {
+        placements.set(page, (placements.get(page) ?? 0) + 1);
+    };
+    const report = { missing, place, isPlaced: (page) => placements.has(page) };
+    const items = sections.map((section) => translateSection(section, index, report));
+    // The root index is the site's home page: it is reached without navigation, so
+    // it is neither placed by a section nor counted as something nobody placed.
+    const homePage = indexOf("", index);
+    const orphans = index.pages.filter((page) => !placements.has(page) && page !== homePage);
+    // Leftovers land in the section that covers them, so a partly-listed folder
+    // stays one folder in the sidebar instead of appearing a second time at the end.
+    let stray = orphans;
+    sections.forEach((section, i) => {
+        const mine = stray.filter((page) => page.toLowerCase().startsWith(`${section.path.toLowerCase()}/`));
+        if (mine.length === 0)
+            return;
+        stray = stray.filter((page) => !mine.includes(page));
+        const target = items[i];
+        if (target === undefined)
+            return;
+        target.items = [
+            ...(target.items ?? []),
+            ...deriveItems(section.path, narrowTo(mine, index), section.order ?? "asc", place),
+        ];
+    });
+    if (stray.length > 0) {
+        items.push(...deriveItems("", narrowTo(stray, index), "asc", place));
+    }
+    if (homePage !== undefined) {
+        // Home first: it is where a reader lands, so it reads oddly anywhere else.
+        items.unshift({ path: homePage });
+    }
+    const duplicates = [...placements.entries()]
+        .filter(([, count]) => count > 1)
+        .map(([page]) => page)
+        .sort();
+    return { spec: { items }, missing, orphans, duplicates };
+}

package/dist/references.d.ts

@@ -0,0 +1,79 @@
+/**
+ * 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.
+ */
+/** Something a document points at. */
+export interface Reference {
+    /** The target exactly as written. */
+    target: string;
+    kind: "link" | "image" | "wikilink";
+    /** 1-based line in the document, so a finding can name where to look. */
+    line: number;
+    /**
+     * The destination ran into a space and stopped there, leaving the rest of the
+     * line outside the link. `target` is what the renderer will use, which is not
+     * what the author wrote — the one case where reporting the target alone
+     * describes something nobody typed.
+     */
+    cutAtSpace?: true;
+}
+/**
+ * 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 declare function extractReferences(markdown: string): Reference[];
+/**
+ * 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 declare function isExternalUrl(url: string): boolean;
+/** Strip a query string or fragment, which address a place *within* a target. */
+export declare function targetPath(url: string): string;
+/**
+ * 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 declare function decodeTarget(path: string): string | undefined;
+/**
+ * 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 declare function resolveFrom(documentPath: string, target: string): string | undefined;