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

package/lib/import-resolver/extract-script-source.d.ts

@@ -0,0 +1,82 @@
+/**
+ * @module extract-script-source
+ *
+ * Framework-specific extractors that pull ESM source text from component files.
+ * Each framework stores imports in different locations:
+ *
+ * | Framework | Source Block               | Extraction Method          |
+ * |-----------|---------------------------|----------------------------|
+ * | Vue       | `<script setup>` tag      | Regex on raw source        |
+ * | Svelte    | `<script>` tag            | Regex on raw source        |
+ * | Astro     | Frontmatter (`---...---`) | Regex on raw source        |
+ * | MDX       | Top-level ESM             | Whole source (lexer-safe)  |
+ */
+/**
+ * The result of extracting a script source block from a component file.
+ */
+export interface ScriptSourceBlock {
+    /** The raw script/ESM content without delimiters */
+    readonly content: string;
+    /** The offset (in characters) of the content start within the original source */
+    readonly offset: number;
+}
+/**
+ * Extracts the content of the `<script setup>` block from a Vue SFC source.
+ * Handles optional `lang` attribute (e.g., `<script setup lang="ts">`).
+ * Only matches `<script setup>` — regular `<script>` blocks are ignored.
+ *
+ * @param source - The full Vue SFC source text
+ * @returns The extracted script block, or `null` if no `<script setup>` is found
+ */
+export declare function extractVueScriptSetup(source: string): ScriptSourceBlock | null;
+/**
+ * Extracts the content of a regular `<script>` block (NOT `<script setup>`) from a Vue SFC source.
+ * Only matches `<script>` without the `setup` attribute.
+ *
+ * @param source - The full Vue SFC source text
+ * @returns The extracted script block, or `null` if no regular `<script>` is found
+ */
+export declare function extractVueScript(source: string): ScriptSourceBlock | null;
+/**
+ * Extracts component names registered in the Vue Options API `components` property.
+ * Handles both shorthand (`{ Button }`) and aliased (`{ Btn: MyButton }`) forms.
+ * For aliased forms, returns the value (the import name), not the key (the template name).
+ *
+ * @param scriptContent - The content of the `<script>` block (without tags)
+ * @returns An array of component local names referenced in the `components` registration
+ */
+export declare function extractVueOptionsApiComponents(scriptContent: string): string[];
+/**
+ * Extracts the content of the `<script>` block from a Svelte component source.
+ * Prefers the instance `<script>` over `<script context="module">`.
+ * Falls back to the module script if no instance script is found.
+ *
+ * @param source - The full Svelte component source text
+ * @returns The extracted script block, or `null` if no `<script>` is found
+ */
+export declare function extractSvelteScript(source: string): ScriptSourceBlock | null;
+/**
+ * Extracts the content of the frontmatter block (`---...---`) from an Astro component source.
+ *
+ * @param source - The full Astro component source text
+ * @returns The extracted frontmatter block, or `null` if no frontmatter is found
+ */
+export declare function extractAstroFrontmatter(source: string): ScriptSourceBlock | null;
+/**
+ * Extracts the top-level ESM block from an MDX file.
+ * MDX files have standard ESM import/export statements at the top of the file,
+ * followed by markdown/JSX content. This function extracts only the contiguous
+ * block of import/export lines (including blank lines within the block),
+ * stopping at the first line that is clearly non-ESM content.
+ *
+ * Tracks brace depth to skip intermediate lines inside multi-line
+ * import/export blocks (e.g., `import { A, B } from '...'`).
+ * Note: the closing line of a multi-line block (e.g., `} from '...'`)
+ * is not recognized as ESM, so standalone multi-line imports are
+ * not captured. Single-line imports preceding a multi-line block
+ * are still returned correctly.
+ *
+ * @param source - The full MDX source text
+ * @returns The ESM block, or `null` if no import/export statements are found at the top
+ */
+export declare function extractMdxEsm(source: string): ScriptSourceBlock | null;

