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

package/dist/project.js

@@ -0,0 +1,175 @@
+/**
+ * An imported GitBook corpus → a Dogsbay project, as data (no Node, quiet, deterministic):
+ * `content/<slug>.md` (front matter + translated body), fragments as include targets,
+ * `content/nav.yml` from SUMMARY.md, `dogsbay.config.yml`, `MIGRATION.md`, the assets to copy
+ * and the redirects. `migrate-gitbook` writes it to disk and adds the Astro scaffold and
+ * `_redirects`; the browser (`./migrate`) returns it as a map of files.
+ */
+import * as yaml from "js-yaml";
+import { gitbookVisible, within } from "@dogsbay/detect";
+function yamlQuote(s) {
+    return /[:#&*!|>%@`,'"[\]{}]|^\s|\s$/.test(s) ? JSON.stringify(s) : s;
+}
+/** Serialize NavItem[] to nav.yml (mirrors migrate-asciidoc's navToYaml). */
+function navToYaml(items, indent = 0) {
+    const pad = "  ".repeat(indent);
+    const lines = [];
+    for (const item of items) {
+        const hasChildren = item.children !== undefined && item.children.length > 0;
+        const target = item.href === undefined
+            ? undefined
+            : /^(?:https?:\/\/|mailto:|tel:)/i.test(item.href) || item.href.includes("#")
+                ? item.href
+                : `${item.href.replace(/^\/+/, "")}.md`;
+        if (target !== undefined && !hasChildren) {
+            lines.push(`${pad}- ${yamlQuote(item.label)}: ${target}`);
+        }
+        else {
+            lines.push(`${pad}- ${yamlQuote(item.label)}:`);
+            if (target !== undefined)
+                lines.push(`${pad}    - ${yamlQuote(target)}`);
+            if (hasChildren)
+                lines.push(navToYaml(item.children, indent + 2));
+        }
+    }
+    return lines.join("\n");
+}
+function buildConfig(siteName, siteUrl) {
+    const lines = [`schemaVersion: 1`, `site:`, `  name: ${yamlQuote(siteName)}`, `  basePath: ""`];
+    if (siteUrl)
+        lines.push(`  url: ${yamlQuote(siteUrl)}`);
+    lines.push(`content:`, `  sources:`, `    - path: ./content`, `      from: dogsbay-md`, 
+    // `.gitbook/includes` fragments are `{% include %}` targets, not routable pages.
+    // routablesFrom: nav restricts routes to SUMMARY-named pages; the fragments stay on disk
+    // so includes resolve.
+    `  excludeFromRoutes:`, `    - .gitbook`, `  routablesFrom: nav`, ``);
+    return lines.join("\n");
+}
+/**
+ * Front matter (source keys + a title) as a YAML block. Array/object values (`tags: [a, b]`,
+ * GitBook `cover:` maps) round-trip instead of being dropped (review #4). The title is the
+ * source `title:` only when it's a non-empty string; otherwise the computed title (H1 / slug):
+ * a blank source title must NOT clobber it (review #6).
+ */
+// No `noRefs`: an alias the source used stays an alias. Writing each out in full turned ten
+// lines of nested aliases into hundreds of MB (an alias bomb, review 2026-10-20).
+function frontmatterBlock(fm, title) {
+    const sourceTitle = typeof fm.title === "string" && fm.title.trim() ? fm.title : undefined;
+    const out = { title: sourceTitle ?? title, ...fm };
+    out.title = sourceTitle ?? title;
+    const body = yaml.dump(out, { lineWidth: -1, skipInvalid: true }).replace(/\n$/, "");
+    return `---\n${body}\n---\n\n`;
+}
+/** A redirect's target as the URL it is served at: drop ./ and .md; a README is its folder. */
+function servedUrl(target) {
+    // A bare `README` maps to the site root `/`, not a dead `/README` (review #5).
+    return `/${target.replace(/^\.\//, "").replace(/\.md$/i, "").replace(/(^|\/)README$/i, "$1").replace(/\/$/, "")}`;
+}
+function migrationNotes(a) {
+    const lines = [
+        `# Migration: ${a.siteName}`,
+        ``,
+        `Migrated from a GitBook Git Sync corpus by \`dogsbay migrate-gitbook\`.`,
+        ``,
+        `- **Source**: \`${a.sourceLabel}\``,
+        `- **Pages**: ${a.pages}${a.fragments ? ` (+ ${a.fragments} include fragments)` : ""}`,
+    ];
+    if (a.spaces.length > 1)
+        lines.push(`- **Spaces**: ${a.spaces.join(", ")} (each a top-level nav section)`);
+    if (a.redirects)
+        lines.push(`- **Redirects**: ${a.redirects}${a.redirectsFile ? ` carried into \`${a.redirectsFile}\`` : ""}`);
+    lines.push(``, `## What was converted`, ``, `- GitBook \`{% hint %}\` → \`:::note/:::warning/:::info/:::danger\` callouts`, `- \`{% tabs %}\` / \`{% stepper %}\` / \`{% columns %}\` → \`:::tabs\` / \`:::steps\` / \`:::grid\``, `- \`{% code %}\`, \`{% content-ref %}\`, \`{% embed %}\`, \`{% file %}\`, \`{% page-ref %}\` → native Dogsbay-MD`, `- \`{% include %}\` reusable content preserved (resolved at build time)`, `- \`<figure>\` images, GitBook emoji spans, raw HTML tables handled`, `- \`SUMMARY.md\` → \`content/nav.yml\`; \`.gitbook.yaml\` redirects kept`, ``, `## Known caveats`, ``, `- \`{% openapi %}\` / \`{% swagger %}\` blocks emit \`:::api-endpoint\` placeholders — wire them to the OpenAPI spec for full rendering.`);
+    if (a.ledger.length) {
+        lines.push(``, `## Review these`, ``);
+        for (const e of a.ledger)
+            lines.push(`- \`${e.file ?? "?"}${e.line ? `:${e.line}` : ""}\`: ${e.message}`);
+    }
+    return lines.join("\n") + "\n";
+}
+export function gitbookProject(result, corpus, opts) {
+    const files = new Map();
+    const ledger = [...result.ledger];
+    // Two source files can slugify to the same path (README.md and index.md both → `index`).
+    // Keep the first, skip and note the rest rather than silently overwriting a page (review #3).
+    // Paths compared without case: on macOS and Windows `INDEX.md` overwrites `index.md`.
+    const taken = new Set();
+    let fragments = 0;
+    let collisions = 0;
+    for (const page of result.pages) {
+        const dst = `content/${page.slug}.md`;
+        if (taken.has(dst.toLowerCase())) {
+            collisions += 1;
+            ledger.push({ severity: "warning", code: "slug-collision", message: `two pages map to ${dst}: kept the first, skipped a later one` });
+            continue;
+        }
+        taken.add(dst.toLowerCase());
+        const body = page.bodyMarkdown ?? "";
+        const text = body.endsWith("\n") ? body : body + "\n";
+        if (page.fragment) {
+            // Fragments: pure body, no frontmatter (they're include targets).
+            files.set(dst, text);
+            fragments += 1;
+        }
+        else {
+            files.set(dst, frontmatterBlock(page.frontmatter ?? {}, page.title) + text);
+        }
+    }
+    // Non-`.md` files under each docs root, at the same relative place under content/, so the
+    // translated relative image refs resolve. From the docs root, not the repo root: with
+    // `root: ./docs/gitbook/` unrelated repo source must not land in content/.
+    const assets = [];
+    for (const root of result.assetRoots) {
+        for (const path of corpus.paths) {
+            if (!within(path, root.dir) || path === root.dir)
+                continue;
+            // Only what stays in the docs root once links resolve: a link named `env.txt` to the
+            // repo's `.env`, or `g` to `.git`, must not be published with the site.
+            if (corpus.contains && !corpus.contains(path, root.dir))
+                continue;
+            const rel = root.dir ? path.slice(root.dir.length + 1) : path;
+            if (!gitbookVisible(rel))
+                continue;
+            const name = rel.slice(rel.lastIndexOf("/") + 1);
+            // A hidden file is the repo's (`.env`, `.npmrc`, `.gitbook/assets/.DS_Store`), never a
+            // page's asset; `.gitbook.yaml` is read as config, not published.
+            if (name.toLowerCase().endsWith(".md") || name.startsWith("."))
+                continue;
+            assets.push({ from: path, to: `content/${root.prefix}${rel}` });
+        }
+    }
+    files.set("content/nav.yml", `# Migrated by dogsbay migrate-gitbook.\n# Edit freely.\n\n${navToYaml(result.nav)}\n`);
+    files.set("dogsbay.config.yml", buildConfig(opts.siteName, opts.siteUrl));
+    files.set("MIGRATION.md", "");
+    // A corpus file at a generated path (a `nav.yml` in the docs root) must not replace it, nor
+    // may two assets that differ only in case replace each other
+    for (const f of files.keys())
+        taken.add(f.toLowerCase());
+    const copies = assets.filter((a) => {
+        const key = a.to.toLowerCase();
+        if (!taken.has(key)) {
+            taken.add(key);
+            return true;
+        }
+        ledger.push({ file: a.from, severity: "warning", code: "file-replaced", message: `not copied: ${a.to} would replace a file the migration writes` });
+        return false;
+    });
+    // A redirect is one `_redirects` line: no whitespace or control character in either side, or
+    // a crafted key (`"x  https://evil 301\n/y"`) adds a line of its own. A backslash is a slash
+    // to a browser (`/\evil.example` is another host), and a `*` or `:name` in the old path is a
+    // pattern that would capture the whole site.
+    const redirects = [];
+    for (const [from, target] of Object.entries(result.redirects)) {
+        const r = { from: `/${from.replace(/^\/+/, "")}`, to: servedUrl(target) };
+        if (/[\s\0-\x1f\\]/.test(r.from + r.to) ||
+            r.from.startsWith("//") ||
+            r.to.startsWith("//") ||
+            /\*|(^|\/):/.test(r.from)) {
+            ledger.push({ file: ".gitbook.yaml", severity: "warning", code: "redirect-refused", message: `redirect not kept: ${JSON.stringify(from)} → ${JSON.stringify(target)}` });
+            continue;
+        }
+        redirects.push(r);
+    }
+    const pages = result.pages.filter((p) => !p.fragment).length;
+    files.set("MIGRATION.md", migrationNotes({ ...opts, pages, fragments, spaces: result.spaces, redirects: redirects.length, ledger }));
+    return { files, assets: copies, redirects, ledger, stats: { pages, fragments, collisions, spaces: result.spaces } };
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@dogsbay/format-gitbook",
-  "version": "0.2.0-beta.129",
-  "description": "GitBook format plugin for Dogsbay — imports GitBook Git Sync (and legacy gitbook-cli) corpora into TreeNode[] by translating the Git Sync markdown dialect to Dogsbay-MD.",
+  "version": "0.2.0-beta.131",
+  "description": "GitBook format plugin for Dogsbay — imports GitBook Git Sync (and legacy gitbook-cli) corpora by translating the Git Sync markdown dialect to Dogsbay-MD. ./migrate converts a corpus given as a map of files in the browser (no Node), the same import the CLI runs.",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -13,6 +13,10 @@
     "./cli": {
       "types": "./dist/cli.d.ts",
       "import": "./dist/cli.js"
+    },
+    "./migrate": {
+      "types": "./dist/migrate.d.ts",
+      "import": "./dist/migrate.js"
     }
   },
   "files": [
@@ -20,12 +24,15 @@
     "README.md"
   ],
   "dependencies": {
-    "yaml": "^2.9.0",
-    "@dogsbay/format-dogsbay-md": "0.2.0-beta.129",
-    "@dogsbay/types": "0.2.0-beta.129"
+    "js-yaml": "^5.2.1",
+    "@dogsbay/detect": "0.2.0-beta.131",
+    "@dogsbay/format-dogsbay-md": "0.2.0-beta.131",
+    "@dogsbay/types": "0.2.0-beta.131"
   },
   "devDependencies": {
+    "@types/js-yaml": "^4.0.9",
     "@types/node": "^25.9.5",
+    "esbuild": "^0.25.0",
     "typescript": "^5.9.3",
     "vitest": "^4.1.10"
   },