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

package/dist/loaders/load.d.ts

@@ -1,13 +1,30 @@
+/**
+ * GitBook corpus loader, over a {@link Corpus} (no Node): find the spaces, read each
+ * `.gitbook.yaml`, parse `SUMMARY.md` for nav, list every page (including orphans not in the
+ * summary), and surface redirects + include fragments. The CLI runs it over a folder
+ * (`folder.ts`), the playground over a map of files.
+ *
+ * Multi-space corpora (e.g. snyk/user-docs holds six spaces, each a dir with its own
+ * SUMMARY.md) are detected by `gitbookSpaces` (@dogsbay/detect, the rule detection uses too):
+ * when the corpus root has no marker, every direct subfolder with a SUMMARY.md is a space. The
+ * default import concatenates all spaces (each summary's nav becomes a top-level section);
+ * `space` selects one.
+ *
+ * Paths are posix and relative to the corpus root. Pages come out in path order, so the same
+ * corpus always gives the same result (a folder's listing order is the file system's).
+ */
 import type { NavItem } from "@dogsbay/types";
+import type { Corpus } from "../corpus.js";
 export interface GitbookPageSource {
-    filePath: string;
+    /** The page's file, relative to the corpus root. */
+    path: string;
     slug: string;
     /** True for `.gitbook/includes/*` — mirrored as a fragment, not a page. */
     fragment?: boolean;
 }
 /** A resolved docs root to mirror assets from, and its slug prefix. */
 export interface GitbookAssetRoot {
-    /** Absolute docs directory (space dir + `.gitbook.yaml` `root:`). */
+    /** Docs folder (space folder + `.gitbook.yaml` `root:`), relative to the corpus root. */
     dir: string;
     /** Slug prefix for pages/assets under this root ("" or "<space>/"). */
     prefix: string;
@@ -16,17 +33,16 @@ export interface GitbookLoadResult {
     pages: GitbookPageSource[];
     nav: NavItem[];
     redirects: Record<string, string>;
-    /** Space directories detected (relative to source); ≥2 ⇒ multi-space. */
+    /** Space directories detected (relative to the corpus root); ≥2 ⇒ multi-space. */
     spaces: string[];
     /** Docs roots to mirror non-`.md` assets from, with their slug prefix. */
     assetRoots: GitbookAssetRoot[];
 }
 export interface GitbookLoadOptions {
-    /** Restrict to a single space directory (relative to source root). */
+    /** Restrict to a single space directory (relative to the corpus root). */
     space?: string;
     /** URL prefix applied to nav hrefs. */
     hrefPrefix?: string;
 }
-/** Does this directory look like a GitBook corpus? */
-export declare function detectGitbook(sourceDir: string): boolean;
-export declare function loadGitbook(sourceDir: string, opts?: GitbookLoadOptions): GitbookLoadResult;
+export declare function loadGitbookCorpus(corpus: Corpus, opts?: GitbookLoadOptions): GitbookLoadResult;
+export declare function prettify(s: string): string;

package/dist/loaders/load.js

@@ -1,163 +1,35 @@
-/**
- * GitBook corpus loader — discover the docs root, read `.gitbook.yaml`,
- * parse `SUMMARY.md` for nav, enumerate every page (including orphans not
- * in the summary), and surface redirects + include fragments.
- *
- * Multi-space corpora (e.g. snyk/user-docs holds six spaces, each a dir
- * with its own SUMMARY.md) are detected: when the caller doesn't point at
- * a single space, every dir containing a SUMMARY.md is a space. The
- * default import concatenates all spaces (each summary's nav becomes a
- * top-level section); `--space <dir>` selects one.
- */
-import { existsSync, readdirSync, readFileSync, realpathSync, statSync } from "node:fs";
-import { basename, join, relative, sep } from "node:path";
-import { readGitbookConfig } from "./config.js";
+import { gitbookSpaces, gitbookVisible, joinPath, normalizePath, within } from "@dogsbay/detect";
+import { parseGitbookConfig } from "./config.js";
 import { parseSummary, pathToSlug } from "./summary.js";
-/** Does this directory look like a GitBook corpus? */
-export function detectGitbook(sourceDir) {
-    if (!existsSync(sourceDir))
-        return false;
-    try {
-        if (!statSync(sourceDir).isDirectory())
-            return false;
-    }
-    catch {
-        return false;
-    }
-    // A .gitbook.yaml anywhere near the top, or a SUMMARY.md, is the signal.
-    if (existsSync(join(sourceDir, ".gitbook.yaml")))
-        return true;
-    if (existsSync(join(sourceDir, "SUMMARY.md")))
-        return true;
-    // Or a single-level space dir carrying either marker.
-    return findSpaces(sourceDir).length > 0;
-}
 /**
- * Directories (relative) that contain a SUMMARY.md — each is a space.
- *
- * If the ROOT itself has a SUMMARY.md, the corpus is single-space and we
- * return just `["."]` — we do NOT also scan subdirectories, because a
- * nested `SUMMARY.md` (e.g. a stray one under `api/`) would otherwise be
- * misread as a second space, duplicating that subtree's pages and adding
- * a phantom top-level nav section (review #8). Multi-space is the
- * monorepo shape where the root has NO SUMMARY.md but ≥1 subdir does.
+ * The pages under one docs folder: every visible `.md` but SUMMARY and GLOSSARY, and only what
+ * stays in that folder once links resolve (a link from the docs root elsewhere in the repo
+ * does not bring pages in).
  */
-function findSpaces(sourceDir) {
-    if (existsSync(join(sourceDir, "SUMMARY.md")) || existsSync(join(sourceDir, ".gitbook.yaml"))) {
-        return ["."];
-    }
+function pagesUnder(corpus, paths, docsDir, landing) {
     const out = [];
-    const seen = new Set();
-    const consider = (dir) => {
-        if (existsSync(join(dir, "SUMMARY.md"))) {
-            const rel = relative(sourceDir, dir) || ".";
-            if (!seen.has(rel)) {
-                seen.add(rel);
-                out.push(rel);
-            }
-        }
-    };
-    // One level down (the snyk monorepo shape: docs/, platform-administration/…).
-    let entries = [];
-    try {
-        entries = readdirSync(sourceDir);
-    }
-    catch {
-        return out;
-    }
-    for (const name of entries) {
-        if (name.startsWith(".") || name === "node_modules")
+    for (const path of paths) {
+        if (!within(path, docsDir) || path === docsDir)
             continue;
-        const full = join(sourceDir, name);
-        try {
-            if (statSync(full).isDirectory())
-                consider(full);
-        }
-        catch {
-            /* ignore */
-        }
-    }
-    return out;
-}
-/** Walk `spaceDir` for every `.md` file; classify includes as fragments. */
-/** Is `p` (once links resolve) `dir` or inside it? False when either does not exist. */
-function insideDir(p, dir) {
-    try {
-        const real = realpathSync(p);
-        const root = realpathSync(dir);
-        return real === root || real.startsWith(root + sep);
-    }
-    catch {
-        return !existsSync(p);
-    }
-}
-function walkPages(spaceDir, sourceDir) {
-    const out = [];
-    // Inside the docs root once links resolve, and 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).
-    let realRoot;
-    try {
-        realRoot = realpathSync(spaceDir);
-    }
-    catch {
-        return out;
+        if (corpus.contains && !corpus.contains(path, docsDir))
+            continue;
+        const rel = docsDir ? path.slice(docsDir.length + 1) : path;
+        if (!gitbookVisible(rel))
+            continue;
+        const name = rel.slice(rel.lastIndexOf("/") + 1);
+        if (!name.toLowerCase().endsWith(".md"))
+            continue;
+        if (name === "SUMMARY.md" || name === "GLOSSARY.md")
+            continue;
+        out.push({ path, slug: pathToSlug(rel, landing), ...(rel.includes(".gitbook/includes/") ? { fragment: true } : {}) });
     }
-    const seen = new Set([realRoot]);
-    const walk = (dir) => {
-        let entries;
-        try {
-            entries = readdirSync(dir);
-        }
-        catch {
-            return;
-        }
-        for (const name of entries) {
-            if (name === "node_modules")
-                continue;
-            const full = join(dir, name);
-            let st;
-            let real;
-            try {
-                real = realpathSync(full);
-                if (real !== realRoot && !real.startsWith(realRoot + sep))
-                    continue;
-                st = statSync(real);
-            }
-            catch {
-                continue;
-            }
-            if (st.isDirectory()) {
-                // Hidden dirs are skipped EXCEPT `.gitbook` (holds includes).
-                if (name.startsWith(".") && name !== ".gitbook")
-                    continue;
-                if (seen.has(real))
-                    continue;
-                seen.add(real);
-                walk(full);
-                continue;
-            }
-            if (!name.toLowerCase().endsWith(".md"))
-                continue;
-            if (name === "SUMMARY.md" || name === "GLOSSARY.md")
-                continue;
-            const relFromSpace = relative(spaceDir, full).replace(/\\/g, "/");
-            const isInclude = relFromSpace.includes(".gitbook/includes/");
-            out.push({
-                filePath: full,
-                slug: pathToSlug(relFromSpace),
-                ...(isInclude ? { fragment: true } : {}),
-            });
-        }
-    };
-    walk(spaceDir);
     return out;
 }
-export function loadGitbook(sourceDir, opts = {}) {
+export function loadGitbookCorpus(corpus, opts = {}) {
     const hrefPrefix = opts.hrefPrefix ?? "";
-    const allSpaces = findSpaces(sourceDir);
-    // Which spaces to load: an explicit --space, else all detected (or the
-    // root itself if none matched).
+    const paths = [...corpus.paths].sort();
+    const allSpaces = gitbookSpaces(paths);
+    // Which spaces to load: an explicit `space`, else all detected (or the root itself if none matched).
     let spaces = opts.space ? [opts.space] : allSpaces;
     if (spaces.length === 0)
         spaces = ["."];
@@ -167,33 +39,38 @@ export function loadGitbook(sourceDir, opts = {}) {
     const assetRoots = [];
     const multi = spaces.length > 1;
     for (const space of spaces) {
-        const spaceDir = space === "." ? sourceDir : join(sourceDir, space);
-        if (!existsSync(spaceDir))
+        const spaceDir = normalizePath(space);
+        if (spaceDir === undefined)
+            throw new Error(`space "${space}" is outside the source directory`);
+        if (spaceDir && !paths.some((p) => within(p, spaceDir)))
             continue;
-        const config = readGitbookConfig(spaceDir);
-        // `root:` relocates the docs dir within the space.
-        const docsDir = config.root && config.root !== "./" ? join(spaceDir, config.root) : spaceDir;
-        // `root:` comes from the repo being imported: it may not lead out of it.
-        if (!insideDir(docsDir, sourceDir)) {
+        const config = parseGitbookConfig(corpus.text(joinPath(spaceDir, ".gitbook.yaml")));
+        // `root:` relocates the docs dir within the space. It comes from the repo being imported:
+        // it may not lead out of it.
+        const docsDir = config.root && config.root !== "./" ? normalizePath(joinPath(spaceDir, config.root)) : spaceDir;
+        if (docsDir === undefined) {
             throw new Error(`.gitbook.yaml in ${space === "." ? "the source" : space}: root "${config.root}" is outside the source directory`);
         }
+        // `structure.readme` names the home page when it is not README.md (`readme: intro.md`).
+        // It becomes `index`, like a README; one that is not in the docs root is ignored.
+        const readme = normalizePath(config.readme);
+        const landing = readme && !/^readme\.md$/i.test(readme) && paths.includes(joinPath(docsDir, readme)) ? readme : undefined;
         // Page prefix so multi-space slugs don't collide (space dir name).
-        const slugPrefix = multi && space !== "." ? `${space}/` : "";
+        const slugPrefix = multi && spaceDir ? `${spaceDir}/` : "";
         assetRoots.push({ dir: docsDir, prefix: slugPrefix });
-        for (const p of walkPages(docsDir, docsDir)) {
+        for (const p of pagesUnder(corpus, paths, docsDir, landing)) {
             pages.push({ ...p, slug: `${slugPrefix}${p.slug}`.replace(/\/+/g, "/") });
         }
         // Nav from SUMMARY.md (under docsDir per config.summary).
-        const summaryPath = join(docsDir, config.summary);
+        const summaryPath = normalizePath(joinPath(docsDir, config.summary));
+        const summary = summaryPath === undefined ? undefined : corpus.text(summaryPath);
         const navPrefix = `${hrefPrefix}${slugPrefix ? "/" + slugPrefix.replace(/\/$/, "") : ""}`;
-        if (existsSync(summaryPath)) {
-            const parsed = parseSummary(readFileSync(summaryPath, "utf-8"), navPrefix);
-            if (multi) {
+        if (summary !== undefined) {
+            const parsed = parseSummary(summary, navPrefix, landing);
+            if (multi)
                 nav.push({ label: prettify(space), children: parsed.nav });
-            }
-            else {
+            else
                 nav.push(...parsed.nav);
-            }
         }
         else {
             // No SUMMARY.md — infer nav from folder structure (paths → slugs).
@@ -203,13 +80,14 @@ export function loadGitbook(sourceDir, opts = {}) {
             else
                 nav.push(...inferred);
         }
-        // Redirect keys (old URL) AND values (target .md) are relative to the
-        // space, so BOTH get the space slug prefix in a multi-space import —
-        // else a redirect in space `docs` would point at an unprefixed target
-        // that doesn't exist under `docs/`.
+        // Redirect keys (old URL) AND values (target .md) are relative to the space, so BOTH get
+        // the space slug prefix in a multi-space import — else a redirect in space `docs` would
+        // point at an unprefixed target that doesn't exist under `docs/`.
         for (const [k, v] of Object.entries(config.redirects)) {
             const key = slugPrefix ? `${slugPrefix}${k}` : k;
-            const val = slugPrefix ? `${slugPrefix}${v.replace(/^\.\//, "")}` : v;
+            // A redirect to the landing page goes to the space's home, as one to its README does
+            const target = landing && normalizePath(v) === landing ? "README.md" : v;
+            const val = slugPrefix ? `${slugPrefix}${target.replace(/^\.\//, "")}` : target;
             redirects[key] = val;
         }
     }
@@ -219,10 +97,10 @@ export function loadGitbook(sourceDir, opts = {}) {
 function inferNavFromPages(pages) {
     return pages
         .filter((p) => p.slug !== "index")
-        .map((p) => ({ label: prettify(basename(p.slug)), href: `/${p.slug}` }))
+        .map((p) => ({ label: prettify(p.slug.slice(p.slug.lastIndexOf("/") + 1)), href: `/${p.slug}` }))
         .sort((a, b) => a.label.localeCompare(b.label));
 }
-function prettify(s) {
+export function prettify(s) {
     return s
         .split(/[-_/]/)
         .filter(Boolean)

package/dist/loaders/summary.d.ts

@@ -22,6 +22,10 @@ export interface ParsedSummary {
     /** Every local page path referenced by the summary (posix, .md kept). */
     referenced: string[];
 }
-/** Normalize a GitBook page path to a Dogsbay slug (README → index). */
-export declare function pathToSlug(relPath: string): string;
-export declare function parseSummary(content: string, hrefPrefix?: string): ParsedSummary;
+/**
+ * Normalize a GitBook page path to a Dogsbay slug (README → index). `landing` is a space's
+ * `.gitbook.yaml` `structure.readme` when it is not README.md: that page is the home page, and
+ * a README.md beside it is an ordinary page, `readme`.
+ */
+export declare function pathToSlug(relPath: string, landing?: string): string;
+export declare function parseSummary(content: string, hrefPrefix?: string, landing?: string): ParsedSummary;

package/dist/loaders/summary.js

@@ -1,6 +1,16 @@
-/** Normalize a GitBook page path to a Dogsbay slug (README → index). */
-export function pathToSlug(relPath) {
+/**
+ * Normalize a GitBook page path to a Dogsbay slug (README → index). `landing` is a space's
+ * `.gitbook.yaml` `structure.readme` when it is not README.md: that page is the home page, and
+ * a README.md beside it is an ordinary page, `readme`.
+ */
+export function pathToSlug(relPath, landing) {
     let p = relPath.replace(/\\/g, "/").replace(/^\.\//, "").replace(/\.md$/i, "");
+    if (landing !== undefined) {
+        if (p === landing.replace(/\.md$/i, ""))
+            return "index";
+        if (p === "README" || p === "readme")
+            return "readme";
+    }
     if (p === "README" || p === "readme")
         return "index";
     p = p.replace(/\/README$/i, "/index");
@@ -16,7 +26,7 @@ const LINK_RE = /^\[([^\]]*)\]\(\s*(?:<([^>]*)>|([^)\s]+))[^)]*\)/;
 const EXTERNAL_RE = /^(https?:\/\/|mailto:|tel:)/i;
 // Strip a trailing `<a href id>` anchor GitBook adds to group headings.
 const ANCHOR_TAIL_RE = /\s*<a\b[^>]*><\/a>\s*$/;
-export function parseSummary(content, hrefPrefix = "") {
+export function parseSummary(content, hrefPrefix = "", landing) {
     const referenced = [];
     const top = [];
     // Current group container the following items attach to (null = top level).
@@ -43,7 +53,7 @@ export function parseSummary(content, hrefPrefix = "") {
         if (!it)
             continue;
         const indent = it[1].replace(/\t/g, "    ").length;
-        const item = parseItem(it[2], hrefPrefix, referenced);
+        const item = parseItem(it[2], hrefPrefix, referenced, landing);
         if (!item)
             continue;
         // Attach by indentation. Pop deeper-or-equal entries; the remaining
@@ -62,7 +72,7 @@ export function parseSummary(content, hrefPrefix = "") {
     strip(top);
     return { nav: top, referenced };
 }
-function parseItem(text, hrefPrefix, referenced) {
+function parseItem(text, hrefPrefix, referenced, landing) {
     const m = text.match(LINK_RE);
     if (!m) {
         // A plain-text item (no link) — a group-ish header without a page.
@@ -79,7 +89,7 @@ function parseItem(text, hrefPrefix, referenced) {
     const frag = hashIdx === -1 ? "" : target.slice(hashIdx);
     if (filePart)
         referenced.push(filePart.replace(/^\.\//, ""));
-    const slug = pathToSlug(filePart);
+    const slug = pathToSlug(filePart, landing);
     const href = `${hrefPrefix}/${slug}`.replace(/\/+/g, "/");
     return { label, href: `${href}${frag}` };
 }

package/dist/migrate.d.ts

@@ -0,0 +1,32 @@
+/**
+ * `@dogsbay/format-gitbook/migrate` — the browser entry. A GitBook corpus as a map of files →
+ * a Dogsbay project as a map of files: the same import and project writer `dogsbay
+ * migrate-gitbook` runs, without the Astro scaffold. No Node, nothing from the corpus is run,
+ * no console, clock or network. Find the corpus with `@dogsbay/detect` first.
+ */
+import type { ImportLedgerEntry } from "@dogsbay/types";
+import { type CorpusFiles } from "./corpus.js";
+export type { CorpusFiles } from "./corpus.js";
+export interface MigrateInput {
+    /** The corpus: paths relative to its root (a detection's `root`), text or bytes. */
+    files: CorpusFiles;
+    /** One space of a multi-space repo (a detection's `choices.spaces`); all when omitted. */
+    choose?: {
+        space?: string;
+    };
+    siteName?: string;
+    siteUrl?: string;
+    /** Where the corpus came from, for MIGRATION.md (e.g. the repo URL). */
+    sourceLabel?: string;
+}
+export interface MigrateResult {
+    /** The Dogsbay project: dogsbay.config.yml, content/** (pages, nav.yml, assets), MIGRATION.md. */
+    files: Map<string, string | Uint8Array>;
+    ledger: ImportLedgerEntry[];
+    /** Old URL → served URL, both root-absolute; the host decides how to serve them. */
+    redirects: {
+        from: string;
+        to: string;
+    }[];
+}
+export declare function migrate(input: MigrateInput): Promise<MigrateResult>;

package/dist/migrate.js

@@ -0,0 +1,19 @@
+import { corpusFromMap } from "./corpus.js";
+import { importGitbookCorpus } from "./import.js";
+import { gitbookProject } from "./project.js";
+export async function migrate(input) {
+    const corpus = corpusFromMap(input.files);
+    const imported = importGitbookCorpus(corpus, { space: input.choose?.space });
+    const project = gitbookProject(imported, corpus, {
+        siteName: input.siteName?.trim() || "Docs",
+        siteUrl: input.siteUrl,
+        sourceLabel: input.sourceLabel ?? "GitBook corpus",
+    });
+    const files = new Map(project.files);
+    for (const { from, to } of project.assets) {
+        const bytes = input.files.get(from);
+        if (bytes !== undefined)
+            files.set(to, bytes);
+    }
+    return { files, ledger: project.ledger, redirects: project.redirects };
+}

package/dist/parse.d.ts

@@ -7,6 +7,12 @@ export interface ParseGitbookResult {
     markdown: string;
     /** Translated body only (no frontmatter) — for callers writing their own. */
     body: string;
+    /** Ledger lines count from the body: the source line the body starts on (1 with no front matter). */
+    bodyLine: number;
     ledger: TranslateLedgerEntry[];
 }
-export declare function parseGitbook(src: string): ParseGitbookResult;
+export interface ParseGitbookOptions {
+    /** Applied to the translated body before it is parsed (the import's renamed page links). */
+    links?: (body: string) => string;
+}
+export declare function parseGitbook(src: string, opts?: ParseGitbookOptions): ParseGitbookResult;

package/dist/parse.js

@@ -15,18 +15,21 @@
  * writes to disk — canonical, editable Dogsbay-MD. `tree` feeds the
  * runtime path (format-astro emit, headings, title).
  */
-import { dogsbayMdToTree } from "@dogsbay/format-dogsbay-md";
+import { dogsbayMdToTree } from "@dogsbay/format-dogsbay-md/browser";
 import { gitbookToDogsbayMd } from "./translate.js";
 const FRONTMATTER_RE = /^---\n([\s\S]*?)\n---\n?/;
-export function parseGitbook(src) {
+export function parseGitbook(src, opts = {}) {
     const normalized = src.replace(/\r\n?/g, "\n");
     const fmMatch = normalized.match(FRONTMATTER_RE);
     const fmBlock = fmMatch ? fmMatch[0] : "";
     const body = fmMatch ? normalized.slice(fmMatch[0].length) : normalized;
-    const { markdown: translatedBody, ledger } = gitbookToDogsbayMd(body);
+    const translated = gitbookToDogsbayMd(body);
+    const { ledger } = translated;
+    const translatedBody = opts.links ? opts.links(translated.markdown) : translated.markdown;
     const markdown = fmBlock ? `${fmBlock.replace(/\n?$/, "\n")}\n${translatedBody}` : translatedBody;
     // dogsbayMdToTree extracts frontmatter itself (gray-matter) and parses
     // the body into TreeNode[]. Feed it the recombined markdown.
     const { tree, frontmatter } = dogsbayMdToTree(markdown);
-    return { tree, frontmatter: frontmatter ?? {}, markdown, body: translatedBody, ledger };
+    const bodyLine = fmBlock ? fmBlock.split("\n").length - (fmBlock.endsWith("\n") ? 1 : 0) + 1 : 1;
+    return { tree, frontmatter: frontmatter ?? {}, markdown, body: translatedBody, bodyLine, ledger };
 }

package/dist/project.d.ts

@@ -0,0 +1,34 @@
+import type { ImportLedgerEntry } from "@dogsbay/types";
+import type { Corpus } from "./corpus.js";
+import type { GitbookImportResult } from "./import.js";
+export interface GitbookProjectOptions {
+    siteName: string;
+    siteUrl?: string;
+    /** Where the corpus came from, for MIGRATION.md (a folder, a repo URL). */
+    sourceLabel: string;
+    /** Where the host writes the redirects, for MIGRATION.md (the CLI: `astro/public/_redirects`). */
+    redirectsFile?: string;
+}
+export interface GitbookProject {
+    /** The project's text files, by path relative to the project root. */
+    files: Map<string, string>;
+    /** Files to copy unchanged: corpus path → project path. */
+    assets: {
+        from: string;
+        to: string;
+    }[];
+    /** Old URL → served URL, both root-absolute (`/old/path` → `/guide`). */
+    redirects: {
+        from: string;
+        to: string;
+    }[];
+    /** The import's ledger plus the writer's own notes (slug collisions). */
+    ledger: ImportLedgerEntry[];
+    stats: {
+        pages: number;
+        fragments: number;
+        collisions: number;
+        spaces: string[];
+    };
+}
+export declare function gitbookProject(result: GitbookImportResult, corpus: Corpus, opts: GitbookProjectOptions): GitbookProject;