@dogsbay/format-mdx 0.2.0-beta.15 → 0.2.0-beta.150

package/dist/index.js

@@ -1,2 +1,11 @@
-export { mdxToTree, extractHeadings } from "./parse.js";
-//# sourceMappingURL=index.js.map
+export { mdxToTree, parseMdx, parseAttrs, extractHeadings, } from "./parse.js";
+export { compileComponentConfig, } from "./adapter.js";
+export { fumadocsAdapter, apiMethodMapping, databaseTableMapping, resourceCardsMapping, MDX_BUILTIN_HANDLERS, parseJsObjectEntries, parseJsArrayElements, } from "./fumadocs.js";
+export { mintlifyAdapter } from "./mintlify.js";
+export { makeExtractMapping } from "./extract.js";
+export { parseTsTypeBlock, } from "./ts-type-block.js";
+export { buildFumadocsNav, detectFumadocsDir, } from "./meta-nav.js";
+export { buildMintlifyNav, detectMintlifyDir, mintlifyRedirects, } from "./mintlify-nav.js";
+export { mintlifyOpenApiSpecRef, buildMintlifyEndpointMap, openApiPageKey, } from "./mintlify-openapi.js";
+export { extractNavFromTsx, extractNavFromTsxFile, } from "./nav-extract.js";
+export { scanBalancedLiteral, splitTopLevel, isQuoteStart, captureConstLiteral, displayJsValue, } from "./js-scan.js";

package/dist/js-scan.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Shared quote/bracket-aware scanning helpers for statically reading JS/TSX
+ * data literals — no execution, ever.
+ *
+ * The one subtlety: apostrophes and quotes inside JSX TEXT content are not
+ * string delimiters (`<p>';--</p>` — better-auth's actual SQL-joke icon —
+ * breaks a naive tracker). A quote only OPENS a string in a value position:
+ * when the previous non-whitespace character is one that can precede a JS
+ * expression (`= ( [ { , : ? & | ! ;` or a `=>` arrow) or at the start of
+ * the scanned span. A bare `>` (JSX tag close) is NOT a value position —
+ * that is exactly where JSX text apostrophes live.
+ */
+/** Is src[i] a quote that starts a string (value position)? */
+export declare function isQuoteStart(src: string, i: number, spanStart: number): boolean;
+/**
+ * Scan a balanced literal starting at src[start] (which must be at or
+ * before the opening `{`/`[`/`(`). Returns the end index (exclusive, past
+ * the closing bracket) or -1 when the span never balances.
+ */
+export declare function scanBalancedLiteral(src: string, start: number): number;
+/**
+ * Capture the right-hand-side literal of a `const NAME = …` /
+ * `export const NAME = …` declaration (type annotations tolerated).
+ * Returns the raw literal text or null.
+ */
+export declare function captureConstLiteral(source: string, name: string): string | null;
+/** Unquote a raw JS value for display; non-literals pass through as source. */
+export declare function displayJsValue(raw: string): string;
+/**
+ * Split the top level of a balanced span into comma-separated pieces.
+ * `src` must already be the INNER text (without the outer brackets).
+ * Returns null when the span doesn't scan.
+ */
+export declare function splitTopLevel(src: string): string[] | null;

package/dist/js-scan.js

