@skyramp/mcp 0.3.0-rc.1 → 0.3.0

package/build/utils/repoScanner.js

@@ -1,29 +1,12 @@
 import * as fs from "fs";
 import * as path from "path";
 import { nextjsFileToApiPath, parseFileEndpoints, } from "./routeParsers.js";
+import { resolvePythonMountPrefixes } from "./pythonMountPrefixes.js";
+import { walkSourceFiles } from "./fileWalk.js";
 import { logger } from "./logger.js";
+const GLOB_SKIP_DIRS = new Set(["node_modules", ".git", ".next", "dist", "build"]);
 function globRecursive(dir, extensions) {
-    const results = [];
-    let entries;
-    try {
-        entries = fs.readdirSync(dir, { withFileTypes: true });
-    }
-    catch (err) {
-        logger.debug("globRecursive: skipping directory", { dir, error: err instanceof Error ? err.message : String(err) });
-        return results;
-    }
-    for (const entry of entries) {
-        const fullPath = path.join(dir, entry.name);
-        if (entry.isDirectory()) {
-            if (entry.name === "node_modules" || entry.name === ".git" || entry.name === ".next" || entry.name === "dist" || entry.name === "build")
-                continue;
-            results.push(...globRecursive(fullPath, extensions));
-        }
-        else if (extensions.some((ext) => entry.name.endsWith(ext))) {
-            results.push(fullPath);
-        }
-    }
-    return results;
+    return walkSourceFiles(dir, { extensions, skipDirs: GLOB_SKIP_DIRS });
 }
 function safeReadFile(filePath) {
     try {
@@ -231,8 +214,28 @@ export function findCandidateRouteFiles(repositoryPath) {
     }
     return result;
 }
+/**
+ * Cross-file FastAPI mount-prefix lookup, resolved lazily: `resolvePythonMountPrefixes`
+ * walks the whole repo's Python, so it's only invoked the first time a `.py` file is
+ * actually scanned — non-Python repos pay nothing. Returns undefined for non-`.py`
+ * files (they never carry Python mount prefixes).
+ */
+function makeMountPrefixLookup(repositoryPath) {
+    let resolved = null;
+    return (relative) => {
+        if (!relative.endsWith(".py"))
+            return undefined;
+        if (resolved === null)
+            resolved = resolvePythonMountPrefixes(repositoryPath);
+        return resolved.get(relative.replace(/\\/g, "/"));
+    };
+}
 export function scanAllRepoEndpoints(repositoryPath) {
+    // Normalize up-front so relative-path derivation (and mount-prefix lookups) don't
+    // depend on a caller-supplied trailing separator.
+    repositoryPath = path.resolve(repositoryPath);
     const endpointMap = new Map();
+    const mountPrefixFor = makeMountPrefixLookup(repositoryPath);
     const sourceFiles = globRecursive(repositoryPath, [".ts", ".tsx", ".js", ".jsx", ".py", ".java", ".kt", ".go", ".rb", ".php", ".rs", ".cs"]);
     for (const file of sourceFiles) {
         if (scanNextjsFile(file, repositoryPath, endpointMap))
@@ -244,7 +247,7 @@ export function scanAllRepoEndpoints(repositoryPath) {
         const content = safeReadFile(file);
         if (content === null)
             continue;
-        for (const ep of parseFileEndpoints(content, relative)) {
+        for (const ep of parseFileEndpoints(content, relative, mountPrefixFor(relative))) {
             addEndpointToMap(endpointMap, ep.path, ep.method, file, repositoryPath, ep.line);
         }
     }
@@ -256,6 +259,7 @@ export function scanAllRepoEndpoints(repositoryPath) {
     }));
 }
 export function scanRelatedEndpoints(repositoryPath, changedFiles) {
+    repositoryPath = path.resolve(repositoryPath);
     const relatedDirs = new Set();
     for (const f of changedFiles) {
         const absDir = path.dirname(path.join(repositoryPath, f));
@@ -265,6 +269,9 @@ export function scanRelatedEndpoints(repositoryPath, changedFiles) {
             relatedDirs.add(parentDir);
     }
     const endpointMap = new Map();
+    // Mount prefixes are resolved over the whole repo (aggregators may live outside
+    // the related dirs) but lazily — only once a Python file is actually scanned.
+    const mountPrefixFor = makeMountPrefixLookup(repositoryPath);
     for (const dir of relatedDirs) {
         if (!fs.existsSync(dir))
             continue;
@@ -279,7 +286,7 @@ export function scanRelatedEndpoints(repositoryPath, changedFiles) {
             const fileContent = safeReadFile(file);
             if (fileContent === null)
                 continue;
-            for (const ep of parseFileEndpoints(fileContent, relative)) {
+            for (const ep of parseFileEndpoints(fileContent, relative, mountPrefixFor(relative))) {
                 addEndpointToMap(endpointMap, ep.path, ep.method, file, repositoryPath, ep.line);
             }
         }

package/build/utils/repoScanner.test.js

@@ -89,4 +89,102 @@ async def bulk_delete_deployments(): pass
             { path: "/bulk_delete", methods: ["POST"], sourceFile: "src/prefect/server/api/flows.py" },
         ]));
     });
