@dogsbay/format-docusaurus 0.2.0-beta.78

package/dist/frontmatter.js

@@ -0,0 +1,45 @@
+/**
+ * Docusaurus frontmatter extraction.
+ *
+ * Returns a typed subset of the well-known docs frontmatter fields plus the
+ * full raw record (so downstream exporters can read custom fields) and the
+ * body with the YAML block stripped.
+ *
+ * Docs: https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-content-docs#markdown-front-matter
+ */
+import matter from "gray-matter";
+export function extractFrontmatter(source) {
+    // No frontmatter fence → nothing to strip.
+    if (source.split("\n")[0]?.trim() !== "---") {
+        return { frontmatter: {}, raw: {}, body: source };
+    }
+    let raw = {};
+    let body = source;
+    try {
+        const result = matter(source);
+        raw = result.data ?? {};
+        body = result.content;
+    }
+    catch {
+        // Malformed YAML — fall back to manual fence stripping, leave raw empty.
+        const lines = source.split("\n");
+        let end = 1;
+        while (end < lines.length && lines[end]?.trim() !== "---")
+            end++;
+        body = lines.slice(end + 1).join("\n");
+    }
+    const frontmatter = {
+        id: typeof raw.id === "string" ? raw.id : undefined,
+        title: typeof raw.title === "string" ? raw.title : undefined,
+        slug: typeof raw.slug === "string" ? raw.slug : undefined,
+        sidebar_position: typeof raw.sidebar_position === "number" ? raw.sidebar_position : undefined,
+        sidebar_label: typeof raw.sidebar_label === "string" ? raw.sidebar_label : undefined,
+        sidebar_class_name: typeof raw.sidebar_class_name === "string" ? raw.sidebar_class_name : undefined,
+        description: typeof raw.description === "string" ? raw.description : undefined,
+        hide_title: typeof raw.hide_title === "boolean" ? raw.hide_title : undefined,
+        draft: typeof raw.draft === "boolean" ? raw.draft : undefined,
+        tags: raw.tags,
+        pagination_label: typeof raw.pagination_label === "string" ? raw.pagination_label : undefined,
+    };
+    return { frontmatter, raw, body };
+}

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * @dogsbay/format-docusaurus — generic Docusaurus importer.
+ *
+ * Public API. Site-specific behaviour is provided by injected adapters
+ * (see the DocusaurusAdapter interface); this package ships none.
+ */
+export { docusaurusToTree, type ParseOptions } from "./parse-mdx.js";
+export { extractFrontmatter, type DocusaurusFrontmatter } from "./frontmatter.js";
+export { parseCodeMeta, type CodeMeta } from "./code-meta.js";
+export { findConfig, parseDocusaurusConfig, selectInstance, type DocsInstance, } from "./config.js";
+export { buildNav, buildNavFromDirectory, docIdToFilePath, makeDocHref, makeDocLabel, } from "./nav.js";
+export { buildNavFromSidebars, loadSidebars, type SidebarContext, type RawSidebars, type RawSidebarItem, } from "./sidebars.js";
+export { loadCjs } from "./load-cjs.js";
+export type { DocusaurusAdapter, ComponentMapping, PreprocessContext, } from "./adapter.js";
+export { plugin } from "./cli.js";

package/dist/index.js

@@ -0,0 +1,14 @@
+/**
+ * @dogsbay/format-docusaurus — generic Docusaurus importer.
+ *
+ * Public API. Site-specific behaviour is provided by injected adapters
+ * (see the DocusaurusAdapter interface); this package ships none.
+ */
+export { docusaurusToTree } from "./parse-mdx.js";
+export { extractFrontmatter } from "./frontmatter.js";
+export { parseCodeMeta } from "./code-meta.js";
+export { findConfig, parseDocusaurusConfig, selectInstance, } from "./config.js";
+export { buildNav, buildNavFromDirectory, docIdToFilePath, makeDocHref, makeDocLabel, } from "./nav.js";
+export { buildNavFromSidebars, loadSidebars, } from "./sidebars.js";
+export { loadCjs } from "./load-cjs.js";
+export { plugin } from "./cli.js";

