@dogsbay/format-starlight 0.2.0-beta.0

package/dist/adapter.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Site adapter — maps site-specific components to TreeNode types.
+ *
+ * The core Starlight parser handles built-in components (Tabs, Steps, Aside, etc.).
+ * Adapters handle custom components that specific sites add on top of Starlight.
+ *
+ * Usage:
+ *   starlightToTree(source)                          // core only
+ *   starlightToTree(source, { adapter: cloudflare }) // core + cloudflare
+ */
+export interface ComponentMapping {
+    /** TreeNode type to produce (e.g. "card", "callout", "badge") */
+    type: string;
+    /** Extract props from JSX attributes */
+    propsFromAttrs?: (attrs: Record<string, string>) => Record<string, unknown>;
+    /** Whether this component wraps children */
+    container: boolean;
+    /** Strip the component entirely. If container=true, inner content is kept. */
+    strip?: boolean;
+}
+export interface SiteAdapter {
+    /** Adapter name (e.g. "cloudflare") */
+    name: string;
+    /** Block-level component mappings (components that appear on their own line) */
+    components: Record<string, ComponentMapping>;
+    /** Self-closing tags (no closing tag expected) */
+    selfClosingTags?: string[];
+    /**
+     * Inline component transformations applied to source text before parsing.
+     * These handle components that appear within prose text (not on their own line).
+     * Each entry: [regex, replacement string or function]
+     */
+    inlineTransforms?: [RegExp, string][];
+    /**
+     * Resolve include/partial component tags in source text.
+     * Called before all other processing (inline transforms, directives, etc.)
+     * so that inlined content gets full parser treatment.
+     *
+     * @param source - MDX source text
+     * @param partialsDir - Base directory for partial files (auto-detected or CLI flag)
+     * @returns Source with include tags replaced by partial content
+     */
+    resolveIncludes?: (source: string, partialsDir?: string) => string;
+    /** Frontmatter field name that carries the redirect/external link URL */
+    redirectField?: string;
+}

package/dist/adapter.js

@@ -0,0 +1,11 @@
+/**
+ * Site adapter — maps site-specific components to TreeNode types.
+ *
+ * The core Starlight parser handles built-in components (Tabs, Steps, Aside, etc.).
+ * Adapters handle custom components that specific sites add on top of Starlight.
+ *
+ * Usage:
+ *   starlightToTree(source)                          // core only
+ *   starlightToTree(source, { adapter: cloudflare }) // core + cloudflare
+ */
+export {};

package/dist/adapters/cloudflare.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Cloudflare adapter for format-starlight.
+ *
+ * Maps Cloudflare-specific custom components used across developers.cloudflare.com.
+ * These are layered on top of the core Starlight component mappings.
+ *
+ * Source: https://github.com/cloudflare/cloudflare-docs/tree/production/src/components
+ */
+import type { SiteAdapter } from "../adapter.js";
+export declare const cloudflareAdapter: SiteAdapter;

package/dist/adapters/cloudflare.js

