@skyramp/mcp 0.4.2 → 0.4.3-rc.2

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 = [];

package/build/utils/reuseRouting.d.ts

@@ -1,12 +1,40 @@
 export declare function isBrowserTestType(testType?: string): boolean;
 export declare function isModularizeFirstTarget(testType?: string, language?: string): boolean;
+/**
+ * Which pass one reuse call serves, resolved ONCE per call and handed to every
+ * branch — discovery, verify, the prompt and the modularization check — so none
+ * of them re-derives it. `pass` is the page-object pass or the SkyrampUtils flow;
+ * `composed` says the target takes both (isPomFirstTarget), so the utils flow
+ * follows the page-object pass and one verify checks both halves.
+ */
+export interface ReuseRoute {
+    pass: "pom" | "utils";
+    composed: boolean;
+}
+/** The route for a target. `pomPassFinished` is the one run-state fact it turns on:
+ *  with both settings on, a finished page-object pass hands the spec to the utils flow. */
+export declare function reuseRouteFor(language: string, framework: string | undefined, testType: string | undefined, pomPassFinished?: boolean): ReuseRoute;
+/**
+ * Both reuse settings on, for a test both paths serve: a UI test in TypeScript or
+ * JavaScript. Such a test takes the page-object pass first — it owns every
+ * page-object class its detection returns — and then the seeded SkyrampUtils flow
+ * over what that pass left inline. `isPomAwareTarget` alone still routes the
+ * page-object pass; this names the composition, so e2e keeps its single path.
+ *
+ * No framework parameter: a UI test in TypeScript or JavaScript is a Playwright
+ * test — the generator derives that framework for it (deriveEffectiveFramework), and
+ * the tools that read this predicate after generation (modularization, the
+ * shared-helper verifier, the maintenance step) carry no framework to pass.
+ */
+export declare function isPomFirstTarget(language: string | undefined, testType: string | undefined): boolean;
 export declare function isPomAwareTarget(language: string, framework?: string, testType?: string): boolean;
 /**
  * Which family's inline call-site rule and sibling scan a test gets — the ONE gate
  * for both. `api` for integration, whatever the flags (the rule is stated in API
  * terms and predates the flag); `browser` for the seeded UI flow, where a Skyramp
- * browser module exists to call into; `undefined` everywhere else (`contract`, `load`,
- * e2e, an absent type, UI with the flag off or page-object reuse on), where an
+ * browser module exists to call into — with page-object reuse on as well, since the
+ * seeded flow runs after the page-object pass; `undefined` everywhere else (`contract`,
+ * `load`, e2e, an absent type, UI with the flag off), where an
  * advisory would describe reuse the feature could not have taken. The prompt renders
  * the rule and STEP 5c on it; the verify pass runs the scan on it.
  */

package/build/utils/reuseRouting.js

