@skyramp/mcp 0.3.6 → 0.3.8

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);
+}

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

@@ -0,0 +1,27 @@
+import type { AssertionLanguage } from "./metrics.js";
+/**
+ * The documented-decline escape hatch for the assertion verify pass, mirroring
+ * the `// kept inline:` marker discipline (reuse-outcome.ts): a spec whose
+ * generated assertions genuinely need no strengthening carries
+ *
+ *   // assertions complete: <test-file basename> — <reason>     (TS/JS/Java)
+ *   # assertions complete: <test-file basename> — <reason>      (Python)
+ *
+ * It clears ONLY the strength-family gates (strength-must-increase and
+ * weak-additions-only) — never a removal, a hard lint, or the hash gate: a
+ * marker that excused removals would excuse gutting the file. The reason is
+ * PR-reviewable in the diff.
+ */
+/** The comment token that makes the marker a REAL comment in this language —
+ *  a `//` marker in a .py file is a syntax error, so accepting it would go
+ *  green on a file that no longer parses. */
+export declare function markerCommentToken(language: AssertionLanguage): string;
+/** The well-formed marker naming this test file, or undefined. */
+export declare function findAssertionsCompleteMarker(content: string, testFile: string, language: AssertionLanguage): {
+    reason: string;
+} | undefined;
+/** Lines announcing an `assertions complete` decline that markerRe cannot read
+ *  (missing reason, unspaced hyphen, unedited placeholder, wrong comment token
+ *  for the language). Reported as their own verify failure with the corrected
+ *  format, so the decline is never lost. */
+export declare function findUnparsableAssertionsComplete(content: string, language: AssertionLanguage): string[];

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

@@ -0,0 +1,61 @@
+import * as path from "path";
+import { strippedSources } from "./strip-dispatch.js";
+/**
+ * The documented-decline escape hatch for the assertion verify pass, mirroring
+ * the `// kept inline:` marker discipline (reuse-outcome.ts): a spec whose
+ * generated assertions genuinely need no strengthening carries
+ *
+ *   // assertions complete: <test-file basename> — <reason>     (TS/JS/Java)
+ *   # assertions complete: <test-file basename> — <reason>      (Python)
+ *
+ * It clears ONLY the strength-family gates (strength-must-increase and
+ * weak-additions-only) — never a removal, a hard lint, or the hash gate: a
+ * marker that excused removals would excuse gutting the file. The reason is
+ * PR-reviewable in the diff.
+ */
+/** The comment token that makes the marker a REAL comment in this language —
+ *  a `//` marker in a .py file is a syntax error, so accepting it would go
+ *  green on a file that no longer parses. */
+export function markerCommentToken(language) {
+    return language === "python" ? "#" : "//";
+}
+/** Separator must be an em/en dash or a *spaced* hyphen — same decidability
+ *  reasoning as KEPT_INLINE_RE. `(?!\s*<reason)` rejects the paste-ready
+ *  placeholder from the failure text pasted unedited. */
+function markerRe(language) {
+    return new RegExp(`${markerCommentToken(language)}\\s*assertions complete:\\s*(\\S.*?)\\s*(?:[—–]+|\\s+-+\\s+)(?!\\s*<reason)\\s*(\\S.*?)\\s*$`);
+}
+/** Looser than markerRe so a malformed marker is detectable, never silently
+ *  lost — including a marker written with the WRONG language's comment token. */
+const MARKER_LOOSE_RE = /(?:\/\/|#)\s*assertions complete:/;
+/** Comment lines only — a marker quoted inside a string literal is not a marker. */
+function commentLines(content, language) {
+    return strippedSources(content, language).stringless.split("\n");
+}
+/** Basename or extension-less stem — same leniency as `isKeptInlineDocumented`. */
+function namesTestFile(named, testFile) {
+    const base = path.basename(testFile);
+    const stem = base.slice(0, base.length - path.extname(base).length);
+    const cleaned = path.basename(named.trim());
+    return cleaned === base || cleaned === stem;
+}
+/** The well-formed marker naming this test file, or undefined. */
+export function findAssertionsCompleteMarker(content, testFile, language) {
+    const re = markerRe(language);
+    for (const line of commentLines(content, language)) {
+        const m = re.exec(line);
+        if (m && namesTestFile(m[1], testFile))
+            return { reason: m[2].trim() };
+    }
+    return undefined;
+}
+/** Lines announcing an `assertions complete` decline that markerRe cannot read
+ *  (missing reason, unspaced hyphen, unedited placeholder, wrong comment token
+ *  for the language). Reported as their own verify failure with the corrected
+ *  format, so the decline is never lost. */
+export function findUnparsableAssertionsComplete(content, language) {
+    const re = markerRe(language);
+    return commentLines(content, language)
+        .filter((line) => MARKER_LOOSE_RE.test(line) && !re.test(line))
+        .map((line) => line.trim());
+}

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

@@ -0,0 +1,30 @@
+import type { ProgrammingLanguage } from "../../types/TestTypes.js";
+export type AssertionLanguage = `${ProgrammingLanguage}`;
+/** One assertion call/statement site. Multi-line chains count once. */
+export interface AssertionSite {
+    /** 1-indexed line of the site's first character. */
+    line: number;
+    /** Matcher name for expect-chains (`toHaveText`, `to_be`), undefined for bare asserts. */
+    matcher?: string;
+    weight: number;
+    fingerprint: string;
+}
+export interface AssertionMetrics {
+    count: number;
+    strengthScore: number;
+    /** Whitespace-collapsed statement texts, 120-char cap, ≤500 — the multiset used
+     *  to scope maintenance-mode checks to assertions added since the baseline. */
+    fingerprints: string[];
+    sites: AssertionSite[];
+}
+export declare function detectAssertionLanguage(testFile: string): AssertionLanguage | undefined;
+/**
+ * The assertion's SUBJECT — what it asserts about — recovered from a fingerprint
+ * (`expect(SUBJECT).matcher(...)` arg, or a python assert's left-hand side).
+ * Correlating subjects across baseline and current fingerprints is what tells a
+ * REPLACED assertion (subject still asserted, usually more strongly) from a
+ * REMOVED one (subject lost all coverage). Undefined when unrecoverable (e.g.
+ * truncated fingerprint) — callers treat that conservatively.
+ */
+export declare function subjectOf(fingerprint: string): string | undefined;
+export declare function computeAssertionMetrics(content: string, language: AssertionLanguage): AssertionMetrics;