@@ -0,0 +1,442 @@
+/**
+ * Cloudflare adapter for format-starlight.
+ *
+ * Maps Cloudflare-specific custom components used across developers.cloudflare.com.
+ * These are layered on top of the core Starlight component mappings.
+ *
+ * Source: https://github.com/cloudflare/cloudflare-docs/tree/production/src/components
+ */
+import { readFileSync, existsSync } from "node:fs";
+import { join, dirname } from "node:path";
+import TOML from "@iarna/toml";
+import { parse as jsoncParse } from "jsonc-parser";
+// ── Indentation helper ─────────────────────────────────
+/**
+ * Indent all lines of content to match the indentation of the original tag.
+ * Critical for resolved content inside list items, Steps, etc. — without
+ * matching indentation, markdown-it treats the content as breaking out of
+ * the parent block context.
+ */
+function indentContent(content, indent) {
+    if (!indent)
+        return content;
+    return content.split("\n").map((line) => line ? `${indent}${line}` : line).join("\n");
+}
+let dashRoutesCache = null;
+function loadDashRoutes(partialsDir) {
+    if (dashRoutesCache)
+        return dashRoutesCache;
+    // Routes are at src/content/dash-routes/ — sibling of src/content/partials/
+    const contentDir = dirname(partialsDir);
+    const routesDir = join(contentDir, "dash-routes");
+    const routes = [];
+    for (const file of ["core.json", "core-manually-defined.json"]) {
+        const path = join(routesDir, file);
+        if (existsSync(path)) {
+            try {
+                const data = JSON.parse(readFileSync(path, "utf-8"));
+                routes.push(...data);
+            }
+            catch { /* ignore parse errors */ }
+        }
+    }
+    dashRoutesCache = routes;
+    return routes;
+}
+function resolveDashButton(source, partialsDir) {
+    if (!partialsDir)
+        return source.replace(/<DashButton\s[^>]*\/>/g, "");
+    const routes = loadDashRoutes(partialsDir);
+    return source.replace(/<DashButton\s+url="([^"]*)"[^>]*\/>/g, (_match, url) => {
+        const route = routes.find((r) => r.deeplink === url);
+        const name = route?.name || "dashboard";
+        const href = `https://dash.cloudflare.com${url}`;
+        return `<LinkButton href="${href}">Go to ${name}</LinkButton>`;
+    });
+}
+const commands = {
+    npm: { add: "npm i", create: "npm create", dlx: "npx", exec: "npx", install: "npm install", run: "npm run", remove: "npm uninstall", dev: "-D" },
+    yarn: { add: "yarn add", create: "yarn create", dlx: "yarn dlx", exec: "yarn", install: "yarn install", run: "yarn run", remove: "yarn remove", dev: "-D" },
+    pnpm: { add: "pnpm add", create: "pnpm create", dlx: "pnpx", exec: "pnpm", install: "pnpm install", run: "pnpm run", remove: "pnpm remove", dev: "-D" },
+    bun: { add: "bun add", install: "bun install", remove: "bun remove", dev: "-d" },
+};
+const MANAGERS = ["npm", "yarn", "pnpm", "bun"];
+function getCommand(mgr, type, pkg, opts = {}) {
+    let cmd = commands[mgr][type];
+    if (cmd === undefined)
+        return undefined;
+    if (opts.prefix)
+        cmd = `${opts.prefix} ${cmd}`;
+    if (opts.dev && type === "add")
+        cmd += ` ${commands[mgr].dev}`;
+    if (pkg) {
+        const processedPkg = type === "create" && mgr === "yarn"
+            ? pkg.replace(/@(?![^@]*\/)[^\s]*$/, "") : pkg;
+        cmd += ` ${processedPkg}`;
+    }
+    if (opts.args) {
+        cmd += `${mgr === "npm" && !["dlx", "exec", "run"].includes(type) ? " --" : ""} ${opts.args}`;
+    }
+    return cmd;
+}
+/**
+ * Resolve `<PackageManagers>` to Tabs with npm/yarn/pnpm/bun commands.
+ */
+function resolvePackageManagers(source) {
+    return source.replace(/^([ \t]*)<PackageManagers\s+([\s\S]*?)\/>/gm, (_match, indent, attrsStr) => {
+        // Parse attributes
+        const type = (attrsStr.match(/type\s*=\s*"([^"]*)"/)?.[1] || "add");
+        const pkg = attrsStr.match(/pkg\s*=\s*"([^"]*)"/)?.[1];
+        const args = attrsStr.match(/args\s*=\s*(?:"([^"]*)"|{["']([^"']*)['"]})/)?.[1]
+            || attrsStr.match(/args\s*=\s*\{?"?([^"}\s]*)"?\}?/)?.[1];
+        const dev = attrsStr.includes("dev");
+        const prefix = attrsStr.match(/prefix\s*=\s*"([^"]*)"/)?.[1];
+        const tabs = MANAGERS
+            .map((mgr) => {
+            const cmd = getCommand(mgr, type, pkg, { args, dev, prefix });
+            return cmd ? `<TabItem label="${mgr}">\n\n\`\`\`sh\n${cmd}\n\`\`\`\n\n</TabItem>` : null;
+        })
+            .filter(Boolean)
+            .join("\n");
+        return indentContent(`<Tabs>\n${tabs}\n</Tabs>`, indent);
+    });
+}
+// ── WranglerConfig resolution ───────────────────────────
+/**
+ * Resolve `<WranglerConfig>` by extracting the inner code block,
+ * converting between JSONC and TOML, and outputting as Tabs.
+ *
+ * Handles:
+ * - `$today` magic string → current date (YYYY-MM-DD)
+ * - Bidirectional JSONC ↔ TOML conversion
+ * - "Set this to today's date" comment injection
+ * - `$schema` property addition for JSONC output
+ */
+function resolveWranglerConfig(source) {
+    return source.replace(/^([ \t]*)<WranglerConfig[^>]*>([\s\S]*?)<\/WranglerConfig>/gm, (_match, indent, inner) => {
+        // Extract code block content: ```lang\ncode\n```
+        const codeMatch = inner.match(/```(\w+)\s*\n([\s\S]*?)```/);
+        if (!codeMatch)
+            return inner.trim();
+        const lang = codeMatch[1].toLowerCase();
+        let code = codeMatch[2].trim();
+        // Replace $today with current date
+        const hadToday = /\$today/i.test(code);
+        const today = new Date().toISOString().split("T")[0];
+        code = code.replace(/\$today/gi, today);
+        try {
+            let jsonc;
+            let toml;
+            if (lang === "toml") {
+                toml = code;
+                const parsed = TOML.parse(code);
+                jsonc = JSON.stringify(parsed, null, 4);
+            }
+            else {
+                // JSONC or JSON
+                const parsed = jsoncParse(code);
+                jsonc = JSON.stringify(parsed, null, 4);
+                toml = TOML.stringify(parsed);
+            }
+            // Inject compatibility_date comment when $today was used
+            if (hadToday) {
+                toml = toml.replace(/^(\s*)(.*compatibility_date.*)/m, "$1# Set this to today's date\n$1$2");
+                jsonc = jsonc.replace(/^(\s*)(.*compatibility_date.*)/m, "$1// Set this to today's date\n$1$2");
+            }
+            const result = `<Tabs>
+<TabItem label="wrangler.jsonc">
+
+\`\`\`jsonc
+${jsonc}
+\`\`\`
+
+</TabItem>
+<TabItem label="wrangler.toml">
+
+\`\`\`toml
+${toml}\`\`\`
+
+</TabItem>
+</Tabs>`;
+            return indentContent(result, indent);
+        }
+        catch {
+            // If conversion fails, output the original code block
+            return indentContent(`\`\`\`${lang}\n${code}\n\`\`\``, indent);
+        }
+    });
+}
+/**
+ * Resolve JSX switch expressions that remain after param substitution.
+ *
+ * Pattern: {(function() { switch('value') { case 'value': return (<content>); ... } })()}
+ *
+ * Extracts the switch value, finds the matching case, and returns its content.
+ * Falls back to stripping the entire expression if no match is found.
+ */
+function resolveJsxSwitch(content) {
+    return content.replace(/\{\(function\s*\(\)\s*\{[\s\S]*?switch\s*\((?:'([^']*)'|"([^"]*)")\)\s*\{([\s\S]*?)\}\s*\}\)\(\)\}/g, (_match, val1, val2, cases) => {
+        const switchValue = val1 ?? val2 ?? "";
+        // Find the matching case
+        const caseRegex = new RegExp(`case\\s+['"]${switchValue.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}['"]\\s*:\\s*return\\s*\\(([\\s\\S]*?)\\);`);
+        const match = cases.match(caseRegex);
+        if (match) {
+            // Clean up the JSX: strip <ul>/<li> wrappers, convert to markdown
+            let html = match[1].trim();
+            // Convert <li>...</li> to markdown list items
+            html = html.replace(/<ul>\s*/g, "");
+            html = html.replace(/<\/ul>\s*/g, "");
+            html = html.replace(/<li>([\s\S]*?)<\/li>/g, "- $1");
+            // Convert <em>...</em> to *...*
+            html = html.replace(/<em>([\s\S]*?)<\/em>/g, "*$1*");
+            // Convert <code>...</code> to `...`
+            html = html.replace(/<code>([\s\S]*?)<\/code>/g, "`$1`");
+            return html.trim();
+        }
+        return ""; // No matching case — strip the expression
+    });
+}
+// ── Raw file import resolution ──────────────────────────
+/**
+ * Resolve `import X from "~/path?raw"` by reading the file and
+ * substituting `{X}` with the file content in the source.
+ * Vite/Astro's ?raw imports file contents as strings.
+ */
+function resolveRawImports(source, partialsDir) {
+    if (!partialsDir)
+        return source;
+    // src/content/partials/ → src/ (go up two levels to repo src/)
+    const srcDir = dirname(dirname(partialsDir));
+    const importRegex = /^import\s+(\w+)\s+from\s+["']~\/([^"']+)\?raw["']\s*;?\s*$/gm;
+    let result = source;
+    let match;
+    while ((match = importRegex.exec(source)) !== null) {
+        const varName = match[1];
+        const filePath = join(srcDir, match[2]);
+        if (existsSync(filePath)) {
+            try {
+                const content = readFileSync(filePath, "utf-8");
+                result = result.replace(match[0], ""); // remove import line
+                // If used in <Code code={X} lang="..." />, replace with a fenced code block
+                const codeTagRegex = new RegExp(`<Code\\s+code=\\{${varName}\\}[^>]*(?:lang=["']([^"']*)["'])?[^>]*/>`);
+                const codeMatch = result.match(codeTagRegex);
+                if (codeMatch) {
+                    const lang = codeMatch[1] || "plaintext";
+                    // Use a fence that doesn't appear in the content
+                    let fence = "```";
+                    const backtickRuns = content.match(/`{3,}/g);
+                    if (backtickRuns) {
+                        const maxLen = Math.max(...backtickRuns.map((r) => r.length));
+                        fence = "`".repeat(maxLen + 1);
+                    }
+                    result = result.replace(codeMatch[0], `${fence}${lang}\n${content}\n${fence}`);
+                }
+                else {
+                    // Fallback: substitute {X} directly
+                    result = result.replace(new RegExp(`\\{${varName}\\}`, "g"), content);
+                }
+            }
+            catch { /* ignore read errors */ }
+        }
+    }
+    return result;
+}
+// ── Render partial resolution ──────────────────────────
+/**
+ * Resolve `<Render>` tags by inlining partial MDX content.
+ *
+ * Cloudflare uses `<Render file="..." product="..." params={{...}} />`
+ * to include content from `src/content/partials/{product}/{file}.mdx`.
+ *
+ * This reads the partial, strips its frontmatter/imports, substitutes
+ * `{props.paramName}` with provided params, and returns the body.
+ */
+function resolveRenderTags(source, partialsDir, depth = 0) {
+    if (!partialsDir || depth > 3)
+        return source; // guard against infinite recursion
+    return source.replace(/^([ \t]*)<Render\b([\s\S]*?)\/>/gm, (_match, indent, attrsStr) => {
+        const attrs = parseRenderAttrs(attrsStr);
+        if (!attrs.file || !attrs.product)
+            return "";
+        const partialPath = join(partialsDir, attrs.product, `${attrs.file}.mdx`);
+        if (!existsSync(partialPath))
+            return "";
+        try {
+            let content = readFileSync(partialPath, "utf-8");
+            // Strip frontmatter
+            if (content.startsWith("---")) {
+                const endIdx = content.indexOf("---", 3);
+                if (endIdx !== -1) {
+                    content = content.slice(endIdx + 3).trim();
+                }
+            }
+            // Strip imports
+            content = content
+                .replace(/^import\s+\{[^}]*\}\s+from\s+["'][^"']*["']\s*;?\s*$/gm, "")
+                .replace(/^import\s+\{[\s\S]*?\}\s+from\s+["'][^"']*["']\s*;?\s*$/gm, "");
+            // Substitute props.paramName with values from params
+            // Handles both {props.key} (in JSX text) and bare props.key (in JS expressions)
+            if (attrs.params) {
+                for (const [key, value] of Object.entries(attrs.params)) {
+                    // {props.key} → value (JSX text interpolation)
+                    content = content.replace(new RegExp(`\\{props\\.${key}\\}`, "g"), value);
+                    // props.key → 'value' (JS expression context — wrap in quotes)
+                    content = content.replace(new RegExp(`props\\.${key}`, "g"), `'${value}'`);
+                }
+                // Resolve JSX switch expressions after param substitution
+                content = resolveJsxSwitch(content);
+            }
+            // Recursively resolve nested Render tags in the partial content
+            content = resolveRenderTags(content.trim(), partialsDir, depth + 1);
+            // Indent resolved content to match the original tag's position
+            return indentContent(content, indent);
+        }
+        catch {
+            return "";
+        }
+    });
+}
+function parseRenderAttrs(str) {
+    const file = str.match(/file\s*=\s*"([^"]*)"/)?.[1];
+    const product = str.match(/product\s*=\s*"([^"]*)"/)?.[1];
+    let params;
+    const paramsMatch = str.match(/params\s*=\s*\{\{([\s\S]*?)\}\}/);
+    if (paramsMatch) {
+        params = {};
+        const pairs = paramsMatch[1].matchAll(/(\w+)\s*:\s*"([^"]*)"/g);
+        for (const pair of pairs) {
+            params[pair[1]] = pair[2];
+        }
+    }
+    return { file, product, params };
+}
+// ── Adapter export ─────────────────────────────────────
+export const cloudflareAdapter = {
+    name: "cloudflare",
+    components: {
+        // ── Mapped components ─────────────────────────────────
+        Feature: {
+            type: "card",
+            container: true,
+            propsFromAttrs: (attrs) => ({
+                title: attrs.header || "",
+                href: attrs.href,
+            }),
+        },
+        RelatedProduct: {
+            type: "card",
+            container: true,
+            propsFromAttrs: (attrs) => ({
+                title: attrs.header || "",
+                href: attrs.href,
+                icon: attrs.product ? `icons/${attrs.product}.svg` : undefined,
+            }),
+        },
+        Description: {
+            type: "description",
+            container: true,
+        },
+        Details: {
+            type: "details",
+            container: true,
+            propsFromAttrs: (attrs) => ({ title: attrs.header || "" }),
+        },
+        YouTube: {
+            type: "youtube",
+            container: false,
+            propsFromAttrs: (attrs) => ({ id: attrs.id || "" }),
+        },
+        Stream: {
+            type: "youtube",
+            container: false,
+            propsFromAttrs: (attrs) => ({ id: attrs.id || "" }),
+        },
+        // ── Stripped components (data-driven, can't resolve) ──
+        FeatureTable: { type: "", container: false, strip: true },
+        // PackageManagers resolved by resolveIncludes → Tabs with code blocks
+        // WranglerConfig resolved by resolveIncludes → Tabs with JSONC + TOML
+        WranglerCommand: { type: "", container: true, strip: true },
+        TypeScriptExample: { type: "", container: true, strip: true },
+        APIRequest: { type: "", container: true, strip: true },
+        AvailableNotifications: { type: "", container: false, strip: true },
+        CompatibilityFlags: { type: "", container: false, strip: true },
+        RSSButton: { type: "", container: false, strip: true },
+        ProductReleaseNotes: { type: "", container: false, strip: true },
+        // ── Workers/Pages-specific (strip) ───────────────────
+        AutoconfigDiagram: { type: "", container: false, strip: true },
+        GitHubCode: { type: "", container: false, strip: true },
+        ResourcesBySelector: { type: "", container: false, strip: true },
+        MetaInfo: { type: "", container: false, strip: true },
+        DirectoryListing: { type: "", container: false, strip: true },
+        ExternalResources: { type: "", container: false, strip: true },
+        YouTubeVideos: { type: "", container: false, strip: true },
+        ListTutorials: { type: "", container: false, strip: true },
+        WorkersTemplates: { type: "", container: false, strip: true },
+        // ── Heading variant (map to heading) ─────────────────
+        AnchorHeading: {
+            type: "heading",
+            container: true,
+            propsFromAttrs: (attrs) => ({
+                level: parseInt(attrs.level || "2", 10),
+                text: attrs.title || "",
+                slug: (attrs.title || "").toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, ""),
+            }),
+        },
+    },
+    selfClosingTags: [
+        "FeatureTable",
+        "YouTube",
+        "Stream",
+        "WranglerCommand",
+        "TypeScriptExample",
+        "APIRequest",
+        "AvailableNotifications",
+        "RSSButton",
+        "ProductReleaseNotes",
+        "AutoconfigDiagram",
+        "GitHubCode",
+        "ResourcesBySelector",
+        "MetaInfo",
+        "DirectoryListing",
+        "ExternalResources",
+        "YouTubeVideos",
+        "ListTutorials",
+        "WorkersTemplates",
+        "CompatibilityFlags",
+    ],
+    // Inline components — transformed in source text before block parsing
+    inlineTransforms: [
+        // <GlossaryTooltip term="..." link="...">text</GlossaryTooltip> → [text](link) or just text
+        [
+            /<GlossaryTooltip\s+term="([^"]*)"(?:\s+link="([^"]*)")?[^>]*>([\s\S]*?)<\/GlossaryTooltip>/g,
+            "$3",
+        ],
+        // <Plan type="all" /> → **Available on all plans**
+        [/<Plan\s+type="all"\s*\/?>/g, "**Available on all plans**"],
+        [/<Plan\s+type="([^"]*)"\s*\/?>/g, "**$1 plan**"],
+        // <InlineBadge ... /> → strip
+        [/<InlineBadge\s[^>]*\/>/g, ""],
+        // Fallback strip for self-closing components that may appear deeply indented
+        // where the block rule can't reach (inside Steps > list items etc.)
+        // PackageManagers resolved by resolveIncludes (not stripped)
+        [/<AutoconfigDiagram[\s\S]*?\/>/g, ""],
+        [/<GitHubCode\s[^>]*\/>/g, ""],
+        [/<ResourcesBySelector[\s\S]*?\/>/g, ""],
+        [/<MetaInfo\s[^>]*\/>/g, ""],
+        [/<DirectoryListing[\s\S]*?\/>/g, ""],
+        [/<ExternalResources\s[^>]*\/>/g, ""],
+        [/<YouTubeVideos\s[^>]*\/>/g, ""],
+        [/<SUBCOMMAND\s[^>]*\/>/g, ""],
+    ],
+    // Resolve <Render> partials and <DashButton> links
+    resolveIncludes(source, partialsDir) {
+        let result = resolveRawImports(source, partialsDir);
+        result = resolveRenderTags(result, partialsDir);
+        result = resolveDashButton(result, partialsDir);
+        result = resolvePackageManagers(result);
+        result = resolveWranglerConfig(result);
+        return result;
+    },
+    // Redirect pages use external_link in frontmatter
+    redirectField: "external_link",
+};

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+import type { FormatPlugin } from "@dogsbay/types";
+export declare const plugin: FormatPlugin;