@markuplint/pretenders 5.0.0-dev.5 → 5.0.0-rc.1

package/lib/import-resolver/parse-imports.js

@@ -0,0 +1,194 @@
+/**
+ * @module parse-imports
+ *
+ * Extracts import bindings from ESM source text using es-module-lexer.
+ * Since es-module-lexer provides specifier positions but not local binding names,
+ * regex parsing on the statement slices supplements the extraction.
+ */
+import { init, parse } from 'es-module-lexer';
+/** Matches `import type` — TypeScript type-only import (no runtime binding) */
+const RE_TYPE_ONLY_IMPORT = /^import\s+type\s/;
+/** Matches `import X from` — default import */
+const RE_DEFAULT_IMPORT = /import\s+(\w+)\s+from/;
+/** Matches `import { ... } from` — named imports */
+const RE_NAMED_IMPORTS = /import\s*\{([^}]+)\}\s*from/;
+/** Matches `import * as X from` — namespace import */
+const RE_NAMESPACE_IMPORT = /import\s*\*\s*as\s+(\w+)\s+from/;
+/** Matches `import X, { ... } from` — default + named imports */
+const RE_DEFAULT_AND_NAMED = /import\s+(\w+)\s*,\s*\{([^}]+)\}\s*from/;
+/** Matches `import X, * as Y from` — default + namespace imports */
+const RE_DEFAULT_AND_NAMESPACE = /import\s+(\w+)\s*,\s*\*\s*as\s+(\w+)\s+from/;
+let initPromise = null;
+/**
+ * Ensures the es-module-lexer WASM module is initialized.
+ * Safe to call multiple times; initialization only happens once.
+ */
+async function ensureInit() {
+    initPromise ??= init;
+    await initPromise;
+}
+/**
+ * Parses named import entries from a comma-separated string inside `{ ... }`.
+ * Handles `as` aliases (e.g., `Foo as Bar`) and whitespace/trailing commas.
+ *
+ * @param raw - The raw string between braces, e.g., `"Foo, Bar as Baz"`
+ * @returns An array of import bindings with type `'named'`
+ */
+function parseNamedEntries(raw, source) {
+    const bindings = [];
+    for (const entry of raw.split(',')) {
+        const trimmed = entry.trim();
+        if (!trimmed) {
+            continue;
+        }
+        // Skip inline type-only imports: `import { type Foo } from '...'`
+        if (/^type\s+/.test(trimmed)) {
+            continue;
+        }
+        const asParts = trimmed.split(/\s+as\s+/);
+        if (asParts.length === 2 && asParts[0] && asParts[1]) {
+            bindings.push({
+                localName: asParts[1].trim(),
+                importedName: asParts[0].trim(),
+                source,
+                type: 'named',
+            });
+        }
+        else {
+            bindings.push({
+                localName: trimmed,
+                importedName: trimmed,
+                source,
+                type: 'named',
+            });
+        }
+    }
+    return bindings;
+}
+/**
+ * Extracts import bindings from a single import statement slice.
+ * Applies regex patterns to determine the import shape (default, named, namespace,
+ * or combinations thereof).
+ *
+ * @param statementText - The full import statement text (from `ss` to `se`)
+ * @param source - The resolved module specifier from es-module-lexer
+ * @returns An array of import bindings found in this statement
+ */
+function extractBindingsFromStatement(statementText, source) {
+    // TypeScript `import type { ... }` — no runtime binding, skip entirely
+    if (RE_TYPE_ONLY_IMPORT.test(statementText)) {
+        return [];
+    }
+    // Try default + named: `import X, { A, B } from '...'`
+    const defaultAndNamed = RE_DEFAULT_AND_NAMED.exec(statementText);
+    if (defaultAndNamed?.[1] && defaultAndNamed[2] !== undefined) {
+        return [
+            {
+                localName: defaultAndNamed[1],
+                importedName: 'default',
+                source,
+                type: 'default',
+            },
+            ...parseNamedEntries(defaultAndNamed[2], source),
+        ];
+    }
+    // Try default + namespace: `import X, * as Y from '...'`
+    const defaultAndNamespace = RE_DEFAULT_AND_NAMESPACE.exec(statementText);
+    if (defaultAndNamespace?.[1] && defaultAndNamespace[2]) {
+        return [
+            {
+                localName: defaultAndNamespace[1],
+                importedName: 'default',
+                source,
+                type: 'default',
+            },
+            {
+                localName: defaultAndNamespace[2],
+                importedName: '*',
+                source,
+                type: 'namespace',
+            },
+        ];
+    }
+    // Try namespace: `import * as X from '...'`
+    const namespace = RE_NAMESPACE_IMPORT.exec(statementText);
+    if (namespace?.[1]) {
+        return [
+            {
+                localName: namespace[1],
+                importedName: '*',
+                source,
+                type: 'namespace',
+            },
+        ];
+    }
+    // Try named: `import { A, B as C } from '...'`
+    const named = RE_NAMED_IMPORTS.exec(statementText);
+    if (named?.[1] !== undefined) {
+        return parseNamedEntries(named[1], source);
+    }
+    // Try default: `import X from '...'`
+    const defaultImport = RE_DEFAULT_IMPORT.exec(statementText);
+    if (defaultImport?.[1]) {
+        return [
+            {
+                localName: defaultImport[1],
+                importedName: 'default',
+                source,
+                type: 'default',
+            },
+        ];
+    }
+    // Side-effect import (`import '...'`) — no bindings to extract
+    return [];
+}
+/**
+ * Analyzes source text and extracts import bindings using es-module-lexer.
+ *
+ * Processes static imports and dynamic imports with string literal specifiers.
+ * `import.meta` references and dynamic imports with non-literal specifiers
+ * (template literals, variables) are excluded.
+ *
+ * @param source - The source text to analyze (e.g., content of a `<script setup>` block)
+ * @returns An array of all import bindings found in the source
+ */
+export async function parseImports(source) {
+    await ensureInit();
+    let imports;
+    try {
+        [imports] = parse(source);
+    }
+    catch {
+        // Source may contain non-JS content (e.g., MDX with markdown).
+        // Return empty bindings rather than propagating the parse error.
+        return [];
+    }
+    const bindings = [];
+    for (const imp of imports) {
+        // import.meta (d === -2) — always skip
+        if (imp.d === -2) {
+            continue;
+        }
+        // n = normalized module specifier (absent for template-literal dynamic imports)
+        if (!imp.n) {
+            continue;
+        }
+        if (imp.d >= 0) {
+            // Dynamic import with a string literal specifier (e.g., `import('./Foo.vue')`)
+            // Dynamic imports have no local binding name, so we use '*' as a sentinel.
+            // Consumers should check `type === 'dynamic'` to distinguish from namespace imports.
+            bindings.push({
+                localName: '*',
+                importedName: '*',
+                source: imp.n,
+                type: 'dynamic',
+            });
+            continue;
+        }
+        // Static imports (d === -1)
+        // ss/se = statement start/end positions
+        const statementText = source.slice(imp.ss, imp.se);
+        bindings.push(...extractBindingsFromStatement(statementText, imp.n));
+    }
+    return bindings;
+}

