@dogsbay/format-gitbook 0.2.0-beta.132 → 0.2.0-beta.134

package/dist/corpus.d.ts

@@ -1,2 +1,2 @@
 /** The corpus an importer reads: `@dogsbay/corpus`, shared by every format's browser import. */
-export { corpusFromMap, type Corpus, type CorpusFiles } from "@dogsbay/corpus";
+export { corpusFromMap, type Corpus, type CorpusFiles, type Unfetched, unfetchedMessage, pendingCopies, withPages } from "@dogsbay/corpus";

package/dist/corpus.js

@@ -1,2 +1,2 @@
 /** The corpus an importer reads: `@dogsbay/corpus`, shared by every format's browser import. */
-export { corpusFromMap } from "@dogsbay/corpus";
+export { corpusFromMap, unfetchedMessage, pendingCopies, withPages } from "@dogsbay/corpus";

package/dist/import.d.ts

@@ -23,5 +23,7 @@ export interface GitbookImportResult {
     /** Docs roots to mirror non-`.md` assets from (corpus-relative folder + slug prefix). */
     assetRoots: GitbookAssetRoot[];
     ledger: ImportLedgerEntry[];
+    /** The corpus file each page was converted from: `sources[i]` is `pages[i]`'s. */
+    sources: string[];
 }
 export declare function importGitbookCorpus(corpus: Corpus, opts?: GitbookImportOptions): GitbookImportResult;

package/dist/import.js

@@ -6,6 +6,7 @@ export function importGitbookCorpus(corpus, opts = {}) {
     const { pages: sources, nav, redirects, spaces, assetRoots } = loadGitbookCorpus(corpus, opts);
     const pages = [];
     const ledger = [];
+    const pageFiles = [];
     // 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();
@@ -37,6 +38,7 @@ export function importGitbookCorpus(corpus, opts = {}) {
             // 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));
+            pageFiles.push(ps.path);
             pages.push({
                 slug: ps.slug,
                 title,
@@ -58,5 +60,5 @@ export function importGitbookCorpus(corpus, opts = {}) {
             });
         }
     }
-    return { pages, nav, redirects, spaces, assetRoots, ledger };
+    return { pages, nav, redirects, spaces, assetRoots, ledger, sources: pageFiles };
 }

package/dist/migrate.d.ts

@@ -5,11 +5,17 @@
  * 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";
+import { type CorpusFiles, type Unfetched } from "./corpus.js";
+export type { CorpusFiles, Unfetched } from "./corpus.js";
 export interface MigrateInput {
     /** The corpus: paths relative to its root (a detection's `root`), text or bytes. */
     files: CorpusFiles;
+    /**
+     * Every path of the project (relative to the same root as `files`), when the host lists more
+     * than it fetched (a GitHub tree). The import then sees the repo as it is, and `unfetched`
+     * says what it needed from those not given: fetch them and call `migrate` again.
+     */
+    paths?: Iterable<string>;
     /** One space of a multi-space repo (a detection's `choices.spaces`); all when omitted. */
     choose?: {
         space?: string;
@@ -28,5 +34,14 @@ export interface MigrateResult {
         from: string;
         to: string;
     }[];
+    /**
+     * The listed `paths` the conversion needed but `files` did not hold. `read`: it read them,
+     * so fetch them and convert again (each round can find one more level of an include or
+     * `require` chain: cap the rounds). While `read` is not empty the result is not a
+     * conversion; when the import could not go on, `files` is empty and the ledger says where
+     * it stopped. `copy`: assets the output copies; fetch them for the finished files, no
+     * rerun. Both empty: the result is complete.
+     */
+    unfetched: Unfetched;
 }
 export declare function migrate(input: MigrateInput): Promise<MigrateResult>;

package/dist/migrate.js

@@ -1,19 +1,38 @@
-import { corpusFromMap } from "./corpus.js";
+import { corpusFromMap, pendingCopies, unfetchedMessage } from "./corpus.js";
 import { importGitbookCorpus } from "./import.js";
 import { gitbookProject } from "./project.js";
+/** The ledger line for a conversion that still needs files, or nothing. */
+function unfetchedLedger(read, stoppedOn) {
+    const message = unfetchedMessage(read, stoppedOn);
+    return message ? [{ severity: "warning", code: "unfetched", message }] : [];
+}
 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 corpus = corpusFromMap(input.files, { paths: input.paths });
+    let project;
+    try {
+        const imported = importGitbookCorpus(corpus, { space: input.choose?.space });
+        project = gitbookProject(imported, corpus, {
+            siteName: input.siteName?.trim() || "Docs",
+            siteUrl: input.siteUrl,
+            sourceLabel: input.sourceLabel ?? "GitBook corpus",
+        });
+    }
+    catch (e) {
+        // A file it needed was not given: that, not the error, is the answer
+        const read = corpus.missing();
+        if (read.length)
+            return { files: new Map(), ledger: unfetchedLedger(read, e), redirects: [], unfetched: { read, copy: [], copyTo: [] } };
+        throw e;
+    }
     const files = new Map(project.files);
+    const copy = [];
     for (const { from, to } of project.assets) {
         const bytes = input.files.get(from);
         if (bytes !== undefined)
             files.set(to, bytes);
+        else
+            copy.push({ from, to });
     }
-    return { files, ledger: project.ledger, redirects: project.redirects };
+    const read = corpus.missing();
+    return { files, ledger: [...unfetchedLedger(read), ...project.ledger], redirects: project.redirects, unfetched: { read, ...pendingCopies(copy) } };
 }

