@skyramp/mcp 0.3.0-rc.1 → 0.3.0

package/build/tools/test-management/analyzeChangesTool.js

@@ -23,7 +23,8 @@ import { classifyUnmatchedFilesByPathAffinity } from "../../utils/pathAffinityCl
 import { scanAllRepoEndpoints, scanRelatedEndpoints, grepRouterMountingContext, findCandidateRouteFiles, } from "../../utils/repoScanner.js";
 import { detectProjectMetadata } from "../../utils/projectMetadata.js";
 import { draftScenariosFromEndpoints, draftResponseShapeScenarios, capScenarios } from "../../utils/scenarioDrafting.js";
-import { mapUnmatchedFilesToImporterEndpoints, buildHopResponseShapeInputs } from "../../utils/importerHop.js";
+import { mapUnmatchedFilesToImporterEndpoints, buildHopResponseShapeInputs, deriveResourceTokensForFile, deriveResourceToken, extractChangedSymbols, sliceDiffByFile } from "../../utils/importerHop.js";
+import { extractChangedSelectors, MAX_CHANGED_SELECTORS } from "../../utils/frontendSelectors.js";
 import { buildAnalysisOutputText } from "../../prompts/test-recommendation/analysisOutputPrompt.js";
 import { parseTraceFile, discoverTraceFiles, discoverPlaywrightZips, } from "../../utils/trace-parser.js";
 import { TestSource } from "../../types/TestAnalysis.js";
@@ -613,19 +614,114 @@ export function registerAnalyzeChangesTool(server) {
             });
             // PR mode → [] excludes external tests from pre-loading (agent discovers via grep).
             // No diff context → undefined triggers full-repo mode in TestDiscoveryService.
