@skyramp/mcp 0.4.2 → 0.4.3-rc.1

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

@@ -4,11 +4,13 @@ import * as path from "path";
 import { logger } from "../../utils/logger.js";
 import { toolError } from "../../utils/utils.js";
 import { getCodeReusePrompt } from "../../prompts/code-reuse.js";
-import { isPomAwareTarget } from "../../utils/reuseRouting.js";
+import { reuseRouteFor, isPomFirstTarget, } from "../../utils/reuseRouting.js";
+import { pageObjectCandidates } from "../../utils/pom-scope/ownership.js";
 import { selectScopedPoms, } from "../../utils/pom-scope/index.js";
 import { verifyReuse } from "../../utils/pom-verify/index.js";
 import { infraGateFailure, zeroReuseGateFailure, composeVerifyText, } from "./verify-gates.js";
 import { recordCandidates, recordNoPomLayer, recordVerifyOutcome, recordUtilsReuseIssued, recordUtilsVerifyOutcome, recordUtilsVerifyError, pendingModularization, utilsBaselineFor, } from "./reuse-state.js";
+import { pomPassOutcome, recordPomPassFinished } from "./pom-pass-state.js";
 import { formatUtilsVerifyText } from "./utils-verify-gates.js";
 import { utilsSpecFor, verifyUtils } from "../../utils/utils-verify/index.js";
 import { codeRefactoringSchema, languageSchema, TestType, } from "../../types/TestTypes.js";
@@ -57,7 +59,7 @@ const codeReuseSchema = z.object({
             .describe("Helpers the search read and did not call, one entry each, with the reason."),
     })
         .optional()
-        .describe("Verify mode, UI tests only (the SkyrampUtils path with page-object reuse off): what the search for the repository's own browser helper modules read and declined. These are DECLARATIONS — the report records them as what the run states it read, labelled as such, not as a measurement. Pass them on the `verify: true` call once the reuse edits are written."),
+        .describe("Verify mode, UI tests only (the SkyrampUtils path, which follows the page-object pass when page-object reuse is on): what the search for the repository's own browser helper modules read and declined. These are DECLARATIONS — the report records them as what the run states it read, labelled as such, not as a measurement. Pass them on the `verify: true` call once the reuse edits are written."),
 });
 const TOOL_NAME = "skyramp_reuse_code";
 /**
@@ -103,12 +105,23 @@ const DISCOVER_FIRST_NOTICE = `VERIFICATION NOT RUN — this test file has not b
 Discovery is per test file: it scopes page-object candidates to this file's own selectors, so discovery done for another spec does not cover this one. Verification confirms only that the page-object calls a spec ALREADY contains resolve against their source — it cannot name the calls the spec should have made. That is why verifying first reports a spec that reuses almost nothing as PASSED.
 
 Follow the result below for this test file; it states what to do next.`;
-// Only advertised when SKYRAMP_FEATURE_POM_REUSE=1 — with the flag off this tool
-// never takes the POM path, so describing it would promise behavior it won't do.
-const POM_AWARE_MODE_DESCRIPTION = `
+/** The page-object paragraph of the tool description — ONE text per configuration,
+ *  read at register time like the flag that gates it (nothing here is decided at
+ *  import). Only advertised with SKYRAMP_FEATURE_POM_REUSE=1: with the flag off this
+ *  tool never takes the POM path, so describing it would promise behavior it won't do.
+ *  With shared-helper reuse on as well, a UI test takes both passes, and the text says
+ *  that instead of a rule and an exception that contradict each other. */
+function pomAwareModeDescription() {
+    if (!isPomReuseEnabled())
+        return "";
+    const head = `
 
       **POM-AWARE MODE (TypeScript/JavaScript + Playwright):**
-      For projects with \`language: "typescript" or "javascript"\` and \`framework: "playwright"\`, this tool first checks whether the project has an existing Page Object Model (POM) library (\`pageobjects/\` directories or \`*.page.ts\` / \`*.page.js\` files). If POMs are found, the test is refactored to use those POM classes and methods — replacing raw inline locators with the existing abstractions. SkyrampUtils consolidation is skipped on this path. If no POMs are found, the tool falls back to the standard SkyrampUtils path. New POM creation is out of scope — existing POMs are reused only. After POM-aware code reuse, do NOT call skyramp_modularization — on this path that supersedes WORKFLOW SUMMARY step 6.`;
+      For projects with \`language: "typescript" or "javascript"\` and \`framework: "playwright"\`, this tool first checks whether the project has an existing Page Object Model (POM) library (\`pageobjects/\` directories or \`*.page.ts\` / \`*.page.js\` files). If POMs are found, the test is refactored to use those POM classes and methods — replacing raw inline locators with the existing abstractions. New POM creation is out of scope — existing POMs are reused only.`;
+    return isUtilsReuseEnabled()
+        ? `${head} For a UI test (\`testType: "ui"\`) this is the FIRST of two passes: once its verification reports PASSED — or it answers "No reusable POM layer detected" — the generation result's next steps call skyramp_modularization and then this tool again, which returns the SkyrampUtils workflow for the steps the POM pass left inline, and whose verify: true call checks both the POM calls and the shared helpers. For any other test type the POM pass is the only pass: do NOT call skyramp_modularization after it. SkyrampUtils consolidation happens only in that second pass, never during the POM pass.`
+        : `${head} SkyrampUtils consolidation is skipped on this path. If no POM layer is found, the tool says so and the test is left as generated. After POM-aware code reuse, do NOT call skyramp_modularization — on this path that supersedes WORKFLOW SUMMARY step 6.`;
+}
 /** Whether a `verify: true` call must be turned into the discovery pass it skipped.
  *
  *  The two modes return very different things — discovery returns the whole refactoring
@@ -119,11 +132,26 @@ const POM_AWARE_MODE_DESCRIPTION = `
  *  `isPomAwareTarget` also carries the feature flag and the browser-test-type check, so a
  *  call that could never have reached the POM procedure is never refused for lacking it.
  *  Enforced only inside a run — see `markKeyFor`. */
