@markuplint/pretenders 5.0.0-rc.4 → 5.0.0-rc.6

package/CHANGELOG.md

@@ -3,6 +3,20 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [5.0.0-rc.6](https://github.com/markuplint/markuplint/compare/v5.0.0-rc.5...v5.0.0-rc.6) (2026-08-30)
+
+**Note:** Version bump only for package @markuplint/pretenders
+
+# [5.0.0-rc.5](https://github.com/markuplint/markuplint/compare/v5.0.0-rc.4...v5.0.0-rc.5) (2026-08-28)
+
+### Bug Fixes
+
+- **pretenders:** resolve same-named components via imports, not scan order ([#3957](https://github.com/markuplint/markuplint/issues/3957)) ([d46a514](https://github.com/markuplint/markuplint/commit/d46a5148c4d7afb156962f4ed795f40a9324e6c5)), closes [#3951](https://github.com/markuplint/markuplint/issues/3951) [#3951](https://github.com/markuplint/markuplint/issues/3951) [#3951](https://github.com/markuplint/markuplint/issues/3951)
+
+### Features
+
+- add `pretenders.auto` for on-demand import-graph resolution ([#3962](https://github.com/markuplint/markuplint/issues/3962)) ([5870671](https://github.com/markuplint/markuplint/commit/58706711a20c12cff080d49359f3f6443345eca3)), closes [#3951](https://github.com/markuplint/markuplint/issues/3951) [#3957](https://github.com/markuplint/markuplint/issues/3957) [#3951](https://github.com/markuplint/markuplint/issues/3951) [#3957](https://github.com/markuplint/markuplint/issues/3957) [#3951](https://github.com/markuplint/markuplint/issues/3951) [#3957](https://github.com/markuplint/markuplint/issues/3957) [#3951](https://github.com/markuplint/markuplint/issues/3951) [#3957](https://github.com/markuplint/markuplint/issues/3957) [#3951](https://github.com/markuplint/markuplint/issues/3951) [#3957](https://github.com/markuplint/markuplint/issues/3957) [#3959](https://github.com/markuplint/markuplint/issues/3959) [#3951](https://github.com/markuplint/markuplint/issues/3951) [#3957](https://github.com/markuplint/markuplint/issues/3957) [#3951](https://github.com/markuplint/markuplint/issues/3951) [#3957](https://github.com/markuplint/markuplint/issues/3957) [#3959](https://github.com/markuplint/markuplint/issues/3959) [#3951](https://github.com/markuplint/markuplint/issues/3951) [#3951](https://github.com/markuplint/markuplint/issues/3951)
+
 # [5.0.0-rc.4](https://github.com/markuplint/markuplint/compare/v5.0.0-rc.3...v5.0.0-rc.4) (2026-04-19)
 
 **Note:** Version bump only for package @markuplint/pretenders

package/README.md

@@ -49,6 +49,21 @@ Instead of the CLI, you can configure dynamic scanning directly in your markupli
 }
 ```
 
+### On-demand Scanning
+
+`scan` pre-scans a configured set of files once. Alternatively, the `auto` field resolves pretenders per lint target by walking the linted file's own import graph — no `files`/`scan` configuration needed, and same-named components in unrelated files can't collide since only files the linted file actually imports (transitively) are ever considered:
+
+```jsonc
+// .markuplintrc
+{
+  "pretenders": {
+    "auto": true,
+  },
+}
+```
+
+Only the config file is filesystem-watched, so in watch mode or an editor session, results can go stale if an imported component file changes without the config changing too.
+
 ## How It Works
 
 ### JSX Scanner
@@ -121,20 +136,25 @@ Slot detection covers:
 
 ### Import Resolver
 
-The import resolver analyzes `<script>` / frontmatter / ESM blocks in component files and extracts import bindings. This links template component usage to source file locations, enabling cross-file dependency resolution.
-
-Script source extraction is delegated to each parser's component-scanner (Vue, Svelte, Astro), while MDX extraction is built-in. Supported script block types:
+The import resolver analyzes a component file and extracts import bindings, linking component usage to source file locations for cross-file dependency resolution.
 
 - Vue `<script setup>` (via `@markuplint/vue-parser/component-scanner`)
 - Vue Options API `<script>` (fallback when no `<script setup>`; only imports registered in `components: { ... }` are returned)
 - Svelte `<script>` (via `@markuplint/svelte-parser/component-scanner`; prefers instance script over module script)
 - Astro frontmatter (via `@markuplint/astro-parser/component-scanner`)
 - MDX top-level ESM (built-in)
+- JS/TS/JSX/TSX (`.js`, `.jsx`, `.ts`, `.tsx`, `.mjs`, `.cjs`, `.mts`, `.cts`): analyzed directly via the TypeScript AST, so JSX syntax and non-standard TS constructs (which `es-module-lexer` cannot parse) are handled correctly
 
 Dynamic imports with string literal specifiers (`import('./path')`) are included in bindings with `type: 'dynamic'`. Template literal and variable specifiers are excluded.
 
 Barrel file re-exports can be resolved with `resolveBarrelExport`, which maps a named import from a directory with an index file back to its original source module (single-level only).
 
+### Lint-time Disambiguation
+
+When the same component name is declared in more than one scanned file (e.g., two unrelated `Item` components rendering different elements), the generated pretenders keep independent entries for each — but `markuplint`'s lint pipeline still needs to know, for the specific file being linted, which one it actually refers to. `disambiguatePretenders` resolves this from the lint target's own declarations and imports; it's normally invoked automatically by `markuplint`'s config resolution, not called directly.
+
+In long-running hosts (watch mode, editor extensions) that keep re-resolving pretenders across file edits, call `clearPretenderCaches()` after each edit — otherwise a renamed export or a newly valid tsconfig `paths` alias keeps resolving as it did before the change for the rest of the process's lifetime.
+
 ## API
 
 ### `scan(files, options)`
@@ -210,9 +230,9 @@ const pretenders = await templateScanner(
 
 ### `analyzeImports(filePath, source)`
 
-Extracts import bindings from a component file's script block. Detects the framework from the file extension and extracts the appropriate source block automatically.
+Extracts import bindings from a component file. Detects the framework from the file extension and extracts the appropriate source automatically — `.vue`, `.svelte`, `.astro`, and `.mdx` extract a script/frontmatter/ESM block first, while `.js`, `.jsx`, `.ts`, `.tsx`, `.mjs`, `.cjs`, `.mts`, and `.cts` are analyzed directly via the TypeScript AST (which, unlike `es-module-lexer`, can parse JSX syntax).
 
-Returns `null` if the file extension is not a supported framework (`.vue`, `.svelte`, `.astro`, `.mdx`).
+Returns `null` if the file extension is not one of the above.
 
 ```ts
 import { analyzeImports } from '@markuplint/pretenders';
@@ -281,3 +301,61 @@ if (binding) {
 #### Returns
 
 `string | null` — The relative source path from the barrel file, or `null` if not a barrel or name not found.
+
+### `disambiguatePretenders(pretenders, options)`
+
+Given a flat pretender list and the file currently being linted, resolves which of several same-selector candidates that file actually refers to. Entries without a `filePath`, or whose `selector` isn't a plain identifier, are never touched. Normally invoked automatically as part of `markuplint`'s config resolution.
+
+```ts
+import { disambiguatePretenders } from '@markuplint/pretenders';
+
+const resolved = await disambiguatePretenders(pretenders, {
+  filePath: '/absolute/path/to/Page.tsx',
+  sourceCode: source,
+});
+```
+
+#### Parameters
+
+| Parameter            | Type                   | Description                                 |
+| -------------------- | ---------------------- | ------------------------------------------- |
+| `pretenders`         | `readonly Pretender[]` | The resolved pretender list to disambiguate |
+| `options.filePath`   | `string`               | Absolute path of the file being linted      |
+| `options.sourceCode` | `string`               | Full source text of the file being linted   |
+
+#### Returns
+
+`Promise<readonly Pretender[]>` — The disambiguated pretender list, or `pretenders` itself when there was nothing to resolve or nothing could be confirmed.
+
+### `autoScan(entryAbsPath, sourceCode)`
+
+Resolves pretenders on demand by walking a single lint target's own import graph (breadth-first, extension-agnostic — a `.tsx` entry can import a `.vue` file and vice versa) and scanning the collected files in one batch. This is the resolution logic behind the `pretenders.auto` config option; it's normally invoked automatically as part of `markuplint`'s config resolution, not called directly.
+
+```ts
+import { autoScan } from '@markuplint/pretenders';
+
+const pretenders = await autoScan('/absolute/path/to/Page.tsx', sourceCode);
+```
+
+#### Parameters
+
+| Parameter      | Type     | Description                                                   |
+| -------------- | -------- | ------------------------------------------------------------- |
+| `entryAbsPath` | `string` | Absolute path of the file being linted                        |
+| `sourceCode`   | `string` | The entry file's current text (may be unsaved editor content) |
+
+#### Returns
+
+`Promise<Pretender[]>` — Discovered pretender mappings for the entry file and its import graph.
+
+Results are cached per entry path, keyed on `sourceCode` equality (not mtime, which doesn't exist for unsaved editor content); `node_modules` is never traversed into, and import cycles are handled via a visited set. Traversal is capped at 8 import hops for template-language (`.vue`/`.svelte`/`.astro`) chains, but this cap does not hold for JSX/TSX-only chains: `jsxScanner` builds a `ts.Program` from the collected files, and TypeScript's own module resolution transitively pulls in whatever those files import regardless of the cap.
+
+### `clearPretenderCaches()`
+
+Clears the module-level caches that back import/export resolution (module resolution, export tables, parsed JSX source files, `autoScan` results). None of these caches expire on their own, so a long-running host (watch mode, an editor extension) that keeps resolving pretenders across file edits must call this after each edit — otherwise a renamed export or a newly valid tsconfig `paths` alias keeps resolving as it did before the change for the rest of the process's lifetime.
+
+```ts
+import { clearPretenderCaches } from '@markuplint/pretenders';
+
+clearPretenderCaches();
+```

package/lib/auto-scan.d.ts

@@ -0,0 +1,36 @@
+/**
+ * @module auto-scan
+ *
+ * On-demand pretender resolution: given a single lint target's absolute path
+ * and current source text, walks its import graph (breadth-first) to collect
+ * the transitively-referenced component files, then scans all of them in one
+ * batch. This lets `pretenders: { auto: true }` work without any
+ * pre-configured `files`/`scan` glob, at the cost of running a scan per lint
+ * target instead of once per project (see `jsx/compiler-host.ts` for the
+ * content-based caching that offsets this).
+ *
+ * Traversal is extension-agnostic — a `.tsx` entry can import a `.vue` file
+ * and vice versa, even though TypeScript's own module resolution can't
+ * follow into `.vue` (it falls back to a filesystem search; see
+ * `resolveModuleFile`). Per-extension scanner dispatch only happens at the
+ * final `scan()` call.
+ */
+import type { Pretender } from '@markuplint/ml-config';
+/**
+ * Clears the module-level auto-scan result cache. This cache is keyed on the
+ * ENTRY file's path and content only, so an edit to any other file in the
+ * entry's import graph does not invalidate it — a long-running host must call
+ * `clearPretenderCaches()` (which includes this one) after an edit to any file
+ * `autoScan` may have walked, not just after an edit to the entry itself.
+ */
+export declare function clearAutoScanCache(): void;
+/**
+ * Resolves pretenders on demand by scanning `entryAbsPath`'s own import graph:
+ * the entry file plus every file it transitively imports (up to a fixed
+ * traversal depth), scanned together in one `scan()` call.
+ *
+ * @param entryAbsPath - Absolute path of the file currently being linted
+ * @param sourceCode - The entry file's current text (may be unsaved editor content)
+ * @returns Discovered pretender mappings for the entry file and its import graph
+ */
+export declare function autoScan(entryAbsPath: string, sourceCode: string): Promise<Pretender[]>;

package/lib/auto-scan.js

@@ -0,0 +1,137 @@
+/**
+ * @module auto-scan
+ *
+ * On-demand pretender resolution: given a single lint target's absolute path
+ * and current source text, walks its import graph (breadth-first) to collect
+ * the transitively-referenced component files, then scans all of them in one
+ * batch. This lets `pretenders: { auto: true }` work without any
+ * pre-configured `files`/`scan` glob, at the cost of running a scan per lint
+ * target instead of once per project (see `jsx/compiler-host.ts` for the
+ * content-based caching that offsets this).
+ *
+ * Traversal is extension-agnostic — a `.tsx` entry can import a `.vue` file
+ * and vice versa, even though TypeScript's own module resolution can't
+ * follow into `.vue` (it falls back to a filesystem search; see
+ * `resolveModuleFile`). Per-extension scanner dispatch only happens at the
+ * final `scan()` call.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { isFatalError } from '@markuplint/shared';
+import { analyzeImports } from './import-resolver/index.js';
+import { normalizePath, resolveModuleFile } from './import-resolver/resolve-module-file.js';
+import { scan } from './scan.js';
+const SCANNABLE_EXTENSIONS = new Set([
+    '.js',
+    '.jsx',
+    '.ts',
+    '.tsx',
+    '.mjs',
+    '.cjs',
+    '.mts',
+    '.cts',
+    '.vue',
+    '.svelte',
+    '.astro',
+]);
+// Bounds runaway traversal (a deep or wrongly resolved chain) rather than
+// expressing a real limit on legitimate component nesting. Note this only
+// bounds which files BFS explicitly visits: for JSX/TSX files, jsxScanner
+// builds a ts.Program from the collected file list, and TypeScript's own
+// module resolution transitively pulls in whatever those files import —
+// including files past this depth — so the cap is not a hard ceiling on
+// what ends up scanned when the chain is JSX/TSX throughout.
+const MAX_DEPTH = 8;
+const resultCache = new Map();
+/**
+ * Clears the module-level auto-scan result cache. This cache is keyed on the
+ * ENTRY file's path and content only, so an edit to any other file in the
+ * entry's import graph does not invalidate it — a long-running host must call
+ * `clearPretenderCaches()` (which includes this one) after an edit to any file
+ * `autoScan` may have walked, not just after an edit to the entry itself.
+ */
+export function clearAutoScanCache() {
+    resultCache.clear();
+}
+/**
+ * Resolves pretenders on demand by scanning `entryAbsPath`'s own import graph:
+ * the entry file plus every file it transitively imports (up to a fixed
+ * traversal depth), scanned together in one `scan()` call.
+ *
+ * @param entryAbsPath - Absolute path of the file currently being linted
+ * @param sourceCode - The entry file's current text (may be unsaved editor content)
+ * @returns Discovered pretender mappings for the entry file and its import graph
+ */
+export async function autoScan(entryAbsPath, sourceCode) {
+    const entryKey = normalizePath(entryAbsPath);
+    const cached = resultCache.get(entryKey);
+    if (cached && cached.sourceCode === sourceCode) {
+        return cached.pretenders;
+    }
+    const sources = new Map([[entryKey, sourceCode]]);
+    const visited = new Set([entryKey]);
+    const collected = [];
+    if (isScannable(entryAbsPath)) {
+        collected.push(entryAbsPath);
+    }
+    let frontier = [
+        { absPath: entryAbsPath, source: sourceCode },
+    ];
+    for (let depth = 0; depth < MAX_DEPTH && frontier.length > 0; depth++) {
+        const nextFrontier = [];
+        for (const { absPath, source } of frontier) {
+            const analysis = await analyzeImports(absPath, source);
+            if (!analysis) {
+                continue;
+            }
+            for (const binding of analysis.bindings) {
+                const resolved = resolveModuleFile(absPath, binding.source);
+                if (!resolved) {
+                    continue;
+                }
+                const key = normalizePath(resolved);
+                if (visited.has(key) || key.includes('/node_modules/')) {
+                    continue;
+                }
+                visited.add(key);
+                if (isDeclarationFile(resolved) || !isScannable(resolved)) {
+                    continue;
+                }
+                collected.push(resolved);
+                const childSource = readFileSafe(resolved);
+                if (childSource == null) {
+                    continue;
+                }
+                // Feed this read into `sources` so the `scan()` call below reuses it
+                // instead of hitting disk again — both the scanners' own file reads
+                // and the export-table construction behind same-selector
+                // disambiguation consult `sources` first.
+                sources.set(key, childSource);
+                nextFrontier.push({ absPath: resolved, source: childSource });
+            }
+        }
+        frontier = nextFrontier;
+    }
+    const pretenders = await scan(collected, { sources });
+    resultCache.set(entryKey, { sourceCode, pretenders });
+    return pretenders;
+}
+function isScannable(filePath) {
+    return SCANNABLE_EXTENSIONS.has(path.extname(filePath).toLowerCase());
+}
+const DECLARATION_SUFFIXES = ['.d.ts', '.d.mts', '.d.cts'];
+function isDeclarationFile(filePath) {
+    const lower = filePath.toLowerCase();
+    return DECLARATION_SUFFIXES.some(suffix => lower.endsWith(suffix));
+}
+function readFileSafe(filePath) {
+    try {
+        return fs.readFileSync(filePath, 'utf8');
+    }
+    catch (error) {
+        if (isFatalError(error)) {
+            throw error;
+        }
+        return null;
+    }
+}

package/lib/cli.d.ts

@@ -1,11 +1 @@
-/**
- * CLI entry point for the pretenders scanner.
- * Accepts file glob patterns as input arguments and writes discovered
- * pretender mappings to a JSON output file.
- *
- * Usage: pretenders [options] <glob patterns...>
- * Flags:
- *   -O, --out <path>   Output file path (required)
- *   --ignore <names>   Comma-separated list of component names to ignore
- */
 export {};

package/lib/cli.js

@@ -1,13 +1,3 @@
-/**
- * CLI entry point for the pretenders scanner.
- * Accepts file glob patterns as input arguments and writes discovered
- * pretender mappings to a JSON output file.
- *
- * Usage: pretenders [options] <glob patterns...>
- * Flags:
- *   -O, --out <path>   Output file path (required)
- *   --ignore <names>   Comma-separated list of component names to ignore
- */
 import path from 'node:path';
 import meow from 'meow';
 import { getFileList } from './input.js';
@@ -35,6 +25,6 @@ async function main() {
         ignoreComponentNames: commands.flags.ignore?.split(',').map(s => s.trim()),
     });
     const outFilePath = path.resolve(process.cwd(), commands.flags.out);
-    await out(outFilePath, pretenders);
+    await out(outFilePath, pretenders, process.cwd());
 }
 await main();

package/lib/create-scanner.d.ts

@@ -1,11 +1,6 @@
 import type { PretenderScannerScanMethod } from './types.js';
 import type { PretenderScanOptions } from '@markuplint/ml-config';
 /**
- * Creates a pretender scanner by wrapping a scan method with path validation.
- * Ensures all provided file paths are absolute before delegating to the scan method.
- *
- * @template O - The scan options type, extending PretenderScanOptions
- * @param method - The underlying scan method to wrap with validation
- * @returns A wrapped scanner function that validates file paths and then invokes the scan method
+ * Wraps a scan method to enforce that all file paths are absolute before delegating.
  */
 export declare function createScanner<O extends PretenderScanOptions = PretenderScanOptions>(method: PretenderScannerScanMethod<O>): (files: readonly string[], options?: O) => Promise<import("@markuplint/ml-config").Pretender[]>;

package/lib/create-scanner.js

@@ -1,11 +1,6 @@
 import path from 'node:path';
 /**
- * Creates a pretender scanner by wrapping a scan method with path validation.
- * Ensures all provided file paths are absolute before delegating to the scan method.
- *
- * @template O - The scan options type, extending PretenderScanOptions
- * @param method - The underlying scan method to wrap with validation
- * @returns A wrapped scanner function that validates file paths and then invokes the scan method
+ * Wraps a scan method to enforce that all file paths are absolute before delegating.
  */
 export function createScanner(method) {
     return (files, options) => {

package/lib/dependency-mapper.d.ts

@@ -1,25 +1,52 @@
 import type { PretenderDirectorMap } from './pretender-director.js';
 import type { Identifier } from './types.js';
+import type { ImportBinding } from './import-resolver/types.js';
 import type { Pretender } from '@markuplint/ml-config';
+export interface DependencyMapperContext {
+    /** Import bindings found in each source file, keyed by the same relative path used as `sourceFile`. */
+    readonly importsByFile?: ReadonlyMap<string, readonly ImportBinding[]>;
+    /** Base directory that relative `sourceFile` paths (and resolved module paths) are relative to. */
+    readonly cwd?: string;
+    /**
+     * In-memory content overrides (keyed by normalized absolute path), consulted
+     * before falling back to disk when resolving a chased import's export table.
+     * Without this, a file with unsaved content (e.g. the lint target itself,
+     * when reached via a circular import) resolves against its stale on-disk
+     * version instead — which can silently pick a wrong same-named component
+     * (see the module JSDoc on `getExportTableForFile`).
+     */
+    readonly sources?: ReadonlyMap<string, string>;
+}
 /**
- * Resolves a map of component-to-identity mappings into a flat array of Pretender objects.
  * Follows chains where one component wraps another (e.g., MyButton -> Button -> button)
  * until a native element is reached or a cycle is detected.
  *
- * Uses import-path-based resolution when a name index is provided, falling back to
- * name-based lookup for backward compatibility.
+ * Resolution order at each hop:
+ * 1. A same-file local declaration (the file the reference itself lives in).
+ * 2. The file's recorded import bindings, resolved to the actual declaration file
+ *    via TypeScript module resolution and the target file's export table.
+ * 3. The legacy name-based index, for backward compatibility when no file context
+ *    is available (or the reference can't be resolved through it).
  *
- * @param map - The map of component keys to their [identifier, identity, filePath] tuples
- * @param nameIndex - Optional mapping from component names to map keys for resolving references
- * @returns A sorted array of fully resolved Pretender objects
+ * (1) and (2) are what let same-named components declared in different files
+ * (e.g., two unrelated `Item` components) resolve independently instead of the
+ * first-registered one silently winning for every reference — see issue #3951.
  */
-export declare function dependencyMapper(map: Readonly<PretenderDirectorMap>, nameIndex?: Readonly<Map<Identifier, string>>): Pretender[];
+export declare function dependencyMapper(map: Readonly<PretenderDirectorMap>, nameIndex?: Readonly<Map<Identifier, string>>, context?: DependencyMapperContext): Pretender[];
 /**
- * Creates a comparator function that sorts objects by a specified property.
+ * Clears the module-level export-table cache. A table built from a file's
+ * on-disk content never expires on its own, so a long-running host (a
+ * watch-mode lint run, an editor extension) that keeps resolving pretenders
+ * across file edits must call this whenever it re-resolves without cache (e.g.
+ * after a file change) — otherwise a renamed or restructured export keeps
+ * resolving to what it used to be for the rest of the process's lifetime.
  *
- * @template T - The object type
- * @template P - The property key type
- * @param propName - The property to sort by (case-insensitive for strings)
- * @returns A comparator function for use with `Array.prototype.sort()`
+ * Tables built from an in-memory `sources` override are the exception: their
+ * text is already in memory, so comparing it costs nothing and they rebuild as
+ * soon as it differs.
  */
-export declare function propSort<T, P extends keyof T>(propName: P): (a: T, b: T) => 1 | -1 | 0;
+export declare function clearExportTableCache(): void;
+/**
+ * Comparator that sorts by `propName`, case-insensitive for string values.
+ */
+export declare function propSort<T, P extends keyof T>(propName: P): (a: T, b: T) => 0 | 1 | -1;