@skyramp/mcp 0.2.9 → 0.2.10-rc.1

package/build/utils/frontendIntegration.js

@@ -0,0 +1,237 @@
+/**
+ * Server-side "frontend component integration check" — SKYR-3855.
+ *
+ * Deterministically answers the question the testbot prompt previously asked
+ * the agent to answer via a mid-run grep: "is this changed frontend file
+ * actually rendered anywhere in the running app, or is it dead/orphaned
+ * code?" Computed here so the skip decision for UI test generation consumes
+ * a server fact instead of an LLM judgment call made under budget pressure.
+ *
+ * Detection greps for the module's PATH-REFERENCE SIGNATURE — the basename
+ * preceded by a slash and followed by a quote (`/Foo'`, `/Foo"`, `/Foo\``) —
+ * rather than the bare component name. Imports always reference the module
+ * path in quotes (`from './Foo'`, `require("components/Foo")`,
+ * `import('./Foo')`), so the signature carries import-context precision
+ * lexically: no per-line verification, no file reads in Node, and `git grep
+ * -l -F` returns only matching paths (bounded output regardless of file
+ * sizes). Named imports that go through a barrel resolve one hop: the
+ * barrel's `export { Foo } from './Foo'` contains the signature, and the
+ * barrel counts as the importer. Known miss: extensionless root-level
+ * imports with no slash (`from 'Foo'`) — root files are route/entrypoint
+ * short-circuited in practice.
+ *
+ * Fail-open by design: any scan failure reports `integrated: true` so a bug
+ * in this heuristic can never wrongly suppress UI test generation.
+ */
+import { execFileSync } from "child_process";
+import * as fs from "fs";
+import * as path from "path";
+import { isTestFile } from "../prompts/test-recommendation/scopeAssessment.js";
+import { logger } from "./logger.js";
+import { IntegrationReason } from "../types/FrontendIntegration.js";
+const MAX_IMPORTERS = 10;
+const MAX_FILES_WALKED = 3000;
+const MAX_FILE_SIZE_BYTES = 512 * 1024;
+// Framework route/page/entrypoint conventions — mirrors the testbot prompt's
+// "Never apply the unintegrated heuristic to framework route/entrypoint files"
+// rule. These are reachable by convention, so the grep is skipped entirely.
+// `app` is deliberately NOT in the dir pattern: it is a common generic
+// monorepo directory (e.g. appsmith's top-level app/), and matching it made
+// the check inert for every file in such repos (eval run 28618761653).
+// Next.js App Router route files are still short-circuited via their
+// basenames (page.*, layout.*); non-route components under app/ resolve
+// through the importer grep like any other file.
+const ROUTE_DIR_PATTERN = /(^|\/)(pages|routes)(\/|$)/i;
+// Generic entrypoint basenames (index/main/app/_app) are only reachable-by-
+// convention at the repo root or directly under `src/` — e.g. Vite's
+// `src/main.tsx`, CRA's `src/index.tsx`, Pages Router's root `_app.tsx`.
+// Deeper in the tree these are ordinary component filenames (folder-per-
+// component layouts commonly name the component file `index.tsx`), so
+// matching them anywhere would short-circuit real, checkable components —
+// the same class of bug as the `app/` dir match (see module doc).
+const ROOT_ENTRYPOINT_BASENAME_PATTERN = /^(src\/)?(index|main|app|_app)\.[^/]+$/i;
+// `page`/`layout` are App Router-specific and only meaningful under an
+// `app/` segment; outside of one, a file named `page.tsx` or `layout.tsx`
+// has no special framework meaning and should go through the normal check.
+const APP_ROUTER_BASENAME_PATTERN = /(^|\/)app\/(.*\/)?(page|layout)\.[^/]+$/i;
+// Frontend-importer file types only. Deliberately NOT shared with
+// analyzeChangesTool's SOURCE_EXTS (backend-inclusive: py|java|go|…) or
+// repoScanner's ROUTE_FILE_PATTERN — those detect backend route handlers;
+// this detects files that can render a frontend component. The domains must
+// stay independently tunable (see the `app/` route-dir lesson above).
+const FRONTEND_SOURCE_EXT_PATTERN = /\.(ts|tsx|js|jsx|mjs|cjs|vue|svelte)$/i;
+const STORY_FILE_PATTERN = /\.stories\.[^/]+$/i;
+const EXCLUDED_DIR_PATTERN = /(^|\/)(node_modules|dist|build|\.git)(\/|$)/;
+function isRouteOrEntrypoint(file) {
+    return (ROUTE_DIR_PATTERN.test(file) ||
+        ROOT_ENTRYPOINT_BASENAME_PATTERN.test(file) ||
+        APP_ROUTER_BASENAME_PATTERN.test(file));
+}
+/**
+ * Fixed-string signatures that identify an import of `file` by module path.
+ * Extensionless (`/Foo'`) covers TS/JS convention; extension-included
+ * (`/Foo.vue'`) covers Vue/Svelte, where imports keep the extension.
+ */
+function buildPathSignatures(file) {
+    // path.extname/basename treat ".d.ts" as ext ".ts" + basename "Foo.d",
+    // which would build a signature ("/Foo.d'") that never matches a real
+    // import of "./Foo" — special-case the compound extension.
+    const isDts = /\.d\.ts$/i.test(file);
+    const ext = isDts ? ".d.ts" : path.extname(file);
+    const basename = isDts ? path.basename(file, ".d.ts") : path.basename(file, ext);
+    const quotes = [`'`, `"`, "`"];
+    const stems = [`/${basename}`, `/${basename}${ext}`];
+    return stems.flatMap((stem) => quotes.map((q) => `${stem}${q}`));
+}
+function isExcludedImporterPath(relPath) {
+    return (EXCLUDED_DIR_PATTERN.test(relPath) ||
+        isTestFile(relPath) ||
+        STORY_FILE_PATTERN.test(relPath) ||
+        !FRONTEND_SOURCE_EXT_PATTERN.test(relPath));
+}
+/**
+ * Runs `git grep -l -F` for the given fixed-string signatures (OR'd
+ * together) scoped to the repository's tracked files. Returns file paths
+ * relative to `repositoryPath` — only paths, never matched lines, so output
+ * stays bounded no matter how large the matching files are. An exit code of
+ * 1 means "no matches" — a normal outcome, not an error. Throws on real
+ * failures (not a git repo, git not installed) so the caller can fall back
+ * to a manual walk.
+ */
+function gitGrepFiles(repositoryPath, signatures) {
+    const args = ["grep", "-l", "-F", "-I"];
+    for (const signature of signatures)
+        args.push("-e", signature);
+    try {
+        const stdout = execFileSync("git", args, {
+            cwd: repositoryPath,
+            encoding: "utf8",
+            maxBuffer: 20 * 1024 * 1024,
+        });
+        return stdout.split("\n").filter(Boolean);
+    }
+    catch (err) {
+        if (err && err.status === 1)
+            return []; // no matches — not an error
+        throw err;
+    }
+}
+/**
+ * Bounded manual directory walk used only when `git grep` itself fails
+ * (e.g. not a git repository). Caps the number and size of files scanned so
+ * a huge repo can't turn a fallback path into a multi-minute scan or a
+ * large allocation.
+ *
+ * If the walk is cut off by `MAX_FILES_WALKED` before finding any importer,
+ * the "no importer" result can't be trusted — an importer may exist in the
+ * unscanned remainder. Per the module's fail-open contract, that ambiguity
+ * throws so the caller reports `scan-error` (`integrated: true`) instead of
+ * a false "no-importers".
+ */
+function manualWalkGrep(repositoryPath, signatures) {
+    const results = [];
+    let filesScanned = 0;
+    let truncated = false;
+    const stack = [repositoryPath];
+    walk: while (stack.length > 0) {
+        if (filesScanned >= MAX_FILES_WALKED) {
+            truncated = true;
+            break;
+        }
+        const dir = stack.pop();
+        let entries;
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            const abs = path.join(dir, entry.name);
+            // Normalize to forward slashes: on Windows, path.relative() returns
+            // "\\"-separated paths, but EXCLUDED_DIR_PATTERN/isTestFile assume "/".
+            const rel = path.relative(repositoryPath, abs).replace(/\\/g, "/");
+            if (entry.isDirectory()) {
+                if (EXCLUDED_DIR_PATTERN.test(rel + "/"))
+                    continue;
+                stack.push(abs);
+                continue;
+            }
+            if (!FRONTEND_SOURCE_EXT_PATTERN.test(entry.name))
+                continue;
+            if (filesScanned >= MAX_FILES_WALKED) {
+                truncated = true;
+                break walk;
+            }
+            filesScanned++;
+            try {
+                if (fs.statSync(abs).size > MAX_FILE_SIZE_BYTES)
+                    continue;
+                const content = fs.readFileSync(abs, "utf-8");
+                if (signatures.some((s) => content.includes(s)))
+                    results.push(rel);
+            }
+            catch {
+                continue;
+            }
+        }
+    }
+    if (truncated && results.length === 0) {
+        throw new Error(`manual-walk fallback truncated at ${MAX_FILES_WALKED} files with no importer found`);
+    }
+    return results;
+}
+function searchProductionImporters(repositoryPath, signatures) {
+    try {
+        return gitGrepFiles(repositoryPath, signatures);
+    }
+    catch (err) {
+        logger.warning("git grep failed for integration check — falling back to bounded manual walk", {
+            repositoryPath,
+            error: err instanceof Error ? err.message : String(err),
+        });
+        return manualWalkGrep(repositoryPath, signatures);
+    }
+}
+function checkOneFile(repositoryPath, file) {
+    if (isRouteOrEntrypoint(file)) {
+        return { file, integrated: true, importers: [], reason: IntegrationReason.RouteOrEntrypoint };
+    }
+    // A missing changed file (e.g. deleted, or an unexpected diff shape) means
+    // the classification can't be trusted — fail open rather than risk wrongly
+    // suppressing UI test generation.
+    if (!fs.existsSync(path.join(repositoryPath, file))) {
+        logger.warning("Integration check: changed file not found on disk — reporting integrated (fail-open)", {
+            file,
+        });
+        return { file, integrated: true, importers: [], reason: IntegrationReason.ScanError };
+    }
+    try {
+        const signatures = buildPathSignatures(file);
+        const importers = searchProductionImporters(repositoryPath, signatures)
+            .filter((candidate) => candidate !== file && !isExcludedImporterPath(candidate))
+            .slice(0, MAX_IMPORTERS);
+        return {
+            file,
+            integrated: importers.length > 0,
+            importers,
+            reason: importers.length > 0 ? IntegrationReason.Imported : IntegrationReason.NoImporters,
+        };
+    }
+    catch (err) {
+        logger.warning("Integration check scan failed — reporting integrated (fail-open)", {
+            file,
+            error: err instanceof Error ? err.message : String(err),
+        });
+        return { file, integrated: true, importers: [], reason: IntegrationReason.ScanError };
+    }
+}
+/**
+ * Checks each changed frontend file for a production importer — the
+ * deterministic version of the grep the testbot prompt used to ask the
+ * agent to run mid-task. See module doc for the signature-based approach
+ * and the fail-open rationale.
+ */
+export function checkFrontendFileIntegration(repositoryPath, changedFrontendFiles) {
+    return changedFrontendFiles.map((file) => checkOneFile(repositoryPath, file));
+}

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

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