-            const changedResources = classifiedEndpoints ? [] : undefined;
+            // SKYR-3924: a diff that changed NO endpoints but did change schema/model/DTO files
+            // yields no endpoint signal, so external tests would be skipped entirely and the
+            // breaking existing tests never enter the maintenance scope. Derive resource tokens
+            // from the changed files via the shared importer-hop derivation and use them, so
+            // discoverTests partitions and PRE-LOADS the relevant existing tests.
+            // Per-file diff slices — lazily computed once and shared by the changedSymbols
+            // (SKYR-3924) and changedSelectors (UI promotion pass 3) derivations below, so a diff
+            // that triggers both isn't sliced twice.
+            let _diffByFile = null;
+            const getDiffByFile = () => (_diffByFile ??= diffData?.diffContent ? sliceDiffByFile(diffData.diffContent) : new Map());
+            let changedResources = classifiedEndpoints ? [] : undefined;
+            let changedSymbols;
+            if (classifiedEndpoints &&
+                classifiedEndpoints.changedEndpoints.length === 0 &&
+                classifiedEndpoints.newEndpoints.length === 0 &&
+                classifiedEndpoints.removedEndpoints.length === 0 &&
+                diffData?.diffContent) {
+                // Only changed application-source files carry a resource signal — skip test
+                // files, configs, workflows, and docs (they'd contribute filename noise like
+                // "workspace" or "skyramp-testbot").
+                const SOURCE_EXT = /\.(ts|tsx|js|jsx|py|java|kt|go|rb|php|rs|cs|ex|exs)$/;
+                const files = (classifiedEndpoints.changedFiles ?? diffData.changedFiles ?? [])
+                    .filter((f) => SOURCE_EXT.test(f) && !isTestFile(f));
+                // A schema/DTO/model file is named for its module, not the REST resource — its
+                // class names are the real signal (DeploymentCreate → "deployment", not the
+                // "actions" filename). For those files prefer the symbol-derived tokens and drop
+                // the generic filename token; otherwise use all tokens.
+                const SCHEMA_FILE = /\/(schemas?|models?|dtos?|entities|serializers?|types)\/|\.(dto|schema|model|entity|serializer)\.[^/]+$/i;
+                // Per-file diff sections (with @@ headers) so each file's tokens derive
+                // only from its own hunk — passing the full multi-file diff would mix
+                // symbols across files. Falls back to the full diff if a path doesn't
+                // match (no worse than the prior behavior). SKYR-3924.
+                const diffByFile = getDiffByFile();
+                const derived = new Set();
+                const symbols = new Set();
+                for (const f of files) {
+                    const fileDiff = diffByFile.get(f) ?? diffData.diffContent;
+                    const all = deriveResourceTokensForFile(f, fileDiff);
+                    const filenameToken = deriveResourceToken(f);
+                    const symbolTokens = all.filter((t) => t !== filenameToken);
+                    // deriveResourceTokensForFile already drops generic tokens (via importerHop's
+                    // GENERIC_RESOURCE_TOKENS / GENERIC_SYMBOL_TOKENS), so no extra filter is needed here.
+                    const chosen = SCHEMA_FILE.test(f) && symbolTokens.length > 0 ? symbolTokens : all;
+                    for (const t of chosen)
+                        derived.add(t);
+                    // Raw changed symbol names, derived from THIS file's diff slice only (not the full
+                    // multi-file diff) so an unrelated changed file — a test or doc — can't inject its
+                    // symbols. Uses the per-file slice from diffByFile.get(f).
+                    for (const s of extractChangedSymbols(diffByFile.get(f) ?? ""))
+                        symbols.add(s);
+                }
+                if (derived.size > 0) {
+                    changedResources = [...derived];
+                    // Raw changed symbol names (e.g. "DeploymentCreate") for a content grep against
+                    // test bodies — catches tests that reference the changed type by name but whose
+                    // path/URL doesn't token-match the resource (e.g. a schema unit test).
+                    changedSymbols = [...symbols];
+                    logger.info("Schema-only diff: derived changedResources from changed files (SKYR-3924)", {
+                        changedResources,
+                        changedSymbols,
+                    });
+                }
+            }
             // Compute changed frontend files once — reused for both discoverTests (component
             // test promotion) and uiContext below (page enumeration). Uses classifiedEndpoints
             // changedFiles so it reflects the same diff scope as the rest of the analysis.
             const flutterSdkDep = hasFlutterSdkDep(params.repositoryPath);
             const changedFrontendFiles = (classifiedEndpoints?.changedFiles ?? diffData?.changedFiles ?? [])
                 .filter(f => isFrontendFile(f, { hasFlutterSdkDep: flutterSdkDep }) && !isTestFile(f));