package/dist/load-cjs.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Load a CJS/ESM module from an absolute or relative path and return its
+ * default export (or the whole module namespace for named-only exports).
+ */
+export declare function loadCjs<T = unknown>(modulePath: string): Promise<T>;

package/dist/load-cjs.js

@@ -0,0 +1,45 @@
+/**
+ * Single trust boundary for executing JavaScript from the source repo.
+ *
+ * Docusaurus config and sidebar files (`docusaurus.config.js`, `sidebars*.js`)
+ * are CommonJS modules that export plain objects/arrays. The simplest faithful
+ * way to read them is to `require()` them — this handles their own internal
+ * `require('./releases.json')` calls, computed values, and helper imports.
+ *
+ * SECURITY: this EXECUTES JavaScript from the source repository. That is
+ * acceptable for a local migration CLI pointed at a trusted repo (the same
+ * trust you already extend by running its `make build`). It is NOT safe for
+ * untrusted input. All such execution funnels through this one function so it
+ * can later be swapped for a sandboxed `node:vm` / worker evaluation without
+ * touching callers.
+ *
+ * Supports both `module.exports = X` (CommonJS) and `export default X` /
+ * named exports (ESM `.mjs` or `.js` with `"type":"module"`).
+ */
+import { createRequire } from "node:module";
+import { pathToFileURL } from "node:url";
+import { resolve } from "node:path";
+const require = createRequire(import.meta.url);
+/**
+ * Load a CJS/ESM module from an absolute or relative path and return its
+ * default export (or the whole module namespace for named-only exports).
+ */
+export async function loadCjs(modulePath) {
+    const abs = resolve(modulePath);
+    // Try CommonJS require first (the common case for Docusaurus config/sidebars).
+    try {
+        // Bust the require cache so re-imports in the same process re-read the file.
+        delete require.cache[require.resolve(abs)];
+        const mod = require(abs);
+        return (mod?.default ?? mod);
+    }
+    catch (err) {
+        // Fall back to dynamic import for ESM modules (.mjs / "type":"module").
+        const isEsmError = err instanceof Error &&
+            /require\(\) of ES Module|Cannot use import statement|ERR_REQUIRE_ESM/.test(err.message);
+        if (!isEsmError)
+            throw err;
+    }
+    const mod = await import(pathToFileURL(abs).href);
+    return (mod.default ?? mod);
+}

package/dist/nav.d.ts

@@ -0,0 +1,19 @@
+import type { NavItem } from "@dogsbay/types";
+/** Resolve a Docusaurus doc id to an on-disk file within the instance dir. */
+export declare function docIdToFilePath(instanceDir: string, id: string): string | null;
+/** doc id → href under hrefPrefix; trailing "/index" is dropped. */
+export declare function makeDocHref(hrefPrefix: string): (id: string) => string;
+/** doc id → label from frontmatter (sidebar_label/title), H1, or humanized id. */
+export declare function makeDocLabel(instanceDir: string): (id: string) => string;
+/**
+ * Build nav by scanning a directory tree. Used for `autogenerated` sidebar
+ * items and as the whole-instance fallback when there is no sidebar file.
+ */
+export declare function buildNavFromDirectory(instanceDir: string, hrefPrefix: string, scanDir?: string): NavItem[];
+export interface BuildNavOptions {
+    instanceDir: string;
+    hrefPrefix: string;
+    /** Absolute path to the sidebar module (from the config's sidebarPath). */
+    sidebarPath?: string | null;
+}
+export declare function buildNav(opts: BuildNavOptions): Promise<NavItem[]>;

package/dist/nav.js

