@skyramp/mcp 0.4.2 → 0.4.3-rc.1

package/build/types/ReuseOutcome.d.ts

@@ -131,6 +131,79 @@ export interface RetrofitOutcome {
     file: string;
     execution?: TestExecutionStatus;
 }
+/** What a run did to a helper that already existed in the repository. A helper the
+ *  module gained is not here: this run created it, and it has no incumbent callers
+ *  whose behaviour it could change. */
+export type HelperChangeKind = 
+/** The parameter list differs — the change a caller's own diff can be read
+ *  against, and the one an added argument or a re-defaulted argument lands in
+ *  (a helper re-defaulted to a rejection status is the recorded case). */
+"signature"
+/** The parameter list is byte-identical and the body is not. The dangerous case
+ *  for a browser helper: a selector change alters what every caller does and
+ *  appears in no calling test's diff. */
+ | "body"
+/** The incumbent defined it and the module no longer does. Every caller's import
+ *  now names something that is not there. */
+ | "removed";
+/** A helper this run changed in a module that already existed in the repository,
+ *  with the tests that call it.
+ *
+ *  A shared helper's change reaches every caller at once — that is the feature's
+ *  value and its danger. A caller the run did not touch is not delivered, so nothing
+ *  executed it, and a break in one reached the customer's own continuous integration
+ *  instead of this report. A browser helper is the worse case: its selector can
+ *  change with no signature change at all, and the change appears in no calling
+ *  test's diff. */
+export interface ChangedHelperEntry {
+    /** REPOSITORY-RELATIVE path (posix) of the module that defines it — per helper,
+     *  as {@link OrphanedHelper} names its: a delivery can carry several modules, and
+     *  the same helper name in two of them is two entries a reader must tell apart. */
+    utilsFile: string;
+    helper: string;
+    change: HelperChangeKind;
+    /** The Skyramp-generated tests that call it, by BASENAME, each with the execution
+     *  recorded against the module as it stands.
+     *
+     *  SCOPED TO THE MODULE'S OWN DIRECTORY, which is as far as the caller walk reads.
+     *  A generated test that imports the module from another directory is not here, so
+     *  this is a lower bound: read it as "the callers found beside the module", never
+     *  as "every test that calls it". The gate acts only on what is listed, so a caller
+     *  it cannot see costs a report line and an unrun test — never a false block, which
+     *  is the direction this feature chooses everywhere.
+     *
+     *  ABSENT means even that much could not be established — never "no test calls
+     *  it". An empty array is the positive statement that the walk ran and found
+     *  none beside the module. A caller with no `execution` and no `deliveredByThisRun`
+     *  was not run: the run could not execute it (a native suite, or a test the prescan
+     *  never inventoried), which is disclosed rather than blocked on. */
+    callers?: ChangedHelperCaller[];
+}
+export interface ChangedHelperCaller {
+    /** BASENAME of the calling test. */
+    file: string;
+    execution?: TestExecutionStatus;
+    /** This run delivered or edited the caller, so its own row in this report carries
+     *  its execution and its own checks judge it. Read an absent `execution` as "not
+     *  run" only when this is absent too. */
+    deliveredByThisRun?: true;
+}
+/** A helper in a shared module that NO Skyramp-generated test imports.
+ *
+ *  A run can delete a test, and a helper that test was the last importer of stays in
+ *  the module. The customer then maintains code nothing calls, and nothing in the
+ *  pull request says so — the agent was told, and the reviewer was not.
+ *
+ *  REPORTED, never removed, and never gated. Removing a helper that is still called
+ *  is far worse than leaving a dead one, and the caller list this is read from is a
+ *  lower bound scoped to the module's directory. A reader decides; the run does not. */
+export interface OrphanedHelper {
+    /** REPOSITORY-RELATIVE path (posix) of the module that defines it. Per helper, not
+     *  per row: a delivery can carry several modules, and a reader needs the file to
+     *  open. */
+    utilsFile: string;
+    helper: string;
+}
 /** Shared-helper reuse for an API test, re-derived from the delivered files at report
  *  time — nothing here is read back from what the agent or the verify pass recorded.
  *  Absent altogether when no utils file exists for the test (the same omission rule
@@ -159,6 +232,16 @@ export interface HelperReuseOutcome {
      *  wraps — reuse that was available and not taken. Omitted at zero. Informational,
      *  like {@link ReuseOutcome.missedReuse}. */
     siblingInlineCallSites?: number;