+            // Selector literals (data-testid values, CSS class tokens) added/removed in the
+            // frontend diff — drives discovery pass 3, which promotes page objects/specs that
+            // couple to a changed component by selector rather than by filename or import
+            // (see TestDiscoveryService Step 2). Derived from each changed frontend file's own
+            // diff slice so an unrelated file can't inject selectors.
+            let changedSelectors;
+            if (changedFrontendFiles.length > 0 && diffData?.diffContent) {
+                const diffByFile = getDiffByFile();
+                // Total cap across all changed files (each file is separately capped inside
+                // extractChangedSelectors). Bounds pass 3's O(externalFiles × selectors) scan so a
+                // large frontend PR can't produce a pathologically long selector set.
+                const MAX_TOTAL_SELECTORS = 200;
+                const selectors = new Set();
+                outer: for (const f of changedFrontendFiles) {
+                    const fileSelectors = extractChangedSelectors(diffByFile.get(f) ?? "");
+                    if (fileSelectors.length >= MAX_CHANGED_SELECTORS) {
+                        logger.warning(`changedSelectors: file '${f}' hit the per-file cap (${MAX_CHANGED_SELECTORS}); its selector extraction may be truncated`);
+                    }
+                    for (const s of fileSelectors) {
+                        selectors.add(s);
+                        if (selectors.size >= MAX_TOTAL_SELECTORS) {
+                            logger.warning(`changedSelectors: hit the total cap (${MAX_TOTAL_SELECTORS}) across ${changedFrontendFiles.length} changed frontend file(s); remaining selectors ignored for UI promotion pass 3`);
+                            break outer;
+                        }
+                    }
+                }
+                if (selectors.size > 0) {
+                    changedSelectors = [...selectors];
+                    logger.info("Derived changedSelectors from frontend diff (UI promotion pass 3)", {
+                        count: changedSelectors.length,
+                    });
+                }
+            }
             let existingTests = [];
             let discoveredRelevantExternalPaths = [];
             try {
                 const testDiscoveryService = new TestDiscoveryService();
                 setTestsRepoDir(params.testsRepoDir);
-                const discoveryResult = await testDiscoveryService.discoverTests(testDir ?? params.repositoryPath, { changedResources, hasFrontendChanges: changedFrontendFiles.length > 0 });
+                const discoveryResult = await testDiscoveryService.discoverTests(testDir ?? params.repositoryPath, { changedResources, changedSymbols, preciseResources: (changedSymbols?.length ?? 0) > 0, changedFrontendFiles, changedSelectors });
                 existingTests = discoveryResult.tests.map((test) => ({
                     testFile: test.testFile,
                     testType: test.testType,
@@ -1374,6 +1470,8 @@ export function registerAnalyzeChangesTool(server) {
                     primaryFramework: projectMeta.primaryFramework,
                     existingTestCount: existingTests.length,
                     newEndpointCount: classifiedEndpoints?.newEndpoints.length ?? 0,
+                    modifiedEndpointCount: classifiedEndpoints?.changedEndpoints.length ?? 0,
+                    removedEndpointCount: classifiedEndpoints?.removedEndpoints.length ?? 0,
                     endpointCount: skeletonEndpoints.reduce((acc, ep) => acc + ep.methods.length, 0),
                 },
                 // Surface uiContext inline so the testbot prompt can iterate
@@ -1454,7 +1552,7 @@ export function registerAnalyzeChangesTool(server) {
         finally {
             AnalyticsService.pushMCPToolEvent(TOOL_NAME, errorResult, {
                 repositoryPath: params.repositoryPath,
-            });
+            }).catch((err) => { logger.warning("Analytics event failed", { error: String(err) }); });
         }
     });
 }

package/build/tools/test-management/analyzeChangesTool.test.js

