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

package/CHANGELOG.md

@@ -3,6 +3,31 @@
 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.0](https://github.com/markuplint/markuplint/compare/v5.0.0-alpha.3...v5.0.0-rc.0) (2026-03-12)
+
+### Bug Fixes
+
+- **pretenders,ml-config:** add scan field to JSON schema and narrow getParser error handling ([e5fda17](https://github.com/markuplint/markuplint/commit/e5fda171f886c1b65d6f0e536c182cebb279ea07))
+- **pretenders:** add error handling to parseComponent and resolveBarrelExport ([c203c4b](https://github.com/markuplint/markuplint/commit/c203c4be341c89abfd0ba7991f09d8322d17728e))
+- **pretenders:** address QA review findings for import resolver phase 2 ([d8fd73f](https://github.com/markuplint/markuplint/commit/d8fd73f533e9b1febec05d93f144f2d5122cffc9))
+- **pretenders:** align import-resolver with [#3335](https://github.com/markuplint/markuplint/issues/3335) design spec ([448181a](https://github.com/markuplint/markuplint/commit/448181ac819e279c925e68c8f5577c7a7cd8ae61)), closes [#3339](https://github.com/markuplint/markuplint/issues/3339) [#3340](https://github.com/markuplint/markuplint/issues/3340)
+- **pretenders:** fix ensureInit TOCTOU race condition ([d9643d8](https://github.com/markuplint/markuplint/commit/d9643d8b679e888b143d9d47f243e35fbeeb6752))
+- **pretenders:** fix false positives in children detection and harden tests ([96f7af3](https://github.com/markuplint/markuplint/commit/96f7af3adf4d6a3b8c65a9e9464cf1bf34c48613))
+- **pretenders:** guard dynamic parser imports and improve test coverage ([9667aa1](https://github.com/markuplint/markuplint/commit/9667aa1278a3ac737fa8c6cfc2df5c1ffd9834c9))
+- **pretenders:** handle empty path edge case in deriveName ([0613743](https://github.com/markuplint/markuplint/commit/0613743c3a83c124b90a5e3f54c62e23b2a7b3bd))
+- **pretenders:** pass importPath in both scanners to prevent name collision ([8644b21](https://github.com/markuplint/markuplint/commit/8644b21b99f1a5a13ab58a4d6d042d2e1aa2a446))
+- **pretenders:** rename createIndentity to createIdentity ([e8f37e5](https://github.com/markuplint/markuplint/commit/e8f37e52f32107e7cc9a9415d2edb6b3bb442fe5))
+- **pretenders:** warn when parser package is not found ([03d567e](https://github.com/markuplint/markuplint/commit/03d567e937228ecfd5b3d9d7811814efd9dd2d09))
+- use visited set for cycle detection in dependencyMapper ([8821f4f](https://github.com/markuplint/markuplint/commit/8821f4fab9cb900582ae0f991e5efe7be413d584)), closes [#3336](https://github.com/markuplint/markuplint/issues/3336)
+
+### Features
+
+- **pretenders,ml-core:** implement slots detection in JSX scanner and ml-core consumption ([ad9c8e2](https://github.com/markuplint/markuplint/commit/ad9c8e20d233cddc752fce9ad83838857f81787f)), closes [#3341](https://github.com/markuplint/markuplint/issues/3341)
+- **pretenders:** add import-resolver module via es-module-lexer ([19c9f65](https://github.com/markuplint/markuplint/commit/19c9f65b3856613fa2d7bc59cc79d5b829894663)), closes [#3339](https://github.com/markuplint/markuplint/issues/3339)
+- **pretenders:** add MLAST-based templateScanner for Vue/Svelte/Astro ([b710639](https://github.com/markuplint/markuplint/commit/b71063937bd13523a7fef31da2c2f9095674a957)), closes [#3338](https://github.com/markuplint/markuplint/issues/3338)
+- **pretenders:** dispatch CLI input to both JSX and template scanners ([a5535af](https://github.com/markuplint/markuplint/commit/a5535af1e7e496f570cddce52148eb21f9611cfe))
+- **pretenders:** import resolver phase 2 — dynamic imports, Vue Options API, barrel files ([203d4fb](https://github.com/markuplint/markuplint/commit/203d4fb5bfdc0656f95a39af23b5e079ea324d39)), closes [#3359](https://github.com/markuplint/markuplint/issues/3359)
+
 # [5.0.0-alpha.3](https://github.com/markuplint/markuplint/compare/v5.0.0-alpha.2...v5.0.0-alpha.3) (2026-02-26)
 
 **Note:** Version bump only for package @markuplint/pretenders

package/README.md

@@ -1,18 +1,59 @@
 # @markuplint/pretenders
 
 [![npm version](https://badge.fury.io/js/%40markuplint%2Fpretenders.svg)](https://www.npmjs.com/package/@markuplint/pretenders)
-[![Build Status](https://travis-ci.org/markuplint/markuplint.svg?branch=main)](https://travis-ci.org/markuplint/markuplint)
-[![Coverage Status](https://coveralls.io/repos/github/markuplint/markuplint/badge.svg?branch=main)](https://coveralls.io/github/markuplint/markuplint?branch=main)
 
-This module features both an API and a CLI that generate **[Pretenders](https://markuplint.dev/docs/guides/besides-html#pretenders) data** from the loaded components
+This module features both an API and a CLI that generate **[Pretenders](https://markuplint.dev/docs/guides/besides-html#pretenders) data** from the loaded components.
 
-## Usage
+## Supported Frameworks
+
+| Framework   | Extensions                   | Scanner           | Approach                              |
+| ----------- | ---------------------------- | ----------------- | ------------------------------------- |
+| React / JSX | `.js`, `.jsx`, `.ts`, `.tsx` | `jsxScanner`      | TypeScript compiler API               |
+| Vue         | `.vue`                       | `templateScanner` | MLAST via `@markuplint/vue-parser`    |
+| Svelte      | `.svelte`                    | `templateScanner` | MLAST via `@markuplint/svelte-parser` |
+| Astro       | `.astro`                     | `templateScanner` | MLAST via `@markuplint/astro-parser`  |
+
+## CLI Usage
 
 ```sh
-$ npx @markuplint/pretenders "./src/**/*.jsx" --out "./pretenders.json"
+$ npx @markuplint/pretenders "./src/**/*.{jsx,tsx,vue,svelte,astro}" --out "./pretenders.json"
 ```
 
-The module analyzes components defined in files using a parser, currently supporting JSX (both `*.jsx` and `*.tsx` formats). It searches for functions or function objects that return elements and maps their function names or the variable names holding these function objects. For example, if a function object named `Foo` returns a `<div>`, the component `Foo` is considered as pretending to be a `div`. In the CLI, it exports the mapped data as a JSON file. By loading this JSON file into the Pretenders feature, the module evaluates the `Foo` component as equivalent to a `div`.
+The CLI accepts glob patterns covering any combination of the supported frameworks. It dispatches files to the appropriate scanner based on file extension, runs them in parallel, and writes the merged results as JSON.
+
+| Flag          | Description                                        |
+| ------------- | -------------------------------------------------- |
+| `-O`, `--out` | Output file path (required)                        |
+| `--ignore`    | Comma-separated list of component names to exclude |
+
+### Configuration-based Scanning
+
+Instead of the CLI, you can configure dynamic scanning directly in your markuplint config file. The `scan` field in `pretenders` accepts glob patterns and automatically dispatches to the appropriate scanner. The `files` field accepts either a single glob string or an array of globs:
+
+```jsonc
+// .markuplintrc
+{
+  "pretenders": {
+    "scan": [
+      {
+        // Single glob string
+        "files": "./src/components/**/*.{vue,tsx,svelte,astro}",
+        "ignoreComponentNames": ["InternalHelper"],
+      },
+      {
+        // Array of glob strings
+        "files": ["./src/pages/**/*.tsx", "./src/layouts/**/*.astro"],
+      },
+    ],
+  },
+}
+```
+
+## How It Works
+
+### JSX Scanner
+
+The JSX scanner analyzes components defined in files using the TypeScript compiler API. It searches for functions or function objects that return elements and maps their function names or the variable names holding these function objects. For example, if a function object named `Foo` returns a `<div>`, the component `Foo` is considered as pretending to be a `div`.
 
 ```jsx
 const Foo = () => <div />;
@@ -24,20 +65,12 @@ function Bar() {
 
 ```json
 [
-  {
-    "selector": "Foo",
-    "as": "div"
-  },
-  {
-    "selector": "Bar",
-    "as": "span"
-  }
+  { "selector": "Foo", "as": "div" },
+  { "selector": "Bar", "as": "span" }
 ]
 ```
 
-The module is **experimental**. It uses the TypeScript compiler to identify functions or function objects in JSX files where the return values are components or HTML elements. Currently, it only performs a simplistic mapping based on function and variable names without considering dependencies between files. **Consequently, it does not handle name duplications across files or variable scopes;** components with duplicate names overwrite existing data during processing.
-
-In addition to definitions based on function and variable names, the module also infers HTML elements from properties, as exemplified by `styled-components`, and infers dependencies from arguments.
+The JSX scanner also infers HTML elements from styled-components patterns and infers dependencies from wrapper function arguments:
 
 ```jsx
 const Foo = styled.div`
@@ -49,90 +82,202 @@ const Bar = styled(Foo)`
 `;
 ```
 
+```json
+[
+  { "selector": "Foo", "as": "div" },
+  { "selector": "Bar", "as": "div" }
+]
+```
+
+The JSX scanner detects **slots** (children). If a component accepts `children` props, the resulting pretender includes `slots: true` in its `as` field.
+
+### Template Scanner
+
+The template scanner uses markuplint's own framework parsers (Vue, Svelte, Astro) to extract the root element from component templates at depth=0. It also detects static attributes and slot/children usage.
+
+```vue
+<template>
+  <button type="submit"><slot /></button>
+</template>
+```
+
 ```json
 [
   {
-    "selector": "Foo",
-    "as": "div"
-  },
-  {
-    "selector": "Bar",
-    "as": "div"
+    "selector": "SubmitButton",
+    "as": {
+      "element": "button",
+      "attrs": [{ "name": "type", "value": "submit" }],
+      "slots": true
+    }
   }
 ]
 ```
 
+Slot detection covers:
+
+- `<slot>` elements in Vue, Svelte, and Astro
+- `{@render children()}` snippets in Svelte 5
+
+### 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.
+
+Supported script block types:
+
+- Vue `<script setup>` (all static imports are exposed as bindings)
+- Vue Options API `<script>` (fallback when no `<script setup>`; only imports registered in `components: { ... }` are returned)
+- Svelte `<script>` (prefers instance script over module script)
+- Astro frontmatter (`---...---`)
+- MDX top-level ESM
+
+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).
+
 ## API
 
+### `scan(files, options)`
+
+The unified entry point. Dispatches files to the appropriate scanner based on file extension, runs both scanners in parallel, and returns the merged, sorted results.
+
+```ts
+import { scan } from '@markuplint/pretenders';
+
+const pretenders = await scan([
+  '/absolute/path/to/Button.tsx',
+  '/absolute/path/to/Card.vue',
+  '/absolute/path/to/Alert.svelte',
+]);
+```
+
+#### Parameters
+
+| Parameter                      | Type                | Description                             |
+| ------------------------------ | ------------------- | --------------------------------------- |
+| `files`                        | `readonly string[]` | Absolute file paths to scan             |
+| `options.ignoreComponentNames` | `readonly string[]` | Component names to exclude from results |
+
 ### `jsxScanner(files, options)`
 
+Scans JSX/TSX files using the TypeScript compiler API.
+
 ```ts
 import { jsxScanner } from '@markuplint/pretenders';
 
-const pretenders = jsxScanner(['./src/**/*.jsx'], {
+const pretenders = await jsxScanner(['/absolute/path/to/Component.jsx'], {
   cwd: process.cwd(),
   asFragment: [/(?:^|\.)provider$/i],
   ignoreComponentNames: [],
-  taggedStylingComponent: [
-    // PropertyAccessExpression: styled.button`css-prop: value;`
-    /^styled\.(?<tagName>[a-z][\da-z]*)$/i,
-    // CallExpression: styled(Button)`css-prop: value;`
-    /^styled\s*\(\s*(?<tagName>[a-z][\da-z]*)\s*\)$/i,
-  ],
+  taggedStylingComponent: [/^styled\.(?<tagName>[a-z][\da-z]*)$/i, /^styled\s*\(\s*(?<tagName>[a-z][\da-z]*)\s*\)$/i],
   extendingWrapper: [],
 });
 ```
 
-#### `files`
+#### Parameters
 
-Type: `string[]`
+| Parameter                        | Type                                                             | Description                                                |
+| -------------------------------- | ---------------------------------------------------------------- | ---------------------------------------------------------- |
+| `files`                          | `readonly string[]`                                              | Absolute file paths to scan                                |
+| `options.cwd`                    | `string`                                                         | Current working directory                                  |
+| `options.asFragment`             | `readonly (RegExp \| string)[]`                                  | Patterns for components treated as transparent fragments   |
+| `options.ignoreComponentNames`   | `readonly string[]`                                              | Component names to ignore                                  |
+| `options.taggedStylingComponent` | `readonly (RegExp \| string)[]`                                  | Patterns for styled-components tagged template expressions |
+| `options.extendingWrapper`       | `readonly (string \| RegExp \| ExtendingWrapperCallerOptions)[]` | Patterns for HOC/wrapper components                        |
 
-An array of file paths to scan.
+### `templateScanner(files, options)`
 
-##### `options.cwd`
+Scans Vue, Svelte, and Astro component files using markuplint's own parsers (MLAST-based).
 
-Type: `string`
+```ts
+import { templateScanner } from '@markuplint/pretenders';
 
-The current working directory.
+const pretenders = await templateScanner(
+  ['/absolute/path/to/Button.vue', '/absolute/path/to/Alert.svelte', '/absolute/path/to/Card.astro'],
+  {
+    ignoreComponentNames: ['InternalHelper'],
+  },
+);
+```
+
+#### Parameters
 
-##### `options.asFragment`
+| Parameter                      | Type                | Description                                    |
+| ------------------------------ | ------------------- | ---------------------------------------------- |
+| `files`                        | `readonly string[]` | Absolute file paths to scan                    |
+| `options.cwd`                  | `string`            | Current working directory (for relative paths) |
+| `options.ignoreComponentNames` | `readonly string[]` | Component names to exclude from results        |
 
-Type: `RegExp[]`
+### `analyzeImports(filePath, source)`
 
-A list of regular expressions to match components that should be treated as fragments.
+Extracts import bindings from a component file's script block. Detects the framework from the file extension and extracts the appropriate source block automatically.
 
-##### `options.ignoreComponentNames`
+Returns `null` if the file extension is not a supported framework (`.vue`, `.svelte`, `.astro`, `.mdx`).
 
-Type: `string[]`
+```ts
+import { analyzeImports } from '@markuplint/pretenders';
+
+const result = await analyzeImports('App.vue', source);
+// result.bindings: [{ localName: 'MyButton', importedName: 'default', source: './components/MyButton.vue', type: 'default' }, ...]
+```
 
-A list of component names to ignore.
+#### Parameters
 
-##### `options.taggedStylingComponent`
+| Parameter  | Type     | Description                                           |
+| ---------- | -------- | ----------------------------------------------------- |
+| `filePath` | `string` | File path (used for framework detection by extension) |
+| `source`   | `string` | Full source text of the component file                |
 
-Type: `RegExp[]`
+#### Returns
 
-A list of regular expressions to match components that are styled.
+`Promise<ImportAnalysisResult | null>` — The analysis result with all import bindings, or `null` if the framework is not supported.
 
-##### `options.extendingWrapper`
+### `resolveComponentImport(componentName, bindings)`
 
-Type: `RegExp[]` | `{ identifier: RegExp, numberOfArgument: number }[]`
+Resolves a component name used in a template to its import binding. Handles Vue's kebab-case to PascalCase normalization (e.g., `<my-button>` resolves to `MyButton`).
 
-```js
-jsxScanner(['./src/**/*.jsx'], {
-  extendingWrapper: [
-    {
-      identifier: /^namespace\.primary$/i,
-      numberOfArgument: 1,
-    },
-  ],
-});
+```ts
+import { resolveComponentImport } from '@markuplint/pretenders';
+
+const binding = resolveComponentImport('my-button', bindings);
+// binding: { localName: 'MyButton', importedName: 'default', source: './components/MyButton.vue', type: 'default' }
 ```
 
-```jsx
-const Foo = <div />;
-const Bar = namespace.primary(true, Foo);
+#### Parameters
+
+| Parameter       | Type                       | Description                            |
+| --------------- | -------------------------- | -------------------------------------- |
+| `componentName` | `string`                   | Component name as used in the template |
+| `bindings`      | `readonly ImportBinding[]` | Import bindings from `analyzeImports`  |
+
+#### Returns
+
+`ImportBinding | undefined` — The matching binding, or `undefined` if no match.
+
+### `resolveBarrelExport(specifier, importedName, importerPath)`
+
+Resolves a barrel file (`index.ts`/`index.js`) re-export to the original source module path. Only handles relative specifiers and single-level barrel resolution.
+
+```ts
+import { analyzeImports, resolveComponentImport, resolveBarrelExport } from '@markuplint/pretenders';
+
+const result = await analyzeImports('App.vue', source);
+const binding = resolveComponentImport('Button', result.bindings);
+
+if (binding) {
+  const originalSource = resolveBarrelExport(binding.source, binding.importedName, '/absolute/path/to/App.vue');
+  // originalSource: './Button.vue' (resolved from './components' barrel)
+}
 ```
 
-A list of regular expressions to match components that are extended.
-`identifier` is a regular expression to match the component name.
-`numberOfArgument` is the number of arguments to pass to the component.
+#### Parameters
+
+| Parameter      | Type     | Description                                     |
+| -------------- | -------- | ----------------------------------------------- |
+| `specifier`    | `string` | The import specifier (e.g., `'./components'`)   |
+| `importedName` | `string` | The name being imported (e.g., `'Button'`)      |
+| `importerPath` | `string` | Absolute path of the file containing the import |
+
+#### Returns
+
+`string | null` — The relative source path from the barrel file, or `null` if not a barrel or name not found.

package/lib/cli.js

@@ -11,8 +11,8 @@
 import path from 'node:path';
 import meow from 'meow';
 import { getFileList } from './input.js';
-import { jsxScanner } from './jsx/index.js';
 import { out } from './out.js';
+import { scan } from './scan.js';
 const commands = meow({
     importMeta: import.meta,
     flags: {
@@ -31,8 +31,7 @@ if (commands.input.length === 0) {
 }
 async function main() {
     const files = await getFileList(commands.input);
-    const jsxFiles = files.filter(filePath => /\.[jt]sx?$/.test(filePath));
-    const pretenders = await jsxScanner(jsxFiles, {
+    const pretenders = await scan(files, {
         ignoreComponentNames: commands.flags.ignore?.split(',').map(s => s.trim()),
     });
     const outFilePath = path.resolve(process.cwd(), commands.flags.out);

package/lib/dependency-mapper.d.ts

@@ -1,42 +1,25 @@
-import type { Identifier, Identity } from './types.js';
+import type { PretenderDirectorMap } from './pretender-director.js';
+import type { Identifier } from './types.js';
 import type { Pretender } from '@markuplint/ml-config';
-/**
- * Internal map structure storing component identifiers to their identity and source location.
- */
-type PretenderDirectorMap = Map<Identifier, [identity: Identity, filePath?: string]>;
-/**
- * Collects and manages pretender mappings discovered during source file scanning.
- * Acts as a registry where component-to-element relationships are added during
- * traversal, then resolved into a flat list of pretenders with dependency linking.
- */
-export declare class PretenderDirector {
-    #private;
-    /**
-     * Registers a component as a pretender mapping. If the identifier is already
-     * registered, the call is silently ignored (first definition wins).
-     *
-     * @param identifier - The component selector (e.g., component name)
-     * @param identity - The native HTML element the component renders as
-     * @param filePath - The relative file path where the component is defined
-     * @param line - The line number of the component declaration
-     * @param col - The column number of the component declaration
-     */
-    add(identifier: Identifier, identity: Identity, filePath: string, line: number, col: number): void;
-    /**
-     * Resolves all registered mappings into a sorted array of Pretender objects.
-     * Follows component-to-component chains to determine the final native element identity.
-     *
-     * @returns A sorted array of resolved Pretender objects
-     */
-    getPretenders(): Pretender[];
-}
 /**
  * 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 recursive loop is detected.
+ * until a native element is reached or a cycle is detected.
  *
- * @param map - The map of component identifiers to their identity and file path
+ * Uses import-path-based resolution when a name index is provided, falling back to
+ * name-based lookup for backward compatibility.
+ *
+ * @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
  */
-export declare function dependencyMapper(map: Readonly<PretenderDirectorMap>): Pretender[];
-export {};
+export declare function dependencyMapper(map: Readonly<PretenderDirectorMap>, nameIndex?: Readonly<Map<Identifier, string>>): Pretender[];
+/**
+ * Creates a comparator function that sorts objects by a specified property.
+ *
+ * @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()`
+ */
+export declare function propSort<T, P extends keyof T>(propName: P): (a: T, b: T) => 1 | -1 | 0;

package/lib/dependency-mapper.js

@@ -1,89 +1,80 @@
-/**
- * Collects and manages pretender mappings discovered during source file scanning.
- * Acts as a registry where component-to-element relationships are added during
- * traversal, then resolved into a flat list of pretenders with dependency linking.
- */
-export class PretenderDirector {
-    #map = new Map();
-    /**
-     * Registers a component as a pretender mapping. If the identifier is already
-     * registered, the call is silently ignored (first definition wins).
-     *
-     * @param identifier - The component selector (e.g., component name)
-     * @param identity - The native HTML element the component renders as
-     * @param filePath - The relative file path where the component is defined
-     * @param line - The line number of the component declaration
-     * @param col - The column number of the component declaration
-     */
-    add(identifier, identity, filePath, line, col) {
-        if (this.#map.has(identifier)) {
-            return;
-        }
-        this.#map.set(identifier, [identity, `${filePath}:${line}:${col}`]);
-    }
-    /**
-     * Resolves all registered mappings into a sorted array of Pretender objects.
-     * Follows component-to-component chains to determine the final native element identity.
-     *
-     * @returns A sorted array of resolved Pretender objects
-     */
-    getPretenders() {
-        return dependencyMapper(this.#map);
-    }
-}
 /**
  * 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 recursive loop is detected.
+ * until a native element is reached or a cycle is detected.
  *
- * @param map - The map of component identifiers to their identity and file path
+ * Uses import-path-based resolution when a name index is provided, falling back to
+ * name-based lookup for backward compatibility.
+ *
+ * @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
  */
-export function dependencyMapper(map) {
+export function dependencyMapper(map, nameIndex) {
+    const resolvedNameIndex = nameIndex ?? buildNameIndex(map);
     const linkedPretenders = [];
-    const collection = [...map.entries()];
-    for (const [identifier, [_identity, _filePath]] of collection) {
+    for (const [key, [identifier, _identity, _filePath]] of map) {
         let identity = _identity;
         let filePath = _filePath;
         let elName = getElName(identity);
         const via = [];
+        const visited = new Set([key]);
         while (true) {
-            const mappedPretender = map.get(elName);
+            const lookupKey = resolvedNameIndex.get(elName) ?? elName;
+            const mappedPretender = map.get(lookupKey);
             if (!mappedPretender) {
                 break;
             }
-            identity = mappedPretender[0];
-            filePath = mappedPretender[1];
-            if (elName === identifier) {
+            identity = mappedPretender[1];
+            filePath = mappedPretender[2];
+            if (visited.has(lookupKey)) {
                 via.push('...[Recursive]');
                 break;
             }
+            visited.add(lookupKey);
             via.push(elName);
             elName = getElName(identity);
         }
         const pretender = {
             selector: identifier,
             as: identity,
+            ...(filePath ? { filePath } : {}),
         };
-        if (filePath) {
-            // @ts-ignore initialize readonly property
-            pretender.filePath = filePath;
-        }
         if (via.length > 0) {
-            // @ts-ignore
-            pretender._via = via;
+            Object.assign(pretender, { _via: via });
         }
         linkedPretenders.push(pretender);
     }
     return linkedPretenders.toSorted(propSort('selector'));
 }
+/**
+ * Builds a name-to-key index from the map for backward-compatible name-based lookup.
+ * First definition wins when multiple entries share the same identifier.
+ */
+function buildNameIndex(map) {
+    const index = new Map();
+    for (const [key, [identifier]] of map) {
+        if (!index.has(identifier)) {
+            index.set(identifier, key);
+        }
+    }
+    return index;
+}
 function getElName(identity) {
     if (typeof identity === 'string') {
         return identity;
     }
     return identity.element;
 }
-function propSort(propName) {
+/**
+ * Creates a comparator function that sorts objects by a specified property.
+ *
+ * @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()`
+ */
+export function propSort(propName) {
     return (a, b) => {
         const nameA = toLowerCase(a[propName]);
         const nameB = toLowerCase(b[propName]);
@@ -98,7 +89,6 @@ function propSort(propName) {
 }
 function toLowerCase(value) {
     if (typeof value === 'string') {
-        // @ts-ignore
         return value.toLowerCase();
     }
     return value;