@@ -0,0 +1,123 @@
+/**
+ * Shared quote/bracket-aware scanning helpers for statically reading JS/TSX
+ * data literals — no execution, ever.
+ *
+ * The one subtlety: apostrophes and quotes inside JSX TEXT content are not
+ * string delimiters (`<p>';--</p>` — better-auth's actual SQL-joke icon —
+ * breaks a naive tracker). A quote only OPENS a string in a value position:
+ * when the previous non-whitespace character is one that can precede a JS
+ * expression (`= ( [ { , : ? & | ! ;` or a `=>` arrow) or at the start of
+ * the scanned span. A bare `>` (JSX tag close) is NOT a value position —
+ * that is exactly where JSX text apostrophes live.
+ */
+const VALUE_POSITION_CHARS = new Set([
+    "=", "(", "[", "{", ",", ":", "?", "&", "|", "!", ";", "+", "-", "*", "%",
+]);
+/** Is src[i] a quote that starts a string (value position)? */
+export function isQuoteStart(src, i, spanStart) {
+    const ch = src[i];
+    if (ch !== '"' && ch !== "'" && ch !== "`")
+        return false;
+    for (let k = i - 1; k >= spanStart; k--) {
+        const prev = src[k];
+        if (prev === " " || prev === "\t" || prev === "\n" || prev === "\r")
+            continue;
+        if (prev === ">")
+            return src[k - 1] === "="; // `=>` arrow body, not JSX close
+        return VALUE_POSITION_CHARS.has(prev);
+    }
+    return true; // start of span
+}
+/**
+ * Scan a balanced literal starting at src[start] (which must be at or
+ * before the opening `{`/`[`/`(`). Returns the end index (exclusive, past
+ * the closing bracket) or -1 when the span never balances.
+ */
+export function scanBalancedLiteral(src, start) {
+    let depth = 0;
+    let started = false;
+    let quote = null;
+    for (let i = start; i < src.length; i++) {
+        const ch = src[i];
+        if (quote) {
+            if (ch === quote && src[i - 1] !== "\\")
+                quote = null;
+            continue;
+        }
+        if (isQuoteStart(src, i, start)) {
+            quote = ch;
+            continue;
+        }
+        if (ch === "{" || ch === "[" || ch === "(") {
+            depth++;
+            started = true;
+        }
+        else if (ch === "}" || ch === "]" || ch === ")") {
+            depth--;
+            if (started && depth === 0)
+                return i + 1;
+        }
+    }
+    return -1;
+}
+/**
+ * Capture the right-hand-side literal of a `const NAME = …` /
+ * `export const NAME = …` declaration (type annotations tolerated).
+ * Returns the raw literal text or null.
+ */
+export function captureConstLiteral(source, name) {
+    const re = new RegExp(`(?:^|\\n)\\s*(?:export\\s+)?const\\s+${name.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;
+    return source.slice(start, end).trim();
+}
+/** Unquote a raw JS value for display; non-literals pass through as source. */
+export function displayJsValue(raw) {
+    const t = raw.trim();
+    const m = t.match(/^(["'`])([\s\S]*)\1$/);
+    return m ? m[2] : t;
+}
+/**
+ * Split the top level of a balanced span into comma-separated pieces.
+ * `src` must already be the INNER text (without the outer brackets).
+ * Returns null when the span doesn't scan.
+ */
+export function splitTopLevel(src) {
+    const pieces = [];
+    let depth = 0;
+    let quote = null;
+    let start = 0;
+    for (let i = 0; i < src.length; i++) {
+        const ch = src[i];
+        if (quote) {
+            if (ch === quote && src[i - 1] !== "\\")
+                quote = null;
+            continue;
+        }
+        if (isQuoteStart(src, i, start)) {
+            quote = ch;
+            continue;
+        }
+        if (ch === "{" || ch === "[" || ch === "(")
+            depth++;
+        else if (ch === "}" || ch === "]" || ch === ")")
+            depth--;
+        else if (ch === "," && depth === 0) {
+            const piece = src.slice(start, i).trim();
+            if (piece)
+                pieces.push(piece);
+            start = i + 1;
+        }
+    }
+    if (quote || depth !== 0)
+        return null;
+    const last = src.slice(start).trim();
+    if (last)
+        pieces.push(last);
+    return pieces;
+}

package/dist/meta-nav.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Fumadocs `meta.json` → NavItem[] builder.
+ *
+ * Fumadocs organizes navigation with per-folder `meta.json` files:
+ *
+ *   { "title": "Guide", "root": true, "pages": ["introduction", "...",
+ *     "email-password/sign-in-and-sign-up", "[GitHub](https://…)"] }
+ *
+ * Supported `pages` entry forms:
+ *   - "name"                — file (name.mdx / name.md) or folder
+ *   - "nested/path"         — page inside a subfolder
+ *   - "..."                 — rest expansion (unlisted items, alphabetical)
+ *   - "z...a"               — rest expansion, reverse alphabetical
+ *   - "!name"               — exclude from rest expansion
+ *   - "[Label](https://…)"  — external link
+ *   - "---Label---"         — separator (skipped: NavItem has no separator)
+ *
+ * Folders with `root: true` are Fumadocs "root folders" (tab-like separate
+ * trees); they are rendered as ordinary top-level groups here.
+ */
+import type { NavItem } from "@dogsbay/types";
+export interface FumadocsNavOptions {
+    /** Prefix for hrefs (e.g. "/docs"). */
+    hrefPrefix?: string;
+}
+/** Detect a Fumadocs content directory: meta.json + .md/.mdx pages. */
+export declare function detectFumadocsDir(path: string): boolean;
+export declare function buildFumadocsNav(rootDir: string, opts?: FumadocsNavOptions): NavItem[];