package/build/utils/frontendIntegration.test.js

@@ -0,0 +1,229 @@
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+import { execFileSync } from "child_process";
+import { checkFrontendFileIntegration } from "./frontendIntegration.js";
+/** Creates a temp git repo, writes the given files, and stages them so
+ * `git grep` (which only searches tracked files by default) can find them. */
+function makeFixtureRepo(files) {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), "frontend-integration-"));
+    execFileSync("git", ["init", "-q"], { cwd: dir });
+    for (const [relPath, content] of Object.entries(files)) {
+        const abs = path.join(dir, relPath);
+        fs.mkdirSync(path.dirname(abs), { recursive: true });
+        fs.writeFileSync(abs, content);
+    }
+    execFileSync("git", ["add", "-A"], { cwd: dir });
+    return dir;
+}
+/** Same as makeFixtureRepo but NOT a git repo, to exercise the manual-walk
+ * fallback (`git grep` fails outright when the directory isn't a repo). */
+function makeNonGitFixture(files) {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), "frontend-integration-nogit-"));
+    for (const [relPath, content] of Object.entries(files)) {
+        const abs = path.join(dir, relPath);
+        fs.mkdirSync(path.dirname(abs), { recursive: true });
+        fs.writeFileSync(abs, content);
+    }
+    return dir;
+}
+describe("checkFrontendFileIntegration", () => {
+    it("marks a component imported by a production file as integrated, listing the importer", () => {
+        const repo = makeFixtureRepo({
+            "src/components/Foo.tsx": `export function Foo() { return null; }\n`,
+            "src/components/Bar.tsx": `import { Foo } from './Foo';\nexport function Bar() { return Foo(); }\n`,
+        });
+        const [result] = checkFrontendFileIntegration(repo, ["src/components/Foo.tsx"]);
+        expect(result.integrated).toBe(true);
+        expect(result.reason).toBe("imported");
+        expect(result.importers).toEqual(["src/components/Bar.tsx"]);
+    });
+    it("marks a component imported ONLY by test files as unintegrated", () => {
+        const repo = makeFixtureRepo({
+            "src/components/Foo.tsx": `export function Foo() { return null; }\n`,
+            "src/components/Foo.test.tsx": `import { Foo } from './Foo';\ntest('renders', () => Foo());\n`,
+            "src/components/__tests__/Foo.spec.tsx": `import { Foo } from './Foo';\n`,
+        });
+        const [result] = checkFrontendFileIntegration(repo, ["src/components/Foo.tsx"]);
+        expect(result.integrated).toBe(false);
+        expect(result.reason).toBe("no-importers");
+        expect(result.importers).toEqual([]);
+    });
+    it("short-circuits route/entrypoint files as integrated without grepping", () => {
+        const repo = makeFixtureRepo({
+            "src/pages/Dashboard.tsx": `export default function Dashboard() { return null; }\n`,
+        });
+        const [result] = checkFrontendFileIntegration(repo, ["src/pages/Dashboard.tsx"]);
+        expect(result).toEqual({
+            file: "src/pages/Dashboard.tsx",
+            integrated: true,
+            importers: [],
+            reason: "route-or-entrypoint",
+        });
+    });
+    it("counts a re-export barrel as an importer", () => {
+        const repo = makeFixtureRepo({
+            "src/components/Foo.tsx": `export function Foo() { return null; }\n`,
+            "src/components/index.ts": `export { Foo } from './Foo';\n`,
+        });
+        const [result] = checkFrontendFileIntegration(repo, ["src/components/Foo.tsx"]);
+        expect(result.integrated).toBe(true);
+        expect(result.importers).toEqual(["src/components/index.ts"]);
+    });
+    it("counts an oversized single-line bundle referencing the module path as an importer, unread", () => {
+        // A minified >512KB one-line file. Node never opens candidates — git
+        // grep -l only returns the path — so file size cannot cause a large
+        // allocation or blow the subprocess buffer.
+        const hugeBundle = `var m=require("./components/Foo");` + "a".repeat(600 * 1024);
+        const repo = makeFixtureRepo({
+            "src/components/Foo.tsx": `export function Foo() { return null; }\n`,
+            "src/vendor/bundle.js": hugeBundle,
+        });
+        const [result] = checkFrontendFileIntegration(repo, ["src/components/Foo.tsx"]);
+        expect(result.integrated).toBe(true);
+        expect(result.importers).toEqual(["src/vendor/bundle.js"]);
+    });
+    it("resolves importers of an oversized changed file (the changed file is never read)", () => {
+        const hugeComponent = `export function Foo() { return null; }\n// ` + "b".repeat(600 * 1024) + `\n`;
+        const repo = makeFixtureRepo({
+            "src/components/Foo.tsx": hugeComponent,
+            "src/components/Bar.tsx": `import Foo from './Foo';\nexport function Bar() { return Foo(); }\n`,
+        });
+        const [result] = checkFrontendFileIntegration(repo, ["src/components/Foo.tsx"]);
+        expect(result.integrated).toBe(true);
+        expect(result.reason).toBe("imported");
+        expect(result.importers).toEqual(["src/components/Bar.tsx"]);
+    });
+    it("catches multiline imports (the from-line carries the path signature)", () => {
+        const repo = makeFixtureRepo({
+            "src/components/Foo.tsx": `export function Foo() { return null; }\n`,
+            "src/components/Bar.tsx": `import {\n  Foo,\n} from "./Foo";\nexport function Bar() { return Foo(); }\n`,
+        });
+        const [result] = checkFrontendFileIntegration(repo, ["src/components/Foo.tsx"]);
+        expect(result.integrated).toBe(true);
+        expect(result.importers).toEqual(["src/components/Bar.tsx"]);
+    });
+    it("does not count bare-name mentions (comments, strings) as importers", () => {
+        // The precision property of the path-signature design: a dead component
+        // whose NAME appears in prose elsewhere must still read as unintegrated.
+        const repo = makeFixtureRepo({
+            "src/components/Foo.tsx": `export function Foo() { return null; }\n`,
+            "src/components/Other.tsx": `// TODO: consolidate with Foo someday\nconst label = "Foo";\nexport function Other() { return label; }\n`,
+        });
+        const [result] = checkFrontendFileIntegration(repo, ["src/components/Foo.tsx"]);
+        expect(result.integrated).toBe(false);
+        expect(result.reason).toBe("no-importers");
+        expect(result.importers).toEqual([]);
+    });
+    it("does not short-circuit components under a generic top-level app/ monorepo dir", () => {
+        // Regression: appsmith's repo root is `app/` — matching it as a framework
+        // route dir made the check inert for the whole repo (eval 28618761653).
+        const repo = makeFixtureRepo({
+            "app/client/src/components/Orphan.tsx": `export function Orphan() { return null; }\n`,
+        });
+        const [result] = checkFrontendFileIntegration(repo, ["app/client/src/components/Orphan.tsx"]);
+        expect(result.integrated).toBe(false);
+        expect(result.reason).toBe("no-importers");
+    });
+    it("still short-circuits Next.js App Router route files via their basenames", () => {
+        const repo = makeFixtureRepo({
+            "src/app/dashboard/page.tsx": `export default function Dashboard() { return null; }\n`,
+        });
+        const [result] = checkFrontendFileIntegration(repo, ["src/app/dashboard/page.tsx"]);
+        expect(result.integrated).toBe(true);
+        expect(result.reason).toBe("route-or-entrypoint");
+    });
+    it("fails open (scan-error, integrated: true) when the changed file does not exist on disk", () => {
+        const repo = makeFixtureRepo({
+            "src/components/Bar.tsx": `export function Bar() { return null; }\n`,
+        });
+        const [result] = checkFrontendFileIntegration(repo, ["src/components/Deleted.tsx"]);
+        expect(result).toEqual({
+            file: "src/components/Deleted.tsx",
+            integrated: true,
+            importers: [],
+            reason: "scan-error",
+        });
+    });
+    it("finds an importer of a .d.ts declaration file", () => {
+        // Regression: path.extname("Foo.d.ts") is ".ts", so a naive basename/ext
+        // split would build a signature for "Foo.d" instead of "Foo" and never
+        // match a real `from "./Foo"` import.
+        const repo = makeFixtureRepo({
+            "src/components/Foo.d.ts": `export declare function Foo(): null;\n`,
+            "src/components/Bar.tsx": `import { Foo } from './Foo';\nexport function Bar() { return Foo(); }\n`,
+        });
+        const [result] = checkFrontendFileIntegration(repo, ["src/components/Foo.d.ts"]);
+        expect(result.integrated).toBe(true);
+        expect(result.reason).toBe("imported");
+        expect(result.importers).toEqual(["src/components/Bar.tsx"]);
+    });
+    describe("basename short-circuit precision", () => {
+        it("does NOT short-circuit a folder-per-component index.tsx as a route/entrypoint", () => {
+            // Regression: matching "index"/"main"/"app" basenames anywhere in the
+            // tree (not just at the root or src/) would short-circuit the common
+            // React folder-per-component convention (Button/index.tsx) as always
+            // integrated, defeating the check for exactly the files it targets.
+            const repo = makeFixtureRepo({
+                "src/components/Button/index.tsx": `export function Button() { return null; }\n`,
+            });
+            const [result] = checkFrontendFileIntegration(repo, ["src/components/Button/index.tsx"]);
+            expect(result.integrated).toBe(false);
+            expect(result.reason).toBe("no-importers");
+        });
+        it("still short-circuits a root-level src/index.tsx entrypoint", () => {
+            const repo = makeFixtureRepo({
+                "src/index.tsx": `export default function App() { return null; }\n`,
+            });
+            const [result] = checkFrontendFileIntegration(repo, ["src/index.tsx"]);
+            expect(result).toEqual({
+                file: "src/index.tsx",
+                integrated: true,
+                importers: [],
+                reason: "route-or-entrypoint",
+            });
+        });
+        it("does NOT short-circuit a page.tsx outside an app/ segment", () => {
+            // "page"/"layout" are App Router-specific; outside an app/ segment they
+            // are ordinary component filenames with no framework meaning.
+            const repo = makeFixtureRepo({
+                "src/components/page.tsx": `export function Page() { return null; }\n`,
+            });
+            const [result] = checkFrontendFileIntegration(repo, ["src/components/page.tsx"]);
+            expect(result.integrated).toBe(false);
+            expect(result.reason).toBe("no-importers");
+        });
+    });
+    describe("manual-walk fallback (non-git repos)", () => {
+        it("falls back to a manual walk and finds an importer when the directory isn't a git repo", () => {
+            const repo = makeNonGitFixture({
+                "src/components/Foo.tsx": `export function Foo() { return null; }\n`,
+                "src/components/Bar.tsx": `import { Foo } from './Foo';\nexport function Bar() { return Foo(); }\n`,
+            });
+            const [result] = checkFrontendFileIntegration(repo, ["src/components/Foo.tsx"]);
+            expect(result.integrated).toBe(true);
+            expect(result.reason).toBe("imported");
+            expect(result.importers).toEqual(["src/components/Bar.tsx"]);
+        });
+        it("fails open (scan-error) when the fallback walk is truncated before finding an importer", () => {
+            // Regression: the module doc promises fail-open on any scan error/
+            // uncertainty, but a truncated manual walk used to just return its
+            // partial (empty) result set, reporting a confident "no-importers"
+            // even though an importer could exist past the file cap.
+            const files = {
+                "src/components/Foo.tsx": `export function Foo() { return null; }\n`,
+            };
+            for (let i = 0; i < 3005; i++) {
+                files[`src/generated/File${i}.tsx`] = `export const noop${i} = 0;\n`;
+            }
+            const repo = makeNonGitFixture(files);
+            const [result] = checkFrontendFileIntegration(repo, ["src/components/Foo.tsx"]);
+            expect(result).toEqual({
+                file: "src/components/Foo.tsx",
+                integrated: true,
+                importers: [],
+                reason: "scan-error",
+            });
+        });
+    });
+});

