@skyramp/mcp 0.4.2 → 0.4.3-rc.2

package/build/utils/utils-verify/retrofit-equivalence.d.ts

@@ -41,8 +41,3 @@ export interface RetrofitMismatch {
  * than a refusal the agent cannot act on.
  */
 export declare function retrofitMismatches(retrofitFile: string, utilsFiles: string[], spec: UtilsLanguageSpec): Promise<RetrofitMismatch[]>;
-/** The file's content at HEAD, or undefined when there is nothing to compare against
- *  (untracked, no git root, or git unavailable). Never throws. The ONE reader of a
- *  file's committed baseline on the utils path: the incumbent-signature gate reads
- *  the utils module through it too. */
-export declare function committedBaseline(file: string): Promise<string | undefined>;

package/build/utils/utils-verify/retrofit-equivalence.js

@@ -1,14 +1,9 @@
-import { execFile } from "child_process";
 import * as fs from "fs";
-import * as path from "path";
-import { promisify } from "util";
-import { logger } from "../logger.js";
-import { detectGitRoot } from "../gitStaging.js";
+import { contentAtHead } from "./head.js";
 import { blankCommentsAndStrings, parseUtilsFile } from "./parse.js";
 import { normalizePath } from "./language-spec.js";
 import { callText, hasSchemaCheck, requestFields, REQUEST_CALL_RE, SCHEMA_SCAN_LINES, shapeKeys, } from "./call-sites.js";
 import { escapeRegExp } from "../regex.js";
-const exec = promisify(execFile);
 /**
  * Whether a retrofit changed the request the rewired test sends.
  *
@@ -41,7 +36,7 @@ const exec = promisify(execFile);
  * than a refusal the agent cannot act on.
  */
 export async function retrofitMismatches(retrofitFile, utilsFiles, spec) {
-    const baseline = await committedBaseline(retrofitFile);
+    const baseline = await contentAtHead(retrofitFile);
     if (baseline === undefined)
         return [];
     let delivered;
@@ -191,30 +186,3 @@ function sameSet(a, b) {
             return false;
     return true;
 }
-/** The file's content at HEAD, or undefined when there is nothing to compare against
- *  (untracked, no git root, or git unavailable). Never throws. The ONE reader of a
- *  file's committed baseline on the utils path: the incumbent-signature gate reads
- *  the utils module through it too. */
-export async function committedBaseline(file) {
-    const root = detectGitRoot(file);
-    if (!root)
-        return undefined;
-    const rel = path.relative(root, file);
-    if (!rel || rel.startsWith(".."))
-        return undefined;
-    try {
-        const { stdout } = await exec("git", ["show", `HEAD:${rel}`], {
-            cwd: root,
-            maxBuffer: 10 * 1024 * 1024,
-        });
-        return stdout;
-    }
-    catch (err) {
-        // A file added by this run has no HEAD version — the common case, not an error.
-        logger.debug("No committed baseline for a retrofit; skipping equivalence", {
-            file,
-            error: String(err),
-        });
-        return undefined;
-    }
-}

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

@@ -1,15 +1,13 @@
-import { execFile } from "child_process";
-import { promisify } from "util";
 import * as fs from "fs";
 import * as path from "path";
 import { detectGitRoot, stageGeneratedPaths } from "../gitStaging.js";
 import { logger } from "../logger.js";
 import { isTestbotEnabled } from "../featureFlags.js";
 import { locateUtilsFiles, realpath } from "./locate.js";
+import { changedSinceHead } from "./head.js";
 import { locateInHouseModules } from "./in-house.js";
 import { CODEGEN_MARKER_RE } from "./call-sites.js";
 import { utilsSpecFor, utilsSpecForFile } from "./language-spec.js";
-const execFileAsync = promisify(execFile);
 export async function stageUtilsArtifacts(testFile, language) {
     const staged = [];
     const failed = [];
@@ -99,10 +97,7 @@ async function modifiedInHouseModules(testFile, language) {
         const modules = await locateInHouseModules({ testFile, spec, cwd: root });
         if (modules.length === 0)
             return [];
-        const { stdout } = await execFileAsync("git", ["diff", "-z", "--name-only", "--diff-filter=M", "HEAD"], { cwd: root, encoding: "utf8" });
-        const modified = new Set();
-        for (const rel of stdout.split("\0").filter(Boolean))
-            modified.add(await realpath(path.resolve(root, rel)));
+        const modified = new Set(await changedSinceHead(root, { filter: "M" }));
         return modules.map((m) => m.file).filter((f) => modified.has(f));
     }
     catch (err) {
@@ -117,18 +112,12 @@ async function modifiedSiblingsImporting(testFile, utilsFiles, language) {
         return [];
     let modified;
     try {
-        // `-z`: unquoted, NUL-separated — git C-quotes non-ASCII paths otherwise.
-        const { stdout } = await execFileAsync("git", 
         // Against HEAD, modified only: a test THIS run created is staged at discovery, so
         // its later STEP 5b edits show in a plain `git diff` and it would masquerade as a
         // pre-existing sibling (observed: the report gate then demanded an execution no
         // record could satisfy, and the agent un-shared the helpers to escape). Files
         // added since HEAD are excluded; they are staged by their own tool calls.
-        ["diff", "-z", "--name-only", "--diff-filter=M", "HEAD"], {
-            cwd: root,
-            encoding: "utf8",
-        });
-        modified = stdout.split("\0").filter(Boolean);
+        modified = await changedSinceHead(root, { filter: "M" });
     }
     catch (err) {
         logger.warning("Could not list modified files — edited sibling tests will not be staged", {
@@ -140,8 +129,7 @@ async function modifiedSiblingsImporting(testFile, utilsFiles, language) {
     const stems = utilsFiles.map((f) => path.basename(f).replace(/\.[^.]+$/, ""));
     const self = await realpath(testFile);
     const out = [];
-    for (const rel of modified) {
-        const abs = await realpath(path.resolve(root, rel));
+    for (const abs of modified) {
         if (abs === self || utilsFiles.includes(abs))
             continue;
         if (!spec.extensions.some((e) => abs.toLowerCase().endsWith(e)))

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

@@ -44,18 +44,39 @@ export interface UtilsTypecheck {
     unresolved: string[];
 }
 export declare const AMBIENT_DECLARATION_CODES: Set<number>;
+/** The delivered files as the repository held them at HEAD, and the files that
+ *  did not exist then. With a baseline the check is the permissive pass alone: it
+ *  exists to say which errors this run inherited, and the settings pass never
+ *  blocks. */
+export interface TypecheckBaseline {
+    contents: ReadonlyMap<string, string>;
+    hidden: ReadonlySet<string>;
+}
+export interface TypecheckOptions {
+    mcpRoot?: string;
+    /** The delivered file whose directory stands for the repository: where global
+     *  types are looked up from, and where the executor packages' peers resolve
+     *  from for EVERY file. The spec, when one is delivered — it is the consumer,
+     *  and in a monorepo its package's Playwright is the one the executor runs,
+     *  not a hoisted root copy the shared module's directory would find. Defaults
+     *  to the first file. */
+    anchor?: string;
+    baseline?: TypecheckBaseline;
+}
 /**
  * Typecheck the delivered TypeScript files — the shared module and the spec that
  * imports it — with the compiler the MCP itself depends on, so the check runs in
  * every repository whether or not `typescript` is installed there.
  *
  * Two passes over the same files. The PERMISSIVE pass has every strictness flag off:
- * an error it reports fails under any configuration and is blocking (`errors`). The
- * SETTINGS pass runs the repository's own tsconfig, when one reaches the files; what
- * it adds is an error only under those settings and is advisory (`settingErrors`).
+ * an error it reports fails under any configuration (`errors`) — the verifier
+ * blocks on it unless the repository already had it at HEAD, which the same
+ * function establishes when called with a `baseline`. The SETTINGS pass runs the
+ * repository's own tsconfig, when one reaches the files; what it adds is an error
+ * only under those settings and is advisory (`settingErrors`).
  * The executor transpiles without typechecking, so neither pass has run before this
  * one, and a delivered file that fails here reaches the customer's own `tsc` first.
  *
  * Never throws: a compiler failure is a result that says the check did not run.
  */
-export declare function typecheckDelivered(files: string[], mcpRoot?: string): Promise<UtilsTypecheck>;
+export declare function typecheckDelivered(files: string[], { mcpRoot, anchor, baseline }?: TypecheckOptions): Promise<UtilsTypecheck>;

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

@@ -1,4 +1,5 @@
 import * as path from "path";
+import { readFileSync } from "fs";
 import { fileURLToPath } from "url";
 let tsModule;
 /** The compiler, loaded on first use and once per process. Loaded statically it
@@ -41,8 +42,61 @@ const UNRESOLVED_MODULE_CODES = new Set([2307, 2792]);
  *  exit was to rewrite working code. Every other package still resolves from the
  *  repository first, because every other package is the repository's to pin. */
 const EXECUTOR_PROVIDED_PACKAGES = ["@skyramp/skyramp"];
+/** The PEERS of the executor-provided packages — what their type declarations
+ *  import and expect the host to install (`@skyramp/skyramp` declares
+ *  `@playwright/test`, whose `Expect` types its `expect`). Read from each
+ *  package's own manifest under `mcpRoot`, once per root: the SDK already states
+ *  the list, and a second copy here would need a test to keep it in step. A peer
+ *  is resolved from the REPOSITORY first for every file that imports it, the
+ *  MCP's own copy second — including from inside the MCP's SDK declarations.
+ *  Otherwise the SDK's copy came from the MCP's install while the spec's own
+ *  import came from the repository's, and a repository pinned to another
+ *  Playwright version had two `Locator` identities: every `expect(locator)` in
+ *  it typed as the base matchers, and four assertion lines that pre-dated the
+ *  run became blocking `type-error`s against a valid module — which the run then
+ *  deleted. The customer's `tsc` has one node_modules and never sees the split;
+ *  the executor runs the repository's Playwright, so the repository's copy is
+ *  the truth. */
+const peersByRoot = new Map();
+function executorPeerPackages(mcpRoot) {
+    let peers = peersByRoot.get(mcpRoot);
+    if (peers)
+        return peers;
+    peers = [];
+    for (const pkg of EXECUTOR_PROVIDED_PACKAGES) {
+        const manifest = installedManifest(pkg, mcpRoot);
+        if (manifest)
+            peers.push(...Object.keys(manifest.peerDependencies ?? {}));
+        // No manifest reachable from this root: the package resolves from nowhere
+        // and its imports are reported as unresolved gaps, so there is no peer to
+        // route.
+    }
+    peersByRoot.set(mcpRoot, peers);
+    return peers;
+}
+/** The package's manifest as Node would find it from `from`: the nearest
+ *  `node_modules/<pkg>` walking UP from there. The MCP's dependencies are not
+ *  always nested under its own root — `npm install @skyramp/mcp`, testbot's
+ *  default, hoists them BESIDE `@skyramp/mcp` — and a read at one fixed path
+ *  found nothing on that layout, left the peer list empty, and brought the two
+ *  Playwright identities back exactly where customers run. */
+function installedManifest(pkg, from) {
+    for (let dir = from;; dir = path.dirname(dir)) {
+        try {
+            return JSON.parse(readFileSync(path.join(dir, "node_modules", pkg, "package.json"), "utf8"));
+        }
+        catch {
+            if (path.dirname(dir) === dir)
+                return undefined;
+        }
+    }
+}
+const isPackageOrSubpath = (specifier, packages) => packages.some((p) => specifier === p || specifier.startsWith(`${p}/`));
 function executorProvides(specifier) {
-    return EXECUTOR_PROVIDED_PACKAGES.some((p) => specifier === p || specifier.startsWith(`${p}/`));
+    return isPackageOrSubpath(specifier, EXECUTOR_PROVIDED_PACKAGES);
+}
+function executorPeer(specifier, mcpRoot) {
+    return isPackageOrSubpath(specifier, executorPeerPackages(mcpRoot));
 }
 export const AMBIENT_DECLARATION_CODES = new Set([
     2304, 2311, 2318, 2468, 2503, 2552, 2580, 2581, 2582, 2583, 2584, 2591, 2592,
@@ -211,26 +265,51 @@ function findConfigs(ts, files) {
  * an error, and its diagnostics are dropped (everything typed by it is `any` and
  * was not checked — the gap is stated instead).
  */
-function runPass(ts, files, options, mcpRoot) {
+function runPass(ts, files, options, mcpRoot, repoDir, baseline) {
     const own = new Set(files.map((f) => path.normalize(f)));
     const unresolved = new Set();
     const host = ts.createCompilerHost(options, true);
+    if (baseline) {
+        // A baseline file is read from the content given, never from disk; a hidden
+        // one does not exist to the compiler, so an import of it is unresolved and
+        // typed `any`, as it was before the run wrote it.
+        const contentOf = (f) => baseline.contents.get(path.normalize(f));
+        const hidden = (f) => baseline.hidden.has(path.normalize(f));
+        const { fileExists, readFile, getSourceFile } = host;
+        host.fileExists = (f) => hidden(f) ? false : contentOf(f) !== undefined || fileExists(f);
+        host.readFile = (f) => hidden(f) ? undefined : (contentOf(f) ?? readFile(f));
+        host.getSourceFile = (f, lang, onError, shouldCreate) => {
+            if (hidden(f))
+                return undefined;
+            const content = contentOf(f);
+            return content === undefined
+                ? getSourceFile(f, lang, onError, shouldCreate)
+                : ts.createSourceFile(f, content, lang, true);
+        };
+    }
     // Global types (`@types/*` pulled in automatically) are looked up from the current
     // directory upward. That must be the repository, not wherever the MCP process
     // happens to run: the MCP's own `@types/jest` made a bare `expect` compile here
     // that the customer's `tsc` cannot see.
-    const repoDir = path.dirname(files[0]);
     host.getCurrentDirectory = () => repoDir;
     // A containing file that does not exist is fine for resolution: only its
     // directory is read, and node_modules is looked up from there.
     const anchor = path.join(mcpRoot, "__skyramp_typecheck_anchor__.ts");
+    // The same device for the repository: a peer imported from INSIDE the MCP's
+    // install must still resolve from the repository first, and the containing
+    // file's directory would find the MCP's copy.
+    const repoAnchor = path.join(repoDir, "__skyramp_typecheck_anchor__.ts");
     host.resolveModuleNameLiterals = (literals, containingFile, _r, opts) => literals.map((literal) => {
         const delivered = own.has(path.normalize(containingFile));
-        // The executor's own packages are read from the MCP's install first;
-        // everything else from the repository first, the MCP second.
+        // The executor's own packages are read from the MCP's install first; their
+        // peers from the repository first wherever the import sits, so both sides of
+        // an SDK type meet ONE copy; everything else from the repository first, the
+        // MCP second.
         const [first, second] = executorProvides(literal.text)
             ? [anchor, containingFile]
-            : [containingFile, anchor];
+            : executorPeer(literal.text, mcpRoot)
+                ? [repoAnchor, anchor]
+                : [containingFile, anchor];
         let resolved = ts.resolveModuleName(literal.text, first, opts, host);
         if (!resolved.resolvedModule) {
             const other = ts.resolveModuleName(literal.text, second, opts, host);
@@ -281,15 +360,17 @@ const findingKey = (f) => `${f.file}\0${f.line}\0${f.code}\0${f.message}`;
  * every repository whether or not `typescript` is installed there.
  *
  * Two passes over the same files. The PERMISSIVE pass has every strictness flag off:
- * an error it reports fails under any configuration and is blocking (`errors`). The
- * SETTINGS pass runs the repository's own tsconfig, when one reaches the files; what
- * it adds is an error only under those settings and is advisory (`settingErrors`).
+ * an error it reports fails under any configuration (`errors`) — the verifier
+ * blocks on it unless the repository already had it at HEAD, which the same
+ * function establishes when called with a `baseline`. The SETTINGS pass runs the
+ * repository's own tsconfig, when one reaches the files; what it adds is an error
+ * only under those settings and is advisory (`settingErrors`).
  * The executor transpiles without typechecking, so neither pass has run before this
  * one, and a delivered file that fails here reaches the customer's own `tsc` first.
  *
  * Never throws: a compiler failure is a result that says the check did not run.
  */
-export async function typecheckDelivered(files, mcpRoot = mcpPackageRoot()) {
+export async function typecheckDelivered(files, { mcpRoot = mcpPackageRoot(), anchor, baseline } = {}) {
     const result = {
         ran: false,
         errors: [],
@@ -310,15 +391,16 @@ export async function typecheckDelivered(files, mcpRoot = mcpPackageRoot()) {
         // import is unresolved here, typed `any`, and its unconditional error then
         // surfaces only in the settings pass — downgraded to an advisory.
         const base = (reaching ?? nearest)?.parsed.options ?? {};
-        const floor = runPass(ts, files, permissiveOptions(ts, base), mcpRoot);
+        const repoDir = path.dirname(anchor ?? files[0]);
+        const floor = runPass(ts, files, permissiveOptions(ts, base), mcpRoot, repoDir, baseline);
         result.ran = true;
         result.errors = floor.findings.filter((f) => !AMBIENT_DECLARATION_CODES.has(f.code));
         result.ambientErrors = floor.findings.filter((f) => AMBIENT_DECLARATION_CODES.has(f.code));
         result.unresolved = [...floor.unresolved].sort();
-        if (reaching) {
+        if (reaching && !baseline) {
             result.tsconfig = reaching.path;
             const seen = new Set([...floor.findings, ...floor.unresolvedFindings].map(findingKey));
-            const settings = runPass(ts, files, settingsOptions(reaching.parsed.options), mcpRoot);
+            const settings = runPass(ts, files, settingsOptions(reaching.parsed.options), mcpRoot, repoDir);
             // An import only the repository's resolution refuses is its `tsc`'s error,
             // not a gap: the permissive pass resolved it, so the module exists.
             result.settingErrors = [

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

@@ -1,7 +1,7 @@
 import { type UtilsTypecheck } from "./typecheck.js";
 import { type InlineCallSite, type UnextractedDuplicate } from "./call-sites.js";
 import { type UtilsAdvisoryKind, type UtilsViolationKind } from "./allow.js";
-import { type SingleImporterHelper } from "./importers.js";
+import { type HelperImporters } from "./importers.js";
 import { type HelperFamilySpec, type UtilsLanguageSpec } from "./language-spec.js";
 export interface UtilsViolation {
     kind: UtilsViolationKind;
@@ -24,6 +24,13 @@ export interface UtilsVerifyResult {
     ok: boolean;
     /** Utils files located for this spec (absolute). Empty = nothing was written or imported. */
     utilsFiles: string[];
+    /** Those of `utilsFiles` that HEAD holds — an earlier run's or the customer's. */
+    incumbentModules: string[];
+    /** Those of `utilsFiles` git could not answer for (outside a repository, or a
+     *  git failure). Neither an incumbent nor this run's: a caller that states
+     *  "this run created it" must not say so for these. The rest of `utilsFiles`
+     *  this run created. */
+    headUnknownModules: string[];
     /** Helpers defined across the utils files. */
     helpers: number;
     /** Helper names the delivered spec imports from those files. */
@@ -60,8 +67,14 @@ export interface UtilsVerifyResult {
      *  findUnextractedDuplicates. API family only. */
     unextractedDuplicates: UnextractedDuplicate[];
     /** Helpers imported by 0 or 1 delivered test (SKYR-4276 A6). Advisory: a first run
-     *  seeds every helper single-use by design; the count is the trend to watch. */
-    singleImporters: SingleImporterHelper[];
+     *  seeds every helper single-use by design; the count is the trend to watch. Empty
+     *  whenever `importersComplete` is false — see there. */
+    singleImporters: HelperImporters[];
+    /** The importer walk read the whole directory. When false, `singleImporters` is
+     *  empty because the walk could not support a finding, NOT because every helper has
+     *  importers: a file it could not read may be the one importer of a helper. A
+     *  caller that states "nothing imports this" must consult it. */
+    importersComplete: boolean;
     /** The numbers the baseline assertion check compared — present only when a
      *  baseline was supplied and the spec was readable. The check is a COUNT: it
      *  cannot see one assertion swapped for another. The caller's text says so.
@@ -80,6 +93,13 @@ export interface UtilsVerifyResult {
      *  `tsconfig-type-error` advisories; this carries the rest (the tsconfig read, the
      *  modules it could not resolve). Absent for Python and JavaScript. */
     typecheck?: UtilsTypecheck;
+    /** What the attribution of compiler errors to this run established — with
+     *  `typecheck`, TypeScript only. `ran` is whether the HEAD compile ran, so an
+     *  error the repository already had could be excused; when it did not, `reason`
+     *  says why and every error blocked as this run's. `headUnknown` lists the
+     *  delivered files git gave no HEAD answer for: each is judged as this run's
+     *  in full, and the pass says so rather than hide it. */
+    attribution?: TypeAttribution;
     /** Modules the spec imports that this pass READ and does not CHECK: the
      *  repository's own modules (tracked at HEAD, no Skyramp header) on a path with no
      *  in-house checks — integration, today — and a module outside the repository.
@@ -104,6 +124,11 @@ export interface UtilsVerifyResult {
      *  Absent when the spec imports no such module. */
     inHouse?: InHouseVerification;
 }
+export interface TypeAttribution {
+    ran: boolean;
+    reason?: string;
+    headUnknown: string[];
+}
 export interface InHouseVerification {
     /** Absolute paths of the in-house modules read. */
     modules: string[];
@@ -171,17 +196,17 @@ export interface VerifyUtilsParams {
  *    returned. See status-once.ts.
  *  - `type-error` (TypeScript): the delivered module or spec fails the compiler with
  *    every strictness flag off — an error under every configuration (a path parameter
- *    typed `unknown`, request options built as a record and handed to `sendRequest`).
- *    An error only the repository's own tsconfig raises is the `tsconfig-type-error`
- *    ADVISORY. See typecheckDelivered.
+ *    typed `unknown`, request options built as a record and handed to `sendRequest`)
+ *    — and this run CAUSED it: an error the file already had at HEAD on an
+ *    unchanged line is the `inherited-type-error` ADVISORY, and an error only the
+ *    repository's own tsconfig raises is the `tsconfig-type-error` ADVISORY. See
+ *    typecheckDelivered and inheritedTypeError.
  *
  * Analyses the utils files' INTERNAL invariants — unlike the POM verifier, which
  * checks a spec's cross-file references — so it reads the utils files, not the spec,
  * except to count what the spec imports.
  */
 export declare function verifyUtils(params: VerifyUtilsParams): Promise<UtilsVerifyResult>;
-/** The compared counts as one phrase, shared by the assertion-loss detail and the
- *  PASSED line's note so the two cannot drift. */
 export declare function describeAssertionCount(c: {
     baseline: number;
     delivered: number;