@skyramp/mcp 0.4.1 → 0.4.2-rc.2

package/build/utils/testExecutionRecord.d.ts

@@ -0,0 +1,94 @@
+import { type TestExecutionData, type TestExecutionRecord, type TestExecutionResult } from "../types/TestExecution.js";
+import type { TestType } from "../types/TestTypes.js";
+import { type UnifiedAnalysisState } from "./AnalysisStateManager.js";
+/**
+ * The serialization key for a run's state file: one queue per FILE, not per
+ * spelling. `./state.json`, its absolute path, and a symlink to it are read and
+ * written as one file, so they must wait on one another — two spellings in
+ * two queues could both pass the cap check. The real path when the file
+ * exists, else the resolved absolute path.
+ */
+export declare function stateFileKey(stateFile: string): string;
+/**
+ * The one path every read and write of a run's state file should use: the real
+ * path when the file exists, else the resolved absolute path. StateManager
+ * writes atomically by renaming a temp file over the target, which REPLACES a
+ * symlink instead of updating what it points to — so a write through a link
+ * would fork the state into two files with two counters. Reading and writing
+ * the real path keeps one file.
+ */
+export declare function canonicalStateFilePath(stateFile: string): string;
+/**
+ * The cap pinned at the run's root, if a valid one is there. Read from the
+ * ROOT on purpose: the pin is run-wide and a related repository's section
+ * never carries a copy, so reading it from the section would hand every
+ * related-repo file "no pin" and let a later prompt value widen its budget.
+ */
+export declare function readPinnedMaxFixAttempts(stateFile: string): Promise<number | undefined>;
+/** Characters of output kept in a run-state execution record. Head and tail
+ *  are kept around a marker so both the setup and the failing assertion
+ *  survive; the full text stays in the tool response. */
+export declare const EXECUTION_RECORD_OUTPUT_LIMIT = 12000;
+/** Bound `output` to the record limit, keeping its head and tail. */
+export declare function boundExecutionOutput(output: string, limit?: number): {
+    output: string;
+    truncated: boolean;
+};
+/** Bound the error list the same way output is bounded: cap the count, then
+ *  cap each entry's length (head only — an error's cause is at the front). */
+export declare function boundExecutionErrors(errors: string[]): string[];
+/** No real process exit code is ever negative, so -1 is unambiguous as "none
+ *  produced" (a timeout kill or a thrown error before the process exited). */
+export declare const NO_EXIT_CODE = -1;
+/** The run-state record for one skyramp_execute_test result. `previous` is the
+ *  file's earlier record in this run, if any, so re-runs are counted. */
+export declare function executionRecordFrom(result: TestExecutionData, testType: TestType, phase: "before" | "after", previous?: TestExecutionRecord, countRun?: boolean, fileHash?: string): TestExecutionRecord;
+/** The repository sections a run's state file holds: the primary at the root
+ *  plus every related repo. Used to name them when a caller's `repository`
+ *  matches none, so the fix is to correct the slug, not to drop the stateFile. */
+export declare function stateSectionsOf(stateFile: string): Promise<string[]>;
+/**
+ * Read one repository's section — for the file's execution record and as the
+ * fail-closed check on the `repository` argument (the cap itself comes from the
+ * root, see readPinnedMaxFixAttempts) — failing in a way the caller can act
+ * on: a stateFile that does not exist, one that cannot be parsed, or one with
+ * no section for `repo` (named against the sections that do exist) each throw
+ * with a distinct message. Never returns null.
+ */
+export declare function readRepoSectionOrThrow(stateFile: string, repo: string): Promise<UnifiedAnalysisState>;
+/**
+ * Reserve one execution attempt BEFORE the run (SKYR-4460): the file's run
+ * counters advance now, and the run's attempt cap is pinned at the state
+ * root (run-wide, whichever section this call writes) on first use. Reserving first means a state write that fails after the run,
+ * or a read that fails before it, can never hand the file a free attempt —
+ * the caller fails closed on a throw here instead of proceeding on zero.
+ * Until the result lands the record reads `Unknown` ("execution was expected
+ * but no result was recorded"), whatever the previous run's status was, so a
+ * run that dies before persisting leaves an honest record. The whole
+ * read-modify-write is serialized on the state file, like the persist below:
+ * two calls for different files in the same run would otherwise overwrite
+ * each other's section. Returns the count of final-phase runs BEFORE this one
+ * and the cap this run enforces.
+ */
+export declare function reserveTestExecutionAttempt(stateFile: string, repo: string, testType: TestType, phase: "before" | "after", testFile: string, cap: number, fileHash: string): Promise<{
+    priorAfterRuns: number;
+    cap: number;
+}>;
+/**
+ * Read-modify-write one execution result into a run's state file: the
+ * per-file testExecutions record (every file, keyed by canonical path — see
+ * executionRecordFrom), plus the maintained-test executionBefore/After row
+ * when `testFile` has one. No-op when the repo section doesn't exist yet.
+ * Returns what was written, so the caller can say what was not.
+ *
+ * Extracted from skyramp_execute_test's own state-write block so the
+ * behavior that makes a file's result available to the post-execution
+ * alignment step is directly testable against a real state file, not only
+ * through the tool's full request/response path.
+ */
+export declare function persistTestExecutionResult(stateFile: string, repo: string, testType: TestType, phase: "before" | "after", result: TestExecutionResult, options?: {
+    reserved?: boolean;
+}): Promise<{
+    saved: boolean;
+    matchedExistingTest: boolean;
+}>;

