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

package/dist/import.d.ts

@@ -24,5 +24,7 @@ export interface VitepressCorpusImport {
     components: Record<string, number>;
     /** Per-page constructs mapped with caveats, pages that failed, and the loader's warnings. */
     ledger: ImportLedgerEntry[];
+    /** The corpus file each page was converted from: `sources[i]` is `pages[i]`'s. */
+    sources: string[];
 }
 export declare function importVitepressCorpus(corpus: Corpus, opts?: VitepressLoadOptions): VitepressCorpusImport;

package/dist/import.js

@@ -8,6 +8,7 @@ export function importVitepressCorpus(corpus, opts = {}) {
     const pages = [];
     const components = {};
     const ledger = [];
+    const sources = [];
     for (const ps of loaded.pages) {
         try {
             const content = corpus.text(ps.path);
@@ -30,6 +31,7 @@ export function importVitepressCorpus(corpus, opts = {}) {
             const heroName = typeof frontmatter.hero?.name === "string"
                 ? (frontmatter.hero.name)
                 : undefined;
+            sources.push(ps.path);
             pages.push({
                 slug: ps.slug,
                 title: fmTitle || h1?.text || heroName || titleFromSlug(ps.slug),
@@ -72,5 +74,6 @@ export function importVitepressCorpus(corpus, opts = {}) {
         warnings: loaded.warnings,
         components,
         ledger,
+        sources,
     };
 }

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 { dogsbayMdPageFiles, mountCopies } from "@dogsbay/format-dogsbay-md/browser";
+import { corpusFromMap, pageSources, pendingCopies, unfetchedMessage, withPages } from "@dogsbay/corpus";
+import { dogsbayMdPageFiles, dogsbayMdPagePath, 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,26 +44,51 @@ 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: [], copyTo: [] } };
+        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
-    for (const { from, to } of mountCopies(corpus.paths, imported.assetDirs)) {
+    const pageFiles = dogsbayMdPageFiles(imported.pages, imported.nav);
+    // One file per output path, the last mount's (public/ and .vitepress/public/ both land in
+    // _assets/), whether its bytes were given or not; a page at the same path wins
+    const winners = new Map();
+    for (const { from, to } of mountCopies(corpus.paths, imported.assetDirs))
+        winners.set(to, from);
+    const copy = [];
+    for (const [to, from] of winners) {
+        if (pageFiles.has(to))
+            continue;
         const bytes = input.files.get(from);
         if (bytes !== undefined)
             files.set(`content/${to}`, bytes);
+        else
+            copy.push({ from, to: `content/${to}` });
     }
-    for (const [path, text] of dogsbayMdPageFiles(imported.pages, imported.nav))
+    for (const [path, text] of pageFiles)
         files.set(`content/${path}`, text);
+    // Each note about a page's file names the page written from it
+    const pageOf = pageSources(imported.pages.map((p, i) => ({ file: imported.sources[i], path: `content/${dogsbayMdPagePath(p)}` })));
+    const ledger = withPages(imported.ledger, pageOf);
     files.set("dogsbay.config.yml", buildConfig(siteName, input.siteUrl));
     files.set("MIGRATION.md", migrationNotes({
         siteName,
         sourceLabel: input.sourceLabel ?? "VitePress project",
         pages: imported.pages.length,
         navSource: imported.navSource,
-        ledger: imported.ledger,
+        ledger,
     }));
-    return { files, ledger: imported.ledger };
+    const read = corpus.missing();
+    return { files, ledger: [...unfetchedLedger(read), ...ledger], unfetched: { read, ...pendingCopies(copy) } };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dogsbay/format-vitepress",
-  "version": "0.2.0-beta.132",
+  "version": "0.2.0-beta.134",
   "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.134",
+    "@dogsbay/detect": "0.2.0-beta.134",
+    "@dogsbay/format-dogsbay-md": "0.2.0-beta.134",
+    "@dogsbay/literal": "0.2.0-beta.134",
+    "@dogsbay/types": "0.2.0-beta.134"
   },
   "devDependencies": {
     "@types/node": "^25.9.5",