+    // FastAPI composes a route's full URL from prefixes applied at include_router()
+    // mount points that live in *other* files — the single-file parser can't see
+    // them. Mealie mounts its whole API under a top-level APIRouter(prefix="/api"),
+    // so a leaf router's own prefix ("/recipes") must be composed with the ancestor
+    // "/api" or generated tests hit the un-prefixed URL and 405.
+    it("composes cross-file include_router mount prefixes into FastAPI route paths", () => {
+        const repo = makeTempRepo();
+        const routesDir = path.join(repo, "mealie/routes");
+        const recipeDir = path.join(routesDir, "recipe");
+        fs.mkdirSync(recipeDir, { recursive: true });
+        // Top-level app: mounts the API router with no extra prefix.
+        fs.writeFileSync(path.join(repo, "mealie/app.py"), `
+from fastapi import FastAPI
+from mealie.routes import router
+
+app = FastAPI()
+app.include_router(router)
+`);
+        // API aggregator: APIRouter(prefix="/api") includes each resource router.
+        fs.writeFileSync(path.join(routesDir, "__init__.py"), `
+from fastapi import APIRouter
+from . import recipe
+
+router = APIRouter(prefix="/api")
+router.include_router(recipe.router)
+`);
+        // Recipe aggregator: no own prefix; mounts the CRUD router directly and the
+        // comments router under a "/recipes" mount prefix drawn from a local const.
+        fs.writeFileSync(path.join(recipeDir, "__init__.py"), `
+from fastapi import APIRouter
+from . import recipe_crud_routes, comments
+
+prefix = "/recipes"
+
+router = APIRouter()
+router.include_router(recipe_crud_routes.router, tags=["Recipe: CRUD"])
+router.include_router(comments.router, prefix=prefix, tags=["Recipe: Comments"])
+`);
+        // Leaf CRUD router declared via a custom APIRouter *subclass* with its own
+        // "/recipes" prefix.
+        fs.writeFileSync(path.join(recipeDir, "recipe_crud_routes.py"), `
+from mealie.routes._base.routers import UserAPIRouter
+
+router = UserAPIRouter(prefix="/recipes")
+
+@router.get("")
+async def get_all(): pass
+
+@router.get("/{slug}")
+async def get_one(): pass
+`);
+        // Comments router: no own prefix — its "/recipes" comes only from the mount.
+        fs.writeFileSync(path.join(recipeDir, "comments.py"), `
+from fastapi import APIRouter
+
+router = APIRouter()
+
+@router.get("/{slug}/comments")
+async def get_comments(): pass
+`);
+        const endpoints = scanAllRepoEndpoints(repo);
+        // CRUD: /api (aggregator) + /recipes (leaf subclass own prefix)
+        expect(endpoints).toEqual(expect.arrayContaining([
+            expect.objectContaining({ path: "/api/recipes", methods: ["GET"], sourceFile: "mealie/routes/recipe/recipe_crud_routes.py" }),
+            expect.objectContaining({ path: "/api/recipes/{slug}", methods: ["GET"], sourceFile: "mealie/routes/recipe/recipe_crud_routes.py" }),
+        ]));
+        // Comments: /api (aggregator) + /recipes (mount prefix from a local const) + own path
+        expect(endpoints).toEqual(expect.arrayContaining([
+            expect.objectContaining({ path: "/api/recipes/{slug}/comments", methods: ["GET"], sourceFile: "mealie/routes/recipe/comments.py" }),
+        ]));
+        // The un-prefixed path must NOT appear (the 405 bug).
+        expect(endpoints).not.toContainEqual(expect.objectContaining({ path: "/recipes" }));
+    });
+    it("composes an app-level include_router(prefix=...) mount", () => {
+        const repo = makeTempRepo();
+        const apiDir = path.join(repo, "src/api");
+        fs.mkdirSync(apiDir, { recursive: true });
+        // Prefix applied at the app mount point rather than on the APIRouter itself.
+        fs.writeFileSync(path.join(repo, "src/main.py"), `
+from fastapi import FastAPI
+from src.api.users import router as users_router
+
+app = FastAPI()
+app.include_router(users_router, prefix="/api/v1")
+`);
+        fs.writeFileSync(path.join(apiDir, "users.py"), `
+from fastapi import APIRouter
+
+router = APIRouter(prefix="/users")
+
+@router.get("/{id}")
+async def get_user(): pass
+`);
+        const endpoints = scanAllRepoEndpoints(repo);
+        expect(endpoints).toEqual(expect.arrayContaining([
+            expect.objectContaining({ path: "/api/v1/users/{id}", methods: ["GET"], sourceFile: "src/api/users.py" }),
+        ]));
+    });
 });

