@skyramp/mcp 0.3.8 → 0.4.0-rc.1

package/build/services/ModularizationService.js

@@ -1,3 +1,4 @@
+import { fixErrorsInstruction } from "../skills/fixTestImportErrorsSkill.js";
 import { TestType } from "../types/TestTypes.js";
 import { getModularizationPrompt as getModularizationPromptForUI } from "../prompts/modularization/ui-test-modularization.js";
 import { getModularizationPrompt as getModularizationPromptForIntegration } from "../prompts/modularization/integration-test-modularization.js";
@@ -47,7 +48,7 @@ The test file \`${params.testFile}\` will remain unchanged. No further action is
 1. Read the test file using the 'read_file' tool
 2. Create the modularized version following the instructions above
 3. Use the 'write' tool (NOT search_replace) to save the complete modularized code to the file
-4. After modularization is complete, proceed to skyramp_fix_errors tool if there are any errors`,
+4. After modularization is complete, if there are any errors, ${fixErrorsInstruction()}`,
                 },
             ],
         };

package/build/services/TestDiscoveryService.d.ts

@@ -4,41 +4,6 @@ interface TestDiscoveryResult {
     /** Paths of external files that were deemed relevant to the PR (score > 0). */
     relevantExternalTestPaths: string[];
 }
-export interface TestDiscoveryOptions {
-    /**
-     * Resource names derived from endpoints in changed files (e.g. ["orders", "products"]).
-     * - Non-empty array: external files partitioned by relevance; only relevant files
-     *   get full endpoint extraction. May be the sentinel `["unknown"]` when endpoints
-     *   exist but resource names are unresolvable — most files score 0 (low-relevance)
-     *   and are excluded; only the few that happen to match the sentinel are kept.
-     * - Empty array `[]`: PR mode with no endpoints from diff or scanner — API/integration
-     *   external tests are excluded entirely; UI tests may still be promoted via changedFrontendFiles.
-     * - `undefined`: full-repo mode — external tests capped at MAX_EXTERNAL_FULL_REPO.
-     */
-    changedResources?: string[];
-    /** Raw changed symbol names (e.g. ["DeploymentCreate"]). Content-grep fallback so an
-     *  external test that references a changed type by name — but whose path/URL matches no
-     *  changed resource (e.g. a schema unit test) — is still surfaced (SKYR-3924). */
-    changedSymbols?: string[];
-    /** True when `changedResources` are precise (derived from specific changed schema/model
-     *  symbols, not the `["unknown"]` sentinel or a broad set). Lets the URL content-match
-     *  bucket skip the MAX_CONTENT_PROMOTED cap — a direct HTTP call to the changed endpoint
-     *  is high-confidence, and the specific resource set naturally bounds the match count. */
-    preciseResources?: boolean;
-    /** Repo-relative paths of the changed frontend (non-test) files — their presence is the
-     *  frontend-change signal that drives UI-test promotion (Step 2). When present, promotion
-     *  is scoped to tests whose name/path/imports are relevant to these files — a frontend PR
-     *  must not pull in the whole monorepo's UI test suite (SKYR-3941). When absent, Step 2 is
-     *  skipped (no UI promotion). */
-    changedFrontendFiles?: string[];
-    /** Selector literals (data-testid values, CSS class tokens) added or removed by the diff.
-     *  UI-test promotion pass 3 ("selector-edge"): a page object / spec couples to a changed
-     *  component by SELECTOR, not by filename or import, so passes 1-2 miss it. Any external
-     *  test-owned file (including page objects, which are not *.test/*.spec) whose body
-     *  references one of these literals is promoted. Both added and removed values are passed
-     *  so a page object still holding a renamed selector's OLD value is caught. */
-    changedSelectors?: string[];
-}
 export declare class TestDiscoveryService {
     private readonly EXCLUDED_DIRS;
     private readonly SKYRAMP_MARKER;
@@ -50,44 +15,10 @@ export declare class TestDiscoveryService {
      * Uses fast-glob for cross-platform file scanning, then classifies discovered files
      * as Skyramp-generated tests, external tests, or not-a-test during processing.
      *
-     * External test handling depends on `options.changedResources`:
-     * - `string[]` with entries (PR mode, endpoints detected): partition by relevance.
-     * - `[]` empty array (PR mode, scanner found no endpoints): skip external tests entirely
-     *   rather than flooding context with irrelevant files.
-     * - `undefined` (full-repo mode, no diff): cap at MAX_EXTERNAL_FULL_REPO.
-     */
-    discoverTests(testDir: string, options?: TestDiscoveryOptions): Promise<TestDiscoveryResult>;
-    /**
-     * Score an external test file's relevance to a set of changed resource names.
-     * Tokenises the last two segments of the file path (split by /, \, -, _, .)
-     * and counts overlapping tokens with the changed resources.
-     * Example: "test_orders_api.py" vs ["orders"] → score 1.
-     */
-    private scoreRelevance;
-    /**
-     * Derive relevance tokens from the changed frontend files, for scoring UI tests in Step 2
-     * the same way scoreRelevance scores against changed API resources. For each file we emit:
-     *  - the basename stem (e.g. "OrderSearch" → "ordersearch") — matches co-located tests like
-     *    OrderSearch.test.tsx, the dominant convention;
-     *  - its sub-tokens, split on delimiters AND camelCase boundaries ("OrderSearch" →
-     *    "order","search") — matches hyphenated/underscored test names like order-search.spec.tsx;
-     *  - the parent directory name — the signal when the basename is generic (orders/index.tsx).
-     * Generic tokens (index, components, utils, …) and tokens shorter than 3 chars are dropped so
-     * a shared dir or an index file doesn't match every UI test in the repo.
-     */
-    private deriveFrontendResourceTokens;
-    private readonly MAX_CONTENT_PROMOTED;
-    private readonly MAX_UI_PROMOTED;
-    private readonly UI_IMPORT_MATCH_WEIGHT;
-    private readonly GENERIC_FRONTEND_TOKENS;
-    /**
-     * Partition external test files into relevant (score > 0) and low-relevance (score = 0).
-     * Two-pass: filename token overlap first (primary); content-based endpoint path scan
-     * as a capped fallback for tests misnamed relative to the endpoint they exercise
-     * (e.g. test_checkout_flow.py testing /api/orders scores 0 by name but matches in content).
-     * Content matches are capped at MAX_CONTENT_PROMOTED to bound token impact.
+     * External tests are capped at MAX_EXTERNAL_FULL_REPO: nothing narrows them by
+     * relevance any more.
      */
-    private partitionByRelevance;
+    discoverTests(testDir: string): Promise<TestDiscoveryResult>;
     /**
      * Process test files in parallel batches with concurrency control
      * @param isExternal When true, uses external test metadata extraction

package/build/services/TestDiscoveryService.js

@@ -3,7 +3,6 @@ import * as path from "path";
 import { logger } from "../utils/logger.js";
 import { TestSource } from "../types/TestAnalysis.js";
 import { TestType } from "../types/TestTypes.js";
-import { buildPathSignatures } from "../utils/pathSignatures.js";
 import fg from "fast-glob";
 import { isDiscoveredTestFile } from "../utils/testFileClassification.js";
 export class TestDiscoveryService {
@@ -40,13 +39,10 @@ export class TestDiscoveryService {
      * Uses fast-glob for cross-platform file scanning, then classifies discovered files
      * as Skyramp-generated tests, external tests, or not-a-test during processing.
      *
-     * External test handling depends on `options.changedResources`:
-     * - `string[]` with entries (PR mode, endpoints detected): partition by relevance.
-     * - `[]` empty array (PR mode, scanner found no endpoints): skip external tests entirely
-     *   rather than flooding context with irrelevant files.
-     * - `undefined` (full-repo mode, no diff): cap at MAX_EXTERNAL_FULL_REPO.
+     * External tests are capped at MAX_EXTERNAL_FULL_REPO: nothing narrows them by
+     * relevance any more.
      */
-    async discoverTests(testDir, options = {}) {
+    async discoverTests(testDir) {
         logger.info(`Starting test discovery in: ${testDir}`);
         const stats = fs.statSync(testDir, { throwIfNoEntry: false });
         if (!stats)
@@ -59,144 +55,13 @@ export class TestDiscoveryService {
         // Process Skyramp tests (content already cached from classification)
         const skyrampTests = await this.processFilesInBatches(classified.skyramp, false, classified.contentCache);
         skyrampTests.forEach(t => { t.source = TestSource.Skyramp; });
-        // Partition external tests into relevant (full extraction) and low-relevance (name-only).
-        //
-        // PR mode + endpoints detected (changedResources is non-empty array):
-        //   Files whose path/name token-overlaps with the changed resource names are "relevant".
-        //   Only they get full endpoint extraction. Low-relevance files get name-only entries.
-        //   No hard cap — the relevance filter naturally bounds the read set to PR scope.
-        //   The sentinel ["unknown"] falls into this branch — most files score 0 (low-relevance)
-        //   and get name-only entries, so external coverage is preserved without context flood.
-        //
-        // PR mode + truly no endpoints (changedResources is empty array []):
-        //   Diff contained no endpoints at all (new, modified, or removed) — skip external
-        //   tests entirely rather than flooding the prompt with hundreds of irrelevant files.
-        //
-        // Full-repo mode (changedResources is undefined):
-        //   No diff context — all external files treated as potentially relevant.
-        //   Cap at MAX_EXTERNAL_FULL_REPO to avoid reading hundreds of files.
-        const { changedResources, changedSymbols, preciseResources, changedFrontendFiles, changedSelectors } = options;
-        let relevantExternal;
-        // Includes .e2e.ts — Playwright/Cypress tests that navigate pages. These get
-        // testType="e2e" from path detection but are never named *.test.ts or *.spec.ts
-        // so without explicit promotion they'd be excluded from stateData.existingTests,
-        // making the server-side symbol grep unable to find them.
-        const UI_TEST_EXT = /\.(test|spec|e2e)\.(tsx|jsx|ts|js)$/;
-        const SEC_EXT = /\.(snap|ambr|txt|yml|yaml)$/;
-        // Step 1 — API relevance partitioning (driven by changedResources).
-        // Two-pass: filename token overlap first, then content-based endpoint path scan
-        // for tests that are misnamed relative to the endpoint they exercise.
-        if (changedResources?.length) {
-            ({ relevant: relevantExternal } =
-                this.partitionByRelevance(classified.external, changedResources, classified.contentCache, changedSymbols, preciseResources));
-        }
-        else if (changedResources !== undefined) {
-            relevantExternal = [];
-        }
-        else {
-            relevantExternal = classified.external.slice(0, this.MAX_EXTERNAL_FULL_REPO);
-        }
-        // Step 2 — UI test promotion, driven by the presence of changed frontend files and
-        // independent of Step 1. Scoped by relevance to those files, mirroring Step 1's API
-        // discipline: a frontend PR must not pull in the whole monorepo's UI test suite (SKYR-3941).
-        // Absent a changed-frontend-file list, Step 2 is skipped (no UI promotion).
-        if (changedFrontendFiles?.length) {
-            const alreadyRelevant = new Set(relevantExternal);
-            const uiCandidates = classified.external.filter(f => UI_TEST_EXT.test(f) && !alreadyRelevant.has(f));
-            // Pass 1 — filename/path relevance: tokens derived from the changed frontend files.
-            const feTokens = this.deriveFrontendResourceTokens(changedFrontendFiles);
-            // Pass 2 — import-edge relevance: module-path signatures of the changed files, matched
-            // against test bodies so a test that imports a changed component (from './PriceLabel')
-            // is caught even when its name shares no token — the recall case a filename-only filter
-            // drops (a checkout test that renders a changed child component). Reuses the same
-            // buildPathSignatures used by frontendIntegration/importerHop; this is Step 2's analog
-            // of Step 1's content-scan fallback. Skip generic basenames (index/app/…): their
-            // signature (`/index'`) would match every barrel import — those are already covered by
-            // pass 1's parent-directory token.
-            const importSignatures = changedFrontendFiles
-                .filter(f => {
-                const stem = path.basename(f).replace(/\.[^.]+$/, "").toLowerCase();
-                return stem.length >= 3 && !this.GENERIC_FRONTEND_TOKENS.has(stem);
-            })
-                .flatMap(f => buildPathSignatures(f));
-            let promoted;
-            if (feTokens.length === 0 && importSignatures.length === 0) {
-                // No relevance signal is derivable — every changed frontend file is a generic
-                // entrypoint (index.tsx / app.tsx / …) whose tokens are filtered out, and none
-                // yields an import signature. A root/entrypoint change is broadly impactful, so
-                // fall back to promoting all UI candidates rather than degenerate to zero — still
-                // bounded by MAX_UI_PROMOTED so it can't re-flood a large monorepo's suite.
-                promoted = uiCandidates.slice(0, this.MAX_UI_PROMOTED);
-                const dropped = uiCandidates.length - promoted.length;
-                logger.info(`UI test promotion: no relevance signal from generic-only frontend changes — capped promote-all fallback (${promoted.length}/${uiCandidates.length} promoted${dropped > 0 ? `, ${dropped} dropped by MAX_UI_PROMOTED` : ""})`);
-            }
-            else {
-                let scored = uiCandidates
-                    .map(f => {
-                    const nameScore = this.scoreRelevance(f, feTokens);
-                    const content = classified.contentCache.get(f) ?? "";
-                    const importsChanged = content.length > 0 && importSignatures.some(sig => content.includes(sig));
-                    return { f, score: nameScore + (importsChanged ? this.UI_IMPORT_MATCH_WEIGHT : 0) };
-                })
-                    .filter(x => x.score > 0)
-                    .sort((a, b) => b.score - a.score)
-                    .map(x => x.f);
-                if (scored.length > this.MAX_UI_PROMOTED) {
-                    logger.info(`UI test promotion: ${scored.length} tests matched ${changedFrontendFiles.length} changed frontend file(s); capping to ${this.MAX_UI_PROMOTED} highest-scoring (SKYR-3941 backstop)`);
-                    scored = scored.slice(0, this.MAX_UI_PROMOTED);
-                }
-                logger.info(`UI test promotion scoped to ${scored.length}/${uiCandidates.length} UI test(s) relevant to changed frontend files`);
-                promoted = scored;
-            }
-            // Pass 3 — selector-edge: a page object / spec couples to a changed component by
-            // SELECTOR (data-testid value or CSS class), not by filename or import, so passes
-            // 1-2 miss it. Crucially the candidate pool here is the FULL external set, not just
-            // UI_TEST_EXT: a page object like `table.component.ts` is classified external (via
-            // the page-objects/ dir pattern) with content cached, but is not a *.test/*.spec
-            // file, so it never enters `uiCandidates`. Promote any not-yet-relevant external
-            // file whose body references a changed selector literal (matched against both the
-            // added and removed diff values, so a page object still holding a renamed selector's
-            // OLD value is caught). Bounded by MAX_UI_PROMOTED.
-            // Combined cap: MAX_UI_PROMOTED is a single Step-2 ceiling, so pass 3 may only add up
-            // to what pass 1/2 left — otherwise the two independent caps could promote 2x and
-            // re-flood discovery (the exact failure SKYR-3941 guards against). Compute the headroom
-            // up front and skip the O(external × selectors) content scan entirely when pass 1/2
-            // already filled the budget.
-            const selectorHeadroom = Math.max(0, this.MAX_UI_PROMOTED - promoted.length);
-            if (changedSelectors?.length && selectorHeadroom > 0) {
-                const alreadyPromoted = new Set([...alreadyRelevant, ...promoted]);
-                const selectorMatched = classified.external
-                    .filter((f) => {
-                    if (alreadyPromoted.has(f))
-                        return false;
-                    const content = classified.contentCache.get(f) ?? "";
-                    return content.length > 0 && changedSelectors.some((sel) => content.includes(sel));
-                })
-                    // Sort for a deterministic cap — filesystem/glob traversal order is not stable
-                    // across environments, so which files survive MAX_UI_PROMOTED must not depend on it.
-                    .sort();
-                if (selectorMatched.length > 0) {
-                    const capped = selectorMatched.slice(0, selectorHeadroom);
-                    logger.info(`UI test promotion: ${selectorMatched.length} test/page-object file(s) reference a changed selector (pass 3, selector-edge)` +
-                        (capped.length < selectorMatched.length ? `; added ${capped.length} (MAX_UI_PROMOTED headroom after pass 1/2)` : ""));
-                    if (capped.length > 0)
-                        promoted = [...promoted, ...capped];
-                }
-            }
-            const promotedSet = new Set(promoted);
-            // Promote snapshot/fixture siblings of scored AND newly promoted UI tests.
-            // Include promoted files so siblings are found on UI-only PRs where
-            // relevantExternal started empty before Step 2.
-            const relevantTestBasenames = new Set([...relevantExternal, ...promoted].filter(f => UI_TEST_EXT.test(f)).map(f => path.basename(f)));
-            const promotedSecondary = classified.external.filter(f => !alreadyRelevant.has(f) &&
-                !promotedSet.has(f) &&
-                relevantTestBasenames.has(path.basename(f).replace(SEC_EXT, '')));
-            const allPromoted = [...promoted, ...promotedSecondary];
-            if (allPromoted.length > 0) {
-                logger.info(`Promoting ${promoted.length} UI test + ${promotedSecondary.length} secondary file(s) for content reading`);
-                relevantExternal = [...relevantExternal, ...allPromoted];
-            }
-        }
+        // No diff context reaches this service: its one caller passes no options, so
+        // every external file is potentially relevant and the cap is what bounds the
+        // read set.
+        const relevantExternal = classified.external.slice(0, this.MAX_EXTERNAL_FULL_REPO);
+        // There is no Step 2 any more. It promoted UI tests by matching filename tokens
+        // against changed FRONTEND files, a list built by classifying paths on
+        // extension and directory. Every external test is already loaded.
         // Free content cache for external files not selected for full extraction.
         const relevantSet = new Set(relevantExternal);
         for (const f of classified.external) {
@@ -212,164 +77,6 @@ export class TestDiscoveryService {
             relevantExternalTestPaths: relevantExternal,
         };
     }
