@skyramp/mcp 0.3.8 → 0.4.0-rc.1

package/build/utils/uiPageEnumerator.js

@@ -1,474 +0,0 @@
-/**
- * Programmatic UI page enumeration — translates "which frontend files changed"
- * into "which URLs should the agent capture blueprints for."
- *
- * Replaces the prose-driven Task 0 strategy ladder in the testbot prompt with
- * deterministic code so the candidate page list lives in the stateFile and is
- * reusable across analyze_changes consumers (testbot, analyze_test_health,
- * future blueprint-grounded recommenders).
- *
- * Strategies, tried in order:
- *
- *   Strategy 1 — Framework route grep
- *     Translate file-system-routed component paths directly to URLs. Covers
- *     Next.js (app/ and pages/), Nuxt / Vue Router file-based, and SvelteKit.
- *     Gated on detection of a framework config file in the repo.
- *
- *   Strategy 1b — Import graph
- *     For a changed file that is not itself a route (a component, a constants
- *     module), map the production files that import it through the same
- *     filesystem-route mapper. Uses the importer list the production-importer integration
- *     check already computed. Merged with strategy 1 rather than tried after it.
- *
- *   Strategy 2 — Source-grounded routes
- *     Walks router/App files with the TS Compiler API for code-defined
- *     route declarations like `<Route path="/cart" element={<Cart/>}>`.
- *     Matches each route's component file OR declaration file against the
- *     changed-file list (so router rewrites surface their routes even when
- *     the component itself is unchanged). Handles React Router string-literal
- *     paths, cross-file constant resolution, Vue Router object literals,
- *     and Directus `defineModule` aggregation. See `sourceRouteExtractor.ts`.
- *
- *   Strategy 3 — Root fallback
- *     Read the workspace's frontend baseUrl and treat it as the single
- *     candidate page. Always available when a frontend service is configured.
- *
- * When no frontend baseUrl can be resolved, strategies 1/1b still run and their
- * results are returned as bare URL paths (`baseUrlResolved: false`) so the agent
- * can prefix the base URL it discovers; strategies 2–3 need a host and are skipped.
- */
-import * as fs from "fs";
-import * as path from "path";
-import { extractDartRoutes } from "./dartRouteExtractor.js";
-import { extractSourceRoutes } from "./sourceRouteExtractor.js";
-import { hasFlutterSdkDep } from "../prompts/test-recommendation/scopeAssessment.js";
-import { readWorkspaceConfigRaw } from "./workspaceAuth.js";
-/**
- * Upper bound on candidate pages. Strategy 1b is bounded by changed files ×
- * importers, and every candidate costs the agent a navigate + a capture, so the
- * list is cut here — direct route matches first, then import-graph pages that
- * render the most changed files.
- */
-export const MAX_CANDIDATE_PAGES = 10;
-// ── Strategy 1: framework route grep ────────────────────────────────────────
-/**
- * File-system → URL mapping for filesystem-routed frameworks.
- *
- * Returns the URL path (no host) when the file is a route entrypoint, or
- * null when the file isn't a route in any recognized convention.
- *
- * The `null` cases include component files used by routes (e.g. shared
- * widgets in `components/`), API handlers (e.g. Next.js `pages/api/*`),
- * and arbitrary `.ts`/`.js` modules under frontend directories. These
- * are picked up by strategy 2 (import-graph walk, future) or by strategy
- * 3 (root fallback).
- */
-export function frameworkFileToUrlPath(filePath) {
-    // Normalize to forward slashes; works on Windows too.
-    const normalized = filePath.replace(/\\/g, "/");
-    // Next.js App Router root: app/page.{tsx,jsx} → /
-    if (/(?:^|\/)app\/page\.(tsx|jsx|ts|js)$/.test(normalized)) {
-        return "/";
-    }
-    // Next.js App Router nested: app/foo/page.tsx → /foo
-    // app/(group)/foo/page.tsx → /foo (route groups stripped in URL)
-    // app/foo/[id]/page.tsx → /foo/:id (Next.js bracket → colon)
-    const nextAppMatch = normalized.match(/(?:^|\/)app\/(.+?)\/page\.(tsx|jsx|ts|js)$/);
-    if (nextAppMatch) {
-        return "/" + stripRouteGroups(nextAppMatch[1]).replace(/\[(\.\.\.)?(\w+)\]/g, ":$2");
-    }
-    // Next.js Pages Router: pages/foo.tsx → /foo, pages/index.tsx → /
-    // Excludes pages/api/* (API handlers) and the framework files _app, _document,
-    // _error (they wrap every page and are not routes of their own).
-    const nextPagesMatch = normalized.match(/(?:^|\/)pages\/(?!api\/)(?!_(?:app|document|error)\.)(.+?)\.(tsx|jsx|ts|js)$/);
-    if (nextPagesMatch) {
-        let urlPath = nextPagesMatch[1];
-        // /index → /, /foo/index → /foo
-        urlPath = urlPath.replace(/(?:^|\/)index$/, "");
-        urlPath = urlPath.replace(/\[(\.\.\.)?(\w+)\]/g, ":$2");
-        return "/" + urlPath;
-    }
-    // Nuxt / Vue Router file-based: pages/foo.vue → /foo
-    // Vue _id.vue → :id (Nuxt 2) or [id].vue → :id (Nuxt 3)
-    const nuxtMatch = normalized.match(/(?:^|\/)pages\/(.+?)\.vue$/);
-    if (nuxtMatch) {
-        let urlPath = nuxtMatch[1];
-        urlPath = urlPath.replace(/(?:^|\/)index$/, "");
-        urlPath = urlPath.replace(/\[(\.\.\.)?(\w+)\]/g, ":$2");
-        urlPath = urlPath.replace(/_(\w+)/g, ":$1");
-        return "/" + urlPath;
-    }
-    // SvelteKit: routes/foo/+page.svelte → /foo, routes/+page.svelte → /
-    const svelteMatch = normalized.match(/(?:^|\/)routes\/(.*?)\+page\.svelte$/);
-    if (svelteMatch) {
-        let urlPath = svelteMatch[1].replace(/\/$/, "");
-        urlPath = urlPath.replace(/\[(\.\.\.)?(\w+)\]/g, ":$2");
-        return "/" + urlPath;
-    }
-    return null;
-}
-/**
- * Drop Next.js App Router route-group segments — `(marketing)/foo` → `foo`.
- * Route groups don't appear in the URL.
- */
-function stripRouteGroups(routePath) {
-    return routePath
-        .split("/")
-        .filter((seg) => !/^\(.+\)$/.test(seg))
-        .join("/");
-}
-/**
- * Detect whether the repository is configured for filesystem-based routing.
- *
- * Strategy 1 maps file paths to URLs based on conventions (Next.js Pages
- * Router, Nuxt, SvelteKit). Without a positive signal that the framework
- * is actually configured, a repo that just *happens* to have a `pages/`
- * directory (e.g. React with conventional layout, Vue with route-config
- * code) produces false-positive URLs. This guard suppresses strategy 1
- * for those repos so they fall through to root-fallback.
- *
- * Looks for framework config files in the repo root, common subdirectories,
- * and the `frontendFiles[]`-derived candidate frontend roots.
- */
-export function detectsFilesystemRouting(repositoryPath) {
-    const FRAMEWORK_CONFIG_FILES = [
-        // Next.js
-        "next.config.js", "next.config.mjs", "next.config.ts",
-        // Nuxt
-        "nuxt.config.ts", "nuxt.config.js",
-        // SvelteKit
-        "svelte.config.js", "svelte.config.ts",
-    ];
-    // Search the repo root and one level deep into common app subdirectories.
-    // Most monorepos place the frontend at apps/web, app/, frontend/, web/, etc.
-    // Going more than one level adds I/O without meaningful coverage gain.
-    const ROOTS_TO_CHECK = [".", "frontend", "web", "app", "client", "apps/web"];
-    for (const root of ROOTS_TO_CHECK) {
-        for (const cfg of FRAMEWORK_CONFIG_FILES) {
-            const fullPath = path.join(repositoryPath, root, cfg);
-            try {
-                if (fs.existsSync(fullPath))
-                    return true;
-            }
-            catch {
-                // ignore — fs errors don't change the answer
-            }
-        }
-    }
-    return false;
-}
-/**
- * Strategies 1 + 1b: map changed route files (1) and the route files that import
- * changed non-route files (1b) to URL paths. Deduped by path; when both name the
- * same path the strategy-1 entry wins and the extra source is appended.
- *
- * Suppressed when the repo doesn't have a recognized filesystem-routing
- * framework config — see `detectsFilesystemRouting`. Without that guard,
- * repos with conventional `pages/` directories but code-defined routes
- * (e.g. React with React Router) produce false-positive URLs.
- */
-function collectRoutePaths(frontendFiles, integration, repositoryPath) {
-    // When repositoryPath is provided, gate on framework detection. When
-    // omitted (e.g. older callers, unit tests), preserve original behavior.
-    if (repositoryPath !== undefined && !detectsFilesystemRouting(repositoryPath)) {
-        return [];
-    }
-    const byPath = new Map();
-    const add = (urlPath, sourceFile, strategy, via) => {
-        const existing = byPath.get(urlPath);
-        if (existing) {
-            // Same path surfaced by multiple files — track all sources.
-            if (!existing.sourcedFrom.includes(sourceFile))
-                existing.sourcedFrom.push(sourceFile);
-            if (via && existing.via && !existing.via.includes(via))
-                existing.via.push(via);
-        }
-        else {
-            byPath.set(urlPath, { path: urlPath, sourcedFrom: [sourceFile], strategy, ...(via ? { via: [via] } : {}) });
-        }
-    };
-    for (const file of frontendFiles) {
-        const urlPath = frameworkFileToUrlPath(file);
-        if (urlPath !== null)
-            add(urlPath, file, "framework-route-grep");
-    }
-    for (const entry of integration ?? []) {
-        if (!entry.integrated)
-            continue;
-        for (const importer of entry.importers) {
-            const urlPath = frameworkFileToUrlPath(importer);
-            if (urlPath !== null)
-                add(urlPath, entry.file, "import-graph", importer);
-        }
-    }
-    const all = Array.from(byPath.values());
-    const rank = (c) => (c.strategy === "framework-route-grep" ? 1 : 0) * 1000 + c.sourcedFrom.length;
-    return all.sort((a, b) => rank(b) - rank(a)).slice(0, MAX_CANDIDATE_PAGES);
-}
-function joinBaseUrl(baseUrl, candidate) {
-    return {
-        url: baseUrl.replace(/\/$/, "") + candidate.path,
-        sourcedFrom: candidate.sourcedFrom,
-        strategy: candidate.strategy,
-        ...(candidate.via ? { via: candidate.via } : {}),
-    };
-}
-/** Strategy 1 only (no import graph), joined to `baseUrl`. */
-export function findCandidatePagesByFrameworkRoute(frontendFiles, baseUrl, repositoryPath) {
-    return collectRoutePaths(frontendFiles, undefined, repositoryPath).map((c) => joinBaseUrl(baseUrl, c));
-}
-// ── Strategy 2: source-grounded routes ──────────────────────────────────────
-/**
- * Strategy 2 implementation. Walks router/App files with the TS Compiler API
- * to find route declarations (`<Route path="/cart" element={<Cart/>}>`),
- * matches each declaration's component file against the changed-file list,
- * and emits one CandidateUiPage per matching route.
- *
- * Slice 3a covers string-literal `path` attributes only — `path={CONST}` and
- * Vue Router object literals are deferred to slice 3b.
- *
- * Returns empty when no route declarations match the changed files (which is
- * also the right answer for SPAs without client-side routing — they fall
- * through to root-fallback).
- */
-export function findCandidatePagesBySourceRoute(frontendFiles, baseUrl, repositoryPath) {
-    const sourceRoutes = extractSourceRoutes(repositoryPath);
-    if (sourceRoutes.length === 0)
-        return [];
-    // Normalize changed files to absolute paths once.
-    const changedAbs = new Set(frontendFiles.map((f) => path.resolve(repositoryPath, f)));
-    const normalizedBase = baseUrl.replace(/\/$/, "");
-    const byUrl = new Map();
-    for (const route of sourceRoutes) {
-        // A route surfaces as a candidate when *either* its component file or its
-        // declaring file (router.ts, modules/<x>/index.ts) appears in the diff.
-        // Component-only matching misses route renames in the declaration file
-        // (the declaration changed; the component is unchanged).
-        const matchedBy = (route.componentFile && changedAbs.has(route.componentFile))
-            ? route.componentFile
-            : (route.declaredIn && changedAbs.has(route.declaredIn))
-                ? route.declaredIn
-                : null;
-        if (matchedBy === null)
-            continue;
-        const fullUrl = normalizedBase + (route.path.startsWith("/") ? route.path : "/" + route.path);
-        const sourceFile = path.relative(repositoryPath, matchedBy);
-        const existing = byUrl.get(fullUrl);
-        if (existing) {
-            if (!existing.sourcedFrom.includes(sourceFile)) {
-                existing.sourcedFrom.push(sourceFile);
-            }
-        }
-        else {
-            byUrl.set(fullUrl, {
-                url: fullUrl,
-                sourcedFrom: [sourceFile],
-                strategy: "source-grounded-routes",
-            });
-        }
-    }
-    return Array.from(byUrl.values());
-}
-// ── Strategy 2.5: Dart GoRouter routes ─────────────────────────────────────
-/**
- * Strategy 2.5: walk the repo's Dart files for GoRoute(path: '...') calls.
- * Gated on `hasFlutterSdkDep(repoPath)` so non-Flutter Dart projects (e.g.
- * shelf_router servers) don't accidentally emit URLs.
- *
- * Diff-matching: each GoRoute references its screen widget via
- * `builder:`/`pageBuilder:` (e.g. `AuthorsScreen`). The extractor resolves
- * those identifiers through the route file's imports to absolute screen
- * file paths. We surface only routes whose screen file appears in the
- * changed-file list. Falls back to all-routes when no route's screen
- * file matches — preserves coverage for "router untouched, screen edited"
- * cases when the import-resolution heuristic doesn't find a match.
- *
- * Filters applied:
- *   1. Drop redirect-only routes (`redirect:` with no `builder:`/`pageBuilder:`).
- *      These have no UI to render — navigating there is wasted work.
- *   2. Drop nested relative children (paths that don't start with `/`).
- *      Without parent-path composition the URL is meaningless.
- *
- * Returns empty when the repo isn't Flutter or no GoRoute calls are
- * found — caller falls through to root-fallback.
- */
-export function findCandidatePagesByDartRoute(repositoryPath, baseUrl, frontendFiles) {
-    if (!hasFlutterSdkDep(repositoryPath))
-        return [];
-    const dartRoutes = extractDartRoutes(repositoryPath);
-    if (dartRoutes.length === 0)
-        return [];
-    // Strip redirect-only and relative routes — they're never valid candidates.
-    const renderable = dartRoutes.filter((r) => !r.isRedirectOnly && r.path.startsWith("/"));
-    if (renderable.length === 0)
-        return [];
-    // Diff-match each route against frontendFiles via its screenFiles.
-    const changedAbs = new Set(frontendFiles.map((f) => path.resolve(repositoryPath, f)));
-    const matched = renderable.filter((r) => r.screenFiles.some((sf) => changedAbs.has(sf)));
-    // Fall back to all renderable routes when nothing diff-matches. The
-    // import-resolution heuristic isn't perfect (custom widget naming, multiple
-    // screens per file, factory functions); a zero-match should not collapse
-    // the candidate list to empty when the repo clearly has UI changes.
-    const surfaced = matched.length > 0 ? matched : renderable;
-    const normalizedBase = baseUrl.replace(/\/$/, "");
-    const byUrl = new Map();
-    for (const route of surfaced) {
-        const fullUrl = normalizedBase + route.path;
-        const sourceFile = path.relative(repositoryPath, route.declaredIn);
-        const existing = byUrl.get(fullUrl);
-        if (existing) {
-            if (!existing.sourcedFrom.includes(sourceFile)) {
-                existing.sourcedFrom.push(sourceFile);
-            }
-        }
-        else {
-            byUrl.set(fullUrl, {
-                url: fullUrl,
-                sourcedFrom: [sourceFile],
-                strategy: "dart-go-router",
-            });
-        }
-    }
-    return Array.from(byUrl.values());
-}
-// ── Strategy 3: root fallback ───────────────────────────────────────────────
-/**
- * Strategy 3: when strategies 1+2 yield nothing, fall back to the workspace's
- * frontend baseUrl as the single candidate page. The agent's downstream
- * explore-and-discover step can then surface gated UI from the root.
- *
- * Returns null when the workspace has no recognizable frontend service.
- */
-export async function findRootFallbackPage(repositoryPath) {
-    const baseUrl = await pickFrontendBaseUrl(repositoryPath);
-    return baseUrl ? rootFallbackPage(baseUrl) : null;
-}
-function rootFallbackPage(baseUrl) {
-    return { url: baseUrl, sourcedFrom: [], strategy: "root-fallback" };
-}
-/**
- * Mirror of testbot.git src/services.ts exportServiceBaseUrlEnvVars sanitize().
- * Keep in sync with that function (separate repo, cannot share code).
- *
- * Transforms a service name into the corresponding env var suffix:
- * `supabase-nextjs` → `SUPABASE_NEXTJS`
- * `my.app` → `MY_APP`
- * `proto://app` → `PROTO___APP`
- */
-function sanitizeServiceName(name) {
-    return name.toUpperCase().replace(/[-.:\/]/g, "_");
-}
-/**
- * Extracted from pickFrontendBaseUrl: returns the chosen frontend service
- * object (not the URL). Implements the original heuristics unchanged.
- *
- * Heuristics, in order:
- *   1. Service whose `serviceName` contains a frontend token (`frontend`,
- *      `ui`, `app`, or `web`) as a `-`/`_`-delimited word
- *   2. Service whose `language` is `typescript` / `javascript` AND whose
- *      `framework` is one of the common UI frameworks (react, vue, svelte,
- *      next, nuxt, etc.)
- *   3. First service with a defined `api.baseUrl`
- *
- * Returns the service object or null when no service has a usable URL.
- */
-function pickFrontendService(services) {
-    // Heuristic 1: serviceName signals frontend.
-    const byName = services.find((s) => typeof s?.serviceName === "string" &&
-        /(?:^|[-_])frontend(?:[-_]|$)|(?:^|[-_])ui(?:[-_]|$)|(?:^|[-_])app(?:[-_]|$)|(?:^|[-_])web(?:[-_]|$)/.test(s.serviceName.toLowerCase()) &&
-        s?.api?.baseUrl);
-    if (byName)
-        return byName;
-    // Heuristic 2: language + framework signal frontend.
-    const FRONTEND_FRAMEWORKS = new Set([
-        "react", "vue", "svelte", "next", "nextjs", "nuxt", "sveltekit",
-        "angular", "solid", "qwik", "remix", "astro",
-    ]);
-    const byFramework = services.find((s) => {
-        const lang = (s?.language ?? "").toLowerCase();
-        const fw = (s?.framework ?? "").toLowerCase();
-        return ((lang === "typescript" || lang === "javascript") &&
-            FRONTEND_FRAMEWORKS.has(fw) &&
-            s?.api?.baseUrl);
-    });
-    if (byFramework)
-        return byFramework;
-    // Heuristic 3: first service with a baseUrl.
-    const anyBase = services.find((s) => s?.api?.baseUrl);
-    return anyBase ?? null;
-}
-/**
- * Resolves the frontend service's baseUrl from the workspace config.
- *
- * Returns the baseUrl string with environment variable override precedence:
- *   1. Per-service override: `SKYRAMP_TEST_SERVICE_URL_<NAME>` (where <NAME>
- *      is the picked frontend service's serviceName, sanitized via
- *      `sanitizeServiceName`)
- *   2. Global override: `SKYRAMP_TEST_BASE_URL` (single service or all
- *      services share one URL). Also honored when the workspace declares no
- *      services at all — the action can know the URL without a workspace entry.
- *   3. Static workspace.yml value: `api.baseUrl` from the picked frontend
- *      service
- *
- * Returns null when neither the environment nor any service has a usable URL.
- *
- * Exported (vs private) so analyze_changes and future tools can reuse the
- * same selection without re-implementing it.
- */
-export async function pickFrontendBaseUrl(repositoryPath) {
-    const config = await readWorkspaceConfigRaw(repositoryPath);
-    const global = process.env.SKYRAMP_TEST_BASE_URL?.trim();
-    if (!config?.services || !Array.isArray(config.services))
-        return global || null;
-    const picked = pickFrontendService(config.services);
-    // 1. Per-service override (multi-service, distinct URLs).
-    // readWorkspaceConfigRaw may fall back to unvalidated YAML, so serviceName
-    // is not guaranteed to be a string — guard before sanitizing.
-    if (typeof picked?.serviceName === "string") {
-        const perSvc = process.env[`SKYRAMP_TEST_SERVICE_URL_${sanitizeServiceName(picked.serviceName)}`]?.trim();
-        if (perSvc)
-            return perSvc;
-    }
-    // 2. Global override (single service / all services share a URL).
-    if (global)
-        return global;
-    // 3. Static workspace.yml value.
-    return picked?.api?.baseUrl ?? null;
-}
-// ── Composer ────────────────────────────────────────────────────────────────
-/**
- * Run the strategy ladder: framework route grep + import graph (1/1b) →
- * source-grounded routes (2) → Dart GoRouter (2.5) → root fallback (3). Each
- * later strategy is consulted only if the earlier ones produced no candidates.
- *
- * `integration` is the production-importer check for the same files; when given,
- * changed non-route files resolve to the pages that import them.
- *
- * Without a resolvable frontend baseUrl only strategies 1/1b can run; their
- * paths are returned with `baseUrlResolved: false` for the agent to prefix.
- * Returns empty only when nothing resolves at all.
- */
-export async function enumerateCandidateUiPages(repositoryPath, frontendFiles, integration) {
-    if (frontendFiles.length === 0)
-        return [];
-    const baseUrl = await pickFrontendBaseUrl(repositoryPath);
-    const routePaths = collectRoutePaths(frontendFiles, integration, repositoryPath);
-    if (!baseUrl) {
-        return routePaths.map((c) => ({
-            url: c.path,
-            sourcedFrom: c.sourcedFrom,
-            strategy: c.strategy,
-            baseUrlResolved: false,
-            ...(c.via ? { via: c.via } : {}),
-        }));
-    }
-    if (routePaths.length > 0)
-        return routePaths.map((c) => joinBaseUrl(baseUrl, c));
-    const fromSource = findCandidatePagesBySourceRoute(frontendFiles, baseUrl, repositoryPath);
-    if (fromSource.length > 0)
-        return fromSource;
-    const fromDart = findCandidatePagesByDartRoute(repositoryPath, baseUrl, frontendFiles);
-    if (fromDart.length > 0)
-        return fromDart;
-    return [rootFallbackPage(baseUrl)];
-}