package/build/utils/routeParsers.d.ts

@@ -27,8 +27,14 @@ export declare function parseRouteLine(line: string, sourceFile: string): Parsed
  *
  * Falls back to pure parseRouteLine for all other frameworks (Express inline, Gin,
  * Rails, Laravel, Actix, Hapi, Go stdlib, etc.), which remain unaffected.
+ *
+ * `mountPrefixes` optionally supplies, per router variable, the **ancestor**
+ * prefix that router inherits from cross-file `include_router(...)` mount points
+ * (see `resolvePythonMountPrefixes`). It is composed *ahead* of the router's own
+ * in-file prefix, so a `router = APIRouter(prefix="/recipes")` mounted under an
+ * aggregator's `APIRouter(prefix="/api")` yields `/api/recipes`, not `/recipes`.
  */
-export declare function parseFileEndpoints(content: string, sourceFile: string): ParsedDiffEndpoint[];
+export declare function parseFileEndpoints(content: string, sourceFile: string, mountPrefixes?: Map<string, string>): ParsedDiffEndpoint[];
 export declare const SKIP_PATH_SEGMENTS: Set<string>;
 /**
  * True for version/prefix path segments — "v1".."v99" and the literal "api".

package/build/utils/routeParsers.js

@@ -1,3 +1,4 @@
+import { joinRoutePrefix } from "./pythonMountPrefixes.js";
 import { logger } from "./logger.js";
 export function nextjsFileToApiPath(filePath) {
     const pagesMatch = filePath.match(/(?:^|\/)pages\/(api\/.+)\.[jt]sx?$/);
@@ -183,13 +184,29 @@ export function parseRouteLine(line, sourceFile) {
  *
  * Falls back to pure parseRouteLine for all other frameworks (Express inline, Gin,
  * Rails, Laravel, Actix, Hapi, Go stdlib, etc.), which remain unaffected.
+ *
+ * `mountPrefixes` optionally supplies, per router variable, the **ancestor**
+ * prefix that router inherits from cross-file `include_router(...)` mount points
+ * (see `resolvePythonMountPrefixes`). It is composed *ahead* of the router's own
+ * in-file prefix, so a `router = APIRouter(prefix="/recipes")` mounted under an
+ * aggregator's `APIRouter(prefix="/api")` yields `/api/recipes`, not `/recipes`.
  */