-function mustDiscoverFirst(params, markKey) {
+function mustDiscoverFirst(markKey, route) {
     return (markKey !== undefined &&
-        isPomAwareTarget(params.language, params.framework, params.testType) &&
+        route.pass === "pom" &&
         !discoveredSpecs.has(markKey));
 }
+/** The route for this call, resolved ONCE and handed to every branch, so discovery,
+ *  verify, the prompt and the modularization check cannot disagree. A page-object
+ *  target takes the page-object pass — except with both reuse settings on once that
+ *  pass has finished for the spec: from then on the spec is in the SkyrampUtils flow,
+ *  which runs over what the page-object pass left inline. */
+async function resolveReuseRoute(params) {
+    const finished = isPomFirstTarget(params.language, params.testType) &&
+        (await pomPassOutcome(params.testFile)) !== undefined;
+    return reuseRouteFor(params.language, params.framework, params.testType, finished);
+}
+function verifyToolResult(v) {
+    return v.error
+        ? toolError(v.text)
+        : { content: [{ type: "text", text: v.text }] };
+}
 /** Verify mode for the SkyrampUtils path: stage the shared utils file(s) this spec
  *  wrote or imports — located by header, in code, after the edits exist — then check
  *  their invariants and record the verdict that clears the utils debt.
@@ -134,23 +162,15 @@ function mustDiscoverFirst(params, markKey) {
 async function runUtilsVerify(params) {
     if (!isUtilsReuseEnabled()) {
         return {
-            content: [
-                {
-                    type: "text",
-                    text: "VERIFICATION SKIPPED — SkyrampUtils code reuse is disabled (SKYRAMP_FEATURE_UTILS_REUSE). Nothing to verify; continue.",
-                },
-            ],
+            text: "VERIFICATION SKIPPED — SkyrampUtils code reuse is disabled (SKYRAMP_FEATURE_UTILS_REUSE). Nothing to verify; continue.",
+            passed: true,
         };
     }
     if (!utilsSpecFor(params.language)) {
         // Say so rather than record a NoUtilsFile verdict nothing established.
         return {
-            content: [
-                {
-                    type: "text",
-                    text: `VERIFICATION SKIPPED — shared-helper verification does not cover ${params.language}; nothing was staged or checked. Continue.`,
-                },
-            ],
+            text: `VERIFICATION SKIPPED — shared-helper verification does not cover ${params.language}; nothing was staged or checked. Continue.`,
+            passed: true,
         };
     }
     try {
@@ -168,18 +188,14 @@ async function runUtilsVerify(params) {
             r.ok = false;
         const recorded = await recordUtilsVerifyOutcome(params.testFile, r, params.language, params.framework, params.testType, undefined, params.inHouse);
         return {
-            content: [
-                {
-                    type: "text",
-                    text: formatUtilsVerifyText(r, {
-                        staged: staging.staged,
-                        // A refused in-house module is the customer's file, not ours to move.
-                        unstaged: staging.failed.filter((f) => !staging.inHouse.includes(f)),
-                        unstagedInHouse: staging.failed.filter((f) => staging.inHouse.includes(f)),
-                        recorded,
-                    }),
-                },
-            ],
+            text: formatUtilsVerifyText(r, {
+                staged: staging.staged,
+                // A refused in-house module is the customer's file, not ours to move.
+                unstaged: staging.failed.filter((f) => !staging.inHouse.includes(f)),
+                unstagedInHouse: staging.failed.filter((f) => staging.inHouse.includes(f)),
+                recorded,
+            }),
+            passed: r.ok,
         };
     }
     catch (err) {
@@ -188,30 +204,28 @@ async function runUtilsVerify(params) {
             error: String(err),
         });
         await recordUtilsVerifyError(params.testFile);
-        return toolError(`VERIFICATION ERROR — the shared-helper verifier could not run: ${String(err)}. This is not something to retry blindly; ` +
-            `it does not block skyramp_enhance_assertions or skyramp_execute_test. If the cause is in your files (unreadable utils file), fix it and verify once more.`);
+        return {
+            text: `VERIFICATION ERROR — the shared-helper verifier could not run: ${String(err)}. This is not something to retry blindly; ` +
+                `it does not block skyramp_enhance_assertions or skyramp_execute_test. If the cause is in your files (unreadable utils file), fix it and verify once more.`,
+            passed: false,
+            error: true,
+        };
     }
 }
-/** Verify mode: check the page-object calls the delivered spec already contains. */
-async function runVerify(params) {
-    // Route on the same predicate the prompt path routes on. A target the POM path
-    // never took must not reach the POM verifier — it is the sole writer of the POM
-    // reuse summary, and a POM-less run would otherwise emit POM numbers — so every
-    // non-POM target, including browser tests with the POM flag off, takes the
-    // SkyrampUtils verifier, which is what the prompt path handed it.
-    if (!isPomAwareTarget(params.language, params.framework, params.testType)) {
-        return runUtilsVerify(params);
-    }
+/** The page-object verifier and its gates, recording what the pass established. */
+async function runPomVerify(params, composed) {
     try {
         const r = await verifyReuse(params.testFile, params.language);
-        const gate = (await infraGateFailure(params, r)) ??
-            (await zeroReuseGateFailure(params, r));
+        const target = { ...params, composed };
+        const gate = (await infraGateFailure(target, r)) ??
+            (await zeroReuseGateFailure(target, r));
         // Record what this pass established before returning the text report:
         // every number in it is already in hand here, so the agent is never
         // asked to read one back out and retype it later.
         await recordVerifyOutcome(params.testFile, r, gate !== undefined, params.language);
         return {
-            content: [{ type: "text", text: composeVerifyText(gate, r) }],
+            text: composeVerifyText(gate, r),
+            passed: gate === undefined && r.ok,
         };
     }
     catch (err) {
@@ -219,14 +233,55 @@ async function runVerify(params) {
             testFile: params.testFile,
             error: String(err),
         });
-        return toolError(`VERIFICATION ERROR (treat as unverified, do not retry more than once): ${String(err)}`);
+        return {
+            text: `VERIFICATION ERROR (treat as unverified, do not retry more than once): ${String(err)}`,
+            passed: false,
+            error: true,
+        };
+    }
+}
+/** Verify mode: check the page-object calls the delivered spec already contains. */
+async function runVerify(params, route) {
+    // Route on the same decision the prompt path routes on. A call outside the POM
+    // pass must not reach the POM verifier alone — it is the sole writer of the POM
+    // reuse summary, and a POM-less run would otherwise emit POM numbers — so every
+    // other call, including browser tests with the POM flag off, takes the
+    // SkyrampUtils verifier, which is what the prompt path handed it.
+    if (route.pass === "utils") {
+        return verifyToolResult(route.composed
+            ? await runComposedVerify(params)
+            : await runUtilsVerify(params));
     }
+    const pom = await runPomVerify(params, route.composed);
+    // Both settings on: a PASSED page-object verify finishes that pass, and the next
+    // reuse call on the spec serves the SkyrampUtils flow over what it left inline.
+    if (pom.passed && route.composed)
+        await recordPomPassFinished(params.testFile);
+    return verifyToolResult(pom);
+}
+/** Both reuse settings on, after the page-object pass: one `verify: true` call checks
+ *  both halves of a spec that calls page objects AND shared helpers. The shared-helper
+ *  verifier writes the utils record; the page-object verifier — still the only writer
+ *  of the page-object record — re-checks the page-object calls the helper pass may
+ *  have moved. Skipped when the page-object pass found no layer: there is nothing to
+ *  re-check, and a verdict here would publish page-object numbers for a repository
+ *  without page objects. */
+async function runComposedVerify(params) {
+    const utils = await runUtilsVerify(params);
+    if ((await pomPassOutcome(params.testFile)) !== "finished")
+        return utils;
+    const pom = await runPomVerify(params, true);
+    return {
+        text: `## Page-object calls (the page-object pass)\n\n${pom.text}\n\n## Shared helpers\n\n${utils.text}\n\nThis call checks both. Re-run it after every fix; finish only when both parts report PASSED.`,
+        passed: utils.passed && pom.passed,
+        ...(utils.error || pom.error ? { error: true } : {}),
+    };
 }
 /** Discovery mode: the POM-aware refactoring procedure, scoped to this one spec.
  *
  *  Both the ordinary discovery call and the refused-verify path go through here, so the
  *  workflow a refused verify receives cannot drift from the one a first call receives. */
-async function runDiscovery(params, markKey) {
+async function runDiscovery(params, markKey, route) {
     logger.info("Analyzing code for reuse opportunities", {
         testFile: params.testFile,
         language: params.language,
@@ -237,7 +292,7 @@ async function runDiscovery(params, markKey) {
     // Deterministic POM pre-scoping (TS/JS+Playwright browser tests only).
     // Never blocks: any error or empty result falls back to the agent-driven STEP 1.
     let scopedPoms;
-    const pomAware = isPomAwareTarget(params.language, params.framework, params.testType);
+    const pomAware = route.pass === "pom";
     // The SkyrampUtils path records its debt here, where the instructions are issued:
     // from this point the tools that follow reuse on this spec refuse until a
     // `verify: true` pass has staged and checked the utils file (SKYR-4220).
@@ -253,10 +308,19 @@ async function runDiscovery(params, markKey) {
     if (pomAware) {
         try {
             const t0 = Date.now();
-            const { tier1, tier2, diagnostics } = await selectScopedPoms({
+            const scoped = await selectScopedPoms({
                 testFile: params.testFile,
                 specContent: params.prompt,
             });
+            const { diagnostics } = scoped;
+            // Both settings on: the page-object path owns class modules only; a
+            // free-function helper module is the in-house path's (pom-scope/ownership.ts).
+            const tier1 = route.composed
+                ? await pageObjectCandidates(scoped.tier1)
+                : scoped.tier1;
+            const tier2 = route.composed
+                ? await pageObjectCandidates(scoped.tier2)
+                : scoped.tier2;
             if (tier1.length + tier2.length > 0) {
                 scopedPoms = { tier1, tier2 };
                 // Only report candidates found through the conventional POM globs.
@@ -276,12 +340,17 @@ async function runDiscovery(params, markKey) {
                     await recordCandidates(params.testFile, tier1.length, params.language);
                 }
             }
-            else if (diagnostics.selectors > 0 &&
-                diagnostics.discovery !== "skipped-too-large") {
+            else if ((diagnostics.selectors > 0 &&
+                diagnostics.discovery !== "skipped-too-large") ||
+                // Every candidate was a free-function module, which is not this path's.
+                scoped.tier1.length + scoped.tier2.length > 0) {
                 // A clean scan ran (glob or selector-grep) and found zero overlap — distinct from
                 // "scoping wasn't attempted" (no selectors) or "scan was skipped" (repo too large).
                 scopedPoms = { tier1: [], tier2: [], scannedNoOverlap: true };
                 await recordNoPomLayer(params.testFile);
+                // Both settings on: no page-object layer finishes that pass at once.
+                if (route.composed)
+                    await recordPomPassFinished(params.testFile);
             }
             logger.info("POM pre-scoping", {
                 ...diagnostics,
@@ -294,7 +363,7 @@ async function runDiscovery(params, markKey) {
             logger.warning("POM pre-scoping failed — falling back to agent-driven detection", { error: String(err) });
         }
     }
-    const codeReusePrompt = getCodeReusePrompt(params.testFile, params.language, params.framework, scopedPoms, params.testType);
+    const codeReusePrompt = getCodeReusePrompt(params.testFile, params.language, params.framework, scopedPoms, params.testType, route);
     // Marked on the last line before the return, so the mark cannot be observed until the
     // workflow it stands for has been built. An earlier mark let a verify arriving mid-scope
     // check a spec that had not been handed the procedure yet.
@@ -336,7 +405,7 @@ export function registerCodeReuseTool(server) {
       - No actual function definitions found in other test files
 
       Applicability is decided by the caller: when a generation result was produced with \`codeReuse: true\`, it directs you here — ALWAYS follow through (a no-op result is a normal outcome, never a failure). Multi-step tests (UI, E2E, INTEGRATION, LOAD) are the ones that benefit; simple single-request tests (smoke, contract, fuzz) do not request code reuse.
-      The tool will provide step-by-step instructions that MUST be followed exactly.${isPomReuseEnabled() ? POM_AWARE_MODE_DESCRIPTION : ""}`,
+      The tool will provide step-by-step instructions that MUST be followed exactly.${pomAwareModeDescription()}`,
         inputSchema: codeReuseSchema.shape,
         _meta: {
             keywords: [
@@ -350,11 +419,12 @@ export function registerCodeReuseTool(server) {
     }, async (params) => {
         let errorResult;
         try {
+            const route = await resolveReuseRoute(params);
             if (params.verify) {
                 const markKey = markKeyFor(params.testFile);
-                if (mustDiscoverFirst(params, markKey)) {
+                if (mustDiscoverFirst(markKey, route)) {
                     logger.info("Verify called before the discovery pass — returning the discovery workflow", { testFile: params.testFile });
-                    const workflow = await runDiscovery(params, markKey);
+                    const workflow = await runDiscovery(params, markKey, route);
                     return {
                         content: [
                             {
@@ -364,13 +434,12 @@ export function registerCodeReuseTool(server) {
                         ],
                     };
                 }
-                return await runVerify(params);
+                return await runVerify(params, route);
             }
             // Modularize-first targets owe skyramp_modularization before reuse is issued —
             // the other half of the pair the hand-off names. Only ever owed for a file
-            // generation handed off, so NL callers and POM targets are untouched.
-            if (isUtilsReuseEnabled() &&
-                !isPomAwareTarget(params.language, params.framework, params.testType)) {
+            // generation handed off, so NL callers and the page-object pass are untouched.
+            if (isUtilsReuseEnabled() && route.pass === "utils") {
                 const owed = await pendingModularization(params.testFile);
                 if (owed) {
                     errorResult = toolError(owed);
@@ -381,7 +450,7 @@ export function registerCodeReuseTool(server) {
                 content: [
                     {
                         type: "text",
-                        text: await runDiscovery(params, markKeyFor(params.testFile)),
+                        text: await runDiscovery(params, markKeyFor(params.testFile), route),
                     },
                 ],
             };

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

@@ -12,7 +12,7 @@ function buildAutoApplyInstructions(testFile, testType, enhanceType) {
         `Test type: ${testType} | Context: ${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.`,
+        `Add assertions after each send_request/sendRequest status-code assertion, except on a setup request.`,
         `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.`,
         ``,
@@ -99,7 +99,7 @@ export function registerEnhanceAssertionsTool(server) {
                 `Enhance response body assertions in: \`${testFile}\``,
                 `Test type: ${testType} | Context: ${enhanceType}`,
                 ``,
-                `Read the file, add assertions after each send_request/sendRequest status-code assertion, write it back.`,
+                `Read the file, add assertions after each send_request/sendRequest status-code assertion, except on a setup request, write it back.`,
                 `Use SDK helper: Python \`skyramp.get_response_value(response, "json.path")\`, JS \`getValue(response, "json.path")\`.`,
                 ``,
                 `Shared assertion rules (apply all that fit):`,

package/build/tools/code-refactor/helper-callers.d.ts

@@ -0,0 +1,65 @@
+import type { HelperChangeKind } from "../../types/ReuseOutcome.js";
+/**
+ * A helper this run changed under the callers it already had — the shared-helper
+ * blast radius nothing in the product measured.
+ *
+ * A shared helper's change reaches every caller at once. The run executes what it
+ * DELIVERS, and an untouched caller is not delivered, so a break in one reached the
+ * customer's own continuous integration instead of the report. Worse for a browser
+ * helper: a changed selector alters what every caller does and appears in no calling
+ * test's diff.
+ *
+ * TWO PREDICATES, never one. `change` is the claim that the helper differs from its
+ * incumbent, and rests only on reading the module at HEAD. `callers` present is the
+ * separate claim that the caller list can be believed, and rests on the importer walk
+ * having read the module's directory. The gate acts on POSITIVE evidence — a file
+ * that was read, that imports this module, and that names this helper — and never on
+ * the absence of one; the disclosure states the list only when it is present, and
+ * says the callers are unknown otherwise. One predicate driving both would make a
+ * read error either demand a run for a helper nobody calls or assert a caller set
+ * that is wrong.
+ */
+export interface ChangedHelperView {
+    /** Absolute path of the shared module. */
+    utilsFile: string;
+    helper: string;
+    change: HelperChangeKind;
+    /** ABSOLUTE PATHS of the Skyramp-generated tests that IMPORT this helper — a
+     *  superset of those that call it, since an imported binding need not be used.
+     *  Detection stops at the import on purpose: a call can reach the helper through an
+     *  alias, a re-export, or a local wrapper, and a syntactic call check would miss
+     *  those. A missed caller is an unexecuted test that breaks in the customer's
+     *  continuous integration; an unused import costs one extra execution of a test
+     *  that is runnable by construction. This over-runs rather than under-runs.
+     *
+     *  ABSENT when the importer walk did not run — the one case where a list would be
+     *  an artefact rather than a lower bound. Present, it is a lower bound: the walk
+     *  covers ONE directory, so a generated test importing this module from anywhere
+     *  else is not here. An empty list is the positive statement that the walk ran and
+     *  found none beside the module. */
+    callers?: string[];
+}
+/** A shared module of one directory as this run left it, with what it was. */
+export interface ChangedModule {
+    /** Absolute path. A module that is gone is named by the path it had. */
+    file: string;
+    /** The module at HEAD — read once by the caller, which also used it to decide the
+     *  file IS a module (the header it carried there). */
+    head: string;
+}
+/**
+ * The helpers this run changed in `modules`, each with the tests beside it that
+ * import it.
+ *
+ * PER DIRECTORY, not per spec. The importer walk reads the modules' directory and
+ * nothing else, so every view here is a fact about the directory: which delivered
+ * spec happens to sit beside a module does not change it, and two specs beside one
+ * module would compute the same views twice. A module no spec names — deleted by a
+ * run that also dropped its import — is still a changed module of its directory,
+ * which is what stops un-sharing the helpers from being the way past the gate.
+ *
+ * No git here. The caller established from git which files were modules at HEAD
+ * and what they held; this compares that against the working tree and walks the
+ * directory. A module whose working copy cannot be read contributes nothing.
+ */
+export declare function changedHelperCallers(modules: ChangedModule[]): Promise<ChangedHelperView[]>;

package/build/tools/code-refactor/helper-callers.js

@@ -0,0 +1,85 @@
+import * as fs from "fs/promises";
+import { logger } from "../../utils/logger.js";
+import { changedHelpersBetween, helperImporters, parseUtilsFile, utilsSpecForFile, } from "../../utils/utils-verify/index.js";
+/**
+ * The helpers this run changed in `modules`, each with the tests beside it that
+ * import it.
+ *
+ * PER DIRECTORY, not per spec. The importer walk reads the modules' directory and
+ * nothing else, so every view here is a fact about the directory: which delivered
+ * spec happens to sit beside a module does not change it, and two specs beside one
+ * module would compute the same views twice. A module no spec names — deleted by a
+ * run that also dropped its import — is still a changed module of its directory,
+ * which is what stops un-sharing the helpers from being the way past the gate.
+ *
+ * No git here. The caller established from git which files were modules at HEAD
+ * and what they held; this compares that against the working tree and walks the
+ * directory. A module whose working copy cannot be read contributes nothing.
+ */
+export async function changedHelperCallers(modules) {
+    const anchor = modules[0]?.file;
+    if (!anchor)
+        return [];
+    const spec = utilsSpecForFile(anchor);
+    if (!spec)
+        return [];
+    const helpersByFile = new Map();
+    const changedByFile = new Map();
+    for (const { file, head } of modules) {
+        // A module that is GONE reads as empty, which makes every helper it had at HEAD a
+        // removal — the same finding as deleting them one at a time. Only absence means
+        // that. Any other read failure — a permission error, a transient fault, a
+        // directory in its place — is the module not being readable, which is not
+        // evidence of anything: treating it as empty would call every incumbent helper
+        // removed and demand a run of every caller, on a malfunction.
+        let current;
+        try {
+            current = await fs.readFile(file, "utf8");
+        }
+        catch (err) {
+            if (err?.code !== "ENOENT") {
+                logger.warning("Could not read a shared module — the helpers it changed will not be reported", { file, error: String(err) });
+                continue;
+            }
+            current = "";
+        }
+        const changes = changedHelpersBetween(head, current, spec);
+        if (changes.length === 0)
+            continue;
+        changedByFile.set(file, changes);
+        // A REMOVED helper is not in the current module, so a caller set read off that
+        // module alone would find none — and report "nothing calls it" about the one
+        // change that breaks every caller's import outright. The incumbent's definitions
+        // of the removed names go into the walk beside the current ones.
+        const helpers = parseUtilsFile(current, spec);
+        const gone = new Set(changes.filter((c) => c.change === "removed").map((c) => c.helper));
+        helpersByFile.set(file, gone.size === 0
+            ? helpers
+            : [
+                ...helpers,
+                ...parseUtilsFile(head, spec).filter((h) => gone.has(h.name)),
+            ]);
+    }
+    if (changedByFile.size === 0)
+        return [];
+    // Anchored on the module: the walk reads the anchor's directory, which is the
+    // module's own. A deleted anchor still has a directory.
+    const scan = await helperImporters(anchor, [...changedByFile.keys()], helpersByFile, spec);
+    const importersOf = new Map(scan.helpers.map((h) => [`${h.file}\0${h.helper}`, h.importers]));
+    const out = [];
+    for (const [utilsFile, changes] of changedByFile)
+        for (const c of changes)
+            out.push({
+                utilsFile,
+                helper: c.helper,
+                change: c.change,
+                ...(scan.read
+                    ? {
+                        callers: [
+                            ...(importersOf.get(`${utilsFile}\0${c.helper}`) ?? []),
+                        ].sort(),
+                    }
+                    : {}),
+            });
+    return out;
+}

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

@@ -2,6 +2,7 @@ import { z } from "zod";
 import { fixErrorsInstruction } from "../../skills/fixTestImportErrorsSkill.js";
 import fs from "fs";
 import { logger } from "../../utils/logger.js";
+import { toolError } from "../../utils/utils.js";
 import { ProgrammingLanguage, TestType } from "../../types/TestTypes.js";
 import { ModularizationService, } from "../../services/ModularizationService.js";
 import { AnalyticsService } from "../../services/AnalyticsService.js";
@@ -9,6 +10,7 @@ import { normalizeLanguageParams, resolveParamAliases, } from "../../utils/norma
 import { normalizeSkyrampImportsInFile } from "../../utils/normalizeSkyrampImports.js";
 import { stageGeneratedPaths } from "../../utils/gitStaging.js";
 import { recordModularized } from "./reuse-state.js";
+import { pendingPomPass } from "./pom-pass-state.js";
 const modularizationSchema = {
     testFile: z
         .string()
@@ -82,6 +84,14 @@ After modularization, if errors remain, ${fixErrorsInstruction()}.
             if (!params.isTraceBased &&
                 [TestType.UI, TestType.E2E, TestType.INTEGRATION].includes(params.testType))
                 params.isTraceBased = true;
+            // Both reuse settings on: the page-object pass maps the raw steps first, and
+            // its gates judge the spec while what it did not substitute is still inline.
+            // Checked before anything is recorded, so a refused call leaves no mark.
+            const owedPomPass = await pendingPomPass(params.testFile);
+            if (owedPomPass) {
+                errorResult = toolError(owedPomPass);
+                return errorResult;
+            }
             normalizeSkyrampImportsInFile(params.testFile);
             // Stage so testbot includes the generated files in its output commit.
             await stageGeneratedPaths(params.testFile);

package/build/tools/code-refactor/pom-pass-state.d.ts

@@ -0,0 +1,51 @@
+import type { ReuseHandOff } from "../../utils/AnalysisStateManager.js";
+import type { ReuseRederivation } from "./reuse-state.js";
+/**
+ * The page-object pass as run state, for a target both reuse settings serve
+ * (isPomFirstTarget): whether the pass has finished for a spec, the mark that
+ * finishes it, the checkpoint that holds modularization until it has, and the
+ * merge of the two halves one such spec's report row carries.
+ */
+/** Whether a hand-off's chain starts with the page-object pass. Derived from what the
+ *  hand-off already stores, never recorded beside it: generation writes the hand-off
+ *  from exactly these three values, and maintenance arms none for such a target. */
+export declare function pomFirstHandOff(handOff: ReuseHandOff): boolean;
+/**
+ * With both reuse settings on (isPomFirstTarget), where this spec's page-object pass
+ * stands. `undefined` while it is open; `"finished"` once its verify pass PASSED;
+ * `"no-layer"` when discovery found no page-object layer to reuse. From then on the
+ * reuse tool serves the SkyrampUtils flow for the spec, and the page-object gates
+ * have already judged the spec while every step they did not substitute was still raw
+ * and inline — the state they were written for.
+ *
+ * A FAILED verdict keeps the pass open: the page-object report says to fix and
+ * re-verify, and `pendingReuseVerification` refuses the tools after it until that
+ * happens. A record owned by another spec, or no run state, reads as open; the caller
+ * then serves the page-object pass, which is what the spec gets without composition.
+ */
+export declare function pomPassOutcome(testFile: string, explicitStateFile?: string): Promise<"finished" | "no-layer" | undefined>;
+/** Mark the page-object pass finished for a spec (see `pomPassOutcome`). Written by
+ *  the reuse tool at the two points that finish it: a PASSED page-object verify, and
+ *  discovery that found no page-object layer. */
+export declare function recordPomPassFinished(testFile: string, explicitStateFile?: string): Promise<void>;
+/**
+ * Does this spec owe its page-object pass before `skyramp_modularization`? Only a spec
+ * generation handed off with the page-object pass first. Modularizing first would move
+ * the raw steps the page-object pass maps into helpers it cannot see, and its gates
+ * would then judge a spec with nothing left inline. Fails open without a hand-off, on
+ * an unreadable or unwritable state file.
+ */
+export declare function pendingPomPass(testFile: string, explicitStateFile?: string): Promise<string | undefined>;
+/**
+ * One row, both halves. The outcome fields are disjoint by construction (the
+ * page-object fields sit at the top level, the shared-helper ones under `helpers` and
+ * `inHouse`). The two blocking verdicts become ONE, because the report refuses per
+ * spec and one `verify: true` call re-checks both halves (the reuse tool's combined
+ * verify). Declines are retired only where the half that owns them was measured: the
+ * page-object half measures a `kept inline` decline only when its zero-reuse gate
+ * walked the candidates, which it does not at non-zero reuse.
+ */
+export declare function combineRederivations(pom: ReuseRederivation, helper: ReuseRederivation, carriesKeptInline: boolean, 
+/** The call that re-checks both halves — the shared-helper verify call, which the
+ *  reuse tool routes to its combined verify for such a spec. */
+combinedVerifyCall: string | undefined): ReuseRederivation;