package/build/utils/pr-comment-parser.d.ts

@@ -1,7 +1,7 @@
 /**
- * PR Comment Parser — extracts TestBot history from GitHub PR comments.
+ * PR Comment Parser — extracts Testbot history from GitHub PR comments.
  *
- * Parses previous Skyramp TestBot comments on a PR to build context
+ * Parses previous Skyramp Testbot comments on a PR to build context
  * about what has already been recommended, implemented, and tested.
  * This prevents re-recommendations and enables contextual awareness
  * across the PR lifecycle.
@@ -23,7 +23,7 @@ export interface PRTestContext {
     }>;
 }
 /**
- * Fetch and parse PR comments to build TestBot history context.
+ * Fetch and parse PR comments to build Testbot history context.
  *
  * Uses the `gh` CLI (available in CI and local dev environments with
  * GitHub CLI installed). Falls back gracefully if `gh` is unavailable.

package/build/utils/pr-comment-parser.js

@@ -1,7 +1,7 @@
 /**
- * PR Comment Parser — extracts TestBot history from GitHub PR comments.
+ * PR Comment Parser — extracts Testbot history from GitHub PR comments.
  *
- * Parses previous Skyramp TestBot comments on a PR to build context
+ * Parses previous Skyramp Testbot comments on a PR to build context
  * about what has already been recommended, implemented, and tested.
  * This prevents re-recommendations and enables contextual awareness
  * across the PR lifecycle.
@@ -16,7 +16,7 @@ const TESTBOT_MARKERS = [
 const TEST_TYPE_PATTERN = /\b(Smoke|Contract|Integration|Fuzz|Load|E2E|UI)\b/gi;
 const TEST_FILE_PATTERN = /[\w/.-]+(?:_test|_smoke|_contract|_fuzz|_integration|_load|_e2e|_ui)\.\w+/gi;
 const STATUS_PATTERN = /\b(Pass|Fail|Skipped)\b/gi;
-function isTestBotComment(comment) {
+function isTestbotComment(comment) {
     const hasMarker = TESTBOT_MARKERS.some((marker) => comment.body.includes(marker));
     if (!hasMarker)
         return false;
@@ -191,7 +191,7 @@ function extractImplementedFiles(body) {
     return [...new Set(matches.map((m) => m[0]))];
 }
 /**
- * Fetch and parse PR comments to build TestBot history context.
+ * Fetch and parse PR comments to build Testbot history context.
  *
  * Uses the `gh` CLI (available in CI and local dev environments with
  * GitHub CLI installed). Falls back gracefully if `gh` is unavailable.
@@ -228,11 +228,11 @@ export async function parsePRComments(repoOwner, repoName, prNumber, _token) {
         logger.warning("Failed to parse PR comments JSON");
         return empty;
     }
-    const testBotComments = comments.filter((c) => isTestBotComment(c));
+    const testBotComments = comments.filter((c) => isTestbotComment(c));
     if (testBotComments.length === 0) {
         return empty;
     }
-    // Use only the latest TestBot comment — older comments represent stale
+    // Use only the latest Testbot comment — older comments represent stale
     // state from previous bot runs. The latest comment has the most accurate
     // picture of what was recommended, generated, and executed.
     const latestComment = testBotComments[testBotComments.length - 1];

package/build/utils/pr-comment-parser.test.js

@@ -163,7 +163,7 @@ describe("parsePRComments — error handling", () => {
         expect(ctx.implementedTestFiles).toEqual([]);
         expect(ctx.executionResults).toEqual([]);
     });
-    it("returns empty context when no TestBot comments exist", async () => {
+    it("returns empty context when no Testbot comments exist", async () => {
         mockedExecFileSync.mockReturnValue(ghResponse([
             { id: 1, body: "LGTM!", login: "reviewer" },
             { id: 2, body: "Please fix the typo", login: "reviewer" },
@@ -173,7 +173,7 @@ describe("parsePRComments — error handling", () => {
         expect(ctx.implementedTestFiles).toEqual([]);
         expect(ctx.executionResults).toEqual([]);
     });
-    it("uses only the latest TestBot comment when multiple exist", async () => {
+    it("uses only the latest Testbot comment when multiple exist", async () => {
         const olderReport = progressWrapper(`### 📋 Business Case Analysis
 Old report.
 
@@ -347,7 +347,7 @@ describe("edge cases", () => {
         const count = ctx.implementedTestFiles.filter((f) => f === "test_items_integration.py").length;
         expect(count).toBe(1);
     });
-    it("handles empty TestBot comment body", async () => {
+    it("handles empty Testbot comment body", async () => {
         mockedExecFileSync.mockReturnValue(ghResponse([{ id: 1, body: "Skyramp Testbot — empty run" }]));
         const ctx = await parsePRComments("owner", "repo", 1);
         expect(ctx.previousRecommendations).toEqual([]);

package/build/utils/repoScanner.d.ts

@@ -2,6 +2,13 @@ export interface ScannedEndpoint {
     path: string;
     methods: string[];
     sourceFile: string;
+    /**
+     * 1-based line number of the route's declaration in `sourceFile`, when known.
+     * Used by hunk-aware diff scoping to attribute a changed line to the single
+     * route that owns it (rather than flagging every route in a touched file).
+     * Optional — absence disables scoping and falls back to file-level matching.
+     */
+    line?: number;
 }
 /**
  * Returns the relative paths of entry-point files that define the routing

package/build/utils/repoScanner.js

@@ -101,16 +101,22 @@ export function grepRouterMountingContext(repositoryPath) {
     }
     return found;
 }
-function addEndpointToMap(endpointMap, apiPath, method, sourceFile, repositoryPath) {
+function addEndpointToMap(endpointMap, apiPath, method, sourceFile, repositoryPath, line) {
     const relative = sourceFile.startsWith(repositoryPath)
         ? sourceFile.slice(repositoryPath.length + 1) : sourceFile;
     const normalizedPath = apiPath.startsWith("/") ? apiPath : `/${apiPath}`;
     const key = `${relative}::${normalizedPath}`;
     const existing = endpointMap.get(key);
-    if (existing)
+    if (existing) {
         existing.methods.add(method);
-    else
-        endpointMap.set(key, { path: normalizedPath, methods: new Set([method]), sourceFile: relative });
+        // Keep the earliest declaration line so ownership-range scoping starts there.
+        if (typeof line === "number" && (existing.line === undefined || line < existing.line)) {
+            existing.line = line;
+        }
+    }
+    else {
+        endpointMap.set(key, { path: normalizedPath, methods: new Set([method]), sourceFile: relative, line });
+    }
 }
 function scanNextjsFile(file, repositoryPath, endpointMap) {
     const relative = file.startsWith(repositoryPath)
@@ -239,13 +245,14 @@ export function scanAllRepoEndpoints(repositoryPath) {
         if (content === null)
             continue;
         for (const ep of parseFileEndpoints(content, relative)) {
-            addEndpointToMap(endpointMap, ep.path, ep.method, file, repositoryPath);
+            addEndpointToMap(endpointMap, ep.path, ep.method, file, repositoryPath, ep.line);
         }
     }
     return Array.from(endpointMap.values()).map((data) => ({
         path: data.path,
         methods: Array.from(data.methods),
         sourceFile: data.sourceFile,
+        ...(data.line !== undefined ? { line: data.line } : {}),
     }));
 }
 export function scanRelatedEndpoints(repositoryPath, changedFiles) {
@@ -273,7 +280,7 @@ export function scanRelatedEndpoints(repositoryPath, changedFiles) {
             if (fileContent === null)
                 continue;
             for (const ep of parseFileEndpoints(fileContent, relative)) {
-                addEndpointToMap(endpointMap, ep.path, ep.method, file, repositoryPath);
+                addEndpointToMap(endpointMap, ep.path, ep.method, file, repositoryPath, ep.line);
             }
         }
     }
@@ -281,5 +288,6 @@ export function scanRelatedEndpoints(repositoryPath, changedFiles) {
         path: data.path,
         methods: Array.from(data.methods),
         sourceFile: data.sourceFile,
+        ...(data.line !== undefined ? { line: data.line } : {}),
     }));
 }