package/dist/project.d.ts

@@ -1,5 +1,5 @@
 import type { ImportLedgerEntry } from "@dogsbay/types";
-import type { Corpus } from "./corpus.js";
+import { type Corpus } from "./corpus.js";
 import type { GitbookImportResult } from "./import.js";
 export interface GitbookProjectOptions {
     siteName: string;

package/dist/project.js

@@ -7,6 +7,7 @@
  */
 import * as yaml from "js-yaml";
 import { gitbookVisible, within } from "@dogsbay/detect";
+import { withPages } from "./corpus.js";
 function yamlQuote(s) {
     return /[:#&*!|>%@`,'"[\]{}]|^\s|\s$/.test(s) ? JSON.stringify(s) : s;
 }
@@ -95,7 +96,9 @@ export function gitbookProject(result, corpus, opts) {
     const taken = new Set();
     let fragments = 0;
     let collisions = 0;
-    for (const page of result.pages) {
+    // Each written page's source file → the page, for the notes about that file
+    const pageOf = new Map();
+    for (const [i, page] of result.pages.entries()) {
         const dst = `content/${page.slug}.md`;
         if (taken.has(dst.toLowerCase())) {
             collisions += 1;
@@ -103,6 +106,8 @@ export function gitbookProject(result, corpus, opts) {
             continue;
         }
         taken.add(dst.toLowerCase());
+        if (result.sources?.[i] !== undefined)
+            pageOf.set(result.sources[i], dst);
         const body = page.bodyMarkdown ?? "";
         const text = body.endsWith("\n") ? body : body + "\n";
         if (page.fragment) {
@@ -170,6 +175,8 @@ export function gitbookProject(result, corpus, opts) {
         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 } };
+    // Each note about a written page's file names that page
+    const placed = withPages(ledger, pageOf);
+    files.set("MIGRATION.md", migrationNotes({ ...opts, pages, fragments, spaces: result.spaces, redirects: redirects.length, ledger: placed }));
+    return { files, assets: copies, redirects, ledger: placed, stats: { pages, fragments, collisions, spaces: result.spaces } };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dogsbay/format-gitbook",
-  "version": "0.2.0-beta.132",
+  "version": "0.2.0-beta.134",
   "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",
@@ -25,10 +25,10 @@
   ],
   "dependencies": {
     "js-yaml": "^5.2.1",
-    "@dogsbay/corpus": "0.2.0-beta.132",
-    "@dogsbay/format-dogsbay-md": "0.2.0-beta.132",
-    "@dogsbay/types": "0.2.0-beta.132",
-    "@dogsbay/detect": "0.2.0-beta.132"
+    "@dogsbay/corpus": "0.2.0-beta.134",
+    "@dogsbay/format-dogsbay-md": "0.2.0-beta.134",
+    "@dogsbay/detect": "0.2.0-beta.134",
+    "@dogsbay/types": "0.2.0-beta.134"
   },
   "devDependencies": {
     "@types/js-yaml": "^4.0.9",