@dcoder-x/plugin-shared 0.1.13 → 0.1.15

package/dist/extractors/ComponentExtractor.js

@@ -12,6 +12,26 @@ const InteractionGraphExtractor_1 = require("./InteractionGraphExtractor");
 const ComponentContextResolver_1 = require("./ComponentContextResolver");
 const HtmlTagGuards_1 = require("../injection/HtmlTagGuards");
 const IdStrategy_1 = require("../injection/IdStrategy");
+/**
+ * A route is a usable module-graph entry point only when its filePath
+ * points to an actual page component, not a layout/guard/wrapper/router file.
+ */
+function isPageRoute(route) {
+    if (route.isLayoutRoute)
+        return false;
+    const p = route.filePath.replace(/\\/g, '/').toLowerCase();
+    const base = path_1.default.basename(p).replace(/\.(tsx?|jsx?)$/, '');
+    if (p.includes('/pages/') || p.includes('/views/') || p.includes('/screens/'))
+        return true;
+    // Directory-based structural patterns
+    if (/\/(contexts?|providers?|guards?|layouts?|wrappers?|hoc|utils?|helpers?)\//.test(p))
+        return false;
+    // Basename-based structural patterns: wrapper, router config, and provider files
+    if (/(provider|context|guard|layout|redirect|catchall|catch-all)/.test(base) ||
+        /^(router|routes|routerconfig|approuter|routesconfig|routingconfig|routeconfig|approviders|appwrapper)$/i.test(base))
+        return false;
+    return true;
+}
 class ComponentExtractor {
     constructor(source, routes) {
         this.source = source;
@@ -19,25 +39,28 @@ class ComponentExtractor {
     }
     async extract() {
         const elements = [];
-        // Build a direct filePath → route.path index so that files which are
-        // themselves route entries get their own route, not whichever layout or
-        // parent route happened to import them first.
+        // Build a filePath → route.path index for ALL routes (including layout routes)
+        // so that any file encountered during a walk can be assigned its own route
+        // when it is directly registered as a route entry.
         const fileRouteIndex = new Map();
         for (const route of this.routes) {
             fileRouteIndex.set(route.filePath, route.path);
             fileRouteIndex.set(route.filePath.replace(/\\/g, '/'), route.path);
         }
-        // Stop the module walk at other route entry files — they will be
-        // processed in their own iteration with the correct route assigned.
-        const allRouteFiles = new Set();
-        for (const route of this.routes) {
-            allRouteFiles.add(route.filePath);
-            allRouteFiles.add(route.filePath.replace(/\\/g, '/'));
+        // Only use page-scoring routes as module-graph entry points.
+        // Layout/guard/wrapper routes are structural — their file imports the entire
+        // app and would contaminate every selector with the layout's route path.
+        const pageRoutes = this.routes.filter(isPageRoute);
+        // The stopAt boundary for each walk = all OTHER page route entry files.
+        // This prevents a walk from crossing into a sibling route's components.
+        const allPageRouteFiles = new Set();
+        for (const route of pageRoutes) {
+            allPageRouteFiles.add(route.filePath);
+            allPageRouteFiles.add(route.filePath.replace(/\\/g, '/'));
         }
-        const seen = new Set(); // deduplicate across routes
-        for (const route of this.routes) {
-            // The stop boundary excludes the current entry file itself (we need to visit it).
-            const stopAt = new Set([...allRouteFiles].filter((f) => f !== route.filePath && f !== route.filePath.replace(/\\/g, '/')));
+        const seen = new Set(); // deduplicate files across all route walks
+        for (const route of pageRoutes) {
+            const stopAt = new Set([...allPageRouteFiles].filter((f) => f !== route.filePath && f !== route.filePath.replace(/\\/g, '/')));
             const moduleFiles = this.getModuleFilesForRoute(route.filePath, stopAt);
             for (const filePath of moduleFiles) {
                 if (seen.has(filePath))
@@ -46,8 +69,8 @@ class ComponentExtractor {
                 const source = this.readSource(filePath);
                 if (!source)
                     continue;
-                // Prefer the route this file is directly registered as; fall back to
-                // the route whose module graph we're walking (the layout/parent route).
+                // If this file is itself a registered route entry, use that route's
+                // path. Otherwise inherit from the walk's originating page route.
                 const assignedRoute = fileRouteIndex.get(filePath) ??
                     fileRouteIndex.get(filePath.replace(/\\/g, '/')) ??
                     route.path;
@@ -69,14 +92,15 @@ class ComponentExtractor {
             fileRouteIndex.set(route.filePath, route.path);
             fileRouteIndex.set(route.filePath.replace(/\\/g, '/'), route.path);
         }
-        const allRouteFiles = new Set();
-        for (const route of this.routes) {
-            allRouteFiles.add(route.filePath);
-            allRouteFiles.add(route.filePath.replace(/\\/g, '/'));
+        const pageRoutes = this.routes.filter(isPageRoute);
+        const allPageRouteFiles = new Set();
+        for (const route of pageRoutes) {
+            allPageRouteFiles.add(route.filePath);
+            allPageRouteFiles.add(route.filePath.replace(/\\/g, '/'));
         }
         const seen = new Set();
-        for (const route of this.routes) {
-            const stopAt = new Set([...allRouteFiles].filter((f) => f !== route.filePath && f !== route.filePath.replace(/\\/g, '/')));
+        for (const route of pageRoutes) {
+            const stopAt = new Set([...allPageRouteFiles].filter((f) => f !== route.filePath && f !== route.filePath.replace(/\\/g, '/')));
             const moduleFiles = this.getModuleFilesForRoute(route.filePath, stopAt);
             for (const filePath of moduleFiles) {
                 if (seen.has(filePath))
@@ -393,10 +417,21 @@ function extractStaticProps(attributes) {
             continue;
         if (attr.value?.type === 'StringLiteral') {
             props[key] = attr.value.value;
+            continue;
         }
-        if (attr.value?.type === 'JSXExpressionContainer' &&
-            attr.value.expression?.type === 'StringLiteral') {
-            props[key] = attr.value.expression.value;
+        if (attr.value?.type === 'JSXExpressionContainer') {
+            const expr = attr.value.expression;
+            if (expr?.type === 'StringLiteral') {
+                props[key] = expr.value;
+            }
+            else if (expr?.type === 'TemplateLiteral' &&
+                expr.quasis?.length === 1 &&
+                expr.expressions?.length === 0) {
+                // Pure template literal with no interpolations: `to="/some/path"`
+                const raw = expr.quasis[0].value.cooked ?? expr.quasis[0].value.raw;
+                if (raw)
+                    props[key] = raw;
+            }
         }
     }
     return props;

package/dist/extractors/FlowInferrer.d.ts

@@ -14,6 +14,12 @@ export declare class FlowInferrer {
      */
     private isCoherentChain;
     private detectInteractionFlows;
+    /**
+     * Deduplicate interaction flows by (page, trigger event, effect target).
+     * Shared components used on multiple routes produce one flow per component
+     * interaction. After dedup, each distinct interaction appears once.
+     */
+    private deduplicateInteractionFlows;
     private buildChain;
     private generateIntentPatterns;
     /**

package/dist/extractors/FlowInferrer.js

@@ -45,10 +45,9 @@ class FlowInferrer {
     infer() {
         const edges = this.buildEdgeGraph();
         const routeFlows = this.detectLinearFlows(edges);
-        const interactionFlows = this.detectInteractionFlows();
+        const interactionFlows = this.deduplicateInteractionFlows(this.detectInteractionFlows());
         const combined = [...routeFlows, ...interactionFlows];
-        // Fix 4: remove patterns that appear in too many flows — they are structural
-        // navigation chrome (sidebars, footers) rather than user intent signals
+        // Remove patterns that appear in too many flows — structural nav chrome
         return this.deduplicateCrossFlowNoise(combined);
     }
     // ---------------------------------------------------------------------------
@@ -56,13 +55,21 @@ class FlowInferrer {
     // ---------------------------------------------------------------------------
     buildEdgeGraph() {
         const edges = [];
+        // Index routes both with and without leading slash to handle mixed conventions
         const routePaths = new Set(this.routes.map((r) => r.path));
+        const normalizeHref = (href) => href.replace(/^\//, '');
         for (const el of this.elements) {
             const isNav = el.tag === 'a' || el.isNavigationLink === true;
-            const href = el.staticProps['href'] || el.staticProps['to'];
-            if (!isNav || !href)
+            const rawHref = el.staticProps['href'] || el.staticProps['to'];
+            if (!isNav || !rawHref)
                 continue;
-            if (!routePaths.has(href))
+            // Match against both the raw href and the normalized (no leading slash) form
+            const href = routePaths.has(rawHref)
+                ? rawHref
+                : routePaths.has(normalizeHref(rawHref))
+                    ? normalizeHref(rawHref)
+                    : null;
+            if (!href)
                 continue;
             const triggerText = el.staticProps['aria-label'] ||
                 el.label ||
@@ -162,6 +169,26 @@ class FlowInferrer {
         return flows;
     }
     // ---------------------------------------------------------------------------
+    // Interaction flow deduplication
+    // ---------------------------------------------------------------------------
+    /**
+     * Deduplicate interaction flows by (page, trigger event, effect target).
+     * Shared components used on multiple routes produce one flow per component
+     * interaction. After dedup, each distinct interaction appears once.
+     */
+    deduplicateInteractionFlows(flows) {
+        const seen = new Set();
+        return flows.filter((f) => {
+            const trigger = f.edges[0]?.trigger ?? '';
+            const step = f.steps[0] ?? '';
+            const sig = `${f.page}::${trigger}::${step}`;
+            if (seen.has(sig))
+                return false;
+            seen.add(sig);
+            return true;
+        });
+    }
+    // ---------------------------------------------------------------------------
     // Chain builder
     // ---------------------------------------------------------------------------
     buildChain(start, adjacency, seen) {

package/dist/extractors/RouteExtractor.d.ts

@@ -7,9 +7,33 @@ export declare class RouteExtractor {
     private walkPagesDir;
     private walkTanStackDir;
     private extractReactRouterRoutes;
-    private buildImportMap;
+    /**
+     * Top-level AST scan. Finds:
+     * 1. JSX <Route> elements at any depth — delegates to walkJsxRouteNode which
+     *    descends the JSX tree hierarchically and accumulates path prefixes.
+     * 2. createBrowserRouter / createHashRouter call arguments — delegates to
+     *    walkObjectRouteConfig which handles the object-literal route config style.
+     */
+    private extractFromAst;
+    /**
+     * Recursively walk a JSX <Route> element and its JSX children.
+     * pathPrefix is the accumulated path from ancestor <Route path> segments.
+     */
+    private walkJsxRouteNode;
+    /**
+     * Walk an object-literal route config node as produced by createBrowserRouter.
+     * Handles: { path, element, Component, children: [...] }
+     */
+    private walkObjectRouteConfig;
     private resolveRouteComponentFile;
+    /**
+     * Given a JSX expression node (either a JSXElement or an Identifier) that
+     * represents the value passed to an `element` or `Component` prop, resolve
+     * it to the best-scoring file path via the import map.
+     */
+    private resolveElementNodeToFile;
     private collectJSXComponentNames;
+    private buildImportMap;
     private resolveImportToFile;
     private findFilesContaining;
     private extractParams;

package/dist/extractors/RouteExtractor.js

@@ -12,6 +12,32 @@ const traverse_1 = __importDefault(require("@babel/traverse"));
 // The CJS-in-ESM import wraps exports in a namespace object, so `.default`
 // may be the module object rather than the function. This guard handles both.
 const traverse = typeof traverse_1.default === 'function' ? traverse_1.default : traverse_1.default.default;
+// ---------------------------------------------------------------------------
+// Scoring helpers — shared between JSX and object-config parsers
+// ---------------------------------------------------------------------------
+/**
+ * Score a resolved file path: higher = more likely to be an actual page component.
+ * 3 = pages/views/screens directory → definitely a page
+ * 1 = unknown / ambiguous
+ * 0 = structural file (provider, guard, layout, context, router config, …)
+ */
+function scoreFilePath(filePath) {
+    const p = filePath.replace(/\\/g, '/').toLowerCase();
+    const base = path_1.default.basename(p).replace(/\.(tsx?|jsx?)$/, '');
+    if (p.includes('/pages/') || p.includes('/views/') || p.includes('/screens/'))
+        return 3;
+    // Directory-based structural patterns
+    if (/\/(contexts?|providers?|guards?|layouts?|wrappers?|hoc|utils?|helpers?)\//.test(p))
+        return 0;
+    // Basename-based structural patterns: wrapper/config/router files
+    if (/(provider|context|guard|layout|redirect|catchall|catch-all)/.test(base) ||
+        /^(router|routes|routerconfig|approuter|routesconfig|routingconfig|routeconfig|approviders|appwrapper)$/i.test(base))
+        return 0;
+    return 1;
+}
+// ---------------------------------------------------------------------------
+// RouteExtractor
+// ---------------------------------------------------------------------------
 class RouteExtractor {
     constructor(dir) {
         this.dir = dir;
@@ -37,6 +63,9 @@ class RouteExtractor {
         }
         return routes;
     }
+    // ---------------------------------------------------------------------------
+    // App-dir / pages-dir / TanStack (unchanged)
+    // ---------------------------------------------------------------------------
     walkAppDir(dir, routePrefix) {
         const results = [];
         const entries = fs_1.default.readdirSync(dir, { withFileTypes: true });
@@ -75,10 +104,6 @@ class RouteExtractor {
                     .relative(path_1.default.join(this.dir, 'pages'), fullPath)
                     .replace(/\.(tsx?|jsx?)$/, '')
                     .replace(/\\/g, '/');
-                // index.tsx maps to the parent segment path.
-                // examples:
-                // pages/index.tsx -> /
-                // pages/blog/index.tsx -> /blog
                 const routePath = relativePath === 'index'
                     ? '/'
                     : `/${relativePath.replace(/\/index$/, '')}`;
@@ -117,6 +142,9 @@ class RouteExtractor {
         }
         return results;
     }
+    // ---------------------------------------------------------------------------
+    // React Router extraction — hierarchical walk
+    // ---------------------------------------------------------------------------
     async extractReactRouterRoutes(srcDir) {
         if (!fs_1.default.existsSync(srcDir))
             return [];
@@ -132,30 +160,12 @@ class RouteExtractor {
                 continue;
             }
             const importMap = this.buildImportMap(ast, filePath);
-            traverse(ast, {
-                JSXOpeningElement: (nodePath) => {
-                    const name = nodePath.node.name?.name;
-                    if (name !== 'Route')
-                        return;
-                    const pathAttr = nodePath.node.attributes.find((a) => a.name?.name === 'path');
-                    const routePath = pathAttr?.value?.value;
-                    if (!routePath)
-                        return;
-                    const resolvedFilePath = this.resolveRouteComponentFile(nodePath, importMap) ?? filePath;
-                    results.push({
-                        path: routePath,
-                        filePath: resolvedFilePath,
-                        isDynamic: routePath.includes(':'),
-                        params: (routePath.match(/:(\w+)/g) || []).map((p) => p.slice(1)),
-                        layout: null,
-                        routerType: 'react-router',
-                        semantic: this.deriveSemanticMeaning(routePath),
-                    });
-                },
-            });
+            // Walk the entire AST looking for JSX Route trees and
+            // createBrowserRouter([…]) / createHashRouter([…]) call expressions.
+            this.extractFromAst(ast, filePath, importMap, results);
         }
-        // Deduplicate: same path + filePath can appear if multiple router files
-        // re-export or nest the same routes (e.g. AppProviders wrapping routerConfig).
+        // Deduplicate: same (path + filePath) pair can appear when multiple router
+        // files re-export or re-nest the same routes.
         const seen = new Set();
         return results.filter((r) => {
             const key = `${r.path}::${r.filePath}`;
@@ -165,61 +175,201 @@ class RouteExtractor {
             return true;
         });
     }
-    buildImportMap(ast, fromFile) {
-        const map = new Map();
-        for (const node of ast.program.body) {
-            if (node.type !== 'ImportDeclaration')
-                continue;
-            const importSource = node.source?.value;
-            if (!importSource)
-                continue;
-            const resolved = this.resolveImportToFile(importSource, fromFile);
-            if (!resolved)
-                continue;
-            for (const specifier of node.specifiers ?? []) {
-                if (specifier.type === 'ImportDefaultSpecifier' ||
-                    specifier.type === 'ImportSpecifier') {
-                    const localName = specifier.local?.name;
-                    if (localName)
-                        map.set(localName, resolved);
+    /**
+     * Top-level AST scan. Finds:
+     * 1. JSX <Route> elements at any depth — delegates to walkJsxRouteNode which
+     *    descends the JSX tree hierarchically and accumulates path prefixes.
+     * 2. createBrowserRouter / createHashRouter call arguments — delegates to
+     *    walkObjectRouteConfig which handles the object-literal route config style.
+     */
+    extractFromAst(ast, filePath, importMap, results) {
+        // Track which JSX Route nodes we have already processed as children of a
+        // parent Route so we don't double-emit them from the flat visitor pass.
+        const processedNodes = new WeakSet();
+        traverse(ast, {
+            // Object-config style: createBrowserRouter([{ path, element, children }])
+            CallExpression: (nodePath) => {
+                const calleeName = nodePath.node.callee?.name ||
+                    nodePath.node.callee?.property?.name;
+                if (calleeName !== 'createBrowserRouter' &&
+                    calleeName !== 'createHashRouter' &&
+                    calleeName !== 'createMemoryRouter')
+                    return;
+                const firstArg = nodePath.node.arguments?.[0];
+                if (!firstArg)
+                    return;
+                // The argument is an ArrayExpression of route config objects.
+                const routeObjects = firstArg.type === 'ArrayExpression' ? firstArg.elements : [];
+                for (const el of routeObjects) {
+                    if (el)
+                        this.walkObjectRouteConfig(el, '', filePath, importMap, results);
                 }
+            },
+            // JSX style: <Routes><Route path="…" element={…}>…</Route></Routes>
+            JSXOpeningElement: (nodePath) => {
+                const name = nodePath.node.name?.name;
+                if (name !== 'Route')
+                    return;
+                // Only process top-level Route elements here. If this node is already
+                // reachable from a parent Route tree we walked, skip it.
+                const jsxElement = nodePath.parentPath?.node;
+                if (!jsxElement || processedNodes.has(jsxElement))
+                    return;
+                // Check whether the immediate JSX parent is also a Route — if so,
+                // this node will be handled by the parent's recursive descent.
+                const parentJsx = nodePath.parentPath?.parentPath?.node;
+                const grandparentOpening = parentJsx?.openingElement?.name?.name;
+                if (grandparentOpening === 'Route')
+                    return;
+                this.walkJsxRouteNode(jsxElement, '', filePath, importMap, results, processedNodes);
+            },
+        });
+    }
+    /**
+     * Recursively walk a JSX <Route> element and its JSX children.
+     * pathPrefix is the accumulated path from ancestor <Route path> segments.
+     */
+    walkJsxRouteNode(jsxElement, pathPrefix, filePath, importMap, results, processedNodes) {
+        if (!jsxElement)
+            return;
+        processedNodes.add(jsxElement);
+        const openingEl = jsxElement.openingElement;
+        if (!openingEl || openingEl.name?.name !== 'Route')
+            return;
+        const pathAttr = openingEl.attributes.find((a) => a.name?.name === 'path');
+        const routeSegment = pathAttr?.value?.value ?? '';
+        // Build the full path for this route node.
+        const fullPath = routeSegment
+            ? pathPrefix
+                ? `${pathPrefix}/${routeSegment}`.replace(/\/+/g, '/')
+                : routeSegment
+            : pathPrefix;
+        // Collect all child <Route> JSX elements (direct JSX children only).
+        const childRouteElements = (jsxElement.children ?? []).filter((child) => child.type === 'JSXElement' &&
+            child.openingElement?.name?.name === 'Route');
+        const hasChildRoutes = childRouteElements.length > 0;
+        // Resolve the component file for this route's element prop.
+        const resolvedFile = this.resolveRouteComponentFile(openingEl, importMap);
+        const effectiveFile = resolvedFile ?? filePath;
+        const fileScore = scoreFilePath(effectiveFile);
+        // A route is a layout container when:
+        // - it has child routes (it is a branch, not a leaf), AND
+        // - its resolved file is a structural wrapper (score 0) or it fell back to the router file
+        const isLayoutRoute = hasChildRoutes && (fileScore === 0 || resolvedFile === null);
+        // Only emit routes that have an explicit path segment — index routes with
+        // no path are structural placeholders.
+        if (routeSegment || (!hasChildRoutes && fullPath)) {
+            results.push({
+                path: fullPath,
+                filePath: effectiveFile,
+                isDynamic: fullPath.includes(':'),
+                params: (fullPath.match(/:(\w+)/g) ?? []).map((p) => p.slice(1)),
+                layout: null,
+                routerType: 'react-router',
+                semantic: this.deriveSemanticMeaning(fullPath),
+                isLayoutRoute,
+            });
+        }
+        // Recurse into child <Route> elements, passing the accumulated path.
+        for (const child of childRouteElements) {
+            this.walkJsxRouteNode(child, fullPath, filePath, importMap, results, processedNodes);
+        }
+    }
+    /**
+     * Walk an object-literal route config node as produced by createBrowserRouter.
+     * Handles: { path, element, Component, children: [...] }
+     */
+    walkObjectRouteConfig(node, pathPrefix, filePath, importMap, results) {
+        if (!node || node.type !== 'ObjectExpression')
+            return;
+        let routeSegment = '';
+        let elementNode = null;
+        let childrenNode = null;
+        for (const prop of node.properties ?? []) {
+            if (prop.type !== 'ObjectProperty' && prop.type !== 'Property')
+                continue;
+            const key = prop.key?.name || prop.key?.value;
+            if (key === 'path') {
+                if (prop.value?.type === 'StringLiteral')
+                    routeSegment = prop.value.value;
+            }
+            else if (key === 'element') {
+                elementNode = prop.value;
+            }
+            else if (key === 'Component') {
+                // createBrowserRouter also supports Component: MyPage directly.
+                elementNode = prop.value;
+            }
+            else if (key === 'children') {
+                childrenNode = prop.value;
             }
         }
-        return map;
+        const fullPath = routeSegment
+            ? pathPrefix
+                ? `${pathPrefix}/${routeSegment}`.replace(/\/+/g, '/')
+                : routeSegment
+            : pathPrefix;
+        const childElements = childrenNode?.type === 'ArrayExpression' ? (childrenNode.elements ?? []) : [];
+        const hasChildRoutes = childElements.length > 0;
+        // Resolve the component from element={<Comp />} or Component={Comp}.
+        const resolvedFile = elementNode
+            ? this.resolveElementNodeToFile(elementNode, importMap)
+            : null;
+        const effectiveFile = resolvedFile ?? filePath;
+        const fileScore = scoreFilePath(effectiveFile);
+        const isLayoutRoute = hasChildRoutes && (fileScore === 0 || resolvedFile === null);
+        if (routeSegment || (!hasChildRoutes && fullPath)) {
+            results.push({
+                path: fullPath,
+                filePath: effectiveFile,
+                isDynamic: fullPath.includes(':'),
+                params: (fullPath.match(/:(\w+)/g) ?? []).map((p) => p.slice(1)),
+                layout: null,
+                routerType: 'react-router',
+                semantic: this.deriveSemanticMeaning(fullPath),
+                isLayoutRoute,
+            });
+        }
+        for (const child of childElements) {
+            if (child)
+                this.walkObjectRouteConfig(child, fullPath, filePath, importMap, results);
+        }
     }
-    resolveRouteComponentFile(routeOpeningPath, importMap) {
-        const elementAttr = routeOpeningPath.node.attributes.find((a) => a.name?.name === 'element');
+    // ---------------------------------------------------------------------------
+    // Component resolution
+    // ---------------------------------------------------------------------------
+    resolveRouteComponentFile(openingElement, importMap) {
+        const elementAttr = openingElement.attributes.find((a) => a.name?.name === 'element');
         if (!elementAttr)
             return null;
         const expr = elementAttr.value?.expression;
         if (!expr)
             return null;
-        // Collect all JSX component names in document order (outermost first, then
-        // children). For each, resolve via the import map, then pick the best candidate:
-        // a file under pages/ beats a wrapper/provider/layout/guard/context.
+        return this.resolveElementNodeToFile(expr, importMap);
+    }
+    /**
+     * Given a JSX expression node (either a JSXElement or an Identifier) that
+     * represents the value passed to an `element` or `Component` prop, resolve
+     * it to the best-scoring file path via the import map.
+     */
+    resolveElementNodeToFile(expr, importMap) {
+        // Component={MyPage} — expr is an Identifier
+        if (expr.type === 'Identifier') {
+            const resolved = importMap.get(expr.name);
+            return resolved ?? null;
+        }
+        // element={<MyPage />} or element={<Wrapper><MyPage /></Wrapper>}
+        // Collect all JSX component names depth-first, score each, pick best.
         const componentNames = this.collectJSXComponentNames(expr);
         const candidates = [];
-        for (const componentName of componentNames) {
-            const resolved = importMap.get(componentName);
+        for (const name of componentNames) {
+            const resolved = importMap.get(name);
             if (resolved)
                 candidates.push(resolved);
         }
         if (candidates.length === 0)
             return null;
-        // Score: page files rank highest, known non-page patterns rank lowest.
-        const score = (filePath) => {
-            const p = filePath.replace(/\\/g, '/').toLowerCase();
-            if (p.includes('/pages/'))
-                return 3;
-            if (p.includes('/views/') || p.includes('/screens/'))
-                return 2;
-            // Wrappers, providers, guards, layouts, contexts are structural — not page components
-            if (/\/(contexts?|providers?|guards?|layouts?|wrappers?|hoc|utils?|helpers?)\//.test(p) ||
-                /(provider|context|guard|layout|redirect|catchall|catch-all)/.test(p))
-                return 0;
-            return 1;
-        };
-        return candidates.reduce((best, c) => (score(c) >= score(best) ? c : best));
+        return candidates.reduce((best, c) => (scoreFilePath(c) >= scoreFilePath(best) ? c : best));
     }
     collectJSXComponentNames(node) {
         if (!node)
@@ -236,6 +386,31 @@ class RouteExtractor {
         }
         return [];
     }
+    // ---------------------------------------------------------------------------
+    // Import map
+    // ---------------------------------------------------------------------------
+    buildImportMap(ast, fromFile) {
+        const map = new Map();
+        for (const node of ast.program.body) {
+            if (node.type !== 'ImportDeclaration')
+                continue;
+            const importSource = node.source?.value;
+            if (!importSource)
+                continue;
+            const resolved = this.resolveImportToFile(importSource, fromFile);
+            if (!resolved)
+                continue;
+            for (const specifier of node.specifiers ?? []) {
+                if (specifier.type === 'ImportDefaultSpecifier' ||
+                    specifier.type === 'ImportSpecifier') {
+                    const localName = specifier.local?.name;
+                    if (localName)
+                        map.set(localName, resolved);
+                }
+            }
+        }
+        return map;
+    }
     resolveImportToFile(importSource, fromFile) {
         if (!importSource.startsWith('.') && !importSource.startsWith('/'))
             return null;
@@ -260,6 +435,9 @@ class RouteExtractor {
         }
         return null;
     }
+    // ---------------------------------------------------------------------------
+    // File discovery
+    // ---------------------------------------------------------------------------
     findFilesContaining(dir, pattern) {
         const results = [];
         const entries = fs_1.default.readdirSync(dir, { withFileTypes: true });
@@ -276,6 +454,9 @@ class RouteExtractor {
         }
         return results;
     }
+    // ---------------------------------------------------------------------------
+    // Utilities
+    // ---------------------------------------------------------------------------
     extractParams(routePath) {
         const nextParams = (routePath.match(/\[([^\]]+)\]/g) || []).map((m) => m.replace(/[\[\]\.]/g, ''));
         const rrParams = (routePath.match(/:(\w+)/g) || []).map((m) => m.slice(1));

package/dist/types.d.ts

@@ -29,6 +29,13 @@ export interface DiscoveredRoute {
     layout: string | null;
     routerType: 'app' | 'pages' | 'react-router' | 'tanstack';
     semantic: string;
+    /**
+     * True when this route exists only as a layout/guard/wrapper container.
+     * Its filePath points to a structural file (provider, guard, layout) rather
+     * than an actual page component. ComponentExtractor skips these as
+     * module-graph entry points — their content is reached via child routes.
+     */
+    isLayoutRoute?: boolean;
 }
 export interface DiscoveredElement {
     tag: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dcoder-x/plugin-shared",
-  "version": "0.1.13",
+  "version": "0.1.15",
   "private": false,
   "main": "dist/index.js",
   "types": "dist/index.d.ts",