+    /** Helpers in `utilsFile` that no Skyramp-generated test imports — see
+     *  {@link OrphanedHelper}. Omitted when there are none, and omitted (with
+     *  `orphanScanIncomplete` set) when the walk could not establish the importers at
+     *  all. Informational: nothing gates on it. */
+    orphanedHelpers?: OrphanedHelper[];
+    /** Present — and only ever `true` — when the importer walk could not read every
+     *  file beside the module, so no helper is reported as orphaned. Absent means the
+     *  walk ran, so an absent `orphanedHelpers` then means none were found rather than
+     *  that nothing was looked for. */
+    orphanScanIncomplete?: true;
     /** Whether the delivered utils file holds the shared-helper invariants: one helper
      *  per method+path, status-code-only assertions, method+resource names — with
      *  documented declines (`reuse-verify: allow …`) counted as holding. */
@@ -296,6 +379,19 @@ export interface ReuseOutcome {
      *  not the module, and is most telling when no module exists at all — the case
      *  where `helpers` is rightly absent. Omitted at zero. Informational. */
     unextractedDuplicateSites?: number;
+    /** Helpers that already existed in the repository and that this run CHANGED, each
+     *  with the tests that call it. Omitted when the run changed no incumbent helper —
+     *  which is every first run, where the module is created rather than edited. A
+     *  helper an earlier run created and this one changed appears here as changed,
+     *  never as created.
+     *
+     *  Top level, not on the helpers row, for the same reason as
+     *  {@link unextractedDuplicateSites}: it describes what happened to a module, and
+     *  it is most telling when NO module is there to describe — a run that deleted or
+     *  renamed the shared module removes every helper at once and leaves `helpers`
+     *  rightly absent, which is exactly when a reader most needs to be told. See
+     *  {@link ChangedHelperEntry}. */
+    changedHelpers?: ChangedHelperEntry[];
     verification?: ReuseVerificationOutcome;
     /** Why `verification` is `failed` on the page-object path, on the same terms as
      *  {@link HelperReuseOutcome.verificationFailures}: present only when the

package/build/types/TestExecution.d.ts

@@ -14,6 +14,17 @@ export declare enum TestExecutionStatus {
     /** Execution was expected (UPDATE/REGENERATE) but no result was recorded. */
     Unknown = "Unknown"
 }
+/** Whether a status is a RESULT: the test ran and pass, fail or error is what it
+ *  did. `Skipped` is a decision not to execute and `Unknown` is an execution that was
+ *  expected and recorded nothing — neither may satisfy a demand for a run, or a run
+ *  that never touched the file would clear the debt for it. */
+export declare function isResult(status: TestExecutionStatus): boolean;
+/** The status of `record` when it is a result that ran the bytes written at
+ *  `sinceMs` or later, and `undefined` otherwise. THE freshness rule, for every gate
+ *  that asks whether a file has been run as it now stands: an execution older than
+ *  the last write to what it exercised ran bytes that no longer exist. Which write —
+ *  the file's own, or a module's under it — is the caller's to say. */
+export declare function freshExecution(record: Pick<TestExecutionData, "status" | "executedAt"> | undefined, sinceMs: number): TestExecutionStatus | undefined;
 export interface TestExecutionData {
     status: TestExecutionStatus;
     executedAt: string;

package/build/types/TestExecution.js

@@ -14,3 +14,22 @@ export var TestExecutionStatus;
     /** Execution was expected (UPDATE/REGENERATE) but no result was recorded. */
     TestExecutionStatus["Unknown"] = "Unknown";
 })(TestExecutionStatus || (TestExecutionStatus = {}));
+/** Whether a status is a RESULT: the test ran and pass, fail or error is what it
+ *  did. `Skipped` is a decision not to execute and `Unknown` is an execution that was
+ *  expected and recorded nothing — neither may satisfy a demand for a run, or a run
+ *  that never touched the file would clear the debt for it. */
+export function isResult(status) {
+    return (status === TestExecutionStatus.Pass ||
+        status === TestExecutionStatus.Fail ||
+        status === TestExecutionStatus.Error);
+}
+/** The status of `record` when it is a result that ran the bytes written at
+ *  `sinceMs` or later, and `undefined` otherwise. THE freshness rule, for every gate
+ *  that asks whether a file has been run as it now stands: an execution older than
+ *  the last write to what it exercised ran bytes that no longer exist. Which write —
+ *  the file's own, or a module's under it — is the caller's to say. */
+export function freshExecution(record, sinceMs) {
+    if (!record || !isResult(record.status))
+        return undefined;
+    return Date.parse(record.executedAt) >= sinceMs ? record.status : undefined;
+}

