safe-mdx 1.3.10 → 1.5.0

package/src/parse.ts

@@ -9,6 +9,62 @@ import { parseHtmlToMdxAst, remarkMdxJsxNormalize } from './html/html-to-mdx-ast
 
 export { parseHtmlToMdxAst, remarkMdxJsxNormalize }
 
+/* ── Import extraction ──────────────────────────────────────────────── */
+
+export type MdxImportSpecifier = {
+    /** Name used in MDX (e.g. `Card`, `MyButton`, `Utils`) */
+    local: string
+    /** Original export name. `'default'` for default imports, local name for named, `'*'` for namespace */
+    imported: string
+    type: 'named' | 'default' | 'namespace'
+}
+
+export type MdxImport = {
+    /** Raw source string as written: `'./card'`, `'/snippets/ui'`, `'some-pkg'` */
+    source: string
+    specifiers: MdxImportSpecifier[]
+}
+
+/**
+ * Extract all import declarations from a parsed mdast tree.
+ * Unlike `parseEsmImports`, this accepts ANY source (not just HTTPS URLs).
+ */
+export function extractImports(ast: Root): MdxImport[] {
+    const imports: MdxImport[] = []
+
+    for (const node of ast.children) {
+        if (node.type !== 'mdxjsEsm') continue
+        const estree = (node as any).data?.estree
+        if (!estree) continue
+
+        for (const statement of estree.body) {
+            if (statement.type !== 'ImportDeclaration') continue
+            const source = statement.source?.value
+            if (typeof source !== 'string') continue
+
+            const specifiers: MdxImportSpecifier[] = []
+            for (const spec of statement.specifiers ?? []) {
+                if (spec.type === 'ImportDefaultSpecifier') {
+                    specifiers.push({ local: spec.local.name, imported: 'default', type: 'default' })
+                } else if (spec.type === 'ImportSpecifier') {
+                    const importedName = spec.imported.type === 'Identifier'
+                        ? spec.imported.name
+                        : String(spec.imported.value)
+                    specifiers.push({ local: spec.local.name, imported: importedName, type: 'named' })
+                } else if (spec.type === 'ImportNamespaceSpecifier') {
+                    specifiers.push({ local: spec.local.name, imported: '*', type: 'namespace' })
+                }
+            }
+
+            if (specifiers.length > 0) {
+                imports.push({ source, specifiers })
+            }
+        }
+    }
+
+    return imports
+}
+
 export function mdxParse(code: string) {
     const file = mdxProcessor.processSync(code)
     return file.data.ast as Root
@@ -95,6 +151,115 @@ export function remarkMarkAndUnravel() {
     }
 }
 