package/dist/meta-nav.js

@@ -0,0 +1,193 @@
+/**
+ * Fumadocs `meta.json` → NavItem[] builder.
+ *
+ * Fumadocs organizes navigation with per-folder `meta.json` files:
+ *
+ *   { "title": "Guide", "root": true, "pages": ["introduction", "...",
+ *     "email-password/sign-in-and-sign-up", "[GitHub](https://…)"] }
+ *
+ * Supported `pages` entry forms:
+ *   - "name"                — file (name.mdx / name.md) or folder
+ *   - "nested/path"         — page inside a subfolder
+ *   - "..."                 — rest expansion (unlisted items, alphabetical)
+ *   - "z...a"               — rest expansion, reverse alphabetical
+ *   - "!name"               — exclude from rest expansion
+ *   - "[Label](https://…)"  — external link
+ *   - "---Label---"         — separator (skipped: NavItem has no separator)
+ *
+ * Folders with `root: true` are Fumadocs "root folders" (tab-like separate
+ * trees); they are rendered as ordinary top-level groups here.
+ */
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+import YAML from "yaml";
+/** Detect a Fumadocs content directory: meta.json + .md/.mdx pages. */
+export function detectFumadocsDir(path) {
+    try {
+        if (!existsSync(join(path, "meta.json")))
+            return false;
+        return readdirSync(path).some((e) => e.endsWith(".mdx") || e.endsWith(".md"));
+    }
+    catch {
+        return false;
+    }
+}
+export function buildFumadocsNav(rootDir, opts = {}) {
+    const prefix = (opts.hrefPrefix ?? "").replace(/\/$/, "");
+    return walkDir(rootDir, rootDir, prefix);
+}
+function readMeta(dir) {
+    const metaPath = join(dir, "meta.json");
+    if (!existsSync(metaPath))
+        return undefined;
+    try {
+        const parsed = JSON.parse(readFileSync(metaPath, "utf-8"));
+        return parsed && typeof parsed === "object" ? parsed : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function pageTitle(filePath, fallback) {
+    try {
+        const source = readFileSync(filePath, "utf-8");
+        const match = /^---\n([\s\S]*?)\n---/.exec(source);
+        if (match) {
+            const fm = YAML.parse(match[1]);
+            if (fm && typeof fm.title === "string")
+                return fm.title;
+        }
+    }
+    catch {
+        // fall through to the filename
+    }
+    return fallback;
+}
+function humanize(name) {
+    return name
+        .replace(/[-_]/g, " ")
+        .replace(/\b\w/g, (c) => c.toUpperCase());
+}
+function resolvePageFile(dir, name) {
+    for (const ext of [".mdx", ".md"]) {
+        const p = join(dir, name + ext);
+        if (existsSync(p))
+            return p;
+    }
+    return null;
+}
+function slugFor(root, dir, name) {
+    const rel = join(dir, name).slice(root.length).replace(/\\/g, "/").replace(/^\//, "");
+    return rel;
+}
+/** One nav item for a file entry, or null when the file doesn't exist. */
+function fileItem(root, dir, name, prefix) {
+    const filePath = resolvePageFile(dir, name);
+    if (!filePath)
+        return null;
+    const slug = slugFor(root, dir, name);
+    // Root index → "/"; a subfolder's index → the folder path itself.
+    const href = slug === "index" ? `${prefix}/` : `${prefix}/${slug.replace(/\/index$/, "")}`;
+    return { label: pageTitle(filePath, humanize(name)), href };
+}
+const EXTERNAL_LINK_RE = /^\[(.*)\]\((.*)\)$/;
+const SEPARATOR_RE = /^---.*---$/;
+function walkDir(root, dir, prefix) {
+    const meta = readMeta(dir);
+    // Inventory of this folder's files and subfolders.
+    const files = new Set();
+    const folders = new Set();
+    for (const entry of readdirSync(dir)) {
+        const full = join(dir, entry);
+        if (statSync(full).isDirectory()) {
+            folders.add(entry);
+        }
+        else if ((entry.endsWith(".mdx") || entry.endsWith(".md")) &&
+            entry !== "llms.txt") {
+            files.add(entry.replace(/\.(mdx|md)$/, ""));
+        }
+    }
+    const restItems = (excluded, reverse) => {
+        const names = [...new Set([...files, ...folders])]
+            .filter((n) => !excluded.has(n))
+            .sort();
+        if (reverse)
+            names.reverse();
+        return names.flatMap((n) => itemFor(n));
+    };
+    const itemFor = (name) => {
+        if (folders.has(name)) {
+            const childDir = join(dir, name);
+            const childMeta = readMeta(childDir);
+            const children = walkDir(root, childDir, prefix);
+            if (children.length === 0)
+                return [];
+            return [{ label: childMeta?.title ?? humanize(name), children }];
+        }
+        const item = fileItem(root, dir, name, prefix);
+        return item ? [item] : [];
+    };
+    if (!meta?.pages) {
+        // No meta.json ordering — alphabetical, index first.
+        const excluded = new Set();
+        const items = [];
+        if (files.has("index")) {
+            const idx = fileItem(root, dir, "index", prefix);
+            if (idx)
+                items.push(idx);
+            excluded.add("index");
+        }
+        items.push(...restItems(excluded, false));
+        return items;
+    }
+    const consumed = new Set();
+    const excluded = new Set();
+    // Pre-scan exclusions so "..." earlier in the list still honors them.
+    for (const entry of meta.pages) {
+        if (entry.startsWith("!"))
+            excluded.add(entry.slice(1));
+    }
+    const hasRest = meta.pages.some((e) => e === "..." || e === "z...a");
+    const items = [];
+    for (const entry of meta.pages) {
+        if (entry.startsWith("!"))
+            continue;
+        if (SEPARATOR_RE.test(entry))
+            continue;
+        const linkMatch = EXTERNAL_LINK_RE.exec(entry);
+        if (linkMatch) {
+            items.push({ label: linkMatch[1], href: linkMatch[2] });
+            continue;
+        }
+        if (entry === "..." || entry === "z...a") {
+            items.push(...restItems(new Set([...consumed, ...excluded]), entry === "z...a"));
+            // Everything is consumed after a rest expansion.
+            for (const n of [...files, ...folders])
+                consumed.add(n);
+            continue;
+        }
+        if (entry.includes("/")) {
+            // Page inside a subfolder (e.g. "email-password/sign-in-and-sign-up")
+            const parts = entry.split("/");
+            const name = parts.pop();
+            const subDir = join(dir, ...parts);
+            const item = fileItem(root, subDir, name, prefix);
+            if (item)
+                items.push(item);
+            continue;
+        }
+        consumed.add(entry);
+        items.push(...itemFor(entry));
+    }
+    // Implicit rest expansion: when the meta has no explicit "...",
+    // unlisted files and folders are appended alphabetically instead of
+    // being hidden. Strict Fumadocs hides them — but sites with heavily
+    // customized sidebars (a hand-written page tree overriding meta.json)
+    // often leave meta.json stale, and an IMPORT that silently drops most
+    // pages from the nav loses real structure. Never-drop applies to
+    // navigation too; `!name` exclusions are still honored.
+    if (!hasRest) {
+        items.push(...restItems(new Set([...consumed, ...excluded]), false));
+    }
+    return items;
+}

package/dist/mintlify-nav.d.ts

@@ -0,0 +1,30 @@
+import type { NavItem } from "@dogsbay/types";
+export interface MintlifyNavOptions {
+    /** Prefixed onto every internal href (e.g. a base path). */
+    hrefPrefix?: string;
+}
+/**
+ * True when `dir` looks like a Mintlify docs source: a `docs.json`/`mint.json`
+ * that actually reads as a Mintlify config, plus md/mdx pages. The config sniff
+ * (a `navigation` key or a `mintlify` `$schema`) keeps an unrelated `docs.json`
+ * — e.g. TypeDoc's output — from being claimed by the mdx importer.
+ */
+export declare function detectMintlifyDir(dir: string): boolean;
+/**
+ * Build NavItem[] from a Mintlify config, or null when no config is present or
+ * it declares no navigation.
+ */
+export declare function buildMintlifyNav(source: string, opts?: MintlifyNavOptions): NavItem[] | null;
+/**
+ * Mintlify `redirects` as a source → destination map, `$ref` resolved.
+ *
+ * A docs site accumulates these as pages move, and its OWN pages then link to
+ * the old paths — Mintlify serves the redirect, so the link works and nobody
+ * notices it is stale. On import the redirect does not exist, so those links
+ * 404: measured on Mintlify's own docs, 16 internal links point at a redirect
+ * source, including `/installation` on the front page (→ `/cli/install`).
+ *
+ * `redirects` is itself commonly a `$ref` to a sibling file (121 entries in
+ * `redirects.json` here), so it is resolved the same way as navigation.
+ */
+export declare function mintlifyRedirects(source: string): Record<string, string>;