-export function parseFileEndpoints(content, sourceFile) {
+export function parseFileEndpoints(content, sourceFile, mountPrefixes) {
     const results = [];
     let classPrefix = ""; // active prefix for the current class body
     let pendingPrefix = ""; // set by class-level annotation; activated on class declaration
     // FastAPI APIRouter / Flask Blueprint: variable name → prefix
     const routerPrefixes = new Map();
+    // Effective prefix for a router var = its cross-file ancestor mount prefix
+    // composed with its own in-file APIRouter(prefix=…). Returns undefined when
+    // the var has neither, so callers leave the path untouched.
+    const effectivePrefix = (varName) => {
+        const own = routerPrefixes.get(varName);
+        const mount = mountPrefixes?.get(varName);
+        if (own === undefined && mount === undefined)
+            return undefined;
+        return joinRoutePrefix(mount ?? "", own ?? "");
+    };
     let pendingRouterVar = ""; // variable name being accumulated in a multi-line declaration
     let pendingPythonDecorator = null;
     let pendingExpressMethod = ""; // HTTP method from a multi-line Express route (e.g. "POST" from `router.post(\n`)
@@ -254,15 +271,16 @@ export function parseFileEndpoints(content, sourceFile) {
                 }
                 continue;
             }
-            // Single-line: varName = APIRouter(prefix="/path") or APIRouter(tags=..., prefix="/path")
-            const singleM = trimmed.match(/^(\w+)\s*=\s*APIRouter\s*\([^)]*prefix\s*=\s*["']([^"'?#]+)["']/) ||
+            // Single-line: varName = APIRouter(prefix="/path") or APIRouter(tags=..., prefix="/path").
+            // `\w*APIRouter` also matches custom subclasses (e.g. Mealie's UserAPIRouter).
+            const singleM = trimmed.match(/^(\w+)\s*=\s*\w*APIRouter\s*\([^)]*prefix\s*=\s*["']([^"'?#]+)["']/) ||
                 trimmed.match(/^(\w+)\s*=\s*Blueprint\s*\([^)]*url_prefix\s*=\s*["']([^"'?#]+)["']/);
             if (singleM) {
                 routerPrefixes.set(singleM[1], singleM[2]);
                 continue;
             }
             // Multi-line open: varName = APIRouter( or Blueprint( without closing ) on this line
-            if (/^(\w+)\s*=\s*(?:APIRouter|Blueprint)\s*\(/.test(trimmed) && !trimmed.includes(")")) {
+            if (/^(\w+)\s*=\s*(?:\w*APIRouter|Blueprint)\s*\(/.test(trimmed) && !trimmed.includes(")")) {
                 const openM = trimmed.match(/^(\w+)/);
                 if (openM)
                     pendingRouterVar = openM[1];
@@ -278,15 +296,13 @@ export function parseFileEndpoints(content, sourceFile) {
             const pathMatch = trimmed.match(/^(?:path\s*=\s*)?["']([^"'?#]*)/) ||
                 trimmed.match(/^value\s*=\s*["']([^"'?#]*)/);
             if (pathMatch) {
-                const routerPrefix = routerPrefixes.get(pendingPythonDecorator.routerVar);
-                const prefix = routerPrefix?.replace(/\/$/, "");
-                const suffix = pathMatch[1].replace(/^\//, "");
-                const path = prefix
-                    ? (suffix ? `${prefix}/${suffix}` : prefix)
+                const eff = effectivePrefix(pendingPythonDecorator.routerVar);
+                const composedPath = eff !== undefined
+                    ? joinRoutePrefix(eff, pathMatch[1])
                     : pathMatch[1];
                 results.push({
                     method: pendingPythonDecorator.method,
-                    path,
+                    path: composedPath,
                     sourceFile,
                     line: pendingPythonDecorator.startLine,
                 });
@@ -448,17 +464,15 @@ export function parseFileEndpoints(content, sourceFile) {
                 ep.path = `${prefix}/${suffix}`;
             }
         }
-        else if (routerPrefixes.size > 0) {
-            // Router-variable prefix (FastAPI, Flask Blueprint)
+        else if (routerPrefixes.size > 0 || (mountPrefixes && mountPrefixes.size > 0)) {
+            // Router-variable prefix (FastAPI, Flask Blueprint) — own prefix composed
+            // with any cross-file ancestor mount prefix.
             const varM = trimmed.match(/@(\w+)\.(get|post|put|patch|delete|head|options)\s*\(/i)
                 || trimmed.match(/@(\w+)\.route\s*\(/i);
             if (varM) {
-                const routerPrefix = routerPrefixes.get(varM[1]);
-                if (routerPrefix) {
-                    const prefix = routerPrefix.replace(/\/$/, "");
-                    const suffix = ep.path.replace(/^\//, "");
-                    ep.path = suffix ? `${prefix}/${suffix}` : prefix;
-                }
+                const eff = effectivePrefix(varM[1]);
+                if (eff !== undefined)
+                    ep.path = joinRoutePrefix(eff, ep.path);
             }
         }
         ep.line = lineNo;

package/build/utils/sourceRouteExtractor.js

@@ -30,6 +30,7 @@
 import * as fs from "fs";
 import * as path from "path";
 import * as ts from "typescript";
+import { collectFiles } from "./fileWalk.js";
 function makeParseCache() {
     return { files: new Map(), tsconfigBaseUrl: new Map() };
 }
@@ -123,49 +124,25 @@ function parseFile(filePath, cache) {
 }
 // ── File discovery ────────────────────────────────────────────────────────
 function findRouterFiles(repoPath) {
-    const matches = [];
     const targets = new Set(ROUTER_FILE_GLOBS.map((g) => g.toLowerCase()));
     const indexExtensions = new Set([".ts", ".tsx", ".js", ".jsx"]);
-    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()) {
-                const lower = entry.name.toLowerCase();
-                if (targets.has(lower)) {
-                    matches.push(full);
-                    continue;
-                }
-                // Directus-style modules: `…/modules/<name>/index.{ts,tsx,js,jsx}`
-                // hosts a `defineModule({ routes: [...] })` call.
-                if (lower.startsWith("index.")) {
-                    const ext = path.extname(lower);
-                    if (indexExtensions.has(ext) && full.includes(`${path.sep}modules${path.sep}`)) {
-                        matches.push(full);
-                    }
-                }
+    return collectFiles(repoPath, {
+        match: (entry, full) => {
+            const lower = entry.name.toLowerCase();
+            if (targets.has(lower))
+                return true;
+            // Directus-style modules: `…/modules/<name>/index.{ts,tsx,js,jsx}`
+            // hosts a `defineModule({ routes: [...] })` call.
+            if (lower.startsWith("index.")) {
+                const ext = path.extname(lower);
+                return indexExtensions.has(ext) && full.includes(`${path.sep}modules${path.sep}`);
             }
-        }
-    }
-    walk(repoPath, 0);
-    return matches;
+            return false;
+        },
+        limit: MAX_CANDIDATE_FILES,
+        maxDepth: MAX_WALK_DEPTH,
+        shouldSkipDir: (entry) => SKIP_DIRS.has(entry.name) || entry.name.startsWith("."),
+    });
 }
 // ── Per-file extraction ────────────────────────────────────────────────────
 function extractRoutesFromFile(filePath, cache) {

package/build/utils/trace-parser.js

@@ -5,6 +5,7 @@
 import * as fs from "fs";
 import * as path from "path";
 import { KNOWN_AUTH_HEADERS } from "./workspaceAuth.js";
+import { walkDir } from "./fileWalk.js";
 const FLOW_GAP_MS = 30_000;
 // Redact-only headers: scrub these from traces but don't treat them as extractable auth headers.
 // set-cookie carries session tokens; auth-token / client-secret / access-token are generic secrets.
@@ -168,27 +169,14 @@ const SKIP_DIRS = new Set(["node_modules", ".git", "dist", "build", ".next", ".n
 /** Known test-artifact directories where testbot-generated traces are written. */
 const TRACE_SCAN_DIRS = [".skyramp", "tests", "test", "e2e", "playwright"];
 /**
- * Recursively scan a directory for files matching a predicate, up to maxDepth levels.
+ * Recursively scan a directory for files matching a predicate, up to maxDepth
+ * levels below `dir` (maxDepth 0 = only files directly in `dir`).
  */
 function scanDir(dir, predicate, maxDepth, results) {
-    if (maxDepth < 0)
-        return;
-    let entries;
-    try {
-        entries = fs.readdirSync(dir, { withFileTypes: true });
-    }
-    catch {
-        return;
-    }
-    for (const entry of entries) {
-        if (entry.isDirectory()) {
-            if (!SKIP_DIRS.has(entry.name)) {
-                scanDir(path.join(dir, entry.name), predicate, maxDepth - 1, results);
-            }
-        }
-        else if (entry.isFile() && predicate(entry.name)) {
-            results.push(path.join(dir, entry.name));
-        }
+    const opts = { maxDepth, shouldSkipDir: (entry) => SKIP_DIRS.has(entry.name) };
+    for (const [entry, full] of walkDir(dir, opts)) {
+        if (predicate(entry.name))
+            results.push(full);
     }
 }
 /**

package/build/utils/versions.d.ts

@@ -1,3 +1,3 @@
-export declare const SKYRAMP_IMAGE_VERSION = "v1.3.33";
-export declare const EXECUTOR_DOCKER_IMAGE = "skyramp/executor:v1.3.33";
-export declare const WORKER_DOCKER_IMAGE = "skyramp/worker:v1.3.33";
+export declare const SKYRAMP_IMAGE_VERSION = "v1.3.34";
+export declare const EXECUTOR_DOCKER_IMAGE = "skyramp/executor:v1.3.34";
+export declare const WORKER_DOCKER_IMAGE = "skyramp/worker:v1.3.34";

package/build/utils/versions.js

@@ -1,3 +1,3 @@
-export const SKYRAMP_IMAGE_VERSION = "v1.3.33";
+export const SKYRAMP_IMAGE_VERSION = "v1.3.34";
 export const EXECUTOR_DOCKER_IMAGE = `skyramp/executor:${SKYRAMP_IMAGE_VERSION}`;
 export const WORKER_DOCKER_IMAGE = `skyramp/worker:${SKYRAMP_IMAGE_VERSION}`;

package/build/utils/walkerCharacterization.test.d.ts

@@ -0,0 +1 @@
+export {};