@dogsbay/format-vitepress 0.2.0-beta.131 → 0.2.0-beta.133

package/dist/loaders/load.d.ts

@@ -1,13 +1,32 @@
+/**
+ * VitePress corpus discovery over a {@link Corpus} (no Node): find the project (the folder
+ * holding `.vitepress`), read its config, resolve `srcDir`, list the pages, and build nav. The
+ * CLI runs it over a folder (`folder.ts`), the playground over a map of files.
+ *
+ * Snippet / include resolution and asset-href rewriting are handed to the translator as
+ * closures over the corpus, so the translator itself stays I/O-free and unit-testable.
+ *
+ * Paths are posix and relative to the corpus root. A corpus is someone else's repo: snippets,
+ * includes and `srcDir` stay inside the project, once links resolve (`Corpus.contains`).
+ */
 import type { NavItem } from "@dogsbay/types";
+import type { Corpus } from "@dogsbay/corpus";
 import { type VitePressConfig } from "../config.js";
 import { linkToSlug } from "../nav.js";
 import type { TranslateOptions } from "../translate.js";
 export interface VitepressPageSource {
-    filePath: string;
+    /** The page's file, relative to the corpus root. */
+    path: string;
     slug: string;
 }
+/** An asset directory to mirror, relative to the corpus root (`ImportResult.assetMounts`). */
+export interface VitepressAssetDir {
+    dir: string;
+    into?: string;
+    mediaOnly?: boolean;
+}
 export interface VitepressLoadResult {
-    /** Project root — the directory that CONTAINS `.vitepress`. */
+    /** Project root — the folder that CONTAINS `.vitepress` ("" for the corpus root). */
     root: string;
     /** Content root — `srcDir`, which page slugs are relative to. */
     srcDir: string;
@@ -17,29 +36,33 @@ export interface VitepressLoadResult {
     /** How nav was obtained, for the import summary. */
     navSource: "sidebar" | "directory";
     /** Directories to mirror as assets. */
-    assetDirs: {
-        dir: string;
-        into?: string;
-        mediaOnly?: boolean;
-    }[];
+    assetDirs: VitepressAssetDir[];
     warnings: string[];
 }
 export interface VitepressLoadOptions {
     hrefPrefix?: string;
-    /** Execute the config instead of reading it statically (see config.ts). */
-    evalConfig?: boolean;
+    /**
+     * The config, already read: the CLI's `--eval-config` imports it (Node). Otherwise it is
+     * read statically from the corpus.
+     */
+    config?: VitePressConfig;
+    /** Notes from reading the config (a failed `--eval-config`), kept with the loader's. */
+    warnings?: string[];
 }
-/**
- * `.vitepress/config.*` is the only unambiguous marker. Requiring it is what
- * lets this plugin sit safely in the registry among the other Markdown
- * importers: it cannot claim a plain-Markdown, MkDocs or GitBook corpus.
- */
-export declare function findVitepressDir(source: string): string | undefined;
-export declare function detectVitepress(source: string): boolean;
 /** `guide/install.md` → `guide/install`; `guide/index.md` → `guide/index`. */
 export declare function pathToSlug(relPath: string): string;
-/** Minimal glob → RegExp for `srcExclude` (`**\/*.md`, `todo.md`, `a/*.md`). */
-export declare function globToRegExp(glob: string): RegExp;
+/**
+ * Minimal glob matcher for `srcExclude` (`**\/*.md`, `todo.md`, `a/*.md`, `{a,b}`): `*` and
+ * `?` stay within a path segment, `**\/` is zero or more folders, `**` anything.
+ *
+ * Not a RegExp: the globs come from someone else's config, and a backtracking regex of
+ * `*a*a*a…b` or `**\/**\/…` took over a minute on one path. Matching is memoized over
+ * (glob position, path position), so it is polynomial in both. Returns `{ test }` so a
+ * caller can use it where it used a RegExp.
+ */
+export declare function globToRegExp(glob: string): {
+    test(path: string): boolean;
+};
 /**
  * Extract a `#region` from a file.
  *
@@ -56,7 +79,7 @@ export declare function extractRegion(content: string, region: string): string |
  */
 export declare function dedent(text: string): string;
 /** Per-page translate options (snippet resolution + asset rewriting). */
-export declare function translateOptionsFor(page: VitepressPageSource, srcDir: string, root: string, warnings: string[]): TranslateOptions;
+export declare function translateOptionsFor(corpus: Corpus, page: VitepressPageSource, srcDir: string, root: string): TranslateOptions;
 /**
  * Translate options anchored at `dir`.
  *
@@ -66,8 +89,13 @@ export declare function translateOptionsFor(page: VitepressPageSource, srcDir: s
  * same-named sibling existed next to the page — silently, with no ledger
  * entry — and dropped the include entirely when it did not.
  */
-export declare function optionsForDir(dir: string, srcDir: string, root: string, warnings: string[]): TranslateOptions;
-export declare function loadVitepress(source: string, opts?: VitepressLoadOptions): Promise<VitepressLoadResult>;
+export declare function optionsForDir(corpus: Corpus, listed: Set<string>, dir: string, srcDir: string, root: string): TranslateOptions;
+/** The VitePress project in `corpus`: its root and config file, or undefined. */
+export declare function findVitepressProject(corpus: Corpus): {
+    root: string;
+    configPath: string;
+} | undefined;
+export declare function loadVitepressCorpus(corpus: Corpus, opts?: VitepressLoadOptions): VitepressLoadResult;
 /** Used only by the fallback nav, where no page has been parsed yet. */
 export declare function titleFromSlug(slug: string): string;
 export { linkToSlug };

package/dist/loaders/load.js

@@ -1,77 +1,13 @@
-/**
- * VitePress corpus discovery: locate `.vitepress`, read the config, resolve
- * `srcDir`, enumerate pages, and build nav.
- *
- * The only module in this package that touches the filesystem. Snippet /
- * include resolution and asset-href rewriting are handed to the translator as
- * closures so the translator itself stays I/O-free and unit-testable.
- */
-import { existsSync, readdirSync, readFileSync, realpathSync, statSync } from "node:fs";
-import { dirname, join, relative, resolve, sep } from "node:path";
-import { findConfigFile, readConfig, evalConfig } from "../config.js";
+import { dirOf, isPlainPath, joinPath, normalizePath, vitepressConfigPath, vitepressPage, vitepressRoots, within } from "@dogsbay/detect";
+import { parseConfig } from "../config.js";
 import { buildNav, navFromSlugs, linkToSlug } from "../nav.js";
-const SKIP_DIRS = new Set([
-    ".vitepress",
-    "node_modules",
-    "public",
-    "dist",
-    ".git",
-    "cache",
-    ".cache",
-]);
-// ── Detection ─────────────────────────────────────────────────────────────
-/**
- * `.vitepress/config.*` is the only unambiguous marker. Requiring it is what
- * lets this plugin sit safely in the registry among the other Markdown
- * importers: it cannot claim a plain-Markdown, MkDocs or GitBook corpus.
- */
-export function findVitepressDir(source) {
-    const candidates = [source, join(source, "docs"), join(source, "site"), join(source, "website")];
-    for (const dir of candidates) {
-        const vp = join(dir, ".vitepress");
-        if (existsSync(vp) && findConfigFile(vp))
-            return vp;
-    }
-    // One level down, for monorepos whose docs live in an unconventional dir.
-    let entries = [];
-    try {
-        entries = readdirSync(source);
-    }
-    catch {
-        return undefined;
-    }
-    for (const name of entries) {
-        if (name.startsWith(".") || name === "node_modules")
-            continue;
-        const vp = join(source, name, ".vitepress");
-        try {
-            if (statSync(vp).isDirectory() && findConfigFile(vp))
-                return vp;
-        }
-        catch {
-            /* not a directory */
-        }
-    }
-    return undefined;
-}
-export function detectVitepress(source) {
-    try {
-        if (!existsSync(source) || !statSync(source).isDirectory())
-            return false;
-    }
-    catch {
-        return false;
-    }
-    return findVitepressDir(source) !== undefined;
-}
 // ── Slugs ─────────────────────────────────────────────────────────────────
 /** `guide/install.md` → `guide/install`; `guide/index.md` → `guide/index`. */
 export function pathToSlug(relPath) {
     return relPath.replace(/\\/g, "/").replace(/\.md$/i, "");
 }
-/** Minimal glob → RegExp for `srcExclude` (`**\/*.md`, `todo.md`, `a/*.md`). */
-export function globToRegExp(glob) {
-    let out = "";
+function globTokens(glob) {
+    const out = [];
     for (let i = 0; i < glob.length; i++) {
         const c = glob[i];
         if (c === "*") {
@@ -79,84 +15,96 @@ export function globToRegExp(glob) {
                 // `**` followed by a separator matches zero or more leading
                 // directories; a bare `**` matches anything, separators included.
                 if (glob[i + 2] === "/") {
-                    out += "(?:.*/)?";
+                    // A run of `**/**/` matches what one does
+                    if (out[out.length - 1]?.t !== "**/")
+                        out.push({ t: "**/" });
                     i += 2;
                 }
                 else {
-                    out += ".*";
+                    out.push({ t: "**" });
                     i += 1;
                 }
                 continue;
             }
-            out += "[^/]*";
+            if (out[out.length - 1]?.t !== "*")
+                out.push({ t: "*" });
             continue;
         }
         if (c === "?") {
-            out += "[^/]";
+            out.push({ t: "?" });
             continue;
         }
         // Brace alternation — picomatch (what VitePress uses) supports it.
-        // Escaping it to a literal made `**/*.{draft,tmp}.md` match nothing, so
+        // Treating it as literal made `**/*.{draft,tmp}.md` match nothing, so
         // an author's srcExclude silently failed to exclude anything.
         if (c === "{") {
             const close = glob.indexOf("}", i);
             if (close > i) {
-                const alts = glob
-                    .slice(i + 1, close)
-                    .split(",")
-                    .map((a) => a.replace(/[.+^${}()|[\]\\*?]/g, "\\$&"));
-                out += `(?:${alts.join("|")})`;
+                out.push({ t: "alt", opts: glob.slice(i + 1, close).split(",") });
                 i = close;
                 continue;
             }
         }
-        out += /[.+^${}()|[\]\\]/.test(c) ? `\\${c}` : c;
+        out.push({ t: "lit", c });
     }
-    return new RegExp(`^${out}$`);
+    return out;
 }
-// ── Page walk ─────────────────────────────────────────────────────────────
-function walkMarkdown(dir, srcDir, out, seen = new Set()) {
-    // Guard on the REAL path. A directory symlink pointing back up the tree
-    // (`docs/guide/loop -> docs`) is not infinite — the OS stops it with ELOOP —
-    // but it multiplies the corpus: a one-page tree walked as 41 pages, each a
-    // duplicate import of the same file under a 447-character slug.
-    let real;
-    try {
-        real = realpathSync(dir);
-    }
-    catch {
-        return;
-    }
-    if (seen.has(real))
-        return;
-    seen.add(real);
-    let entries;
-    try {
-        entries = readdirSync(dir);
-    }
-    catch {
-        return;
-    }
-    for (const name of entries) {
-        const full = join(dir, name);
-        let st;
-        try {
-            st = statSync(full);
-        }
-        catch {
-            continue;
-        }
-        if (st.isDirectory()) {
-            if (SKIP_DIRS.has(name) || name.startsWith("."))
-                continue;
-            walkMarkdown(full, srcDir, out, seen);
-            continue;
-        }
-        if (!name.toLowerCase().endsWith(".md"))
-            continue;
-        const rel = relative(srcDir, full).replace(/\\/g, "/");
-        out.push({ filePath: full, slug: pathToSlug(rel) });
-    }
+/**
+ * Minimal glob matcher for `srcExclude` (`**\/*.md`, `todo.md`, `a/*.md`, `{a,b}`): `*` and
+ * `?` stay within a path segment, `**\/` is zero or more folders, `**` anything.
+ *
+ * Not a RegExp: the globs come from someone else's config, and a backtracking regex of
+ * `*a*a*a…b` or `**\/**\/…` took over a minute on one path. Matching is memoized over
+ * (glob position, path position), so it is polynomial in both. Returns `{ test }` so a
+ * caller can use it where it used a RegExp.
+ */
+export function globToRegExp(glob) {
+    const toks = globTokens(glob);
+    return {
+        test(path) {
+            const n = path.length;
+            const memo = new Uint8Array((toks.length + 1) * (n + 1)); // 0 unknown, 1 no, 2 yes
+            const match = (g, i) => {
+                if (g === toks.length)
+                    return i === n;
+                const slot = g * (n + 1) + i;
+                if (memo[slot])
+                    return memo[slot] === 2;
+                const tok = toks[g];
+                let ok = false;
+                switch (tok.t) {
+                    case "lit":
+                        ok = path[i] === tok.c && match(g + 1, i + 1);
+                        break;
+                    case "?":
+                        ok = i < n && path[i] !== "/" && match(g + 1, i + 1);
+                        break;
+                    case "*":
+                        ok = match(g + 1, i);
+                        for (let j = i; !ok && j < n && path[j] !== "/"; j++)
+                            ok = match(g + 1, j + 1);
+                        break;
+                    case "**":
+                        ok = match(g + 1, i);
+                        for (let j = i; !ok && j < n; j++)
+                            ok = match(g + 1, j + 1);
+                        break;
+                    case "**/":
+                        ok = match(g + 1, i);
+                        for (let j = i; !ok && j < n; j++)
+                            if (path[j] === "/")
+                                ok = match(g + 1, j + 1);
+                        break;
+                    case "alt":
+                        ok = tok.opts.some((o) => path.startsWith(o, i) && match(g + 1, i + o.length));
+                        break;
+                }
+                memo[slot] = ok ? 2 : 1;
+                return ok;
+            };
+            return match(0, 0);
+        },
+    };
 }
 // ── Snippet / include resolution ──────────────────────────────────────────
 /**
@@ -221,76 +169,42 @@ export function dedent(text) {
         return text;
     return lines.map((l) => l.slice(min)).join("\n");
 }
-/**
- * Is `target` genuinely inside `root`?
- *
- * `relative()` alone is a STRING computation — it does not follow symlinks,
- * but `readFileSync` does. A single symlink under the docs tree
- * (`docs/guide/link -> /tmp`) turned a `<<<` reference into arbitrary file
- * read driven by document content. Both ends are resolved to their real paths
- * first, and the boundary is checked on a path SEGMENT so that a sibling
- * directory sharing a prefix (`/a/docs` vs `/a/docs-secret`) cannot pass.
- */
-function isInside(root, target) {
-    let realRoot;
-    let realTarget;
-    try {
-        realRoot = realpathSync(root);
-    }
-    catch {
-        realRoot = root;
-    }
-    try {
-        realTarget = realpathSync(target);
-    }
-    catch {
-        // Not created yet / broken link — fall back to the lexical path, which is
-        // still checked below.
-        realTarget = target;
-    }
-    if (realTarget === realRoot)
-        return true;
-    const rel = relative(realRoot, realTarget);
-    if (!rel)
-        return true;
-    return rel !== ".." && !rel.startsWith(`..${sep}`);
+/** Is `path` inside the project `root`, once links resolve? */
+function inProject(corpus, listed, path, root) {
+    if (path === undefined || !within(path, root))
+        return false;
+    // A listed file is checked through its real path: a symlink under the docs tree
+    // (`docs/guide/link -> /tmp`) must not turn a `<<<` reference into a read outside it.
+    return !corpus.contains || !listed.has(path) || corpus.contains(path, root);
+}
+/** `@/x` and `/x` are relative to `srcDir` (VitePress's alias); anything else to `dir`. */
+function snippetPath(spec, dir, srcDir) {
+    const target = spec.startsWith("@/")
+        ? joinPath(srcDir, spec.slice(2))
+        : spec.startsWith("/")
+            ? joinPath(srcDir, spec.slice(1))
+            : joinPath(dir, spec);
+    return normalizePath(target);
 }
 /**
  * Build the `readSnippet` closure for one page.
  *
- * `@/` is VitePress's alias for `srcDir`; everything else resolves relative to
- * the page's own directory. A path escaping `root` is refused — a migration
- * should not read files outside the project it was pointed at.
+ * A path escaping `root` is refused — a migration should not read files outside the project
+ * it was pointed at.
  */
-function makeReadSnippet(pageDir, srcDir, root, warnings) {
+function makeReadSnippet(corpus, listed, pageDir, srcDir, root) {
     return (req) => {
-        const raw = req.path;
-        const abs = raw.startsWith("@/")
-            ? resolve(srcDir, raw.slice(2))
-            : raw.startsWith("/")
-                ? resolve(srcDir, raw.slice(1))
-                : resolve(pageDir, raw);
-        if (!isInside(root, abs)) {
-            warnings.push(`refused to read "${raw}" — outside the project root`);
-            return undefined;
-        }
-        if (!existsSync(abs))
-            return undefined;
-        let content;
-        try {
-            content = readFileSync(abs, "utf-8");
-        }
-        catch {
+        const path = snippetPath(req.path, pageDir, srcDir);
+        if (!inProject(corpus, listed, path, root))
+            return { missing: "refused to read: outside the project root" };
+        const content = corpus.text(path);
+        if (content === undefined)
             return undefined;
-        }
-        const rel = relative(root, abs);
         if (!req.region)
             return content;
         const extracted = extractRegion(content, req.region);
-        if (extracted === undefined) {
-            warnings.push(`region "#${req.region}" not found in ${rel}`);
-            return undefined;
-        }
+        if (extracted === undefined)
+            return { missing: `region "#${req.region}" not found in ${root ? path.slice(root.length + 1) : path}` };
         return extracted;
     };
 }
@@ -309,16 +223,15 @@ function makeAssetHref(pageDir, srcDir) {
             return src;
         if (src.startsWith("/"))
             return `/_assets${src}`;
-        const abs = resolve(pageDir, src);
-        const rel = relative(srcDir, abs).replace(/\\/g, "/");
-        if (rel.startsWith(".."))
+        const path = normalizePath(joinPath(pageDir, src));
+        if (path === undefined || !within(path, srcDir))
             return src;
-        return `/_assets/pages/${rel}`;
+        return `/_assets/pages/${srcDir ? path.slice(srcDir.length + 1) : path}`;
     };
 }
 /** Per-page translate options (snippet resolution + asset rewriting). */
-export function translateOptionsFor(page, srcDir, root, warnings) {
-    return optionsForDir(dirname(page.filePath), srcDir, root, warnings);
+export function translateOptionsFor(corpus, page, srcDir, root) {
+    return optionsForDir(corpus, new Set(corpus.paths), dirOf(page.path), srcDir, root);
 }
 /**
  * Translate options anchored at `dir`.
@@ -329,57 +242,59 @@ export function translateOptionsFor(page, srcDir, root, warnings) {
  * same-named sibling existed next to the page — silently, with no ledger
  * entry — and dropped the include entirely when it did not.
  */
-export function optionsForDir(dir, srcDir, root, warnings) {
+export function optionsForDir(corpus, listed, dir, srcDir, root) {
     return {
-        readSnippet: makeReadSnippet(dir, srcDir, root, warnings),
+        readSnippet: makeReadSnippet(corpus, listed, dir, srcDir, root),
         assetHref: makeAssetHref(dir, srcDir),
         resolveDir: (spec) => {
-            const abs = spec.startsWith("@/")
-                ? resolve(srcDir, spec.slice(2))
-                : spec.startsWith("/")
-                    ? resolve(srcDir, spec.slice(1))
-                    : resolve(dir, spec);
-            return isInside(root, abs) ? dirname(abs) : undefined;
+            const path = snippetPath(spec, dir, srcDir);
+            return inProject(corpus, listed, path, root) ? dirOf(path) : undefined;
         },
-        optionsForDir: (nextDir) => optionsForDir(nextDir, srcDir, root, warnings),
+        optionsForDir: (nextDir) => optionsForDir(corpus, listed, nextDir, srcDir, root),
     };
 }
 // ── Load ──────────────────────────────────────────────────────────────────
-export async function loadVitepress(source, opts = {}) {
-    const hrefPrefix = opts.hrefPrefix ?? "";
-    const warnings = [];
-    const vitepressDir = findVitepressDir(source);
-    if (!vitepressDir) {
-        throw new Error(`No .vitepress/config.* found under ${source}`);
-    }
-    const root = dirname(vitepressDir);
-    const configPath = findConfigFile(vitepressDir);
-    if (!configPath)
-        throw new Error(`No config file in ${vitepressDir}`);
-    let config;
-    if (opts.evalConfig) {
-        try {
-            config = await evalConfig(configPath);
-        }
-        catch (err) {
-            const msg = err instanceof Error ? err.message : String(err);
-            warnings.push(`--eval-config failed (${msg}); falling back to static reading`);
-            config = readConfig(configPath);
-        }
-    }
-    else {
-        config = readConfig(configPath);
+/** The VitePress project in `corpus`: its root and config file, or undefined. */
+export function findVitepressProject(corpus) {
+    for (const root of vitepressRoots(corpus.paths)) {
+        const configPath = vitepressConfigPath(corpus.paths, root);
+        if (configPath)
+            return { root, configPath };
     }
+    return undefined;
+}
+export function loadVitepressCorpus(corpus, opts = {}) {
+    const hrefPrefix = opts.hrefPrefix ?? "";
+    const warnings = [...(opts.warnings ?? [])];
+    const project = findVitepressProject(corpus);
+    if (!project)
+        throw new Error("No .vitepress/config.* found");
+    const { root } = project;
+    const config = opts.config ?? parseConfig(corpus.text(project.configPath) ?? "", project.configPath);
     for (const u of config.unresolved) {
         warnings.push(`config: could not read ${u}`);
     }
-    const srcDir = config.srcDir ? resolve(root, config.srcDir) : root;
-    if (!existsSync(srcDir)) {
+    // `srcDir` comes from the repo being imported: it may not lead out of the project.
+    const srcDir = config.srcDir ? normalizePath(joinPath(root, config.srcDir)) : root;
+    if (srcDir === undefined || !within(srcDir, root)) {
+        throw new Error(`srcDir "${config.srcDir}" is outside the project`);
+    }
+    const listed = new Set(corpus.paths);
+    if (srcDir !== root && !corpus.paths.some((p) => within(p, srcDir))) {
         throw new Error(`srcDir "${config.srcDir}" does not exist (resolved to ${srcDir})`);
     }
-    // Pages.
+    // Pages: the visible .md files under srcDir that stay in the project once links resolve.
     const found = [];
-    walkMarkdown(srcDir, srcDir, found);
+    for (const path of corpus.paths) {
+        if (!within(path, srcDir) || path === srcDir)
+            continue;
+        const rel = srcDir ? path.slice(srcDir.length + 1) : path;
+        if (!vitepressPage(rel))
+            continue;
+        if (!inProject(corpus, listed, path, root))
+            continue;
+        found.push({ path, slug: pathToSlug(rel) });
+    }
     const excludes = (config.srcExclude ?? []).map(globToRegExp);
     const rewrites = config.rewrites ?? {};
     // VitePress supports dynamic route params in a rewrite key
@@ -391,23 +306,32 @@ export async function loadVitepress(source, opts = {}) {
             warnings.push(`rewrite rule "${key}" uses dynamic parameters, which are not expanded — pages under it keep their source paths`);
         }
     }
+    const rel = (path) => (srcDir ? path.slice(srcDir.length + 1) : path);
     const pages = [];
     const bySlug = new Map();
     for (const p of found) {
         const relMd = `${p.slug}.md`;
         if (excludes.some((re) => re.test(relMd) || re.test(p.slug)))
             continue;
-        // `rewrites` remaps a SOURCE path to the served path.
-        const rewritten = rewrites[relMd] ?? rewrites[p.slug];
-        const page = rewritten ? { ...p, slug: pathToSlug(rewritten) } : p;
+        // `rewrites` remaps a SOURCE path to the served path. It comes from the repo too: a
+        // rewrite that leads out of the content root is not a slug.
+        // Own string keys only: a page named `constructor.md` read Object.prototype's.
+        const own = (k) => (Object.hasOwn(rewrites, k) && typeof rewrites[k] === "string" ? rewrites[k] : undefined);
+        const rewritten = own(relMd) ?? own(p.slug);
+        const normalized = rewritten === undefined ? undefined : normalizePath(rewritten);
+        const target = normalized && isPlainPath(normalized) ? normalized : undefined;
+        if (rewritten !== undefined && !target) {
+            warnings.push(`rewrite of ${relMd} to "${rewritten}" leads out of the site or is not a plain path — kept its source path`);
+        }
+        const page = target ? { ...p, slug: pathToSlug(target) } : p;
         // Two files landing on one slug means a page is DROPPED by the exporter —
         // the run still says "Imported N pages" and one of them silently isn't
         // there. Name both sources; a migration that loses a page must say so.
         const prior = bySlug.get(page.slug);
         if (prior) {
-            warnings.push(`slug collision "${page.slug}": ${relative(srcDir, prior)} and ${relative(srcDir, page.filePath)} — only one survives`);
+            warnings.push(`slug collision "${page.slug}": ${rel(prior)} and ${rel(page.path)} — only one survives`);
         }
-        bySlug.set(page.slug, page.filePath);
+        bySlug.set(page.slug, page.path);
         pages.push(page);
     }
     pages.sort((a, b) => a.slug.localeCompare(b.slug));
@@ -426,11 +350,12 @@ export async function loadVitepress(source, opts = {}) {
         navSource = "directory";
     }
     const assetDirs = [];
-    const publicDir = join(root, "public");
-    if (existsSync(publicDir))
+    const hasDir = (dir) => corpus.paths.some((p) => within(p, dir) && p !== dir);
+    const publicDir = joinPath(root, "public");
+    if (hasDir(publicDir))
         assetDirs.push({ dir: publicDir });
-    const vpPublic = join(vitepressDir, "public");
-    if (existsSync(vpPublic))
+    const vpPublic = joinPath(root, ".vitepress/public");
+    if (hasDir(vpPublic))
         assetDirs.push({ dir: vpPublic });
     assetDirs.push({ dir: srcDir, into: "pages", mediaOnly: true });
     return { root, srcDir, config, pages, nav, navSource, assetDirs, warnings };