@skyramp/mcp 0.4.1 → 0.4.2-rc.2

package/build/utils/utils-verify/status-once.js

@@ -0,0 +1,207 @@
+import { blankCommentsAndStrings, blankStrings, hasDefault, paramName, } from "./parse.js";
+import { STATUS_RECEIVER } from "./language-spec.js";
+import { escapeRegExp } from "../regex.js";
+/**
+ * Where a test states the status it expects: ONCE, as the argument of the helper
+ * call. The shared-helper policy says the helper asserts the status — that is the
+ * invariant that makes it safe for another test to call — and stopped there, so the
+ * agent decided what the spec then contains and decided differently each run. Two
+ * shapes came out: the spec states nothing (the status is a defaulted parameter the
+ * call omits) or states it twice (the spec asserts again on the returned response).
+ * Neither is a gate escape — a status assertion in a helper is allowed on purpose,
+ * and the assertion-loss count credits the helper's assertion to the spec — so both
+ * rules are stated here as code, beside the policy sentence the prompt renders.
+ */
+/** The RECEIVER of a status assertion — `response.status`, `r.statusCode`,
+ *  `resp.status_code`, `res.status()` — blanked before the parameters are looked
+ *  for, so a helper handed the response as a parameter is not read as reading it. */
+const STATUS_RECEIVER_RE = /[\w$.]*\.status(?:_?[cC]ode)?\b(?:\s*\(\s*\))?/g;
+/** `assert.strictEqual(<status receiver>, …)` — the matcher form, with the status
+ *  itself as the compared value rather than an expression over it. */
+const ASSERT_MATCHER_STATUS_RE = new RegExp(`(?<![\\w$.])assert\\.(?:strictEqual|equal|deepStrictEqual|deepEqual)\\s*\\(\\s*${STATUS_RECEIVER}\\s*,`);
+/** `assert(<status receiver> === …)` / `== …` — the one bare-assert shape that pins. */
+const ASSERT_STATUS_EQUALITY_RE = new RegExp(`(?<![\\w$.])assert\\s*\\(\\s*${STATUS_RECEIVER}\\s*===?(?!=)`);
+/** A TypeScript optional parameter: `expectedStatus?: number` / `expectedStatus?`. */
+const OPTIONAL_PARAM_RE = /^[A-Za-z_$][\w$]*\s*\?(?:\s*:|$)/;
+/** The helper's status-only assertions, as the language spec recognises them. */
+export function statusAssertions(h, spec) {
+    return h.assertions.filter((a) => spec.allowedAssertion.test(a.text));
+}
+/** Whether the helper pins the status to ONE value — an equality whose operand IS
+ *  the status, not a bound or a set (`toBeLessThan(500)`, `in (200, 201)`), and not
+ *  an equality elsewhere in the same assertion (`… < 500 and attempts == 1`). Only
+ *  then is a status assertion in the spec a restatement rather than a tighter
+ *  claim. A `.not.` form pins nothing. */
+export function assertsStatusEquality(h, spec) {
+    return statusAssertions(h, spec).some((a) => {
+        const code = blankStrings(a.text, spec);
+        // A disjunction admits more than one value — `== 200 or == 201`,
+        // `=== 200 || === 201` — so the status is not pinned to one.
+        if (spec.language === "python" ? /\bor\b/.test(code) : /\|\|/.test(code))
+            return false;
+        return spec.language === "python"
+            ? /\bstatus_code\b\s*==(?!=)|(?<![=!<>])==(?!=)\s*[\w$.]*\bstatus_code\b/.test(code)
+            : (/\)\s*\.\s*(?:toBe|toEqual|toStrictEqual)\s*\(/.test(a.text) &&
+                !/\.\s*not\s*\./.test(a.text)) ||
+                // The matcher form pins only when the status RECEIVER is the value being
+                // compared — its first argument, followed by the comma that ends it.
+                // `assert.strictEqual(r.statusCode < 500, true)` compares a BOOLEAN: the
+                // status is bounded, not pinned, and a later exact check is the tighter
+                // claim. The matcher's name alone decided, and refused that check.
+                ASSERT_MATCHER_STATUS_RE.test(code) ||
+                // The bare form pins only when a POSITIVE equality is anchored to the
+                // status receiver: `!==` carries `==` inside it, and an equality elsewhere
+                // in the condition says nothing about the status.
+                ASSERT_STATUS_EQUALITY_RE.test(code);
+    });
+}
+/**
+ * The parameter the helper's status assertion READS, when it carries a default (or
+ * is optional). `undefined` when the helper asserts no status, when its status
+ * assertion reads a literal rather than a parameter, or when the parameter has no
+ * default.
+ *
+ * Keyed on the assertion, not on the parameter's name: the same cohort that produced
+ * the evidence spelled it `expectedStatus` in one module and `expectedStatusCode` in
+ * another, and a name-matched rule misses whichever spelling the next run picks. A
+ * `None` default counts — a helper whose assertion is switched off by default lets
+ * a caller read the status without verifying it.
+ */
+export function defaultedStatusParam(h, spec) {
+    const read = statusParamOf(h, spec);
+    return read && (hasDefault(read.param) || OPTIONAL_PARAM_RE.test(read.param))
+        ? { param: read.param.replace(/\s+/g, " "), name: read.name }
+        : undefined;
+}
+/** The declared parameter the helper's status assertion reads, or `undefined` when
+ *  the helper asserts no status or compares it against a literal. */
+export function statusParamOf(h, spec) {
+    if (!h.params)
+        return undefined;
+    const declared = new Map(h.params.map((p) => [paramName(p), p]));
+    for (const a of statusAssertions(h, spec)) {
+        // Strings blanked (a message may name anything), then the receiver.
+        const read = blankStrings(a.text, spec).replace(STATUS_RECEIVER_RE, " ");
+        for (const m of read.matchAll(/[A-Za-z_$][\w$]*/g)) {
+            const raw = declared.get(m[0]);
+            if (raw !== undefined)
+                return { param: raw, name: m[0] };
+        }
+    }
+    return undefined;
+}
+/** The literal a helper pins the status to (`200`), when it pins one and reads no
+ *  parameter for it — the shape whose restatement cannot be fixed by deleting the
+ *  spec's assertion alone, because the call has no status argument to keep. */
+export function pinnedStatusLiteral(h, spec) {
+    if (!assertsStatusEquality(h, spec) || statusParamOf(h, spec))
+        return undefined;
+    for (const a of statusAssertions(h, spec)) {
+        const m = /\b(\d{3})\b/.exec(blankStrings(a.text, spec).replace(STATUS_RECEIVER_RE, " "));
+        if (m)
+            return m[1];
+    }
+    return "the literal";
+}
+/** A status-only assertion whose receiver is the variable `v`, per language — the
+ *  `expect(…)` form and the `node:assert` form (`assert.strictEqual(r.statusCode,
+ *  200)`), the same two the language's assertion pattern reads. ANY operator counts
+ *  on this side: once the helper has pinned the status to one value, a further
+ *  status assertion on that response is redundant whatever it compares. Neither
+ *  name may follow an identifier or a dot: `console.assert(…)` asserts nothing. */
+function statusAssertionOn(v, spec) {
+    const id = escapeRegExp(v);
+    return spec.language === "python"
+        ? new RegExp(`\\b${id}\\.status_code\\b`)
+        : new RegExp(`(?<![\\w$.])(?:expect(?:\\.soft)?|assert(?:\\.\\w+)?)\\s*\\(\\s*${id}\\.status(?:_?[cC]ode)?\\b`);
+}
+/** `<v> = <helper>(` in either language, with or without a declaration keyword, a
+ *  type annotation or `await` — and qualified only by a name the spec binds the
+ *  utils MODULE to (`utils.getOrder(`). Any other qualifier is another object's
+ *  method of the same name (`client.getOrder(`), which the helper never ran; an
+ *  unconstrained qualifier made that a blocking finding. */
+function bindingOf(helper, qualifiers) {
+    const qualified = qualifiers.length > 0
+        ? `(?:(?:${qualifiers.map(escapeRegExp).join("|")})\\.)?`
+        : "";
+    return new RegExp(`(?:^|[^\\w$.])(?:(?:const|let|var)\\s+)?([A-Za-z_$][\\w$]*)\\s*(?::[^=\\n]*)?=\\s*(?:await\\s+)?${qualified}${escapeRegExp(helper)}\\s*\\(`);
+}
+/** Where the variable stops naming the helper's response: an assignment to `v`, a
+ *  declaration of `v` with or without `=` (`for (const v of …)`), or `v` declared as
+ *  a callback parameter (`(v) =>`, `v =>`). */
+function rebindingOf(v) {
+    const id = escapeRegExp(v);
+    return new RegExp(`(?:^|[^\\w$.])(?:(?:const|let|var)\\s+${id}\\b|${id}\\s*(?::[^=\\n]*)?=(?![=>])|\\(\\s*[^()]*\\b${id}\\b[^()]*\\)\\s*=>|${id}\\s*=>)`);
+}
+/** A line that opens another scope: a function or test block, whose `v` is whatever
+ *  that scope binds. The scan is line-based and has no block structure, so a later
+ *  \`def check(r)\` or the next \`test(…)\` would otherwise inherit an earlier
+ *  binding of \`r\` and report a restatement that is not one — a false finding on a
+ *  BLOCKING kind. Stopping here costs a miss at worst. */
+function scopeBoundaryOf(spec) {
+    return spec.language === "python"
+        ? /^\s*(?:(?:async\s+)?def\s+\w+\s*\(|class\s+\w)/
+        : /^\s*(?:(?:export\s+)?(?:(?:async\s+)?function\b|(?:abstract\s+)?class\s+\w)|(?:test|it|describe)(?:\.\w+)*\s*\()/;
+}
+/**
+ * Call sites in the spec whose returned response the spec then asserts the status
+ * of — for helpers that already assert it. One finding per helper, with the count.
+ *
+ * The link from call to assertion is the RESPONSE VARIABLE: the call's result is
+ * bound to a name (`const r = await getOrder(…)`, `r = get_order(…)`), and a later
+ * line asserts on `<that name>.status…` before the name is assigned again. Read on
+ * a copy with comments and string contents blanked, so a commented-out call or a
+ * quoted example binds nothing, and it stops at the next function or test block,
+ * which binds its own names. What this cannot see: a destructured result
+ * (`const { statusCode } = await …`), a call passed straight into an assertion
+ * (`expect((await getOrder(…)).status)`), an alias of the status (`const s =
+ * r.status`), a helper called under an import alias, and a response threaded through
+ * a further call or a `.then`. Each is a miss, never a false finding.
+ */
+export function restatedStatusAssertions(specContent, spec, helpers, 
+/** Names the spec binds the utils module to — see UtilsLanguageSpec.moduleQualifiers. */
+qualifiers = []) {
+    if (helpers.length === 0 || specContent === "")
+        return [];
+    const lines = blankCommentsAndStrings(specContent, spec).split("\n");
+    const raw = specContent.split("\n");
+    const out = [];
+    const boundary = scopeBoundaryOf(spec);
+    for (const helper of helpers) {
+        const bind = bindingOf(helper, qualifiers);
+        let first;
+        for (let i = 0; i < lines.length; i++) {
+            const m = bind.exec(lines[i]);
+            if (!m)
+                continue;
+            const v = m[1];
+            const asserted = statusAssertionOn(v, spec);
+            const rebound = rebindingOf(v);
+            for (let j = i + 1; j < lines.length; j++) {
+                if (rebound.test(lines[j]) || boundary.test(lines[j]))
+                    break;
+                // A formatted assertion may open on one line and name its receiver on the
+                // next; the window is three lines, anchored on a match that begins in this one.
+                const window = lines.slice(j, j + 3).join(" ");
+                const hit = asserted.exec(window);
+                if (!hit || hit.index >= lines[j].length)
+                    continue;
+                if (spec.language === "python" && !spec.allowedAssertion.test(lines[j]))
+                    continue;
+                if (first)
+                    first.sites++;
+                else
+                    first = {
+                        helper,
+                        line: j + 1,
+                        text: raw[j].trim(),
+                        sites: 1,
+                    };
+                break;
+            }
+        }
+        if (first)
+            out.push(first);
+    }
+    return out;
+}

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

@@ -0,0 +1,61 @@
+/**
+ * One compiler error in a delivered file, 1-based line, `code` the TS number
+ * (`2322`), `message` the flattened text.
+ */
+export interface TypeFinding {
+    file: string;
+    line: number;
+    code: number;
+    message: string;
+}
+export interface UtilsTypecheck {
+    /** Whether the compiler ran over the delivered files at all. */
+    ran: boolean;
+    /** Why it did not run. Present only when `ran` is false. */
+    reason?: string;
+    /** Errors under the most permissive settings the compiler has — every strictness
+     *  flag off, extensionless imports accepted. An error here fails under EVERY
+     *  configuration, so it is the customer's error whatever their tsconfig says. */
+    errors: TypeFinding[];
+    /** Errors of the "cannot find name / global" family, from the permissive pass:
+     *  `process`, `describe`, `Promise`. Whether such a name exists depends on the
+     *  declaration packages the repository installs (`@types/node`, a test runner's
+     *  types) and its `lib` setting — which this run cannot see, because the
+     *  testbot never installs the repository's dependencies. The customer's own
+     *  `tsc`, with node_modules present, may accept every one of them, so they are
+     *  a gap to state, never a block. */
+    ambientErrors: TypeFinding[];
+    /** Errors present only under the repository's own tsconfig (`noImplicitAny`,
+     *  `strictNullChecks`, …). Whether that tsconfig is the one the customer's build
+     *  runs is their call — advised, never blocked. Empty without a reaching tsconfig. */
+    settingErrors: TypeFinding[];
+    /** The tsconfig whose settings produced `settingErrors`: the nearest one above a
+     *  delivered file that includes at least one of them (the rest come in through
+     *  imports), followed through `references`. */
+    tsconfig?: string;
+    /** A tsconfig found above the files that includes none of them (nor does any
+     *  project it references): the customer's `tsc` never sees these files, so no
+     *  settings pass ran. */
+    tsconfigNotReaching?: string;
+    /** Import specifiers in the delivered files that resolved from neither the
+     *  repository nor the MCP's own install. Everything typed by such a module is
+     *  `any` to the compiler and was NOT checked — reported as a gap, never as an
+     *  error, because whether a module is installed is not a fault in the file. */
+    unresolved: string[];
+}
+export declare const AMBIENT_DECLARATION_CODES: Set<number>;
+/**
+ * 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`).
+ * 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>;

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

@@ -0,0 +1,338 @@
+import * as path from "path";
+import { fileURLToPath } from "url";
+let tsModule;
+/** The compiler, loaded on first use and once per process. Loaded statically it
+ *  rode along with every import of the verifier — about 9 MB of JavaScript that
+ *  each jest test file instantiated in its own module registry, which took a CI
+ *  worker on Node 18 past its 2 GB heap. Only a verify that actually compiles
+ *  TypeScript needs it. */
+function loadTs() {
+    return (tsModule ??= import("typescript").then(
+    // The package is CommonJS: the namespace carries it as `default` where the
+    // loader could not lift its named exports.
+    (mod) => mod.default ?? mod));
+}
+/** The `@skyramp/mcp` package root — `typescript`, `@skyramp/skyramp` and
+ *  `@playwright/test` are its runtime dependencies, so a module the customer's
+ *  repository lacks can still be resolved from here. build/utils/utils-verify/x.js
+ *  and src/utils/utils-verify/x.ts both sit three levels below it. */
+function mcpPackageRoot() {
+    return path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..", "..");
+}
+/** `Cannot find module …` — the resolution gap `unresolved` records; not an error
+ *  in the file. 2792 is the same message with a moduleResolution hint. */
+const UNRESOLVED_MODULE_CODES = new Set([2307, 2792]);
+/** "Cannot find name / namespace / global value / global type", in EVERY spelling the
+ *  compiler has, read off its own message table (the test cross-checks the list
+ *  against `ts.Diagnostics`): the plain forms (2304, 2318, 2468, 2503), the forms
+ *  with a suggestion attached (2552 "Did you mean", 2662/2663 member hints, 2833,
+ *  2311), the forms that name the missing declarations — node (2580, 2591), jQuery
+ *  (2581, 2592), a test runner (2582, 2593), Bun (2867, 2868), `lib` (2583, 2584) —
+ *  the Promise constructor (2705, 2712), and a shorthand property with no value in
+ *  scope (18004). The compiler cannot tell a typo from a global whose declarations
+ *  the run cannot see, and it picks the SPELLING by whether a declared name happens
+ *  to sit near the missing one (`headers` beside lib.dom's `Headers` is 2552 where
+ *  `hdrs` is 2304), so the whole family is reported as `ambientErrors`. */
+/** Packages the EXECUTOR supplies at run time, whatever the repository pins. Their
+ *  types are resolved from the MCP's own install first: a repository pinned to an
+ *  older `@skyramp/skyramp` (one whose `SendRequestV2Options` has no `queryParams`)
+ *  made the call shape the helper policy prescribes a blocking TS2353, on code the
+ *  executor runs correctly — and a `type-error` has no marker, so the agent's only
+ *  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"];
+function executorProvides(specifier) {
+    return EXECUTOR_PROVIDED_PACKAGES.some((p) => specifier === p || specifier.startsWith(`${p}/`));
+}
+export const AMBIENT_DECLARATION_CODES = new Set([
+    2304, 2311, 2318, 2468, 2503, 2552, 2580, 2581, 2582, 2583, 2584, 2591, 2592,
+    2593, 2662, 2663, 2705, 2712, 2833, 2867, 2868, 18004,
+]);
+/**
+ * The settings under which an error is the FILE's fault and nothing else's: every
+ * strictness flag off, every import form accepted, the widest target and library,
+ * nothing emitted. Only the repository's RESOLUTION options are carried in (the
+ * list below) — they decide what resolves, not what is strict or what exists.
+ */
+/** The repository options that decide WHAT RESOLVES — an alias, a base URL, a
+ *  type root, a `types` list, a package-condition set. Everything else in a
+ *  tsconfig is a setting the settings pass reports; carried into the permissive
+ *  pass it would either add errors (`target: ES5` makes a bigint literal one) or
+ *  remove them (`noCheck: true` removes all of them). */
+const RESOLUTION_OPTIONS = [
+    "paths",
+    "baseUrl",
+    "rootDirs",
+    "typeRoots",
+    "types",
+    "moduleSuffixes",
+    "customConditions",
+    "resolvePackageJsonExports",
+    "resolvePackageJsonImports",
+    "allowArbitraryExtensions",
+    "preserveSymlinks",
+];
+function permissiveOptions(ts, base) {
+    const kept = {};
+    for (const key of RESOLUTION_OPTIONS)
+        if (base[key] !== undefined)
+            kept[key] = base[key];
+    return {
+        ...kept,
+        target: ts.ScriptTarget.ES2022,
+        jsx: ts.JsxEmit.Preserve,
+        noCheck: false,
+        noEmit: true,
+        skipLibCheck: true,
+        composite: false,
+        incremental: false,
+        declaration: false,
+        emitDeclarationOnly: false,
+        noEmitOnError: false,
+        // Resolution: the most accepting mode. A `.js` specifier finds the `.ts` file,
+        // an extensionless one too, and a `.ts` extension is not refused.
+        module: ts.ModuleKind.ESNext,
+        moduleResolution: ts.ModuleResolutionKind.Bundler,
+        allowImportingTsExtensions: true,
+        resolveJsonModule: true,
+        allowSyntheticDefaultImports: true,
+        esModuleInterop: true,
+        allowJs: true,
+        checkJs: false,
+        isolatedModules: false,
+        verbatimModuleSyntax: false,
+        // Strictness: everything off, individually — `strict: false` alone leaves a flag
+        // the repository set explicitly in force.
+        strict: false,
+        noImplicitAny: false,
+        strictNullChecks: false,
+        strictFunctionTypes: false,
+        strictBindCallApply: false,
+        strictPropertyInitialization: false,
+        strictBuiltinIteratorReturn: false,
+        noImplicitThis: false,
+        alwaysStrict: false,
+        useUnknownInCatchVariables: false,
+        exactOptionalPropertyTypes: false,
+        noUncheckedIndexedAccess: false,
+        noUncheckedSideEffectImports: false,
+        noImplicitReturns: false,
+        noImplicitOverride: false,
+        noPropertyAccessFromIndexSignature: false,
+        noUnusedLocals: false,
+        noUnusedParameters: false,
+        noFallthroughCasesInSwitch: false,
+        allowUnreachableCode: true,
+        allowUnusedLabels: true,
+    };
+}
+/** The repository's own options, made runnable over a hand-picked file list: nothing
+ *  emitted, no project-build bookkeeping (`composite` would report every file the
+ *  config did not list, and the imports it pulls in are not listed). */
+function settingsOptions(base) {
+    return {
+        ...base,
+        noEmit: true,
+        skipLibCheck: true,
+        composite: false,
+        incremental: false,
+        tsBuildInfoFile: undefined,
+        declaration: false,
+        emitDeclarationOnly: false,
+        noEmitOnError: false,
+    };
+}
+function parseConfig(ts, configPath) {
+    const read = ts.readConfigFile(configPath, ts.sys.readFile);
+    if (read.error || !read.config)
+        return undefined;
+    const parsed = ts.parseJsonConfigFileContent(read.config, ts.sys, path.dirname(configPath), undefined, configPath);
+    return { path: configPath, parsed };
+}
+/** Whether the config's root files name at least one delivered file. Root files
+ *  only — `include` lists the specs, and the shared module comes into the program
+ *  through their imports — so one match means the customer's `tsc -p` compiles
+ *  the whole delivery. */
+function includesAny(parsed, files) {
+    const listed = new Set(parsed.fileNames.map((f) => path.normalize(f)));
+    return files.some((f) => listed.has(path.normalize(f)));
+}
+/**
+ * The nearest tsconfig above each delivered file (an imported module may live
+ * outside the spec's package, and the package config sits above the spec), and —
+ * when one of them includes a delivered file, directly or through its
+ * `references` (the solution-style layout: a root config with `files: []`
+ * pointing at per-target configs, which may point further) — the config that
+ * reaches the delivery. The reference graph is walked depth-first with a visited
+ * set: a nested graph (root → package → tests) is valid, and a cycle must not
+ * hang the verify. `nearest` is the first config found, in the order the files
+ * were given.
+ */
+function findConfigs(ts, files) {
+    const seen = new Set();
+    const candidates = [];
+    for (const file of files) {
+        const configPath = ts.findConfigFile(path.dirname(file), ts.sys.fileExists);
+        if (!configPath || seen.has(configPath))
+            continue;
+        seen.add(configPath);
+        const parsed = parseConfig(ts, configPath);
+        if (parsed)
+            candidates.push(parsed);
+    }
+    if (candidates.length === 0)
+        return {};
+    const visited = new Set();
+    const reachingFrom = (config) => {
+        if (visited.has(config.path))
+            return undefined;
+        visited.add(config.path);
+        if (includesAny(config.parsed, files))
+            return config;
+        for (const ref of config.parsed.projectReferences ?? []) {
+            const referenced = parseConfig(ts, ts.resolveProjectReferencePath(ref));
+            const found = referenced && reachingFrom(referenced);
+            if (found)
+                return found;
+        }
+        return undefined;
+    };
+    for (const candidate of candidates) {
+        const reaching = reachingFrom(candidate);
+        if (reaching)
+            return { nearest: candidates[0], reaching };
+    }
+    return { nearest: candidates[0] };
+}
+/**
+ * One compiler run over `files`. Module resolution tries the repository first and
+ * the MCP's own install second, so `@skyramp/skyramp` resolves whether or not the
+ * customer installed it; what resolves from neither is recorded, not reported as
+ * 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) {
+    const own = new Set(files.map((f) => path.normalize(f)));
+    const unresolved = new Set();
+    const host = ts.createCompilerHost(options, 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");
+    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.
+        const [first, second] = executorProvides(literal.text)
+            ? [anchor, containingFile]
+            : [containingFile, anchor];
+        let resolved = ts.resolveModuleName(literal.text, first, opts, host);
+        if (!resolved.resolvedModule) {
+            const other = ts.resolveModuleName(literal.text, second, opts, host);
+            if (other.resolvedModule)
+                resolved = other;
+            else if (delivered)
+                unresolved.add(literal.text);
+        }
+        return resolved;
+    });
+    const program = ts.createProgram(files, options, host);
+    // A module the program declares AMBIENTLY (`declare module "fs"`, which every
+    // `@types/node` carries) resolves to no file, so the resolver above records it as
+    // a gap while the checker reads it correctly. Reporting it told the agent to go
+    // fix an import that was right — the same class of instruction as the `process`
+    // rewrite. The checker's own ambient list settles it.
+    for (const ambient of program.getTypeChecker().getAmbientModules())
+        unresolved.delete(ambient.name.replace(/^["']|["']$/g, ""));
+    const findings = [];
+    const unresolvedFindings = [];
+    for (const file of files) {
+        const sf = program.getSourceFile(file);
+        if (!sf)
+            continue;
+        for (const d of [
+            ...program.getSyntacticDiagnostics(sf),
+            ...program.getSemanticDiagnostics(sf),
+        ]) {
+            if (d.category !== ts.DiagnosticCategory.Error)
+                continue;
+            const { line } = sf.getLineAndCharacterOfPosition(d.start ?? 0);
+            (UNRESOLVED_MODULE_CODES.has(d.code)
+                ? unresolvedFindings
+                : findings).push({
+                file,
+                line: line + 1,
+                code: d.code,
+                message: ts.flattenDiagnosticMessageText(d.messageText, " "),
+            });
+        }
+    }
+    return { findings, unresolvedFindings, unresolved };
+}
+const findingKey = (f) => `${f.file}\0${f.line}\0${f.code}\0${f.message}`;
+/**
+ * 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`).
+ * 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()) {
+    const result = {
+        ran: false,
+        errors: [],
+        ambientErrors: [],
+        settingErrors: [],
+        unresolved: [],
+    };
+    if (files.length === 0) {
+        result.reason = "no file to check";
+        return result;
+    }
+    try {
+        const ts = await loadTs();
+        const { nearest, reaching } = findConfigs(ts, files);
+        // The permissive pass takes its RESOLUTION options (`paths`, `baseUrl`, `types`)
+        // from the config that reaches the files when there is one: a solution-style
+        // root carries none, and without the referenced config's `paths` an aliased
+        // 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);
+        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) {
+            result.tsconfig = reaching.path;
+            const seen = new Set([...floor.findings, ...floor.unresolvedFindings].map(findingKey));
+            const settings = runPass(ts, files, settingsOptions(reaching.parsed.options), mcpRoot);
+            // 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 = [
+                ...settings.findings,
+                ...settings.unresolvedFindings,
+            ].filter((f) => !seen.has(findingKey(f)));
+        }
+        else if (nearest) {
+            result.tsconfigNotReaching = nearest.path;
+        }
+    }
+    catch (err) {
+        result.ran = false;
+        result.reason = `the compiler threw: ${String(err)}`;
+    }
+    return result;
+}