package/build/types/index.d.ts

@@ -4,5 +4,5 @@ export { TestType, HttpMethod } from "./TestTypes.js";
 export type { TestbotReport } from "./TestbotReport.js";
 export { IssueFoundCategory } from "./TestbotReport.js";
 export { ReuseDeclinedBy, ReuseVerificationOutcome, HelperVerificationOutcome, } from "./ReuseOutcome.js";
-export type { ReuseOutcome, ReuseSkippedEntry, ReuseMissedEntry, HelperReuseOutcome, RetrofitOutcome, } from "./ReuseOutcome.js";
+export type { ReuseOutcome, ReuseSkippedEntry, ReuseMissedEntry, HelperReuseOutcome, RetrofitOutcome, ChangedHelperEntry, ChangedHelperCaller, OrphanedHelper, } from "./ReuseOutcome.js";
 export type { RelatedRepository, TestbotPromptOptions, } from "./TestbotPromptOptions.js";

package/build/utils/branchDiff.d.ts

@@ -72,5 +72,5 @@ export declare function changedFileNames(diff: BranchDiffData): ChangedFileName[
  *  compares two commits through the three-dot form, which is the CI shape. */
 export declare function computeBranchDiff(repositoryPath: string, providedBaseBranch?: string, includeUncommitted?: boolean, 
 /** Names only: no diff text is computed, and `diffContent`/`diffStat` come back
- *  empty. The plan checks read which files changed, never what changed in them. */
+ *  empty. */
 namesOnly?: boolean): Promise<BranchDiffData>;

package/build/utils/branchDiff.js

@@ -349,7 +349,7 @@ export function changedFileNames(diff) {
  *  compares two commits through the three-dot form, which is the CI shape. */
 export async function computeBranchDiff(repositoryPath, providedBaseBranch, includeUncommitted = false, 
 /** Names only: no diff text is computed, and `diffContent`/`diffStat` come back
- *  empty. The plan checks read which files changed, never what changed in them. */
+ *  empty. */
 namesOnly = false) {
     const git = simpleGit(repositoryPath);
     const isRepo = await git.checkIsRepo();

package/build/utils/changedRuns.d.ts

@@ -0,0 +1,13 @@
+/** One run of consecutive changed lines in a file: lines removed, added, or both. */
+export interface ChangedRun {
+    file: string;
+    /** First and last line of the run in the new file. A run that only removes
+     *  lines has none of its own, so both name the line that now follows it. */
+    start: number;
+    end: number;
+    /** The run's first changed line as the diff shows it, for the evidence. */
+    firstLine: string;
+}
+/** Every run of changed lines, file by file, in the new file's numbering. A run
+ *  whose changed lines are all blank changes nothing a test can observe. */
+export declare function collectChangedRuns(rawDiff: string): ChangedRun[];

package/build/utils/changedRuns.js

@@ -0,0 +1,56 @@
+import { diffBlocksByPath } from "./branchDiff.js";
+/** Every run of changed lines, file by file, in the new file's numbering. A run
+ *  whose changed lines are all blank changes nothing a test can observe. */
+export function collectChangedRuns(rawDiff) {
+    const runs = [];
+    for (const [file, block] of diffBlocksByPath(rawDiff)) {
+        let inHunk = false;
+        let newLine = 0;
+        let open;
+        const close = () => {
+            if (open && open.lines.some((text) => text.slice(1).trim() !== "")) {
+                runs.push({
+                    file,
+                    start: open.start,
+                    end: open.added > 0 ? open.start + open.added - 1 : open.start,
+                    firstLine: open.lines.find((text) => text.slice(1).trim() !== "") ?? "",
+                });
+            }
+            open = undefined;
+        };
+        for (const text of block.split("\n")) {
+            // A path printed twice holds its header twice, and the second one is no hunk.
+            if (text.startsWith("diff ")) {
+                close();
+                inHunk = false;
+                continue;
+            }
+            const hunk = /^@@ -\d+(?:,\d+)? \+(\d+)/.exec(text);
+            if (hunk) {
+                close();
+                inHunk = true;
+                newLine = Number(hunk[1]);
+                continue;
+            }
+            // Only the file header spells `---`/`+++`; inside a hunk they are content.
+            if (!inHunk)
+                continue;
+            if (text.startsWith("-") || text.startsWith("+")) {
+                open ??= { start: newLine, added: 0, lines: [] };
+                open.lines.push(text);
+                if (text.startsWith("+")) {
+                    open.added++;
+                    newLine++;
+                }
+            }
+            else if (!text.startsWith("\\")) {
+                // `` belongs to the line before it.
+                close();
+                if (text.startsWith(" "))
+                    newLine++;
+            }
+        }
+        close();
+    }
+    return runs;
+}

package/build/utils/featureFlags.d.ts

@@ -4,8 +4,9 @@
  * Each helper in this module reads a `SKYRAMP_FEATURE_*` env var and returns
  * a boolean. These helpers treat a flag as ON only when the env var is
  * exactly `"1"`; anything else (unset, empty, "0", "true", "false", etc.) is
- * treated as OFF. The utils-reuse flag is additionally ON for the orgs in
- * `UTILS_REUSE_DEFAULT_ORGS` regardless of the env vars.
+ * treated as OFF. The POM-reuse and utils-reuse flags are additionally ON for
+ * the orgs in `POM_REUSE_DEFAULT_ORGS` and `UTILS_REUSE_DEFAULT_ORGS`
+ * regardless of the env vars.
  */
 /**
  * Gates BOTH consumer-side contract tests AND the SDK's "default mode"
@@ -54,15 +55,12 @@ export declare function isLocalDevEnabled(): boolean;
 export declare function isOneClickEnabled(): boolean;
 /**
  * Gates the POM-aware path of `skyramp_reuse_code`
- * (SKYRAMP_FEATURE_POM_REUSE=1).
+ * (SKYRAMP_FEATURE_POM_REUSE=1, or a `POM_REUSE_DEFAULT_ORGS` org).
  *
- * Deliberately NOT defaulted on for `UTILS_REUSE_DEFAULT_ORGS`: for UI tests
- * the POM path supersedes the modularize-first flow (see
- * `isModularizeFirstTarget` in utils/reuseRouting.ts), so an org-level POM
- * default would stop those orgs' UI tests from ever seeding a SkyrampUtils
- * file — the very thing the utils org default exists to provide (SKYR-4290).
- * And an explicit-"0"-override escape hatch cannot work either, because
- * testbot normalizes an unset flag to a literal "0" before forwarding.
+ * With both flags on, a UI test takes the POM pass first and the
+ * modularize-first flow over what it left inline (see `isPomFirstTarget` in
+ * utils/reuseRouting.ts), so a `POM_REUSE_DEFAULT_ORGS` org that also has the
+ * utils default still seeds a SkyrampUtils file for its UI tests.
  *
  * When OFF (default), TypeScript/JavaScript + Playwright targets are treated
  * like every other target: `skyramp_reuse_code` returns the SkyrampUtils

package/build/utils/featureFlags.js

@@ -4,8 +4,9 @@
  * Each helper in this module reads a `SKYRAMP_FEATURE_*` env var and returns
  * a boolean. These helpers treat a flag as ON only when the env var is
  * exactly `"1"`; anything else (unset, empty, "0", "true", "false", etc.) is
- * treated as OFF. The utils-reuse flag is additionally ON for the orgs in
- * `UTILS_REUSE_DEFAULT_ORGS` regardless of the env vars.
+ * treated as OFF. The POM-reuse and utils-reuse flags are additionally ON for
+ * the orgs in `POM_REUSE_DEFAULT_ORGS` and `UTILS_REUSE_DEFAULT_ORGS`
+ * regardless of the env vars.
  */
 /**
  * Gates BOTH consumer-side contract tests AND the SDK's "default mode"
@@ -62,15 +63,12 @@ export function isOneClickEnabled() {
 }
 /**
  * Gates the POM-aware path of `skyramp_reuse_code`
- * (SKYRAMP_FEATURE_POM_REUSE=1).
+ * (SKYRAMP_FEATURE_POM_REUSE=1, or a `POM_REUSE_DEFAULT_ORGS` org).
  *
- * Deliberately NOT defaulted on for `UTILS_REUSE_DEFAULT_ORGS`: for UI tests
- * the POM path supersedes the modularize-first flow (see
- * `isModularizeFirstTarget` in utils/reuseRouting.ts), so an org-level POM
- * default would stop those orgs' UI tests from ever seeding a SkyrampUtils
- * file — the very thing the utils org default exists to provide (SKYR-4290).
- * And an explicit-"0"-override escape hatch cannot work either, because
- * testbot normalizes an unset flag to a literal "0" before forwarding.
+ * With both flags on, a UI test takes the POM pass first and the
+ * modularize-first flow over what it left inline (see `isPomFirstTarget` in
+ * utils/reuseRouting.ts), so a `POM_REUSE_DEFAULT_ORGS` org that also has the
+ * utils default still seeds a SkyrampUtils file for its UI tests.
  *
  * When OFF (default), TypeScript/JavaScript + Playwright targets are treated
  * like every other target: `skyramp_reuse_code` returns the SkyrampUtils
@@ -83,7 +81,8 @@ export function isOneClickEnabled() {
  * the verification gates apply.
  */
 export function isPomReuseEnabled() {
-    return process.env.SKYRAMP_FEATURE_POM_REUSE === "1";
+    return (process.env.SKYRAMP_FEATURE_POM_REUSE === "1" ||
+        isDefaultOrg(POM_REUSE_DEFAULT_ORGS));
 }
 /**
  * Gates SkyrampUtils code reuse for integration tests on the testbot path, and
@@ -107,27 +106,30 @@ export function isPomReuseEnabled() {
  * yields the single reuse pass it did before the feature existed.
  */
 export function isUtilsReuseEnabled() {
-    return (process.env.SKYRAMP_FEATURE_UTILS_REUSE === "1" || isUtilsReuseDefaultOrg());
+    return (process.env.SKYRAMP_FEATURE_UTILS_REUSE === "1" ||
+        isDefaultOrg(UTILS_REUSE_DEFAULT_ORGS));
 }
 /**
- * GitHub orgs where SkyrampUtils code reuse is on by default, without
- * requiring the SKYRAMP_FEATURE_UTILS_REUSE env var. Compared
- * case-insensitively (GitHub owner handles are case-insensitive, but
- * GITHUB_REPOSITORY_OWNER preserves display casing). Because this ORs with
- * the env check, these orgs cannot turn the feature off by setting the env
- * var to "0". POM reuse has no org default — see `isPomReuseEnabled`.
+ * GitHub orgs where a reuse feature is on by default, without requiring its
+ * SKYRAMP_FEATURE_* env var. Compared case-insensitively (GitHub owner handles
+ * are case-insensitive, but GITHUB_REPOSITORY_OWNER preserves display casing).
+ * Because these OR with the env check, these orgs cannot turn the feature off
+ * by setting the env var to "0" — and testbot normalizes an unset flag to a
+ * literal "0" anyway.
  *
- * "Skyramp-HandsOn" is the Wipro / IntelliAssure pilot org (SKYR-4286).
+ * "Skyramp-HandsOn" is the Wipro / IntelliAssure pilot org (SKYR-4286 for
+ * utils reuse, SKYR-4514 for POM reuse).
  */
 const UTILS_REUSE_DEFAULT_ORGS = ["skyramp-handson"];
-function isUtilsReuseDefaultOrg() {
+const POM_REUSE_DEFAULT_ORGS = ["skyramp-handson"];
+function isDefaultOrg(orgs) {
     // GITHUB_REPOSITORY_OWNER is set on GitHub Actions runners; fall back to
     // the owner half of GITHUB_REPOSITORY ("owner/repo") for environments that
     // only set the latter.
     const owner = process.env.GITHUB_REPOSITORY_OWNER ??
         process.env.GITHUB_REPOSITORY?.split("/")[0] ??
         "";
-    return UTILS_REUSE_DEFAULT_ORGS.includes(owner.toLowerCase());
+    return orgs.includes(owner.toLowerCase());
 }
 /**
  * Returns true when the calling agent has the Skyramp Agent Skills plugin

package/build/utils/normalizeSkyrampImports.d.ts

@@ -1,7 +1,10 @@
 /**
  * Ensure `expect` is imported from `@skyramp/skyramp` rather than `@playwright/test`.
  * - Strips `expect` from any `@playwright/test` import (keeps other identifiers).
- * - If the file uses `expect(...)`, ensures an `@skyramp/skyramp` import carries `expect`.
+ * - If the file uses `expect(...)`, ensures its `@skyramp/skyramp` import carries `expect`.
+ * A file with no `@skyramp/skyramp` import is not a Skyramp test (a repository's
+ * own spec), so it is left alone, as is a file that takes `expect` from another
+ * module.
  * Returns the original string if no rewrite was needed.
  */
 export declare function normalizeSkyrampExpectImport(source: string): string;

package/build/utils/normalizeSkyrampImports.js

@@ -3,7 +3,19 @@ import { logger } from "./logger.js";
 const PLAYWRIGHT_IMPORT_RE = /import\s*\{([^}]*)\}\s*from\s*['"]@playwright\/test['"]\s*;?[ \t]*\r?\n?/g;
 const SKYRAMP_IMPORT_RE = /import\s*\{([^}]*)\}\s*from\s*['"]@skyramp\/skyramp['"]\s*;?/;
 const EXPECT_USAGE_RE = /\bexpect\s*\(/;
-const LAST_IMPORT_RE = /^import\s[^;]*;[ \t]*$/gm;
+const NAMED_IMPORT_RE = /import\s*\{([^}]*)\}\s*from\s*['"]([^'"]+)['"]/g;
+/** True when a module other than @playwright/test or @skyramp/skyramp imports
+ *  `expect` (e.g. a repository's own harness); moving it would break that file. */
+function expectFromOtherModule(source) {
+    for (const [, raw, from] of source.matchAll(NAMED_IMPORT_RE)) {
+        if (from === "@playwright/test" || from === "@skyramp/skyramp")
+            continue;
+        const names = splitImports(raw).map((item) => item.split(/\s+as\s+/).pop());
+        if (names.includes("expect"))
+            return true;
+    }
+    return false;
+}
 function splitImports(raw) {
     return raw
         .split(",")
@@ -13,10 +25,16 @@ function splitImports(raw) {
 /**
  * Ensure `expect` is imported from `@skyramp/skyramp` rather than `@playwright/test`.
  * - Strips `expect` from any `@playwright/test` import (keeps other identifiers).
- * - If the file uses `expect(...)`, ensures an `@skyramp/skyramp` import carries `expect`.
+ * - If the file uses `expect(...)`, ensures its `@skyramp/skyramp` import carries `expect`.
+ * A file with no `@skyramp/skyramp` import is not a Skyramp test (a repository's
+ * own spec), so it is left alone, as is a file that takes `expect` from another
+ * module.
  * Returns the original string if no rewrite was needed.
  */
 export function normalizeSkyrampExpectImport(source) {
+    if (!SKYRAMP_IMPORT_RE.test(source) || expectFromOtherModule(source)) {
+        return source;
+    }
     let out = source;
     out = out.replace(PLAYWRIGHT_IMPORT_RE, (match, raw) => {
         const items = splitImports(raw);
@@ -31,22 +49,11 @@ export function normalizeSkyrampExpectImport(source) {
     if (!EXPECT_USAGE_RE.test(out))
         return out;
     const skyrampMatch = out.match(SKYRAMP_IMPORT_RE);
-    if (skyrampMatch) {
-        const items = splitImports(skyrampMatch[1]);
-        if (items.includes("expect"))
-            return out;
-        items.push("expect");
-        out = out.replace(SKYRAMP_IMPORT_RE, `import { ${items.join(", ")} } from '@skyramp/skyramp';`);
+    const items = splitImports(skyrampMatch[1]);
+    if (items.includes("expect"))
         return out;
-    }
-    const newImport = `import { expect } from '@skyramp/skyramp';`;
-    const imports = [...out.matchAll(LAST_IMPORT_RE)];
-    const last = imports[imports.length - 1];
-    if (last && last.index !== undefined) {
-        const insertAt = last.index + last[0].length;
-        return out.slice(0, insertAt) + "\n" + newImport + out.slice(insertAt);
-    }
-    return newImport + "\n" + out;
+    items.push("expect");
+    return out.replace(SKYRAMP_IMPORT_RE, `import { ${items.join(", ")} } from '@skyramp/skyramp';`);
 }
 /**
  * Normalize the `expect` import in a file on disk. No-op if the file is missing,

package/build/utils/pom-scope/ownership.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Which reuse path owns a repository module when both reuse settings are on: the
+ * page-object path owns a module that declares a class, the in-house helper path
+ * (utils-verify/in-house.ts) owns one that does not. ONE predicate, read by both
+ * sides, so a module is never claimed by both and never by neither.
+ *
+ * Decided by shape because the in-house parser cannot read a class — it reports
+ * one as unverifiable — while page-object detection also globs free-function
+ * helper libraries (`support/`, `testUtils`). Without this split both paths would
+ * work on the same free-function module in one run.
+ */
+export declare function declaresClass(content: string): boolean;
+/** The file's working-copy content decides; an unreadable file is not a page
+ *  object (fails toward the in-house path, whose additive gate reads HEAD). */
+export declare function isPageObjectModule(file: string): Promise<boolean>;
+/** Keep only the candidates the page-object path owns. */
+export declare function pageObjectCandidates<T extends {
+    file: string;
+}>(candidates: T[]): Promise<T[]>;

package/build/utils/pom-scope/ownership.js

@@ -0,0 +1,31 @@
+import { readFile } from "fs/promises";
+import { stripCommentsAndStrings } from "./strip.js";
+/**
+ * Which reuse path owns a repository module when both reuse settings are on: the
+ * page-object path owns a module that declares a class, the in-house helper path
+ * (utils-verify/in-house.ts) owns one that does not. ONE predicate, read by both
+ * sides, so a module is never claimed by both and never by neither.
+ *
+ * Decided by shape because the in-house parser cannot read a class — it reports
+ * one as unverifiable — while page-object detection also globs free-function
+ * helper libraries (`support/`, `testUtils`). Without this split both paths would
+ * work on the same free-function module in one run.
+ */
+export function declaresClass(content) {
+    return /(?:^|[\s;}])class\s+[A-Za-z_$][\w$]*/.test(stripCommentsAndStrings(content));
+}
+/** The file's working-copy content decides; an unreadable file is not a page
+ *  object (fails toward the in-house path, whose additive gate reads HEAD). */
+export async function isPageObjectModule(file) {
+    try {
+        return declaresClass(await readFile(file, "utf8"));
+    }
+    catch {
+        return false;
+    }
+}
+/** Keep only the candidates the page-object path owns. */
+export async function pageObjectCandidates(candidates) {
+    const owned = await Promise.all(candidates.map((c) => isPageObjectModule(c.file)));
+    return candidates.filter((_, i) => owned[i]);
+}

package/build/utils/pom-scope/pom-files.d.ts

@@ -3,6 +3,14 @@
  * targets them.
  */
 export declare const SPEC_BASENAME: RegExp;
+/**
+ * Skyramp's own shared helper module is never a page object, wherever it lives — a
+ * customer layout such as `tests/lib/skyrampUtils.ts` matches the test-tree helper
+ * glob above. These globs only LIST files, and the whole-repository fallback lists
+ * every source file, so the module is not recognised here: the two readers that
+ * open candidates anyway — `scorePoms` for discovery, `verifyReuse` for the files a
+ * spec binds — drop a file whose head carries the shared-module header.
+ */
 export declare function globPomFiles(root: string): Promise<string[]>;
 /**
  * Spec files anywhere under `root`, by basename rather than by directory.

package/build/utils/pom-scope/pom-files.js

@@ -34,6 +34,14 @@ const BUILD_IGNORE = [
 /** Test trees a POM is not expected to live in. Not skipped when the tests themselves are the subject. */
 const TEST_TREE_IGNORE = ["**/cypress/**", "**/__tests__/**"];
 const ALL_SOURCE_IGNORE = [...BUILD_IGNORE, ...TEST_TREE_IGNORE];
+/**
+ * Skyramp's own shared helper module is never a page object, wherever it lives — a
+ * customer layout such as `tests/lib/skyrampUtils.ts` matches the test-tree helper
+ * glob above. These globs only LIST files, and the whole-repository fallback lists
+ * every source file, so the module is not recognised here: the two readers that
+ * open candidates anyway — `scorePoms` for discovery, `verifyReuse` for the files a
+ * spec binds — drop a file whose head carries the shared-module header.
+ */
 export async function globPomFiles(root) {
     const matches = await fg(POM_GLOBS, {
         cwd: root,

package/build/utils/pom-scope/scoring.js

@@ -1,4 +1,6 @@
 import { readFile } from "fs/promises";
+import { hasUtilsHeaderContent } from "../utils-verify/locate.js";
+import { logger } from "../logger.js";
 export const RARE_DF = 5;
 /**
  * IDF-style scoring: each selector contributes 1/df to every file containing it
@@ -18,7 +20,17 @@ export async function scorePoms(selectors, files) {
     const contents = new Map();
     await Promise.all(files.map(async (f) => {
         try {
-            contents.set(f, (await readFile(f, "utf8")).replace(/\\/g, ""));
+            // The whole file: the scoring loop below counts a selector wherever it
+            // appears in the content, so a partial read would change the scores.
+            const text = await readFile(f, "utf8");
+            // Skyramp's own shared module is never a page-object candidate, wherever the
+            // globs found it (see pom-files.ts). Judged on the first lines of the content
+            // the scorer holds anyway, so the check adds no read.
+            if (hasUtilsHeaderContent(text)) {
+                logger.info("Page-object scoring skipped a Skyramp shared module the globs listed", { file: f });
+                return;
+            }
+            contents.set(f, text.replace(/\\/g, ""));
         }
         catch {
             /* unreadable file: skip */

package/build/utils/pom-scope/strip.d.ts

@@ -1,3 +1,8 @@
+/** Half-open `[start, end)` offsets of a region in the source. */
+export interface SourceSpan {
+    start: number;
+    end: number;
+}
 /** Every line- and block-comment span in `src`, in source order. Exported for callers
  * that must decide whether a `//` OPENS a comment rather than sits inside one: a `//`
  * on its own line inside `/* … *\/` opens nothing, and deleting that line can take the
@@ -11,6 +16,11 @@ export declare function commentSpans(src: string): {
  * (newlines preserved) so remaining code characters keep their original offset. */
 export declare function stripComments(src: string): string;
 /** Blanks string/template literal contents only, preserving comments as-is. */
+/** The string literals in TS/JS source, quotes INCLUDED, in order. The same scan the
+ *  blanking helpers use — exported so a caller that must treat literal contents
+ *  differently from code (rather than blank them) has one definition of where a
+ *  literal starts and ends, not a second scanner of its own. */
+export declare function stringSpans(src: string): SourceSpan[];
 export declare function stripStrings(src: string): string;
 /** Blanks both comments and string/template literals -- for scanners (like call-chain matching)
  * that never need to read quoted text and want prose in either kind fully inert. */

package/build/utils/pom-scope/strip.js

@@ -317,6 +317,15 @@ export function stripComments(src) {
     return blankSpans(src, classifySpans(src).filter((s) => s.kind === "comment"));
 }
 /** Blanks string/template literal contents only, preserving comments as-is. */
+/** The string literals in TS/JS source, quotes INCLUDED, in order. The same scan the
+ *  blanking helpers use — exported so a caller that must treat literal contents
+ *  differently from code (rather than blank them) has one definition of where a
+ *  literal starts and ends, not a second scanner of its own. */
+export function stringSpans(src) {
+    return classifySpans(src)
+        .filter((s) => s.kind === "string")
+        .map(({ start, end }) => ({ start, end }));
+}
 export function stripStrings(src) {
     return blankSpans(src, classifySpans(src).filter((s) => s.kind === "string"));
 }

package/build/utils/pom-verify/verify.js

@@ -4,7 +4,8 @@ import * as path from "path";
 import { promisify } from "util";
 import { findRoot } from "../pom-scope/index.js";
 import { globPomFiles, globAllSourceFiles } from "../pom-scope/pom-files.js";
-import { extractPomBindings } from "./bindings.js";
+import { extractPomBindings, primaryFile } from "./bindings.js";
+import { hasUtilsHeader } from "../utils-verify/locate.js";
 import { extractPomCalls } from "./calls.js";
 import { resolveMemberSource } from "./resolve.js";
 import { stripComments, stripCommentsAndStrings } from "../pom-scope/strip.js";
@@ -128,12 +129,22 @@ export async function verifyReuse(testFile, language) {
         pomFiles = await globAllSourceFiles(root);
     const pageManagerFile = pomFiles.find((f) => PAGE_MANAGER_RE.test(path.basename(f)));
     const aliasMap = await loadAliasMap(root);
-    const { bindings, unrecognized } = await extractPomBindings(spec, {
+    const extracted = await extractPomBindings(spec, {
         specDir: path.dirname(testFile),
         pomFiles,
         pageManagerFile,
         aliasMap,
     });
+    // Skyramp's own shared module can sit inside a page-object glob (`tests/lib/`), and
+    // a call to one of its helpers must not count as page-object reuse. The header is
+    // read on the few files the spec binds, never across the glob: the whole-repository
+    // fallback above lists every source file. Dropping the binding is the whole change:
+    // `unrecognized` fills only from a `new` of an unresolved class, which a dropped
+    // binding never was, so nothing needs a second extraction.
+    const bound = [...new Set(extracted.bindings.map(primaryFile))];
+    const ours = new Set((await Promise.all(bound.map(async (f) => ((await hasUtilsHeader(f)) ? f : undefined)))).filter((f) => f !== undefined));
+    const { unrecognized } = extracted;
+    const bindings = extracted.bindings.filter((b) => !ours.has(primaryFile(b)));
     const calls = extractPomCalls(spec, bindings);
     const bindingsByName = new Map(bindings.map((b) => [b.name, b]));
     const violations = [];