@skyramp/mcp 0.2.7 → 0.2.150-rc.mntnc

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

@@ -24,6 +24,32 @@ import { buildAnalysisOutputText } from "../../prompts/test-recommendation/analy
 import { parseTraceFile, discoverTraceFiles, discoverPlaywrightZips, } from "../../utils/trace-parser.js";
 import { TestSource } from "../../types/TestAnalysis.js";
 import { parsePRComments } from "../../utils/pr-comment-parser.js";
+// Generic module names that appear as imports in virtually every router file.
+// Matching against these would extract ALL prefix= tokens from mount files,
+// flooding changedResources with unrelated resources.
+const GENERIC_MODULE_NAMES = new Set([
+    "models", "utils", "helpers", "schemas", "types", "constants",
+    "config", "settings", "exceptions", "errors", "base", "common",
+    "app", "main", "index", "server", "init", "deps", "dependencies",
+]);
+function resolveMountPrefixTokens(mountFileContents, changedFiles) {
+    const tokens = changedFiles.flatMap((file) => {
+        const mod = path.basename(file).replace(/\.[^.]+$/, "").toLowerCase();
+        if (GENERIC_MODULE_NAMES.has(mod))
+            return [];
+        const modRe = new RegExp(`\\b${mod.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\b`);
+        return mountFileContents.flatMap((content) => {
+            if (!modRe.test(content.toLowerCase()))
+                return [];
+            const matches = [...content.matchAll(/prefix\s*=\s*["'](\/?[^"']+)/g)];
+            return matches.flatMap((m) => {
+                const token = extractResourceFromPath(m[1]);
+                return token !== "unknown" ? [token] : [];
+            });
+        });
+    });
+    return [...new Set(tokens)];
+}
 /** Exported for testing: maps a parsed trace result to a TraceFile. */
 export function buildTraceFileEntry(tracePath, result) {
     return {
@@ -339,11 +365,6 @@ export const analyzeChangesInputSchema = {
         .number()
         .optional()
         .describe("GitHub PR number. When provided, fetches previous TestBot comments on this PR and skips re-recommending tests already suggested in earlier commits — reduces duplicate recommendations across multiple pushes to the same PR."),
-    stateOutputFile: z
-        .string()
-        .refine((v) => path.isAbsolute(v), { message: "stateOutputFile must be an absolute path" })
-        .optional()
-        .describe("Absolute path where the state file should be written. When provided, overrides the default auto-generated temp path so the caller can locate it without log parsing."),
     testsRepoDir: z
         .string()
         .refine((v) => path.isAbsolute(v), { message: "testsRepoDir must be an absolute path" })
@@ -568,6 +589,30 @@ export function registerAnalyzeChangesTool(server) {
             // testsRepoDir is a cross-repo path override — honour it when set.
             // Otherwise always scan the full repo root.
             const testDir = params.testsRepoDir ?? undefined;
+            const routerMountContext = grepRouterMountingContext(params.repositoryPath);
+            // Read contents once — used for token extraction and LLM prompt injection.
+            const ROUTER_INLINE_LIMIT = 4096;
+            const routerMountContextContents = routerMountContext.map((f) => {
+                try {
+                    const abs = path.isAbsolute(f) ? f : path.join(params.repositoryPath, f);
+                    if (fs.statSync(abs).size > ROUTER_INLINE_LIMIT * 10)
+                        return ""; // skip very large files
+                    return fs.readFileSync(abs, "utf-8");
+                }
+                catch {
+                    return "";
+                }
+            });
+            // Size-capped subset for LLM prompt injection.
+            const ROUTER_INLINE_MAX_FILES = 3;
+            const routerFileContents = routerMountContext
+                .slice(0, ROUTER_INLINE_MAX_FILES)
+                .flatMap((f, i) => {
+                const content = routerMountContextContents[i] ?? "";
+                if (!content || content.length > ROUTER_INLINE_LIMIT)
+                    return [];
+                return [{ file: f, content: content.trimEnd() }];
+            });
             // Compute changedResources from classified endpoints for test discovery filtering.
             // undefined    → full-repo mode (no diff context)
             // []           → PR mode, no endpoints found → skip external tests
@@ -596,14 +641,22 @@ export function registerAnalyzeChangesTool(server) {
                     }
                     else {
                         // All endpoints resolved to "unknown" (e.g. NestJS relative paths) —
-                        // extract resource names from changed file paths instead.
-                        const candidateFiles = classifiedEndpoints.unmatchedFiles.length > 0
-                            ? classifiedEndpoints.unmatchedFiles
-                            : classifiedEndpoints.changedFiles ?? [];
-                        const fromFiles = candidateFiles
-                            .map((f) => extractResourceFromPath(f.replace(/\.[^./]+$/, "").replace(FRAMEWORK_SUFFIX_RE, "")))
-                            .filter((r, i, arr) => r !== "unknown" && arr.indexOf(r) === i);
-                        changedResources = fromFiles.length > 0 ? fromFiles : ["unknown"];
+                        // first try to extract resource names from router mount prefixes.
+                        const changedSourceFiles = classifiedEndpoints.changedFiles ?? [];
+                        const mountedResources = resolveMountPrefixTokens(routerMountContextContents, changedSourceFiles);
+                        if (mountedResources.length > 0) {
+                            changedResources = mountedResources;
+                        }
+                        else {
+                            // Fall back to extracting resource names from changed file paths.
+                            const candidateFiles = classifiedEndpoints.unmatchedFiles.length > 0
+                                ? classifiedEndpoints.unmatchedFiles
+                                : classifiedEndpoints.changedFiles ?? [];
+                            const fromFiles = candidateFiles
+                                .map((f) => extractResourceFromPath(f.replace(/\.[^./]+$/, "").replace(FRAMEWORK_SUFFIX_RE, "")))
+                                .filter((r, i, arr) => r !== "unknown" && arr.indexOf(r) === i);
+                            changedResources = fromFiles.length > 0 ? fromFiles : ["unknown"];
+                        }
                     }
                 }
                 else if (classifiedEndpoints.unmatchedFiles.length > 0) {
@@ -622,7 +675,15 @@ export function registerAnalyzeChangesTool(server) {
                     changedResources = fromFiles.length > 0 ? fromFiles : ["unknown"];
                 }
                 else {
-                    changedResources = [];
+                    // No endpoints and no unmatched files — the diff touches only non-route
+                    // files (e.g. schema, model, DTO). Extract resource tokens from the
+                    // changed file paths so tests that import the changed symbol are still
+                    // surfaced for drift assessment. Fall back to [] only if extraction
+                    // yields nothing (e.g. a file with a non-resource name like utils.py).
+                    const fromChangedFiles = (classifiedEndpoints.changedFiles ?? [])
+                        .map((f) => extractResourceFromPath(f.replace(/\.[^./]+$/, "").replace(FRAMEWORK_SUFFIX_RE, "")))
+                        .filter((r, i, arr) => r !== "unknown" && arr.indexOf(r) === i);
+                    changedResources = fromChangedFiles.length > 0 ? fromChangedFiles : [];
                 }
             }
             let existingTests = [];
@@ -903,10 +964,15 @@ export function registerAnalyzeChangesTool(server) {
                         sourceFile: m.sourceFile ?? "",
                     })))
                     : [];
+            const removedEndpointsForDrafting = classifiedEndpoints?.removedEndpoints.flatMap((ep) => ep.methods.map((m) => ({
+                method: m,
+                path: ep.path,
+                sourceFile: ep.sourceFile,
+            }))) ?? [];
             const codeInferredScenarios = draftScenariosFromEndpoints(skeletonEndpoints, scenarioDraftSeed, wsAuthType, {
                 changedEndpoints: changedEndpointsForSecurityExpansion,
                 securityRelevantDiff,
-            });
+            }, removedEndpointsForDrafting);
             let allDraftedScenarios = codeInferredScenarios;
             if (traceResult && traceResult.userFlows.length > 0) {
                 const traceScenarios = traceResult.userFlows
@@ -1109,7 +1175,6 @@ export function registerAnalyzeChangesTool(server) {
             // can be persisted to the state file for downstream tools (health, drift).
             // Without them, analyzeTestHealth would work only off the static catalog
             // which has wrong paths for nested resources and unsupported frameworks.
-            const routerMountContext = grepRouterMountingContext(params.repositoryPath);
             const routeLikeUnmatchedFiles = [];
             for (const file of classifiedEndpoints?.unmatchedFiles ?? []) {
                 const routeLike = SOURCE_EXTS.test(file) &&
@@ -1138,25 +1203,6 @@ export function registerAnalyzeChangesTool(server) {
                 diffFilePath = path.join(os.tmpdir(), `skyramp-diff-${sessionId}.diff`);
                 await fs.promises.writeFile(diffFilePath, diffData.diffContent, { encoding: "utf-8", mode: 0o600 });
             }
-            // Read router mount files server-side (size-capped) so the LLM has them
-            // inline and doesn't need an extra read step when no spec is available.
-            const ROUTER_INLINE_LIMIT = 4096; // bytes — skip files larger than ~4 KB
-            const ROUTER_INLINE_MAX_FILES = 3;
-            const routerFileContents = routerMountContext
-                .slice(0, ROUTER_INLINE_MAX_FILES)
-                .flatMap((f) => {
-                try {
-                    const absPath = path.isAbsolute(f) ? f : path.join(params.repositoryPath, f);
-                    const stat = fs.statSync(absPath);
-                    if (stat.size > ROUTER_INLINE_LIMIT)
-                        return [];
-                    const content = fs.readFileSync(absPath, "utf-8").trimEnd();
-                    return [{ file: f, content }];
-                }
-                catch {
-                    return [];
-                }
-            });
             // Compute UI context from the diff's changed files using the shared
             // `isFrontendFile` classifier. Persisting this in the stateFile lets
             // skyramp_analyze_test_health and the recommendation prompt consume the
@@ -1252,17 +1298,14 @@ export function registerAnalyzeChangesTool(server) {
                     relevantExternalTestPaths,
                 },
             };
-            // Clean up old state files (>24 hours) before creating new one
-            const stateDir = params.stateOutputFile
-                ? path.dirname(path.resolve(params.stateOutputFile))
-                : undefined;
+            // Clean up old state files (>24 hours) before creating new one.
             try {
-                await StateManager.cleanupOldFiles(24, stateDir);
+                await StateManager.cleanupOldFiles(24);
             }
             catch (error) {
                 logger.warning(`Failed to cleanup old state files: ${error.message}`);
             }
-            const stateManager = new StateManager("analysis", sessionId, undefined, params.stateOutputFile);
+            const stateManager = new StateManager("analysis", sessionId);
             await stateManager.writeData(unifiedState, {
                 repositoryPath: params.repositoryPath,
                 step: "analyze_changes",

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

@@ -99,28 +99,6 @@ describe("isSecurityRelevantDiff", () => {
         expect(isSecurityRelevantDiff("move compression middleware to server setup")).toBe(false);
     });
 });
-describe("analyzeChangesInputSchema — stateOutputFile validation", () => {
-    it("accepts a valid absolute path", () => {
-        const result = schema.safeParse({
-            repositoryPath: "/repo",
-            stateOutputFile: "/tmp/analyze-changes-state.json",
-        });
-        expect(result.success).toBe(true);
-    });
-    it("rejects a relative path for stateOutputFile", () => {
-        // stateOutputFile must be absolute so the caller can guarantee the file location.
-        // Relative paths are silently ambiguous and should be rejected.
-        const result = schema.safeParse({
-            repositoryPath: "/repo",
-            stateOutputFile: "relative/path/state.json",
-        });
-        expect(result.success).toBe(false);
-    });
-    it("accepts absence of stateOutputFile (optional field)", () => {
-        const result = schema.safeParse({ repositoryPath: "/repo" });
-        expect(result.success).toBe(true);
-    });
-});
 describe("automatic old files cleanup", () => {
     let cleanupOldFilesSpy;
     beforeEach(() => {
@@ -128,31 +106,23 @@ describe("automatic old files cleanup", () => {
         cleanupOldFilesSpy = jest.fn().mockResolvedValue(0);
         StateManager.cleanupOldFiles = cleanupOldFilesSpy;
     });
-    it("calls cleanupOldFiles with default temp dir when no stateOutputFile provided", async () => {
-        // This test verifies the cleanup call is made without stateDir when using default location
+    it("calls cleanupOldFiles with default temp dir", async () => {
         expect(StateManager.cleanupOldFiles).toBeDefined();
         await StateManager.cleanupOldFiles(24, undefined);
         expect(cleanupOldFilesSpy).toHaveBeenCalledWith(24, undefined);
     });
-    it("calls cleanupOldFiles with custom dir when stateOutputFile is provided", async () => {
-        // This test verifies the cleanup call is made with the directory of stateOutputFile
+    it("calls cleanupOldFiles with custom dir", async () => {
         const customPath = "/custom/dir";
         await StateManager.cleanupOldFiles(24, customPath);
         expect(cleanupOldFilesSpy).toHaveBeenCalledWith(24, customPath);
     });
-    it("calls cleanupOldFiles with empty stateTypes to restrict to diff files only", async () => {
-        // analyzeTestHealthTool passes [] so state files (skyramp-analysis-*, skyramp-recommendation-*)
-        // are never deleted — the caller still needs args.stateFile for skyramp_actions.
+    it("calls cleanupOldFiles with empty stateTypes", async () => {
         await StateManager.cleanupOldFiles(24, undefined, []);
         expect(cleanupOldFilesSpy).toHaveBeenCalledWith(24, undefined, []);
     });
     it("continues execution if cleanup fails", async () => {
-        // Cleanup failures should not crash the analyze flow
         cleanupOldFilesSpy.mockRejectedValue(new Error("permission denied"));
-        await expect(StateManager.cleanupOldFiles(24).catch(() => {
-            // In the real code, this is caught and logged as a warning
-            return Promise.resolve();
-        })).resolves.toBeUndefined();
+        await expect(StateManager.cleanupOldFiles(24).catch(() => Promise.resolve())).resolves.toBeUndefined();
     });
 });
 // ─────────────────────────────────────────────────────────────────────────────

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

@@ -15,11 +15,11 @@ export function registerAnalyzeTestHealthTool(server) {
             idempotentHint: true,
             openWorldHint: false,
         },
-        description: `Generate drift assessment instructions for existing tests — second step of the unified Test Health Analysis Flow. Optionally execute tests with skyramp_execute_test before calling skyramp_actions to capture beforeStatus.`,
+        description: `Generate drift assessment instructions for existing tests — second step of the unified Test Health Analysis Flow.`,
         inputSchema: {
             stateFile: z
                 .string()
-                .describe("Path to state file from skyramp_analyze_changes. Assessment results exist only in the LLM's reasoning context — this tool does not write back to the stateFile."),
+                .describe("Path to the analyze-changes-state.json file returned by skyramp_analyze_changes (the stateFile field in its output). Do NOT pass summaryOutputFile or testbot-result.txt here."),
         },
         outputSchema: {
             prompt: z.string().describe("LLM drift analysis prompt and assessment instructions."),
@@ -37,7 +37,10 @@ export function registerAnalyzeTestHealthTool(server) {
                 return toolError(`State file is empty or invalid: ${args.stateFile}. Call skyramp_analyze_changes first to generate a valid state file.`);
             }
             if (!repositoryPath || typeof repositoryPath !== "string") {
-                return toolError(`repositoryPath not found in state file metadata. The state file was likely created by an older version — re-run skyramp_analyze_changes to regenerate it.`);
+                return toolError(`repositoryPath not found in state file metadata. The stateFile parameter must be the analyze-changes-state.json path returned by skyramp_analyze_changes — not summaryOutputFile or testbot-result.txt. Re-run skyramp_analyze_changes to regenerate it.`);
+            }
+            if (!Array.isArray(stateData.existingTests)) {
+                return toolError(`stateFile does not contain test discovery data (existingTests missing). The stateFile parameter must be the analyze-changes-state.json path returned by skyramp_analyze_changes — not summaryOutputFile or testbot-result.txt.`);
             }
             // Skyramp tests: full drift analysis + all actions permitted.
             // Relevant external tests (user-written, relevant to this PR's endpoints): drift analysis

package/build/types/TestAnalysis.d.ts

@@ -92,5 +92,6 @@ export interface TestAnalysisResult {
         changes: DriftChange[];
         affectedFiles: AffectedFiles;
     };
-    execution?: TestExecutionResult;
+    executionBefore?: TestExecutionResult;
+    executionAfter?: TestExecutionResult;
 }

package/build/types/TestExecution.d.ts

@@ -3,18 +3,28 @@
  *
  * These types define the structure for test execution results
  */
+/** Execution outcome for a test run recorded in the maintenance report. */
+export declare enum TestExecutionStatus {
+    Pass = "Pass",
+    Fail = "Fail",
+    Error = "Error",
+    /** Deliberately not executed — VERIFY/IGNORE actions or DELETE (file removed). */
+    Skipped = "Skipped",
+    /** Execution was expected (UPDATE/REGENERATE) but no result was recorded. */
+    Unknown = "Unknown"
+}
 export interface TestExecutionData {
-    passed: boolean;
+    status: TestExecutionStatus;
     executedAt: string;
     duration: number;
     errors: string[];
     warnings: string[];
-    crashed: boolean;
     output?: string;
     exitCode?: number;
 }
 export interface TestExecutionResult extends TestExecutionData {
     testFile: string;
+    videoPath?: string;
 }
 export interface BatchExecutionResult {
     totalTests: number;

package/build/types/TestExecution.js

@@ -3,4 +3,14 @@
  *
  * These types define the structure for test execution results
  */
-export {};
+/** Execution outcome for a test run recorded in the maintenance report. */
+export var TestExecutionStatus;
+(function (TestExecutionStatus) {
+    TestExecutionStatus["Pass"] = "Pass";
+    TestExecutionStatus["Fail"] = "Fail";
+    TestExecutionStatus["Error"] = "Error";
+    /** Deliberately not executed — VERIFY/IGNORE actions or DELETE (file removed). */
+    TestExecutionStatus["Skipped"] = "Skipped";
+    /** Execution was expected (UPDATE/REGENERATE) but no result was recorded. */
+    TestExecutionStatus["Unknown"] = "Unknown";
+})(TestExecutionStatus || (TestExecutionStatus = {}));

package/build/types/TestbotReport.d.ts

@@ -0,0 +1,68 @@
+import type { DriftAction } from "./TestAnalysis.js";
+import type { TestExecutionStatus } from "./TestExecution.js";
+import type { HttpMethod, TestType } from "./TestTypes.js";
+/**
+ * Shape of the JSON report written by skyramp_submit_report and read by testbot
+ * for rendering as Markdown. All fields mirror the corresponding Zod schemas in
+ * submitReportTool.ts — keep the two in sync.
+ */
+export interface TestbotReport {
+    businessCaseAnalysis: string;
+    newTestsCreated: {
+        testId: string;
+        testType: TestType;
+        endpoint: string;
+        fileName: string;
+        reasoning: string;
+        description?: string;
+        scenarioFile?: string;
+        traceFile?: string;
+        frontendTrace?: string;
+    }[];
+    /** Omitted when no existing tests were found (agent omits the field). */
+    testMaintenance?: {
+        testType: TestType;
+        endpoint: string;
+        fileName: string;
+        description: string;
+        action: DriftAction;
+        beforeStatus: TestExecutionStatus;
+        beforeDetails: string;
+        afterStatus: TestExecutionStatus;
+        afterDetails: string;
+    }[];
+    testResults: {
+        testType: TestType;
+        endpoint: string;
+        status: "Pass" | "Fail" | "Skipped";
+        details: string;
+        videoPath?: string;
+    }[];
+    additionalRecommendations?: {
+        testId: string;
+        testType: TestType;
+        category?: string;
+        primaryEndpoint?: string;
+        scenarioName?: string;
+        steps: {
+            method?: HttpMethod;
+            path?: string;
+            description: string;
+            expectedStatusCode?: number;
+            requestBody?: Record<string, unknown>;
+            responseBody?: Record<string, unknown>;
+        }[];
+        description: string;
+        priority: "high" | "medium" | "low";
+        reasoning: string;
+        openApiSpec?: string;
+        backendTrace?: string;
+        frontendTrace?: string;
+    }[];
+    issuesFound: {
+        description: string;
+        severity?: "critical" | "high" | "medium" | "low";
+    }[];
+    nextSteps: string[];
+    commitMessage: string;
+}

package/build/types/TestbotReport.js

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

package/build/types/index.d.ts

@@ -0,0 +1,4 @@
+export { TestExecutionStatus } from "./TestExecution.js";
+export { DriftAction } from "./TestAnalysis.js";
+export { TestType, HttpMethod } from "./TestTypes.js";
+export type { TestbotReport } from "./TestbotReport.js";

package/build/types/index.js

@@ -0,0 +1,3 @@
+export { TestExecutionStatus } from "./TestExecution.js";
+export { DriftAction } from "./TestAnalysis.js";
+export { TestType, HttpMethod } from "./TestTypes.js";

package/build/utils/AnalysisStateManager.js

@@ -119,6 +119,15 @@ export class StateManager {
         if (stateFilePath) {
             this.stateFile = stateFilePath;
         }
+        else if (stateType === "analysis" && process.env.RUNNER_TEMP) {
+            // In CI (testbot action), RUNNER_TEMP is a job-isolated dir that both the
+            // action and this tool can independently derive — no LLM input needed.
+            // TODO: interim step — remove this branch when stateFile and summaryOutputFile are merged
+            // (see getTestbotPrompt TODO). RUNNER_TEMP is GitHub Actions-specific; other CI systems
+            // (Jenkins, GitLab, Buildkite) must set it explicitly. Once merged, path flows through
+            // summaryOutputFile which is already testbot-controlled and CI-agnostic.
+            this.stateFile = path.join(process.env.RUNNER_TEMP, "skyramp", "analyze-changes-state.json");
+        }
         else {
             const baseDir = stateDir || os.tmpdir();
             const prefix = STATE_FILE_PREFIXES[stateType];
@@ -260,7 +269,7 @@ export class StateManager {
      * @returns Number of files deleted
      */
     static async cleanupOldFiles(maxAgeHours = 24, stateDir, stateTypes) {
-        const baseDir = stateDir || os.tmpdir();
+        const baseDir = stateDir || (process.env.RUNNER_TEMP ? path.join(process.env.RUNNER_TEMP, "skyramp") : os.tmpdir());
         const files = await fs.promises.readdir(baseDir).catch(() => []);
         const statePrefixes = stateTypes
             ? stateTypes.map((t) => STATE_FILE_PREFIXES[t])

package/build/utils/routeParsers.d.ts

@@ -50,14 +50,4 @@ export interface ClassifiedEndpoints {
     baseBranch: string;
     affectedServices: string[];
 }
-/**
- * Classify endpoints by cross-referencing `changedFiles` against `scannedEndpoints[].sourceFile`.
- *
- * This replaces `parseEndpointsFromDiff` — instead of regex-parsing diff hunks for route
- * annotations (fragile for 15+ frameworks), it uses the already-scanned endpoint catalog
- * which has full, resolved paths and concrete HTTP methods.
- *
- * For deleted files, the caller must supply endpoints recovered from the base branch
- * (via `parseFileEndpoints` on `git show base:<file>`) in `deletedFileEndpoints`.
- */
 export declare function classifyEndpointsByChangedFiles(diffData: BranchDiffData, scannedEndpoints: ScannedEndpoint[], deletedFileEndpoints?: ScannedEndpoint[]): ClassifiedEndpoints;

package/build/utils/routeParsers.js

@@ -406,21 +406,36 @@ const GENERIC_ROUTE_BASENAMES = new Set(["api", "app", "handler", "handlers", "i
 function normalizeSourcePath(filePath) {
     return filePath.replace(/\\/g, "/");
 }
-/**
- * Classify endpoints by cross-referencing `changedFiles` against `scannedEndpoints[].sourceFile`.
- *
- * This replaces `parseEndpointsFromDiff` — instead of regex-parsing diff hunks for route
- * annotations (fragile for 15+ frameworks), it uses the already-scanned endpoint catalog
- * which has full, resolved paths and concrete HTTP methods.
- *
- * For deleted files, the caller must supply endpoints recovered from the base branch
- * (via `parseFileEndpoints` on `git show base:<file>`) in `deletedFileEndpoints`.
- */
+function staticPathSegments(urlPath) {
+    return urlPath.split("/").filter(s => s && !/^[:{[]/.test(s)).map(s => s.toLowerCase());
+}
+function endpointSourceResource(ep) {
+    const sourceSegments = ep.sourceFile.split(/[\\/]/).filter(Boolean);
+    const filename = sourceSegments.at(-1)?.replace(/\.[^.]+$/, "") ?? "";
+    const normalizedFilename = filename.replace(/^(?:old|new)[-_]/i, "").toLowerCase();
+    const isDynamic = /^\[.*\]$/.test(normalizedFilename) || /^\{.*\}$/.test(normalizedFilename);
+    if (!isDynamic && !GENERIC_ROUTE_BASENAMES.has(normalizedFilename) && normalizedFilename) {
+        return normalizedFilename;
+    }
+    else if (GENERIC_ROUTE_BASENAMES.has(normalizedFilename)) {
+        // Generic filename: walk up the directory tree for a more specific ancestor name.
+        const parentSegments = sourceSegments.slice(0, -1).reverse();
+        const contextSegment = parentSegments
+            .map(s => s.replace(/\.[^.]+$/, "").replace(/^(?:old|new)[-_]/i, "").toLowerCase())
+            .find(s => s && !GENERIC_ROUTE_BASENAMES.has(s) && !/^\[.*\]$/.test(s) && !/^\{.*\}$/.test(s));
+        if (contextSegment)
+            return `${contextSegment}/${normalizedFilename}`;
+    }
+    // Fall back to the last static segment of the endpoint's URL path.
+    const segments = staticPathSegments(ep.path);
+    return segments.at(-1) ?? normalizedFilename;
+}
+function endpointMovedKey(path, resource, method) {
+    return method ? `${path}::${resource}::${method}` : `${path}::${resource}`;
+}
 export function classifyEndpointsByChangedFiles(diffData, scannedEndpoints, deletedFileEndpoints) {
     const newFileSet = new Set(diffData.newFiles.map(normalizeSourcePath));
     const deletedFileSet = new Set(diffData.deletedFiles.map(normalizeSourcePath));
-    // Build sourceFile -> ScannedEndpoint[] map from the post-change catalog.
-    // Git diffs use POSIX separators; scanner output can reflect OS-native paths.
     const bySourceFile = new Map();
     for (const ep of scannedEndpoints) {
         const sourceKey = normalizeSourcePath(ep.sourceFile);
@@ -435,7 +450,6 @@ export function classifyEndpointsByChangedFiles(diffData, scannedEndpoints, dele
     const unmatchedFiles = [];
     for (const file of diffData.changedFiles) {
         const fileKey = normalizeSourcePath(file);
-        // Deleted files won't appear in scanned catalog — handled separately below
         if (deletedFileSet.has(fileKey))
             continue;
         const eps = bySourceFile.get(fileKey);
@@ -454,47 +468,26 @@ export function classifyEndpointsByChangedFiles(diffData, scannedEndpoints, dele
     // Filter out endpoints that still exist in the current catalog as moved/refactored.
     // Same router-relative paths can exist in sibling files, so only treat them as moved
     // when the source resource also matches.
-    function endpointSourceResource(ep) {
-        const sourceSegments = ep.sourceFile.split(/[\\/]/).filter(Boolean);
-        const base = sourceSegments.at(-1)?.replace(/\.[^.]+$/, "") ?? "";
-        const normalizedBase = base.replace(/^(?:old|new)[-_]/i, "").toLowerCase();
-        const isDynamicBase = /^\[.*\]$/.test(normalizedBase) || /^\{.*\}$/.test(normalizedBase);
-        if (normalizedBase && !isDynamicBase && !GENERIC_ROUTE_BASENAMES.has(normalizedBase)) {
-            return normalizedBase;
-        }
-        if (normalizedBase && GENERIC_ROUTE_BASENAMES.has(normalizedBase)) {
-            const contextSegment = [...sourceSegments]
-                .slice(0, -1)
-                .reverse()
-                .map((segment) => segment.replace(/\.[^.]+$/, "").replace(/^(?:old|new)[-_]/i, "").toLowerCase())
-                .find((segment) => segment && !GENERIC_ROUTE_BASENAMES.has(segment) && !/^\[.*\]$/.test(segment) && !/^\{.*\}$/.test(segment));
-            if (contextSegment)
-                return `${contextSegment}/${normalizedBase}`;
-        }
-        const staticSegments = ep.path.split("/").filter(Boolean).filter((segment) => !/^[:{[]/.test(segment));
-        return staticSegments[staticSegments.length - 1]?.toLowerCase() ?? normalizedBase;
-    }
     const currentMethodKeys = new Set();
     const currentPathResourceKeys = new Set();
     const currentMultiKeys = new Set();
-    const movedKey = (path, resource, method) => method ? `${path}::${resource}::${method}` : `${path}::${resource}`;
     for (const current of scannedEndpoints) {
         const currentResource = endpointSourceResource(current);
-        const pathResourceKey = movedKey(current.path, currentResource);
+        const pathResourceKey = endpointMovedKey(current.path, currentResource);
         currentPathResourceKeys.add(pathResourceKey);
         for (const method of current.methods) {
             if (method === "MULTI")
                 currentMultiKeys.add(pathResourceKey);
-            currentMethodKeys.add(movedKey(current.path, currentResource, method));
+            currentMethodKeys.add(endpointMovedKey(current.path, currentResource, method));
         }
     }
     function isMovedEndpoint(deleted, method) {
         const deletedResource = endpointSourceResource(deleted);
-        const pathResourceKey = movedKey(deleted.path, deletedResource);
+        const pathResourceKey = endpointMovedKey(deleted.path, deletedResource);
         if (method === "MULTI")
             return currentPathResourceKeys.has(pathResourceKey);
         return currentMultiKeys.has(pathResourceKey) ||
-            currentMethodKeys.has(movedKey(deleted.path, deletedResource, method));
+            currentMethodKeys.has(endpointMovedKey(deleted.path, deletedResource, method));
     }
     const removedEndpoints = (deletedFileEndpoints ?? [])
         .map((ep) => ({

package/build/utils/scenarioDrafting.d.ts

@@ -41,7 +41,7 @@ export type ResourceRelationships = Map<string, Set<string>>;
  * the caller to fall back to heuristic pairing.
  */
 export declare function inferResourceRelationships(endpoints: Array<EndpointInput>): ResourceRelationships;
-export declare function draftScenariosFromEndpoints(endpoints: Array<EndpointInput>, newEndpoints?: Array<EndpointRef>, wsAuthType?: WorkspaceAuthType, options?: ScenarioDraftOptions): DraftedScenario[];
+export declare function draftScenariosFromEndpoints(endpoints: Array<EndpointInput>, newEndpoints?: Array<EndpointRef>, wsAuthType?: WorkspaceAuthType, options?: ScenarioDraftOptions, removedEndpoints?: Array<EndpointRef>): DraftedScenario[];
 /**
  * Draft scenarios that directly test each new endpoint in the branch diff.
  *

package/build/utils/scenarioDrafting.js

@@ -142,7 +142,7 @@ export function inferResourceRelationships(endpoints) {
     }
     return relationships;
 }
-export function draftScenariosFromEndpoints(endpoints, newEndpoints = [], wsAuthType, options = {}) {
+export function draftScenariosFromEndpoints(endpoints, newEndpoints = [], wsAuthType, options = {}, removedEndpoints = []) {
     const scenarios = [];
     const resourceGroups = new Map();
     for (const ep of endpoints) {
@@ -191,6 +191,28 @@ export function draftScenariosFromEndpoints(endpoints, newEndpoints = [], wsAuth
     }
     scenarios.push(...draftDiffDirectScenarios(newEndpoints, resourceGroups, wsAuthType));
     scenarios.push(...draftAttackSurfaceExpansionScenarios(endpoints, options.changedEndpoints ?? [], wsAuthType, options.securityRelevantDiff ?? false));
+    // 404-guard scenarios for removed endpoints — absence assertions confirming
+    // the endpoint is gone. Single-step contract tests, no chaining needed.
+    for (const ep of removedEndpoints) {
+        scenarios.push({
+            scenarioName: `verify-removed-${ep.method.toLowerCase()}-${ep.path.replace(/[^a-z0-9]+/gi, "-").replace(/^-|-$/g, "")}`,
+            description: `Verify ${ep.method} ${ep.path} returns 404 — endpoint was removed in this PR`,
+            category: "breaking_change",
+            priority: "high",
+            steps: [{
+                    order: 1,
+                    method: ep.method,
+                    path: ep.path,
+                    description: `${ep.method} ${ep.path} → 404 (endpoint removed)`,
+                    interactionType: "error",
+                    expectedStatusCode: 404,
+                }],
+            chainingKeys: [],
+            requiresAuth: false,
+            estimatedComplexity: "simple",
+            source: ScenarioSource.CodeInferred,
+        });
+    }
     return capScenarios(scenarios);
 }
 const MAX_TOTAL_SCENARIOS = 30;