safe-mdx 1.9.0 → 1.11.0

package/src/safe-mdx.tsx

@@ -135,6 +135,10 @@ export class MdastToJsx {
     baseUrl?: string
     onError?: (error: SafeMdxError) => void
     scope?: Record<string, any>
+    /** Whether the caller passed a non-empty scope. Used to decide if
+     *  function calls should be auto-enabled — module imports adding to
+     *  scope should NOT flip this flag. */
+    private userProvidedScope: boolean = false
     evaluateOptions?: EvaluateOptions
 
     constructor({
@@ -195,7 +199,8 @@ export class MdastToJsx {
         this.modules = modules
         this.baseUrl = baseUrl
         this.onError = onError
-        this.scope = scope
+        this.scope = scope ? { ...scope } : undefined
+        this.userProvidedScope = !!scope && Object.keys(scope).length > 0
         this.evaluateOptions = evaluateOptions
 
         this.c = {
@@ -219,9 +224,11 @@ export class MdastToJsx {
      * Resolved components are added directly to `this.c` (the component map)
      * so the existing `accessWithDot` lookup finds them.
      */
-    resolveImportsFromModules(node: MyRootContent): void {
+    /** Resolve imports from pre-loaded modules. Returns the set of local names that were resolved. */
+    resolveImportsFromModules(node: MyRootContent): Set<string> {
+        const resolved = new Set<string>()
         const estree = (node as any).data?.estree
-        if (!estree) return
+        if (!estree) return resolved
 
         const moduleKeys = Object.keys(this.modules!)
 
@@ -230,26 +237,37 @@ export class MdastToJsx {
             const source: string = statement.source?.value
             if (typeof source !== 'string') continue
 
-            const resolved = resolveModulePath(source, this.baseUrl || './', moduleKeys)
-            if (!resolved) continue
-            const mod = this.modules![resolved]
-            if (!mod) continue
+            const resolvedPath = resolveModulePath(source, this.baseUrl || './', moduleKeys)
+            if (!resolvedPath) continue
+            const mod = this.modules![resolvedPath]
+            if (mod == null) continue
 
             for (const spec of statement.specifiers ?? []) {
+                let value: any
                 if (spec.type === 'ImportDefaultSpecifier') {
-                    this.c[spec.local.name] = mod.default ?? mod
+                    value = mod.default ?? mod
                 } else if (spec.type === 'ImportSpecifier') {
                     const importedName = spec.imported.type === 'Identifier'
                         ? spec.imported.name
                         : String(spec.imported.value)
-                    this.c[spec.local.name] = mod[importedName]
+                    value = mod[importedName]
                 } else if (spec.type === 'ImportNamespaceSpecifier') {
                     // Namespace import: import * as UI from '...'
                     // Supports <UI.Card> via accessWithDot
-                    this.c[spec.local.name] = mod
+                    value = mod
+                } else {
+                    continue
                 }
+
+                this.c[spec.local.name] = value
+                resolved.add(spec.local.name)
+                // Also add to scope so values are available in expressions
+                // like {code} or prop={code}
+                if (!this.scope) this.scope = {}
+                this.scope[spec.local.name] = value
             }
         }
+        return resolved
     }
 
     addLineNumberToProps(
@@ -530,8 +548,8 @@ export class MdastToJsx {
     evaluateExpression(expression: any) {
         const hasScope = this.scope && Object.keys(this.scope).length > 0
         const context = hasScope ? this.scope : undefined
-        const options = hasScope || this.evaluateOptions
-            ? { ...(hasScope ? { functions: true } : {}), ...this.evaluateOptions }
+        const options = this.userProvidedScope || this.evaluateOptions
+            ? { ...(this.userProvidedScope ? { functions: true } : {}), ...this.evaluateOptions }
             : undefined
 
         // When functions are enabled and the user hasn't provided their own
@@ -546,6 +564,16 @@ export class MdastToJsx {
             }
         }
 
+        // When scope is provided, check that referenced identifiers exist
+        // before evaluation. eval-estree-expression silently returns undefined
+        // for missing identifiers, so we catch them here to produce clear errors.
+        if (context) {
+            const missing = findMissingIdentifiers(expression, context)
+            if (missing.length > 0) {
+                throw new Error(`${missing[0]} is not defined. Available variables: ${Object.keys(context).join(', ')}`)
+            }
+        }
+
         return Evaluate.evaluate.sync(expression, context, options)
     }
 
@@ -741,10 +769,65 @@ export class MdastToJsx {
 
         switch (node.type) {
             case 'mdxjsEsm': {
+                const estree = (node as any).data?.estree
+                const nodeLine = node.position?.start?.line
+
+                // Warn about export declarations (not supported in safe-mdx)
+                if (estree) {
+                    for (const stmt of estree.body) {
+                        if (stmt.type === 'ExportNamedDeclaration' || stmt.type === 'ExportDefaultDeclaration') {
+                            const stmtLine = stmt.loc?.start?.line ?? nodeLine
+                            const exportKind = stmt.type === 'ExportDefaultDeclaration' ? 'default' : 'named'
+                            let detail = ''
+                            if (stmt.declaration) {
+                                const decl = stmt.declaration
+                                if (decl.type === 'FunctionDeclaration' && decl.id?.name) {
+                                    detail = ` "${decl.id.name}"`
+                                } else if (decl.type === 'VariableDeclaration') {
+                                    const names = decl.declarations
+                                        .map((d: any) => d.id?.name)
+                                        .filter(Boolean)
+                                        .join(', ')
+                                    if (names) detail = ` "${names}"`
+                                }
+                            }
+                            this.pushError({
+                                type: 'expression',
+                                message: `Unsupported ${exportKind} export${detail}. Export declarations are not evaluated, so exported values and components are not available in the document.`,
+                                line: stmtLine,
+                            })
+                        }
+                    }
+                }
+
                 // Resolve imports from pre-loaded modules (server-side)
+                let resolvedImportLocals = new Set<string>()
                 if (this.modules) {
-                    this.resolveImportsFromModules(node)
+                    resolvedImportLocals = this.resolveImportsFromModules(node)
                 }
+
+                // Warn about import declarations that cannot be resolved
+                if (estree && !this.allowClientEsmImports) {
+                    for (const stmt of estree.body) {
+                        if (stmt.type !== 'ImportDeclaration') continue
+                        const stmtLine = stmt.loc?.start?.line ?? nodeLine
+                        const source: string = stmt.source?.value
+                        if (typeof source !== 'string') continue
+
+                        // Check against actually resolved imports, not this.c (which includes pre-existing components)
+                        const specNames = (stmt.specifiers ?? []).map((s: any) => s.local?.name).filter(Boolean)
+                        const unresolvedNames = specNames.filter((name: string) => !resolvedImportLocals.has(name))
+
+                        if (unresolvedNames.length > 0) {
+                            this.pushError({
+                                type: 'expression',
+                                message: `Unresolved import "${unresolvedNames.join(', ')}" from "${source}". The imported module could not be resolved, so these names are not available in the document.`,
+                                line: stmtLine,
+                            })
+                        }
+                    }
+                }
+
                 // Parse ESM imports for client-side dynamic loading (only if allowed)
                 if (this.allowClientEsmImports) {
                     const parsedImports = parseEsmImports(node, (err) =>
@@ -1106,6 +1189,144 @@ export class MdastToJsx {
 }
 
 
+/** JS globals that eval-estree-expression treats as built-in values */
+const ALLOWED_GLOBALS = new Set(['undefined', 'NaN', 'Infinity', 'true', 'false', 'null'])
+
+/**
+ * Walk an estree expression AST and collect top-level Identifier names
+ * that are not defined in the given scope context. Skips property access
+ * identifiers (e.g. `foo.bar` only checks `foo`, not `bar`), function
+ * parameter bindings, and JS built-in globals.
+ *
+ * For short-circuit operators (||, ??, &&) and ternary expressions,
+ * only checks the left/test operand since the right side may never
+ * be evaluated at runtime.
+ */
+function findMissingIdentifiers(
+    node: any,
+    context: Record<string, any>,
+    localBindings: Set<string> = new Set(),
+): string[] {
+    if (!node) return []
+    const missing: string[] = []
+
+    switch (node.type) {
+        case 'Identifier':
+            if (!ALLOWED_GLOBALS.has(node.name) && !(node.name in context) && !localBindings.has(node.name)) {
+                missing.push(node.name)
+            }
+            break
+        case 'MemberExpression':
+            // Only check the object, not the property
+            missing.push(...findMissingIdentifiers(node.object, context, localBindings))
+            // Check computed properties like obj[expr]
+            if (node.computed) {
+                missing.push(...findMissingIdentifiers(node.property, context, localBindings))
+            }
+            break
+        case 'CallExpression':
+            missing.push(...findMissingIdentifiers(node.callee, context, localBindings))
+            for (const arg of node.arguments || []) {
+                missing.push(...findMissingIdentifiers(arg, context, localBindings))
+            }
+            break
+        case 'BinaryExpression':
+            missing.push(...findMissingIdentifiers(node.left, context, localBindings))
+            missing.push(...findMissingIdentifiers(node.right, context, localBindings))
+            break
+        case 'LogicalExpression':
+            // For ||, ??, && only check the left side statically.
+            // The right side may never be evaluated at runtime.
+            missing.push(...findMissingIdentifiers(node.left, context, localBindings))
+            break
+        case 'UnaryExpression':
+            missing.push(...findMissingIdentifiers(node.argument, context, localBindings))
+            break
+        case 'ConditionalExpression':
+            // Only check the test statically. The branches may never run.
+            missing.push(...findMissingIdentifiers(node.test, context, localBindings))
+            break
+        case 'TemplateLiteral':
+            for (const expr of node.expressions || []) {
+                missing.push(...findMissingIdentifiers(expr, context, localBindings))
+            }
+            break
+        case 'ArrowFunctionExpression':
+        case 'FunctionExpression': {
+            // Collect parameter names as local bindings
+            const newBindings = new Set(localBindings)
+            for (const param of node.params || []) {
+                collectParamNames(param, newBindings)
+            }
+            missing.push(...findMissingIdentifiers(node.body, context, newBindings))
+            break
+        }
+        case 'BlockStatement':
+            for (const stmt of node.body || []) {
+                // Register variable declarations (including destructuring) as local bindings
+                if (stmt.type === 'VariableDeclaration') {
+                    for (const decl of stmt.declarations || []) {
+                        collectParamNames(decl.id, localBindings)
+                        // Check the initializer for missing identifiers
+                        if (decl.init) {
+                            missing.push(...findMissingIdentifiers(decl.init, context, localBindings))
+                        }
+                    }
+                    // Skip re-walking this statement since we already handled it
+                    continue
+                }
+                missing.push(...findMissingIdentifiers(stmt, context, localBindings))
+            }
+            break
+        case 'ExpressionStatement':
+            missing.push(...findMissingIdentifiers(node.expression, context, localBindings))
+            break
+        case 'ReturnStatement':
+            missing.push(...findMissingIdentifiers(node.argument, context, localBindings))
+            break
+        case 'ArrayExpression':
+            for (const elem of node.elements || []) {
+                if (elem) missing.push(...findMissingIdentifiers(elem, context, localBindings))
+            }
+            break
+        case 'ObjectExpression':
+            for (const prop of node.properties || []) {
+                if (prop.value) missing.push(...findMissingIdentifiers(prop.value, context, localBindings))
+            }
+            break
+        case 'SpreadElement':
+            missing.push(...findMissingIdentifiers(node.argument, context, localBindings))
+            break
+        // Literal, JSXElement, etc. - no identifiers to check
+    }
+
+    return missing
+}
+
+/** Extract all bound names from a function parameter AST node */
+function collectParamNames(param: any, names: Set<string>) {
+    if (!param) return
+    if (param.type === 'Identifier') {
+        names.add(param.name)
+    } else if (param.type === 'ObjectPattern') {
+        for (const prop of param.properties || []) {
+            if (prop.type === 'RestElement') {
+                collectParamNames(prop.argument, names)
+            } else {
+                collectParamNames(prop.value, names)
+            }
+        }
+    } else if (param.type === 'ArrayPattern') {
+        for (const elem of param.elements || []) {
+            if (elem) collectParamNames(elem, names)
+        }
+    } else if (param.type === 'RestElement') {
+        collectParamNames(param.argument, names)
+    } else if (param.type === 'AssignmentPattern') {
+        collectParamNames(param.left, names)
+    }
+}
+
 function accessWithDot(obj, path: string) {
     return path
         .split('.')