@dogsbay/format-gitbook 0.2.0-beta.130 → 0.2.0-beta.131

package/README.md

@@ -0,0 +1,23 @@
+# @dogsbay/format-gitbook
+
+GitBook (Git Sync) import for Dogsbay: the `{% %}` blocks translated to Dogsbay Markdown,
+`SUMMARY.md` as the navigation, `.gitbook.yaml` read as data. Nothing in the repository is run.
+
+| Entry | For |
+|---|---|
+| `@dogsbay/format-gitbook/migrate` | The browser: a corpus as a map of files → a Dogsbay project as a map of files. No Node |
+| `@dogsbay/format-gitbook` | The parts, with no Node: `parseGitbook`, `gitbookToDogsbayMd`, `importGitbookCorpus`, `gitbookProject` |
+| `@dogsbay/format-gitbook/cli` | Node: the `dogsbay` CLI's format plugin, and a folder as a corpus |
+
+```ts
+import { migrate } from "@dogsbay/format-gitbook/migrate";
+const { files, ledger, redirects } = await migrate({ files: corpus, siteName: "My Docs" });
+```
+
+The CLI's `dogsbay migrate-gitbook` runs the same import and project writer, so both give the
+same project. Find the corpus in a repository with `@dogsbay/detect`. See
+[Migrating from GitBook](https://github.com/dogsbay/dogsbay/blob/main/docs/migrating-gitbook.md).
+
+## License
+
+MIT

package/dist/cli.d.ts

@@ -1,14 +1,11 @@
-import type { FormatPlugin, ExportPage, NavItem } from "@dogsbay/types";
-export interface GitbookImportResult {
-    pages: ExportPage[];
-    nav: NavItem[];
-    redirects: Record<string, string>;
-    spaces: string[];
-    /** Docs roots to mirror non-`.md` assets from (dir + slug prefix). */
-    assetRoots: {
-        dir: string;
-        prefix: string;
-    }[];
-}
-export declare function importGitbook(source: string, opts: Record<string, unknown>): Promise<GitbookImportResult>;
+import type { FormatPlugin } from "@dogsbay/types";
+import { type GitbookImportResult } from "./import.js";
+import { type FolderCorpus } from "./loaders/folder.js";
+export { readFolder, readGitbookFolder, type FolderCorpus } from "./loaders/folder.js";
+export { gitbookProject, type GitbookProject, type GitbookProjectOptions } from "./project.js";
+export type { GitbookImportResult } from "./import.js";
+/** Import a GitBook folder. Prints a one-line summary of the ledger, as the CLI always has. */
+export declare function importGitbook(source: string, opts: Record<string, unknown>): Promise<GitbookImportResult & {
+    corpus: FolderCorpus;
+}>;
 export declare const plugin: FormatPlugin;

package/dist/cli.js

@@ -1,78 +1,38 @@
 /**
- * FormatPlugin for GitBook as a source format.
+ * FormatPlugin for GitBook as a source format (Node: reads a folder).
  *
- * Orchestrates: detect corpus → loadGitbook (config + SUMMARY + pages) →
- * translate each page (parseGitbook) → assemble ExportPage[] + NavItem[].
- * Fragments (`.gitbook/includes/*`) are emitted with `fragment: true` so
- * the CLI writes them as `{% include %}` targets, not routable pages —
- * the same fragment model AsciiBinder/Antora use.
+ * A folder becomes a {@link Corpus} (`loaders/folder.ts`), and the import itself is
+ * `importGitbookCorpus`, the same one the browser entry runs. Fragments
+ * (`.gitbook/includes/*`) come back with `fragment: true` so the CLI writes them as
+ * `{% include %}` targets, not routable pages.
  *
- * The redirects from `.gitbook.yaml` are surfaced on the result so
- * `migrate-gitbook` can carry them into the site config.
+ * The redirects from `.gitbook.yaml` are surfaced on the result so `migrate-gitbook` can
+ * carry them into the site.
  */
-import { existsSync, readFileSync } from "node:fs";
-import { basename } from "node:path";
-import { extractHeadings } from "@dogsbay/format-dogsbay-md";
-import { parseGitbook } from "./parse.js";
-import { loadGitbook, detectGitbook } from "./loaders/load.js";
-function prettify(slug) {
-    return slug
-        .split(/[-_/]/)
-        .filter(Boolean)
-        .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
-        .join(" ");
-}
+import { existsSync } from "node:fs";
+import { importGitbookCorpus } from "./import.js";
+import { detectGitbook, readGitbookFolder } from "./loaders/folder.js";
+export { readFolder, readGitbookFolder } from "./loaders/folder.js";
+export { gitbookProject } from "./project.js";
+/** Import a GitBook folder. Prints a one-line summary of the ledger, as the CLI always has. */
 export async function importGitbook(source, opts) {
     if (!existsSync(source)) {
         throw new Error(`Source directory not found: ${source}`);
     }
     const space = typeof opts.space === "string" ? opts.space : undefined;
-    const hrefPrefix = typeof opts.hrefPrefix === "string" ? opts.hrefPrefix : "";
-    const { pages: pageSources, nav, redirects, spaces, assetRoots } = loadGitbook(source, {
+    const corpus = readGitbookFolder(source, space);
+    const result = importGitbookCorpus(corpus, {
         space,
-        hrefPrefix,
+        hrefPrefix: typeof opts.hrefPrefix === "string" ? opts.hrefPrefix : "",
     });
-    const pages = [];
-    let failed = 0;
-    let ledgerTotal = 0;
-    for (const ps of pageSources) {
-        try {
-            const content = readFileSync(ps.filePath, "utf-8");
-            const { tree, frontmatter, body, ledger } = parseGitbook(content);
-            ledgerTotal += ledger.length;
-            const headings = extractHeadings(tree);
-            const h1 = headings.find((h) => h.depth === 1);
-            // A whitespace-only source `title:` must not win — `.trim()` so a
-            // blank falls through to the H1 / slug (review #6).
-            const fmTitle = typeof frontmatter.title === "string" && frontmatter.title.trim()
-                ? frontmatter.title
-                : undefined;
-            const title = fmTitle || h1?.text || prettify(basename(ps.slug));
-            pages.push({
-                slug: ps.slug,
-                title,
-                tree,
-                headings,
-                frontmatter,
-                meta: {},
-                ...(ps.fragment ? { fragment: true } : {}),
-                // Translated Dogsbay-MD body — what migrate-gitbook writes to disk.
-                bodyMarkdown: body,
-            });
-        }
-        catch (err) {
-            failed += 1;
-            const msg = err instanceof Error ? err.message : String(err);
-            console.warn(`gitbook import: failed to convert ${ps.filePath} (slug "${ps.slug}"), skipping: ${msg}`);
-        }
-    }
-    if (failed > 0) {
-        console.warn(`gitbook import: ${failed} of ${pageSources.length} page(s) failed and were skipped`);
+    for (const e of result.ledger.filter((e) => e.code === "page-failed")) {
+        console.warn(`gitbook import: failed to convert ${e.file}, skipping: ${e.message}`);
     }
-    if (ledgerTotal > 0) {
-        console.warn(`gitbook import: ${ledgerTotal} construct(s) mapped with caveats (see per-page ledger)`);
+    const mapped = result.ledger.filter((e) => e.code === "unmapped-construct").length;
+    if (mapped > 0) {
+        console.warn(`gitbook import: ${mapped} construct(s) mapped with caveats (see the ledger)`);
     }
-    return { pages, nav, redirects, spaces, assetRoots };
+    return { ...result, corpus };
 }
 export const plugin = {
     name: "gitbook",
@@ -87,11 +47,11 @@ export const plugin = {
     ],
     exportOptions: [],
     async import(source, opts) {
-        const { pages, nav, assetRoots } = await importGitbook(source, opts);
-        // Slugs are relative to the space's docs root (`.gitbook.yaml` `root:`,
-        // or the `--space` folder), so references resolve there: a relative
-        // `:::openapi` spec or include looked up from the repo root missed.
-        const only = assetRoots.length === 1 && assetRoots[0].prefix === "" ? assetRoots[0].dir : undefined;
-        return { pages, nav, ...(only ? { contentRoot: only } : {}) };
+        const { pages, nav, assetRoots, ledger, corpus } = await importGitbook(source, opts);
+        // Slugs are relative to the space's docs root (`.gitbook.yaml` `root:`, or the `--space`
+        // folder), so references resolve there: a relative `:::openapi` spec or include looked up
+        // from the repo root missed.
+        const only = assetRoots.length === 1 && assetRoots[0].prefix === "" ? corpus.absolute(assetRoots[0].dir) : undefined;
+        return { pages, nav, ledger, ...(only ? { contentRoot: only } : {}) };
     },
 };

package/dist/corpus.d.ts

@@ -0,0 +1,18 @@
+export interface Corpus {
+    /** Every file, posix, relative to the corpus root; plain paths only (`isPlainPath`). */
+    paths: string[];
+    /** The file's text, or undefined when it is not in the corpus. */
+    text(path: string): string | undefined;
+    /**
+     * Does `path` still lie inside the folder `dir` once links resolve? A folder corpus answers
+     * (a symlink in the docs root must not bring in the repo's `.env` or `.git`); a map of files
+     * has no links and leaves it out.
+     */
+    contains?(path: string, dir: string): boolean;
+}
+export type CorpusFiles = Map<string, string | Uint8Array>;
+/**
+ * A corpus over a map of files; bytes are read as UTF-8. A key that is not a plain path
+ * (`../x`, `/etc/x`, `a/./b`, a backslash) is left out: the keys come from someone else's repo.
+ */
+export declare function corpusFromMap(files: CorpusFiles): Corpus;

package/dist/corpus.js

@@ -0,0 +1,26 @@
+/**
+ * A corpus as the importer sees it: its file paths (posix, relative to the corpus root) and a
+ * way to read one as text. The CLI builds one from a folder (`loaders/folder.ts`, which also
+ * keeps symlinks inside it); the browser builds one from a map of files (`corpusFromMap`).
+ * Assets are never read through it: the project lists them as copies, and each host copies
+ * the bytes its own way.
+ */
+import { isPlainPath } from "@dogsbay/detect";
+/**
+ * A corpus over a map of files; bytes are read as UTF-8. A key that is not a plain path
+ * (`../x`, `/etc/x`, `a/./b`, a backslash) is left out: the keys come from someone else's repo.
+ */
+export function corpusFromMap(files) {
+    const decoder = new TextDecoder();
+    const paths = [...files.keys()].filter(isPlainPath).sort();
+    const listed = new Set(paths);
+    return {
+        paths,
+        text(path) {
+            if (!listed.has(path))
+                return undefined;
+            const v = files.get(path);
+            return v === undefined ? undefined : typeof v === "string" ? v : decoder.decode(v);
+        },
+    };
+}

package/dist/import.d.ts

@@ -0,0 +1,27 @@
+/**
+ * GitBook corpus → pages, nav, redirects and a ledger, over a {@link Corpus} (no Node, quiet).
+ * The one import: the plugin's `import()` (`convert`, `site build`), `migrate-gitbook` and
+ * the browser (`./migrate`) all run it.
+ *
+ * Fragments (`.gitbook/includes/*`) come out with `fragment: true`, so a writer emits them as
+ * `{% include %}` targets, not routable pages (the fragment model AsciiBinder/Antora use).
+ */
+import type { ExportPage, ImportLedgerEntry, NavItem } from "@dogsbay/types";
+import type { Corpus } from "./corpus.js";
+import { type GitbookAssetRoot } from "./loaders/load.js";
+export interface GitbookImportOptions {
+    /** Import one space (a subfolder with a SUMMARY.md) of a multi-space repo. */
+    space?: string;
+    /** URL prefix applied to nav hrefs. */
+    hrefPrefix?: string;
+}
+export interface GitbookImportResult {
+    pages: ExportPage[];
+    nav: NavItem[];
+    redirects: Record<string, string>;
+    spaces: string[];
+    /** Docs roots to mirror non-`.md` assets from (corpus-relative folder + slug prefix). */
+    assetRoots: GitbookAssetRoot[];
+    ledger: ImportLedgerEntry[];
+}
+export declare function importGitbookCorpus(corpus: Corpus, opts?: GitbookImportOptions): GitbookImportResult;

package/dist/import.js

@@ -0,0 +1,62 @@
+import { extractHeadings } from "@dogsbay/format-dogsbay-md/browser";
+import { loadGitbookCorpus, prettify } from "./loaders/load.js";
+import { followRenames } from "./links.js";
+import { parseGitbook } from "./parse.js";
+export function importGitbookCorpus(corpus, opts = {}) {
+    const { pages: sources, nav, redirects, spaces, assetRoots } = loadGitbookCorpus(corpus, opts);
+    const pages = [];
+    const ledger = [];
+    // A page written under another file name (README.md → index.md, a landing page → index.md):
+    // links to it follow the rename.
+    const renames = new Map();
+    for (const ps of sources) {
+        if (ps.fragment)
+            continue;
+        const name = `${ps.slug.slice(ps.slug.lastIndexOf("/") + 1)}.md`;
+        if (name !== ps.path.slice(ps.path.lastIndexOf("/") + 1))
+            renames.set(ps.path, name);
+    }
+    for (const ps of sources) {
+        try {
+            const content = corpus.text(ps.path);
+            if (content === undefined)
+                throw new Error("the file could not be read");
+            const { tree, frontmatter, body, ledger: notes, bodyLine } = parseGitbook(content, { links: (body) => followRenames(body, ps.path, renames) });
+            for (const n of notes) {
+                ledger.push({
+                    file: ps.path,
+                    ...(n.line ? { line: n.line + bodyLine - 1 } : {}),
+                    severity: "warning",
+                    code: "unmapped-construct",
+                    message: `${n.construct}: ${n.note}`,
+                });
+            }
+            const headings = extractHeadings(tree);
+            const h1 = headings.find((h) => h.depth === 1);
+            // A whitespace-only source `title:` must not win — `.trim()` so a blank falls through
+            // to the H1 / slug (review #6).
+            const fmTitle = typeof frontmatter.title === "string" && frontmatter.title.trim() ? frontmatter.title : undefined;
+            const title = fmTitle || h1?.text || prettify(ps.slug.slice(ps.slug.lastIndexOf("/") + 1));
+            pages.push({
+                slug: ps.slug,
+                title,
+                tree,
+                headings,
+                frontmatter,
+                meta: {},
+                ...(ps.fragment ? { fragment: true } : {}),
+                // Translated Dogsbay-MD body — what the project writer writes.
+                bodyMarkdown: body,
+            });
+        }
+        catch (err) {
+            ledger.push({
+                file: ps.path,
+                severity: "warning",
+                code: "page-failed",
+                message: `not converted, skipped: ${err instanceof Error ? err.message : String(err)}`,
+            });
+        }
+    }
+    return { pages, nav, redirects, spaces, assetRoots, ledger };
+}

package/dist/index.d.ts

@@ -2,9 +2,13 @@
  * @dogsbay/format-gitbook — GitBook (Git Sync + legacy gitbook-cli)
  * format plugin. Imports GitBook corpora into TreeNode[] by translating
  * the Git Sync markdown dialect to Dogsbay-MD, then parsing with the
- * canonical dogsbay-md parser.
+ * canonical dogsbay-md parser. No Node in this entry or in `./migrate`;
+ * reading a folder is `./cli`.
  *
  * See plans/format-gitbook.md.
  */
 export { parseGitbook, type ParseGitbookResult } from "./parse.js";
 export { gitbookToDogsbayMd, type TranslateResult, type TranslateLedgerEntry, } from "./translate.js";
+export { corpusFromMap, type Corpus, type CorpusFiles } from "./corpus.js";
+export { importGitbookCorpus, type GitbookImportOptions, type GitbookImportResult } from "./import.js";
+export { gitbookProject, type GitbookProject, type GitbookProjectOptions } from "./project.js";

package/dist/index.js

@@ -2,9 +2,13 @@
  * @dogsbay/format-gitbook — GitBook (Git Sync + legacy gitbook-cli)
  * format plugin. Imports GitBook corpora into TreeNode[] by translating
  * the Git Sync markdown dialect to Dogsbay-MD, then parsing with the
- * canonical dogsbay-md parser.
+ * canonical dogsbay-md parser. No Node in this entry or in `./migrate`;
+ * reading a folder is `./cli`.
  *
  * See plans/format-gitbook.md.
  */
 export { parseGitbook } from "./parse.js";
 export { gitbookToDogsbayMd, } from "./translate.js";
+export { corpusFromMap } from "./corpus.js";
+export { importGitbookCorpus } from "./import.js";
+export { gitbookProject } from "./project.js";

package/dist/links.d.ts

@@ -0,0 +1,4 @@
+/** Corpus path of a page → the file name it is written under, when that differs. */
+export type Renames = Map<string, string>;
+/** Rewrite the page links in `markdown`, a page at corpus path `from`. */
+export declare function followRenames(markdown: string, from: string, renames: Renames): string;

package/dist/links.js

@@ -0,0 +1,64 @@
+/**
+ * Page links that follow a renamed file. The migration writes `README.md` as `index.md`, and a
+ * space's landing page (`structure.readme: intro.md`) as `index.md` too, in the same folder.
+ * A link that named the old file (`guide/README.md`, `../intro.md#setup`) would then name
+ * nothing, so it is rewritten to the new file name; everything else is left as written.
+ *
+ * Text work over the translated Dogsbay MD, before it is parsed, so the written page and the
+ * tree agree. Fenced code and code spans are left alone: a page that SHOWS a link keeps it.
+ */
+import { dirOf, joinPath, normalizePath } from "@dogsbay/detect";
+const FENCE_RE = /^\s*(`{3,}|~{3,})/; // any indent: fences sit inside list items and directives
+/** `](dest)` / `](<dest>)`, a reference definition `[x]: dest`, and `href="dest"`. */
+const DEST_RE = /(\]\(\s*)(<[^>\n]*>|[^)\s]+)|(^ {0,3}\[[^\]\n]+\]:\s*)(<[^>\n]*>|\S+)|(\bhref=")([^"\n]*)(")/g;
+/** Rewrite the page links in `markdown`, a page at corpus path `from`. */
+export function followRenames(markdown, from, renames) {
+    if (renames.size === 0)
+        return markdown;
+    const base = dirOf(from);
+    let fence;
+    return markdown
+        .split("\n")
+        .map((line) => {
+        const f = FENCE_RE.exec(line);
+        if (fence) {
+            if (f && f[1][0] === fence[0] && f[1].length >= fence.length && line.trim() === f[1])
+                fence = undefined;
+            return line;
+        }
+        if (f) {
+            fence = f[1];
+            return line;
+        }
+        // Code spans stay as written: rewrite only the text between them
+        return line
+            .split(/(`+[^`]*`+)/)
+            .map((part, i) => (i % 2 ? part : part.replace(DEST_RE, (m, ...g) => rewrite(m, g, base, renames))))
+            .join("");
+    })
+        .join("\n");
+}
+function rewrite(match, g, base, renames) {
+    const [pre, dest, close] = g[0] !== undefined ? [g[0], g[1], ""] : g[2] !== undefined ? [g[2], g[3], ""] : [g[4], g[5], g[6]];
+    const angled = dest.startsWith("<") && dest.endsWith(">");
+    const raw = angled ? dest.slice(1, -1) : dest;
+    const cut = raw.search(/[#?]/);
+    const file = cut < 0 ? raw : raw.slice(0, cut);
+    // Only relative paths: not a scheme, a site path, or a bare #fragment
+    if (!file || /^[a-z][a-z0-9+.-]*:/i.test(file) || file.startsWith("/"))
+        return match;
+    let decoded = file;
+    try {
+        decoded = decodeURIComponent(file);
+    }
+    catch {
+        // keep it as written
+    }
+    const target = normalizePath(joinPath(base, decoded.replace(/^\.\//, "")));
+    const name = target === undefined ? undefined : renames.get(target);
+    if (name === undefined)
+        return match;
+    const slash = file.lastIndexOf("/");
+    const next = `${file.slice(0, slash + 1)}${name}${cut < 0 ? "" : raw.slice(cut)}`;
+    return `${pre}${angled ? `<${next}>` : next}${close}`;
+}

package/dist/loaders/config.d.ts

@@ -4,5 +4,5 @@ export interface GitbookConfig {
     summary: string;
     redirects: Record<string, string>;
 }
-/** Read `.gitbook.yaml` from `dir` if present; else return defaults. */
-export declare function readGitbookConfig(dir: string): GitbookConfig;
+/** Read a `.gitbook.yaml`'s text (undefined: no file); defaults for anything absent or unreadable. */
+export declare function parseGitbookConfig(text: string | undefined): GitbookConfig;

package/dist/loaders/config.js

@@ -8,24 +8,24 @@
  *     summary: SUMMARY.md    # table of contents, default SUMMARY.md
  *   redirects:
  *     old/path: new/page.md  # old URL → target md file
+ *
+ * js-yaml, not `yaml`: the playground already ships it, and its `load` reads plain data only
+ * (no custom tags), which is all `.gitbook.yaml` holds.
  */
-import { existsSync, readFileSync } from "node:fs";
-import { join } from "node:path";
-import YAML from "yaml";
+import * as yaml from "js-yaml";
 const DEFAULTS = {
     root: "./",
     readme: "README.md",
     summary: "SUMMARY.md",
     redirects: {},
 };
-/** Read `.gitbook.yaml` from `dir` if present; else return defaults. */
-export function readGitbookConfig(dir) {
-    const p = join(dir, ".gitbook.yaml");
-    if (!existsSync(p))
+/** Read a `.gitbook.yaml`'s text (undefined: no file); defaults for anything absent or unreadable. */
+export function parseGitbookConfig(text) {
+    if (text === undefined)
         return { ...DEFAULTS };
     let parsed;
     try {
-        parsed = YAML.parse(readFileSync(p, "utf-8"));
+        parsed = yaml.load(text);
     }
     catch {
         return { ...DEFAULTS };

package/dist/loaders/folder.d.ts

@@ -0,0 +1,31 @@
+import type { Corpus } from "../corpus.js";
+import { type GitbookConfig } from "./config.js";
+import { type GitbookLoadOptions, type GitbookLoadResult } from "./load.js";
+export interface FolderCorpus extends Corpus {
+    /** The folder's absolute path. */
+    root: string;
+    /** A corpus path as an absolute path on disk. */
+    absolute(path: string): string;
+}
+/**
+ * List `dir` (skipping `node_modules` and `.git`) and read files from it on demand. A
+ * directory reached by two names is listed under the first one walked, so `first` names the
+ * folders to walk before the rest (the docs roots): a `docs -> content-src` link must list the
+ * pages under `docs/`, where `root: ./docs/` looks for them.
+ */
+export declare function readFolder(dir: string, maxDepth?: number, first?: string[]): FolderCorpus;
+/** Read `.gitbook.yaml` from `dir` if present; else return defaults. */
+export declare function readGitbookConfig(dir: string): GitbookConfig;
+/**
+ * Does this directory look like a GitBook corpus? The importer's own rule (a marker at the
+ * top, or subfolders with a SUMMARY.md), over the folder's top two levels, through the shared
+ * path detector (so an mdBook's `src/SUMMARY.md` beside `book.toml` is not claimed).
+ */
+export declare function detectGitbook(sourceDir: string): boolean;
+/**
+ * A GitBook folder as a corpus, its docs roots walked first: the spaces and each one's
+ * `.gitbook.yaml` `root:` are read from the top two levels, the same rule the import applies.
+ */
+export declare function readGitbookFolder(sourceDir: string, space?: string): FolderCorpus;
+/** `loadGitbookCorpus` over a folder. */
+export declare function loadGitbook(sourceDir: string, opts?: GitbookLoadOptions): GitbookLoadResult;

package/dist/loaders/folder.js

@@ -0,0 +1,167 @@
+/**
+ * Node only: a folder as a {@link Corpus}, and the CLI's on-disk detector. Everything else in
+ * the loader reads the corpus, so the CLI and the browser import run the same code.
+ *
+ * The walk keeps to the folder once links resolve, and visits each directory once: a symlink
+ * out of the repo read pages from elsewhere, and two links to `.` made the walk branch twice
+ * per level until ELOOP (about 2^40 visits). Text is read only when asked for.
+ */
+import { existsSync, readdirSync, readFileSync, realpathSync, statSync } from "node:fs";
+import { join, sep } from "node:path";
+import { detectGitbook as detectGitbookPaths, gitbookSpaces, isPlainPath, joinPath, normalizePath } from "@dogsbay/detect";
+import { parseGitbookConfig } from "./config.js";
+import { loadGitbookCorpus } from "./load.js";
+/**
+ * List `dir` (skipping `node_modules` and `.git`) and read files from it on demand. A
+ * directory reached by two names is listed under the first one walked, so `first` names the
+ * folders to walk before the rest (the docs roots): a `docs -> content-src` link must list the
+ * pages under `docs/`, where `root: ./docs/` looks for them.
+ */
+export function readFolder(dir, maxDepth = Infinity, first = []) {
+    const paths = [];
+    /** Each listed path's real path, for `contains`. */
+    const reals = new Map();
+    let realRoot;
+    try {
+        realRoot = realpathSync(dir);
+    }
+    catch {
+        realRoot = "";
+    }
+    if (realRoot) {
+        const seen = new Set([realRoot]);
+        const walk = (abs, rel, depth) => {
+            let entries;
+            try {
+                entries = readdirSync(abs).sort();
+            }
+            catch {
+                return;
+            }
+            for (const name of entries) {
+                if (name === "node_modules" || name === ".git")
+                    continue;
+                const full = join(abs, name);
+                const path = rel ? `${rel}/${name}` : name;
+                if (!isPlainPath(path))
+                    continue;
+                let real;
+                let st;
+                try {
+                    real = realpathSync(full);
+                    if (real !== realRoot && !real.startsWith(realRoot + sep))
+                        continue;
+                    st = statSync(real);
+                }
+                catch {
+                    continue;
+                }
+                if (st.isDirectory()) {
+                    if (seen.has(real) || depth + 1 > maxDepth)
+                        continue;
+                    seen.add(real);
+                    walk(full, path, depth + 1);
+                }
+                else if (st.isFile()) {
+                    paths.push(path);
+                    reals.set(path, real);
+                }
+            }
+        };
+        for (const d of first) {
+            if (!d || !isPlainPath(d))
+                continue;
+            let real;
+            try {
+                real = realpathSync(join(dir, d));
+                if (!real.startsWith(realRoot + sep) || seen.has(real) || !statSync(real).isDirectory())
+                    continue;
+            }
+            catch {
+                continue;
+            }
+            seen.add(real);
+            walk(join(dir, d), d, d.split("/").length);
+        }
+        walk(dir, "", 0);
+    }
+    const listed = new Set(paths);
+    const realDirs = new Map();
+    const realDir = (d) => {
+        if (!realDirs.has(d)) {
+            let r;
+            try {
+                r = realpathSync(join(dir, d));
+            }
+            catch {
+                r = undefined;
+            }
+            realDirs.set(d, r);
+        }
+        return realDirs.get(d);
+    };
+    return {
+        root: dir,
+        paths,
+        absolute: (path) => join(dir, path),
+        contains(path, d) {
+            const real = reals.get(path);
+            const root = realDir(d);
+            return !!real && !!root && (real === root || real.startsWith(root + sep));
+        },
+        text(path) {
+            if (!listed.has(path))
+                return undefined;
+            try {
+                return readFileSync(join(dir, path), "utf-8");
+            }
+            catch {
+                return undefined;
+            }
+        },
+    };
+}
+/** Read `.gitbook.yaml` from `dir` if present; else return defaults. */
+export function readGitbookConfig(dir) {
+    const p = join(dir, ".gitbook.yaml");
+    return parseGitbookConfig(existsSync(p) ? readFileSync(p, "utf-8") : undefined);
+}
+/**
+ * Does this directory look like a GitBook corpus? The importer's own rule (a marker at the
+ * top, or subfolders with a SUMMARY.md), over the folder's top two levels, through the shared
+ * path detector (so an mdBook's `src/SUMMARY.md` beside `book.toml` is not claimed).
+ */
+export function detectGitbook(sourceDir) {
+    try {
+        if (!existsSync(sourceDir) || !statSync(sourceDir).isDirectory())
+            return false;
+    }
+    catch {
+        return false;
+    }
+    const { paths } = readFolder(sourceDir, 1);
+    return detectGitbookPaths(paths) !== undefined && gitbookSpaces(paths).length > 0;
+}
+/**
+ * A GitBook folder as a corpus, its docs roots walked first: the spaces and each one's
+ * `.gitbook.yaml` `root:` are read from the top two levels, the same rule the import applies.
+ */
+export function readGitbookFolder(sourceDir, space) {
+    const top = readFolder(sourceDir, 1);
+    const spaces = space ? [space] : gitbookSpaces(top.paths);
+    const roots = [];
+    for (const s of spaces.length ? spaces : ["."]) {
+        const spaceDir = normalizePath(s);
+        if (spaceDir === undefined)
+            continue;
+        const { root } = parseGitbookConfig(top.text(joinPath(spaceDir, ".gitbook.yaml")));
+        const docsDir = root && root !== "./" ? normalizePath(joinPath(spaceDir, root)) : spaceDir;
+        if (docsDir)
+            roots.push(docsDir);
+    }
+    return readFolder(sourceDir, Infinity, roots);
+}
+/** `loadGitbookCorpus` over a folder. */
+export function loadGitbook(sourceDir, opts = {}) {
+    return loadGitbookCorpus(readGitbookFolder(sourceDir, opts.space), opts);
+}