@skyramp/mcp 0.4.1 → 0.4.2-rc.2

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

@@ -5,7 +5,8 @@ import * as path from "path";
 import { detectGitRoot } from "../gitStaging.js";
 import { logger } from "../logger.js";
 import { SKYRAMP_UTILS_HEADER } from "../utils.js";
-import { utilsSpecFor, utilsSpecForFile, } from "./language-spec.js";
+import { blankComments } from "./parse.js";
+import { UTILS_LANGUAGE_SPECS, utilsSpecFor, utilsSpecForFile, } from "./language-spec.js";
 const execFileAsync = promisify(execFile);
 /** The header `generateSkyrampHeader` writes into a utils file: `Generated by Skyramp on
  *  <timestamp>`. Deliberately NOT the bare `SKYRAMP_UTILS_HEADER`, which every generated
@@ -36,7 +37,10 @@ const HEADER_SCAN_BYTES = 2048;
  * other failure logs and contributes nothing.
  */
 export async function locateUtilsFiles(params) {
-    const spec = utilsSpecFor(params.language) ?? utilsSpecForFile(params.testFile);
+    // The file's extension decides its language; the declared language covers a
+    // path whose extension names none (a TypeScript UI spec and a JavaScript API
+    // spec share one directory in a mixed repository, under one declared language).
+    const spec = utilsSpecForFile(params.testFile) ?? utilsSpecFor(params.language);
     if (!spec)
         return [];
     const found = new Set();
@@ -78,7 +82,7 @@ export async function realpath(p) {
         return path.resolve(p);
     }
 }
