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

package/dist/migrate.d.ts

@@ -6,11 +6,17 @@
  * clock or network. Find the project with `@dogsbay/detect` first.
  */
 import type { ImportLedgerEntry } from "@dogsbay/types";
-import { type CorpusFiles } from "@dogsbay/corpus";
-export type { CorpusFiles } from "@dogsbay/corpus";
+import { type CorpusFiles, type Unfetched } from "@dogsbay/corpus";
+export type { CorpusFiles, Unfetched } from "@dogsbay/corpus";
 export interface MigrateInput {
     /** The project: 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>;
     /** Defaults to the config's `title`, else "Docs". */
     siteName?: string;
     siteUrl?: string;
@@ -21,5 +27,14 @@ export interface MigrateResult {
     /** The Dogsbay project: dogsbay.config.yml, content/** (pages, nav.json, _assets), MIGRATION.md. */
     files: Map<string, string | Uint8Array>;
     ledger: ImportLedgerEntry[];
+    /**
+     * 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,6 +1,11 @@
-import { corpusFromMap } from "@dogsbay/corpus";
+import { corpusFromMap, unfetchedMessage } from "@dogsbay/corpus";
 import { dogsbayMdPageFiles, mountCopies } from "@dogsbay/format-dogsbay-md/browser";
 import { importVitepressCorpus } from "./import.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 }] : [];
+}
 const yamlQuote = (s) => JSON.stringify(s);
 function buildConfig(siteName, siteUrl) {
     const lines = [`schemaVersion: 1`, `site:`, `  name: ${yamlQuote(siteName)}`, `  basePath: ""`];
@@ -39,16 +44,29 @@ function migrationNotes(a) {
     return lines.join("\n") + "\n";
 }
 export async function migrate(input) {
-    const corpus = corpusFromMap(input.files);
-    const imported = importVitepressCorpus(corpus);
+    const corpus = corpusFromMap(input.files, { paths: input.paths });
+    let imported;
+    try {
+        imported = importVitepressCorpus(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), unfetched: { read, copy: [] } };
+        throw e;
+    }
     const siteName = input.siteName?.trim() || imported.siteName?.trim() || "Docs";
     const files = new Map();
     // Assets first, then the pages: `convert` copies the mounts before it writes the pages, so a
     // page wins over a file at the same path
+    const copy = [];
     for (const { from, to } of mountCopies(corpus.paths, imported.assetDirs)) {
         const bytes = input.files.get(from);
         if (bytes !== undefined)
             files.set(`content/${to}`, bytes);
+        else
+            copy.push(from);
     }
     for (const [path, text] of dogsbayMdPageFiles(imported.pages, imported.nav))
         files.set(`content/${path}`, text);
@@ -60,5 +78,6 @@ export async function migrate(input) {
         navSource: imported.navSource,
         ledger: imported.ledger,
     }));
-    return { files, ledger: imported.ledger };
+    const read = corpus.missing();
+    return { files, ledger: [...unfetchedLedger(read), ...imported.ledger], unfetched: { read, copy: copy.sort() } };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dogsbay/format-vitepress",
-  "version": "0.2.0-beta.132",
+  "version": "0.2.0-beta.133",
   "description": "VitePress format plugin for Dogsbay — imports VitePress docs projects into TreeNode[] by translating VitePress containers, code-fence conventions, snippets and includes to Dogsbay-MD.",
   "type": "module",
   "main": "dist/index.js",
@@ -24,11 +24,11 @@
     "README.md"
   ],
   "dependencies": {
-    "@dogsbay/detect": "0.2.0-beta.132",
-    "@dogsbay/format-dogsbay-md": "0.2.0-beta.132",
-    "@dogsbay/corpus": "0.2.0-beta.132",
-    "@dogsbay/literal": "0.2.0-beta.132",
-    "@dogsbay/types": "0.2.0-beta.132"
+    "@dogsbay/corpus": "0.2.0-beta.133",
+    "@dogsbay/format-dogsbay-md": "0.2.0-beta.133",
+    "@dogsbay/detect": "0.2.0-beta.133",
+    "@dogsbay/literal": "0.2.0-beta.133",
+    "@dogsbay/types": "0.2.0-beta.133"
   },
   "devDependencies": {
     "@types/node": "^25.9.5",