@mintlify/common 1.0.1274 → 1.0.1276

package/dist/mdx/estreeReferences.d.ts

@@ -37,3 +37,5 @@ export declare function hasEagerCall(node: unknown): boolean;
  * local may alias that object; a local initialized from fresh values passes nothing on.
  */
 export declare function collectModuleWrites(node: unknown, eagerOnly?: boolean): ModuleWrites;
+/** Every name `node` declares or binds, at any depth. */
+export declare function collectDeclaredNames(node: unknown, names?: Set<string>): Set<string>;

package/dist/mdx/estreeReferences.js

@@ -961,3 +961,35 @@ export function collectModuleWrites(node, eagerOnly = false) {
     });
     return writes;
 }
+/** Every name `node` declares or binds, at any depth. */
+export function collectDeclaredNames(node, names = new Set()) {
+    if (Array.isArray(node)) {
+        for (const child of node)
+            collectDeclaredNames(child, names);
+        return names;
+    }
+    if (!isObject(node))
+        return names;
+    if (node.type === 'VariableDeclarator')
+        collectPatternNames(node.id, names);
+    if ((node.type === 'FunctionDeclaration' || node.type === 'ClassDeclaration') &&
+        isObject(node.id) &&
+        typeof node.id.name === 'string') {
+        names.add(node.id.name);
+    }
+    if (Array.isArray(node.params)) {
+        for (const param of node.params)
+            collectPatternNames(param, names);
+    }
+    if (node.type === 'CatchClause')
+        collectPatternNames(node.param, names);
+    if ((node.type === 'ImportSpecifier' ||
+        node.type === 'ImportDefaultSpecifier' ||
+        node.type === 'ImportNamespaceSpecifier') &&
+        isObject(node.local) &&
+        typeof node.local.name === 'string') {
+        names.add(node.local.name);
+    }
+    forEachCodeChild(node, (child) => collectDeclaredNames(child, names));
+    return names;
+}

package/dist/mdx/plugins/remark/remarkVisibilityForMarkdown.js

@@ -3,7 +3,7 @@ import { isObject } from '../../../types/guards.js';
 import { getAST, stringifyTree } from '../../remark-core.js';
 import { BLOCK_LINK_LABEL } from './firstPartyMarkdownComponents.js';
 import { evaluateStatic } from './staticEvaluator.js';