-    /**
-     * Score an external test file's relevance to a set of changed resource names.
-     * Tokenises the last two segments of the file path (split by /, \, -, _, .)
-     * and counts overlapping tokens with the changed resources.
-     * Example: "test_orders_api.py" vs ["orders"] → score 1.
-     */
-    scoreRelevance(filePath, changedResources) {
-        const normalized = filePath.toLowerCase().replace(/\\/g, "/");
-        // Use the last two path segments to avoid false matches from deeply-nested dirs
-        const segments = normalized.split("/").slice(-2).join("/");
-        const tokens = new Set(segments.split(/[/\-_.]+/).filter(Boolean));
-        // Expand tokens with plural/singular variants so "deployment" matches
-        // "deployments" and vice versa. Only strip trailing "s" when the result
-        // is ≥4 chars (avoids "pas"→"pa") and doesn't end in "ss" (avoids "pass"→"pas").
-        const expanded = new Set(tokens);
-        for (const t of tokens) {
-            if (t.endsWith("s") && !t.endsWith("ss") && t.length > 4)
-                expanded.add(t.slice(0, -1));
-            else if (!t.endsWith("s"))
-                expanded.add(t + "s");
-        }
-        return changedResources.filter(r => {
-            const rLower = r.toLowerCase();
-            if (expanded.has(rLower))
-                return true;
-            // Compound resource names (e.g. "order-items") — all parts must appear as tokens.
-            const parts = rLower.split(/[-_]/);
-            return parts.length > 1 && parts.every(p => p.length >= 3 && expanded.has(p));
-        }).length;
-    }
-    /**
-     * Derive relevance tokens from the changed frontend files, for scoring UI tests in Step 2
-     * the same way scoreRelevance scores against changed API resources. For each file we emit:
-     *  - the basename stem (e.g. "OrderSearch" → "ordersearch") — matches co-located tests like
-     *    OrderSearch.test.tsx, the dominant convention;
-     *  - its sub-tokens, split on delimiters AND camelCase boundaries ("OrderSearch" →
-     *    "order","search") — matches hyphenated/underscored test names like order-search.spec.tsx;
-     *  - the parent directory name — the signal when the basename is generic (orders/index.tsx).
-     * Generic tokens (index, components, utils, …) and tokens shorter than 3 chars are dropped so
-     * a shared dir or an index file doesn't match every UI test in the repo.
-     */
-    deriveFrontendResourceTokens(changedFrontendFiles) {
-        const out = new Set();
-        const add = (t) => {
-            const v = t.toLowerCase();
-            if (v.length >= 3 && !this.GENERIC_FRONTEND_TOKENS.has(v))
-                out.add(v);
-        };
-        for (const f of changedFrontendFiles) {
-            const segs = f.replace(/\\/g, "/").split("/").filter(Boolean);
-            const base = segs[segs.length - 1] ?? "";
-            const stem = base.replace(/\.[^.]+$/, ""); // drop extension
-            add(stem); // whole stem (e.g. "ordersearch", "order-search")
-            for (const t of stem.split(/[-_.]+|(?<=[a-z0-9])(?=[A-Z])/))
-                add(t); // sub-tokens
-            const parent = segs[segs.length - 2];
-            if (parent && !parent.startsWith("__"))
-                add(parent);
-        }
-        return [...out];
-    }
-    // Max additional tests promoted via content-based scoring on top of filename matches.
-    // Content matches are lower-confidence than filename matches — cap to avoid token bloat.
-    MAX_CONTENT_PROMOTED = 5;
-    // Backstop cap on scoped UI-test promotion (Step 2). The relevance filter against the
-    // changed frontend files does the real bounding; this only guards a pathological match
-    // (e.g. a change to a widely-shared component). Highest-scoring tests survive truncation.
-    MAX_UI_PROMOTED = 50;
-    // Weight added to a UI test's relevance score when it imports a changed frontend file by
-    // module path (import-edge match, Step 2 pass 2). Set high above any filename-token score
-    // so import matches — the strongest "this test exercises the changed code" signal —
-    // always survive the MAX_UI_PROMOTED cap ahead of name-only matches.
-    UI_IMPORT_MATCH_WEIGHT = 100;
-    // Generic path/name tokens that carry no feature signal — excluded when deriving relevance
-    // tokens from changed frontend files so a changed index.tsx or a shared "components" dir
-    // doesn't match every UI test in the repo.
-    GENERIC_FRONTEND_TOKENS = new Set([
-        "index", "app", "main", "root", "styles", "style", "css", "scss", "types", "type",
-        "constants", "utils", "util", "helpers", "helper", "components", "component", "pages",
-        "page", "routes", "route", "src", "common", "shared", "hooks", "hook", "lib", "context",
-        "providers", "provider", "store", "stores", "api", "test", "tests", "spec", "specs",
-        "mocks", "mock", "fixtures", "fixture", "assets", "config",
-    ]);
-    /**
-     * Partition external test files into relevant (score > 0) and low-relevance (score = 0).
-     * Two-pass: filename token overlap first (primary); content-based endpoint path scan
-     * as a capped fallback for tests misnamed relative to the endpoint they exercise
-     * (e.g. test_checkout_flow.py testing /api/orders scores 0 by name but matches in content).
-     * Content matches are capped at MAX_CONTENT_PROMOTED to bound token impact.
-     */
-    partitionByRelevance(files, changedResources, contentCache, changedSymbols, preciseResources) {
-        const nameMatched = [];
-        const symbolMatched = [];
-        const contentCandidates = [];
-        // Precompile content patterns once — avoids 20 resources × 150 files = 3K compilations.
-        const contentPatterns = contentCache
-            ? changedResources.map(r => {
-                // Escape all regex metacharacters, then restore [-/] as a character class
-                // for hyphens and slashes that appear in resource names like "order-items".
-                const escaped = r.toLowerCase()
-                    .replace(/[.*+?^${}()|[\]\\]/g, "\\$&") // escape regex metacharacters
-                    .replace(/-|\//g, "[-/]"); // treat hyphens/slashes interchangeably
-                return new RegExp(`["'\`][^"'\`]*/${escaped}`, "i");
-            })
-            : [];
-        // Exact, case-sensitive word-boundary match on a changed type name (e.g.
-        // `DeploymentCreate`). Catches an external test that references the changed schema/model
-        // by name but whose path/URL matches no changed resource — a schema unit test
-        // constructing it directly (SKYR-3924). High-confidence, so not subject to the content cap.
-        const symbolPatterns = contentCache
-            ? (changedSymbols ?? []).map(s => new RegExp(`\\b${s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\b`))
-            : [];
-        // Endpoint-call patterns: an HTTP-method call to a path containing the changed resource
-        // (e.g. `client.post("/deployments/")`). A direct call to the changed endpoint is
-        // high-confidence — distinct from a file that merely mentions the resource string.
-        const endpointCallPatterns = contentCache
-            ? changedResources.map(r => {
-                const escaped = r.toLowerCase()
-                    .replace(/[.*+?^${}()|[\]\\]/g, "\\$&")
-                    .replace(/-|\//g, "[-/]");
-                return new RegExp(`\\b(?:get|post|put|patch|delete|request|fetch)\\b[^\\n]{0,60}["'\`][^"'\`]*/${escaped}`, "i");
-            })
-            : [];
-        const strongContent = [];
-        for (const f of files) {
-            if (this.scoreRelevance(f, changedResources) > 0) {
-                nameMatched.push(f);
-                continue;
-            }
-            const content = contentCache?.get(f) ?? "";
-            if (!content)
-                continue;
-            if (symbolPatterns.some(p => p.test(content))) {
-                symbolMatched.push(f);
-            }
-            else if (endpointCallPatterns.some(p => p.test(content))) {
-                strongContent.push(f); // direct call to the changed endpoint — high-confidence
-            }
-            else if (contentPatterns.some(p => p.test(content))) {
-                contentCandidates.push(f); // loose mention of the resource — low-confidence, capped
-            }
-        }
-        // Precise resource sets (schema-diff preload): keep high-confidence endpoint-call matches
-        // uncapped (bounded by the specific resource), still cap loose mentions. Otherwise cap all
-        // content matches together (original behavior).
-        const contentMatched = preciseResources
-            ? [...strongContent, ...contentCandidates.slice(0, this.MAX_CONTENT_PROMOTED)]
-            : [...strongContent, ...contentCandidates].slice(0, this.MAX_CONTENT_PROMOTED);
-        if (symbolMatched.length > 0 || contentMatched.length > 0) {
-            // Report what actually landed in contentMatched — the non-precise branch caps
-            // strong+loose together, so strongContent may be truncated too. Deriving both
-            // counts from contentMatched.length avoids a misleading negative "loose" count.
-            const strongIn = Math.min(strongContent.length, contentMatched.length);
-            const looseIn = contentMatched.length - strongIn;
-            logger.info(`Relevance: ${symbolMatched.length} symbol + ${strongIn} endpoint-call + ${looseIn} loose content`);
-        }
-        return { relevant: [...nameMatched, ...symbolMatched, ...contentMatched] };
-    }
     /**
      * Process test files in parallel batches with concurrency control
      * @param isExternal When true, uses external test metadata extraction

package/build/services/containerEnv.d.ts

@@ -22,4 +22,4 @@ export declare function isValidEnvVarName(name: string): boolean;
 /**
  * Build the environment variable array for the Docker executor container.
  */
-export declare function buildContainerEnv(options: Pick<TestExecutionOptions, "token" | "language" | "useHostNetwork">, saveStoragePath?: string, hostEnv?: Record<string, string | undefined>, passthroughNames?: string[]): string[];
+export declare function buildContainerEnv(options: Pick<TestExecutionOptions, "token" | "language" | "useHostNetwork" | "rebaselineSnapshots">, saveStoragePath?: string, hostEnv?: Record<string, string | undefined>, passthroughNames?: string[]): string[];

package/build/services/containerEnv.js

@@ -77,6 +77,18 @@ export function buildContainerEnv(options, saveStoragePath, hostEnv = process.en
         ...(options.token ? [`SKYRAMP_TEST_TOKEN=${options.token}`] : []),
         "SKYRAMP_IN_DOCKER=true",
     ];
+    // Visual-snapshot baselines this run replaces (SKYR-4298). SmartPlaywright
+    // reads SKYRAMP_UPDATE_SNAPSHOTS and re-captures each named baseline through
+    // its first-run path instead of comparing. Set here, first-class, because the
+    // SKYRAMP_ prefix is reserved from workspace passthrough below — nothing else
+    // can put it in the container. Omitted entirely when nothing is to refresh, so
+    // the default stays "compare".
+    const rebaseline = (options.rebaselineSnapshots ?? [])
+        .map((n) => n.trim())
+        .filter(Boolean);
+    if (rebaseline.length > 0) {
+        env.push(`SKYRAMP_UPDATE_SNAPSHOTS=${rebaseline.join(",")}`);
+    }
     // Skyramp-generated tests are standalone HTTP tests that never need host repo
     // conftest.py files or pytest configuration. --noconftest prevents loading any
     // conftest in the test directory tree (avoids missing deps like boto3, django).

package/build/skills/fixTestImportErrorsSkill.d.ts

@@ -0,0 +1,13 @@
+/**
+ * The `fix-test-import-errors` skill ships in `plugin/skills/` at the package
+ * root (SKYR-4296). It carries the same instructions `skyramp_fix_errors`
+ * returns, so an agent that loads the plugin follows the skill and an agent
+ * that does not keeps calling the tool. The tool itself is unchanged.
+ */
+export declare const FIX_TEST_IMPORT_ERRORS_SKILL = "fix-test-import-errors";
+/**
+ * The sentence a prompt uses to send the agent to the fix-errors instructions.
+ * With the plugin loaded it names the skill and states the override contract:
+ * a project skill of the same name wins over the plugin copy.
+ */
+export declare function fixErrorsInstruction(): string;

package/build/skills/fixTestImportErrorsSkill.js

@@ -0,0 +1,20 @@
+import { isSkillsLoaded } from "../utils/featureFlags.js";
+/**
+ * The `fix-test-import-errors` skill ships in `plugin/skills/` at the package
+ * root (SKYR-4296). It carries the same instructions `skyramp_fix_errors`
+ * returns, so an agent that loads the plugin follows the skill and an agent
+ * that does not keeps calling the tool. The tool itself is unchanged.
+ */
+export const FIX_TEST_IMPORT_ERRORS_SKILL = "fix-test-import-errors";
+const FIX_ERRORS_TOOL = "skyramp_fix_errors";
+/**
+ * The sentence a prompt uses to send the agent to the fix-errors instructions.
+ * With the plugin loaded it names the skill and states the override contract:
+ * a project skill of the same name wins over the plugin copy.
+ */
+export function fixErrorsInstruction() {
+    if (isSkillsLoaded()) {
+        return `invoke the \`${FIX_TEST_IMPORT_ERRORS_SKILL}\` skill (a project skill with the same name takes precedence over the plugin copy)`;
+    }
+    return `call the \`${FIX_ERRORS_TOOL}\` tool`;
+}

package/build/toolNames.d.ts

@@ -17,3 +17,4 @@ export declare const TOOL_INTEGRATION_TEST_GENERATION = "skyramp_integration_tes
 export declare const TOOL_E2E_TEST_GENERATION = "skyramp_e2e_test_generation";
 export declare const TOOL_UI_TEST_GENERATION = "skyramp_ui_test_generation";
 export declare const TOOL_REGISTER_TEST_PLAN = "skyramp_register_test_plan";
+export declare const TOOL_RESOLVE_SCREEN = "skyramp_resolve_screen";

package/build/toolNames.js

@@ -17,3 +17,4 @@ export const TOOL_INTEGRATION_TEST_GENERATION = "skyramp_integration_test_genera
 export const TOOL_E2E_TEST_GENERATION = "skyramp_e2e_test_generation";
 export const TOOL_UI_TEST_GENERATION = "skyramp_ui_test_generation";
 export const TOOL_REGISTER_TEST_PLAN = "skyramp_register_test_plan";
+export const TOOL_RESOLVE_SCREEN = "skyramp_resolve_screen";

package/build/tools/code-refactor/enhanceAssertionsTool.js

@@ -16,7 +16,7 @@ import { stageGeneratedPaths } from "../../utils/gitStaging.js";
 const TOOL_NAME = "skyramp_enhance_assertions";
 const TESTBOT_UI_CHECKS = `
 ### Additional Testbot-Specific Checks
-- If no suitable selector exists in the generated file for an assertion you need to add, go back and call \`browser_assert\` on the live page to record it with a valid selector, then re-export and regenerate.
+- If no suitable selector exists in the generated file for an assertion you need to add, go back and call \`browser_assert\` on the live page to record it with a valid selector, then re-export and regenerate. Do not re-record an assertion that is expected to fail today; add it here with the blueprint's selector.
 - **After executing a UI test that documents a bug from \`issuesFound\`**: if it passed when you expected it to fail, the assertions are too weak — add a stronger \`expect()\` that directly targets the buggy behavior. This counts as the single allowed retry under the 2-attempt cap — do NOT re-run more than once.
 `;
 function buildAssertionInstructions(testFile, testType, enhanceType) {
@@ -44,7 +44,7 @@ function buildAutoApplyInstructions(testFile, testType, enhanceType) {
         `Read the file, apply the type-specific assertion guidance below, and write the file back directly.`,
         `Add assertions after each send_request/sendRequest status-code assertion.`,
         `Use SDK helper: Python \`skyramp.get_response_value(response, "json.path")\`, JS \`getValue(response, "json.path")\`.`,
-        `Do NOT restructure, reformat, add comments, or change imports. Only add assertion lines.`,
+        `Do NOT restructure, reformat, or add comments. You may add an import when a new assertion needs a helper — from \`@skyramp/skyramp\` or from the test's own helper module. Only add assertion lines.`,
         ``,
         `Type-specific assertion guidance:`,
         typeSpecificInstructions,
@@ -169,7 +169,7 @@ export function registerEnhanceAssertionsTool(server) {
                 `Shared assertion rules (apply all that fit):`,
                 renderSharedAssertionRules(),
                 ``,
-                `Do NOT restructure, reformat, add comments, or change imports. Only add assertion lines.`,
+                `Do NOT restructure, reformat, or add comments. You may add an import when a new assertion needs a helper — from \`@skyramp/skyramp\` or from the test's own helper module. Only add assertion lines.`,
             ].join("\n");
             const result = {
                 content: [{ type: "text", text: compactInstructions }],

package/build/tools/code-refactor/modularizationTool.js

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { fixErrorsInstruction } from "../../skills/fixTestImportErrorsSkill.js";
 import fs from "fs";
 import { logger } from "../../utils/logger.js";
 import { ProgrammingLanguage, TestType } from "../../types/TestTypes.js";
@@ -39,7 +40,7 @@ export function registerModularizationTool(server) {
 
 **MANDATORY**: ONLY MODULARIZE THE TEST IF THE IS TRACE BASED FLAG IS SET TO TRUE ELSE DO NOT MODULARIZE THE TEST AND LEAVE THE TEST FILE AS IS.
 **CRITICAL**: NON TRACE BASED TESTS ARE ALREADY MODULARIZED AND DO NOT NEED MODULARIZATION.
-After modularization, if errors remain, call skyramp_fix_errors.
+After modularization, if errors remain, ${fixErrorsInstruction()}.
 
 **CRITICAL**: This tool expects you to complete the modularization by writing the refactored code back to the file.`,
         inputSchema: modularizationSchema,