@@ -5,7 +5,7 @@ import { jest } from "@jest/globals";
 // graph touches must use unstable_mockModule before the dynamic import below.
 jest.unstable_mockModule("simple-git", () => ({ simpleGit: jest.fn() }));
 jest.unstable_mockModule("../../services/AnalyticsService.js", () => ({
-    AnalyticsService: { pushMCPToolEvent: jest.fn() },
+    AnalyticsService: { pushMCPToolEvent: jest.fn().mockResolvedValue(undefined) },
 }));
 jest.unstable_mockModule("../../prompts/test-recommendation/test-recommendation-prompt.js", () => ({
     buildRecommendationPrompt: jest.fn(),
@@ -49,6 +49,8 @@ jest.unstable_mockModule("../../utils/importerHop.js", () => ({
     deriveResourceTokensForFile: jest.fn(() => []),
     endpointResourceTokens: jest.fn(() => new Set()),
     sliceAddedLinesByFile: jest.fn(() => new Map()),
+    sliceDiffByFile: jest.fn(() => new Map()),
+    extractChangedSymbols: jest.fn(() => []),
 }));
 jest.unstable_mockModule("../../utils/repoScanner.js", () => ({
     scanAllRepoEndpoints: jest.fn(),

package/build/tools/test-management/analyzeTestHealthTool.js

@@ -95,10 +95,18 @@ export function registerAnalyzeTestHealthTool(server) {
             let uiDriftParams;
             if (hasUiFrontend) {
                 logger.info(`Including UI drift analysis for ${uiTests.length} UI test(s), ${apiTests.length} API test(s)`);
+                // Shared components = changed frontend files imported by 2+ production files
+                // (server-computed importer graph, SKYR-3855). Surfacing the concrete importer
+                // list makes the "shared component → cannot IGNORE unread" drift rule enforceable
+                // against real data instead of the agent's qualitative guess.
+                const sharedComponents = (uiContext.frontendFileIntegration ?? [])
+                    .filter((f) => f.importers.length >= 2)
+                    .map((f) => ({ file: f.file, importers: f.importers }));
                 uiDriftParams = {
                     tests: uiTests.map(t => ({ testFile: t.testFile, source: t.source })),
                     changedFrontendFiles: uiContext.changedFrontendFiles,
                     blueprintCaptured: args.blueprintCaptured,
+                    sharedComponents,
                 };
             }
             // Collect all checked-out repo paths so the grep instruction covers
@@ -124,7 +132,7 @@ export function registerAnalyzeTestHealthTool(server) {
             return errorResult;
         }
         finally {
-            AnalyticsService.pushMCPToolEvent(TOOL_NAME, errorResult, {});
+            AnalyticsService.pushMCPToolEvent(TOOL_NAME, errorResult, {}).catch((err) => { logger.warning("Analytics event failed", { error: String(err) }); });
         }
     });
 }

package/build/tools/test-management/analyzeTestHealthTool.test.js

@@ -15,7 +15,7 @@ jest.unstable_mockModule("../../utils/logger.js", () => ({
     },
 }));
 jest.unstable_mockModule("../../services/AnalyticsService.js", () => ({
-    AnalyticsService: { pushMCPToolEvent: jest.fn() },
+    AnalyticsService: { pushMCPToolEvent: jest.fn().mockResolvedValue(undefined) },
 }));
 const mockBuildDriftAnalysisPrompt = jest.fn().mockImplementation((_stateFile, apiTests, ui) => {
     const parts = [];

package/build/tools/trace/startTraceCollectionTool.js

@@ -251,7 +251,7 @@ For detailed documentation visit: https://www.skyramp.dev/docs/load-test/advance
                 prompt: params.prompt,
                 playwright: params.playwright.toString(),
             };
-            AnalyticsService.pushMCPToolEvent(TOOL_NAME, errorResult, recordParams);
+            AnalyticsService.pushMCPToolEvent(TOOL_NAME, errorResult, recordParams).catch((err) => { logger.warning("Analytics event failed", { error: String(err) }); });
         }
     });
 }

package/build/tools/trace/stopTraceCollectionTool.js

@@ -140,7 +140,7 @@ For detailed documentation visit: https://www.skyramp.dev/docs/load-test/advance
                 prompt: params.prompt,
                 playwright: params.playwrightEnabled.toString(),
             };
-            AnalyticsService.pushMCPToolEvent(TOOL_NAME, errorResult, recordParams);
+            AnalyticsService.pushMCPToolEvent(TOOL_NAME, errorResult, recordParams).catch((err) => { logger.warning("Analytics event failed", { error: String(err) }); });
         }
     });
 }

package/build/tools/workspace/initScanWorkspaceTool.js

@@ -70,7 +70,7 @@ export function registerInitScanWorkspaceTool(server) {
             return errorResult;
         }
         finally {
-            AnalyticsService.pushMCPToolEvent(TOOL_NAME, errorResult, recordParams);
+            AnalyticsService.pushMCPToolEvent(TOOL_NAME, errorResult, recordParams).catch((err) => { logger.warning("Analytics event failed", { error: String(err) }); });
         }
     });
 }

package/build/tools/workspace/initializeWorkspaceTool.js

@@ -201,7 +201,7 @@ export function registerInitializeWorkspaceTool(server) {
             return errorResult;
         }
         finally {
-            AnalyticsService.pushMCPToolEvent(TOOL_NAME, errorResult, recordParams);
+            AnalyticsService.pushMCPToolEvent(TOOL_NAME, errorResult, recordParams).catch((err) => { logger.warning("Analytics event failed", { error: String(err) }); });
         }
     });
 }