-import { chargeUnfoldBudget, chargeUnfoldCall, collectMarkdownComponentContext, collectUsageProps, containsJsx, createUnfoldBudget, definitionGatesContent, DROP_ELEMENTS, dropPairedDarkOnly, escapeInterpolatedText, HEADING_ELEMENTS, isPresentationalAttribute, UNWRAP_BLOCK_ELEMENTS, UNWRAP_INLINE_ELEMENTS, escapeLinkLabel, extractProgramExpression, markdownLinkDestination, MAX_UNFOLD_DEPTH, GFM_ALERT_PATTERN, HEADLINE_ATTRIBUTES, KEEP_TAG_COMPONENTS, materializeComponent, serializeExpressionJsx, } from './unfoldComponentsForMarkdown.js';
+import { chargeUnfoldBudget, chargeUnfoldCall, collectMarkdownComponentContext, collectUsageProps, containsJsx, createUnfoldBudget, definitionGatesContent, DROP_ELEMENTS, FORM_CONTROL_ELEMENTS, dropPairedDarkOnly, escapeInterpolatedText, HEADING_ELEMENTS, isPresentationalAttribute, UNWRAP_BLOCK_ELEMENTS, UNWRAP_INLINE_ELEMENTS, escapeLinkLabel, extractProgramExpression, markdownLinkDestination, MAX_UNFOLD_DEPTH, GFM_ALERT_PATTERN, HEADLINE_ATTRIBUTES, KEEP_TAG_COMPONENTS, materializeComponent, serializeExpressionJsx, } from './unfoldComponentsForMarkdown.js';
 export function isVisibilityElement(node) {
     return ((node.type === 'mdxJsxFlowElement' || node.type === 'mdxJsxTextElement') &&
         node.name === 'Visibility');
@@ -403,6 +403,7 @@ function bodyExpressionValue(bodyChildren, ctx) {
         return undefined;
     const evaluated = evaluateStatic(extractProgramExpression((_a = only.data) === null || _a === void 0 ? void 0 : _a.estree), {
         scope: ctx.moduleScope,
+        declaredNames: ctx.declaredNames,
     });
     if (!evaluated.ok || (typeof evaluated.value === 'object' && evaluated.value !== null)) {
         return undefined;
@@ -475,12 +476,44 @@ function headlineMarkdown(title, href) {
         return `**${label}**`;
     return `[${escapeLinkLabel(label)}](${markdownLinkDestination(href)})`;
 }
+// Text an inline component shows when it has no children. `path` names a location, not a label.
+const INLINE_TEXT_PROPS = [
+    'children',
+    'title',
+    'label',
+    'name',
+    'description',
+    'alt',
+    'aria-label',
+];
+/** Inside running text a component stands for a word or phrase: its text, linked when it has an `href`. */
+function unfoldInlineForeignUsage(node, props, ctx, transformed) {
+    const children = flattenToPhrasing(transformed !== null && transformed !== void 0 ? transformed : transformChildren([...node.children], ctx)).filter(isPhrasingContent);
+    const hasChildContent = children.some((child) => !(child.type === 'text' && child.value.trim() === ''));
+    const childrenProp = props.get('children');
+    const text = typeof childrenProp === 'number'
+        ? String(childrenProp)
+        : firstTextProp(props, INLINE_TEXT_PROPS);
+    const content = hasChildContent
+        ? children
+        : text === undefined
+            ? []
+            : [{ type: 'text', value: text }];
+    const href = props.get('href');
+    if (content.length === 0 || typeof href !== 'string' || href === '')
+        return content;
+    return [
+        { type: 'link', url: href, children: flattenToPhrasing(content).filter(isPhrasingContent) },
+    ];
+}
 function unfoldForeignUsage(node, name, ctx, transformed) {
     if (KEEP_TAG_COMPONENTS.has(name))
         return undefined;
     const props = collectUsageProps(node, ctx);
     if (props.get('aria-hidden') === true || props.get('aria-hidden') === 'true')
         return [];
+    if (node.type === 'mdxJsxTextElement')
+        return unfoldInlineForeignUsage(node, props, ctx, transformed);
     const result = [];
     const title = firstTextProp(props, HEADLINE_ATTRIBUTES);
     if (title !== undefined) {
@@ -535,6 +568,8 @@ function transformIntrinsicElement(node, name, ctx) {
     const fallback = () => fallbackLabel === '' ? [] : [{ type: 'text', value: fallbackLabel }];
     if (DROP_ELEMENTS.has(name))
         return fallback();
+    if (FORM_CONTROL_ELEMENTS.has(name))
+        return [];
     if (name === 'br')
         return node.type === 'mdxJsxTextElement' ? [{ type: 'break' }] : [];
     if (name === 'hr')
@@ -579,7 +614,18 @@ function transformIntrinsicElement(node, name, ctx) {
             return children.length > 0 ? children : fallback();
         return linkContent(children, href, fallbackLabel);
     }
-    node.attributes = node.attributes.filter((attr) => attr.type !== 'mdxJsxAttribute' || !isPresentationalAttribute(attr.name));
+    // Attributes, spreads included, are kept only as resolved static values: an unresolved
+    // expression would print code
+    node.attributes = [...props].flatMap(([attrName, value]) => {
+        if (attrName === 'children' || isPresentationalAttribute(attrName))
+            return [];
+        if (value === true)
+            return [{ type: 'mdxJsxAttribute', name: attrName, value: null }];
+        if (typeof value === 'string' || typeof value === 'number') {
+            return [{ type: 'mdxJsxAttribute', name: attrName, value: String(value) }];
+        }
+        return [];
+    });
     replaceChildren(node.children, children);
     return [node];
 }
@@ -702,7 +748,10 @@ function transformExpression(node, ctx) {
             return [{ type: 'text', value: trimmed }];
         }
     }
-    const evaluated = evaluateStatic(expression, { scope: ctx.moduleScope });
+    const evaluated = evaluateStatic(expression, {
+        scope: ctx.moduleScope,
+        declaredNames: ctx.declaredNames,
+    });
     if (evaluated.ok) {
         const value = evaluated.value;
         if (value === null || value === undefined || typeof value === 'boolean')

package/dist/mdx/plugins/remark/staticEvaluator.d.ts

@@ -1,4 +1,5 @@
 import type { Root } from 'mdast';
+import { type UnknownRecord } from '../../estreeReferences.js';
 export declare function nodeType(value: unknown): string | undefined;
 export type StaticValue = string | number | boolean | null | undefined | {
     readonly [key: string]: StaticValue;
@@ -28,6 +29,8 @@ export type MarkdownComponentContext = {
      * produce them, so no write the evaluator cannot see can make them stale.
      */
     literalScope: StaticScope;
+    /** Every name the module declares or binds, in any scope. */
+    declaredNames?: ReadonlySet<string>;
 };
 export type EvalResult = {
     ok: true;
@@ -38,6 +41,18 @@ export type EvalResult = {
 export declare const EVAL_FAILED: EvalResult;
 export type EvalEnv = {
     scope: StaticScope;
+    /** The parameter a component's children are bound to. */
+    childrenName?: string;
+    /**
+     * The children are markdown built from the usage, with links or formatting in it. Reading or
+     * transforming them as a string would act on that markdown, not on the text a reader sees.
+     */
+    markdownChildren?: boolean;
+    /**
+     * Every name the module declares or binds, in any scope. A browser-only global is known to be
+     * absent only when the module does not declare that name itself.
+     */
+    declaredNames?: ReadonlySet<string>;
     propsObjectName?: string;
     failedProps?: ReadonlySet<string>;
     restName?: string;
@@ -46,6 +61,10 @@ export type EvalEnv = {
 export declare function unbindPattern(pattern: unknown, env: EvalEnv): void;
 export declare function bindPattern(pattern: unknown, value: StaticValue, env: EvalEnv): void;
 export declare function evaluateStatic(node: unknown, env: EvalEnv): EvalResult;
+/** Whether `node` reads children that are markdown, directly or as `props.children`. */
+export declare function readsMarkdownChildren(node: unknown, env: EvalEnv): boolean;
+/** The property a member reads when it is fixed: `a.children` or `a["children"]`. */
+export declare function staticPropertyName(member: UnknownRecord): string | undefined;
 /**
  * Collects a module's component definitions and its statically known values. Objects are only
  * bound when the module never writes through any object: tracking which objects a write can reach

package/dist/mdx/plugins/remark/staticEvaluator.js

@@ -1,5 +1,5 @@
 import { isObject } from '../../../types/guards.js';
-import { collectModuleWrites, collectPatternNames, hasEagerCall, } from '../../estreeReferences.js';
+import { collectDeclaredNames, collectModuleWrites, collectPatternNames, hasEagerCall, } from '../../estreeReferences.js';
 export function nodeType(value) {
     return isObject(value) && typeof value.type === 'string' ? value.type : undefined;
 }
@@ -256,6 +256,8 @@ export function evaluateStatic(node, env) {
         case 'ParenthesizedExpression':
             return evaluateStatic(node.expression, env);
         case 'MemberExpression': {
+            if (readsMarkdownChildren(node.object, env))
+                return EVAL_FAILED;
             const property = node.property;
             const key = node.computed === true
                 ? evaluateStatic(property, env)
@@ -415,7 +417,11 @@ export function evaluateStatic(node, env) {
                 return EVAL_FAILED;
             return evaluateStatic(test.value ? node.consequent : node.alternate, env);
         }
+        case 'CallExpression':
+            return evaluateMethodCall(node, env);
         case 'UnaryExpression': {
+            if (node.operator === 'typeof')
+                return evaluateTypeof(node.argument, env);
             const argument = evaluateStatic(node.argument, env);
             if (!argument.ok)
                 return EVAL_FAILED;
@@ -437,6 +443,216 @@ export function evaluateStatic(node, env) {
             return EVAL_FAILED;
     }
 }
+function isIndex(value) {
+    return value === undefined || (typeof value === 'number' && Number.isFinite(value));
+}
+/** Pure string methods, called on a known string with known arguments. */
+function callStringMethod(text, method, args) {
+    const [first, second] = args;
+    const stringArg = typeof first === 'string' ? first : undefined;
+    switch (method) {
+        case 'startsWith':
+        case 'endsWith':
+        case 'includes':
+        case 'indexOf':
+        case 'lastIndexOf':
+            if (stringArg === undefined || !isIndex(second))
+                return EVAL_FAILED;
+            return { ok: true, value: text[method](stringArg, second) };
+        case 'slice':
+        case 'substring':
+            if (!isIndex(first) || !isIndex(second))
+                return EVAL_FAILED;
+            return { ok: true, value: text[method](first !== null && first !== void 0 ? first : 0, second) };
+        case 'at':
+        case 'charAt':
+            if (!isIndex(first))
+                return EVAL_FAILED;
+            return { ok: true, value: method === 'at' ? text.at(first !== null && first !== void 0 ? first : 0) : text.charAt(first !== null && first !== void 0 ? first : 0) };
+        case 'toLowerCase':
+        case 'toUpperCase':
+        case 'trim':
+        case 'trimStart':
+        case 'trimEnd':
+            return args.length === 0 ? { ok: true, value: text[method]() } : EVAL_FAILED;
+        case 'replace':
+        case 'replaceAll': {
+            // `$` patterns can copy large parts of the text into each replacement
+            if (stringArg === undefined || typeof second !== 'string' || second.includes('$')) {
+                return EVAL_FAILED;
+            }
+            const occurrences = stringArg === ''
+                ? method === 'replaceAll'
+                    ? text.length + 1
+                    : 1
+                : method === 'replaceAll'
+                    ? text.split(stringArg).length - 1
+                    : Number(text.includes(stringArg));
+            const length = text.length + occurrences * (second.length - stringArg.length);
+            if (length > MAX_STATIC_VALUE_WEIGHT)
+                return EVAL_FAILED;
+            return { ok: true, value: text[method](stringArg, second) };
+        }
+        case 'split':
+            if (stringArg === undefined || !isIndex(second))
+                return EVAL_FAILED;
+            return withinBudget(text.split(stringArg, second));
+        case 'padStart':
+        case 'padEnd':
+            if (typeof first !== 'number' || first > MAX_STATIC_VALUE_WEIGHT)
+                return EVAL_FAILED;
+            if (second !== undefined && typeof second !== 'string')
+                return EVAL_FAILED;
+            return { ok: true, value: text[method](first, second) };
+        case 'repeat':
+            if (typeof first !== 'number' || first < 0 || text.length * first > MAX_STATIC_VALUE_WEIGHT) {
+                return EVAL_FAILED;
+            }
+            return { ok: true, value: text.repeat(first) };
+        case 'concat': {
+            if (!args.every((arg) => typeof arg === 'string' || typeof arg === 'number')) {
+                return EVAL_FAILED;
+            }
+            const parts = args.map(String);
+            const length = parts.reduce((total, part) => total + part.length, text.length);
+            if (length > MAX_STATIC_VALUE_WEIGHT)
+                return EVAL_FAILED;
+            return { ok: true, value: text.concat(...parts) };
+        }
+        default:
+            return EVAL_FAILED;
+    }
+}
+/** Pure array methods that read a known array without changing it. */
+function callArrayMethod(items, method, args) {
+    const [first, second] = args;
+    switch (method) {
+        case 'join': {
+            if (first !== undefined && typeof first !== 'string')
+                return EVAL_FAILED;
+            if (!items.every((item) => item === null || typeof item !== 'object'))
+                return EVAL_FAILED;
+            const parts = items.map((item) => (item == null ? '' : String(item)));
+            const separator = first !== null && first !== void 0 ? first : ',';
+            const length = parts.reduce((total, part) => total + part.length, 0) +
+                separator.length * Math.max(parts.length - 1, 0);
+            if (length > MAX_STATIC_VALUE_WEIGHT)
+                return EVAL_FAILED;
+            return { ok: true, value: parts.join(separator) };
+        }
+        case 'includes':
+        case 'indexOf':
+            if (first !== null && typeof first === 'object')
+                return EVAL_FAILED;
+            if (!isIndex(second))
+                return EVAL_FAILED;
+            return { ok: true, value: items[method](first, second) };
+        case 'slice':
+            if (!isIndex(first) || !isIndex(second))
+                return EVAL_FAILED;
+            return { ok: true, value: items.slice(first, second) };
+        case 'at':
+            if (!isIndex(first))
+                return EVAL_FAILED;
+            return { ok: true, value: items.at(first !== null && first !== void 0 ? first : 0) };
+        default:
+            return EVAL_FAILED;
+    }
+}
+/** A call to a pure built-in method on a known string or array, such as `path.startsWith("/")`. */
+function evaluateMethodCall(node, env) {
+    const callee = node.callee;
+    if (nodeType(callee) !== 'MemberExpression' || !isObject(callee) || callee.optional === true) {
+        return EVAL_FAILED;
+    }
+    const method = callee.computed === true
+        ? isObject(callee.property) && typeof callee.property.value === 'string'
+            ? callee.property.value
+            : undefined
+        : identifierName(callee.property);
+    if (method === undefined)
+        return EVAL_FAILED;
+    if (readsMarkdownChildren(callee.object, env))
+        return EVAL_FAILED;
+    const receiver = evaluateStatic(callee.object, env);
+    if (!receiver.ok)
+        return EVAL_FAILED;
+    const rawArgs = Array.isArray(node.arguments) ? node.arguments : [];
+    const args = [];
+    for (const rawArg of rawArgs) {
+        if (nodeType(rawArg) === 'SpreadElement')
+            return EVAL_FAILED;
+        const evaluated = evaluateStatic(rawArg, env);
+        if (!evaluated.ok)
+            return EVAL_FAILED;
+        args.push(evaluated.value);
+    }
+    // Sizes are checked before each call; a native error still fails evaluation instead of throwing
+    try {
+        if (typeof receiver.value === 'string')
+            return callStringMethod(receiver.value, method, args);
+        if (Array.isArray(receiver.value))
+            return callArrayMethod(receiver.value, method, args);
+    }
+    catch (_a) {
+        return EVAL_FAILED;
+    }
+    return EVAL_FAILED;
+}
+// Markdown is rendered without a browser, as on a server, so these globals do not exist there
+const BROWSER_ONLY_GLOBALS = new Set([
+    'window',
+    'document',
+    'navigator',
+    'location',
+    'history',
+    'localStorage',
+    'sessionStorage',
+    'matchMedia',
+    'requestAnimationFrame',
+]);
+/** Whether `node` reads children that are markdown, directly or as `props.children`. */
+export function readsMarkdownChildren(node, env) {
+    var _a, _b;
+    if (env.markdownChildren !== true || !isObject(node))
+        return false;
+    if (node.type === 'Identifier') {
+        return node.name === env.childrenName && !((_b = (_a = env.failedProps) === null || _a === void 0 ? void 0 : _a.has('children')) !== null && _b !== void 0 ? _b : false);
+    }
+    if (node.type !== 'MemberExpression')
+        return false;
+    const objectName = identifierName(node.object);
+    return (staticPropertyName(node) === 'children' &&
+        objectName !== undefined &&
+        (objectName === env.propsObjectName || objectName === env.restName));
+}
+/** The property a member reads when it is fixed: `a.children` or `a["children"]`. */
+export function staticPropertyName(member) {
+    if (member.computed !== true)
+        return identifierName(member.property);
+    const property = member.property;
+    return isObject(property) && property.type === 'Literal' && typeof property.value === 'string'
+        ? property.value
+        : undefined;
+}
+function evaluateTypeof(argument, env) {
+    if (readsMarkdownChildren(argument, env))
+        return EVAL_FAILED;
+    if (nodeType(argument) === 'Identifier' &&
+        isObject(argument) &&
+        typeof argument.name === 'string' &&
+        BROWSER_ONLY_GLOBALS.has(argument.name) &&
+        !env.scope.has(argument.name) &&
+        env.declaredNames !== undefined &&
+        !env.declaredNames.has(argument.name)) {
+        return { ok: true, value: 'undefined' };
+    }
+    const evaluated = evaluateStatic(argument, env);
+    if (!evaluated.ok)
+        return EVAL_FAILED;
+    const value = evaluated.value;
+    return { ok: true, value: value === null ? 'object' : typeof value };
+}
 function isFunctionNode(value) {
     const type = nodeType(value);
     return (type === 'ArrowFunctionExpression' ||
@@ -515,7 +731,7 @@ export function collectContextFromTree(tree) {
         }
         if (kind !== 'const')
             return;
-        const literal = evaluateStatic(init, { scope: literalScope });
+        const literal = evaluateStatic(init, { scope: literalScope, declaredNames });
         if (literal.ok) {
             // Defaults and computed keys in the pattern may read earlier literal values
             const bound = new Map(literalScope);
@@ -531,13 +747,14 @@ export function collectContextFromTree(tree) {
                     literalScope.set(boundName, value);
             }
         }
-        const evaluated = evaluateStatic(init, { scope: moduleScope });
+        const evaluated = evaluateStatic(init, { scope: moduleScope, declaredNames });
         if (!evaluated.ok)
             return;
         bindPattern(declarator.id, evaluated.value, { scope: moduleScope });
     };
     const estrees = [];
     collectEstrees(tree, estrees);
+    const declaredNames = collectDeclaredNames(estrees);
     const { reassigned, mutated } = collectModuleWrites(estrees);
     const moduleWrites = reassigned.size > 0 || mutated.size > 0;
     for (const statement of statements) {
@@ -635,5 +852,5 @@ export function collectContextFromTree(tree) {
             }
         }
     }
-    return { defs, moduleScope, literalScope };
+    return { defs, moduleScope, literalScope, declaredNames };
 }

package/dist/mdx/plugins/remark/unfoldComponentsForMarkdown.d.ts

@@ -37,6 +37,7 @@ export declare const FAILED_SPREAD = "*";
 export declare function collectMarkdownComponentContext(tree: Root): MarkdownComponentContext;
 export declare function getFirstPartyComponentDefs(): Map<string, ComponentDef>;
 export declare const DROP_ELEMENTS: Set<string>;
+export declare const FORM_CONTROL_ELEMENTS: Set<string>;
 export declare const UNWRAP_BLOCK_ELEMENTS: Set<string>;
 export declare const UNWRAP_INLINE_ELEMENTS: Set<string>;
 export declare const HEADING_ELEMENTS: Record<string, Heading['depth']>;