@skyramp/mcp 0.3.6 → 0.3.8

package/build/utils/AnalysisStateManager.d.ts

@@ -1,4 +1,5 @@
 import type { ReuseRecord } from "../tools/code-refactor/reuse-outcome.js";
+import type { AssertionRecord } from "../types/AssertionOutcome.js";
 import { TestAnalysisResult, MaintenanceActionCore } from "../types/TestAnalysis.js";
 import { RepositoryAnalysis, AnalysisScope } from "../types/RepositoryAnalysis.js";
 import { PRTestContext } from "./pr-comment-parser.js";
@@ -181,6 +182,16 @@ export interface PlanBudgetContext {
     /** Whether the PR diff changes any test file; see BudgetContext. */
     diffChangesTestFiles?: boolean;
 }
+/** A pre-existing Skyramp-generated test the reuse pass edited to import from a
+ *  shared utils file (STEP 5c / the sibling-inline advisory). Keyed by ABSOLUTE
+ *  PATH. Recorded in-process where staging finds the edit; skyramp_submit_report
+ *  refuses a report that leaves one undisclosed or unexecuted. */
+export interface ReuseRetrofit {
+    /** BASENAME(s) of the utils file(s) it now imports from. */
+    utilsFile: string;
+    /** Absolute path of the generated test whose reuse pass caused the edit. */
+    testFile: string;
+}
 export interface ReuseHandOff {
     testType: string;
     language: string;
@@ -231,19 +242,14 @@ export interface UnifiedAnalysisState {
      *  which computes every value in-process; skyramp_submit_report merges it into
      *  the report's `reuse` field. Never supplied by the LLM. */
     reuseOutcomes?: Record<string, ReuseRecord>;
-    /** SKYR-4262. Assertion-enhancement obligations per spec, keyed by test-file
-     *  BASENAME (same key as `reuseOutcomes`). Written in-process by
-     *  skyramp_enhance_assertions when it hands out instructions; checked by
-     *  skyramp_execute_test, which blocks when the spec is byte-identical to its
-     *  state at handout time (the agent acknowledged the instructions but never
-     *  acted on them). Never supplied by the LLM. */
-    enhanceOutcomes?: Record<string, import("../tools/code-refactor/enhance-state.js").EnhanceRecord>;
     /** Generation hand-offs that owe a modularize→reuse pass, keyed by the ABSOLUTE
      *  PATH of each file the generation call wrote (found by snapshotting `outputDir`
      *  before and after codegen — the agent, not the tool, chooses the file name).
      *  Written by the generation service at the exact site that emits the hand-off, so
      *  the debt has the same server-derived trust as `reuseOutcomes`. */
     reuseHandOffs?: Record<string, ReuseHandOff>;
+    /** See {@link ReuseRetrofit}. Never supplied by the LLM. */
+    reuseRetrofits?: Record<string, ReuseRetrofit>;
     /**
      * SKYR-4156. Recorded video per executed browser test, keyed by test-file
      * BASENAME (the same key `reuseOutcomes` uses, so matching needs no path
@@ -258,6 +264,13 @@ export interface UnifiedAnalysisState {
      * the earlier attempt's now-stale directory.
      */
     executionVideos?: Record<string, VideoRecord>;
+    /** Assertion-enhancement baseline + verify verdict per test file, keyed by
+     *  CANONICAL ABSOLUTE PATH (path.resolve — unlike `reuseOutcomes`, nothing
+     *  here matches report rows, and path keying removes basename collisions and
+     *  alias bypasses). Written in-process by skyramp_enhance_assertions;
+     *  skyramp_execute_test verifies against it server-side before executing.
+     *  Never supplied by the LLM. */
+    assertionOutcomes?: Record<string, AssertionRecord>;
 }
 /**
  * State file metadata

package/build/utils/assertion-verify/api-shared-lints.d.ts

@@ -0,0 +1,5 @@
+import type { AssertionLanguage } from "./metrics.js";
+import { type LintFinding, type LintOptions } from "./lint-types.js";
+/** Checks shared by integration and provider-contract tests. Java is never
+ *  linted (count+hash gates only). */
+export declare function lintApiShared(raw: string, language: AssertionLanguage, opts?: LintOptions): LintFinding[];

package/build/utils/assertion-verify/api-shared-lints.js

@@ -0,0 +1,315 @@
+import { escapeRegExp } from "../regex.js";
+import { strippedSources } from "./strip-dispatch.js";
+import { balancedCloseIndex, identifierRe, inScope, interpolationRe, lineOfOffset, } from "./lint-types.js";
+/**
+ * Deterministic checks shared by integration and provider-contract tests — the
+ * machine-checkable slice of the D5 rubric's echo_computed and array_depth
+ * dims. Exact VALUE correctness (does the assertion match the recorded/sent
+ * value?) needs trace ground truth and stays with the LLM judge.
+ */
+const RESPONSE_BINDING_RES = {
+    jsts: /(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=\s*await\s+[\w$.]*sendRequest\s*\(/g,
+    python: /^[ \t]*([A-Za-z_]\w*)\s*=\s*[\w.]*send_request\s*\(/gm,
+};
+const STATUS_USE_RE = /^\s*\.\s*(?:statusCode|status_code|status)\b/;
+/** All send_request/sendRequest bindings in the stripped source. */
+function responseBindings(stripped, language) {
+    const bindings = [];
+    const re = language === "python"
+        ? RESPONSE_BINDING_RES.python
+        : RESPONSE_BINDING_RES.jsts;
+    re.lastIndex = 0;
+    let m;
+    while ((m = re.exec(stripped)) !== null) {
+        const openIdx = stripped.indexOf("(", m.index + m[0].length - 1);
+        const declClose = balancedCloseIndex(stripped, openIdx);
+        if (declClose === -1)
+            continue;
+        bindings.push({ varName: m[1], declIndex: m.index, declClose });
+    }
+    return bindings;
+}
+/** Statuses asserted on a var's status lines; used for the 204/202 exemption. */
+function assertedStatuses(commentless, statusUseOffsets) {
+    const statuses = [];
+    for (const offset of statusUseOffsets) {
+        const lineEnd = commentless.indexOf("\n", offset);
+        const line = commentless.slice(offset, lineEnd === -1 ? undefined : lineEnd);
+        const code = /\b([1-5]\d{2})\b/.exec(line);
+        if (code)
+            statuses.push(Number(code[1]));
+    }
+    return statuses;
+}
+/** True when the binding at `idx` is declared inside a loop body — codegen's
+ *  polling loops (`for (…) { const r = await sendRequest(…); if (r.status …) break; }`)
+ *  bind a response that legitimately exists only to poll, and the remediation
+ *  ("assert after the status assertion") points at a place that is out of
+ *  scope after the loop. Poll bindings are exempt. */
+function isInsideLoop(stripped, idx, language) {
+    if (language === "python") {
+        const upto = stripped.slice(0, idx);
+        const lineStart = upto.lastIndexOf("\n") + 1;
+        let threshold = (/^[ \t]*/.exec(stripped.slice(lineStart)) ?? [""])[0]
+            .length;
+        const lines = upto.slice(0, lineStart).split("\n");
+        for (let i = lines.length - 1; i >= 0; i--) {
+            const line = lines[i];
+            if (line.trim() === "")
+                continue;
+            const indent = (/^[ \t]*/.exec(line) ?? [""])[0].length;
+            if (indent >= threshold)
+                continue;
+            if (/^[ \t]*(?:for|while)\b/.test(line))
+                return true;
+            threshold = indent;
+            if (threshold === 0)
+                return false;
+        }
+        return false;
+    }
+    const blockIsLoop = [];
+    for (let i = 0; i < idx; i++) {
+        const c = stripped[i];
+        if (c === "{") {
+            const head = stripped.slice(Math.max(0, i - 160), i);
+            blockIsLoop.push(/\b(?:for|while)\s*\([^{]*\)\s*$/.test(head) || /\bdo\s*$/.test(head));
+        }
+        else if (c === "}") {
+            blockIsLoop.pop();
+        }
+    }
+    return blockIsLoop.some(Boolean);
+}
+// The SDK's own status helper: `checkStatusCode(r, "200")` passes the response
+// as a call argument, but it is a STATUS use, not a body read.
+const STATUS_HELPER_BEFORE_RE = /check_?status_?code\s*\(\s*$/i;
+/** Response bindings whose every use is a status read (or that are never used).
+ *  Any other read — getValue/get_response_value/checkSchema/.json()/passed as a
+ *  call argument, including inside a template-literal or f-string interpolation
+ *  — clears it. Exempt: DELETE calls, sole 204/202 statuses, poll bindings
+ *  inside loops. Severity follows the rubric: unconditional (`hard`) for
+ *  4xx/5xx — an error body must always be asserted — and advisory (`warn`)
+ *  when only 2xx statuses are asserted, because a 200 can legitimately carry
+ *  no body (/logout, /cancel) and that is not deterministically knowable. */
+function lintStatusOnlyResponses(stripped, commentless, language, bindings) {
+    const findings = [];
+    for (const { varName, declIndex, declClose } of bindings) {
+        // DELETE exemption: the request itself is a DELETE (args read from the
+        // comment-stripped raw so the method string literal is visible; the
+        // enum spelling `method: Method.DELETE` counts too).
+        const openIdx = stripped.indexOf("(", declIndex);
+        const declArgs = commentless.slice(openIdx, declClose + 1);
+        if (/['"]delete['"]|method\s*[:=]\s*[\w.]*\bDELETE\b/i.test(declArgs)) {
+            continue;
+        }
+        if (isInsideLoop(stripped, declIndex, language))
+            continue;
+        const after = stripped.slice(declClose + 1);
+        const refRe = identifierRe(varName, "g");
+        let ref;
+        let statusUses = 0;
+        let otherUses = 0;
+        const statusUseOffsets = [];
+        while ((ref = refRe.exec(after)) !== null) {
+            // Bounded window: STATUS_USE_RE is anchored and needs ~20 chars, so
+            // slicing to EOF per reference was O(n × references).
+            const tail = after.slice(ref.index + varName.length, ref.index + varName.length + 40);
+            const before = after.slice(Math.max(0, ref.index - 24), ref.index);
+            if (STATUS_USE_RE.test(tail) || STATUS_HELPER_BEFORE_RE.test(before)) {
+                statusUses++;
+                statusUseOffsets.push(declClose + 1 + ref.index);
+            }
+            else {
+                otherUses++;
+            }
+        }
+        // Template-literal `${...}` and python f-string `{...}` interpolations are
+        // blanked wholesale by the strippers, so a use like
+        // `sendRequest(\`/orders/\${getValue(resp, "id")}\`)` is invisible above.
+        // Count interpolation reads from the comment-stripped source.
+        if (otherUses === 0 &&
+            interpolationRe(varName, language).test(commentless.slice(declClose + 1))) {
+            otherUses++;
+        }
+        if (otherUses > 0)
+            continue;
+        const statuses = assertedStatuses(commentless, statusUseOffsets);
+        if (statuses.length > 0 && statuses.every((s) => s === 204 || s === 202)) {
+            continue;
+        }
+        // Never-used responses and asserted error statuses are unconditional
+        // violations; a 2xx-only status check is advisory (empty-body 200s exist).
+        const severity = statusUses === 0 || statuses.some((s) => s >= 400) ? "hard" : "warn";
+        findings.push({
+            rule: "status-only-response",
+            severity,
+            line: lineOfOffset(stripped, declIndex),
+            message: statusUses > 0
+                ? severity === "hard"
+                    ? `Error response \`${varName}\` is only checked for its status code — the error body (code/message/detail) must be asserted.`
+                    : `Response \`${varName}\` is only checked for its status code — if this endpoint returns a body, assert its fields (skip only for genuinely empty-body responses).`
+                : `Response \`${varName}\` is captured but never asserted.`,
+            remediation: language === "python"
+                ? `Assert body fields via \`skyramp.get_response_value(${varName}, "json.path")\` after the status assertion.`
+                : `Assert body fields via \`getValue(${varName}, "json.path")\` after the status assertion.`,
+        });
+    }
+    return findings;
+}
+/** Dict-subscript access on a response binding (`r["field"]`) — the rules
+ *  mandate the SDK helper for every body read; subscript access bypasses the
+ *  helper's null-safe path handling. Near-zero false positives: response
+ *  objects are not lists/dicts, so a legitimate subscript on one is not a real
+ *  pattern. */
+function lintSdkHelperBypass(stripped, bindings, language) {
+    const findings = [];
+    for (const { varName, declClose } of bindings) {
+        const after = stripped.slice(declClose + 1);
+        const subscriptRe = new RegExp(`(?<![\\w$])${escapeRegExp(varName)}\\s*\\[`, "g");
+        const m = subscriptRe.exec(after);
+        if (m) {
+            findings.push({
+                rule: "sdk-helper-bypass",
+                severity: "hard",
+                line: lineOfOffset(stripped, declClose + 1 + m.index),
+                message: `Response \`${varName}\` is read via dict/subscript access instead of the SDK helper.`,
+                remediation: language === "python"
+                    ? `Use \`skyramp.get_response_value(${varName}, "json.path")\` — never \`${varName}[...]\`.`
+                    : `Use \`getValue(${varName}, "json.path")\` — never \`${varName}[...]\`.`,
+            });
+        }
+    }
+    return findings;
+}
+// Exactly the permissive forms the rules name — anything cleverer is not chased.
+const PERMISSIVE_STATUS_RES = [
+    /toBeGreaterThanOrEqual\s*\(\s*200\s*\)/,
+    /toMatch\s*\(\s*\/\^?2/,
+    /\b200\s*<=\s*[\w.]*status(?:_code|Code)?\b/,
+    /str\s*\(\s*[\w.]*status_code\s*\)\s*\.\s*startswith\s*\(\s*['"]2/,
+    // Only WILDCARD forms ('20x', '2xx') are permissive — the SDK documents
+    // '"200" matches exactly 200', so a fully numeric literal is an exact match.
+    /check_?status_?code\s*\([^)]*['"][0-9x]*x[0-9x]*['"]/i,
+];
+const STATUS_MENTION_RE = /statusCode|status_code|\.status\b|check_?status/i;
+function lintPermissiveStatusMatchers(commentless, opts) {
+    const findings = [];
+    const lines = commentless.split("\n");
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        if (!STATUS_MENTION_RE.test(line))
+            continue;
+        if (PERMISSIVE_STATUS_RES.some((re) => re.test(line)) &&
+            inScope(i + 1, opts)) {
+            findings.push({
+                rule: "permissive-status-matcher",
+                severity: "hard",
+                line: i + 1,
+                message: "Permissive status matcher — the exact recorded status is knowable.",
+                remediation: "Assert the exact status code from the recorded trace or expected_response_body (e.g. `.toBe(201)` / `== 201`).",
+            });
+        }
+    }
+    return findings;
+}
+const SHAPE_ONLY_RE = /Array\.isArray\s*\(|typeof\s+[\w.[\]]+\s*===|instanceof\s+Array|Object\.keys\s*\([^)]*\)\s*\.length|isinstance\s*\(/;
+function lintShapeOnlyChecks(commentless) {
+    const findings = [];
+    const lines = commentless.split("\n");
+    for (let i = 0; i < lines.length; i++) {
+        if (SHAPE_ONLY_RE.test(lines[i])) {
+            findings.push({
+                rule: "shape-only-check",
+                severity: "warn",
+                line: i + 1,
+                message: "Shape/type-only check — fine as a companion, not as the sole validation.",
+                remediation: "Ensure the response's actual values are also asserted exactly (fields, lengths, per-item values).",
+            });
+        }
+    }
+    return findings;
+}
+// JSON paths read through the SDK helpers, e.g. getValue(r, "items.0.id").
+const SDK_PATH_RE = /(?:getValue|getResponseValue|get_response_value)\s*\(\s*[\w.]+\s*,\s*['"]([^'"]+)['"]/g;
+// Length reads on an SDK-helper result: `getValue(r, "items").length` or
+// `len(skyramp.get_response_value(r, "items"))`.
+const JS_LENGTH_RE = /(?:getValue|getResponseValue)\s*\(\s*[\w.]+\s*,\s*['"]([^'"]+)['"]\s*\)\s*\.\s*length/g;
+const PY_LENGTH_RE = /len\s*\(\s*[\w.]*get_response_value\s*\(\s*[\w.]+\s*,\s*['"]([^'"]+)['"]/g;
+/** Array-depth advisories (warn-only — array emptiness/size is trace-dependent):
+ *  - length asserted for a path but no per-item field asserted under it
+ *  - per-item assertions exist but the next index is never asserted absent */
+function lintArrayDepth(commentless) {
+    const findings = [];
+    const paths = [];
+    SDK_PATH_RE.lastIndex = 0;
+    let m;
+    while ((m = SDK_PATH_RE.exec(commentless)) !== null)
+        paths.push(m[1]);
+    const lengthPaths = new Set();
+    for (const re of [JS_LENGTH_RE, PY_LENGTH_RE]) {
+        re.lastIndex = 0;
+        while ((m = re.exec(commentless)) !== null)
+            lengthPaths.add(m[1]);
+    }
+    // Length-only: a counted array with no per-item content assertion under it.
+    for (const arrayPath of lengthPaths) {
+        const hasItemRead = paths.some((p) => p.startsWith(`${arrayPath}.`));
+        if (!hasItemRead) {
+            findings.push({
+                rule: "array-length-only",
+                severity: "warn",
+                message: `Array \`${arrayPath}\` is only checked for its length — no per-item field is asserted.`,
+                remediation: `Assert key fields on each recorded item (e.g. "${arrayPath}.0.<field>") in addition to the length.`,
+            });
+        }
+    }
+    // Indexed item-content reads (`items.N.field`) without a next-index-absent
+    // assertion (a bare `items.N+1` read). Scalar arrays (bare-index-only reads)
+    // are skipped — a bare index there is a content assertion, not an absence
+    // check, and the two are indistinguishable without parsing matchers.
+    const contentMaxByPath = new Map();
+    const barePaths = new Set();
+    for (const p of paths) {
+        const withField = /^(.+)\.(\d+)\./.exec(p);
+        if (withField) {
+            const base = withField[1];
+            const n = Number(withField[2]);
+            contentMaxByPath.set(base, Math.max(contentMaxByPath.get(base) ?? -1, n));
+            continue;
+        }
+        if (/^.+\.\d+$/.test(p))
+            barePaths.add(p);
+    }
+    for (const [base, maxIdx] of contentMaxByPath) {
+        const nextPath = `${base}.${maxIdx + 1}`;
+        if (!barePaths.has(nextPath)) {
+            findings.push({
+                rule: "array-missing-next-index-check",
+                severity: "warn",
+                message: `Items of \`${base}\` are asserted up to index ${maxIdx}, but index ${maxIdx + 1} is never asserted absent.`,
+                remediation: `Add an absence assertion for the index after the last expected item (e.g. \`getValue(response, "${nextPath}")\` is undefined / None).`,
+            });
+        }
+    }
+    return findings;
+}
+/** Checks shared by integration and provider-contract tests. Java is never
+ *  linted (count+hash gates only). */
+export function lintApiShared(raw, language, opts) {
+    if (language === "java")
+        return [];
+    const maintenance = opts?.scopeLines !== undefined;
+    const { commentless, stripped } = strippedSources(raw, language);
+    const findings = [];
+    if (!maintenance) {
+        // Bindings discovered once, shared by both binding-scoped lints.
+        const bindings = responseBindings(stripped, language);
+        findings.push(...lintStatusOnlyResponses(stripped, commentless, language, bindings));
+        findings.push(...lintSdkHelperBypass(stripped, bindings, language));
+        findings.push(...lintShapeOnlyChecks(commentless));
+        findings.push(...lintArrayDepth(commentless));
+    }
+    findings.push(...lintPermissiveStatusMatchers(commentless, opts));
+    return findings;
+}

package/build/utils/assertion-verify/contract-lints.d.ts

@@ -0,0 +1,3 @@
+import type { AssertionLanguage } from "./metrics.js";
+import { type LintFinding, type LintOptions } from "./lint-types.js";
+export declare function lintContractTest(raw: string, language: AssertionLanguage, opts?: LintOptions): LintFinding[];

package/build/utils/assertion-verify/contract-lints.js

@@ -0,0 +1,87 @@
+import { strippedSources } from "./strip-dispatch.js";
+import { balancedCloseIndex, identifierRe, lineOfOffset, } from "./lint-types.js";
+import { lintApiShared } from "./api-shared-lints.js";
+/**
+ * Provider-contract lints: the shared API checks plus the machine-checkable
+ * slice of the D5 `value_sources` dim — contract assertions must use inline
+ * request values, never data provisioned in beforeAll/beforeEach.
+ */
+const SETUP_BLOCK_RE = /\b(?:beforeAll|beforeEach)\s*\(/g;
+const DECL_RE = /(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=/g;
+/** Identifiers assigned inside beforeAll/beforeEach blocks and the block
+ *  ranges themselves (JS/TS only — python contract tests use pytest fixtures,
+ *  out of scope here). The ranges matter: codegen's own provisioning status
+ *  checks live INSIDE the setup blocks and reference these names legitimately
+ *  — only TEST-BODY assertions using setup data violate the rubric (measured:
+ *  7 of 8 pristine provider-contract goldens false-warned without this). */
+function setupDeclarations(stripped) {
+    const names = new Set();
+    const ranges = [];
+    SETUP_BLOCK_RE.lastIndex = 0;
+    let m;
+    while ((m = SETUP_BLOCK_RE.exec(stripped)) !== null) {
+        const close = balancedCloseIndex(stripped, m.index + m[0].length - 1);
+        if (close === -1)
+            continue;
+        ranges.push([m.index, close]);
+        const block = stripped.slice(m.index, close + 1);
+        DECL_RE.lastIndex = 0;
+        let decl;
+        while ((decl = DECL_RE.exec(block)) !== null)
+            names.add(decl[1]);
+    }
+    return { names, ranges };
+}
+/** An assertion references a value provisioned in beforeAll/beforeEach.
+ *  Warn-only: block-scoped `const` inside beforeAll is not reachable from a
+ *  test body in real code, so hits are usually closure vars — a strong smell,
+ *  but shared infra handles (clients, tokens) are legitimate closure vars too. */
+function lintSetupDataInAssertions(stripped) {
+    const { names, ranges } = setupDeclarations(stripped);
+    if (names.size === 0)
+        return [];
+    // Compile once per name, not per (site × name).
+    const nameRes = new Map([...names].map((name) => [name, identifierRe(name)]));
+    const findings = [];
+    const expectRe = /\bexpect(?:\s*\.\s*soft)?\s*\(/g;
+    let m;
+    while ((m = expectRe.exec(stripped)) !== null) {
+        // Setup-internal assertions (provisioning status checks) are codegen's
+        // own sanctioned shape — only test-body references are the violation.
+        const at = m.index;
+        if (ranges.some(([start, end]) => at >= start && at <= end))
+            continue;
+        const close = balancedCloseIndex(stripped, m.index + m[0].length - 1);
+        if (close === -1)
+            continue;
+        // The whole statement line, so matcher arguments count too.
+        const lineEnd = stripped.indexOf("\n", close);
+        const stmt = stripped.slice(m.index, lineEnd === -1 ? undefined : lineEnd);
+        for (const [name, re] of nameRes) {
+            if (re.test(stmt)) {
+                findings.push({
+                    rule: "setup-data-in-assertion",
+                    severity: "warn",
+                    line: lineOfOffset(stripped, m.index),
+                    message: `Assertion references \`${name}\`, which is provisioned in beforeAll/beforeEach.`,
+                    remediation: "Contract assertions must use values from the inline request body, path, query, or expected_response_body — not setup-provisioned data.",
+                });
+                break;
+            }
+        }
+    }
+    return findings;
+}
+export function lintContractTest(raw, language, opts) {
+    // Java is count+hash gated only (a documented limit of the verifier): the
+    // lint regexes and strength weights are written for the python/ts/js SDK
+    // helper idioms, and applying them to JUnit source would produce false
+    // findings, not protection. Same guard as helper-imports.ts.
+    if (language === "java")
+        return [];
+    const findings = lintApiShared(raw, language, opts);
+    if (opts?.scopeLines === undefined && language !== "python") {
+        findings.push(...lintSetupDataInAssertions(strippedSources(raw, language).stripped));
+    }
+    return findings;
+}

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

@@ -0,0 +1,5 @@
+import type { AssertionVerifyResult } from "./verify.js";
+/** Renders the verify result as the text returned to the agent — PASSED/FAILED
+ *  with one actionable remediation per violation, in the style of the reuse
+ *  verify report (verify-gates.ts). */
+export declare function formatAssertionVerifyReport(r: AssertionVerifyResult, testFile: string): string;

package/build/utils/assertion-verify/format.js

@@ -0,0 +1,65 @@
+import * as path from "path";
+import { detectAssertionLanguage } from "./metrics.js";
+import { markerCommentToken } from "./marker.js";
+/** Renders the verify result as the text returned to the agent — PASSED/FAILED
+ *  with one actionable remediation per violation, in the style of the reuse
+ *  verify report (verify-gates.ts). */
+export function formatAssertionVerifyReport(r, testFile) {
+    const spec = path.basename(testFile);
+    // Paste-ready marker lines must use THIS file's comment token — a `//`
+    // marker in a .py file is a syntax error.
+    const token = markerCommentToken(detectAssertionLanguage(testFile) ?? "typescript");
+    const finding = (f) => `- ${f.line !== undefined ? `line ${f.line}: ` : ""}${f.message} Fix: ${f.remediation}`;
+    if (r.ok) {
+        // Maintenance drops the strength-family gates (value-only fixes are
+        // legitimate), so its PASS is a weaker claim — say so, rather than letting
+        // the agent and the eval judge read it as a full verification.
+        const heading = r.enhanceType === "maintenance" && r.baselinePresent
+            ? r.maintenanceNoAssertionChanges
+                ? `ASSERTION MAINTENANCE CHECK PASSED — ${spec}: no assertion changes since hand-out; nothing to verify.`
+                : `ASSERTION MAINTENANCE CHECK PASSED — ${spec}: ${r.currentMetrics?.count ?? "?"} assertion sites (differential strength gates are not applicable in maintenance; added/changed assertions were linted and removals guarded).`
+            : `ASSERTION VERIFICATION PASSED — ${spec}: ${r.currentMetrics?.count ?? "?"} assertion sites` +
+                (r.strengthDelta !== undefined && r.strengthDelta > 0
+                    ? `, strength +${r.strengthDelta} over the generated baseline.`
+                    : ".");
+        const lines = [heading];
+        if (r.replacedCount !== undefined && r.replacedCount > 0) {
+            lines.push(`${r.replacedCount} generated assertion${r.replacedCount === 1 ? "" : "s"} replaced on the same subject — accepted.`);
+        }
+        if (r.movedToHelperCount !== undefined && r.movedToHelperCount > 0) {
+            lines.push(`${r.movedToHelperCount} assertion${r.movedToHelperCount === 1 ? "" : "s"} now covered by an imported helper file — accepted.`);
+        }
+        if (r.markerReason !== undefined) {
+            lines.push(`Documented decline accepted: ${r.markerReason}`);
+        }
+        if (!r.baselinePresent) {
+            lines.push("No enhancement baseline was recorded for this file, so only the stateless checks (rubric lints, markers) ran.");
+        }
+        return [...lines, ...warningsBlock(r.warnings, finding)].join("\n");
+    }
+    const lines = [`ASSERTION VERIFICATION FAILED — ${spec}:`];
+    if (r.hashUnchanged) {
+        lines.push("- The file is byte-identical to when the enhancement instructions were handed out — nothing was applied. Read the file, apply the instructions, and re-verify.");
+    }
+    if (r.removedFingerprints !== undefined) {
+        lines.push(`- Assertions were REMOVED — their subjects are asserted neither in this file nor in any helper file it imports. Replacing an assertion with a stronger one on the same subject is fine — losing coverage is not, and a documented decline does NOT clear this. Restore the assertions in THIS spec file${r.baselineFilePath !== undefined ? ` (the generated baseline is preserved at ${r.baselineFilePath})` : ""}. Do NOT edit shared helper/utils files — they are imported by other tests.`, r.removedCount !== undefined &&
+            r.removedCount > r.removedFingerprints.length
+            ? `  Missing (showing ${r.removedFingerprints.length} of ${r.removedCount} — restore ALL of them in this pass):`
+            : "  Missing:", ...r.removedFingerprints.map((fp) => `    ${fp}`));
+    }
+    lines.push(...r.hardFindings.map(finding));
+    if (r.strengthGateFailed) {
+        lines.push("- Assertion strength did not increase over the generated baseline: no assertion was added and no weak matcher was strengthened (e.g. `toBeVisible` → `toHaveText`). Apply the enhancement rules. A documented decline (`assertions complete` comment) is accepted only AFTER at least one assertion was added or replaced — a marker-only edit does not pass this gate.");
+    }
+    if (r.weakAdditionsOnly) {
+        lines.push("- Every assertion added since the baseline is existence/visibility-tier (`toBeVisible`, `not.toBeNull`, `is not None`, ranges). When the exact text/value/count is knowable from the trace, source, or request, assert it exactly (`toHaveText`/`toHaveCount`/`toBe`/`==`). If only existence is genuinely knowable, document the decline:", `    ${token} assertions complete: ${spec} — <reason exact values are not knowable>`);
+    }
+    lines.push(...warningsBlock(r.warnings, finding));
+    lines.push("Re-run this verification (verify: true) after every fix pass — skyramp_execute_test runs the same checks automatically and will not execute this test until they pass.");
+    return lines.join("\n");
+}
+function warningsBlock(warnings, finding) {
+    if (warnings.length === 0)
+        return [];
+    return ["WARNINGS (informational — do not block):", ...warnings.map(finding)];
+}

package/build/utils/assertion-verify/helper-imports.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Assertion SUBJECTS found in the spec's locally imported, actually-called
+ * helper files. Strict-by-default failure direction: an unreadable/oversized/
+ * uncalled helper is skipped, so its subjects don't excuse anything.
+ */
+export declare function importedHelperSubjects(testFile: string, content: string): Promise<Set<string>>;