@skyramp/mcp 0.3.6-rc.2.ac20 → 0.3.7

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>>;

package/build/utils/assertion-verify/helper-imports.js

@@ -0,0 +1,178 @@
+import * as path from "path";
+import { readFile, stat } from "fs/promises";
+import { logger } from "../logger.js";
+import { strippedSources } from "./strip-dispatch.js";
+import { identifierRe } from "./lint-types.js";
+import { computeAssertionMetrics, detectAssertionLanguage, subjectOf, } from "./metrics.js";
+/**
+ * Read-only scan of the spec's locally imported AND CALLED modules (the
+ * modularized skyramp-utils/helper files), used by the removal gate: a
+ * baseline subject missing from the spec is not "removed" if an imported
+ * helper still asserts it.
+ *
+ * Two deliberate restrictions:
+ * - One-directional — helper assertions can only EXCUSE removals, never add
+ *   to the spec's count or strength score: a shared utils file is imported by
+ *   many specs, and crediting its assertions to each one would inflate every
+ *   baseline comparison.
+ * - CALLED, not merely imported — an import statement plus a dead helper file
+ *   would otherwise turn a correctly-blocked gutting into a PASS (same
+ *   call-position requirement as the reuse gate's call-site matching). Only
+ *   helpers whose imported bindings appear at a call position in the spec
+ *   contribute subjects.
+ *
+ * Helpers are never modified.
+ */
+const MAX_HELPER_FILES = 5;
+const MAX_HELPER_BYTES = 256 * 1024;
+// Import forms that bind local names to a RELATIVE module. Dynamic import()
+// is deliberately absent: it binds no statically-trackable name, and dropping
+// it errs strict (the removal stays a removal).
+const JS_IMPORT_RES = [
+    // import defaultName from './x' | import * as ns from './x' |
+    // import { a, b as c } from './x' | import d, { a } from './x'
+    /import\s+([^'"()]+?)\s*from\s*['"](\.{1,2}\/[^'"]+)['"]/g,
+    // const d = require('./x') | const { a, b: c } = require('./x')
+    /(?:const|let|var)\s+([^=]+?)\s*=\s*require\s*\(\s*['"](\.{1,2}\/[^'"]+)['"]\s*\)/g,
+];
+const PY_IMPORT_RES = [
+    // from .x import a, b as c   |   from x import a
+    /^[ \t]*from\s+(\.*[\w.]+)\s+import\s+([^\n#]+)/gm,
+    // import x   (module itself becomes the callable namespace)
+    /^[ \t]*import\s+([\w.]+)(?:\s+as\s+([\w]+))?/gm,
+];
+const JS_RESOLVE_SUFFIXES = [
+    "",
+    ".ts",
+    ".tsx",
+    ".js",
+    ".jsx",
+    ".mjs",
+    ".cjs",
+    ".mts",
+    ".cts",
+    "/index.ts",
+    "/index.js",
+];
+function pyCandidates(specDir, specifier) {
+    const moduleName = specifier.replace(/^\.+/, "").split(".")[0];
+    return moduleName ? [path.resolve(specDir, `${moduleName}.py`)] : [];
+}
+/** Local names bound by a JS import/require clause ("d, { a, b as c }"). */
+function jsBoundNames(clause) {
+    const names = [];
+    const star = /\*\s*as\s+([\w$]+)/.exec(clause);
+    if (star)
+        names.push(star[1]);
+    const braces = /\{([^}]*)\}/.exec(clause);
+    if (braces) {
+        for (const part of braces[1].split(",")) {
+            const name = (part.split(/\s+as\s+|\s*:\s*/).pop() ?? "").trim();
+            if (/^[\w$]+$/.test(name))
+                names.push(name);
+        }
+    }
+    const bare = clause
+        .replace(/\{[^}]*\}/, "")
+        .replace(/\*\s*as\s+[\w$]+/, "")
+        .replace(/,/g, " ")
+        .trim();
+    if (/^[\w$]+$/.test(bare))
+        names.push(bare);
+    return names;
+}
+/** Relative/local imports with the names they bind. */
+function localImports(content, language) {
+    const commentless = strippedSources(content, language).commentless;
+    const imports = [];
+    if (language === "python") {
+        const [fromRe, importRe] = PY_IMPORT_RES;
+        fromRe.lastIndex = 0;
+        let m;
+        while ((m = fromRe.exec(commentless)) !== null) {
+            const names = m[2]
+                .split(",")
+                .map((part) => (part.split(/\s+as\s+/).pop() ?? "").trim())
+                .filter((n) => /^\w+$/.test(n));
+            imports.push({ specifier: m[1], localNames: names });
+        }
+        importRe.lastIndex = 0;
+        while ((m = importRe.exec(commentless)) !== null) {
+            imports.push({ specifier: m[1], localNames: [m[2] ?? m[1]] });
+        }
+        return imports;
+    }
+    for (const re of JS_IMPORT_RES) {
+        re.lastIndex = 0;
+        let m;
+        while ((m = re.exec(commentless)) !== null) {
+            imports.push({ specifier: m[2], localNames: jsBoundNames(m[1]) });
+        }
+    }
+    return imports;
+}
+/** True when any of the bound names appears at a CALL position in the spec —
+ *  `name(...)` or `name.member(...)` — on comment/string-stripped source. */
+function anyNameCalled(strippedSpec, names) {
+    // identifierRe gives the identifier boundary; the extra `(?<!\.)` keeps a
+    // same-named METHOD on another object (`other.name(...)`) from counting;
+    // the suffix requires a CALL position — `name(...)` or `name.member(...)`.
+    return names.some((name) => new RegExp(`(?<!\\.)${identifierRe(name).source}\\s*(?:\\(|\\.\\s*[\\w$]+\\s*\\()`).test(strippedSpec));
+}
+/**
+ * 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 async function importedHelperSubjects(testFile, content) {
+    const subjects = new Set();
+    const language = detectAssertionLanguage(testFile);
+    // Not a no-op: an empty subject set means NO removal gets excused by a
+    // helper — the strict direction. Unknown languages have no import scanner;
+    // java is count+hash gated only (no fingerprint subjects exist to excuse —
+    // same documented limit as contract-lints.ts).
+    if (language === undefined || language === "java")
+        return subjects;
+    const strippedSpec = strippedSources(content, language).stripped;
+    const specDir = path.dirname(testFile);
+    let scanned = 0;
+    for (const { specifier, localNames } of localImports(content, language)) {
+        if (scanned >= MAX_HELPER_FILES) {
+            logger.warning("Assertion verification scanned the maximum number of imported helper files — remaining imports ignored", { testFile, max: MAX_HELPER_FILES });
+            break;
+        }
+        // An import whose bindings are never invoked cannot vouch for coverage —
+        // a dead helper file must not excuse a gutted spec.
+        if (localNames.length === 0 || !anyNameCalled(strippedSpec, localNames)) {
+            continue;
+        }
+        const candidates = language === "python"
+            ? pyCandidates(specDir, specifier)
+            : JS_RESOLVE_SUFFIXES.map((s) => path.resolve(specDir, specifier) + s);
+        for (const candidate of candidates) {
+            try {
+                const info = await stat(candidate);
+                // A directory hit (extensionless specifier) must not shadow the real
+                // module file — keep trying the remaining suffix candidates.
+                if (!info.isFile() || info.size > MAX_HELPER_BYTES)
+                    continue;
+                const helperLanguage = detectAssertionLanguage(candidate);
+                if (helperLanguage === undefined)
+                    continue;
+                const helperContent = await readFile(candidate, "utf8");
+                for (const fp of computeAssertionMetrics(helperContent, helperLanguage)
+                    .fingerprints) {
+                    const subject = subjectOf(fp);
+                    if (subject !== undefined)
+                        subjects.add(subject);
+                }
+                scanned++;
+                break;
+            }
+            catch {
+                // Candidate doesn't exist / unreadable — try the next suffix.
+            }
+        }
+    }
+    return subjects;
+}

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

@@ -0,0 +1,3 @@
+export { detectAssertionLanguage, computeAssertionMetrics } from "./metrics.js";
+export { verifyAssertionEnhancement, sha256Of, type AssertionBaseline, type AssertionEnhanceType, type AssertionVerifyResult, } from "./verify.js";
+export { formatAssertionVerifyReport } from "./format.js";

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

@@ -0,0 +1,7 @@
+// Barrel: only what crosses the package boundary (assertion-state.ts and
+// enhanceAssertionsTool.ts). Internal helpers and the per-test-type lint
+// modules are imported directly by their sibling files and by tests — listing
+// them here made every internal name look like public API.
+export { detectAssertionLanguage, computeAssertionMetrics } from "./metrics.js";
+export { verifyAssertionEnhancement, sha256Of, } from "./verify.js";
+export { formatAssertionVerifyReport } from "./format.js";

package/build/utils/assertion-verify/integration-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 lintIntegrationTest(raw: string, language: AssertionLanguage, opts?: LintOptions): LintFinding[];

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

@@ -0,0 +1,36 @@
+import { strippedSources } from "./strip-dispatch.js";
+import { lineOfOffset, } from "./lint-types.js";
+import { lintApiShared } from "./api-shared-lints.js";
+/**
+ * Integration-test lints: the shared API checks plus the machine-checkable
+ * slice of the D5 `chaining` dim. Whether chained values are the RIGHT ones is
+ * judge territory; a literal UUID embedded in a request is not — an ID that
+ * exists before the run started cannot have come from a prior response.
+ */
+const UUID_IN_REQUEST_RE = /(?:sendRequest|send_request)\s*\([^)]*['"`][^'"`]*\b[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\b/gi;
+/** A hardcoded UUID inside a request call — chained IDs should come from a
+ *  prior step's response. Warn-only: fixtures may legitimately pin seeded IDs. */
+function lintHardcodedRequestIds(commentless) {
+    const findings = [];
+    UUID_IN_REQUEST_RE.lastIndex = 0;
+    let m;
+    while ((m = UUID_IN_REQUEST_RE.exec(commentless)) !== null) {
+        findings.push({
+            rule: "hardcoded-request-id",
+            severity: "warn",
+            line: lineOfOffset(commentless, m.index),
+            message: "A request embeds a hardcoded UUID.",
+            remediation: "Extract the ID from the prior step's response (SDK helper) instead of hardcoding it, unless it is intentionally seeded fixture data.",
+        });
+    }
+    return findings;
+}
+export function lintIntegrationTest(raw, language, opts) {
+    if (language === "java")
+        return [];
+    const findings = lintApiShared(raw, language, opts);
+    if (opts?.scopeLines === undefined) {
+        findings.push(...lintHardcodedRequestIds(strippedSources(raw, language).commentless));
+    }
+    return findings;
+}

package/build/utils/assertion-verify/js-regex-blank.d.ts

@@ -0,0 +1 @@
+export declare function blankJsRegexLiterals(src: string): string;

package/build/utils/assertion-verify/js-regex-blank.js

@@ -0,0 +1,153 @@
+/**
+ * Offset-preserving blanking of JS/TS regex literals. `pom-scope/strip.ts`
+ * knows nothing about regex literals, so an apostrophe inside one (e.g.
+ * `getByText(/Don't have an account/)`) opens a phantom string span that
+ * swallows real code through the next quote — corrupting metrics and lints on
+ * perfectly valid specs. Blanking regex interiors first removes the hazard.
+ *
+ * Heuristic regex-start detection (`/` is a regex only where an expression may
+ * begin): the previous non-space character is an operator/opener/keyword end,
+ * not an identifier/literal end. Division therefore stays untouched. Only used
+ * as a pre-pass for scanners that never need regex CONTENT — lints that match
+ * regex text (permissive-status) run on comment-stripped source instead.
+ */
+const REGEX_MAY_FOLLOW = new Set([
+    "(",
+    ",",
+    "=",
+    ":",
+    "[",
+    "!",
+    "&",
+    "|",
+    "?",
+    "{",
+    ";",
+    "+",
+    "-",
+    "*",
+    "%",
+    "<",
+    ">",
+    "~",
+    "^",
+]);
+// Whole-token match only: an identifier merely ENDING in a keyword (`min`,
+// `margin`, `todo`, `login`) is an ordinary value and a `/` after it is
+// division — suffix-matching here silently blanked real code.
+const KEYWORDS_BEFORE_REGEX = new Set([
+    "return",
+    "typeof",
+    "case",
+    "in",
+    "of",
+    "instanceof",
+    "new",
+    "do",
+    "else",
+    "void",
+    "delete",
+    "throw",
+    "await",
+    "yield",
+]);
+export function blankJsRegexLiterals(src) {
+    const out = src.split("");
+    let i = 0;
+    const n = src.length;
+    let inLineComment = false;
+    let inBlockComment = false;
+    let stringQuote;
+    while (i < n) {
+        const c = src[i];
+        if (inLineComment) {
+            if (c === "\n")
+                inLineComment = false;
+            i++;
+            continue;
+        }
+        if (inBlockComment) {
+            if (c === "*" && src[i + 1] === "/") {
+                inBlockComment = false;
+                i += 2;
+                continue;
+            }
+            i++;
+            continue;
+        }
+        if (stringQuote !== undefined) {
+            if (c === "\\") {
+                i += 2;
+                continue;
+            }
+            if (c === stringQuote || (c === "\n" && stringQuote !== "`")) {
+                stringQuote = undefined;
+            }
+            i++;
+            continue;
+        }
+        if (c === "/" && src[i + 1] === "/") {
+            inLineComment = true;
+            i += 2;
+            continue;
+        }
+        if (c === "/" && src[i + 1] === "*") {
+            inBlockComment = true;
+            i += 2;
+            continue;
+        }
+        if (c === "'" || c === '"' || c === "`") {
+            stringQuote = c;
+            i++;
+            continue;
+        }
+        if (c === "/") {
+            // Decide regex vs division from the previous non-whitespace token.
+            let j = i - 1;
+            while (j >= 0 && /\s/.test(src[j]))
+                j--;
+            const prev = j >= 0 ? src[j] : "";
+            // The COMPLETE identifier before the slash (scan across [\w$]) — only an
+            // exact keyword counts; after any other identifier, `/` is division.
+            let tokenStart = j;
+            while (tokenStart >= 0 && /[\w$]/.test(src[tokenStart]))
+                tokenStart--;
+            const prevToken = /[\w$]/.test(prev)
+                ? src.slice(tokenStart + 1, j + 1)
+                : "";
+            const regexStart = j < 0 ||
+                REGEX_MAY_FOLLOW.has(prev) ||
+                KEYWORDS_BEFORE_REGEX.has(prevToken);
+            if (regexStart) {
+                // Scan to the closing unescaped `/` (a `/` inside [...] doesn't close).
+                let k = i + 1;
+                let inClass = false;
+                let closed = false;
+                while (k < n && src[k] !== "\n") {
+                    const ck = src[k];
+                    if (ck === "\\") {
+                        k += 2;
+                        continue;
+                    }
+                    if (ck === "[")
+                        inClass = true;
+                    else if (ck === "]")
+                        inClass = false;
+                    else if (ck === "/" && !inClass) {
+                        closed = true;
+                        break;
+                    }
+                    k++;
+                }
+                if (closed) {
+                    for (let b = i; b <= k; b++)
+                        out[b] = " ";
+                    i = k + 1;
+                    continue;
+                }
+            }
+        }
+        i++;
+    }
+    return out.join("");
+}

package/build/utils/assertion-verify/lint-types.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Shared types and text helpers for the per-test-type deterministic lints
+ * (ui-lints.ts, integration-lints.ts, contract-lints.ts). Each lint mirrors a
+ * dim of the eval D5 assertion-depth rubric; only near-zero-false-positive
+ * rules are `hard` (they block the verify pass), everything a legitimate spec
+ * could trip ships as `warn` until run evidence justifies promotion.
+ */
+export interface LintFinding {
+    rule: string;
+    severity: "hard" | "warn";
+    /** 1-indexed line, when the finding anchors to one. */
+    line?: number;
+    message: string;
+    remediation: string;
+}
+export interface LintOptions {
+    /** Maintenance scope: line numbers of assertion sites ADDED since the baseline.
+     *  When set, site-scoped lints only report findings on these lines and
+     *  structural (whole-file) lints — including the import lint — are skipped:
+     *  they would flag pre-existing customer code the agent was told not to touch. */
+    scopeLines?: Set<number>;
+}
+export declare function lineOfOffset(src: string, offset: number): number;
+/** `\b` breaks on `$`-names, so identifier boundaries use lookarounds. Single
+ *  home for the pattern — it is subtle enough that hand-inlined copies drifted
+ *  (found by the /simplify pass: six sites, one missing the f-string branch). */
+export declare function identifierRe(name: string, flags?: string): RegExp;
+/** A use of `name` inside a string interpolation — js/ts `${...}` or python
+ *  f-string `{...}`. Interpolations are blanked wholesale by the string
+ *  strippers, so callers test this against COMMENT-stripped source. */
+export declare function interpolationRe(name: string, language: string): RegExp;
+export declare function balancedCloseIndex(stripped: string, openIdx: number): number;
+export declare function inScope(line: number, opts?: LintOptions): boolean;

package/build/utils/assertion-verify/lint-types.js

@@ -0,0 +1,57 @@
+import { escapeRegExp } from "../regex.js";
+// One-entry memo of a source's newline offsets: every scanner asks for line
+// numbers of many offsets in the SAME string (assertion sites, lint findings),
+// so counting newlines from index 0 per call was O(n × sites). The memo is
+// per-string; a new source replaces it.
+let newlineIndexSrc;
+let newlineIndex = [];
+export function lineOfOffset(src, offset) {
+    if (src !== newlineIndexSrc) {
+        newlineIndexSrc = src;
+        newlineIndex = [];
+        for (let i = 0; i < src.length; i++) {
+            if (src[i] === "\n")
+                newlineIndex.push(i);
+        }
+    }
+    // Binary search: number of newlines strictly before `offset`, plus 1.
+    let lo = 0;
+    let hi = newlineIndex.length;
+    while (lo < hi) {
+        const mid = (lo + hi) >> 1;
+        if (newlineIndex[mid] < offset)
+            lo = mid + 1;
+        else
+            hi = mid;
+    }
+    return lo + 1;
+}
+/** `\b` breaks on `$`-names, so identifier boundaries use lookarounds. Single
+ *  home for the pattern — it is subtle enough that hand-inlined copies drifted
+ *  (found by the /simplify pass: six sites, one missing the f-string branch). */
+export function identifierRe(name, flags = "") {
+    return new RegExp(`(?<![\\w$])${escapeRegExp(name)}(?![\\w$])`, flags);
+}
+/** A use of `name` inside a string interpolation — js/ts `${...}` or python
+ *  f-string `{...}`. Interpolations are blanked wholesale by the string
+ *  strippers, so callers test this against COMMENT-stripped source. */
+export function interpolationRe(name, language) {
+    const open = language === "python" ? "\\{" : "\\$\\{";
+    return new RegExp(`${open}[^}]*(?<![\\w$])${escapeRegExp(name)}(?![\\w$])`);
+}
+export function balancedCloseIndex(stripped, openIdx) {
+    let depth = 0;
+    for (let i = openIdx; i < stripped.length; i++) {
+        if (stripped[i] === "(")
+            depth++;
+        else if (stripped[i] === ")") {
+            depth--;
+            if (depth === 0)
+                return i;
+        }
+    }
+    return -1;
+}
+export function inScope(line, opts) {
+    return opts?.scopeLines === undefined || opts.scopeLines.has(line);
+}