@skyramp/mcp 0.2.1 → 0.2.2

package/build/utils/dartRouteExtractor.js

@@ -0,0 +1,319 @@
+/**
+ * Dart route extraction for Flutter apps using the `go_router` package.
+ *
+ * Walks the repo's Dart sources looking for GoRoute declarations with
+ * string-literal `path:` arguments:
+ *
+ *   GoRoute(path: '/login', builder: (ctx, st) => LoginScreen())
+ *   GoRoute(path: "/profile/:id", builder: ...)
+ *
+ * Why regex (not a Dart compiler): Dart parsers (analyzer, dart-analyzer
+ * package) require a Dart SDK install. Regex on the GoRoute string-literal-path
+ * subset gives ~95% coverage of real customer apps with zero install cost.
+ * Constants like `path: _kHome` are deliberately skipped — emitting them
+ * as a URL `_kHome` would mislead the agent worse than dropping them.
+ *
+ * Each route also carries metadata to support diff-matching in the caller
+ * (findCandidatePagesByDartRoute):
+ *
+ *   - `screenWidgets`: identifiers referenced as builder/pageBuilder targets,
+ *     e.g. `AuthorsScreen`. Resolved through the file's imports to absolute
+ *     paths in `screenFiles`.
+ *   - `screenFiles`: the imported source files those identifiers come from.
+ *   - `isRedirectOnly`: true if the GoRoute has `redirect:` but no
+ *     `builder:` or `pageBuilder:` — these don't render UI, just redirect.
+ *
+ * Scope choices for slice 1:
+ *   - GoRouter only (`MaterialApp.routes` and `auto_route` deferred)
+ *   - String-literal `path:` only (no constant resolution)
+ *   - Nested GoRoutes emit each declaration verbatim — the absolute parent
+ *     plus relative children. Caller may compose them later.
+ */
+import * as fs from "fs";
+import * as path from "path";
+const MAX_CANDIDATE_FILES = 200;
+const MAX_WALK_DEPTH = 10;
+const SKIP_DIRS = new Set([
+    "build",
+    ".dart_tool",
+    ".git",
+    ".idea",
+    "android",
+    "ios",
+    "macos",
+    "linux",
+    "windows",
+    "web",
+    "node_modules",
+    "test",
+    ".pub-cache",
+]);
+/**
+ * Match a GoRoute declaration's body — from the opening `(` through to its
+ * matching `)`. We need the body to extract `path:`, screen widgets, and
+ * the redirect/builder distinction.
+ *
+ * The regex captures the literal string after `path:` and the start of the
+ * GoRoute call body; we then walk forward manually to find the matching
+ * close paren (regex can't match balanced parens reliably).
+ */
+const GO_ROUTE_PATH_REGEX = /\bGoRoute\s*\(\s*(?:<[^>]+>\s*)?[\s\S]*?path\s*:\s*(['"])([^'"\\]*)\1/g;
+/** Identifier reference inside builder:/pageBuilder: bodies — `AuthorsScreen`, `Authors`. */
+const SCREEN_WIDGET_REGEX = /\b([A-Z][A-Za-z0-9_]*)\s*\(/g;
+/** Top-level Dart import: `import 'src/screens/authors.dart';` or `package:foo/bar.dart`. */
+const IMPORT_REGEX = /^\s*import\s+['"]([^'"]+)['"]/gm;
+/** Identifiers we never treat as screen widgets — Flutter framework + go_router internals. */
+const NON_SCREEN_IDENTIFIERS = new Set([
+    "BuildContext", "GoRouterState", "GoRoute", "GoRouter", "ShellRoute",
+    "StatefulShellRoute", "ShellRouteBase", "MaterialPage", "CupertinoPage",
+    "CustomTransitionPage", "FadeTransitionPage", "Page", "Widget", "Key",
+    "ValueKey", "LocalKey", "Future", "Animation", "Duration",
+    "MaterialApp", "CupertinoApp", "Scaffold", "AppBar",
+]);
+export function extractDartRoutes(repositoryPath) {
+    const candidates = findDartFiles(repositoryPath);
+    const seen = new Set();
+    const routes = [];
+    for (const file of candidates) {
+        let source;
+        try {
+            source = fs.readFileSync(file, "utf-8");
+        }
+        catch {
+            continue;
+        }
+        const imports = collectImports(source, file, repositoryPath);
+        GO_ROUTE_PATH_REGEX.lastIndex = 0;
+        let match;
+        while ((match = GO_ROUTE_PATH_REGEX.exec(source)) !== null) {
+            const pathValue = match[2];
+            if (seen.has(pathValue))
+                continue;
+            seen.add(pathValue);
+            const body = extractGoRouteBody(source, match.index);
+            const inspect = inspectGoRouteBody(body);
+            const screenFiles = [];
+            for (const widget of inspect.screenWidgets) {
+                const resolved = imports.get(widget);
+                if (resolved)
+                    screenFiles.push(resolved);
+            }
+            routes.push({
+                path: pathValue,
+                declaredIn: file,
+                screenWidgets: inspect.screenWidgets,
+                screenFiles,
+                isRedirectOnly: inspect.isRedirectOnly,
+            });
+        }
+    }
+    return routes;
+}
+/**
+ * Starting at `start` (the index of the matched `GoRoute` token), find the
+ * end of the GoRoute call by counting balanced `(` / `)`. Stops at the
+ * matching close paren of the outermost GoRoute(...). Strings are skipped
+ * so we don't mis-count a `)` inside a string literal.
+ *
+ * Returns the call body (between the outer parens) — empty string on failure.
+ */
+function extractGoRouteBody(source, start) {
+    // Find the first '(' after `GoRoute`
+    const openParen = source.indexOf("(", start);
+    if (openParen < 0)
+        return "";
+    let depth = 1;
+    let i = openParen + 1;
+    let inString = null;
+    while (i < source.length && depth > 0) {
+        const ch = source[i];
+        if (inString) {
+            if (ch === "\\") {
+                i += 2;
+                continue;
+            }
+            if (ch === inString)
+                inString = null;
+        }
+        else {
+            if (ch === '"' || ch === "'")
+                inString = ch;
+            else if (ch === "(")
+                depth++;
+            else if (ch === ")")
+                depth--;
+        }
+        i++;
+    }
+    if (depth !== 0)
+        return "";
+    return source.slice(openParen + 1, i - 1);
+}
+/**
+ * Inspect a GoRoute body to find:
+ *   - screen widget identifiers from builder:/pageBuilder:
+ *   - whether the route is redirect-only (no builder/pageBuilder)
+ *
+ * The `routes:` nested GoRoute siblings are stripped before scanning so
+ * we don't pick up child route widgets as part of the parent's screens.
+ */
+function inspectGoRouteBody(body) {
+    const builderPart = extractKeyValue(body, "builder");
+    const pageBuilderPart = extractKeyValue(body, "pageBuilder");
+    const redirectPart = extractKeyValue(body, "redirect");
+    const screenWidgets = [];
+    for (const part of [builderPart, pageBuilderPart]) {
+        if (!part)
+            continue;
+        SCREEN_WIDGET_REGEX.lastIndex = 0;
+        let m;
+        while ((m = SCREEN_WIDGET_REGEX.exec(part)) !== null) {
+            const id = m[1];
+            if (NON_SCREEN_IDENTIFIERS.has(id))
+                continue;
+            if (!screenWidgets.includes(id))
+                screenWidgets.push(id);
+        }
+    }
+    const hasBuilder = !!builderPart || !!pageBuilderPart;
+    const hasRedirect = !!redirectPart;
+    const isRedirectOnly = hasRedirect && !hasBuilder;
+    return { screenWidgets, isRedirectOnly };
+}
+/**
+ * Find a `key:` value in a GoRoute body. Returns the substring after `key:`
+ * up to the next top-level comma (depth 0 brace/paren/bracket), or `null`
+ * when the key isn't present. Strings and nested groups are skipped.
+ */
+function extractKeyValue(body, key) {
+    const re = new RegExp(`\\b${key}\\s*:`, "g");
+    const m = re.exec(body);
+    if (!m)
+        return null;
+    let i = m.index + m[0].length;
+    // Skip whitespace
+    while (i < body.length && /\s/.test(body[i]))
+        i++;
+    const start = i;
+    let depth = 0;
+    let inString = null;
+    while (i < body.length) {
+        const ch = body[i];
+        if (inString) {
+            if (ch === "\\") {
+                i += 2;
+                continue;
+            }
+            if (ch === inString)
+                inString = null;
+        }
+        else {
+            if (ch === '"' || ch === "'")
+                inString = ch;
+            else if (ch === "(" || ch === "[" || ch === "{")
+                depth++;
+            else if (ch === ")" || ch === "]" || ch === "}") {
+                if (depth === 0)
+                    break;
+                depth--;
+            }
+            else if (ch === "," && depth === 0)
+                break;
+        }
+        i++;
+    }
+    return body.slice(start, i).trim();
+}
+/**
+ * Build a `local-name → absolute-file-path` map from the file's imports.
+ *
+ * Dart imports two ways:
+ *   import 'src/screens/authors.dart';   → relative within current package
+ *   import 'package:foo/screens/x.dart'; → cross-package, not resolved here
+ *
+ * We only resolve relative imports (the common case for in-app screens).
+ * The "local name" for a relative import is taken as ALL identifiers that
+ * the file exports — but since we don't parse the imported file's exports,
+ * we use a coarse approximation: the importing file's `import 'X.dart';`
+ * makes available any PascalCase identifier referenced from the file's
+ * scope. We map every identifier we see in builder/pageBuilder bodies to
+ * the union of relative imports — first matching one wins.
+ *
+ * For the common Flutter pattern (one screen widget per screen file with
+ * a matching name like `AuthorsScreen`), we approximate via filename:
+ *   import 'src/screens/authors.dart' → expose `AuthorsScreen`, `Authors`
+ *
+ * False positives on this approximation just mean we surface a route that
+ * shouldn't have been; false negatives just mean we fall back to "no
+ * diff-match" and surface all routes (the previous behavior).
+ */
+function collectImports(source, filePath, repoPath) {
+    const result = new Map();
+    const fileDir = path.dirname(filePath);
+    IMPORT_REGEX.lastIndex = 0;
+    let match;
+    while ((match = IMPORT_REGEX.exec(source)) !== null) {
+        const spec = match[1];
+        if (spec.startsWith("package:") || spec.startsWith("dart:"))
+            continue;
+        if (!spec.endsWith(".dart"))
+            continue;
+        const resolved = path.resolve(fileDir, spec);
+        if (!resolved.startsWith(repoPath))
+            continue;
+        // Filename-based heuristic: `authors.dart` exposes `Authors`, `AuthorsScreen`,
+        // `AuthorsScreenState`, etc. We register a few common shapes derived from
+        // the file's basename. Conflicts (the same identifier present in two
+        // imports) resolve to the first registration.
+        const base = path.basename(spec, ".dart");
+        const camel = snakeToCamel(base);
+        const candidates = [
+            camel,
+            camel + "Screen",
+            camel + "Page",
+            camel + "View",
+        ];
+        for (const id of candidates) {
+            if (!result.has(id))
+                result.set(id, resolved);
+        }
+    }
+    return result;
+}
+function snakeToCamel(s) {
+    return s
+        .split("_")
+        .map((p, i) => p.charAt(0).toUpperCase() + p.slice(1))
+        .join("");
+}
+function findDartFiles(repoPath) {
+    const matches = [];
+    function walk(dir, depth) {
+        if (depth > MAX_WALK_DEPTH)
+            return;
+        if (matches.length >= MAX_CANDIDATE_FILES)
+            return;
+        let entries;
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (matches.length >= MAX_CANDIDATE_FILES)
+                return;
+            const full = path.join(dir, entry.name);
+            if (entry.isDirectory()) {
+                if (SKIP_DIRS.has(entry.name) || entry.name.startsWith("."))
+                    continue;
+                walk(full, depth + 1);
+            }
+            else if (entry.isFile() && entry.name.endsWith(".dart")) {
+                matches.push(full);
+            }
+        }
+    }
+    walk(repoPath, 0);
+    return matches;
+}

package/build/utils/dartRouteExtractor.test.js

@@ -0,0 +1,307 @@
+// No external mocks needed — the extractor is pure fs + regex.
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+import { extractDartRoutes } from "./dartRouteExtractor.js";
+function makeTmpRepo(files) {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), "skyramp-dart-route-test-"));
+    for (const f of files) {
+        const fullPath = path.join(dir, f.path);
+        fs.mkdirSync(path.dirname(fullPath), { recursive: true });
+        fs.writeFileSync(fullPath, f.content);
+    }
+    return dir;
+}
+function cleanup(dir) {
+    fs.rmSync(dir, { recursive: true, force: true });
+}
+describe("extractDartRoutes", () => {
+    it("returns empty when repo has no .dart files", () => {
+        const repo = makeTmpRepo([
+            { path: "lib/main.dart", content: "void main() => runApp(MyApp());" },
+        ]);
+        expect(extractDartRoutes(repo)).toEqual([]);
+        cleanup(repo);
+    });
+    it("extracts a single GoRoute with double-quoted path", () => {
+        const repo = makeTmpRepo([
+            {
+                path: "lib/router.dart",
+                content: `
+import 'package:go_router/go_router.dart';
+
+final router = GoRouter(routes: [
+  GoRoute(path: "/login", builder: (ctx, st) => LoginScreen()),
+]);
+`,
+            },
+        ]);
+        const routes = extractDartRoutes(repo);
+        expect(routes).toHaveLength(1);
+        expect(routes[0].path).toBe("/login");
+        expect(routes[0].declaredIn).toMatch(/router\.dart$/);
+        cleanup(repo);
+    });
+    it("extracts a single GoRoute with single-quoted path", () => {
+        const repo = makeTmpRepo([
+            {
+                path: "lib/app.dart",
+                content: `GoRoute(path: '/home', builder: (c, s) => Home())`,
+            },
+        ]);
+        const routes = extractDartRoutes(repo);
+        expect(routes).toHaveLength(1);
+        expect(routes[0].path).toBe("/home");
+        cleanup(repo);
+    });
+    it("extracts multiple GoRoutes from one file", () => {
+        const repo = makeTmpRepo([
+            {
+                path: "lib/router.dart",
+                content: `
+final router = GoRouter(routes: [
+  GoRoute(path: '/login', builder: (c, s) => LoginScreen()),
+  GoRoute(path: '/dashboard', builder: (c, s) => DashboardScreen()),
+  GoRoute(path: '/profile/:id', builder: (c, s) => ProfileScreen()),
+]);
+`,
+            },
+        ]);
+        const routes = extractDartRoutes(repo);
+        expect(routes.map((r) => r.path).sort()).toEqual([
+            "/dashboard",
+            "/login",
+            "/profile/:id",
+        ]);
+        cleanup(repo);
+    });
+    it("extracts nested GoRoutes (sub-routes inside parent)", () => {
+        const repo = makeTmpRepo([
+            {
+                path: "lib/router.dart",
+                content: `
+GoRoute(
+  path: '/settings',
+  builder: (c, s) => SettingsScreen(),
+  routes: [
+    GoRoute(path: 'account', builder: (c, s) => AccountScreen()),
+    GoRoute(path: 'privacy', builder: (c, s) => PrivacyScreen()),
+  ],
+);
+`,
+            },
+        ]);
+        const routes = extractDartRoutes(repo);
+        expect(routes.map((r) => r.path).sort()).toEqual([
+            "/settings",
+            "account",
+            "privacy",
+        ]);
+        cleanup(repo);
+    });
+    it("walks lib/ and skips build, .dart_tool, ios, android, macos, web", () => {
+        const repo = makeTmpRepo([
+            {
+                path: "lib/router.dart",
+                content: `GoRoute(path: '/real', builder: (c, s) => X())`,
+            },
+            {
+                path: "build/app/intermediates/router.dart",
+                content: `GoRoute(path: '/build-fake', builder: (c, s) => X())`,
+            },
+            {
+                path: ".dart_tool/something.dart",
+                content: `GoRoute(path: '/tool-fake', builder: (c, s) => X())`,
+            },
+            {
+                path: "ios/Generated.dart",
+                content: `GoRoute(path: '/ios-fake', builder: (c, s) => X())`,
+            },
+        ]);
+        const routes = extractDartRoutes(repo);
+        expect(routes.map((r) => r.path)).toEqual(["/real"]);
+        cleanup(repo);
+    });
+    it("ignores GoRoute calls without a string-literal path (constants, expressions)", () => {
+        const repo = makeTmpRepo([
+            {
+                path: "lib/router.dart",
+                content: `
+const _kHome = '/home';
+final router = GoRouter(routes: [
+  GoRoute(path: _kHome, builder: (c, s) => H()),
+  GoRoute(path: '/login', builder: (c, s) => L()),
+]);
+`,
+            },
+        ]);
+        const routes = extractDartRoutes(repo);
+        expect(routes.map((r) => r.path)).toEqual(["/login"]);
+        cleanup(repo);
+    });
+    it("returns empty for non-Flutter Dart files (no GoRoute calls)", () => {
+        const repo = makeTmpRepo([
+            {
+                path: "bin/server.dart",
+                content: `
+void main() async {
+  final server = await HttpServer.bind('localhost', 8080);
+  await for (final req in server) { /* ... */ }
+}
+`,
+            },
+        ]);
+        expect(extractDartRoutes(repo)).toEqual([]);
+        cleanup(repo);
+    });
+    it("deduplicates identical GoRoute paths declared multiple times", () => {
+        const repo = makeTmpRepo([
+            {
+                path: "lib/a.dart",
+                content: `GoRoute(path: '/login', builder: (c, s) => A())`,
+            },
+            {
+                path: "lib/b.dart",
+                content: `GoRoute(path: '/login', builder: (c, s) => B())`,
+            },
+        ]);
+        const routes = extractDartRoutes(repo);
+        expect(routes).toHaveLength(1);
+        expect(routes[0].path).toBe("/login");
+        cleanup(repo);
+    });
+    // Real-world: extract all routes from the books example we built locally.
+    // This guards the regex against the actual customer-style GoRouter shape
+    // — multi-line declarations with redirect+pageBuilder mixed in.
+    it("extracts the books example's six routes", () => {
+        const repo = makeTmpRepo([
+            {
+                path: "lib/main.dart",
+                content: `
+import 'package:go_router/go_router.dart';
+
+late final GoRouter _router = GoRouter(
+  routes: <GoRoute>[
+    GoRoute(path: '/', redirect: (_, _) => '/books'),
+    GoRoute(
+      path: '/signin',
+      pageBuilder: (BuildContext context, GoRouterState state) => SignIn(),
+    ),
+    GoRoute(path: '/books', redirect: (_, _) => '/books/popular'),
+    GoRoute(
+      path: '/book/:bookId',
+      redirect: (BuildContext context, GoRouterState state) =>
+          '/books/all/' + state.pathParameters['bookId']!,
+    ),
+    GoRoute(
+      path: '/books/:kind(new|all|popular)',
+      pageBuilder: (BuildContext context, GoRouterState state) => Books(),
+      routes: <GoRoute>[
+        GoRoute(
+          path: ':bookId',
+          builder: (BuildContext context, GoRouterState state) => BookDetails(),
+        ),
+      ],
+    ),
+    GoRoute(
+      path: '/author/:authorId',
+      redirect: (BuildContext context, GoRouterState state) =>
+          '/authors/' + state.pathParameters['authorId']!,
+    ),
+    GoRoute(
+      path: '/authors',
+      pageBuilder: (BuildContext context, GoRouterState state) => Authors(),
+      routes: <GoRoute>[
+        GoRoute(
+          path: ':authorId',
+          builder: (BuildContext context, GoRouterState state) => AuthorDetails(),
+        ),
+      ],
+    ),
+    GoRoute(
+      path: '/settings',
+      pageBuilder: (BuildContext context, GoRouterState state) => Settings(),
+    ),
+  ],
+);
+`,
+            },
+        ]);
+        const routes = extractDartRoutes(repo);
+        const paths = routes.map((r) => r.path).sort();
+        // Top-level absolute paths.
+        expect(paths).toEqual([
+            "/",
+            "/author/:authorId",
+            "/authors",
+            "/book/:bookId",
+            "/books",
+            "/books/:kind(new|all|popular)",
+            "/settings",
+            "/signin",
+            ":authorId",
+            ":bookId",
+        ].sort());
+        cleanup(repo);
+    });
+    // ── New shape: screenWidgets, screenFiles, isRedirectOnly ─────────────────
+    it("flags redirect-only routes (no builder/pageBuilder)", () => {
+        const repo = makeTmpRepo([
+            {
+                path: "lib/router.dart",
+                content: `
+GoRoute(path: '/', redirect: (_, _) => '/home'),
+GoRoute(path: '/home', builder: (c, s) => Home()),
+`,
+            },
+        ]);
+        const routes = extractDartRoutes(repo);
+        const root = routes.find((r) => r.path === "/");
+        const home = routes.find((r) => r.path === "/home");
+        expect(root?.isRedirectOnly).toBe(true);
+        expect(home?.isRedirectOnly).toBe(false);
+        cleanup(repo);
+    });
+    it("captures screen widget identifiers from builder/pageBuilder", () => {
+        const repo = makeTmpRepo([
+            {
+                path: "lib/router.dart",
+                content: `
+GoRoute(path: '/login', builder: (c, s) => LoginScreen()),
+GoRoute(path: '/profile', pageBuilder: (c, s) => MaterialPage(child: ProfileScreen())),
+`,
+            },
+        ]);
+        const routes = extractDartRoutes(repo);
+        const login = routes.find((r) => r.path === "/login");
+        const profile = routes.find((r) => r.path === "/profile");
+        expect(login?.screenWidgets).toContain("LoginScreen");
+        expect(profile?.screenWidgets).toContain("ProfileScreen");
+        // Ignored framework identifiers should NOT appear.
+        expect(login?.screenWidgets).not.toContain("BuildContext");
+        expect(profile?.screenWidgets).not.toContain("MaterialPage");
+        cleanup(repo);
+    });
+    it("resolves screenWidgets to imported file paths via filename heuristic", () => {
+        const repo = makeTmpRepo([
+            {
+                path: "lib/main.dart",
+                content: `
+import 'src/screens/authors.dart';
+import 'src/screens/settings.dart';
+
+GoRoute(path: '/authors', builder: (c, s) => AuthorsScreen()),
+GoRoute(path: '/settings', builder: (c, s) => SettingsScreen()),
+`,
+            },
+            { path: "lib/src/screens/authors.dart", content: "// AuthorsScreen widget" },
+            { path: "lib/src/screens/settings.dart", content: "// SettingsScreen widget" },
+        ]);
+        const routes = extractDartRoutes(repo);
+        const authors = routes.find((r) => r.path === "/authors");
+        const settings = routes.find((r) => r.path === "/settings");
+        expect(authors?.screenFiles[0]).toMatch(/lib\/src\/screens\/authors\.dart$/);
+        expect(settings?.screenFiles[0]).toMatch(/lib\/src\/screens\/settings\.dart$/);
+        cleanup(repo);
+    });
+});