package/lib/import-resolver/resolve-barrel.d.ts

@@ -0,0 +1,19 @@
+/**
+ * @module resolve-barrel
+ *
+ * Resolves barrel file (index.ts/index.js) re-exports to their original source.
+ * Only handles single-level barrel resolution — nested barrel chains are not followed.
+ *
+ * Given a specifier like `'./components'`, checks if it is a directory with an
+ * index file, parses that index file's export statements, and maps the requested
+ * binding name back to the original module.
+ */
+/**
+ * Resolves a barrel file re-export to the original source module path.
+ *
+ * @param specifier - The import specifier (e.g., `'./components'`)
+ * @param importedName - The name being imported (e.g., `'Button'`)
+ * @param importerPath - The absolute path of the file containing the import
+ * @returns The relative source path from the barrel file, or `null` if not a barrel or name not found
+ */
+export declare function resolveBarrelExport(specifier: string, importedName: string, importerPath: string): string | null;

package/lib/import-resolver/resolve-barrel.js

@@ -0,0 +1,113 @@
+/**
+ * @module resolve-barrel
+ *
+ * Resolves barrel file (index.ts/index.js) re-exports to their original source.
+ * Only handles single-level barrel resolution — nested barrel chains are not followed.
+ *
+ * Given a specifier like `'./components'`, checks if it is a directory with an
+ * index file, parses that index file's export statements, and maps the requested
+ * binding name back to the original module.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+/** Pattern to match `export { Name } from './source'` or `export { default as Name } from './source'` */
+const RE_NAMED_REEXPORT = /export\s*\{([^}]+)\}\s*from\s*['"]([^'"]+)['"]/;
+/** Index file names to check, in priority order */
+const INDEX_FILES = ['index.ts', 'index.js', 'index.mts', 'index.mjs'];
+/**
+ * Resolves a barrel file re-export to the original source module path.
+ *
+ * @param specifier - The import specifier (e.g., `'./components'`)
+ * @param importedName - The name being imported (e.g., `'Button'`)
+ * @param importerPath - The absolute path of the file containing the import
+ * @returns The relative source path from the barrel file, or `null` if not a barrel or name not found
+ */
+export function resolveBarrelExport(specifier, importedName, importerPath) {
+    // Only handle relative specifiers
+    if (!specifier.startsWith('.')) {
+        return null;
+    }
+    const importerDir = path.dirname(importerPath);
+    const resolved = path.resolve(importerDir, specifier);
+    // If the specifier points to an existing file, it's not a barrel
+    if (isFile(resolved)) {
+        return null;
+    }
+    // Check if the resolved path is a directory with an index file
+    const indexPath = findIndexFile(resolved);
+    if (!indexPath) {
+        return null;
+    }
+    let indexSource;
+    try {
+        indexSource = fs.readFileSync(indexPath, 'utf8');
+    }
+    catch (error) {
+        // eslint-disable-next-line no-console
+        console.warn(`Failed to read barrel file: ${indexPath}`, error instanceof Error ? error.message : error);
+        return null;
+    }
+    return matchExportedName(indexSource, importedName);
+}
+/**
+ * Finds the first matching index file in the given directory.
+ */
+function findIndexFile(dirPath) {
+    if (!isDirectory(dirPath)) {
+        return null;
+    }
+    for (const name of INDEX_FILES) {
+        const candidate = path.join(dirPath, name);
+        if (isFile(candidate)) {
+            return candidate;
+        }
+    }
+    return null;
+}
+/**
+ * Parses export statements in a barrel file and returns the source path
+ * for the given exported name.
+ */
+function matchExportedName(indexSource, targetName) {
+    // Parse named re-exports: `export { X } from '...'` and `export { default as X } from '...'`
+    let match;
+    const namedRe = new RegExp(RE_NAMED_REEXPORT.source, 'g');
+    while ((match = namedRe.exec(indexSource)) !== null) {
+        const entriesRaw = match[1];
+        const source = match[2];
+        for (const entry of entriesRaw.split(',')) {
+            const trimmed = entry.trim();
+            if (!trimmed) {
+                continue;
+            }
+            const asParts = trimmed.split(/\s+as\s+/);
+            // `default as Button` → exported name is `Button`
+            // `Button` → exported name is `Button`
+            // `Button as Btn` → exported name is `Btn`
+            const exportedName = asParts.length === 2 ? asParts[1].trim() : trimmed;
+            if (exportedName === targetName) {
+                return source;
+            }
+        }
+    }
+    // Star re-exports: `export * from '...'` — we can't statically verify the name,
+    // but for single-level resolution we do not traverse further.
+    // Return null since we can't confirm the name exists in the star export.
+    return null;
+}
+function isFile(p) {
+    try {
+        return fs.statSync(p).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+function isDirectory(p) {
+    try {
+        return fs.statSync(p).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}

package/lib/import-resolver/types.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Represents a single import binding extracted from a source file.
+ * Links a local name (used in template/code) to its source module path.
+ */
+export interface ImportBinding {
+    /**
+     * The local name used in the file (e.g., `MyButton`, `default as Btn` → `Btn`).
+     *
+     * For dynamic imports (`type === 'dynamic'`), this is set to `'*'` as a sentinel
+     * value because dynamic imports have no local binding name. Use the `type` field
+     * to distinguish dynamic imports from namespace imports (which also use `'*'`
+     * for `importedName`).
+     */
+    readonly localName: string;
+    /** The imported name from the source module (e.g., `default`, `MyButton`, or `*` for namespace/dynamic) */
+    readonly importedName: string;
+    /** The module specifier string (e.g., `./components/Button.vue`, `@/lib/utils`) */
+    readonly source: string;
+    /**
+     * The type of import binding:
+     * - `'default'` — `import X from '...'`
+     * - `'named'` — `import { X } from '...'`
+     * - `'namespace'` — `import * as X from '...'`
+     * - `'dynamic'` — `import('...')` with a string literal specifier
+     */
+    readonly type: 'default' | 'named' | 'namespace' | 'dynamic';
+}
+/**
+ * The result of analyzing imports in a source block.
+ */
+export interface ImportAnalysisResult {
+    /** All import bindings found in the source */
+    readonly bindings: readonly ImportBinding[];
+}

package/lib/import-resolver/types.js

@@ -0,0 +1 @@
+export {};

package/lib/index.d.ts

@@ -2,8 +2,34 @@
  * @module @markuplint/pretenders
  *
  * Provides scanning utilities for detecting component-to-element mappings (pretenders)
- * in JSX/TSX source files. Pretenders allow markuplint to understand which native HTML
+ * in source files. Pretenders allow markuplint to understand which native HTML
  * elements a component renders, enabling accurate linting of component-based code.
+ *
+ * ## Scanning
+ *
+ * - {@link scan} — Unified entry point that dispatches to the appropriate scanner by file extension
+ * - {@link jsxScanner} — Scans JSX/TSX files using the TypeScript compiler API
+ * - {@link templateScanner} — Scans Vue, Svelte, and Astro SFC files using markuplint's parsers
+ *
+ * ## Import resolution
+ *
+ * - {@link analyzeImports} — Extracts import bindings from component script blocks
+ *   (Vue `<script setup>`, Vue Options API, Svelte, Astro, MDX)
+ * - {@link resolveComponentImport} — Resolves a component name to its import binding,
+ *   including Vue kebab-case → PascalCase normalization
+ * - {@link resolveBarrelExport} — Resolves barrel file (`index.ts`/`index.js`) re-exports
+ *   to original source modules. Call this separately after `analyzeImports` when an import
+ *   source points to a directory with a barrel index.
+ *
+ * Dynamic imports (`import('./path')`) are included in bindings with `type: 'dynamic'`
+ * and `localName: '*'` as a sentinel. Check `type === 'dynamic'` to distinguish from
+ * namespace imports.
  */
 export { jsxScanner } from './jsx/index.js';
+export { templateScanner } from './template/index.js';
+export { scan } from './scan.js';
+export type { ScanOptions } from './scan.js';
+export { analyzeImports, resolveComponentImport, resolveBarrelExport } from './import-resolver/index.js';
+export type { ImportBinding, ImportAnalysisResult } from './import-resolver/types.js';
 export type * from './types.js';
+export type { ComponentScanner, ComponentScanResult, ComponentScanAttr, ComponentScanScriptSource, } from './component-scanner.js';

package/lib/index.js

@@ -2,7 +2,30 @@
  * @module @markuplint/pretenders
  *
  * Provides scanning utilities for detecting component-to-element mappings (pretenders)
- * in JSX/TSX source files. Pretenders allow markuplint to understand which native HTML
+ * in source files. Pretenders allow markuplint to understand which native HTML
  * elements a component renders, enabling accurate linting of component-based code.
+ *
+ * ## Scanning
+ *
+ * - {@link scan} — Unified entry point that dispatches to the appropriate scanner by file extension
+ * - {@link jsxScanner} — Scans JSX/TSX files using the TypeScript compiler API
+ * - {@link templateScanner} — Scans Vue, Svelte, and Astro SFC files using markuplint's parsers
+ *
+ * ## Import resolution
+ *
+ * - {@link analyzeImports} — Extracts import bindings from component script blocks
+ *   (Vue `<script setup>`, Vue Options API, Svelte, Astro, MDX)
+ * - {@link resolveComponentImport} — Resolves a component name to its import binding,
+ *   including Vue kebab-case → PascalCase normalization
+ * - {@link resolveBarrelExport} — Resolves barrel file (`index.ts`/`index.js`) re-exports
+ *   to original source modules. Call this separately after `analyzeImports` when an import
+ *   source points to a directory with a barrel index.
+ *
+ * Dynamic imports (`import('./path')`) are included in bindings with `type: 'dynamic'`
+ * and `localName: '*'` as a sentinel. Check `type === 'dynamic'` to distinguish from
+ * namespace imports.
  */
 export { jsxScanner } from './jsx/index.js';
+export { templateScanner } from './template/index.js';
+export { scan } from './scan.js';
+export { analyzeImports, resolveComponentImport, resolveBarrelExport } from './import-resolver/index.js';

package/lib/jsx/create-identify.d.ts

@@ -1,14 +1,13 @@
 import type { Attr } from '../types.js';
-import type { Slot } from '@markuplint/ml-config';
 /**
  * Creates a pretender identity from a JSX element's tag name, attributes, and slots.
- * If the element has no attributes, returns just the tag name string.
+ * If the element has no attributes and no slots, returns just the tag name string.
  * Otherwise, returns a detailed identity object including attributes, slots,
  * and whether the element inherits spread attributes.
  *
  * @param tagName - The HTML element or component tag name
  * @param attrs - The attributes discovered on the JSX element
- * @param slots - The child slots discovered within the JSX element
+ * @param slots - Whether the component accepts children (`true`) or not (`null`)
  * @returns A simple tag name string or a detailed Identity object
  */
-export declare function createIndentity(tagName: string, attrs: readonly Attr[], slots: readonly Slot[]): string | import("@markuplint/ml-config").OriginalNode;
+export declare function createIdentity(tagName: string, attrs: readonly Attr[], slots: null | true): string | import("@markuplint/ml-config").OriginalNode;

package/lib/jsx/create-identify.js

@@ -1,41 +1,26 @@
 /**
  * Creates a pretender identity from a JSX element's tag name, attributes, and slots.
- * If the element has no attributes, returns just the tag name string.
+ * If the element has no attributes and no slots, returns just the tag name string.
  * Otherwise, returns a detailed identity object including attributes, slots,
  * and whether the element inherits spread attributes.
  *
  * @param tagName - The HTML element or component tag name
  * @param attrs - The attributes discovered on the JSX element
- * @param slots - The child slots discovered within the JSX element
+ * @param slots - Whether the component accepts children (`true`) or not (`null`)
  * @returns A simple tag name string or a detailed Identity object
  */
-export function createIndentity(tagName, attrs, slots) {
-    if (attrs.length === 0) {
+export function createIdentity(tagName, attrs, slots) {
+    if (attrs.length === 0 && slots !== true) {
         return tagName;
     }
     const availableAttrs = attrs.filter(attr => attr.nodeType !== 'spread');
     const hasSpread = attrs.some(attr => attr.nodeType === 'spread');
-    const pretenderAttrs = availableAttrs.map(attr => {
-        const pretenderAttr = {
-            name: attr.name,
-        };
-        if (attr.nodeType === 'static' && attr.value) {
-            // @ts-ignore initialize readonly property
-            pretenderAttr.value = attr.value;
-        }
-        return pretenderAttr;
-    });
+    const pretenderAttrs = availableAttrs.map(attr => attr.nodeType === 'static' && attr.value ? { name: attr.name, value: attr.value } : { name: attr.name });
     const identify = {
         element: tagName,
         slots,
+        ...(pretenderAttrs.length > 0 ? { attrs: pretenderAttrs } : {}),
+        ...(hasSpread ? { inheritAttrs: true } : {}),
     };
-    if (pretenderAttrs.length > 0) {
-        // @ts-ignore initialize readonly property
-        identify.attrs = pretenderAttrs;
-    }
-    if (hasSpread) {
-        // @ts-ignore initialize readonly property
-        identify.inheritAttrs = true;
-    }
     return identify;
 }

package/lib/jsx/get-children.d.ts

@@ -1,11 +1,17 @@
-import type { Slot } from '@markuplint/ml-config';
 import type { JsxOpeningElement, JsxSelfClosingElement, SourceFile } from 'typescript';
 /**
- * Extracts child slot information from a JSX element.
- * Currently returns an empty array as child slot extraction is not yet implemented.
+ * Detects whether a JSX element accepts children by searching for
+ * `{children}` or `{props.children}` expressions in its content subtree.
  *
- * @param el - The JSX opening or self-closing element to extract children from
+ * Only searches content children (text, expressions, nested elements),
+ * NOT attribute values on the element or nested elements.
+ *
+ * - Self-closing elements (`<Foo />`) cannot have children → returns `null`
+ * - Opening elements with `{children}` or `{props.children}` in content → returns `true`
+ * - Opening elements without children expressions → returns `null`
+ *
+ * @param el - The JSX opening or self-closing element to inspect
  * @param sourceFile - The TypeScript source file containing the element
- * @returns An array of Slot objects representing discovered child slots
+ * @returns `true` if children are accepted, `null` otherwise
  */
-export declare function getChildren(el: JsxOpeningElement | JsxSelfClosingElement, sourceFile: SourceFile): Slot[];
+export declare function getChildren(el: JsxOpeningElement | JsxSelfClosingElement, sourceFile: SourceFile): null | true;

package/lib/jsx/get-children.js

@@ -1,18 +1,74 @@
-// import { finder } from './finder.js';
+import ts from 'typescript';
+const { forEachChild, isIdentifier, isJsxAttributes, isJsxElement, isJsxSelfClosingElement, isPropertyAccessExpression, } = ts;
 /**
- * Extracts child slot information from a JSX element.
- * Currently returns an empty array as child slot extraction is not yet implemented.
+ * Detects whether a JSX element accepts children by searching for
+ * `{children}` or `{props.children}` expressions in its content subtree.
  *
- * @param el - The JSX opening or self-closing element to extract children from
+ * Only searches content children (text, expressions, nested elements),
+ * NOT attribute values on the element or nested elements.
+ *
+ * - Self-closing elements (`<Foo />`) cannot have children → returns `null`
+ * - Opening elements with `{children}` or `{props.children}` in content → returns `true`
+ * - Opening elements without children expressions → returns `null`
+ *
+ * @param el - The JSX opening or self-closing element to inspect
  * @param sourceFile - The TypeScript source file containing the element
- * @returns An array of Slot objects representing discovered child slots
+ * @returns `true` if children are accepted, `null` otherwise
  */
 export function getChildren(
 // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
 el, 
 // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
 sourceFile) {
-    const children = [];
-    // const find = finder(sourceFile);
-    return children;
+    if (isJsxSelfClosingElement(el)) {
+        return null;
+    }
+    const parent = el.parent;
+    if (!isJsxElement(parent)) {
+        return null;
+    }
+    // Search only through content children (JsxChild[]),
+    // which excludes opening/closing tags and their attributes.
+    for (const child of parent.children) {
+        if (hasChildrenIdentifier(child, sourceFile)) {
+            return true;
+        }
+    }
+    return null;
+}
+/**
+ * Recursively checks whether a node or its descendants contain a
+ * `children` identifier or `props.children` property access.
+ *
+ * Skips JsxAttributes nodes to avoid false positives from
+ * `{children}` used as attribute values on nested elements.
+ */
+function hasChildrenIdentifier(
+// eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+node, 
+// eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+sourceFile) {
+    // Skip attribute containers — {children} in attrs is not a slot indicator
+    if (isJsxAttributes(node)) {
+        return false;
+    }
+    // {children}
+    if (isIdentifier(node) && node.getText(sourceFile) === 'children') {
+        return true;
+    }
+    // {props.children}
+    if (isPropertyAccessExpression(node) &&
+        isIdentifier(node.name) &&
+        node.name.getText(sourceFile) === 'children' &&
+        isIdentifier(node.expression) &&
+        node.expression.getText(sourceFile) === 'props') {
+        return true;
+    }
+    let found = false;
+    forEachChild(node, child => {
+        if (!found && hasChildrenIdentifier(child, sourceFile)) {
+            found = true;
+        }
+    });
+    return found;
 }

package/lib/jsx/index.d.ts

@@ -19,5 +19,9 @@ import type { Pretender } from '@markuplint/ml-config';
  * - HOC / wrapper function patterns
  * - Fragment and provider component transparency
  * - `@pretends null` JSDoc tag to opt out a component
+ *
+ * @param files - Absolute file paths to scan (relative paths cause a `ReferenceError`)
+ * @param options - JSX scanner configuration (fragment patterns, styled-components, wrappers, etc.)
+ * @returns Discovered pretender mappings for all components found in the given files
  */
 export declare const jsxScanner: (files: readonly string[], options?: PretenderScanJSXOptions | undefined) => Promise<Pretender[]>;