-function isInside(file, dir) {
+export function isInside(file, dir) {
     const rel = path.relative(dir, file);
     return rel !== "" && !rel.startsWith("..") && !path.isAbsolute(rel);
 }
@@ -149,8 +153,13 @@ export async function hasUtilsHeader(file) {
     }
 }
 /** Absolute paths of sibling modules `testFile` imports, for the module forms the reuse
- *  prompt produces. Only paths that exist are returned. */
-async function importedModules(testFile, spec) {
+ *  prompt produces. Only paths that exist are returned. Shared with the in-house
+ *  module locator: the customer's helper module is found through the same import. */
+export async function importedModules(testFile, spec, 
+/** `existing` (default) returns only files on disk; `all` returns every candidate
+ *  path the imports could resolve to, so a caller can ask HEAD about a module the
+ *  working tree no longer holds. */
+which = "existing") {
     let content;
     try {
         content = await fs.promises.readFile(testFile, "utf8");
@@ -165,35 +174,128 @@ async function importedModules(testFile, spec) {
         return [];
     }
     const dir = path.dirname(testFile);
+    const isFile = async (p) => {
+        try {
+            return (await fs.promises.stat(p)).isFile();
+        }
+        catch {
+            return false;
+        }
+    };
+    const existing = new Set();
+    /** Every path the imports could resolve to — the `all` mode's answer. */
     const candidates = new Set();
     if (spec.language === "python") {
         for (const m of content.matchAll(/^\s*(?:from\s+([\w.]+)\s+import\b|import\s+([\w.]+)(?:\s+as\s+\w+)?\s*$)/gm)) {
             const mod = (m[1] ?? m[2]).replace(/^\.+/, "");
             if (!mod)
                 continue;
-            candidates.add(path.join(dir, ...mod.split(".")) + ".py");
+            const candidate = path.join(dir, ...mod.split(".")) + ".py";
+            candidates.add(candidate);
+            if (await isFile(candidate))
+                existing.add(candidate);
         }
     }
     else {
-        for (const m of content.matchAll(/(?:from\s*|require\(\s*|import\(\s*)["'](\.{1,2}\/[^"']+)["']/g)) {
-            const base = path.resolve(dir, m[1]);
-            const stripped = base.replace(/\.[cm]?[jt]sx?$/, "");
-            for (const ext of spec.extensions)
-                candidates.add(stripped + ext);
-            // A `.js` specifier in an ESM TypeScript spec resolves to the `.ts` source.
-            candidates.add(stripped + ".ts");
-            candidates.add(stripped + ".js");
+        // ONE import resolves to ONE module, in the order a resolver tries the
+        // candidates: the spec's own family first, the other family next (a `.js`
+        // specifier in an ESM TypeScript spec resolves to the `.ts` source, and a
+        // TypeScript spec may import a JavaScript-only module), then a directory index.
+        // Taking EVERY candidate that exists located both `skyrampUtils.ts` and
+        // `skyrampUtils.js` for one `./skyrampUtils`, and the JavaScript module was then
+        // judged by TypeScript rules (run 9, sample-microservices).
+        for (const imp of relativeImports(content, dir, spec)) {
+            if (which === "all") {
+                for (const c of imp.candidates)
+                    candidates.add(c);
+                continue;
+            }
+            for (const c of imp.candidates)
+                if (await isFile(c)) {
+                    existing.add(c);
+                    break;
+                }
         }
     }
-    const existing = [];
-    for (const c of candidates) {
-        try {
-            if ((await fs.promises.stat(c)).isFile())
-                existing.push(c);
-        }
-        catch {
-            /* not present */
+    if (which === "all")
+        return [...candidates];
+    return [...existing];
+}
+/** A module extension the spec's language resolves, stripped before the candidate
+ *  extensions are tried. */
+const MODULE_EXT_RE = /\.[cm]?[jt]sx?$/;
+/** An ASSET import — data, styles, media — which is not a module this verifier
+ *  judges. A DENY list, never "any extension that is not JavaScript": a dot in a
+ *  module's name is ordinary and is the page-object convention STEP 2b searches for
+ *  (`login.page`, `auth.setup`, `api.client`), and treating those as assets dropped
+ *  them from the locator, from in-house discovery and from staging. */
+const ASSET_EXT_RE = /\.(?:json|jsonc|css|s[ca]ss|less|styl|svg|png|jpe?g|gif|webp|avif|bmp|ico|woff2?|ttf|otf|eot|mp[34]|webm|wav|ogg|txt|md|mdx|ya?ml|toml|html?|xml|csv|pdf|zip|graphql|gql|wasm|node)$/i;
+function relativeImports(content, dir, spec) {
+    const out = [];
+    const seen = new Set();
+    // Comments blanked, string CONTENTS kept: a specifier lives inside quotes, and a
+    // commented-out import is not one. It used to yield a candidate that simply did
+    // not exist on disk and was dropped in silence; once an unresolvable specifier
+    // could be REPORTED, a deleted line became a finding whose only remedy was
+    // deleting a comment — which no message said. A whole import statement written
+    // INSIDE a string literal is still read as one: the specifier lives in quotes,
+    // so the strings cannot be blanked without blanking it too.
+    for (const m of blankComments(content, spec).matchAll(/(?:from\s*|require\(\s*|import\(\s*)["'](\.{1,2}\/[^"']+)["']/g)) {
+        const specifier = m[1];
+        if (seen.has(specifier))
+            continue;
+        seen.add(specifier);
+        if (ASSET_EXT_RE.test(specifier.split("/").pop() ?? ""))
+            continue;
+        const base = path.resolve(dir, specifier);
+        const stripped = base.replace(MODULE_EXT_RE, "");
+        const candidates = [];
+        // The spec's own family first, then the other's: a TypeScript spec importing a
+        // sibling `.mjs` — or a JavaScript one importing a `.tsx` — loads fine, and a
+        // candidate list that stops at one family reads it as missing. (A `.js`
+        // specifier in an ESM TypeScript spec resolving to the `.ts` source is the same
+        // rule: the extension written is not the extension on disk.)
+        for (const ext of spec.extensions)
+            candidates.push(stripped + ext);
+        for (const other of Object.values(UTILS_LANGUAGE_SPECS))
+            if (other.language !== "python")
+                for (const ext of other.extensions)
+                    candidates.push(stripped + ext);
+        // A directory import resolves to its index.
+        for (const ext of [".ts", ".js", ".mjs", ".cjs", ".tsx", ".jsx"])
+            candidates.push(path.join(base, "index" + ext));
+        out.push({ specifier, candidates: [...new Set(candidates)] });
+    }
+    return out;
+}
+/** The relative imports of a TypeScript/JavaScript spec, each resolved against the
+ *  files beside it. Empty for Python, where a relative import and a package import
+ *  are spelled the same and cannot be told apart. Never throws. */
+export async function resolveSpecImports(testFile, spec) {
+    if (spec.language === "python")
+        return [];
+    let content;
+    try {
+        content = await fs.promises.readFile(testFile, "utf8");
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const imp of relativeImports(content, path.dirname(testFile), spec)) {
+        let resolved;
+        for (const c of imp.candidates) {
+            try {
+                if ((await fs.promises.stat(c)).isFile()) {
+                    resolved = await realpath(c);
+                    break;
+                }
+            }
+            catch {
+                /* not present */
+            }
         }
+        out.push({ ...imp, resolved });
     }
-    return existing;
+    return out;
 }

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

@@ -0,0 +1,40 @@
+import { type UtilsLanguageSpec } from "./language-spec.js";
+import type { UtilsFinding } from "./verify.js";
+/**
+ * The shared module this run wrote carries the name the reuse prompt prescribes.
+ *
+ * The prompt states the name in code — `UtilsLanguageSpec.fileName`, which the
+ * instruction the agent reads is rendered from — and nothing checked the delivered
+ * file against it, so a run could invent a variant and the two runs' modules would
+ * never meet. Measured in testplan-run-9 on one repository: one fixture delivered
+ * `skyrampUiUtils.ts` and another `skyrampUtils.ts`, for the same role, in the same
+ * directory, from one build and one model. The divergence had a cause — the first
+ * run had also written a JavaScript module and took the two to need different names
+ * — and no rule resolved it. Each language prescribes its own basename, so the two
+ * modules are `skyrampUtils.js` and `skyrampUtils.ts` and a spec resolves the one of
+ * its own language first (SKYR-4486).
+ *
+ * Two exemptions, both about files this run does not own:
+ *  - A module HEAD already holds keeps its name. Callers this run cannot see import
+ *    it — the earlier run's tests, and anything the customer wrote since — and a
+ *    rename breaks every one of them. Same principle as `incumbent-signature`.
+ *  - The customer's own module never reaches here: `locateUtilsFiles` returns files
+ *    carrying the Skyramp utils header and no others.
+ *
+ * And one carve-out for a name the prompt itself sanctions: it allows a SECOND module
+ * "with a different name" once the first is large. So a module is left alone once the
+ * prescribed name is taken IN ITS OWN DIRECTORY — asked of the directory rather than
+ * of the located set, because the located set answers a different question and gets
+ * this wrong both ways. A prescribed module the spec imports from elsewhere would
+ * excuse a module named freely beside the test; and a prescribed module that ALREADY
+ * sits beside the test, which the spec does not import, never reaches the located set
+ * at all — so reporting would tell the run to rename its own module ONTO an incumbent,
+ * destroying the file the HEAD exemption exists to protect.
+ *
+ * ADVISORY for its first cohort — see UTILS_ADVISORY_KINDS. It still FAILS OPEN: the
+ * only thing that separates a module this run wrote from an incumbent is what HEAD
+ * holds, and where git cannot be asked — outside a repository, before the first
+ * commit, on any error — nothing is reported. A rule that will be promoted to
+ * blocking is written to the standard it will be held to.
+ */
+export declare function misnamedNewModules(utilsFiles: string[], spec: UtilsLanguageSpec, root: string | undefined): Promise<UtilsFinding[]>;

package/build/utils/utils-verify/module-name.js

@@ -0,0 +1,98 @@
+import { execFile } from "child_process";
+import * as fs from "fs";
+import * as path from "path";
+import { promisify } from "util";
+import { utilsSpecForFile } from "./language-spec.js";
+const execFileAsync = promisify(execFile);
+/**
+ * The shared module this run wrote carries the name the reuse prompt prescribes.
+ *
+ * The prompt states the name in code — `UtilsLanguageSpec.fileName`, which the
+ * instruction the agent reads is rendered from — and nothing checked the delivered
+ * file against it, so a run could invent a variant and the two runs' modules would
+ * never meet. Measured in testplan-run-9 on one repository: one fixture delivered
+ * `skyrampUiUtils.ts` and another `skyrampUtils.ts`, for the same role, in the same
+ * directory, from one build and one model. The divergence had a cause — the first
+ * run had also written a JavaScript module and took the two to need different names
+ * — and no rule resolved it. Each language prescribes its own basename, so the two
+ * modules are `skyrampUtils.js` and `skyrampUtils.ts` and a spec resolves the one of
+ * its own language first (SKYR-4486).
+ *
+ * Two exemptions, both about files this run does not own:
+ *  - A module HEAD already holds keeps its name. Callers this run cannot see import
+ *    it — the earlier run's tests, and anything the customer wrote since — and a
+ *    rename breaks every one of them. Same principle as `incumbent-signature`.
+ *  - The customer's own module never reaches here: `locateUtilsFiles` returns files
+ *    carrying the Skyramp utils header and no others.
+ *
+ * And one carve-out for a name the prompt itself sanctions: it allows a SECOND module
+ * "with a different name" once the first is large. So a module is left alone once the
+ * prescribed name is taken IN ITS OWN DIRECTORY — asked of the directory rather than
+ * of the located set, because the located set answers a different question and gets
+ * this wrong both ways. A prescribed module the spec imports from elsewhere would
+ * excuse a module named freely beside the test; and a prescribed module that ALREADY
+ * sits beside the test, which the spec does not import, never reaches the located set
+ * at all — so reporting would tell the run to rename its own module ONTO an incumbent,
+ * destroying the file the HEAD exemption exists to protect.
+ *
+ * ADVISORY for its first cohort — see UTILS_ADVISORY_KINDS. It still FAILS OPEN: the
+ * only thing that separates a module this run wrote from an incumbent is what HEAD
+ * holds, and where git cannot be asked — outside a repository, before the first
+ * commit, on any error — nothing is reported. A rule that will be promoted to
+ * blocking is written to the standard it will be held to.
+ */
+export async function misnamedNewModules(utilsFiles, spec, root) {
+    if (!root || utilsFiles.length === 0)
+        return [];
+    const out = [];
+    for (const file of utilsFiles) {
+        // The module's OWN language prescribes its name. A TypeScript spec may resolve a
+        // JavaScript module (locateUtilsFiles supports it, and #951 makes it the rule),
+        // and judging that module by the spec's language blocked a file carrying exactly
+        // the name its language prescribes. The declared language is the fallback, for a
+        // path whose extension names none.
+        const own = utilsSpecForFile(file) ?? spec;
+        if (path.basename(file) === own.fileName)
+            continue;
+        if (await exists(path.join(path.dirname(file), own.fileName)))
+            continue;
+        if (!(await absentAtHead(root, file)))
+            continue;
+        out.push({
+            kind: "module-name",
+            file,
+            helper: path.basename(file).replace(/\W/g, "_"),
+            line: 1,
+            detail: `this run created \`${path.basename(file)}\`, and the shared module for ${own.language} is \`${own.fileName}\` — the name is prescribed so that a second run against this repository writes the same module instead of a second one beside it. Rename the file to \`${own.fileName}\` and update the imports in the tests this run wrote. A module that already existed keeps its name; this one does not exist at HEAD`,
+        });
+    }
+    return out;
+}
+/** Whether the path is a file. A directory of that name is not the module, and any
+ *  error answers `false` — the caller then falls through to the HEAD question, which
+ *  fails open on its own. */
+async function exists(file) {
+    try {
+        return (await fs.promises.stat(file)).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+/** Whether HEAD does not hold `file`, i.e. this run created it. `undefined`-safe by
+ *  returning `false` — the caller must not report — for every question git cannot
+ *  answer: no HEAD, a path outside the repository, or any git failure. `ls-tree`
+ *  rather than `cat-file -e`, whose exit code is 128 both for a path absent at HEAD
+ *  and for a broken invocation, so the two could not be told apart. */
+async function absentAtHead(root, file) {
+    const rel = path.relative(root, file);
+    if (rel === "" || rel.startsWith("..") || path.isAbsolute(rel))
+        return false;
+    try {
+        const { stdout } = await execFileAsync("git", ["ls-tree", "-z", "--name-only", "HEAD", "--", rel], { cwd: root, encoding: "utf8" });
+        return stdout.trim() === "";
+    }
+    catch {
+        return false;
+    }
+}

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

@@ -1,4 +1,5 @@
 import { type UtilsLanguageSpec } from "./language-spec.js";
+import { type HelperSleep } from "./fixed-sleep.js";
 export interface HelperAssertion {
     line: number;
     text: string;
@@ -22,19 +23,31 @@ export interface UtilsHelper {
      *  into a shared helper is still delivered — see hasPageErrorGuard. */
     hasGuard: boolean;
     assertions: HelperAssertion[];
-    /** TypeScript only: signature parameters with no type annotation (`page`, not
-     *  `page: Page`). Empty for other languages. */
-    untypedParams: string[];
+    /** TypeScript only: signature parameters whose type a caller cannot satisfy —
+     *  unannotated (`page`), `any`, or `unknown` — see unusableParamTypesOf. Empty
+     *  for other languages. */
+    unusableParamTypes: string[];
     /** Declared parameter count — defaulted and rest parameters included. Two
      *  definitions of one name with different arities are the collision a caller
      *  written against either signature hits. `undefined` when no signature could
      *  be read. */
     arity?: number;
+    /** Fixed sleeps in the body — a wait for a duration rather than for a condition,
+     *  centralised into the module every test imports. See fixedSleepsIn. */
+    fixedSleeps: HelperSleep[];
+    /** The declared parameters as written (types and defaults included, comments
+     *  blanked, string contents kept), in order — what a caller's argument count is
+     *  checked against, and what the additive gate reads a default's value from (see
+     *  in-house.ts). `undefined` when no signature could be read; `arity` is its
+     *  length. */
+    params?: string[];
     /** The helper's Playwright action sequence — the duplicate key of a browser
      *  helper, where an API helper has method+path. See actionKeyOf. Read for
      *  TypeScript, JavaScript and Python (through the JavaScript spelling); absent
-     *  for a helper with no readable action. */
+     *  for a helper with no readable action. `actionSteps` is the same sequence one
+     *  step per entry, for the sibling scan that matches step by step. */
     actionKey?: string;
+    actionSteps?: string[];
 }
 /** The declared parameters of a signature, raw text trimmed, empty entries dropped
  *  (a trailing comma). Reads the signature from the definition line to its body
@@ -43,9 +56,33 @@ export interface UtilsHelper {
  *  a binding pattern never splits. `undefined` when the text holds no readable
  *  parameter list. Language-neutral: both a TS `{` and a Python `:` terminator lie
  *  outside the parentheses this reads. */
-export declare function signatureParams(sigLines: string[]): string[] | undefined;
-/** The parameter names in a TS signature that carry no `: type`. */
-export declare function untypedParamsOf(sigLines: string[]): string[];
+export declare function signatureParams(sigLines: string[], 
+/** The same lines with only comments blanked, offsets preserved. When given, the
+ *  parameters are SPLIT on `sigLines` (string contents blanked, so a comma inside
+ *  a default never splits) and READ from these, so a default keeps its value —
+ *  the additive gate compares that value against the body it replaced. */
+rawLines?: string[]): string[] | undefined;
+/** The index of the `=` that opens a parameter's default value, or -1. Depth-aware,
+ *  so an `=` inside a parenthesised type, an object type or a generic is not one;
+ *  `=>`, `==`, `!=`, `<=` and `>=` are not one either.
+ *
+ *  The ONE detection of a default: the typing advisory reads it, the status rule
+ *  reads it, and the additive gate reads the value that follows it. They must not
+ *  disagree about what a default is. */
+export declare function defaultAt(param: string): number;
+/** Whether one declared parameter carries a default value. See defaultAt. */
+export declare function hasDefault(param: string): boolean;
+/** The declared NAME of a parameter, less its annotation, default, rest / unpack
+ *  marker and optional `?`: `...rest: T[]` → `rest`, `expected_status=200` →
+ *  `expected_status`, `expectedStatus?: number` → `expectedStatus`. A binding
+ *  pattern has no single name and returns its text unchanged. */
+export declare function paramName(raw: string): string;
+/** The parameters of a TS signature whose type gives a caller nothing to satisfy:
+ *  no annotation (`page`), `any` (checks nothing), or `unknown` (assignable to
+ *  nothing but itself, so every use of it fails, under every compiler setting).
+ *  Each entry is the name alone when unannotated, `name: any` / `name: unknown`
+ *  otherwise. */
+export declare function unusableParamTypesOf(sigLines: string[]): string[];
 /**
  * Structured extraction of the module-level helpers in a utils file.
  *
@@ -56,6 +93,13 @@ export declare function untypedParamsOf(sigLines: string[]): string[];
  * next non-blank column-0 line; TS/JS bodies end when the brace depth opened by
  * the definition returns to zero.
  */
+/** A generated TEST's own module-level helpers: what parseUtilsFile reads from it,
+ *  less the test functions themselves (`test_…` / `testUi`), which are not helpers a
+ *  call can sit "inside" in the sense the sibling scans and the body-reach check
+ *  report. */
+export declare function localHelpersOf(content: string, spec: UtilsLanguageSpec): UtilsHelper[];
+/** The helper whose body holds `line` (1-based), if any. */
+export declare function localHelperAt(helpers: UtilsHelper[], line: number): UtilsHelper | undefined;
 export declare function parseUtilsFile(content: string, spec: UtilsLanguageSpec): UtilsHelper[];
 /** True when the `path` value is a single string literal ending the argument — a
  *  concatenation (`"/api/orders/" + str(id) + "/items"`) has no route this can name. */
@@ -78,4 +122,9 @@ export declare function countAssertions(content: string, spec: UtilsLanguageSpec
  * Both copies preserve offsets, so a Prettier-wrapped registration matches too.
  */
 export declare function hasPageErrorGuard(content: string, spec: UtilsLanguageSpec): boolean;
+/** Comments blanked, strings preserved, offsets kept. TS/JS use the shared stripper;
+ *  Python blanks each line from its first `#` outside a string. Exported for the
+ *  readers that need a literal intact but a comment gone — an import's module
+ *  path is a string, and a commented-out import must not count. */
+export declare function blankComments(src: string, spec: UtilsLanguageSpec): string;
 export declare function blankCommentsAndStrings(src: string, spec: UtilsLanguageSpec): string;