package/build/tools/workspace/initializeWorkspaceTool.test.js

@@ -18,7 +18,7 @@ jest.unstable_mockModule("../../utils/logger.js", () => ({
     logger: { info: jest.fn(), error: jest.fn() },
 }));
 jest.unstable_mockModule("../../services/AnalyticsService.js", () => ({
-    AnalyticsService: { pushMCPToolEvent: jest.fn() },
+    AnalyticsService: { pushMCPToolEvent: jest.fn().mockResolvedValue(undefined) },
 }));
 jest.unstable_mockModule("./initScanWorkspaceTool.js", () => ({
     validateAndConsumeScanToken: jest.fn(),

package/build/types/RepositoryAnalysis.d.ts

@@ -1431,12 +1431,12 @@ export declare const analysisMetadataSchema: z.ZodObject<{
 }, "strip", z.ZodTypeAny, {
     repositoryName: string;
     analysisDate: string;
-    scanDepth: "quick" | "full";
+    scanDepth: "full" | "quick";
     analysisScope?: AnalysisScope | undefined;
 }, {
     repositoryName: string;
     analysisDate: string;
-    scanDepth: "quick" | "full";
+    scanDepth: "full" | "quick";
     analysisScope?: AnalysisScope | undefined;
 }>;
 export declare const projectClassificationSchema: z.ZodObject<{
@@ -1464,12 +1464,12 @@ export declare const repositoryAnalysisSchema: z.ZodObject<{
     }, "strip", z.ZodTypeAny, {
         repositoryName: string;
         analysisDate: string;
-        scanDepth: "quick" | "full";
+        scanDepth: "full" | "quick";
         analysisScope?: AnalysisScope | undefined;
     }, {
         repositoryName: string;
         analysisDate: string;
-        scanDepth: "quick" | "full";
+        scanDepth: "full" | "quick";
         analysisScope?: AnalysisScope | undefined;
     }>;
     projectClassification: z.ZodObject<{
@@ -2601,7 +2601,7 @@ export declare const repositoryAnalysisSchema: z.ZodObject<{
     metadata: {
         repositoryName: string;
         analysisDate: string;
-        scanDepth: "quick" | "full";
+        scanDepth: "full" | "quick";
         analysisScope?: AnalysisScope | undefined;
     };
     projectClassification: {
@@ -2803,7 +2803,7 @@ export declare const repositoryAnalysisSchema: z.ZodObject<{
     metadata: {
         repositoryName: string;
         analysisDate: string;
-        scanDepth: "quick" | "full";
+        scanDepth: "full" | "quick";
         analysisScope?: AnalysisScope | undefined;
     };
     projectClassification: {

package/build/types/TestAnalysis.d.ts

@@ -48,8 +48,21 @@ export interface DriftRecommendation extends MaintenanceActionCore {
         newPath: string;
         method: string;
     }>;
+    /** Line-anchored edit sites the assessment located while reading a large UPDATE file —
+     *  surfaced in update_context as a checklist so the apply step edits each site directly
+     *  instead of re-scanning the file. */
+    editSites?: Array<{
+        line: number;
+        anchor: string;
+        change?: string;
+    }>;
     /** Computed during instruction building — suggested renamed file path if applicable. */
     _suggestedNewFile?: string;
+    /** REGENERATE/DELETE on an external (user-authored) test is report-only: the verdict is
+     *  recorded and rendered in the report so the developer sees the recommendation, but the
+     *  file is never touched (the apply loops skip reportOnly entries). Lets the report keep
+     *  the real DELETE/REGENERATE action instead of flattening it to VERIFY. */
+    reportOnly?: boolean;
 }
 /**
  * Complete test analysis result that combines discovery, drift, execution, and health data

package/build/utils/dartRouteExtractor.js

@@ -31,6 +31,7 @@
  */
 import * as fs from "fs";
 import * as path from "path";
+import { collectFiles } from "./fileWalk.js";
 const MAX_CANDIDATE_FILES = 200;
 const MAX_WALK_DEPTH = 10;
 const SKIP_DIRS = new Set([
@@ -283,37 +284,14 @@ function collectImports(source, filePath, repoPath) {
 function snakeToCamel(s) {
     return s
         .split("_")
-        .map((p, i) => p.charAt(0).toUpperCase() + p.slice(1))
+        .map((p) => 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;
+    return collectFiles(repoPath, {
+        match: (entry) => entry.name.endsWith(".dart"),
+        limit: MAX_CANDIDATE_FILES,
+        maxDepth: MAX_WALK_DEPTH,
+        shouldSkipDir: (entry) => SKIP_DIRS.has(entry.name) || entry.name.startsWith("."),
+    });
 }

package/build/utils/docker.test.js

@@ -55,7 +55,7 @@ describe("dockerImageExistsLocally", () => {
     });
 });
 describe("pullDockerImage", () => {
-    const IMAGE = "skyramp/executor:v1.3.33";
+    const IMAGE = "skyramp/executor:v1.3.34";
     beforeEach(() => jest.clearAllMocks());
     describe("on amd64 host", () => {
         const originalArch = process.arch;

package/build/utils/fileWalk.d.ts

@@ -0,0 +1,71 @@
+import * as fs from "fs";
+export interface WalkDirOptions {
+    /**
+     * Return `true` to skip descending into a directory entirely. Receives the
+     * directory's `Dirent` and its absolute path. Omit to descend into every
+     * directory.
+     */
+    shouldSkipDir?: (entry: fs.Dirent, fullPath: string) => boolean;
+    /**
+     * Maximum directory depth to descend, with the walk root at depth 0. A file
+     * is visited only if its parent directory's depth is `<= maxDepth`. Omit for
+     * unlimited depth. (`maxDepth: 0` visits only files directly under the root.)
+     */
+    maxDepth?: number;
+}
+/**
+ * Core depth-first directory traversal shared by every repo walker.
+ *
+ * Yields `[entry, fullPath]` for each regular file encountered (directories are
+ * never yielded). Callers early-exit simply by `break`ing out of the `for…of` —
+ * abandoning the generator stops the walk immediately, before any further
+ * `readdirSync`.
+ *
+ * Best-effort: an unreadable directory is skipped rather than throwing, matching
+ * the scanners' "one bad directory shouldn't abort discovery" contract.
+ */
+export declare function walkDir(rootDir: string, opts?: WalkDirOptions): Generator<[fs.Dirent, string]>;
+export interface CollectFilesOptions {
+    /** Return `true` for files to include. Receives the file's `Dirent` and its absolute path. */
+    match: (entry: fs.Dirent, fullPath: string) => boolean;
+    /**
+     * Stop once this many files have been collected — a backstop against
+     * pathological repos. Omit for no cap. When the cap is hit exactly `limit`
+     * files are returned, so callers can detect truncation via
+     * `result.length >= limit`.
+     */
+    limit?: number;
+    /** Skip descending into a directory (see {@link WalkDirOptions.shouldSkipDir}). */
+    shouldSkipDir?: (entry: fs.Dirent, fullPath: string) => boolean;
+    /** Maximum descent depth, root = 0 (see {@link WalkDirOptions.maxDepth}). */
+    maxDepth?: number;
+}
+/**
+ * Collect the absolute paths of files matching `match`, up to `limit`.
+ *
+ * The cap-aware layer over {@link walkDir}: it owns the "accumulate matches and
+ * abort at the count cap" idiom once, so the repo's file collectors don't each
+ * re-derive it. Best-effort, matching `walkDir`.
+ */
+export declare function collectFiles(rootDir: string, opts: CollectFilesOptions): string[];
+export interface WalkOptions {
+    /** Only files whose name ends with one of these extensions are returned (e.g. [".py"], [".ts", ".tsx"]). */
+    extensions: string[];
+    /** Directory names to skip entirely (matched on basename, not full path). */
+    skipDirs: Set<string>;
+    /**
+     * Stop once this many files have been collected — a backstop against
+     * pathological repos. Omit for no cap. When the cap is hit the walk returns
+     * exactly `limit` files, so callers can detect truncation via
+     * `result.length >= limit`.
+     */
+    limit?: number;
+}
+/**
+ * Recursively collect source files under `rootDir`, returning absolute paths.
+ *
+ * Shared walker used by the repo scanners (endpoint catalog, Python mount-prefix
+ * resolver) so they don't each carry a near-identical `readdirSync` recursion.
+ * Thin wrapper over {@link collectFiles} that matches by extension suffix.
+ */
+export declare function walkSourceFiles(rootDir: string, opts: WalkOptions): string[];

package/build/utils/fileWalk.js

@@ -0,0 +1,79 @@
+import * as fs from "fs";
+import * as path from "path";
+/**
+ * Core depth-first directory traversal shared by every repo walker.
+ *
+ * Yields `[entry, fullPath]` for each regular file encountered (directories are
+ * never yielded). Callers early-exit simply by `break`ing out of the `for…of` —
+ * abandoning the generator stops the walk immediately, before any further
+ * `readdirSync`.
+ *
+ * Best-effort: an unreadable directory is skipped rather than throwing, matching
+ * the scanners' "one bad directory shouldn't abort discovery" contract.
+ */
+export function* walkDir(rootDir, opts = {}) {
+    const { shouldSkipDir, maxDepth } = opts;
+    function* walk(dir, depth) {
+        let entries;
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return; // best-effort: skip unreadable directory, keep going
+        }
+        for (const entry of entries) {
+            const full = path.join(dir, entry.name);
+            if (entry.isDirectory()) {
+                // Cheap integer bound before the (possibly non-trivial) skip callback.
+                if (maxDepth !== undefined && depth + 1 > maxDepth)
+                    continue;
+                if (shouldSkipDir?.(entry, full))
+                    continue;
+                yield* walk(full, depth + 1);
+            }
+            else if (entry.isFile()) {
+                yield [entry, full];
+            }
+        }
+    }
+    yield* walk(rootDir, 0);
+}
+/**
+ * Collect the absolute paths of files matching `match`, up to `limit`.
+ *
+ * The cap-aware layer over {@link walkDir}: it owns the "accumulate matches and
+ * abort at the count cap" idiom once, so the repo's file collectors don't each
+ * re-derive it. Best-effort, matching `walkDir`.
+ */
+export function collectFiles(rootDir, opts) {
+    const { match, limit, shouldSkipDir, maxDepth } = opts;
+    if (limit !== undefined && limit <= 0)
+        return [];
+    const results = [];
+    for (const [entry, full] of walkDir(rootDir, { shouldSkipDir, maxDepth })) {
+        if (match(entry, full)) {
+            results.push(full);
+            // Stop the instant the cap is reached — breaking abandons the generator
+            // before it descends into (and readdirs) any further directories, so we
+            // return exactly `limit` files.
+            if (limit !== undefined && results.length >= limit)
+                break;
+        }
+    }
+    return results;
+}
+/**
+ * Recursively collect source files under `rootDir`, returning absolute paths.
+ *
+ * Shared walker used by the repo scanners (endpoint catalog, Python mount-prefix
+ * resolver) so they don't each carry a near-identical `readdirSync` recursion.
+ * Thin wrapper over {@link collectFiles} that matches by extension suffix.
+ */
+export function walkSourceFiles(rootDir, opts) {
+    const { extensions, skipDirs, limit } = opts;
+    return collectFiles(rootDir, {
+        match: (entry) => extensions.some((ext) => entry.name.endsWith(ext)),
+        limit,
+        shouldSkipDir: (entry) => skipDirs.has(entry.name),
+    });
+}

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

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