package/build/utils/testExecutionRecord.js

@@ -0,0 +1,269 @@
+import { TestExecutionStatus, } from "../types/TestExecution.js";
+import { StateManager, } from "./AnalysisStateManager.js";
+import { canonicalTestPath } from "../tools/code-refactor/assertion-state.js";
+import { runSerialized } from "./runSerialized.js";
+import { parseMaxFixAttemptsArg } from "./fixAttempts.js";
+import * as fs from "fs";
+import * as path from "path";
+/**
+ * The serialization key for a run's state file: one queue per FILE, not per
+ * spelling. `./state.json`, its absolute path, and a symlink to it are read and
+ * written as one file, so they must wait on one another — two spellings in
+ * two queues could both pass the cap check. The real path when the file
+ * exists, else the resolved absolute path.
+ */
+export function stateFileKey(stateFile) {
+    return `state:${canonicalStateFilePath(stateFile)}`;
+}
+/**
+ * The one path every read and write of a run's state file should use: the real
+ * path when the file exists, else the resolved absolute path. StateManager
+ * writes atomically by renaming a temp file over the target, which REPLACES a
+ * symlink instead of updating what it points to — so a write through a link
+ * would fork the state into two files with two counters. Reading and writing
+ * the real path keeps one file.
+ */
+export function canonicalStateFilePath(stateFile) {
+    const resolved = path.resolve(stateFile);
+    try {
+        return fs.realpathSync.native(resolved);
+    }
+    catch {
+        // Not there yet (or unreadable): the resolved path is the best identity.
+        return resolved;
+    }
+}
+/**
+ * The cap pinned at the run's root, if a valid one is there. Read from the
+ * ROOT on purpose: the pin is run-wide and a related repository's section
+ * never carries a copy, so reading it from the section would hand every
+ * related-repo file "no pin" and let a later prompt value widen its budget.
+ */
+export async function readPinnedMaxFixAttempts(stateFile) {
+    const root = await StateManager.fromStatePath(stateFile).readData();
+    return parseMaxFixAttemptsArg(root?.maxFixAttempts, "stateFile");
+}
+/** Characters of output kept in a run-state execution record. Head and tail
+ *  are kept around a marker so both the setup and the failing assertion
+ *  survive; the full text stays in the tool response. */
+export const EXECUTION_RECORD_OUTPUT_LIMIT = 12_000;
+const TRUNCATION_MARKER = (dropped) => `\n… [${dropped} characters omitted] …\n`;
+/** Bound `output` to the record limit, keeping its head and tail. */
+export function boundExecutionOutput(output, limit = EXECUTION_RECORD_OUTPUT_LIMIT) {
+    if (output.length <= limit)
+        return { output, truncated: false };
+    const half = Math.floor(limit / 2);
+    return {
+        output: output.slice(0, half) +
+            TRUNCATION_MARKER(output.length - 2 * half) +
+            output.slice(output.length - half),
+        truncated: true,
+    };
+}
+/** Max errors kept in a record, and the max length of any one of them — a
+ *  parser that goes wild on unstructured output must not make `errors`
+ *  unbounded the way `output` deliberately isn't. */
+const EXECUTION_RECORD_MAX_ERRORS = 20;
+const EXECUTION_RECORD_MAX_ERROR_LENGTH = 2_000;
+/** Bound the error list the same way output is bounded: cap the count, then
+ *  cap each entry's length (head only — an error's cause is at the front). */
+export function boundExecutionErrors(errors) {
+    const kept = errors.slice(0, EXECUTION_RECORD_MAX_ERRORS);
+    const bounded = kept.map((e) => e.length > EXECUTION_RECORD_MAX_ERROR_LENGTH
+        ? `${e.slice(0, EXECUTION_RECORD_MAX_ERROR_LENGTH)}… [truncated]`
+        : e);
+    if (errors.length > EXECUTION_RECORD_MAX_ERRORS) {
+        bounded.push(`… [${errors.length - EXECUTION_RECORD_MAX_ERRORS} more error(s) omitted]`);
+    }
+    return bounded;
+}
+/** No real process exit code is ever negative, so -1 is unambiguous as "none
+ *  produced" (a timeout kill or a thrown error before the process exited). */
+export const NO_EXIT_CODE = -1;
+/** The run-state record for one skyramp_execute_test result. `previous` is the
+ *  file's earlier record in this run, if any, so re-runs are counted. */
+export function executionRecordFrom(result, testType, phase, previous, countRun = true, fileHash) {
+    const { output, truncated } = boundExecutionOutput(result.output ?? "");
+    const step = countRun ? 1 : 0;
+    // The hash travels with the run: set at reservation, kept by the result write.
+    const hash = fileHash ?? previous?.fileHash;
+    return {
+        ...(hash ? { fileHash: hash } : {}),
+        testType,
+        phase,
+        status: result.status,
+        executedAt: result.executedAt,
+        duration: result.duration,
+        exitCode: result.exitCode ?? NO_EXIT_CODE,
+        errors: boundExecutionErrors(result.errors),
+        output,
+        outputTruncated: truncated,
+        runs: (previous?.runs ?? 0) + step,
+        afterRuns: (previous?.afterRuns ?? 0) + (phase === "after" ? step : 0),
+    };
+}
+/** The repository sections a run's state file holds: the primary at the root
+ *  plus every related repo. Used to name them when a caller's `repository`
+ *  matches none, so the fix is to correct the slug, not to drop the stateFile. */
+export async function stateSectionsOf(stateFile) {
+    const full = await StateManager.fromStatePath(stateFile).readFullState();
+    if (!full)
+        return [];
+    return [
+        full.metadata.repository,
+        ...Object.keys(full.relatedRepos ?? {}),
+    ].filter((r) => typeof r === "string" && r.length > 0);
+}
+/**
+ * Read one repository's section — for the file's execution record and as the
+ * fail-closed check on the `repository` argument (the cap itself comes from the
+ * root, see readPinnedMaxFixAttempts) — failing in a way the caller can act
+ * on: a stateFile that does not exist, one that cannot be parsed, or one with
+ * no section for `repo` (named against the sections that do exist) each throw
+ * with a distinct message. Never returns null.
+ */
+export async function readRepoSectionOrThrow(stateFile, repo) {
+    if (!fs.existsSync(canonicalStateFilePath(stateFile))) {
+        throw new Error(`stateFile ${stateFile} does not exist`);
+    }
+    const stateData = await StateManager.fromStatePath(stateFile).readRepoData(repo);
+    if (stateData)
+        return stateData;
+    const sections = await stateSectionsOf(stateFile);
+    throw new Error(`stateFile ${stateFile} has no section for repository "${repo}"` +
+        (sections.length
+            ? `; it holds: ${sections.join(", ")}. Correct the repository argument`
+            : `; it holds no analysis yet — run skyramp_analyze_changes for it first`));
+}
+/**
+ * Reserve one execution attempt BEFORE the run (SKYR-4460): the file's run
+ * counters advance now, and the run's attempt cap is pinned at the state
+ * root (run-wide, whichever section this call writes) on first use. Reserving first means a state write that fails after the run,
+ * or a read that fails before it, can never hand the file a free attempt —
+ * the caller fails closed on a throw here instead of proceeding on zero.
+ * Until the result lands the record reads `Unknown` ("execution was expected
+ * but no result was recorded"), whatever the previous run's status was, so a
+ * run that dies before persisting leaves an honest record. The whole
+ * read-modify-write is serialized on the state file, like the persist below:
+ * two calls for different files in the same run would otherwise overwrite
+ * each other's section. Returns the count of final-phase runs BEFORE this one
+ * and the cap this run enforces.
+ */
+export async function reserveTestExecutionAttempt(stateFile, repo, testType, phase, testFile, cap, 
+// The sha256 of the file being executed. The caller hashes it before
+// reserving (the file must exist to run), so a reservation always has one.
+fileHash) {
+    return runSerialized(stateFileKey(stateFile), async () => {
+        const stateData = await readRepoSectionOrThrow(stateFile, repo);
+        const manager = StateManager.fromStatePath(stateFile);
+        // The pin is RUN-wide, so it lives at the root whichever section this call
+        // writes: a multi-repo run otherwise pins each section separately and two
+        // files from one prompt can run under two caps. Pin on first use; an
+        // invalid pinned value (a hand-edited 0, a half-written 11) is replaced
+        // rather than carried into "attempt 1 of 0".
+        const root = (await manager.readData()) ?? {};
+        const pinned = parseMaxFixAttemptsArg(root.maxFixAttempts, "stateFile") ?? cap;
+        if (root.maxFixAttempts !== pinned) {
+            await manager.appendData({ ...root, maxFixAttempts: pinned });
+        }
+        // The section write below must not carry its own copy: when this section
+        // IS the root, the root's value is carried forward (ROOT_FIELDS_OWNED_ELSEWHERE);
+        // when it is a related section, the field does not belong there.
+        delete stateData.maxFixAttempts;
+        const key = canonicalTestPath(testFile);
+        const previous = stateData.testExecutions?.[key];
+        const placeholder = {
+            status: TestExecutionStatus.Unknown,
+            executedAt: new Date().toISOString(),
+            duration: 0,
+            errors: [],
+            warnings: [],
+            output: "",
+            exitCode: NO_EXIT_CODE,
+        };
+        const inFlight = executionRecordFrom(placeholder, testType, phase, previous, true, fileHash);
+        // The record is "the latest run", so the run in flight replaces the last
+        // completed one — but what that run was is kept beside it: a process that
+        // dies here (the case reserving first exists for) leaves a record that
+        // still says what the file last did. A maintained test's baseline OUTPUT
+        // lives on in existingTests[].executionBefore, which an "after"
+        // reservation never touches.
+        if (previous && previous.status !== TestExecutionStatus.Unknown) {
+            inFlight.previousRun = {
+                status: previous.status,
+                phase: previous.phase,
+                executedAt: previous.executedAt,
+                exitCode: previous.exitCode,
+            };
+        }
+        else if (previous?.previousRun) {
+            inFlight.previousRun = previous.previousRun;
+        }
+        stateData.testExecutions = {
+            ...(stateData.testExecutions ?? {}),
+            [key]: inFlight,
+        };
+        // A maintained test's before/after status is read by the report from its
+        // existingTests row, not from the record above. The row for THIS phase is
+        // set to the same in-flight Unknown, so a run that dies (or whose result
+        // write fails) cannot leave the previous Pass/Fail there to be published as
+        // this run's outcome. The other phase's row — the baseline output, for an
+        // "after" reservation — is untouched.
+        // Canonical on both sides: the row was written by analysis, the argument
+        // by the agent, and `/repo/tests/./x.py` or a symlink spelling is one file.
+        const row = stateData.existingTests?.find((t) => canonicalTestPath(t.testFile) === key);
+        if (row) {
+            const rowPlaceholder = { ...placeholder, testFile };
+            if (phase === "before")
+                row.executionBefore = rowPlaceholder;
+            else
+                row.executionAfter = rowPlaceholder;
+        }
+        await manager.updateRepoData(stateData, { repo });
+        return {
+            priorAfterRuns: previous?.afterRuns ?? 0,
+            cap: pinned,
+        };
+    });
+}
+/**
+ * Read-modify-write one execution result into a run's state file: the
+ * per-file testExecutions record (every file, keyed by canonical path — see
+ * executionRecordFrom), plus the maintained-test executionBefore/After row
+ * when `testFile` has one. No-op when the repo section doesn't exist yet.
+ * Returns what was written, so the caller can say what was not.
+ *
+ * Extracted from skyramp_execute_test's own state-write block so the
+ * behavior that makes a file's result available to the post-execution
+ * alignment step is directly testable against a real state file, not only
+ * through the tool's full request/response path.
+ */
+export async function persistTestExecutionResult(stateFile, repo, testType, phase, result, options = {}) {
+    // Serialized on the state file: the section is read whole and written whole,
+    // so two files' results landing at once would drop one of them.
+    return runSerialized(stateFileKey(stateFile), async () => {
+        const { testFile } = result;
+        const stateManager = StateManager.fromStatePath(stateFile);
+        const stateData = await stateManager.readRepoData(repo);
+        if (!stateData)
+            return { saved: false, matchedExistingTest: false };
+        const testIndex = stateData.existingTests?.findIndex((t) => canonicalTestPath(t.testFile) === canonicalTestPath(testFile)) ?? -1;
+        if (testIndex >= 0) {
+            if (phase === "before") {
+                stateData.existingTests[testIndex].executionBefore = result;
+            }
+            else {
+                stateData.existingTests[testIndex].executionAfter = result;
+            }
+        }
+        const key = canonicalTestPath(testFile);
+        stateData.testExecutions = {
+            ...(stateData.testExecutions ?? {}),
+            [key]: executionRecordFrom(result, testType, phase, stateData.testExecutions?.[key], 
+            // A reserved attempt already advanced the counters before the run.
+            !options.reserved),
+        };
+        await stateManager.updateRepoData(stateData, { repo });
+        return { saved: true, matchedExistingTest: testIndex >= 0 };
+    });
+}

