@dogsbay/format-rst 0.2.0-beta.101

package/dist/loaders/sphinx.js

@@ -0,0 +1,194 @@
+/**
+ * Sphinx corpus loader.
+ *
+ * Detects a Sphinx project (`conf.py`), runs `sphinx-build -b xml` once for
+ * the whole project (resolving toctree, cross-refs, directives, autodoc),
+ * then enumerates the emitted per-doc XML and extracts nav from the master
+ * doc's toctree. The transform of each XML → Dogsbay-MD happens in the CLI
+ * layer (which reads the files); this loader owns discovery + nav.
+ *
+ * See plans/format-rst.md Phase 2.
+ */
+import { existsSync, mkdtempSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { join, relative } from "node:path";
+import { tmpdir } from "node:os";
+import { parseDocument } from "htmlparser2";
+import { sphinxBuildXml } from "../sidecar.js";
+// ── local dom guards (never instanceof — see transform.ts) ──────────────────
+function isTag(n) {
+    return n.type === "tag" || n.type === "script" || n.type === "style";
+}
+function els(n) {
+    return n.children.filter(isTag);
+}
+function text(n) {
+    let s = "";
+    for (const c of n.children) {
+        if (c.type === "text")
+            s += c.data ?? "";
+        else if (isTag(c))
+            s += text(c);
+    }
+    return s;
+}
+function firstDesc(n, tag) {
+    for (const c of els(n)) {
+        if (c.tagName === tag)
+            return c;
+        const d = firstDesc(c, tag);
+        if (d)
+            return d;
+    }
+    return undefined;
+}
+/** Find the Sphinx source dir (the dir with conf.py) at or below `dir`. */
+export function findSphinxSrc(dir) {
+    if (existsSync(join(dir, "conf.py")))
+        return dir;
+    // Common layouts: docs/, doc/, source/, docs/source/.
+    for (const cand of ["docs", "doc", "source", join("docs", "source"), join("doc", "source")]) {
+        const p = join(dir, cand);
+        if (existsSync(join(p, "conf.py")))
+            return p;
+    }
+    return null;
+}
+/** Read `master_doc`/`root_doc` from conf.py (best-effort regex). */
+function readRootDoc(srcDir) {
+    try {
+        const conf = readFileSync(join(srcDir, "conf.py"), "utf-8");
+        const m = conf.match(/^\s*(?:master_doc|root_doc)\s*=\s*["']([^"']+)["']/m);
+        if (m)
+            return m[1];
+    }
+    catch {
+        /* ignore */
+    }
+    return "index";
+}
+/** Enumerate every `.xml` under outDir as a doc (slug = path sans .xml). */
+function enumerateDocs(outDir) {
+    const docs = [];
+    const walk = (dir) => {
+        for (const name of readdirSync(dir)) {
+            const full = join(dir, name);
+            if (statSync(full).isDirectory())
+                walk(full);
+            else if (name.endsWith(".xml")) {
+                const slug = relative(outDir, full).replace(/\\/g, "/").replace(/\.xml$/, "");
+                docs.push({ slug, xmlPath: full });
+            }
+        }
+    };
+    walk(outDir);
+    return docs;
+}
+/** Resolve a toctree entry's refuri (relative to `docDir`) to an absolute
+ *  docname slug. Anchor-only / external refs return "". */
+function resolveDocSlug(refuri, docDir) {
+    if (!refuri || refuri.startsWith("#") || /^[a-z][a-z0-9+.-]*:/i.test(refuri))
+        return "";
+    const hash = refuri.indexOf("#");
+    const path = (hash === -1 ? refuri : refuri.slice(0, hash)).replace(/\.html$/i, "");
+    if (!path)
+        return "";
+    const segs = path.startsWith("/") ? [] : docDir ? docDir.split("/") : [];
+    for (const part of path.replace(/^\//, "").split("/")) {
+        if (part === "" || part === ".")
+            continue;
+        if (part === "..")
+            segs.pop();
+        else
+            segs.push(part);
+    }
+    return segs.join("/");
+}
+/**
+ * Build the full nav by following toctrees ACROSS documents. Each toctree
+ * entry points at a child doc; we recurse into that doc's own toctrees for
+ * deeper levels (the master doc alone gives only the top level). A visited
+ * set breaks cycles. Section-anchor sub-entries (the maxdepth expansion
+ * within a page) are skipped — those are on-page TOC, not sidebar nav; the
+ * sidebar mirrors the document hierarchy.
+ */
+function buildSphinxNav(rootDoc, docMap, hrefPrefix) {
+    const visited = new Set();
+    const navForDoc = (docSlug) => {
+        if (visited.has(docSlug))
+            return [];
+        visited.add(docSlug);
+        const xmlPath = docMap.get(docSlug);
+        if (!xmlPath)
+            return [];
+        let xml;
+        try {
+            xml = readFileSync(xmlPath, "utf-8");
+        }
+        catch {
+            return [];
+        }
+        const parsed = parseDocument(xml, { xmlMode: true });
+        const root = parsed.children.find((c) => isTag(c) && c.tagName === "document");
+        if (!root)
+            return [];
+        const docDir = docSlug.includes("/") ? docSlug.slice(0, docSlug.lastIndexOf("/")) : "";
+        const out = [];
+        const walk = (el) => {
+            for (const child of els(el)) {
+                if (child.tagName === "compound" && (child.attribs?.classes ?? "").includes("toctree-wrapper")) {
+                    for (const cp of els(child).filter((c) => c.tagName === "compact_paragraph")) {
+                        const captionEl = els(cp).find((c) => c.tagName === "title");
+                        const list = els(cp).find((c) => c.tagName === "bullet_list");
+                        const entries = [];
+                        if (list) {
+                            for (const li of els(list).filter((c) => c.tagName === "list_item")) {
+                                const ref = firstDesc(li, "reference");
+                                if (!ref)
+                                    continue;
+                                const label = text(ref).trim();
+                                const childSlug = resolveDocSlug(ref.attribs?.refuri ?? "", docDir);
+                                const item = childSlug
+                                    ? { label, href: `${hrefPrefix}/${childSlug}`.replace(/\/+/g, "/") }
+                                    : { label };
+                                if (childSlug) {
+                                    const kids = navForDoc(childSlug); // recurse into the child doc
+                                    if (kids.length)
+                                        item.children = kids;
+                                }
+                                entries.push(item);
+                            }
+                        }
+                        if (captionEl)
+                            out.push({ label: text(captionEl).trim(), children: entries });
+                        else
+                            out.push(...entries);
+                    }
+                }
+                else {
+                    walk(child);
+                }
+            }
+        };
+        walk(root);
+        return out;
+    };
+    return navForDoc(rootDoc);
+}
+/**
+ * Load a Sphinx project: build to XML, enumerate docs, extract nav.
+ * `outDir` defaults to a temp dir. Throws (via the sidecar) when Python /
+ * Sphinx is unavailable or the build fails.
+ */
+export function loadSphinx(sourceDir, hrefPrefix = "") {
+    const srcDir = findSphinxSrc(sourceDir);
+    if (!srcDir)
+        throw new Error(`No Sphinx conf.py found under ${sourceDir}`);
+    const outDir = mkdtempSync(join(tmpdir(), "dogsbay-sphinx-xml-"));
+    sphinxBuildXml(srcDir, outDir);
+    const docs = enumerateDocs(outDir);
+    const rootDoc = readRootDoc(srcDir);
+    const docMap = new Map(docs.map((d) => [d.slug, d.xmlPath]));
+    const nav = docMap.has(rootDoc) ? buildSphinxNav(rootDoc, docMap, hrefPrefix) : [];
+    return { srcDir, outDir, docs, nav, rootDoc };
+}
+//# sourceMappingURL=sphinx.js.map

package/dist/loaders/sphinx.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sphinx.js","sourceRoot":"","sources":["../../src/loaders/sphinx.ts"],"names":[],"mappings":"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"}

package/dist/parse.d.ts

@@ -0,0 +1,19 @@
+import type { TreeNode } from "@dogsbay/types";
+import { type RstLedgerEntry } from "./transform.js";
+export interface ParseRstResult {
+    tree: TreeNode[];
+    title?: string;
+    /** Translated Dogsbay-MD body (no frontmatter) — for migrate to disk. */
+    markdown: string;
+    ledger: RstLedgerEntry[];
+}
+export declare function parseRstFile(filePath: string, hrefPrefix?: string): ParseRstResult;
+/**
+ * Transform an already-obtained docutils XML string (no sidecar spawn).
+ * `docPath` is the doc's root-relative slug (Sphinx mode) — enables
+ * cross-ref (`:doc:`/`:ref:`) resolution to root-relative links.
+ * `hrefPrefix` (site basePath) is applied to those resolved links so they
+ * match the nav's hrefs on subpath deploys.
+ */
+export declare function parseRstXml(xml: string, docPath?: string, hrefPrefix?: string): ParseRstResult;
+//# sourceMappingURL=parse.d.ts.map

package/dist/parse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse.d.ts","sourceRoot":"","sources":["../src/parse.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAE/C,OAAO,EAA0B,KAAK,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAE7E,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,QAAQ,EAAE,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,yEAAyE;IACzE,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,cAAc,EAAE,CAAC;CAC1B;AAED,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,cAAc,CAGlF;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,cAAc,CAI9F"}

package/dist/parse.js

@@ -0,0 +1,30 @@
+/**
+ * `.rst` file → { tree, title, markdown, ledger }.
+ *
+ * Pipeline: sidecar (docutils/Sphinx → XML) → transform (XML AST →
+ * Dogsbay-MD) → dogsbayMdToTree (canonical parser → TreeNode). Mirrors
+ * format-gitbook's "translate to Dogsbay-MD, then reuse the parser" shape.
+ *
+ * `markdown` is what `migrate-rst` writes to disk; `tree` feeds the
+ * runtime path.
+ */
+import { dogsbayMdToTree } from "@dogsbay/format-dogsbay-md";
+import { rstFileToXml } from "./sidecar.js";
+import { docutilsXmlToDogsbayMd } from "./transform.js";
+export function parseRstFile(filePath, hrefPrefix) {
+    const xml = rstFileToXml(filePath, "plain");
+    return parseRstXml(xml, undefined, hrefPrefix);
+}
+/**
+ * Transform an already-obtained docutils XML string (no sidecar spawn).
+ * `docPath` is the doc's root-relative slug (Sphinx mode) — enables
+ * cross-ref (`:doc:`/`:ref:`) resolution to root-relative links.
+ * `hrefPrefix` (site basePath) is applied to those resolved links so they
+ * match the nav's hrefs on subpath deploys.
+ */
+export function parseRstXml(xml, docPath, hrefPrefix) {
+    const { markdown, title, ledger } = docutilsXmlToDogsbayMd(xml, { docPath, hrefPrefix });
+    const { tree } = dogsbayMdToTree(markdown);
+    return { tree, title, markdown, ledger };
+}
+//# sourceMappingURL=parse.js.map

package/dist/parse.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse.js","sourceRoot":"","sources":["../src/parse.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAE7D,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,EAAE,sBAAsB,EAAuB,MAAM,gBAAgB,CAAC;AAU7E,MAAM,UAAU,YAAY,CAAC,QAAgB,EAAE,UAAmB;IAChE,MAAM,GAAG,GAAG,YAAY,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;IAC5C,OAAO,WAAW,CAAC,GAAG,EAAE,SAAS,EAAE,UAAU,CAAC,CAAC;AACjD,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,WAAW,CAAC,GAAW,EAAE,OAAgB,EAAE,UAAmB;IAC5E,MAAM,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,sBAAsB,CAAC,GAAG,EAAE,EAAE,OAAO,EAAE,UAAU,EAAE,CAAC,CAAC;IACzF,MAAM,EAAE,IAAI,EAAE,GAAG,eAAe,CAAC,QAAQ,CAAC,CAAC;IAC3C,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC;AAC3C,CAAC"}

package/dist/sidecar.d.ts

@@ -0,0 +1,21 @@
+export declare class RstSidecarError extends Error {
+}
+/**
+ * Find a Python interpreter that has docutils, or null. Result is cached
+ * for the process (probing spawns a subprocess). Honours DOGSBAY_PYTHON.
+ */
+export declare function findPython(): string | null;
+/** Human-actionable message when no docutils-capable Python is found. */
+export declare function missingPythonMessage(): string;
+export declare function rstFileToXml(filePath: string, mode?: "plain" | "sphinx"): string;
+/** True when a docutils-capable Python is available. */
+export declare function sidecarAvailable(): boolean;
+/** True when the found Python also has Sphinx (needed for Sphinx mode). */
+export declare function sphinxAvailable(): boolean;
+/**
+ * Run `sphinx-build -b xml <srcDir> <outDir>` — a whole-project build that
+ * resolves toctree, cross-references, Sphinx directives, and autodoc into
+ * per-doc docutils XML files under outDir. Throws on failure.
+ */
+export declare function sphinxBuildXml(srcDir: string, outDir: string): void;
+//# sourceMappingURL=sidecar.d.ts.map

package/dist/sidecar.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sidecar.d.ts","sourceRoot":"","sources":["../src/sidecar.ts"],"names":[],"mappings":"AAmBA,qBAAa,eAAgB,SAAQ,KAAK;CAAG;AAY7C;;;GAGG;AACH,wBAAgB,UAAU,IAAI,MAAM,GAAG,IAAI,CAuB1C;AAED,yEAAyE;AACzE,wBAAgB,oBAAoB,IAAI,MAAM,CAM7C;AAYD,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,GAAE,OAAO,GAAG,QAAkB,GAAG,MAAM,CAczF;AAED,wDAAwD;AACxD,wBAAgB,gBAAgB,IAAI,OAAO,CAE1C;AAED,2EAA2E;AAC3E,wBAAgB,eAAe,IAAI,OAAO,CAazC;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAyBnE"}

package/dist/sidecar.js

@@ -0,0 +1,141 @@
+/**
+ * Python sidecar driver — spawn docutils (via `python/rst2dogsbay.py`) to
+ * parse a `.rst` file into docutils XML.
+ *
+ * rST has no reliable JS parser (see plans/format-rst.md); docutils is the
+ * reference implementation. We shell out to it — the same Python-subprocess
+ * pattern @dogsbay/autodoc-python already uses — and hand the resulting XML
+ * AST to the transformer. Python + docutils are a documented migrate-time
+ * requirement; a missing interpreter fails with a clear, actionable error.
+ */
+import { execFileSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+const HERE = dirname(fileURLToPath(import.meta.url));
+// dist/sidecar.js → package root → python/rst2dogsbay.py
+const SCRIPT = join(HERE, "..", "python", "rst2dogsbay.py");
+export class RstSidecarError extends Error {
+}
+/** Candidate interpreters, in priority order. `DOGSBAY_PYTHON` wins. */
+function candidatePythons() {
+    const out = [];
+    if (process.env.DOGSBAY_PYTHON)
+        out.push(process.env.DOGSBAY_PYTHON);
+    out.push("python3", "python");
+    return out;
+}
+let cachedPython;
+/**
+ * Find a Python interpreter that has docutils, or null. Result is cached
+ * for the process (probing spawns a subprocess). Honours DOGSBAY_PYTHON.
+ */
+export function findPython() {
+    if (cachedPython !== undefined)
+        return cachedPython;
+    if (!existsSync(SCRIPT)) {
+        // Package mis-packaged (python/ not shipped) — surface loudly.
+        throw new RstSidecarError(`rst2dogsbay.py not found at ${SCRIPT}`);
+    }
+    for (const py of candidatePythons()) {
+        try {
+            const out = execFileSync(py, [SCRIPT, "--check"], {
+                encoding: "utf-8",
+                timeout: 10_000,
+                stdio: ["ignore", "pipe", "pipe"],
+            });
+            if (out.startsWith("ok ")) {
+                cachedPython = py;
+                return py;
+            }
+        }
+        catch {
+            // interpreter missing or docutils absent — try the next candidate
+        }
+    }
+    cachedPython = null;
+    return null;
+}
+/** Human-actionable message when no docutils-capable Python is found. */
+export function missingPythonMessage() {
+    return ("reStructuredText import needs Python 3 with docutils, which was not found.\n" +
+        "  Install it:   python3 -m pip install docutils   (add 'sphinx' for Sphinx projects)\n" +
+        "  Or point Dogsbay at a specific interpreter:   DOGSBAY_PYTHON=/path/to/python\n");
+}
+/**
+ * Parse a `.rst` file to docutils XML. Throws RstSidecarError when no
+ * docutils-capable Python is available (caller decides fail vs skip), or
+ * when the sidecar itself errors on that file.
+ */
+/** Per-file docutils parse timeout (ms) — a hung parse must not wedge a run. */
+const FILE_TIMEOUT_MS = 60_000;
+/** Whole-project Sphinx build timeout (ms) — generous for large corpora. */
+const BUILD_TIMEOUT_MS = 15 * 60_000;
+export function rstFileToXml(filePath, mode = "plain") {
+    const py = findPython();
+    if (!py)
+        throw new RstSidecarError(missingPythonMessage());
+    try {
+        return execFileSync(py, [SCRIPT, "--mode", mode, filePath], {
+            encoding: "utf-8",
+            maxBuffer: 64 * 1024 * 1024, // large docs (numpy pages) exceed the 1MB default
+            timeout: FILE_TIMEOUT_MS,
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        throw new RstSidecarError(`docutils failed on ${filePath}: ${msg}`);
+    }
+}
+/** True when a docutils-capable Python is available. */
+export function sidecarAvailable() {
+    return findPython() !== null;
+}
+/** True when the found Python also has Sphinx (needed for Sphinx mode). */
+export function sphinxAvailable() {
+    const py = findPython();
+    if (!py)
+        return false;
+    try {
+        const out = execFileSync(py, [SCRIPT, "--check-sphinx"], {
+            encoding: "utf-8",
+            timeout: 10_000,
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        return out.startsWith("ok ");
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Run `sphinx-build -b xml <srcDir> <outDir>` — a whole-project build that
+ * resolves toctree, cross-references, Sphinx directives, and autodoc into
+ * per-doc docutils XML files under outDir. Throws on failure.
+ */
+export function sphinxBuildXml(srcDir, outDir) {
+    const py = findPython();
+    if (!py)
+        throw new RstSidecarError(missingPythonMessage());
+    // SECURITY: sphinx-build EXECUTES the project's conf.py and, for autodoc,
+    // IMPORTS its Python modules — arbitrary code from the source repo runs on
+    // this machine (inherent to Sphinx, same as running the project's own
+    // build). Warn so a user migrating an untrusted repo knows.
+    console.warn(`rst: running the project's Sphinx build (executes ${srcDir}/conf.py and imports its modules).\n` +
+        "  Only migrate repositories you trust. Use --loader plain to skip Sphinx and avoid executing project code.");
+    try {
+        execFileSync(py, [SCRIPT, "--sphinx-build", srcDir, outDir], {
+            encoding: "utf-8",
+            maxBuffer: 64 * 1024 * 1024,
+            timeout: BUILD_TIMEOUT_MS,
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        throw new RstSidecarError(`sphinx-build failed for ${srcDir}: ${msg}\n` +
+            "The project's conf.py may reference extensions/deps not installed in this Python env.");
+    }
+}
+//# sourceMappingURL=sidecar.js.map

package/dist/sidecar.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sidecar.js","sourceRoot":"","sources":["../src/sidecar.ts"],"names":[],"mappings":"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"}

package/dist/transform.d.ts

@@ -0,0 +1,19 @@
+export interface RstLedgerEntry {
+    construct: string;
+    note: string;
+}
+export interface TransformResult {
+    markdown: string;
+    /** Document title from the root `<document title="…">`, if any. */
+    title?: string;
+    ledger: RstLedgerEntry[];
+}
+export interface TransformOptions {
+    /** Docroot-relative slug of this doc (Sphinx mode). Enables cross-ref
+     *  resolution: `:doc:` refuris are relative to the current doc. */
+    docPath?: string;
+    /** URL prefix (site basePath) for resolved cross-doc links. */
+    hrefPrefix?: string;
+}
+export declare function docutilsXmlToDogsbayMd(xml: string, opts?: TransformOptions): TransformResult;
+//# sourceMappingURL=transform.d.ts.map

package/dist/transform.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transform.d.ts","sourceRoot":"","sources":["../src/transform.ts"],"names":[],"mappings":"AAwCA,MAAM,WAAW,cAAc;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,mEAAmE;IACnE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,cAAc,EAAE,CAAC;CAC1B;AA2BD,MAAM,WAAW,gBAAgB;IAC/B;uEACmE;IACnE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,+DAA+D;IAC/D,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,GAAE,gBAAqB,GAAG,eAAe,CA6BhG"}