@skyramp/mcp 0.3.7 → 0.3.9-rc.1

package/build/utils/assertion-verify/ui-lints.d.ts

@@ -1,8 +1,3 @@
 import type { AssertionLanguage } from "./metrics.js";
 import { type LintFinding, type LintOptions } from "./lint-types.js";
-/** UI (Playwright) lints. Python (playwright-python) UI specs deliberately get
- *  the site-scoped lints only: the structural rules' patterns and accept-lists
- *  are JS/TS-specific (imports, waitForResponse shapes, expect matcher accept
- *  forms), and porting them without a python golden corpus to validate against
- *  would recreate the false-block class review round 2 removed. Pinned by test. */
 export declare function lintUiSpec(raw: string, language: AssertionLanguage, opts?: LintOptions): LintFinding[];

package/build/utils/assertion-verify/ui-lints.js

@@ -222,6 +222,36 @@ function lintUnassertedTrailingAction(stripped) {
  *  are JS/TS-specific (imports, waitForResponse shapes, expect matcher accept
  *  forms), and porting them without a python golden corpus to validate against
  *  would recreate the false-block class review round 2 removed. Pinned by test. */
+// SKYR-4305 — a removal guard (`toBeHidden()` / `not.toBeVisible()` on an element a
+// PR removed) is only meaningful next to a positive assertion on the same page: alone
+// it passes on a blank page, a 404, a typo'd testid, or a page the element never
+// rendered on. `toBeHidden` is a PARTIAL_MATCHER (weight 2), so the strength gate does
+// not catch a negative-only spec; this lint does.
+const ABSENCE_ASSERT_RE = /\.\s*(?:toBeHidden|to_be_hidden)\s*\(|\.\s*not\s*\.\s*(?:toBeVisible|toBeAttached)\s*\(|\.\s*not_to_be_(?:visible|attached)\s*\(/g;
+// Only Playwright LOCATOR/page matchers count as the positive half of the pair —
+// they prove something rendered. Generic Jest matchers (toBe/toEqual/toHaveLength)
+// are deliberately absent: `expect(resp.status()).toBe(200)` next to a lone
+// toBeHidden() proves nothing about the page.
+const POSITIVE_ASSERT_RE = /\.\s*(?:toHaveText|toContainText|toHaveValue|toHaveValues|toHaveAttribute|toHaveCount|toHaveURL|toHaveTitle|toHaveId|toHaveClass|toHaveCSS|toHaveJSProperty|toHaveAccessibleName|toHaveAccessibleDescription|toHaveRole|toHaveScreenshot|toBeVisible|toBeChecked|toBeEnabled|toBeDisabled|toBeEditable|toBeEmpty|toBeFocused|toBeInViewport|toContainClass|to_have_text|to_contain_text|to_have_value|to_have_values|to_have_attribute|to_have_count|to_have_url|to_have_title|to_have_id|to_have_class|to_have_css|to_have_js_property|to_have_accessible_name|to_have_accessible_description|to_have_role|to_have_screenshot|to_be_visible|to_be_checked|to_be_enabled|to_be_disabled|to_be_editable|to_be_empty|to_be_focused|to_be_in_viewport|to_contain_class)\s*\(/;
+function lintNegativeOnlySpec(commentless) {
+    ABSENCE_ASSERT_RE.lastIndex = 0;
+    const first = ABSENCE_ASSERT_RE.exec(commentless);
+    if (!first)
+        return [];
+    // Strip the absence assertions themselves, then look for a Playwright matcher
+    // on a rendered element (generic Jest matchers do not count — see POSITIVE_ASSERT_RE).
+    const remainder = commentless.replace(ABSENCE_ASSERT_RE, "");
+    ABSENCE_ASSERT_RE.lastIndex = 0;
+    if (POSITIVE_ASSERT_RE.test(remainder))
+        return [];
+    return [{
+            rule: "negative-only-spec",
+            severity: "hard",
+            line: lineOfOffset(commentless, first.index),
+            message: "Every locator assertion in this spec asserts absence (toBeHidden / not.toBeVisible); nothing proves the page rendered, so it passes on a blank page, a 404 or a typo'd selector.",
+            remediation: "Add at least one positive assertion on a retained element of the same page (toHaveText / toHaveValue / toHaveCount / toHaveURL) next to the absence assertions.",
+        }];
+}
 export function lintUiSpec(raw, language, opts) {
     if (language === "java")
         return [];
@@ -240,5 +270,7 @@ export function lintUiSpec(raw, language, opts) {
         findings.push(...lintUnassertedTrailingAction(stripped));
     }
     findings.push(...lintTautologies(commentless, opts));
+    if (!maintenance)
+        findings.push(...lintNegativeOnlySpec(commentless));
     return findings;
 }

package/build/utils/frontendSelectors.d.ts

@@ -32,3 +32,36 @@ export declare const MAX_CHANGED_SELECTORS = 80;
  *      `ads-button--primary`).
  */
 export declare function extractChangedSelectors(fileDiff: string): string[];
+/** A removed element's identity: the `data-*` attribute and its literal value. */
+export interface RemovedAttribute {
+    /** Lower-cased attribute name, e.g. `data-testid`, `data-cy`, `data-section`. */
+    attribute: string;
+    value: string;
+}
+/** Identifying attribute VALUES that appear on `+` lines of a diff (any number of files). */
+export declare function extractAddedAttributeValues(diff: string): string[];
+/**
+ * Identifying `data-*` attributes one file's diff REMOVED: literals on `-` lines, minus the
+ * cases where the element still renders somewhere:
+ *
+ *   - **moved / extracted** — the same value appears on a `+` line of this file or, via
+ *     `addedValuesElsewhere`, anywhere else in the diff (a component extracted into a new
+ *     file is the common shape);
+ *   - **not an element** — a `-` line counts only when it opens a JSX/HTML tag or is a
+ *     wrapped attribute line of a tag opened above it (the tag is carried until the `>`
+ *     that closes it). A deleted comment, docs snippet, story arg or page-object
+ *     `getByTestId(...)` call that merely mentions the attribute is not an element
+ *     removal — the element itself may well survive on an unchanged context line;
+ *   - **renamed** — a rename cannot be told apart by literal identity (old and new
+ *     value differ by definition), so it is paired structurally: within the same hunk,
+ *     each `-` line is paired with AT MOST ONE `+` line carrying a NEW identifying
+ *     attribute — first by identical shape with the values blanked, else by the same
+ *     opening tag — and a paired `+` line is consumed. So one added element suppresses
+ *     one removal, not every removal in the hunk. This still errs toward suppressing a
+ *     guard when one same-tag element is swapped for an unrelated new one.
+ *
+ * Feeds `uiContext.removedElements` (SKYR-4305) — the grounding for a removal guard
+ * (`toBeHidden()` on `getByTestId(value)` for `data-testid`, on
+ * `locator('[<attribute>="<value>"]')` for any other `data-*`).
+ */
+export declare function extractRemovedAttributes(fileDiff: string, addedValuesElsewhere?: Iterable<string>): RemovedAttribute[];

package/build/utils/frontendSelectors.js

@@ -52,6 +52,28 @@ function isDistinctiveSelector(token, trusted) {
     }
     return hasBEM || (hyphens >= 2 && !COMMON_CSS_SELECTOR_TOKENS.test(token));
 }
+/**
+ * The test-facing selector grammar, shared by every extractor in this module so the
+ * two cannot drift: `data-testid` / `data-test` / `data-test-id` / `data-cy` / `data-qa`
+ * attribute values (string literals only) and `getByTestId(...)` arguments.
+ * Case-insensitive on purpose: JSX authors write `data-testId` (demoshop) and the
+ * browser lowercases attribute names, so `getByTestId` matches either spelling.
+ */
+const TESTID_ATTR_RE = /\b(data-(?:test-?id|test|cy|qa))\b\s*=\s*\{?\s*[`'"]([A-Za-z][\w:-]{2,})[`'"]/gi;
+const GET_BY_TEST_ID_RE = /getByTestId\(\s*[`'"]([A-Za-z][\w:-]{2,})[`'"]/gi;
+/**
+ * Any other `data-*` attribute with a static string value (`data-section="session-id-debug"`).
+ * Untrusted: the value must pass the stricter distinctiveness rule, and attributes that carry
+ * component STATE rather than identity are excluded — they flip at runtime, so "absent" is
+ * meaningless for them.
+ */
+const GENERIC_DATA_ATTR_RE = /\b(data-[a-z][a-z0-9]*(?:-[a-z0-9]+)*)\s*=\s*\{?\s*[`'"]([A-Za-z][\w:-]{2,})[`'"]/gi;
+const STATE_DATA_ATTRS = new Set([
+    "data-state", "data-theme", "data-orientation", "data-side", "data-align", "data-value",
+    "data-index", "data-slot", "data-disabled", "data-checked", "data-active", "data-open",
+    "data-loading", "data-size", "data-variant", "data-selected", "data-highlighted",
+    "data-focus", "data-hover", "data-pressed", "data-expanded", "data-placeholder", "data-status",
+]);
 /**
  * Extract selector literals added or removed in a single file's diff slice.
  *
@@ -74,8 +96,8 @@ export function extractChangedSelectors(fileDiff) {
     // `data-testid="x"`, `data-testid={'x'}`, `data-testid={`x`}`. The closing delimiter
     // deliberately rejects interpolated template literals (`data-testid={`members-${id}`}`),
     // which would otherwise leak a partial prefix (`members-`) into the selector set.
-    const ATTR = /\bdata-(?:test-?id|test|cy|qa)\b\s*=\s*\{?\s*[`'"]([A-Za-z][\w:-]{2,})[`'"]/g;
-    const GET_BY_TEST_ID = /getByTestId\(\s*[`'"]([A-Za-z][\w:-]{2,})[`'"]/g;
+    const ATTR = TESTID_ATTR_RE;
+    const GET_BY_TEST_ID = GET_BY_TEST_ID_RE;
     const KEBAB = /[a-z][a-z0-9]*(?:-{1,2}[a-z0-9]+)+/g;
     // BEM base whose modifier is composed DYNAMICALLY, so no concrete class literal exists
     // in the diff to grep: `ads-button--${kind}`, "ads-button--" + kind, clsx(base && `x--${y}`).
@@ -92,12 +114,12 @@ export function extractChangedSelectors(fileDiff) {
         if (raw.startsWith("+++") || raw.startsWith("---"))
             continue;
         const line = raw.slice(1);
-        for (const re of [ATTR, GET_BY_TEST_ID]) {
+        for (const [re, valueGroup] of [[ATTR, 2], [GET_BY_TEST_ID, 1]]) {
             re.lastIndex = 0;
             let m;
             while ((m = re.exec(line)) !== null) {
-                if (isDistinctiveSelector(m[1], true))
-                    out.add(m[1]);
+                if (isDistinctiveSelector(m[valueGroup], true))
+                    out.add(m[valueGroup]);
                 if (out.size >= MAX_CHANGED_SELECTORS)
                     return [...out];
             }
@@ -121,3 +143,172 @@ export function extractChangedSelectors(fileDiff) {
     }
     return [...out];
 }
+/**
+ * Identifying `data-*` attributes on one source line: the trusted test-facing set (any
+ * casing), `getByTestId(...)` arguments (attributed to `data-testid`), and any other
+ * static `data-*` whose value is distinctive and whose attribute is not a state carrier.
+ */
+function attributesOnLine(line) {
+    const out = [];
+    const seen = new Set();
+    const push = (attribute, value) => {
+        const key = `${attribute}=${value}`;
+        if (!seen.has(key)) {
+            seen.add(key);
+            out.push({ attribute, value });
+        }
+    };
+    let m;
+    TESTID_ATTR_RE.lastIndex = 0;
+    while ((m = TESTID_ATTR_RE.exec(line)) !== null) {
+        if (isDistinctiveSelector(m[2], true))
+            push(m[1].toLowerCase(), m[2]);
+    }
+    GET_BY_TEST_ID_RE.lastIndex = 0;
+    while ((m = GET_BY_TEST_ID_RE.exec(line)) !== null) {
+        if (isDistinctiveSelector(m[1], true))
+            push("data-testid", m[1]);
+    }
+    GENERIC_DATA_ATTR_RE.lastIndex = 0;
+    while ((m = GENERIC_DATA_ATTR_RE.exec(line)) !== null) {
+        const attribute = m[1].toLowerCase();
+        if (STATE_DATA_ATTRS.has(attribute))
+            continue;
+        if (seen.has(`${attribute}=${m[2]}`))
+            continue; // already captured by the trusted pass
+        if (isDistinctiveSelector(m[2], false))
+            push(attribute, m[2]);
+    }
+    return out;
+}
+/**
+ * Tag name of the JSX/HTML element a diff line opens, or "" — also "" for a comment
+ * line (`//`, `/*`, `*`, `{/*`, `<!--`), whose `<div …>` is text, not an element.
+ */
+function openingTagOf(line) {
+    const t = line.trim();
+    if (/^(?:\/\/|\/\*|\*|\{\s*\/\*|<!--)/.test(t))
+        return "";
+    return /<\s*([A-Za-z][\w.-]*)/.exec(t)?.[1]?.toLowerCase() ?? "";
+}
+/** Identifying attribute VALUES that appear on `+` lines of a diff (any number of files). */
+export function extractAddedAttributeValues(diff) {
+    const out = new Set();
+    for (const raw of diff.split("\n")) {
+        if (!raw.startsWith("+") || raw.startsWith("+++"))
+            continue;
+        for (const a of attributesOnLine(raw.slice(1)))
+            out.add(a.value);
+    }
+    return [...out];
+}
+/**
+ * Identifying `data-*` attributes one file's diff REMOVED: literals on `-` lines, minus the
+ * cases where the element still renders somewhere:
+ *
+ *   - **moved / extracted** — the same value appears on a `+` line of this file or, via
+ *     `addedValuesElsewhere`, anywhere else in the diff (a component extracted into a new
+ *     file is the common shape);
+ *   - **not an element** — a `-` line counts only when it opens a JSX/HTML tag or is a
+ *     wrapped attribute line of a tag opened above it (the tag is carried until the `>`
+ *     that closes it). A deleted comment, docs snippet, story arg or page-object
+ *     `getByTestId(...)` call that merely mentions the attribute is not an element
+ *     removal — the element itself may well survive on an unchanged context line;
+ *   - **renamed** — a rename cannot be told apart by literal identity (old and new
+ *     value differ by definition), so it is paired structurally: within the same hunk,
+ *     each `-` line is paired with AT MOST ONE `+` line carrying a NEW identifying
+ *     attribute — first by identical shape with the values blanked, else by the same
+ *     opening tag — and a paired `+` line is consumed. So one added element suppresses
+ *     one removal, not every removal in the hunk. This still errs toward suppressing a
+ *     guard when one same-tag element is swapped for an unrelated new one.
+ *
+ * Feeds `uiContext.removedElements` (SKYR-4305) — the grounding for a removal guard
+ * (`toBeHidden()` on `getByTestId(value)` for `data-testid`, on
+ * `locator('[<attribute>="<value>"]')` for any other `data-*`).
+ */
+export function extractRemovedAttributes(fileDiff, addedValuesElsewhere = []) {
+    const addedAnywhere = new Set(addedValuesElsewhere);
+    for (const v of extractAddedAttributeValues(fileDiff))
+        addedAnywhere.add(v);
+    // Split into hunks so rename pairing stays local.
+    const hunks = [];
+    for (const raw of fileDiff.split("\n")) {
+        if (raw.startsWith("@@")) {
+            hunks.push([]);
+            continue;
+        }
+        if (hunks.length === 0)
+            hunks.push([]);
+        hunks[hunks.length - 1].push(raw);
+    }
+    const shapeOf = (line, attrs) => {
+        let shape = line.trim();
+        for (const a of attrs)
+            shape = shape.split(a.value).join("\u0000");
+        return shape;
+    };
+    const out = [];
+    const seen = new Set();
+    for (const hunk of hunks) {
+        const removedLines = [];
+        const addedNew = [];
+        // A JSX attribute wrapped onto its own line (`+  data-testid="x"`) belongs to the
+        // element opened on an earlier line of the same side; carry that tag forward
+        // until the `>` that closes the opening tag, so a later comment or unrelated
+        // line in the hunk does not inherit it.
+        let lastMinusTag = "";
+        let lastPlusTag = "";
+        for (const raw of hunk) {
+            if (raw.startsWith("+++") || raw.startsWith("---"))
+                continue;
+            if (!(raw.startsWith("+") || raw.startsWith("-")))
+                continue;
+            const line = raw.slice(1);
+            const ownTag = openingTagOf(line);
+            const minus = raw.startsWith("-");
+            if (ownTag) {
+                if (minus)
+                    lastMinusTag = ownTag;
+                else
+                    lastPlusTag = ownTag;
+            }
+            const tag = ownTag || (minus ? lastMinusTag : lastPlusTag);
+            if (line.includes(">")) {
+                if (minus)
+                    lastMinusTag = "";
+                else
+                    lastPlusTag = "";
+            }
+            const attrs = attributesOnLine(line);
+            if (attrs.length === 0)
+                continue;
+            // Only an element (a tag opened on this line or carried from above) can be a
+            // removed element; a bare mention in a comment / docs / page object is not.
+            if (minus && tag === "")
+                continue;
+            if (minus)
+                removedLines.push({ attrs, tag, shape: shapeOf(line, attrs) });
+            else
+                addedNew.push({ tag, shape: shapeOf(line, attrs), consumed: false });
+        }
+        // Pair each removed line with at most ONE new-side line: identical blanked shape
+        // first, else the same opening tag. A paired + line is consumed, so one added
+        // element suppresses one removal (a moved value is handled by addedAnywhere).
+        for (const r of removedLines) {
+            const partner = addedNew.find((a) => !a.consumed && a.shape === r.shape)
+                ?? addedNew.find((a) => !a.consumed && a.tag === r.tag);
+            if (partner) {
+                partner.consumed = true;
+                continue;
+            }
+            for (const a of r.attrs) {
+                const key = `${a.attribute}=${a.value}`;
+                if (!addedAnywhere.has(a.value) && !seen.has(key)) {
+                    seen.add(key);
+                    out.push(a);
+                }
+            }
+        }
+    }
+    return out;
+}

package/build/utils/pathSignatures.d.ts

@@ -22,7 +22,10 @@ export declare function isIndexModule(file: string): boolean;
  * (`@/x`, `~/x`, `~~/x`, `#/x`, `src/x`) are accepted when the module directory
  * ends with the aliased path AND the importer lives under the same root that the
  * alias maps to — `packages/store/Page.tsx` importing `@/app/shop/_constants` does
- * not match `packages/admin/app/shop/_constants/index.ts`. All paths are
+ * not match `packages/admin/app/shop/_constants/index.ts`. Prefix-less
+ * multi-segment specifiers (`Components/Foo` under tsconfig `baseUrl: "src"` —
+ * SKYR-4287) go through the same suffix + shared-root check; only single-segment
+ * prefix-less specifiers (`react`) are treated as npm packages. All paths are
  * repo-relative with forward slashes.
  */
 export declare function importsIndexModule(importerFile: string, importerContent: string, indexFile: string): boolean;

package/build/utils/pathSignatures.js

@@ -60,7 +60,10 @@ export function isIndexModule(file) {
  * (`@/x`, `~/x`, `~~/x`, `#/x`, `src/x`) are accepted when the module directory
  * ends with the aliased path AND the importer lives under the same root that the
  * alias maps to — `packages/store/Page.tsx` importing `@/app/shop/_constants` does
- * not match `packages/admin/app/shop/_constants/index.ts`. All paths are
+ * not match `packages/admin/app/shop/_constants/index.ts`. Prefix-less
+ * multi-segment specifiers (`Components/Foo` under tsconfig `baseUrl: "src"` —
+ * SKYR-4287) go through the same suffix + shared-root check; only single-segment
+ * prefix-less specifiers (`react`) are treated as npm packages. All paths are
  * repo-relative with forward slashes.
  */
 export function importsIndexModule(importerFile, importerContent, indexFile) {
@@ -76,7 +79,16 @@ export function importsIndexModule(importerFile, importerContent, indexFile) {
             continue;
         }
         const aliased = spec.replace(/^(@\/|~~\/|~\/|#\/|src\/)/, "");
-        if (aliased === spec)
+        // A prefix-less specifier is only a bare npm package when it has a single
+        // segment ('react'). Multi-segment prefix-less specifiers are how tsconfig
+        // `baseUrl` repos import internal modules ('Components/Foo' with
+        // baseUrl: "src" — SKYR-4287: every folder-per-component index.tsx in such
+        // repos was misreported as no-importers). Those flow into the same
+        // suffix + shared-root check as aliases; a deep npm import ('lodash/get')
+        // is unlikely to match unless the repo actually contains a `lodash/get`
+        // directory under the same root, and a scoped package ('@scope/pkg') would
+        // require a source directory literally named '@scope'.
+        if (aliased === spec && !spec.includes("/"))
             continue; // bare package specifier — not a repo path
         if (moduleDir === aliased)
             return true; // alias maps to the repo root

package/build/utils/planOnlyMode.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Plan-only mode capture for `skyramp_submit_report` (SKYR-4250).
+ *
+ * A plan-only eval run (SKYR-3879) writes no test files: `newTestsCreated`
+ * DECLARES the approved GENERATE selection instead of recording generated
+ * files, and the declaration itself is the deliverable. The SKYR-3883 guard
+ * (`findUnchangedFileClaims`) verifies every `newTestsCreated` claim against
+ * the working tree, so in that lane EVERY declaration is unbacked by
+ * construction and the report is rejected.
+ *
+ * That rejection is not evenly distributed. `findUnchangedFileClaims` exempts a
+ * claim attributed to a non-primary repo, so on a cross-repo fixture the
+ * related repo's declarations pass and only the primary repo's are checked.
+ * On a frontend-primary pair that makes the mandatory UI item (SKYR-4204's
+ * floor) the one claim that always fails, and the agent's only compliant move
+ * is to demote it to `additionalRecommendations` — which is exactly the
+ * under-declaration SKYR-4250 exists to fix (run 32903633247).
+ *
+ * `planOnly` reaches the server only as a testbot prompt/resource arg, so this
+ * mirrors the SKYR-4185 report-language capture: the prompt render is the
+ * single capture point, and the report tool reads the captured mode later in
+ * the same process.
+ *
+ * Capture is fail-open by design: if the testbot prompt was never served, the
+ * mode stays false and the guard behaves exactly as it does today.
+ */
+/** Capture plan-only mode at prompt-serve time. Last render wins: a later
+ *  non-plan-only render disarms a mode captured earlier in a long-lived server
+ *  process, so an ordinary run never silently skips the guard. */
+export declare function setPlanOnlyMode(planOnly: boolean): void;
+export declare function isPlanOnlyMode(): boolean;
+/** Test isolation only — module state persists across tests in one process. */
+export declare function resetPlanOnlyMode(): void;

package/build/utils/planOnlyMode.js

@@ -0,0 +1,40 @@
+/**
+ * Plan-only mode capture for `skyramp_submit_report` (SKYR-4250).
+ *
+ * A plan-only eval run (SKYR-3879) writes no test files: `newTestsCreated`
+ * DECLARES the approved GENERATE selection instead of recording generated
+ * files, and the declaration itself is the deliverable. The SKYR-3883 guard
+ * (`findUnchangedFileClaims`) verifies every `newTestsCreated` claim against
+ * the working tree, so in that lane EVERY declaration is unbacked by
+ * construction and the report is rejected.
+ *
+ * That rejection is not evenly distributed. `findUnchangedFileClaims` exempts a
+ * claim attributed to a non-primary repo, so on a cross-repo fixture the
+ * related repo's declarations pass and only the primary repo's are checked.
+ * On a frontend-primary pair that makes the mandatory UI item (SKYR-4204's
+ * floor) the one claim that always fails, and the agent's only compliant move
+ * is to demote it to `additionalRecommendations` — which is exactly the
+ * under-declaration SKYR-4250 exists to fix (run 32903633247).
+ *
+ * `planOnly` reaches the server only as a testbot prompt/resource arg, so this
+ * mirrors the SKYR-4185 report-language capture: the prompt render is the
+ * single capture point, and the report tool reads the captured mode later in
+ * the same process.
+ *
+ * Capture is fail-open by design: if the testbot prompt was never served, the
+ * mode stays false and the guard behaves exactly as it does today.
+ */
+let sessionPlanOnly = false;
+/** Capture plan-only mode at prompt-serve time. Last render wins: a later
+ *  non-plan-only render disarms a mode captured earlier in a long-lived server
+ *  process, so an ordinary run never silently skips the guard. */
+export function setPlanOnlyMode(planOnly) {
+    sessionPlanOnly = planOnly;
+}
+export function isPlanOnlyMode() {
+    return sessionPlanOnly;
+}
+/** Test isolation only — module state persists across tests in one process. */
+export function resetPlanOnlyMode() {
+    sessionPlanOnly = false;
+}

package/build/utils/rebaselineSnapshots.d.ts

@@ -0,0 +1,24 @@
+import { z } from "zod";
+/**
+ * Visual-snapshot baseline names as a Skyramp test passes them to
+ * `toHaveScreenshot()` — e.g. `page-001.png` — and as `skyramp_actions` and
+ * `skyramp_execute_test` accept them in `rebaselineSnapshots` (SKYR-4298).
+ *
+ * Bare filename only: no path separators, and no commas or whitespace, because the
+ * list is joined with commas into `SKYRAMP_UPDATE_SNAPSHOTS` and split again in the
+ * executor, where `a,b.png` would read as two baselines. One definition shared by
+ * both tools so they can never drift apart.
+ */
+export declare const REBASELINE_SNAPSHOT_NAME_RE: RegExp;
+export declare const rebaselineSnapshotNameSchema: z.ZodString;
+/** `page-001.png` → `page-001`. */
+export declare function baselineStem(name: string): string;
+export declare function baselineFileMatchesStem(fileBasename: string, stem: string): boolean;
+/** The directory Playwright keeps a spec's baselines in under the default layout. */
+export declare function snapshotDirFor(specFile: string): string;
+/** Looks like an on-disk baseline filename (`page-001-chromium-linux.png`) rather than the
+ *  name the test passes (`page-001.png`) — the likeliest wrong input, and one the name
+ *  schema accepts. Advisory only: `hero-linux.png` is also a perfectly valid name a test
+ *  can pass, so callers warn and keep the entry; execution authorizes it against the
+ *  verdict and reports whether anything was actually rewritten. */
+export declare function looksLikeOnDiskBaselineName(name: string): boolean;

package/build/utils/rebaselineSnapshots.js

@@ -0,0 +1,65 @@
+import path from "path";
+import { z } from "zod";
+/**
+ * Visual-snapshot baseline names as a Skyramp test passes them to
+ * `toHaveScreenshot()` — e.g. `page-001.png` — and as `skyramp_actions` and
+ * `skyramp_execute_test` accept them in `rebaselineSnapshots` (SKYR-4298).
+ *
+ * Bare filename only: no path separators, and no commas or whitespace, because the
+ * list is joined with commas into `SKYRAMP_UPDATE_SNAPSHOTS` and split again in the
+ * executor, where `a,b.png` would read as two baselines. One definition shared by
+ * both tools so they can never drift apart.
+ */
+export const REBASELINE_SNAPSHOT_NAME_RE = /^[^/\\,\s]+\.png$/i;
+export const rebaselineSnapshotNameSchema = z
+    .string()
+    .trim()
+    .regex(REBASELINE_SNAPSHOT_NAME_RE, {
+    message: 'rebaselineSnapshots entries must be bare .png filenames as passed to toHaveScreenshot(), e.g. "page-001.png" — no path, commas, or whitespace',
+});
+/** `page-001.png` → `page-001`. */
+export function baselineStem(name) {
+    return path.basename(name).replace(/\.png$/i, "");
+}
+/**
+ * Playwright's default snapshot layout, which is what the executor produces: the
+ * baseline for `<stem>.png` lives in `<spec>-snapshots/` as `<stem>-<project>-<platform>.png`
+ * (or `<stem>-<platform>.png` with no project, or `<stem>.png` under a custom
+ * `snapshotPathTemplate`). Safe to assume here because TestExecutionService mounts
+ * its own generated Playwright config over any the repo carries, so a repo cannot
+ * relocate its snapshots out from under this rule.
+ *
+ * The executor's generated config declares no `projects`, but runner.sh passes
+ * `--browser=chromium`, so Playwright names the implicit project "chromium" and a
+ * refresh writes `<stem>-chromium-linux.png` (observed end to end on demoshop).
+ * Baselines the Skyramp executor produced therefore round-trip exactly. A baseline
+ * a repo's own CI wrote under another project name (`<stem>-Desktop-Chrome-linux.png`)
+ * is a different file: the executor's refresh adds its own and leaves that one as
+ * it was — the tool reports what it rewrote, and the repo's own suite is out of
+ * scope for skyramp_execute_test (which never runs it).
+ *
+ * Anchored so a longer baseline cannot vouch for a shorter one: `page-001-wide-chromium-linux.png`
+ * belongs to `page-001-wide.png` and must not satisfy a claim on `page-001.png`.
+ */
+const SNAPSHOT_PLATFORMS = "(?:darwin|linux|win32)";
+export function baselineFileMatchesStem(fileBasename, stem) {
+    // A degenerate stem ("" or dots only, from a name like "..png") would match a wide
+    // set of files; nothing legitimate has one.
+    if (!stem || /^\.+$/.test(stem))
+        return false;
+    const escaped = stem.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const re = new RegExp(`^${escaped}(?:-[^-]+-${SNAPSHOT_PLATFORMS}|-${SNAPSHOT_PLATFORMS})?\\.png$`, "i");
+    return re.test(fileBasename);
+}
+/** The directory Playwright keeps a spec's baselines in under the default layout. */
+export function snapshotDirFor(specFile) {
+    return `${specFile}-snapshots`;
+}
+/** Looks like an on-disk baseline filename (`page-001-chromium-linux.png`) rather than the
+ *  name the test passes (`page-001.png`) — the likeliest wrong input, and one the name
+ *  schema accepts. Advisory only: `hero-linux.png` is also a perfectly valid name a test
+ *  can pass, so callers warn and keep the entry; execution authorizes it against the
+ *  verdict and reports whether anything was actually rewritten. */
+export function looksLikeOnDiskBaselineName(name) {
+    return /-(?:[^-]+-)?(?:darwin|linux|win32)\.png$/i.test(name);
+}

package/build/utils/removedUiElements.d.ts

@@ -0,0 +1,34 @@
+import type { CandidateUiPage } from "./uiPageEnumerator.js";
+import type { FrontendFileIntegration } from "../types/FrontendIntegration.js";
+export interface RemovedUiElement {
+    /** Lower-cased identifying attribute: `data-testid`, `data-cy`, `data-qa`, `data-section`, … */
+    attribute: string;
+    /** Its literal value. `attribute` + `value` is unique across the result. */
+    value: string;
+    /** Repo-relative frontend file the diff removed it from. */
+    file: string;
+    /** Candidate UI pages attributed to that file (directly, or via its importers). */
+    pageUrls: string[];
+}
+/**
+ * Bound the list: each entry is a guard assertion the agent records on one page, and
+ * the plan budget is small (`MAX_TESTS_TO_GENERATE`), so a large cleanup PR gets its
+ * first few ids, not a flood. Truncation is logged at info with the dropped count.
+ */
+export declare const MAX_REMOVED_UI_ELEMENTS = 5;
+export interface CollectRemovedUiElementsInput {
+    changedFrontendFiles: string[];
+    /** Files with `+++ /dev/null` in the diff — their page is gone, no guard. */
+    deletedFiles: string[];
+    /** Per-file diff slices for the WHOLE diff keyed by repo-relative path (see sliceDiffByFile). */
+    diffByFile: Map<string, string>;
+    frontendFileIntegration?: FrontendFileIntegration[];
+    candidateUiPages: CandidateUiPage[];
+    /** Absolute paths of discovered existing tests (skyramp + relevant external). */
+    existingTestFiles: string[];
+    /** True when test discovery threw — the existing-test check cannot run, so report nothing. */
+    discoveryFailed?: boolean;
+    /** Injectable for tests; defaults to a tolerant fs read that logs failures. */
+    readFile?: (absPath: string) => string | undefined;
+}
+export declare function collectRemovedUiElements(input: CollectRemovedUiElementsInput): RemovedUiElement[];