package/build/utils/testFileClassification.d.ts

@@ -14,6 +14,14 @@ export declare function isDiscoveredTestFile(filePath: string): boolean;
  *  `isDiscoveredTestFile`'s rule, which also counts `tests/`, a page-object
  *  directory and `test_orders.py`. The maintenance tool wants this narrow one. */
 export declare function isTestFile(filePath: string): boolean;
+/** The file's own NAME says it is a test — `login.spec.ts`, `orders.test.js`,
+ *  `test_orders.py`, `UserDAOTest.java`. Almost entirely a NAME rule: a helper,
+ *  a fixture, a page object or a config sitting in `e2e/` or `cypress/support/`
+ *  is not a test and cannot be run as one. The one exception is `__tests__/`,
+ *  Jest's convention that everything inside it is a test whatever it is called.
+ *  Exported for callers that must not act on a file merely because of where it
+ *  lives. */
+export declare function hasTestFileName(filePath: string): boolean;
 /** Whether a path is a test file, by directory or by name. Read by the route
  *  checks: a route declared in a mock server or a spec fixture is not a surface
  *  anyone serves. */

package/build/utils/testFileClassification.js

@@ -76,14 +76,49 @@ const TEST_ROOT_DIR = /(^|[\\/])(tests?|__tests__|__mocks__|e2e|cypress|testing)
  *  `TEST_FILE_PATTERNS` rows it resembles — any extension, and `.`, `_` or `-`
  *  before `test` — so no row above can stand in for it. */
 const TEST_FILE_NAME = /[._-](test|spec)\.[a-z]+$|(^|[\\/])test_[^\\/]*$/i;