@@ -19,30 +19,50 @@ export function isBrowserTestType(testType) {
 // maintenance step) read isModularizeFirstHandOffTarget in prompts/reuse-hand-off.ts,
 // which is THIS predicate plus a utils spec for the language: a language the
 // verifier does not cover has no payable reuse half, so no hand-off is owed for
-// it. Integration qualifies whenever the flag is on;
-// UI only while the POM path is off (POM refactoring supersedes modularization,
-// and the testbot UI flow asks for codeReuse unconditionally, so the flag is what
-// keeps the default-off behavior a no-op reuse pass). e2e and load are not
-// routed here: load has no modularization routing at all, e2e is deferred.
-// Deliberately keyed on the POM *flag*, not on isPomAwareTarget: with the flag
-// on, a UI target the POM path does not cover keeps today's plain reuse pass.
-// Composing utils reuse with the POM path is a separate change; this predicate
-// only decides the flag-off UI flow. The modularization prompts read it too, so
-// extraction and seeding agree for every codeReuse flow; a modularizeCode-only
-// call (no codeReuse) still receives the shared-helper rules — harmless without
-// a reuse pass, and the tool cannot see codeReuse.
+// it. Integration qualifies whenever the flag is on; UI in TypeScript or
+// JavaScript too, whatever the page-object flag says. With page-object reuse
+// also on, the page-object pass runs FIRST and the seeded flow takes what it
+// left inline (see isPomFirstTarget). e2e and load are not routed here: load has
+// no modularization routing at all, e2e is deferred.
 export function isModularizeFirstTarget(testType, language) {
     if (!isUtilsReuseEnabled())
         return false;
     if (testType === "integration")
         return true;
-    if (testType !== "ui" || isPomReuseEnabled())
+    if (testType !== "ui")
         return false;
     // Shared browser helpers are Playwright TS/JS; other UI languages have no
     // utils-file convention here and would fall through to a Python file name.
     const lang = language?.toLowerCase();
     return lang === "typescript" || lang === "javascript";
 }
+/** The route for a target. `pomPassFinished` is the one run-state fact it turns on:
+ *  with both settings on, a finished page-object pass hands the spec to the utils flow. */
+export function reuseRouteFor(language, framework, testType, pomPassFinished = false) {
+    const composed = isPomFirstTarget(language, testType);
+    const pomAware = isPomAwareTarget(language, framework, testType);
+    return {
+        pass: pomAware && !(composed && pomPassFinished) ? "pom" : "utils",
+        composed,
+    };
+}
+/**
+ * Both reuse settings on, for a test both paths serve: a UI test in TypeScript or
+ * JavaScript. Such a test takes the page-object pass first — it owns every
+ * page-object class its detection returns — and then the seeded SkyrampUtils flow
+ * over what that pass left inline. `isPomAwareTarget` alone still routes the
+ * page-object pass; this names the composition, so e2e keeps its single path.
+ *
+ * No framework parameter: a UI test in TypeScript or JavaScript is a Playwright
+ * test — the generator derives that framework for it (deriveEffectiveFramework), and
+ * the tools that read this predicate after generation (modularization, the
+ * shared-helper verifier, the maintenance step) carry no framework to pass.
+ */
+export function isPomFirstTarget(language, testType) {
+    return (isPomReuseEnabled() &&
+        testType === "ui" &&
+        isModularizeFirstTarget(testType, language));
+}
 export function isPomAwareTarget(language, framework, testType) {
     if (!isPomReuseEnabled())
         return false;
@@ -56,8 +76,9 @@ export function isPomAwareTarget(language, framework, testType) {
  * Which family's inline call-site rule and sibling scan a test gets — the ONE gate
  * for both. `api` for integration, whatever the flags (the rule is stated in API
  * terms and predates the flag); `browser` for the seeded UI flow, where a Skyramp
- * browser module exists to call into; `undefined` everywhere else (`contract`, `load`,
- * e2e, an absent type, UI with the flag off or page-object reuse on), where an
+ * browser module exists to call into — with page-object reuse on as well, since the
+ * seeded flow runs after the page-object pass; `undefined` everywhere else (`contract`,
+ * `load`, e2e, an absent type, UI with the flag off), where an
  * advisory would describe reuse the feature could not have taken. The prompt renders
  * the rule and STEP 5c on it; the verify pass runs the scan on it.
  */

package/build/utils/testDependencyPolicy.js

@@ -6,6 +6,7 @@ import { promisify } from "util";
 import fg from "fast-glob";
 import { canonicalJson as canonical, isPlainObject as isObject, } from "./canonicalJson.js";
 import { listChangedFiles } from "./reportVerification.js";
+import { contentAtHead } from "./utils-verify/head.js";
 import { SKYRAMP_SDK_VERSION } from "./skyrampSdkVersion.js";
 const execFileAsync = promisify(execFile);
 export const NPM_TEST_PACKAGES = new Set([
@@ -96,7 +97,7 @@ export async function verifyTestDependencyChanges(repositoryPath) {
             }
             continue;
         }
-        const committedBaseline = await baselineFile(repositoryPath, file);
+        const committedBaseline = await contentAtHead(path.join(repositoryPath, file), repositoryPath);
         const baseline = committedBaseline ??
             (await baselineForNewManifest(repositoryPath, file, name, violations));
         if (baseline === undefined)
@@ -203,19 +204,6 @@ function verifyJavaManifest(file, name, baseline, current, violations) {
         return verifyMaven(file, baseline, current, violations);
     return verifyGradle(file, baseline, current, violations);
 }
-async function baselineFile(repositoryPath, file) {
-    try {
-        const { stdout } = await execFileAsync("git", ["show", `HEAD:${file}`], {
-            cwd: repositoryPath,
-            encoding: "utf8",
-            maxBuffer: 10 * 1024 * 1024,
-        });
-        return stdout;
-    }
-    catch {
-        return undefined;
-    }
-}
 async function baselineFileExists(repositoryPath, file) {
     try {
         await execFileAsync("git", ["cat-file", "-e", `HEAD:${file}`], {
@@ -540,7 +528,7 @@ async function correspondingManifests(repositoryPath, file, lockName) {
         const rootManifest = at("package.json");
         // Membership comes from the committed root manifest, not the edited lockfile.
         // A workspace addition is an unrelated manifest edit and remains disallowed.
-        const baseline = await baselineFile(repositoryPath, rootManifest);
+        const baseline = await contentAtHead(path.join(repositoryPath, rootManifest), repositoryPath);
         if (baseline === undefined)
             return [rootManifest];
         const manifest = JSON.parse(baseline);
@@ -575,7 +563,7 @@ async function correspondingManifests(repositoryPath, file, lockName) {
     return [];
 }
 async function verifyLockfile(repositoryPath, file, name, pairedManifests, validManifests, violations) {
-    const committedBaseline = await baselineFile(repositoryPath, file);
+    const committedBaseline = await contentAtHead(path.join(repositoryPath, file), repositoryPath);
     const baseline = committedBaseline ?? '{"packages":{}}\n';
     let current;
     try {

package/build/utils/utils-verify/action-sites.d.ts

@@ -1,6 +1,6 @@
 import { type UtilsHelper } from "./parse.js";
 import { type UtilsLanguageSpec } from "./language-spec.js";
-import { type InlineCallSite, type SiblingFile } from "./call-sites.js";
+import { type InlineCallSite, type SiblingScan } from "./call-sites.js";
 /**
  * The browser family's sibling scan: a contiguous run of actions in OTHER
  * Skyramp-generated tests beside `testFile` whose action sequence equals a utils
@@ -29,4 +29,4 @@ import { type InlineCallSite, type SiblingFile } from "./call-sites.js";
  * consumed and the scan continues after it. A run inside the sibling's own local
  * helper is reported with that helper's name, as the API scan does.
  */
-export declare function findSiblingInlineActionSites(testFile: string, helpersByFile: ReadonlyMap<string, UtilsHelper[]>, spec: UtilsLanguageSpec, preReadSiblings: SiblingFile[] | undefined): Promise<InlineCallSite[]>;
+export declare function findSiblingInlineActionSites(testFile: string, helpersByFile: ReadonlyMap<string, UtilsHelper[]>, spec: UtilsLanguageSpec, preReadSiblings: SiblingScan | undefined): Promise<InlineCallSite[]>;

package/build/utils/utils-verify/allow.d.ts

@@ -74,7 +74,7 @@ export type UtilsViolationKind = "duplicate-helper" | "body-assertion" | "scenar
 /** Kinds that only ever advise. Kept OUT of UtilsViolationKind so that type keeps
  *  meaning "a kind the allow grammar and the gate know about" — an advisory can
  *  never fail a verify and never needs (or accepts) an allow marker. */
-export declare const UTILS_ADVISORY_KINDS: readonly ["unusable-parameter-type", "fixed-sleep", "module-name", "duplicate-body-reach", "duplicate-action", "tsconfig-type-error", "ambient-type-error", "in-house-duplicate"];
+export declare const UTILS_ADVISORY_KINDS: readonly ["unusable-parameter-type", "fixed-sleep", "module-name", "duplicate-body-reach", "duplicate-action", "tsconfig-type-error", "ambient-type-error", "inherited-type-error", "in-house-duplicate"];
 export type UtilsAdvisoryKind = (typeof UTILS_ADVISORY_KINDS)[number];
 export declare const MARKERABLE_UTILS_KINDS: readonly ["frozen-body", "duplicate-helper", "body-assertion", "scenario-name", "assertion-loss", "status-default", "status-restated"];
 /** A kind the allow grammar accepts. `guard-removed` is a gate kind but never

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

@@ -50,6 +50,21 @@ export const UTILS_ADVISORY_KINDS = [
      *  never blocked: a block here made an agent rewrite `process.env` into a
      *  `globalThis` cast to get past the gate. */
     "ambient-type-error",
+    /** A compiler error this run INHERITED: the line is unchanged since HEAD AND
+     *  the file at HEAD already failed the compiler with the same code on that
+     *  line. Whatever the error is, the customer or an earlier run wrote it, it is
+     *  not the shared module's fault, and it must never be the reason a valid
+     *  module is deleted: a run once destroyed its module over four assertion lines
+     *  that pre-dated the run. Advised, never blocked.
+     *
+     *  Attribution is by CAUSE, not by position: an error the run caused on a line
+     *  it left alone — a helper rewritten to return nothing under an unchanged line
+     *  that reads its result — was not there at HEAD and blocks. A file HEAD does
+     *  not hold (a module or a spec this run generated) has nothing to inherit
+     *  from, and every error in it blocks, the generator's included: a line any
+     *  pass of this run wrote is the run's to fix. See inheritedTypeError in
+     *  changed-lines.ts. */
+    "inherited-type-error",
     /** A helper this run added to one of the repository's own modules performs an
      *  action sequence a helper already in that module performs — the duplicate the
      *  extension exists to avoid, now inside the customer's file. Advisory for the

package/build/utils/utils-verify/body-reach.d.ts

@@ -1,5 +1,5 @@
 import type { UtilsLanguageSpec } from "./language-spec.js";
-import { type SiblingFile } from "./call-sites.js";
+import { type SiblingScan } from "./call-sites.js";
 /**
  * A shared helper whose request body no parameter of its signature reaches, beside a
  * spec that defines its OWN helper for the same route.
@@ -117,4 +117,4 @@ export declare function findDuplicateBodyReach(utilsFiles: string[], spec: Utils
  * Shared helpers whose body no parameter reaches, each paired with a sibling spec
  * that defines its own helper for the same route. Never throws; fails open to [].
  */
-export declare function findUnreachableBodies(testFile: string, utilsFiles: string[], spec: UtilsLanguageSpec, preReadSiblings?: SiblingFile[]): Promise<UnreachableBody[]>;
+export declare function findUnreachableBodies(testFile: string, utilsFiles: string[], spec: UtilsLanguageSpec, preReadSiblings?: SiblingScan): Promise<UnreachableBody[]>;

package/build/utils/utils-verify/body-reach.js

@@ -319,7 +319,10 @@ export async function findUnreachableBodies(testFile, utilsFiles, spec, preReadS
     const siblings = preReadSiblings ??
         (await generatedSiblings(testFile, spec, { includeSelf: true }));
     const out = [];
-    for (const { file, content } of siblings) {
+    // `.files`: the walk reports what it read alongside whether it read the whole
+    // directory. This scan acts only on siblings it HAS, so an incomplete walk costs it
+    // a finding and never invents one.
+    for (const { file, content } of siblings.files) {
         for (const h of localHelpersOf(content, spec)) {
             if (!h.method || !h.normalizedPath)
                 continue;

package/build/utils/utils-verify/call-sites.d.ts

@@ -10,16 +10,26 @@ export interface SiblingFile {
     file: string;
     content: string;
 }
+/** The sibling walk's result. `complete` is the walk's own verdict on whether it saw
+ *  the whole directory: the listing succeeded AND every candidate file was read. An
+ *  incomplete walk still returns what it found — the findings stand — but a caller
+ *  that blocks or asserts on the ABSENCE of a sibling must not treat the list as the
+ *  full set. A silently short list is indistinguishable from an honest one. */
+export interface SiblingScan {
+    files: SiblingFile[];
+    complete: boolean;
+}
 /**
  * The Skyramp-generated tests in the spec's directory, each read once — THE sibling
  * walk, shared by the two sibling call-site scans and the importer count (the inline
  * scan excludes the spec itself; the other two include it). Utils files carry no
- * codegen version marker, so the marker check alone excludes them. Fails open to []
- * on any read error.
+ * codegen version marker, so the marker check alone excludes them. Fails open to an
+ * empty, INCOMPLETE scan on a listing failure, and drops an unreadable file from a
+ * scan it then reports as incomplete.
  */
 export declare function generatedSiblings(testFile: string, spec: UtilsLanguageSpec, opts: {
     includeSelf: boolean;
-}): Promise<SiblingFile[]>;
+}): Promise<SiblingScan>;
 /** An SDK request call. Global: clone with `new RegExp(...)` before `matchAll`. */
 export declare const REQUEST_CALL_RE: RegExp;
 interface InlineSiteBase {
@@ -70,7 +80,7 @@ export type InlineCallSite = (InlineSiteBase & {
  * findSiblingInlineActionSites is the browser family's, and inlineCallSiteFamily
  * decides which runs.
  */
-export declare function findSiblingInlineCallSites(testFile: string, utilsFiles: string[], _helpers: UtilsHelper[], spec: UtilsLanguageSpec, preReadSiblings?: SiblingFile[]): Promise<InlineCallSite[]>;
+export declare function findSiblingInlineCallSites(testFile: string, utilsFiles: string[], _helpers: UtilsHelper[], spec: UtilsLanguageSpec, preReadSiblings?: SiblingScan): Promise<InlineCallSite[]>;
 /** One operation written in two or more sibling generated specs that no shared
  *  helper wraps — the extraction the reuse pass exists to perform and did not. */
 export interface UnextractedDuplicate {
@@ -108,11 +118,11 @@ export interface UnextractedSite {
  * A group must span two or more FILES: a spec repeating one request twice is a
  * different question. Advisory by design — consolidation is a judgement. Never throws.
  */
-export declare function findUnextractedDuplicates(testFile: string, utilsFiles: string[], spec: UtilsLanguageSpec, preReadSiblings?: SiblingFile[]): Promise<UnextractedDuplicate[]>;
+export declare function findUnextractedDuplicates(testFile: string, utilsFiles: string[], spec: UtilsLanguageSpec, preReadSiblings?: SiblingScan): Promise<UnextractedDuplicate[]>;
 /** The generated siblings less the utils files themselves (a utils file carries no
  *  codegen marker, so this is belt and braces). Pre-read siblings are used as given —
  *  the caller's walk decides whether the spec itself is among them. */
-export declare function nonUtilsSiblings(testFile: string, utilsFiles: string[], spec: UtilsLanguageSpec, preReadSiblings: SiblingFile[] | undefined, includeSelf: boolean): Promise<SiblingFile[]>;
+export declare function nonUtilsSiblings(testFile: string, utilsFiles: string[], spec: UtilsLanguageSpec, preReadSiblings: SiblingScan | undefined, includeSelf: boolean): Promise<SiblingFile[]>;
 /** Lines after a call scanned for its schema assertion — the generated shape puts it
  *  immediately after the status-code assertion. */
 export declare const SCHEMA_SCAN_LINES = 12;

package/build/utils/utils-verify/call-sites.js

@@ -14,8 +14,9 @@ const HEADER_SCAN_LINES = 5;
  * The Skyramp-generated tests in the spec's directory, each read once — THE sibling
  * walk, shared by the two sibling call-site scans and the importer count (the inline
  * scan excludes the spec itself; the other two include it). Utils files carry no
- * codegen version marker, so the marker check alone excludes them. Fails open to []
- * on any read error.
+ * codegen version marker, so the marker check alone excludes them. Fails open to an
+ * empty, INCOMPLETE scan on a listing failure, and drops an unreadable file from a
+ * scan it then reports as incomplete.
  */
 export async function generatedSiblings(testFile, spec, opts) {
     let dir;
@@ -27,8 +28,9 @@ export async function generatedSiblings(testFile, spec, opts) {
         entries = await fs.promises.readdir(dir);
     }
     catch {
-        return [];
+        return { files: [], complete: false };
     }
+    let complete = true;
     const out = [];
     for (const name of entries.sort()) {
         const file = path.join(dir, name);
@@ -41,13 +43,16 @@ export async function generatedSiblings(testFile, spec, opts) {
             content = await fs.promises.readFile(file, "utf8");
         }
         catch {
+            // A candidate this walk could not read may or may not have been a generated
+            // test importing the module — so the scan is short by an unknown amount.
+            complete = false;
             continue;
         }
         if (!CODEGEN_MARKER_RE.test(content.split("\n").slice(0, HEADER_SCAN_LINES).join("\n")))
             continue;
         out.push({ file, content });
     }
-    return out;
+    return { files: out, complete };
 }
 /** An SDK request call. Global: clone with `new RegExp(...)` before `matchAll`. */
 export const REQUEST_CALL_RE = /\b(?:send_request|sendRequest)\s*\(/g;
@@ -183,8 +188,9 @@ async function helperRoutes(utilsFiles, spec) {
  *  the caller's walk decides whether the spec itself is among them. */
 export async function nonUtilsSiblings(testFile, utilsFiles, spec, preReadSiblings, includeSelf) {
     const utilsSet = new Set(await Promise.all(utilsFiles.map((f) => realpath(f))));
-    return (preReadSiblings ??
-        (await generatedSiblings(testFile, spec, { includeSelf }))).filter((sib) => !utilsSet.has(path.resolve(sib.file)));
+    const scan = preReadSiblings ??
+        (await generatedSiblings(testFile, spec, { includeSelf }));
+    return scan.files.filter((sib) => !utilsSet.has(path.resolve(sib.file)));
 }
 /** Every keyable request call in a generated test. Calls whose method or path cannot
  *  be read are skipped: they have no route to compare. Calls are located, and their