+/* ── Module resolution ───────────────────────────────────────────────── */
+
+/** Extensions tried when resolving a bare import against glob keys */
+const RESOLVE_EXTENSIONS = [
+    '', '.tsx', '.ts', '.jsx', '.js', '.mdx', '.md',
+    '/index.tsx', '/index.ts', '/index.jsx', '/index.js',
+]
+
+/**
+ * Given an import source and a baseUrl, resolve the source to a key
+ * that exists in `moduleKeys`. Handles:
+ * - Relative imports (`./card`) resolved from `baseUrl`
+ * - Absolute imports (`/snippets/card`) normalized to `./snippets/card`
+ * - Extension resolution (tries .tsx, .ts, .jsx, .js, .mdx, .md, /index.*)
+ */
+export function resolveModulePath(
+    source: string,
+    baseUrl: string,
+    moduleKeys: string[],
+): string | undefined {
+    let normalized: string
+
+    if (source.startsWith('/')) {
+        // Absolute import from project root: /snippets/card → ./snippets/card
+        normalized = '.' + source
+    } else if (source.startsWith('./') || source.startsWith('../')) {
+        // Relative import: resolve from baseUrl
+        const joined = joinPaths(baseUrl, source)
+        if (!joined) return undefined // .. escaped above root
+        normalized = joined
+    } else {
+        // Bare specifier (npm package etc.) — not resolvable from glob
+        return undefined
+    }
+
+    // Try each extension
+    for (const ext of RESOLVE_EXTENSIONS) {
+        const candidate = normalized + ext
+        if (moduleKeys.includes(candidate)) {
+            return candidate
+        }
+    }
+
+    return undefined
+}
+
+/** Simple path join that normalizes `./a/b/../c` segments.
+ *  Both inputs and output use `./` prefix (matching Vite glob key format).
+ *  Returns `undefined` if `..` escapes above the project root. */
+function joinPaths(base: string, relative: string): string | undefined {
+    // Strip ./ prefix and trailing /
+    const baseParts = base.replace(/^\.\//, '').replace(/\/$/, '').split('/').filter(Boolean)
+    const relParts = relative.replace(/^\.\//, '').split('/').filter(Boolean)
+
+    for (const part of relParts) {
+        if (part === '..') {
+            if (baseParts.length === 0) return undefined // escaped above root
+            baseParts.pop()
+        } else if (part !== '.') {
+            baseParts.push(part)
+        }
+    }
+
+    return './' + baseParts.join('/')
+}
+
+export type LazyGlob = Record<string, () => Promise<Record<string, any>>>
+export type EagerModules = Record<string, Record<string, any>>
+
+/**
+ * Given a lazy Vite glob and a parsed mdast, resolve only the imported
+ * modules eagerly. Returns the exact shape `SafeMdxRenderer.modules` expects.
+ *
+ * Usage:
+ * ```ts
+ * const lazyGlob = import.meta.glob('./snippets/*.tsx')
+ * const mdast = mdxParse(mdxString)
+ * const modules = await resolveModules({ glob: lazyGlob, mdast, baseUrl: './pages/' })
+ * <SafeMdxRenderer modules={modules} baseUrl="./pages/" ... />
+ * ```
+ */
+export async function resolveModules({
+    glob,
+    mdast,
+    baseUrl,
+}: {
+    glob: LazyGlob
+    mdast: Root
+    baseUrl: string
+}): Promise<EagerModules> {
+    const imports = extractImports(mdast)
+    if (imports.length === 0) return {}
+
+    const keys = Object.keys(glob)
+    const result: EagerModules = {}
+
+    await Promise.all(
+        imports.map(async (imp) => {
+            const resolved = resolveModulePath(imp.source, baseUrl, keys)
+            if (!resolved || !glob[resolved]) return
+            // Avoid loading the same module twice
+            if (result[resolved]) return
+            result[resolved] = await glob[resolved]()
+        }),
+    )
+
+    return result
+}
+
 const mdxProcessor = remark()
     .use(remarkMdx)
     .use(remarkFrontmatter, ['yaml', 'toml'])

package/src/safe-mdx.test.tsx

@@ -483,6 +483,7 @@ test('missing components are ignored', () => {
           {
             "line": 1,
             "message": "Unsupported jsx component MissingComponent",
+            "type": "missing-component",
           },
         ],
         "html": "",
@@ -520,10 +521,12 @@ test('props parsing', () => {
           {
             "line": 8,
             "message": "Failed to evaluate expression attribute: expression2={Boolean(1)}. Functions are not supported",
+            "type": "expression",
           },
           {
             "line": 8,
             "message": "Expressions in jsx prop not evaluated: (expression2={Boolean(1)})",
+            "type": "expression",
           },
           {
             "line": 9,
@@ -532,10 +535,12 @@ test('props parsing', () => {
           {
             "line": 9,
             "message": "Failed to evaluate expression attribute: jsx={<SomeComponent />}. visitor "JSXElement" is not supported",
+            "type": "expression",
           },
           {
             "line": 9,
             "message": "Expressions in jsx prop not evaluated: (jsx={<SomeComponent />})",
+            "type": "expression",
           },
         ],
         "html": "<h1 num="2" doublequote="a &quot; string" quote="a &#x27; string" backTick="some undefined value" expression1="4" someJson="[object Object]"><p>hi</p></h1>",
@@ -2531,16 +2536,19 @@ test('component props schema validation with zod', () => {
             "line": 5,
             "message": "Invalid props for component "Heading" at "level": Too big: expected number to be <=6",
             "schemaPath": "level",
+            "type": "validation",
           },
           {
             "line": 7,
             "message": "Invalid props for component "Cards" at "count": Too small: expected number to be >0",
             "schemaPath": "count",
+            "type": "validation",
           },
           {
             "line": 9,
             "message": "Invalid props for component "Cards" at "count": Invalid input: expected number, received string",
             "schemaPath": "count",
+            "type": "validation",
           },
         ],
         "html": "<h1 title="test">Valid heading</h1><div count="3" variant="outline">Valid cards</div><h1 title="test">Invalid heading - level too high</h1><div count="-1">Invalid cards - negative count</div><div count="not a number">Invalid cards - wrong type</div>",
@@ -2578,6 +2586,66 @@ test('component props schema validation with zod', () => {
     `)
 })
 
+test('onError callback is called for each error', () => {
+    const errors: any[] = []
+    const code = dedent`
+        <Missing>should error</Missing>
+        
+        <Heading level={10}>invalid level</Heading>
+    `
+    const componentPropsSchema: ComponentPropsSchema = {
+        Heading: z.object({
+            level: z.number().min(1).max(6),
+        }),
+    }
+    const mdast = mdxParse(code)
+    const visitor = new MdastToJsx({
+        markdown: code,
+        mdast,
+        components,
+        componentPropsSchema,
+        onError: (err) => errors.push(err),
+    })
+    visitor.run()
+    expect(errors).toMatchInlineSnapshot(`
+      [
+        {
+          "line": 1,
+          "message": "Unsupported jsx component Missing",
+          "type": "missing-component",
+        },
+        {
+          "line": 3,
+          "message": "Invalid props for component "Heading" at "level": Too big: expected number to be <=6",
+          "schemaPath": "level",
+          "type": "validation",
+        },
+      ]
+    `)
+    // errors array and onError callback should have the same errors
+    expect(visitor.errors).toEqual(errors)
+})
+
+test('onError callback can throw to stop rendering', () => {
+    const code = dedent`
+        <Missing>should throw</Missing>
+        
+        <Heading>should not reach</Heading>
+    `
+    const mdast = mdxParse(code)
+    expect(() => {
+        const visitor = new MdastToJsx({
+            markdown: code,
+            mdast,
+            components,
+            onError: (err) => {
+                throw new Error(`MDX error on line ${err.line}: ${err.message}`)
+            },
+        })
+        visitor.run()
+    }).toThrow('MDX error on line 1: Unsupported jsx component Missing')
+})
+
 test('mdx expressions evaluation', () => {
     expect(
         render(dedent`
@@ -2635,10 +2703,12 @@ test('mdx expressions with unsupported functions', () => {
           {
             "line": 1,
             "message": "Failed to evaluate expression: Math.max(5, 10). Functions are not supported",
+            "type": "expression",
           },
           {
             "line": 2,
             "message": "Failed to evaluate expression: console.log("test"). Functions are not supported",
+            "type": "expression",
           },
         ],
         "html": "<p>Math function: 
@@ -2750,11 +2820,13 @@ test('validation error includes schema path', () => {
             "line": 1,
             "message": "Invalid props for component "Heading" at "user.age": Too small: expected number to be >=0",
             "schemaPath": "user.age",
+            "type": "validation",
           },
           {
             "line": 1,
             "message": "Invalid props for component "Heading" at "settings.theme": Invalid option: expected one of "light"|"dark"",
             "schemaPath": "settings.theme",
+            "type": "validation",
           },
         ],
         "html": "<h1 user="[object Object]" settings="[object Object]">Complex validation</h1>",
@@ -2887,6 +2959,7 @@ test('mdxJsxExpressionAttribute edge cases', () => {
           {
             "line": 3,
             "message": "Failed to evaluate expression attribute: ...{null: null, undefined: undefined}. undefined is undefined",
+            "type": "expression",
           },
         ],
         "html": "<h1 title="empty spread">Empty spread</h1><h1 title="null/undefined values">Null/undefined</h1><h1 array="1,2,3" object="[object Object]" title="complex values">Complex types</h1>",
@@ -3147,10 +3220,12 @@ test("jsx components in attributes error handling", () => {
         {
           "line": 3,
           "message": "Failed to evaluate expression attribute: icon={<UnsupportedComponent />}. visitor "JSXElement" is not supported",
+          "type": "expression",
         },
         {
           "line": 3,
           "message": "Expressions in jsx prop not evaluated: (icon={<UnsupportedComponent />})",
+          "type": "expression",
         },
       ]
     `)
@@ -3498,5 +3573,119 @@ test("skip unknown elements in complex nested HTML structures", () => {
 </div>
 `);
   
-  expect(html).toMatchInlineSnapshot(`"<h1>Main Title</h1><article><header><h1>Article Title</h1></header><section><blockquote><p>A famous quote</p></blockquote></section><footer></footer></article><h2>Another Section</h2><div></div>"`);
+   expect(html).toMatchInlineSnapshot(`"<h1>Main Title</h1><article><header><h1>Article Title</h1></header><section><blockquote><p>A famous quote</p></blockquote></section><footer></footer></article><h2>Another Section</h2><div></div>"`);
 });
+
+/* ── modules prop tests ─────────────────────────────────────────────── */
+
+test('modules prop: resolves named import from absolute path', () => {
+    function CustomBadge({ label }: { label: string }) {
+        return <span className="badge">{label}</span>
+    }
+
+    const code = dedent`
+        import { CustomBadge } from '/snippets/badge'
+
+        # Hello
+
+        <CustomBadge label="Works" />
+    `
+    const mdast = mdxParse(code)
+    const visitor = new MdastToJsx({
+        markdown: code,
+        mdast,
+        components,
+        modules: {
+            './snippets/badge.tsx': { CustomBadge },
+        },
+        baseUrl: './pages/',
+    })
+    const result = visitor.run()
+    const html = renderToStaticMarkup(result)
+    expect(html).toMatchInlineSnapshot(`"<h1>Hello</h1><span class="badge">Works</span>"`)
+    expect(visitor.errors).toMatchInlineSnapshot(`[]`)
+})
+
+test('modules prop: resolves default import from relative path', () => {
+    function MyCard({ children }: { children?: React.ReactNode }) {
+        return <div className="card">{children}</div>
+    }
+
+    const code = dedent`
+        import MyCard from './card'
+
+        <MyCard>content</MyCard>
+    `
+    const mdast = mdxParse(code)
+    const visitor = new MdastToJsx({
+        markdown: code,
+        mdast,
+        components,
+        modules: {
+            './pages/card.tsx': { default: MyCard },
+        },
+        baseUrl: './pages/',
+    })
+    const result = visitor.run()
+    const html = renderToStaticMarkup(result)
+    expect(html).toMatchInlineSnapshot(`"<div class="card">content</div>"`)
+    expect(visitor.errors).toMatchInlineSnapshot(`[]`)
+})
+
+test('modules prop: resolves namespace import with dot notation', () => {
+    function Card({ title }: { title: string }) {
+        return <div>{title}</div>
+    }
+    function Badge({ label }: { label: string }) {
+        return <span>{label}</span>
+    }
+
+    const code = dedent`
+        import * as UI from './ui'
+
+        <UI.Card title="hello" />
+        <UI.Badge label="tag" />
+    `
+    const mdast = mdxParse(code)
+    const visitor = new MdastToJsx({
+        markdown: code,
+        mdast,
+        components,
+        modules: {
+            './components/ui.tsx': { Card, Badge },
+        },
+        baseUrl: './components/',
+    })
+    const result = visitor.run()
+    const html = renderToStaticMarkup(result)
+    expect(html).toMatchInlineSnapshot(`"<div>hello</div><span>tag</span>"`)
+    expect(visitor.errors).toMatchInlineSnapshot(`[]`)
+})
+
+test('modules prop: unresolved import produces error', () => {
+    const code = dedent`
+        import { Missing } from './nonexistent'
+
+        <Missing />
+    `
+    const mdast = mdxParse(code)
+    const visitor = new MdastToJsx({
+        markdown: code,
+        mdast,
+        components,
+        modules: {},
+        baseUrl: './pages/',
+    })
+    const result = visitor.run()
+    const html = renderToStaticMarkup(result)
+    expect(html).toMatchInlineSnapshot(`""`)
+    expect(visitor.errors).toMatchInlineSnapshot(`
+      [
+        {
+          "line": 3,
+          "message": "Unsupported jsx component Missing",
+          "type": "missing-component",
+        },
+      ]
+    `)
+})