+/** The file's own NAME says it is a test — `login.spec.ts`, `orders.test.js`,
+ *  `test_orders.py`, `UserDAOTest.java`. Almost entirely a NAME rule: a helper,
+ *  a fixture, a page object or a config sitting in `e2e/` or `cypress/support/`
+ *  is not a test and cannot be run as one. The one exception is `__tests__/`,
+ *  Jest's convention that everything inside it is a test whatever it is called.
+ *  Exported for callers that must not act on a file merely because of where it
+ *  lives. */
+export function hasTestFileName(filePath) {
+    return (
+    // Discovery's own name rule, applied to the basename so it admits no
+    // directory. It carries the framework spellings the regexes below miss:
+    // `UserDAOTest.java`, `orders_smoke.py`, `checkout_e2e.ts`.
+    TEST_FILE_PATTERNS.some((p) => p.test(path.basename(filePath))) ||
+        TEST_FILE_NAME.test(filePath) ||
+        CAMEL_TEST_FILE_NAME.test(filePath) ||
+        // Surefire's default includes are `Test*.java` as well as `*Test.java`, and
+        // Failsafe's are `*IT.java`. CAMEL_TEST_FILE_NAME needs a lowercase
+        // character before the suffix, so the acronym spelling (`APIIT.java`) and
+        // the prefix spelling (`TestOrder.java`) both fall through it.
+        /(^|[\\/])Test[A-Z][A-Za-z0-9]*\.(java|kt|kts|scala)$/.test(filePath) ||
+        /[A-Za-z0-9]IT\.(java|kt|kts|scala)$/.test(filePath) ||
+        // mocha's default spec glob is `./test/*.js` — one directory level, and no
+        // name rule at all, so `test/app.js` is a test to mocha.
+        /(^|[\\/])test[\\/][^\\/]+\.(js|cjs|mjs)$/.test(filePath) ||
+        // `login.e2e.ts` and Cypress's own `login.cy.ts` — the dot forms
+        // TEST_FILE_NAME does not carry. `.cy.` is to Cypress what `.spec.` is to
+        // Playwright.
+        /\.(cy|e2e)\.[a-z]+$/i.test(filePath) ||
+        // Jest's convention: everything under `__tests__/` is a test, whatever it
+        // is called. The only directory that means that on its own.
+        /(^|[\\/])__tests__[\\/]/.test(filePath));
+}
 /** The CamelCase spellings, which carry no separator before `Test`.
- *  Case-SENSITIVE and must stay so: with `i` it also matches `Latest.java` and
- *  `Manifest.cs`, ordinary source files. That is why the case-insensitive
- *  `*Test.java` / `*Tests.cs` rows above cannot serve here. */
+ *  Case-SENSITIVE and must stay so: with `i` it also matches `Latest.java`,
+ *  `Audit.java`, `Edit.cs` and `Digit.ts`, ordinary source files. That is why
+ *  the case-insensitive `*Test.java` / `*Tests.cs` rows above cannot serve
+ *  here. */
 const CAMEL_TEST_FILE_NAME = /[a-z0-9](Tests?|IT)\.[A-Za-z0-9]+$/;
 /** Whether a path is a test file, by directory or by name. Read by the route
  *  checks: a route declared in a mock server or a spec fixture is not a surface
  *  anyone serves. */
 export function isTestPath(file) {
-    return TEST_ROOT_DIR.test(file) || TEST_FILE_NAME.test(file) || CAMEL_TEST_FILE_NAME.test(file);
+    return (TEST_ROOT_DIR.test(file) ||
+        TEST_FILE_NAME.test(file) ||
+        CAMEL_TEST_FILE_NAME.test(file));
 }