@@ -0,0 +1,142 @@
+/**
+ * Navigation builder for a Docusaurus docs instance.
+ *
+ * Mode 1 (preferred): explicit sidebar from `sidebarPath` → buildNavFromSidebars.
+ * Mode 2 (fallback): scan the instance directory, reading `_category_.json` and
+ * frontmatter `sidebar_position`/`sidebar_label`, sorted by position.
+ *
+ * `buildNav` picks Mode 1 when a sidebar is present and loadable, else Mode 2.
+ */
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { join, basename } from "node:path";
+import { extractFrontmatter } from "./frontmatter.js";
+import { buildNavFromSidebars, loadSidebars, } from "./sidebars.js";
+const DOC_EXTS = [".mdx", ".md"];
+/** Resolve a Docusaurus doc id to an on-disk file within the instance dir. */
+export function docIdToFilePath(instanceDir, id) {
+    for (const ext of DOC_EXTS) {
+        const direct = join(instanceDir, id + ext);
+        if (existsSync(direct))
+            return direct;
+    }
+    for (const ext of DOC_EXTS) {
+        const asIndex = join(instanceDir, id, "index" + ext);
+        if (existsSync(asIndex))
+            return asIndex;
+    }
+    return null;
+}
+/** Humanize a slug segment: "managed-public-cloud" → "Managed public cloud". */
+function humanize(segment) {
+    const words = segment.replace(/[-_]+/g, " ").trim();
+    return words.charAt(0).toUpperCase() + words.slice(1);
+}
+/** First H1 in a markdown body, if any. */
+function firstH1(body) {
+    const m = body.match(/^#\s+(.+?)\s*$/m);
+    return m ? m[1].trim() : undefined;
+}
+/** doc id → href under hrefPrefix; trailing "/index" is dropped. */
+export function makeDocHref(hrefPrefix) {
+    const prefix = hrefPrefix.replace(/\/$/, "");
+    return (id) => {
+        const clean = id.replace(/\/index$/, "").replace(/^index$/, "");
+        return clean ? `${prefix}/${clean}` : prefix;
+    };
+}
+/** doc id → label from frontmatter (sidebar_label/title), H1, or humanized id. */
+export function makeDocLabel(instanceDir) {
+    return (id) => {
+        const filePath = docIdToFilePath(instanceDir, id);
+        if (filePath) {
+            const src = readFileSync(filePath, "utf-8");
+            const { frontmatter, body } = extractFrontmatter(src);
+            if (frontmatter.sidebar_label)
+                return frontmatter.sidebar_label;
+            if (frontmatter.title)
+                return frontmatter.title;
+            const h1 = firstH1(body);
+            if (h1)
+                return h1;
+        }
+        const seg = id.replace(/\/index$/, "").split("/").pop() || id;
+        return humanize(seg);
+    };
+}
+function readCategoryMeta(dir) {
+    const p = join(dir, "_category_.json");
+    if (!existsSync(p))
+        return {};
+    try {
+        return JSON.parse(readFileSync(p, "utf-8"));
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * Build nav by scanning a directory tree. Used for `autogenerated` sidebar
+ * items and as the whole-instance fallback when there is no sidebar file.
+ */
+export function buildNavFromDirectory(instanceDir, hrefPrefix, scanDir = instanceDir) {
+    const docHref = makeDocHref(hrefPrefix);
+    const entries = [];
+    for (const name of readdirSync(scanDir)) {
+        if (name.startsWith("_"))
+            continue; // _category_.json, _includes, etc.
+        const full = join(scanDir, name);
+        const stat = statSync(full);
+        if (stat.isDirectory()) {
+            const meta = readCategoryMeta(full);
+            const children = buildNavFromDirectory(instanceDir, hrefPrefix, full);
+            if (children.length === 0)
+                continue;
+            const nav = { label: meta.label ?? humanize(name), children };
+            if (meta.link?.type === "doc" && meta.link.id)
+                nav.href = docHref(meta.link.id);
+            entries.push({ nav, position: meta.position ?? Number.MAX_SAFE_INTEGER, sortKey: name });
+            continue;
+        }
+        if (!DOC_EXTS.some((e) => name.endsWith(e)))
+            continue;
+        if (name === "index.mdx" || name === "index.md")
+            continue; // category overview, not a child
+        const src = readFileSync(full, "utf-8");
+        const { frontmatter, body } = extractFrontmatter(src);
+        const id = relativeDocId(instanceDir, full);
+        const label = frontmatter.sidebar_label ?? frontmatter.title ?? firstH1(body) ?? humanize(basename(name).replace(/\.mdx?$/, ""));
+        entries.push({
+            nav: { label, href: docHref(id) },
+            position: frontmatter.sidebar_position ?? Number.MAX_SAFE_INTEGER,
+            sortKey: name,
+        });
+    }
+    entries.sort((a, b) => a.position !== b.position ? a.position - b.position : a.sortKey.localeCompare(b.sortKey));
+    return entries.map((e) => e.nav);
+}
+/** File path → doc id relative to the instance dir (no extension, "/index" kept). */
+function relativeDocId(instanceDir, filePath) {
+    let rel = filePath.slice(instanceDir.length).replace(/\\/g, "/").replace(/^\//, "");
+    rel = rel.replace(/\.mdx?$/, "");
+    return rel;
+}
+export async function buildNav(opts) {
+    const { instanceDir, hrefPrefix, sidebarPath } = opts;
+    if (sidebarPath && existsSync(sidebarPath)) {
+        const ctx = {
+            docHref: makeDocHref(hrefPrefix),
+            docLabel: makeDocLabel(instanceDir),
+            expandAutogenerated: (dirName) => buildNavFromDirectory(instanceDir, hrefPrefix, join(instanceDir, dirName)),
+        };
+        try {
+            const sidebars = await loadSidebars(sidebarPath);
+            const nav = buildNavFromSidebars(sidebars, ctx);
+            if (nav.length > 0)
+                return nav;
+        }
+        catch (err) {
+            console.warn(`Warning: could not load sidebar ${sidebarPath} (${err.message}); falling back to directory scan.`);
+        }
+    }
+    return buildNavFromDirectory(instanceDir, hrefPrefix);
+}

package/dist/parse-mdx.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Generic Docusaurus MDX parser.
+ *
+ * Reads a standard Docusaurus `.mdx`/`.md` body and produces TreeNode[].
+ * Handles only built-in Docusaurus syntax:
+ *   - :::admonitions (note/tip/info/warning/danger/caution) with optional title
+ *   - <Tabs> / <TabItem value label>
+ *   - <details> / <summary>
+ *   - <CodeBlock> and fenced code with metastrings (title/{ranges}/showLineNumbers)
+ *   - <DocCardList> / <DocCard> (theme built-ins → placeholder + warning)
+ *   - import/export MDX statements (stripped)
+ *
+ * Site-specific components, variable substitution, and partial includes are
+ * the job of an injected `DocusaurusAdapter` — never this file.
+ */
+import type { TreeNode, NavItem } from "@dogsbay/types";
+import type { DocusaurusAdapter, PreprocessContext } from "./adapter.js";
+export interface ParseOptions {
+    adapter?: DocusaurusAdapter;
+    /** Docusaurus routeBasePath of the instance (e.g. "calico"); used for link rewrite. */
+    routeBasePath?: string;
+    /** Dogsbay href prefix to rewrite internal links to (default "/docs"). */
+    hrefPrefix?: string;
+    /**
+     * Slug of the file being parsed (e.g. "guides/install"). Relative doc links
+     * (`../foo.mdx`) resolve against its directory into absolute hrefs.
+     */
+    currentSlug?: string;
+    /**
+     * Asset-root prefix for root-absolute image srcs (e.g. "/_assets"). Set when
+     * the project's static dir is mounted into `_assets`; maps `/img/x` →
+     * `/_assets/img/x`. Omitted → image srcs are left as-is.
+     */
+    assetPrefix?: string;
+    /**
+     * Resolve a Docusaurus doc id → its served href + title. Used to fill in
+     * `card` nodes that reference a target by `docId` (e.g. `<DocCardLink>`).
+     */
+    resolveDoc?: (docId: string) => {
+        href: string;
+        title: string;
+    } | undefined;
+    /**
+     * Resolve the current page's sidebar-category children → nav items, used to
+     * build a real `cards` grid for `<DocCardList>`. Returns undefined when the
+     * page isn't a category index (→ DocCardList falls back to a placeholder).
+     */
+    resolveDocCardList?: (currentSlug: string) => NavItem[] | undefined;
+    /** Context passed to the adapter's preprocess hook. */
+    preprocessContext?: PreprocessContext;
+    /** Warning sink (e.g. for DocCardList placeholders). */
+    onWarn?: (msg: string) => void;
+}
+export declare function docusaurusToTree(source: string, options?: ParseOptions): TreeNode[];