package/lib/import-resolver/extract-script-source.js

@@ -0,0 +1,227 @@
+/**
+ * @module extract-script-source
+ *
+ * Framework-specific extractors that pull ESM source text from component files.
+ * Each framework stores imports in different locations:
+ *
+ * | Framework | Source Block               | Extraction Method          |
+ * |-----------|---------------------------|----------------------------|
+ * | Vue       | `<script setup>` tag      | Regex on raw source        |
+ * | Svelte    | `<script>` tag            | Regex on raw source        |
+ * | Astro     | Frontmatter (`---...---`) | Regex on raw source        |
+ * | MDX       | Top-level ESM             | Whole source (lexer-safe)  |
+ */
+/**
+ * Extracts the content of the `<script setup>` block from a Vue SFC source.
+ * Handles optional `lang` attribute (e.g., `<script setup lang="ts">`).
+ * Only matches `<script setup>` — regular `<script>` blocks are ignored.
+ *
+ * @param source - The full Vue SFC source text
+ * @returns The extracted script block, or `null` if no `<script setup>` is found
+ */
+export function extractVueScriptSetup(source) {
+    // Match <script setup> with optional attributes like lang="ts"
+    const re = /<script\s[^>]*?\bsetup\b[^>]*>/i;
+    const match = re.exec(source);
+    if (!match) {
+        return null;
+    }
+    const startTag = match[0];
+    const contentStart = match.index + startTag.length;
+    const endTagRe = /<\/script\s*>/i;
+    const remaining = source.slice(contentStart);
+    const endMatch = endTagRe.exec(remaining);
+    if (!endMatch) {
+        return null;
+    }
+    return {
+        content: remaining.slice(0, endMatch.index),
+        offset: contentStart,
+    };
+}
+/**
+ * Extracts the content of a regular `<script>` block (NOT `<script setup>`) from a Vue SFC source.
+ * Only matches `<script>` without the `setup` attribute.
+ *
+ * @param source - The full Vue SFC source text
+ * @returns The extracted script block, or `null` if no regular `<script>` is found
+ */
+export function extractVueScript(source) {
+    const re = /<script(?:\s[^>]*)?>/gi;
+    let match;
+    while ((match = re.exec(source)) !== null) {
+        const startTag = match[0];
+        // Skip <script setup> blocks
+        if (/\bsetup\b/i.test(startTag)) {
+            continue;
+        }
+        const contentStart = match.index + startTag.length;
+        const remaining = source.slice(contentStart);
+        const endMatch = /<\/script\s*>/i.exec(remaining);
+        if (!endMatch) {
+            continue;
+        }
+        return {
+            content: remaining.slice(0, endMatch.index),
+            offset: contentStart,
+        };
+    }
+    return null;
+}
+/**
+ * Extracts component names registered in the Vue Options API `components` property.
+ * Handles both shorthand (`{ Button }`) and aliased (`{ Btn: MyButton }`) forms.
+ * For aliased forms, returns the value (the import name), not the key (the template name).
+ *
+ * @param scriptContent - The content of the `<script>` block (without tags)
+ * @returns An array of component local names referenced in the `components` registration
+ */
+export function extractVueOptionsApiComponents(scriptContent) {
+    if (!scriptContent) {
+        return [];
+    }
+    // Match `components: { ... }` allowing for multiline
+    const re = /\bcomponents\s*:\s*\{([^}]*)\}/;
+    const match = re.exec(scriptContent);
+    if (!match?.[1]) {
+        return [];
+    }
+    const names = [];
+    for (const entry of match[1].split(',')) {
+        const trimmed = entry.trim();
+        if (!trimmed) {
+            continue;
+        }
+        // Split on first colon only to handle values containing colons
+        const colonIdx = trimmed.indexOf(':');
+        if (colonIdx === -1) {
+            // Shorthand: `Button` → use as-is
+            names.push(trimmed);
+        }
+        else {
+            // Aliased form: `Btn: MyButton` → use value `MyButton`
+            const value = trimmed.slice(colonIdx + 1).trim();
+            if (value) {
+                names.push(value);
+            }
+        }
+    }
+    return names;
+}
+/**
+ * Extracts the content of the `<script>` block from a Svelte component source.
+ * Prefers the instance `<script>` over `<script context="module">`.
+ * Falls back to the module script if no instance script is found.
+ *
+ * @param source - The full Svelte component source text
+ * @returns The extracted script block, or `null` if no `<script>` is found
+ */
+export function extractSvelteScript(source) {
+    const re = /<script(?:\s[^>]*)?>/gi;
+    let match;
+    let moduleBlock = null;
+    while ((match = re.exec(source)) !== null) {
+        const startTag = match[0];
+        const isModule = /\bcontext\s*=\s*["']module["']/i.test(startTag);
+        const contentStart = match.index + startTag.length;
+        const endTagRe = /<\/script\s*>/i;
+        const remaining = source.slice(contentStart);
+        const endMatch = endTagRe.exec(remaining);
+        if (!endMatch) {
+            continue;
+        }
+        const block = {
+            content: remaining.slice(0, endMatch.index),
+            offset: contentStart,
+        };
+        if (!isModule) {
+            return block; // Prefer instance script
+        }
+        // Remember module script as fallback
+        moduleBlock ??= block;
+    }
+    return moduleBlock;
+}
+/**
+ * Extracts the content of the frontmatter block (`---...---`) from an Astro component source.
+ *
+ * @param source - The full Astro component source text
+ * @returns The extracted frontmatter block, or `null` if no frontmatter is found
+ */
+export function extractAstroFrontmatter(source) {
+    const re = /^(?:\s*\n)?---\r?\n/;
+    const startMatch = re.exec(source);
+    if (!startMatch) {
+        return null;
+    }
+    const contentStart = startMatch[0].length;
+    const afterStart = source.slice(contentStart);
+    const endRe = /\r?\n---\r?\n/;
+    const endMatch = endRe.exec(afterStart);
+    if (!endMatch) {
+        return null;
+    }
+    return {
+        content: afterStart.slice(0, endMatch.index),
+        offset: contentStart,
+    };
+}
+/**
+ * Extracts the top-level ESM block from an MDX file.
+ * MDX files have standard ESM import/export statements at the top of the file,
+ * followed by markdown/JSX content. This function extracts only the contiguous
+ * block of import/export lines (including blank lines within the block),
+ * stopping at the first line that is clearly non-ESM content.
+ *
+ * Tracks brace depth to skip intermediate lines inside multi-line
+ * import/export blocks (e.g., `import { A, B } from '...'`).
+ * Note: the closing line of a multi-line block (e.g., `} from '...'`)
+ * is not recognized as ESM, so standalone multi-line imports are
+ * not captured. Single-line imports preceding a multi-line block
+ * are still returned correctly.
+ *
+ * @param source - The full MDX source text
+ * @returns The ESM block, or `null` if no import/export statements are found at the top
+ */
+export function extractMdxEsm(source) {
+    const lines = source.split('\n');
+    let esmEnd = 0;
+    let pos = 0;
+    let braceDepth = 0;
+    for (const line of lines) {
+        const trimmed = line.trim();
+        // Track brace depth for multi-line imports
+        for (const ch of line) {
+            if (ch === '{') {
+                braceDepth++;
+            }
+            if (ch === '}') {
+                braceDepth--;
+            }
+        }
+        pos += line.length + 1; // +1 for '\n'
+        // Inside a multi-line import/export block
+        if (braceDepth > 0) {
+            continue;
+        }
+        // ESM-like lines: import, export, empty, single-line comments
+        if (trimmed === '' || /^import\s/.test(trimmed) || /^export\s/.test(trimmed) || trimmed.startsWith('//')) {
+            esmEnd = pos;
+            continue;
+        }
+        // Non-ESM content (markdown, JSX, etc.) — stop
+        break;
+    }
+    if (esmEnd === 0) {
+        return null;
+    }
+    const content = source.slice(0, esmEnd);
+    // Verify the extracted block actually contains import/export statements
+    if (!/\b(?:import|export)\s/.test(content)) {
+        return null;
+    }
+    return {
+        content,
+        offset: 0,
+    };
+}

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

@@ -0,0 +1,85 @@
+/**
+ * @module import-resolver
+ *
+ * Import analysis module that extracts import statements from `<script>` /
+ * frontmatter / ESM blocks in component files, linking template component
+ * usage to source file locations.
+ *
+ * Uses es-module-lexer (WASM-based) to identify import specifiers, then
+ * supplements with regex parsing on statement slices to extract local names.
+ *
+ * ## Supported frameworks
+ *
+ * - Vue `<script setup>` (all static imports are exposed as bindings)
+ * - Vue Options API `components` property (fallback when no `<script setup>`;
+ *   only imports registered in `components: { ... }` are returned)
+ * - Svelte `<script>` tags (prefers instance script over module script)
+ * - Astro frontmatter (`---...---`)
+ * - MDX top-level ESM
+ *
+ * ## Dynamic imports
+ *
+ * Dynamic imports with string literal specifiers (`import('./path')`) are
+ * included in the bindings with `type: 'dynamic'`. These bindings use
+ * `localName: '*'` as a sentinel since dynamic imports have no local binding.
+ * Template literal and variable specifiers are excluded.
+ *
+ * ## Barrel file resolution
+ *
+ * `resolveBarrelExport` is a standalone utility (not called by `analyzeImports`)
+ * that resolves a named import from a barrel directory (e.g., `'./components'`)
+ * to its original source module. Only single-level re-exports are resolved.
+ *
+ * ### Usage example: resolving barrel imports
+ *
+ * ```ts
+ * import { analyzeImports, resolveComponentImport, resolveBarrelExport } from '@markuplint/pretenders';
+ *
+ * const result = await analyzeImports('App.vue', source);
+ * const binding = resolveComponentImport('Button', result.bindings);
+ *
+ * if (binding) {
+ *   // Check if the import source is a barrel directory
+ *   const originalSource = resolveBarrelExport(binding.source, binding.importedName, filePath);
+ *   // originalSource: './Button.vue' (resolved from './components' barrel)
+ * }
+ * ```
+ *
+ * ## Excludes
+ *
+ * - `import.meta` references
+ * - Dynamic imports with template literals or variable specifiers
+ * - Multi-level barrel chains (only single-level re-exports are resolved)
+ *
+ * ## Future integration
+ *
+ * The current implementation uses regex-based source extraction.
+ * When the CLI multi-framework dispatch (#3340) creates a unified parsing
+ * pipeline, MLAST psblock-based extraction can be integrated by parsing
+ * the file once and passing the document to both templateScanner and
+ * import-resolver.
+ */
+import type { ImportBinding, ImportAnalysisResult } from './types.js';
+export { resolveBarrelExport } from './resolve-barrel.js';
+export type { ImportBinding, ImportAnalysisResult } from './types.js';
+/**
+ * Analyzes a component file's source text and extracts all static import bindings.
+ * Automatically detects the framework type from the file extension and extracts
+ * the appropriate source block (script setup, script, frontmatter, or top-level ESM).
+ *
+ * @param filePath - The absolute or relative file path (used for framework detection)
+ * @param source - The full source text of the component file
+ * @returns The analysis result with all import bindings, or `null` if the framework
+ *          is not supported or no relevant script block is found
+ */
+export declare function analyzeImports(filePath: string, source: string): Promise<ImportAnalysisResult | null>;
+/**
+ * Resolves a component name used in a template to its import source path.
+ * For Vue, handles both PascalCase (`<MyButton>`) and kebab-case (`<my-button>`)
+ * representations of the same component by normalizing to PascalCase for lookup.
+ *
+ * @param componentName - The component name as used in the template
+ * @param bindings - The import bindings extracted from the script block
+ * @returns The matching import binding, or `undefined` if no match is found
+ */
+export declare function resolveComponentImport(componentName: string, bindings: readonly ImportBinding[]): ImportBinding | undefined;

package/lib/import-resolver/index.js

@@ -0,0 +1,184 @@
+/**
+ * @module import-resolver
+ *
+ * Import analysis module that extracts import statements from `<script>` /
+ * frontmatter / ESM blocks in component files, linking template component
+ * usage to source file locations.
+ *
+ * Uses es-module-lexer (WASM-based) to identify import specifiers, then
+ * supplements with regex parsing on statement slices to extract local names.
+ *
+ * ## Supported frameworks
+ *
+ * - Vue `<script setup>` (all static imports are exposed as bindings)
+ * - Vue Options API `components` property (fallback when no `<script setup>`;
+ *   only imports registered in `components: { ... }` are returned)
+ * - Svelte `<script>` tags (prefers instance script over module script)
+ * - Astro frontmatter (`---...---`)
+ * - MDX top-level ESM
+ *
+ * ## Dynamic imports
+ *
+ * Dynamic imports with string literal specifiers (`import('./path')`) are
+ * included in the bindings with `type: 'dynamic'`. These bindings use
+ * `localName: '*'` as a sentinel since dynamic imports have no local binding.
+ * Template literal and variable specifiers are excluded.
+ *
+ * ## Barrel file resolution
+ *
+ * `resolveBarrelExport` is a standalone utility (not called by `analyzeImports`)
+ * that resolves a named import from a barrel directory (e.g., `'./components'`)
+ * to its original source module. Only single-level re-exports are resolved.
+ *
+ * ### Usage example: resolving barrel imports
+ *
+ * ```ts
+ * import { analyzeImports, resolveComponentImport, resolveBarrelExport } from '@markuplint/pretenders';
+ *
+ * const result = await analyzeImports('App.vue', source);
+ * const binding = resolveComponentImport('Button', result.bindings);
+ *
+ * if (binding) {
+ *   // Check if the import source is a barrel directory
+ *   const originalSource = resolveBarrelExport(binding.source, binding.importedName, filePath);
+ *   // originalSource: './Button.vue' (resolved from './components' barrel)
+ * }
+ * ```
+ *
+ * ## Excludes
+ *
+ * - `import.meta` references
+ * - Dynamic imports with template literals or variable specifiers
+ * - Multi-level barrel chains (only single-level re-exports are resolved)
+ *
+ * ## Future integration
+ *
+ * The current implementation uses regex-based source extraction.
+ * When the CLI multi-framework dispatch (#3340) creates a unified parsing
+ * pipeline, MLAST psblock-based extraction can be integrated by parsing
+ * the file once and passing the document to both templateScanner and
+ * import-resolver.
+ */
+import path from 'node:path';
+import { extractVueScriptSetup, extractVueScript, extractVueOptionsApiComponents, extractSvelteScript, extractAstroFrontmatter, extractMdxEsm, } from './extract-script-source.js';
+import { parseImports } from './parse-imports.js';
+export { resolveBarrelExport } from './resolve-barrel.js';
+const EXTENSION_MAP = {
+    '.vue': 'vue',
+    '.svelte': 'svelte',
+    '.astro': 'astro',
+    '.mdx': 'mdx',
+};
+/**
+ * Determines the framework type from the file extension.
+ * Local to import-resolver to include MDX without affecting templateScanner.
+ */
+function getImportFrameworkType(filePath) {
+    const ext = path.extname(filePath).toLowerCase();
+    return EXTENSION_MAP[ext] ?? null;
+}
+/**
+ * Analyzes a component file's source text and extracts all static import bindings.
+ * Automatically detects the framework type from the file extension and extracts
+ * the appropriate source block (script setup, script, frontmatter, or top-level ESM).
+ *
+ * @param filePath - The absolute or relative file path (used for framework detection)
+ * @param source - The full source text of the component file
+ * @returns The analysis result with all import bindings, or `null` if the framework
+ *          is not supported or no relevant script block is found
+ */
+export async function analyzeImports(filePath, source) {
+    const framework = getImportFrameworkType(filePath);
+    if (!framework) {
+        return null;
+    }
+    let scriptSource = null;
+    switch (framework) {
+        case 'vue': {
+            scriptSource = extractVueScriptSetup(source);
+            if (!scriptSource) {
+                // Fallback to Vue Options API: extract regular <script>, parse imports,
+                // then filter to only those registered in the `components` property.
+                return analyzeVueOptionsApi(source);
+            }
+            break;
+        }
+        case 'svelte': {
+            scriptSource = extractSvelteScript(source);
+            break;
+        }
+        case 'astro': {
+            scriptSource = extractAstroFrontmatter(source);
+            break;
+        }
+        case 'mdx': {
+            scriptSource = extractMdxEsm(source);
+            break;
+        }
+    }
+    if (!scriptSource) {
+        return { bindings: [] };
+    }
+    const bindings = await parseImports(scriptSource.content);
+    return { bindings };
+}
+/**
+ * Analyzes a Vue SFC's regular `<script>` block for Options API component registration.
+ * Parses all imports from the script block, then filters to only those whose
+ * local name appears in the `components: { ... }` property.
+ *
+ * @param source - The full Vue SFC source text
+ * @returns The analysis result with filtered bindings, or empty bindings if not applicable
+ */
+async function analyzeVueOptionsApi(source) {
+    const scriptBlock = extractVueScript(source);
+    if (!scriptBlock) {
+        return { bindings: [] };
+    }
+    const allBindings = await parseImports(scriptBlock.content);
+    const componentNames = extractVueOptionsApiComponents(scriptBlock.content);
+    if (componentNames.length === 0) {
+        return { bindings: [] };
+    }
+    const componentNameSet = new Set(componentNames);
+    const bindings = allBindings.filter(b => componentNameSet.has(b.localName));
+    return { bindings };
+}
+/**
+ * Resolves a component name used in a template to its import source path.
+ * For Vue, handles both PascalCase (`<MyButton>`) and kebab-case (`<my-button>`)
+ * representations of the same component by normalizing to PascalCase for lookup.
+ *
+ * @param componentName - The component name as used in the template
+ * @param bindings - The import bindings extracted from the script block
+ * @returns The matching import binding, or `undefined` if no match is found
+ */
+export function resolveComponentImport(componentName, bindings) {
+    // Direct match
+    const direct = bindings.find(b => b.localName === componentName);
+    if (direct) {
+        return direct;
+    }
+    // Vue kebab-case → PascalCase normalization
+    const pascalName = kebabToPascalCase(componentName);
+    if (pascalName !== componentName) {
+        return bindings.find(b => b.localName === pascalName);
+    }
+    return undefined;
+}
+/**
+ * Converts a kebab-case string to PascalCase.
+ * Used for Vue's component name resolution where `<my-button>` maps to `MyButton`.
+ *
+ * @param str - The kebab-case string
+ * @returns The PascalCase equivalent
+ */
+function kebabToPascalCase(str) {
+    if (!str.includes('-')) {
+        return str;
+    }
+    return str
+        .split('-')
+        .map(part => (part.length > 0 ? part[0].toUpperCase() + part.slice(1) : ''))
+        .join('');
+}

package/lib/import-resolver/parse-imports.d.ts

@@ -0,0 +1,19 @@
+/**
+ * @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 type { ImportBinding } from './types.js';
+/**
+ * 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 declare function parseImports(source: string): Promise<readonly ImportBinding[]>;