package/build/utils/trace-parser.js

@@ -9,7 +9,12 @@ import { walkDir } from "./fileWalk.js";
 const FLOW_GAP_MS = 30_000;
 // Redact-only headers: scrub these from traces but don't treat them as extractable auth headers.
 // set-cookie carries session tokens; auth-token / client-secret / access-token are generic secrets.
-const REDACT_ONLY_HEADERS = new Set(["set-cookie", "auth-token", "client-secret", "access-token"]);
+const REDACT_ONLY_HEADERS = new Set([
+    "set-cookie",
+    "auth-token",
+    "client-secret",
+    "access-token",
+]);
 // Build redaction check from the shared KNOWN_AUTH_HEADERS set (workspaceAuth.ts) plus
 // the redact-only extras. Uses exact matching — KNOWN_AUTH_HEADERS covers all known variants.
 function isSensitiveHeader(name) {
@@ -29,7 +34,11 @@ function groupIntoFlows(entries) {
         if (curr - prev > FLOW_GAP_MS) {
             const first = new Date(current[0].timestamp).getTime();
             const last = new Date(current[current.length - 1].timestamp).getTime();
-            flows.push({ flowId: `flow-${flowIdx++}`, entries: current, durationMs: last - first });
+            flows.push({
+                flowId: `flow-${flowIdx++}`,
+                entries: current,
+                durationMs: last - first,
+            });
             current = [];
         }
         current.push(sorted[i]);
@@ -37,7 +46,11 @@ function groupIntoFlows(entries) {
     if (current.length > 0) {
         const first = new Date(current[0].timestamp).getTime();
         const last = new Date(current[current.length - 1].timestamp).getTime();
-        flows.push({ flowId: `flow-${flowIdx}`, entries: current, durationMs: last - first });
+        flows.push({
+            flowId: `flow-${flowIdx}`,
+            entries: current,
+            durationMs: last - first,
+        });
     }
     return flows;
 }
@@ -52,20 +65,34 @@ function parseSkyrampTrace(data) {
     return data.map((entry) => {
         const rawQp = entry.QueryParams || entry.queryParams;
         let queryParams;
-        if (rawQp && typeof rawQp === "object" && !Array.isArray(rawQp) && Object.keys(rawQp).length > 0) {
+        if (rawQp &&
+            typeof rawQp === "object" &&
+            !Array.isArray(rawQp) &&
+            Object.keys(rawQp).length > 0) {
             queryParams = {};
             for (const [k, v] of Object.entries(rawQp)) {
                 queryParams[k] = Array.isArray(v) ? v.map(String) : [String(v)];
             }
         }
         return {
-            method: (entry.method || entry.Method || entry.request?.method || "GET").toUpperCase(),
+            method: (entry.method ||
+                entry.Method ||
+                entry.request?.method ||
+                "GET").toUpperCase(),
             path: entry.path || entry.Path || entry.url || entry.request?.url || "/",
-            statusCode: entry.statusCode || entry.StatusCode || entry.status || entry.response?.status || 0,
-            requestHeaders: entry.request?.headers ? sanitizeHeaders(entry.request.headers) : undefined,
+            statusCode: entry.statusCode ||
+                entry.StatusCode ||
+                entry.status ||
+                entry.response?.status ||
+                0,
+            requestHeaders: entry.request?.headers
+                ? sanitizeHeaders(entry.request.headers)
+                : undefined,
             requestBody: summarizeBody(entry.request?.body ?? entry.requestBody ?? entry.RequestBody),
             queryParams,
-            responseHeaders: entry.response?.headers ? sanitizeHeaders(entry.response.headers) : undefined,
+            responseHeaders: entry.response?.headers
+                ? sanitizeHeaders(entry.response.headers)
+                : undefined,
             responseBody: summarizeBody(entry.response?.body ?? entry.responseBody ?? entry.ResponseBody),
             timestamp: entry.timestamp || entry.Timestamp || entry.request?.timestamp || "",
         };
@@ -165,7 +192,18 @@ export async function parseTraceFile(filePath) {
     const userFlows = groupIntoFlows(entries);
     return { entries, userFlows, format };
 }
-const SKIP_DIRS = new Set(["node_modules", ".git", "dist", "build", ".next", ".nuxt", "coverage", "__pycache__", ".venv", "venv"]);
+const SKIP_DIRS = new Set([
+    "node_modules",
+    ".git",
+    "dist",
+    "build",
+    ".next",
+    ".nuxt",
+    "coverage",
+    "__pycache__",
+    ".venv",
+    "venv",
+]);
 /** Known test-artifact directories where testbot-generated traces are written. */
 const TRACE_SCAN_DIRS = [".skyramp", "tests", "test", "e2e", "playwright"];
 /**
@@ -173,7 +211,10 @@ const TRACE_SCAN_DIRS = [".skyramp", "tests", "test", "e2e", "playwright"];
  * levels below `dir` (maxDepth 0 = only files directly in `dir`).
  */
 function scanDir(dir, predicate, maxDepth, results) {
-    const opts = { maxDepth, shouldSkipDir: (entry) => SKIP_DIRS.has(entry.name) };
+    const opts = {
+        maxDepth,
+        shouldSkipDir: (entry) => SKIP_DIRS.has(entry.name),
+    };
     for (const [entry, full] of walkDir(dir, opts)) {
         if (predicate(entry.name))
             results.push(full);
@@ -201,7 +242,13 @@ function scanTraceArtifactDirs(repositoryPath, predicate, results) {
 export function discoverTraceFiles(repositoryPath) {
     const found = [];
     // Fixed-name candidates at repo root
-    for (const name of ["skyramp_traces.json", "traces.json", "trace.json", "traces.har", "trace.har"]) {
+    for (const name of [
+        "skyramp_traces.json",
+        "traces.json",
+        "trace.json",
+        "traces.har",
+        "trace.har",
+    ]) {
         const full = `${repositoryPath}/${name}`;
         if (fs.existsSync(full))
             found.push(full);
@@ -221,9 +268,10 @@ export function discoverTraceFiles(repositoryPath) {
 export function discoverPlaywrightZips(repositoryPath) {
     const found = [];
     // Match: *playwright*.zip OR *_trace.zip (skyramp_export_zip output) OR trace.zip
-    const isPlaywrightZip = (name) => /\.zip$/i.test(name) && (/playwright/i.test(name) ||
-        /_trace\.zip$/i.test(name) ||
-        name.toLowerCase() === "trace.zip");
+    const isPlaywrightZip = (name) => /\.zip$/i.test(name) &&
+        (/playwright/i.test(name) ||
+            /_trace\.zip$/i.test(name) ||
+            name.toLowerCase() === "trace.zip");
     scanTraceArtifactDirs(repositoryPath, isPlaywrightZip, found);
     return [...new Set(found)].sort();
 }

package/build/utils/urlPath.js

@@ -27,7 +27,9 @@ export function pathFromEndpointURL(endpointURL) {
     if (!endpointURL)
         return undefined;
     try {
-        return new URL(endpointURL).pathname.replace(/%7B/gi, "{").replace(/%7D/gi, "}");
+        return new URL(endpointURL).pathname
+            .replace(/%7B/gi, "{")
+            .replace(/%7D/gi, "}");
     }
     catch {
         return endpointURL.startsWith("/") ? endpointURL : undefined;

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

@@ -25,3 +25,49 @@ import type { UtilsLanguage } from "./language-spec.js";
  * helper in either language gets the same key.
  */
 export declare function actionKeyOf(body: string, language?: UtilsLanguage): string | undefined;
+/** The keys of every step, in order, or `undefined` when there is no step or a
+ *  step has no key — the sequence `actionKeyOf` joins, kept as steps for a caller
+ *  that matches step by step (a key is not split back: a selector may carry the
+ *  separator). */
+export declare function actionStepKeys(steps: ActionStep[]): string[] | undefined;
+/** One Playwright action in a body, in source order — the unit `actionKeyOf` joins. */
+export interface ActionStep {
+    /** The step's key (`verb chain [target]`), or `undefined` when this action cannot
+     *  be read: its locator is not built from plain string literals, or its arguments
+     *  do not balance. A helper with one such step has no key; a spec's other steps
+     *  are still read, so an unreadable step is a boundary no matched run crosses. */
+    key?: string;
+    /** 1-based line of the action verb. */
+    line: number;
+    /** The source between the previous action's closing `)` (or the start of the
+     *  body) and this action's chain: what stands between two consecutive actions.
+     *  Comments are as the caller left them; string contents are kept. Empty for
+     *  the first step. See `betweenActionsIsTransparent`. */
+    gapBefore: string;
+    /** The source after this action's closing `)` up to the next action's chain, or
+     *  to the end of the body for the last step — the next step's `gapBefore`. */
+    gapAfter: string;
+}
+/**
+ * Every action in `body`, in order, each keyed as `actionKeyOf` keys it. Where
+ * `actionKeyOf` answers "what does this helper do" with one string, this answers
+ * "which actions, where, and what sits between them" — what a scan for an inline
+ * copy of a helper's sequence needs. Lines survive the Python and alias rewrites:
+ * neither adds or removes a newline.
+ */
+export declare function actionStepsOf(body: string, language?: UtilsLanguage): ActionStep[];
+/** `click empty-cart-btn; fill qty` → `click \`empty-cart-btn\`; fill \`qty\`` — the
+ *  key as the agent reads it, selectors quoted so a `#id` never reads as prose. */
+export declare function describeActionKey(key: string): string;
+/** Index of the `)` that closes the `(` at `open`, on a string-blanked copy. */
+export declare function matchingClose(structure: string, open: number): number;
+/** Whitespace and braces dropped outside string literals, `'` normalised to `"` —
+ *  the spelling a locator chain has inside a key. */
+export declare function normalizeChain(text: string): string;
+/** String contents replaced by spaces, delimiters kept, same length. */
+export declare function blankStringContents(text: string): string;
+/** The statements of a fragment as `[start, end)` spans on `structure` (a
+ *  string-blanked copy): each cut where valueEnd cuts — a `;` at depth 0, or a line
+ *  end at depth 0 that the next line does not continue with `.` — so a
+ *  Prettier-wrapped chain is one statement, not one per line. */
+export declare function statementSpans(structure: string): [number, number][];