@dogsbay/format-mdx 0.2.0-beta.13 → 0.2.0-beta.130

package/dist/nav-extract.js

@@ -0,0 +1,134 @@
+/**
+ * Static sidebar extraction from a hardcoded Fumadocs page tree.
+ *
+ * Passing a hand-built `PageTree.Root` to `DocsLayout tree={…}` is a
+ * documented first-class Fumadocs pattern; sites that use it (better-auth's
+ * sidebar-content.tsx) keep the REAL sidebar in a TSX data literal and let
+ * meta.json go stale. Page trees must be serializable by design, so the
+ * literal is statically readable: this module captures the exported array
+ * and maps it to NavItem[] — no execution, ever (icons and other JSX
+ * values ride through the balanced scanner and are dropped).
+ *
+ * The mapping is shape-tolerant rather than better-auth-specific: an entry
+ * contributes a nav item when it has a string `title`/`name`/`label`;
+ * `href`/`url` become the link; the first array-valued key among
+ * `list`/`subpages`/`children`/`items`/`pages` becomes the children.
+ *
+ * Href prefix: sites hardcode their mount point (`/docs/introduction`).
+ * When every internal href shares the same first path segment it is
+ * stripped and replaced with the importer's own `hrefPrefix` (auto-detected
+ * — pass `stripPrefix` to override).
+ */
+import { readFileSync } from "node:fs";
+import { scanBalancedLiteral } from "./js-scan.js";
+import { parseJsArrayElements, parseJsObjectEntries } from "./fumadocs.js";
+const CHILD_KEYS = ["list", "subpages", "children", "items", "pages"];
+function unquote(raw) {
+    if (!raw)
+        return undefined;
+    const m = raw.trim().match(/^(["'`])([\s\S]*)\1$/);
+    return m ? m[2] : undefined;
+}
+function entryToItem(objSrc) {
+    const entries = parseJsObjectEntries(objSrc);
+    if (!entries)
+        return null;
+    const o = Object.fromEntries(entries);
+    const label = unquote(o.title) ?? unquote(o.name) ?? unquote(o.label);
+    if (!label)
+        return null;
+    const item = { label };
+    const href = unquote(o.href) ?? unquote(o.url);
+    if (href)
+        item.href = href;
+    if (o.external === "true" || href?.match(/^[a-z]+:\/\//))
+        item.external = true;
+    for (const key of CHILD_KEYS) {
+        const value = o[key]?.trim();
+        if (value?.startsWith("[")) {
+            const elements = parseJsArrayElements(value);
+            if (elements) {
+                const children = elements.map(entryToItem).filter((c) => c !== null);
+                if (children.length > 0)
+                    item.children = children;
+            }
+            break;
+        }
+    }
+    return item;
+}
+/** First path segment of an internal href ("/docs/x" → "/docs"). */
+function firstSegment(href) {
+    const m = href.match(/^(\/[^/]+)(\/|$)/);
+    return m ? m[1] : null;
+}
+function collectInternalHrefs(items, out) {
+    for (const item of items) {
+        if (item.href && !item.external)
+            out.push(item.href);
+        if (item.children)
+            collectInternalHrefs(item.children, out);
+    }
+}
+function toNavItems(items, stripPrefix, hrefPrefix) {
+    return items.map((item) => {
+        const nav = { label: item.label };
+        if (item.href) {
+            if (item.external) {
+                nav.href = item.href;
+            }
+            else {
+                let path = item.href;
+                if (stripPrefix && path.startsWith(stripPrefix)) {
+                    path = path.slice(stripPrefix.length) || "/";
+                }
+                nav.href = `${hrefPrefix}${path.startsWith("/") ? "" : "/"}${path}`;
+            }
+        }
+        if (item.children) {
+            nav.children = toNavItems(item.children, stripPrefix, hrefPrefix);
+        }
+        return nav;
+    });
+}
+/**
+ * Extract NavItem[] from TSX source containing an exported data-literal
+ * page tree. Returns null when the export is missing or doesn't scan —
+ * callers fall back to the meta.json walk (never guess).
+ */
+export function extractNavFromTsx(source, opts = {}) {
+    const exportName = opts.exportName ?? "contents";
+    const re = new RegExp(`export\\s+const\\s+${exportName.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\s*(?::[^=]*?)?=\\s*`);
+    const m = re.exec(source);
+    if (!m)
+        return null;
+    const start = m.index + m[0].length;
+    const end = scanBalancedLiteral(source, start);
+    if (end === -1)
+        return null;
+    const elements = parseJsArrayElements(source.slice(start, end).trim());
+    if (!elements || elements.length === 0)
+        return null;
+    const items = elements.map(entryToItem).filter((i) => i !== null);
+    if (items.length === 0)
+        return null;
+    // Auto-detect the hardcoded mount prefix ("/docs") when not given.
+    let stripPrefix = opts.stripPrefix;
+    if (stripPrefix === undefined) {
+        const hrefs = [];
+        collectInternalHrefs(items, hrefs);
+        const segments = new Set(hrefs.map(firstSegment));
+        stripPrefix =
+            segments.size === 1 && !segments.has(null) ? [...segments][0] : "";
+    }
+    return toNavItems(items, stripPrefix ?? "", (opts.hrefPrefix ?? "").replace(/\/$/, ""));
+}
+/** File-reading convenience for the CLI layer. */
+export function extractNavFromTsxFile(filePath, opts = {}) {
+    try {
+        return extractNavFromTsx(readFileSync(filePath, "utf-8"), opts);
+    }
+    catch {
+        return null;
+    }
+}

package/dist/parse.d.ts

@@ -8,12 +8,108 @@
  *   4. Parse markdown sections with markdown-it for inline formatting.
  *   5. Map components to TreeNode types.
  *
- * The MDX served by Mintlify/Next.js uses well-formed, XML-like JSX tags with
- * string attributes — no complex JSX expressions. This means a simple recursive
- * tag parser works without a full JSX/AST parser.
+ * The MDX served by Mintlify/Next.js/Fumadocs uses well-formed, XML-like JSX
+ * tags with string attributes — no complex JSX expressions. This means a
+ * simple recursive tag parser works without a full JSX/AST parser.
+ *
+ * Extension points (plans/format-fumadocs.md): the component registry is
+ * open — `parseMdx(source, { adapter, components })` merges
+ * builtins < adapter < per-source config. Unknown block components are
+ * NEVER dropped: they become `mdx-raw` nodes carrying the verbatim source
+ * span plus a fidelity-ledger entry.
  */
 import type { TreeNode } from "@dogsbay/types";
-export declare function mdxToTree(source: string): TreeNode[];
+import type { ComponentMapping, MdxAdapter, MdxLedgerEntry } from "./adapter.js";
+export interface MdxParseOptions {
+    /** Framework adapter (e.g. fumadocs) merged over the builtins. */
+    adapter?: MdxAdapter;
+    /** Per-source component mappings merged over builtins + adapter. */
+    components?: Record<string, ComponentMapping>;
+    /** Additional self-closing tag names. */
+    selfClosingTags?: string[];
+    /** Source file path — stamped onto ledger entries. */
+    file?: string;
+    /**
+     * Docs root. Needed to resolve a ROOT-relative snippet import
+     * (`import X from "/snippets/foo.mdx"`) — Mintlify resolves those against
+     * the docs root, not the filesystem root.
+     */
+    rootDir?: string;
+    /** Internal: absolute paths already being inlined, to break import cycles. */
+    inlining?: Set<string>;
+    /**
+     * Source-declared redirects (`source` → `destination`), applied to internal
+     * links so a page that links to a path the site redirects still resolves
+     * after import. See `rewriteInternalHref`.
+     */
+    linkRedirects?: Record<string, string>;
+}
+export interface MdxParseResult {
+    tree: TreeNode[];
+    /** Fidelity ledger: what was preserved-as-raw or deliberately stripped. */
+    ledger: MdxLedgerEntry[];
+    /** Same-file `export const` literals captured during parsing. */
+    moduleData: Record<string, string>;
+}
+/**
+ * Parse MDX into TreeNode[] + fidelity ledger.
+ */
+export declare function parseMdx(source: string, opts?: MdxParseOptions): MdxParseResult;
+/**
+ * Back-compat convenience: parse and return only the tree.
+ * Prefer `parseMdx` — it also returns the fidelity ledger.
+ */
+export declare function mdxToTree(source: string, opts?: MdxParseOptions): TreeNode[];
+/**
+ * Remove `{/* … *​/}` MDX comments, fence-aware.
+ *
+ * Only an expression whose ENTIRE body is a block comment is removed: `{foo /*
+ * note *​/}` is a real expression and must survive to the mdx-raw path. When
+ * the comment occupied a whole line, the line goes with it, so no blank
+ * paragraph is left behind.
+ */
+export declare function stripMdxComments(source: string): string;
+/**
+ * Rewrite an internal link so it resolves in the IMPORTED site.
+ *
+ * Two corrections, both measured on Mintlify's own docs, where they broke two
+ * of the four cards on the front page:
+ *
+ *  1. `/dir/index` → `/dir`. A `dir/index.mdx` page is routed at `/dir` (every
+ *     importer collapses it, and so does the nav), but links written to the
+ *     file path kept the `/index` and 404'd. 107 links in that corpus.
+ *  2. A path that the source's own `redirects` map moves — a docs site
+ *     accumulates these as pages are renamed, and its own pages go on linking
+ *     to the old path because the live site serves the redirect. After import
+ *     nothing serves it. 16 links, including `/installation` → `/cli/install`.
+ *
+ * Anchors and query strings are preserved, and redirect chains are followed
+ * with a seen-set so a cycle in someone's config cannot hang the import.
+ */
+export declare function rewriteInternalHref(href: string, redirects?: Record<string, string>): string;
+/** Collapse the opening tag (up to and incl. the first unquoted `>`, tracking
+ *  quotes across newlines) onto one line; leave content after the tag intact. */
+/**
+ * Rewrite JSX-only attributes on a LOWERCASE HTML tag into HTML markdown-it
+ * will accept.
+ *
+ * markdown-it's HTML rules require quoted or bare attribute values, so a JSX
+ * expression attribute — `style={{ borderRadius: "12px" }}` — makes the whole
+ * tag fail to parse as HTML and it is emitted as ESCAPED TEXT. On ollama that
+ * showed a reader a literal `&lt;img src="…" /&gt;` and lost the image: 25
+ * occurrences across 17 pages, 5 of them the page's only images.
+ *
+ * `style={{ … }}` converts (camelCase → kebab-case, the real CSS); any other
+ * expression attribute is dropped, because its value is JavaScript and there
+ * is nothing faithful to put in its place.
+ */
+export declare function normalizeJsxAttrs(tag: string, onDrop?: (attr: string) => void): string;
+/**
+ * Parse a JSX attribute string. Supports `key="v"`, `key='v'`,
+ * `key={expr}` (balanced braces — `{{obj}}` keeps the inner `{obj}`),
+ * and bare boolean attributes (`requireSession` → "true").
+ */
+export declare function parseAttrs(attrStr: string): Record<string, string>;
 interface Heading {
     depth: number;
     slug: string;
@@ -25,4 +121,3 @@ interface Heading {
  */
 export declare function extractHeadings(nodes: TreeNode[]): Heading[];
 export {};
-//# sourceMappingURL=parse.d.ts.map