devlensio 0.4.2 → 0.4.4

package/README.md

@@ -26,10 +26,11 @@ Requires Node 18+ (or Bun). An LLM provider key is needed only for summarization
 Repo path
    │
 [1] Fingerprint     detect language, framework, router, state manager, data layer, databases
-[2] Filesystem scan extract routes (Next.js app/pages, Express, Fastify, Koa)
+[2] Route detection  extract routes (Next.js app/pages, React Router / TanStack / wouter,
+                    Express, Fastify, Koa)
 [3] Parse (ts-morph) walk every .ts/.tsx/.js/.jsx → nodes (typed params, return types, prop types)
 [4] Edge detection  many detectors → CALLS, IMPORTS, READS_FROM, WRITES_TO, PROP_PASS, EMITS,
-                    LISTENS, WRAPPED_BY, GUARDS, HANDLES, TESTS, USES
+                    LISTENS, WRAPPED_BY, GUARDS, HANDLES, TESTS, USES, NEXTJS_API_CALL, NAVIGATES_TO
 [5] Scoring         multi-pass importance scoring + noise filtering (no AI)
 [6] Clustering      cohesive cluster assignment
 [7] Summarize       (optional) topologically-ordered LLM summaries, checkpoint/resume, MapReduce
@@ -73,7 +74,8 @@ Also exported: all core types (`CodeNode`, `CodeEdge`, `NodeType`, `EdgeType`,
 ### Node & edge types
 
 - **Node types:** `COMPONENT`, `HOOK`, `FUNCTION`, `STATE_STORE`, `UTILITY`, `FILE`, `ROUTE`, `TEST`, `STORY`, `THIRD_PARTY` (+ internal `GHOST`).
-- **Edge types:** `CALLS`, `IMPORTS`, `READS_FROM`, `WRITES_TO`, `PROP_PASS`, `EMITS`, `LISTENS`, `WRAPPED_BY`, `GUARDS`, `HANDLES`, `TESTS`, `USES`.
+- **Route subtypes** (on `ROUTE` nodes via `metadata.routeNodeType`): `PAGE`, `LAYOUT`, `API_ROUTE`, `LOADING`, `ERROR`, `MIDDLEWARE`, `NOT_FOUND` (Next.js), and `REACT_ROUTER_ROUTE` (React Router / TanStack / wouter, defined in code rather than on the filesystem). Navigation targets that can't be resolved to a known route — dynamic paths, unmatched paths, or external URLs — become `[route]::…` ROUTE nodes flagged `isUnresolved` / `isExternal`.
+- **Edge types:** `CALLS`, `IMPORTS`, `READS_FROM`, `WRITES_TO`, `PROP_PASS`, `EMITS`, `LISTENS`, `WRAPPED_BY`, `GUARDS`, `HANDLES`, `TESTS`, `USES`, `NEXTJS_API_CALL` (frontend `fetch`/`axios`/`useSWR` call site → Next.js API route), `NAVIGATES_TO` (client-side navigation — `navigate()`, `router.push/replace`, `history.*`, `window.location.*`, `<Link>`/`<NavLink>` — from a component/hook/function → the ROUTE it targets).
 - Each node carries an importance score and (after summarization) a technical summary, a business summary, and a security assessment (`none|low|medium|high` + notes).
 
 ---
@@ -98,7 +100,7 @@ Graphs and config are stored under `~/.devlens` and shared with all DevLens tool
 ```
 src/
 ├── fingerprint/   # detect framework, language, router, state, data layer, databases
-├── filesystem/    # route detection (Next.js app/pages, Express, Fastify, Koa)
+├── filesystem/    # route detection (Next.js app/pages, React Router/TanStack/wouter, Express, Fastify, Koa)
 ├── parser/        # ts-morph AST extraction → nodes
 ├── graph/         # edge detectors, traversal API, third-party libs, lookup maps
 ├── scoring/       # multi-pass importance scoring + noise filtering

package/dist/filesystem/index.js

@@ -2,11 +2,17 @@ import path from "path";
 import { analyzeAppRouter } from "./appRouter.js";
 import { analyzePagesRouter } from "./pagesRouter.js";
 import { analyzeBackendRoutes } from "./backendRoutes.js";
+import { analyzeReactRouterRoutes } from "./reactRouterRoutes.js";
 export function analyzeFilesystem(repoPath, fingerprint) {
     // Handle backend frameworks first
     if (["express", "fastify", "koa"].includes(fingerprint.framework)) {
         return analyzeBackendRoutes(repoPath);
     }
+    // Handle React Router projects (framework: "react", router: "react-router").
+    // Routes are defined in code, so this runs before the Next.js gate below.
+    if (fingerprint.router === "react-router") {
+        return analyzeReactRouterRoutes(repoPath);
+    }
     // Handle Next.js frontend
     if (fingerprint.framework !== "nextjs") {
         return [];

package/dist/filesystem/index.test.js

@@ -176,3 +176,173 @@ describe("analyzeFilesystem", () => {
         deleteFakeRepo(repoPath);
     });
 });
+// ─── React Router ───────────────────────────────────────────────────────────────
+describe("analyzeFilesystem — React Router", () => {
+    // React Router routes live in code, so these fixtures need real file content
+    // (the top-level createFakeRepo writes a placeholder comment instead).
+    function createRepoWithFiles(files) {
+        const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "devlens-rr-test-"));
+        for (const [filePath, content] of Object.entries(files)) {
+            const fullPath = path.join(tmpDir, filePath);
+            fs.mkdirSync(path.dirname(fullPath), { recursive: true });
+            fs.writeFileSync(fullPath, content);
+        }
+        return tmpDir;
+    }
+    const rrFingerprint = makeFingerprint("react", "react-router");
+    it("detects a JSX <Route path> route", () => {
+        const repoPath = createRepoWithFiles({
+            "src/App.tsx": `
+        import { Routes, Route } from "react-router-dom";
+        export default function App() {
+          return (
+            <Routes>
+              <Route path="/users" element={<Users />} />
+            </Routes>
+          );
+        }
+      `,
+        });
+        const routes = analyzeFilesystem(repoPath, rrFingerprint);
+        const route = routes.find((r) => r.urlPath === "/users");
+        expect(route).toBeDefined();
+        expect(route?.type).toBe("REACT_ROUTER_ROUTE");
+        deleteFakeRepo(repoPath);
+    });
+    it("detects a dynamic JSX <Route path> with params", () => {
+        const repoPath = createRepoWithFiles({
+            "src/App.tsx": `
+        import { Route } from "react-router-dom";
+        export default function App() {
+          return <Route path="/users/:id" element={<User />} />;
+        }
+      `,
+        });
+        const routes = analyzeFilesystem(repoPath, rrFingerprint);
+        const route = routes.find((r) => r.urlPath === "/users/:id");
+        expect(route).toBeDefined();
+        expect(route?.isDynamic).toBe(true);
+        expect(route?.params).toContain("id");
+        deleteFakeRepo(repoPath);
+    });
+    it("assembles nested paths from createBrowserRouter children", () => {
+        const repoPath = createRepoWithFiles({
+            "src/router.tsx": `
+        import { createBrowserRouter } from "react-router-dom";
+        export const router = createBrowserRouter([
+          {
+            path: "/dashboard",
+            element: <Dashboard />,
+            children: [
+              { path: "settings", element: <Settings /> },
+            ],
+          },
+        ]);
+      `,
+        });
+        const routes = analyzeFilesystem(repoPath, rrFingerprint);
+        expect(routes.find((r) => r.urlPath === "/dashboard")).toBeDefined();
+        expect(routes.find((r) => r.urlPath === "/dashboard/settings")).toBeDefined();
+        deleteFakeRepo(repoPath);
+    });
+    it("detects routes from a useRoutes config", () => {
+        const repoPath = createRepoWithFiles({
+            "src/Routes.tsx": `
+        import { useRoutes } from "react-router-dom";
+        export function AppRoutes() {
+          return useRoutes([
+            { path: "/about", element: <About /> },
+          ]);
+        }
+      `,
+        });
+        const routes = analyzeFilesystem(repoPath, rrFingerprint);
+        expect(routes.find((r) => r.urlPath === "/about")).toBeDefined();
+        deleteFakeRepo(repoPath);
+    });
+    it("detects a TanStack createFileRoute", () => {
+        const repoPath = createRepoWithFiles({
+            "src/routes/dashboard.tsx": `
+        import { createFileRoute } from "@tanstack/react-router";
+        export const Route = createFileRoute("/dashboard")({
+          component: Dashboard,
+        });
+      `,
+        });
+        const routes = analyzeFilesystem(repoPath, rrFingerprint);
+        expect(routes.find((r) => r.urlPath === "/dashboard")).toBeDefined();
+        deleteFakeRepo(repoPath);
+    });
+    it("converts a splat '*' route into a catch-all", () => {
+        const repoPath = createRepoWithFiles({
+            "src/App.tsx": `
+        import { Route } from "react-router-dom";
+        export default function App() {
+          return <Route path="/files/*" element={<Files />} />;
+        }
+      `,
+        });
+        const routes = analyzeFilesystem(repoPath, rrFingerprint);
+        const route = routes.find((r) => r.urlPath === "/files/:splat*");
+        expect(route).toBeDefined();
+        expect(route?.isCatchAll).toBe(true);
+        deleteFakeRepo(repoPath);
+    });
+    // ─── rendersComponent capture ───────────────────────────────────────────
+    it("captures the rendered component from element={<Home/>} (v6 JSX)", () => {
+        const repoPath = createRepoWithFiles({
+            "src/App.tsx": `
+        import { Route } from "react-router-dom";
+        export default function App() {
+          return <Route path="/" element={<Home />} />;
+        }
+      `,
+        });
+        const routes = analyzeFilesystem(repoPath, rrFingerprint);
+        const route = routes.find((r) => r.urlPath === "/");
+        expect(route?.rendersComponent).toBe("Home");
+        deleteFakeRepo(repoPath);
+    });
+    it("captures the rendered component from a v5 component={About} prop", () => {
+        const repoPath = createRepoWithFiles({
+            "src/App.tsx": `
+        import { Route } from "react-router-dom";
+        export default function App() {
+          return <Route path="/about" component={About} />;
+        }
+      `,
+        });
+        const routes = analyzeFilesystem(repoPath, rrFingerprint);
+        const route = routes.find((r) => r.urlPath === "/about");
+        expect(route?.rendersComponent).toBe("About");
+        deleteFakeRepo(repoPath);
+    });
+    it("captures the rendered component from a createBrowserRouter object (element)", () => {
+        const repoPath = createRepoWithFiles({
+            "src/router.tsx": `
+        import { createBrowserRouter } from "react-router-dom";
+        export const router = createBrowserRouter([
+          { path: "/dashboard", element: <Dashboard /> },
+        ]);
+      `,
+        });
+        const routes = analyzeFilesystem(repoPath, rrFingerprint);
+        const route = routes.find((r) => r.urlPath === "/dashboard");
+        expect(route?.rendersComponent).toBe("Dashboard");
+        deleteFakeRepo(repoPath);
+    });
+    it("captures the rendered component from a data-router Component property", () => {
+        const repoPath = createRepoWithFiles({
+            "src/router.tsx": `
+        import { createBrowserRouter } from "react-router-dom";
+        export const router = createBrowserRouter([
+          { path: "/profile", Component: Profile },
+        ]);
+      `,
+        });
+        const routes = analyzeFilesystem(repoPath, rrFingerprint);
+        const route = routes.find((r) => r.urlPath === "/profile");
+        expect(route?.rendersComponent).toBe("Profile");
+        deleteFakeRepo(repoPath);
+    });
+});

package/dist/filesystem/reactRouterRoutes.d.ts

@@ -0,0 +1,2 @@
+import type { RouteNode } from "../types.js";
+export declare function analyzeReactRouterRoutes(repoPath: string): RouteNode[];

package/dist/filesystem/reactRouterRoutes.js

@@ -0,0 +1,243 @@
+// Detects React Router (v5/v6), TanStack Router, and wouter routes, which are
+// defined in CODE (not on the filesystem). Mirrors backendRoutes.ts structure.
+import { Project, SyntaxKind } from "ts-morph";
+import path from "path";
+import fs from "fs";
+const IGNORE_DIRS = [
+    "node_modules", "dist", "build",
+    ".next", "coverage", ".git",
+];
+const ROUTER_FACTORY_NAMES = [
+    "createBrowserRouter", "createHashRouter", "createMemoryRouter", "useRoutes",
+];
+function extractParams(urlPath) {
+    const matches = urlPath.match(/:([a-zA-Z0-9_]+)/g) || [];
+    return matches.map((m) => m.replace(":", ""));
+}
+// Normalizes a route path:
+//   - converts React Router splat segment "*" → ":splat*" (so urlPathtoRegex
+//     treats it as a catch-all, matching the Next.js ":slug*" convention)
+//   - ensures a leading "/"
+//   - strips trailing "/" (except root)
+// Returns null for empty / pathless entries.
+function normalizePath(p) {
+    if (p === null || p === undefined)
+        return null;
+    let s = p.trim();
+    if (s === "")
+        return null;
+    s = s.split("/").map(seg => (seg === "*" ? ":splat*" : seg)).join("/");
+    if (!s.startsWith("/"))
+        s = "/" + s;
+    s = s.replace(/\/+$/, "");
+    return s === "" ? "/" : s;
+}
+// Joins a parent path with a (possibly relative) child segment.
+function joinPath(parent, seg) {
+    if (seg.startsWith("/"))
+        return seg; // absolute child
+    if (parent === "" || parent === "/")
+        return "/" + seg;
+    return parent + "/" + seg;
+}
+// Reads a string literal / no-substitution template value, else null.
+function literalString(node) {
+    if (!node)
+        return null;
+    const k = node.getKind();
+    if (k === SyntaxKind.StringLiteral || k === SyntaxKind.NoSubstitutionTemplateLiteral) {
+        return node.getLiteralText();
+    }
+    return null;
+}
+// Resolves the component name from a route's element/component value.
+//   <Home/> / <Home></Home> → "Home"   (element={<Home/>}, element: <Home/>)
+//   Home                     → "Home"   (component={Home}, Component: Home)
+// Returns undefined for inline render functions, lazy imports, etc.
+function extractComponentName(valueNode) {
+    if (!valueNode)
+        return undefined;
+    const k = valueNode.getKind();
+    if (k === SyntaxKind.JsxSelfClosingElement)
+        return valueNode.getTagNameNode().getText();
+    if (k === SyntaxKind.JsxElement)
+        return valueNode.getOpeningElement().getTagNameNode().getText();
+    if (k === SyntaxKind.Identifier)
+        return valueNode.getText();
+    return undefined;
+}
+// Unwraps a JSX attribute initializer (element={<Home/>}) to its inner expression.
+function unwrapJsxAttr(attr) {
+    if (!attr || !attr.getInitializer)
+        return null;
+    const init = attr.getInitializer();
+    if (!init)
+        return null;
+    return init.getKind() === SyntaxKind.JsxExpression ? init.getExpression() : init;
+}
+// Reads the rendered-component name from a route-config object literal's
+// element / Component / component property (checked in that priority order).
+function objComponentName(obj) {
+    for (const propName of ["element", "Component", "component"]) {
+        const prop = obj.getProperty(propName);
+        if (prop && prop.getInitializer) {
+            const name = extractComponentName(prop.getInitializer());
+            if (name)
+                return name;
+        }
+    }
+    return undefined;
+}
+function pushRoute(out, rawPath, filePath, seen, rendersComponent) {
+    const normalized = normalizePath(rawPath);
+    if (normalized === null)
+        return;
+    const key = filePath + "::" + normalized;
+    if (seen.has(key))
+        return;
+    seen.add(key);
+    const params = extractParams(normalized);
+    out.push({
+        type: "REACT_ROUTER_ROUTE",
+        urlPath: normalized,
+        filePath,
+        isDynamic: /[:*]/.test(normalized),
+        isCatchAll: normalized.includes("*"),
+        isGroupRoute: false,
+        params: params.length > 0 ? params : undefined,
+        rendersComponent,
+    });
+}
+// Recursively walks an array literal of route-config objects
+// (createBrowserRouter([...]) / useRoutes([...]) / nested children).
+function walkRouteObjects(arr, parentPath, filePath, out, seen) {
+    for (const el of arr.getElements()) {
+        if (el.getKind() !== SyntaxKind.ObjectLiteralExpression)
+            continue;
+        const pathProp = el.getProperty("path");
+        const indexProp = el.getProperty("index");
+        let seg = null;
+        if (pathProp && pathProp.getInitializer) {
+            seg = literalString(pathProp.getInitializer());
+        }
+        const fullPath = seg !== null ? joinPath(parentPath, seg) : parentPath;
+        const rendersComponent = objComponentName(el);
+        // A real route node when it has a literal path, or is an index route.
+        if (seg !== null) {
+            pushRoute(out, fullPath, filePath, seen, rendersComponent);
+        }
+        else if (indexProp) {
+            pushRoute(out, parentPath, filePath, seen, rendersComponent);
+        }
+        // Recurse into children with fullPath as the new parent.
+        const childrenProp = el.getProperty("children");
+        const childInit = childrenProp && childrenProp.getInitializer ? childrenProp.getInitializer() : null;
+        if (childInit && childInit.getKind() === SyntaxKind.ArrayLiteralExpression) {
+            walkRouteObjects(childInit, fullPath, filePath, out, seen);
+        }
+    }
+}
+function findReactFiles(dir, files = []) {
+    let entries;
+    try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return files;
+    }
+    for (const entry of entries) {
+        const fullPath = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            if (IGNORE_DIRS.includes(entry.name))
+                continue;
+            findReactFiles(fullPath, files);
+        }
+        else if (entry.isFile()) {
+            if (/\.(tsx|jsx|ts|js)$/.test(entry.name))
+                files.push(fullPath);
+        }
+    }
+    return files;
+}
+export function analyzeReactRouterRoutes(repoPath) {
+    const nodes = [];
+    const project = new Project({
+        compilerOptions: { allowJs: true, checkJs: false, jsx: 4, strict: false },
+        skipAddingFilesFromTsConfig: true,
+    });
+    for (const filePath of findReactFiles(repoPath)) {
+        try {
+            project.addSourceFileAtPath(filePath);
+        }
+        catch {
+            continue;
+        }
+    }
+    for (const file of project.getSourceFiles()) {
+        const filePath = file.getFilePath();
+        const seen = new Set();
+        // ── Pattern A: JSX <Route path="..."> / <Route path="..." /> (v5/v6, wouter)
+        for (const el of [
+            ...file.getDescendantsOfKind(SyntaxKind.JsxOpeningElement),
+            ...file.getDescendantsOfKind(SyntaxKind.JsxSelfClosingElement),
+        ]) {
+            const tag = el.getTagNameNode().getText();
+            if (tag !== "Route")
+                continue;
+            const pathAttr = el.getAttribute("path");
+            if (!pathAttr || !pathAttr.getInitializer)
+                continue;
+            const init = pathAttr.getInitializer();
+            if (!init)
+                continue;
+            let valueNode = init;
+            if (init.getKind() === SyntaxKind.JsxExpression) {
+                valueNode = init.getExpression();
+            }
+            const raw = literalString(valueNode);
+            if (raw === null)
+                continue; // computed path — skip
+            // element={<Home/>} (v6) or component={Home} / Component={Home} (v5)
+            const rendersComponent = extractComponentName(unwrapJsxAttr(el.getAttribute("element"))) ??
+                extractComponentName(unwrapJsxAttr(el.getAttribute("component"))) ??
+                extractComponentName(unwrapJsxAttr(el.getAttribute("Component")));
+            pushRoute(nodes, raw, filePath, seen, rendersComponent);
+        }
+        // ── Patterns B & C: createBrowserRouter([...]) / useRoutes([...]) (+ nested children)
+        // ── Pattern D: TanStack createRoute / createFileRoute / createRootRoute
+        for (const call of file.getDescendantsOfKind(SyntaxKind.CallExpression)) {
+            const callee = call.getExpression().getText();
+            const calleeLeaf = callee.split(".").pop();
+            const args = call.getArguments();
+            if (ROUTER_FACTORY_NAMES.includes(calleeLeaf)) {
+                if (args.length === 0)
+                    continue;
+                if (args[0].getKind() === SyntaxKind.ArrayLiteralExpression) {
+                    walkRouteObjects(args[0], "", filePath, nodes, seen);
+                }
+                continue;
+            }
+            if (calleeLeaf === "createFileRoute") {
+                // createFileRoute('/dashboard')(...) — path is the string arg
+                if (args.length > 0)
+                    pushRoute(nodes, literalString(args[0]), filePath, seen);
+                continue;
+            }
+            if (calleeLeaf === "createRoute") {
+                // createRoute({ path: '/x', component: X })
+                if (args.length > 0 && args[0].getKind() === SyntaxKind.ObjectLiteralExpression) {
+                    const pathProp = args[0].getProperty("path");
+                    if (pathProp && pathProp.getInitializer) {
+                        pushRoute(nodes, literalString(pathProp.getInitializer()), filePath, seen, objComponentName(args[0]));
+                    }
+                }
+                continue;
+            }
+            if (calleeLeaf === "createRootRoute") {
+                pushRoute(nodes, "/", filePath, seen);
+                continue;
+            }
+        }
+    }
+    return nodes;
+}