@skyramp/mcp 0.4.1 → 0.4.2-rc.2

package/build/utils/utils-verify/action-key.js

@@ -34,55 +34,104 @@ const TARGET_ARG = new Set(["goto", "dragTo"]);
  * helper in either language gets the same key.
  */
 export function actionKeyOf(body, language = "typescript") {
+    return actionStepKeys(actionStepsOf(body, language))?.join("; ");
+}
+/** 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 function actionStepKeys(steps) {
+    if (steps.length === 0 || steps.some((s) => s.key === undefined))
+        return undefined;
+    return steps.map((s) => s.key);
+}
+/**
+ * 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 function actionStepsOf(body, language = "typescript") {
     const src = resolveLocatorAliases(language === "python" ? toPlaywrightJs(body) : body);
     // Structure is read on a copy with string CONTENTS blanked (same length), so a
-    // `)` or `.` inside a literal never ends a chain; text is taken from the original.
+    // `)` or `.` inside a literal never ends a chain, and a `.click(` written inside
+    // a string is not an action; text is taken from the original.
     const structure = blankStringContents(src);
     const steps = [];
-    for (const m of src.matchAll(ACTION_RE)) {
+    let prevEnd = 0;
+    for (const m of structure.matchAll(ACTION_RE)) {
         const verb = m[1];
         const dot = m.index;
+        const line = src.slice(0, dot).split("\n").length;
         const argsOpen = dot + m[0].length - 1;
         const argsClose = matchingClose(structure, argsOpen);
-        if (argsClose === -1)
-            return undefined;
         const chainStart = chainStartBefore(structure, dot);
-        let chain = src.slice(chainStart, dot);
-        const args = src.slice(argsOpen + 1, argsClose);
-        let target = "";
-        if (!/\(/.test(structure.slice(chainStart, dot))) {
-            // No locator call in the chain: the legacy `page.click("#save")` form, whose
-            // first argument is the selector; or `page.goto(url)`.
-            target = firstArgument(structure, src, argsOpen + 1, argsClose);
-            if (!target)
-                return undefined;
-        }
-        else if (TARGET_ARG.has(verb))
-            target = args;
-        if (verb === "goto") {
-            chain = "";
-            // A template target is keyed on its text, `${…}` included: generated helpers
-            // prefix every path with one module constant (`${baseUrl}/login`), and
-            // `/orders/${id}` is one page whatever the id. A bare variable is not a
-            // target this can read.
-            if (/^\s*`/.test(target))
-                target = "`" + target.trim().slice(1, -1) + "`";
-            else if (!/^\s*["']/.test(target))
-                return undefined;
+        const gapBefore = steps.length === 0 ? "" : src.slice(prevEnd, chainStart);
+        // An action inside another action's arguments: its chain starts before the
+        // previous action ended, so there is no gap to judge and no run to join.
+        if (argsClose === -1 || chainStart < prevEnd) {
+            steps.push({ line, gapBefore, gapAfter: "" });
+            prevEnd = argsOpen + 1;
+            continue;
         }
-        if (hasDynamicSelector(chain) || hasDynamicSelector(target))
+        prevEnd = argsClose + 1;
+        steps.push({
+            line,
+            gapBefore,
+            gapAfter: "",
+            key: stepKey(verb, src, structure, chainStart, dot, argsOpen, argsClose),
+        });
+    }
+    for (let i = 0; i < steps.length; i++)
+        steps[i].gapAfter =
+            i + 1 < steps.length ? steps[i + 1].gapBefore : src.slice(prevEnd);
+    return steps;
+}
+/** The key of one action, or `undefined` when its locator or target is unreadable. */
+function stepKey(verb, src, structure, chainStart, dot, argsOpen, argsClose) {
+    let chain = src.slice(chainStart, dot);
+    const args = src.slice(argsOpen + 1, argsClose);
+    let target = "";
+    if (!/\(/.test(structure.slice(chainStart, dot))) {
+        // No locator call in the chain: the legacy `page.click("#save")` form, whose
+        // first argument is the selector; or `page.goto(url)`.
+        target = firstArgument(structure, src, argsOpen + 1, argsClose);
+        if (!target)
             return undefined;
-        if (!/["'`]/.test(chain) && !/["'`]/.test(target))
+    }
+    else if (TARGET_ARG.has(verb))
+        target = args;
+    if (verb === "goto") {
+        chain = "";
+        // A template target is keyed on its text, `${…}` included: generated helpers
+        // prefix every path with one module constant (`${baseUrl}/login`), and
+        // `/orders/${id}` is one page whatever the id. A bare variable is not a
+        // target this can read.
+        if (/^\s*`/.test(target))
+            target = "`" + target.trim().slice(1, -1) + "`";
+        else if (!/^\s*["']/.test(target))
             return undefined;
-        const step = [verb, normalize(chain), normalize(target)]
-            .filter(Boolean)
-            .join(" ");
-        steps.push(step);
     }
-    return steps.length > 0 ? steps.join("; ") : undefined;
+    if (hasDynamicSelector(chain) || hasDynamicSelector(target))
+        return undefined;
+    if (!/["'`]/.test(chain) && !/["'`]/.test(target))
+        return undefined;
+    return [verb, normalize(chain), normalize(target)].filter(Boolean).join(" ");
+}
+/** `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 function describeActionKey(key) {
+    return key
+        .split("; ")
+        .map((step) => {
+        const at = step.indexOf(" ");
+        return `${step.slice(0, at)} \`${step.slice(at + 1)}\``;
+    })
+        .join("; ");
 }
 /** Index of the `)` that closes the `(` at `open`, on a string-blanked copy. */
-function matchingClose(structure, open) {
+export function matchingClose(structure, open) {
     let depth = 0;
     for (let i = open; i < structure.length; i++) {
         const ch = structure[i];
@@ -170,7 +219,11 @@ function hasDynamicSelector(text) {
                 return true;
     return false;
 }
-/** Whitespace and braces dropped outside string literals, `'` normalised to `"`. */
+/** Whitespace and braces dropped outside string literals, `'` normalised to `"` —
+ *  the spelling a locator chain has inside a key. */
+export function normalizeChain(text) {
+    return normalize(text);
+}
 function normalize(text) {
     let out = "";
     let quote = null;
@@ -201,7 +254,7 @@ function normalize(text) {
     return out.replace(/,(?=[)\]])/g, "");
 }
 /** String contents replaced by spaces, delimiters kept, same length. */
-function blankStringContents(text) {
+export function blankStringContents(text) {
     return text.replace(/(["'`])(?:\\.|(?!\1)[^\\])*\1/g, (q) => q[0] + " ".repeat(Math.max(0, q.length - 2)) + q[0]);
 }
 /** Playwright for Python spells the same API in snake_case, passes locator options
@@ -243,7 +296,12 @@ function toPlaywrightJs(body) {
  *  semicolons, to the end of its `.`-continued lines — so a Prettier-wrapped chain
  *  is kept whole. A name bound more than once (`for (const row of rows)`), reassigned
  *  (`t = page.…`), or used as a parameter is ambiguous and is left alone; a variable
- *  receiver is unreadable. */
+ *  receiver is unreadable.
+ *
+ *  Deliberately file-wide when the sibling scan hands it a whole spec: a name bound
+ *  in two `test()` blocks is then ambiguous and its steps lose their key, and the
+ *  final substitution runs on raw text, so an alias name inside a selector string
+ *  is rewritten too. Both only ever lose a match, never invent one. */
 function resolveLocatorAliases(body) {
     const structure = blankStringContents(body);
     const aliases = new Map();
@@ -251,7 +309,13 @@ function resolveLocatorAliases(body) {
         const name = m[1];
         const from = m.index + m[0].length;
         const to = valueEnd(structure, from);
-        aliases.set(name, body.slice(from, to).trim().replace(/;$/, ""));
+        // Joined onto one line: the substitution must not move the lines of the
+        // actions after it (actionStepsOf reports each action's line).
+        aliases.set(name, body
+            .slice(from, to)
+            .trim()
+            .replace(/;$/, "")
+            .replace(/\s*\n\s*/g, " "));
     }
     for (const name of [...aliases.keys()]) {
         const esc = name.replace(/\$/g, "\\$");
@@ -271,6 +335,24 @@ function resolveLocatorAliases(body) {
         return body;
     return body.replace(/(?<![\w$.])([A-Za-z_$][\w$]*)(?=\s*\.)/g, (id) => aliases.get(id) ?? id);
 }
+/** 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 function statementSpans(structure) {
+    const out = [];
+    let i = 0;
+    while (i < structure.length) {
+        while (i < structure.length && /[\s;]/.test(structure[i]))
+            i++;
+        if (i >= structure.length)
+            break;
+        const end = valueEnd(structure, i);
+        out.push([i, end]);
+        i = end + 1;
+    }
+    return out;
+}
 /** End of an initialiser that starts at `from`: the `;` at paren depth 0, or a
  *  newline at depth 0 whose next line does not continue the chain with `.`. */
 function valueEnd(structure, from) {

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

@@ -0,0 +1,32 @@
+import { type UtilsHelper } from "./parse.js";
+import { type UtilsLanguageSpec } from "./language-spec.js";
+import { type InlineCallSite, type SiblingFile } from "./call-sites.js";
+/**
+ * The browser family's sibling scan: a contiguous run of actions in OTHER
+ * Skyramp-generated tests beside `testFile` whose action sequence equals a utils
+ * helper's — the inline copy of a shared step (measured: three cohorts in a row, a
+ * run created the helper, rewired the two copies it happened to read and left the
+ * third, naming it in its own report).
+ *
+ * A browser step is a SEQUENCE, so the match is a sequence match: each helper's key
+ * (verb + locator chain per action, in body order — the same key STEP 3b matches a
+ * customer's helper on) is looked for as a run of consecutive actions in the
+ * sibling. Two things stand between "consecutive" and "one call can replace it":
+ *
+ *  - **What sits between two actions of the run.** A structural wait (a presence
+ *    matcher on a structural locator, a `waitFor…`), a fixed sleep or a comment is
+ *    transparent — the helper's own body may hold the same, and the key ignores it
+ *    either way. ANYTHING ELSE breaks the run: a value assertion (it cannot move
+ *    across an action — the reuse policy's own boundary rule), a page-error guard,
+ *    another call, a binding, or the end of the block the run started in. The test
+ *    the gap is held to is the one the verify pass holds a helper body to, so a run
+ *    is matched only where a helper could have held every line of it.
+ *  - **A step this cannot read.** A helper whose key is undefined is no candidate;
+ *    a sibling action with an undefined key equals nothing, so no run crosses it.
+ *    Both fail open — no match, no finding — as STEP 3b's decline rule does.
+ *
+ * Where two helpers' keys start the same run, the longer wins; the run's actions are
+ * consumed and the scan continues after it. A run inside the sibling's own local
+ * helper is reported with that helper's name, as the API scan does.
+ */
+export declare function findSiblingInlineActionSites(testFile: string, helpersByFile: ReadonlyMap<string, UtilsHelper[]>, spec: UtilsLanguageSpec, preReadSiblings: SiblingFile[] | undefined): Promise<InlineCallSite[]>;

package/build/utils/utils-verify/action-sites.js

@@ -0,0 +1,202 @@
+import * as path from "path";
+import { blankComments, localHelperAt, localHelpersOf, } from "./parse.js";
+import { expectArgs, HELPER_FAMILIES, } from "./language-spec.js";
+import { actionStepsOf, blankStringContents, normalizeChain, statementSpans, } from "./action-key.js";
+import { realpath } from "./locate.js";
+import { nonUtilsSiblings, } from "./call-sites.js";
+/** A presence assertion as `[normalised locator, matcher]`, or undefined when the
+ *  text is not one this can read. */
+function presenceWait(text, spec) {
+    if (!spec.assertionRe.test(text))
+        return undefined;
+    const matcher = /\)\s*\.\s*((?:not[._]\s*)?to\w+)\s*\(/.exec(text);
+    if (!matcher)
+        return undefined;
+    return [normalizeChain(expectArgs(text)), matcher[1].replace(/\s+/g, "")];
+}
+/**
+ * The browser family's sibling scan: a contiguous run of actions in OTHER
+ * Skyramp-generated tests beside `testFile` whose action sequence equals a utils
+ * helper's — the inline copy of a shared step (measured: three cohorts in a row, a
+ * run created the helper, rewired the two copies it happened to read and left the
+ * third, naming it in its own report).
+ *
+ * A browser step is a SEQUENCE, so the match is a sequence match: each helper's key
+ * (verb + locator chain per action, in body order — the same key STEP 3b matches a
+ * customer's helper on) is looked for as a run of consecutive actions in the
+ * sibling. Two things stand between "consecutive" and "one call can replace it":
+ *
+ *  - **What sits between two actions of the run.** A structural wait (a presence
+ *    matcher on a structural locator, a `waitFor…`), a fixed sleep or a comment is
+ *    transparent — the helper's own body may hold the same, and the key ignores it
+ *    either way. ANYTHING ELSE breaks the run: a value assertion (it cannot move
+ *    across an action — the reuse policy's own boundary rule), a page-error guard,
+ *    another call, a binding, or the end of the block the run started in. The test
+ *    the gap is held to is the one the verify pass holds a helper body to, so a run
+ *    is matched only where a helper could have held every line of it.
+ *  - **A step this cannot read.** A helper whose key is undefined is no candidate;
+ *    a sibling action with an undefined key equals nothing, so no run crosses it.
+ *    Both fail open — no match, no finding — as STEP 3b's decline rule does.
+ *
+ * Where two helpers' keys start the same run, the longer wins; the run's actions are
+ * consumed and the scan continues after it. A run inside the sibling's own local
+ * helper is reported with that helper's name, as the API scan does.
+ */
+export async function findSiblingInlineActionSites(testFile, helpersByFile, spec, preReadSiblings) {
+    const sequences = helperSequences(helpersByFile, spec);
+    if (sequences.length === 0)
+        return [];
+    const siblings = await nonUtilsSiblings(testFile, [...helpersByFile.keys()], spec, preReadSiblings, false);
+    const self = await realpath(testFile);
+    const out = [];
+    for (const { file, content } of siblings) {
+        if (path.resolve(file) === self)
+            continue;
+        const localHelpers = localHelpersOf(content, spec);
+        // Comments blanked, strings kept — the same reading the helper's key was made
+        // from, so a commented-out click is not a step and the selectors compare.
+        const steps = actionStepsOf(blankComments(content, spec), spec.language);
+        let i = 0;
+        while (i < steps.length) {
+            const match = sequences.find((s) => runMatches(steps, i, s, spec));
+            if (!match) {
+                i++;
+                continue;
+            }
+            const first = steps[i];
+            const last = steps[i + match.steps.length - 1];
+            const owner = localHelperAt(localHelpers, first.line);
+            out.push({
+                kind: "sequence",
+                file,
+                line: first.line,
+                endLine: last.line,
+                actionKey: match.key,
+                helper: match.helper,
+                utilsFile: match.utilsFile,
+                ...(owner ? { localHelper: owner.name } : {}),
+            });
+            i += match.steps.length;
+        }
+    }
+    return out;
+}
+/** Whether the helper's sequence is the run of actions starting at `at`, with
+ *  nothing between its actions that a helper body could not hold, and no wait in
+ *  or right after the run that contradicts one of the helper's own. */
+function runMatches(steps, at, helper, spec) {
+    const want = helper.steps;
+    if (at + want.length > steps.length)
+        return false;
+    for (let k = 0; k < want.length; k++) {
+        const step = steps[at + k];
+        if (step.key === undefined || step.key !== want[k])
+            return false;
+        if (k > 0) {
+            const between = transparentStatements(step.gapBefore, spec);
+            if (between === undefined)
+                return false;
+            if (contradictsWaits(between, helper.waits, spec))
+                return false;
+        }
+    }
+    // The structural waits that follow the last action are the run's too: a wait the
+    // helper would perform, or its opposite.
+    const trailing = transparentStatements(steps[at + want.length - 1].gapAfter, spec, { prefix: true });
+    return !contradictsWaits(trailing ?? [], helper.waits, spec);
+}
+/** Whether one of `statements` asserts an element the helper waits on with a
+ *  different matcher or negation. */
+function contradictsWaits(statements, waits, spec) {
+    for (const s of statements) {
+        const wait = presenceWait(s.replace(/^await\s+/, ""), spec);
+        if (!wait)
+            continue;
+        const held = waits.get(wait[0]);
+        if (held !== undefined && held !== wait[1])
+            return true;
+    }
+    return false;
+}
+/**
+ * The statements of `gap` that a shared browser helper may hold — a permitted
+ * structural wait, as the verify pass judges one (`HELPER_FAMILIES.browser`), or a
+ * `waitFor…` — or `undefined` when one is not, or when the gap closes a bracket it
+ * did not open. With `prefix`, the leading transparent statements up to the first
+ * that is not: the waits that follow a run, read until the run's own text ends.
+ * Statements are cut as statementSpans cuts them, on a string-blanked copy, so a
+ * `;` inside a literal is not a boundary and a Prettier-wrapped chain is one
+ * statement. Conservative: an unfamiliar statement ends the run.
+ */
+function transparentStatements(gap, spec, opts = {}) {
+    const structure = blankStringContents(gap);
+    if (!opts.prefix && leavesBlock(structure))
+        return undefined;
+    const out = [];
+    for (const [from, to] of statementSpans(structure)) {
+        const text = gap.slice(from, to).trim();
+        // The `await` that precedes the next action's chain.
+        if (text === "await")
+            continue;
+        const body = text.replace(/^await\s+/, "");
+        const transparent = WAIT_STATEMENT_RE.test(blankStringContents(body)) ||
+            (spec.assertionRe.test(body) &&
+                HELPER_FAMILIES.browser.isAllowed(spec, body));
+        if (!transparent)
+            return opts.prefix ? out : undefined;
+        out.push(text);
+    }
+    return out;
+}
+/** A closing bracket the fragment did not open: the run leaves its block. */
+function leavesBlock(structure) {
+    let depth = 0;
+    for (const ch of structure) {
+        if ("([{".includes(ch))
+            depth++;
+        else if (")]}".includes(ch) && --depth < 0)
+            return true;
+    }
+    return false;
+}
+/** `page.waitForTimeout(3000)`, `page.waitForLoadState()`, `page.getByTestId("x")
+ *  .waitFor({ state: "visible" })` — a wait on the page or on a locator chain, as a
+ *  statement of its own (not bound: `const p = page.waitForResponse(…)` is used
+ *  later, and the run cannot carry it). */
+const WAIT_STATEMENT_RE = /^(?:this\.)?page(?:\s*\.\s*[\w$]+\s*\([^;]*\))*\s*\.\s*(?:waitFor\w*|wait_for\w*)\s*\([^;]*\)\s*$/;
+/** A step whose receiver is the keyboard or the mouse rather than a locator. */
+function isElementlessStep(step) {
+    return /^\w+ (?:this\.)?page\.(?:keyboard|mouse)(?:\s|$)/.test(step);
+}
+/** Every keyed browser helper across the utils files, in file then body order, from
+ *  the helpers the verify pass already parsed. The first helper to carry a key owns
+ *  it; a second (the `duplicate-action` advisory's case) is not reported twice. */
+function helperSequences(helpersByFile, spec) {
+    const out = [];
+    const seen = new Set();
+    for (const [utilsFile, helpers] of helpersByFile)
+        for (const h of helpers) {
+            if (!h.actionKey || !h.actionSteps || seen.has(h.actionKey))
+                continue;
+            // A key of bare keyboard or mouse steps names no element: `press "Escape"`
+            // is what closes a dialog in one helper and a menu in the next, and every
+            // Escape in every sibling matched it (measured: fixture 22, the advisory
+            // named a menu close for a dialog-closing helper). One locator-bearing step
+            // is enough to identify the sequence.
+            if (h.actionKey.split("; ").every(isElementlessStep))
+                continue;
+            seen.add(h.actionKey);
+            out.push({
+                helper: h.name,
+                utilsFile,
+                key: h.actionKey,
+                steps: h.actionSteps,
+                waits: new Map(h.assertions
+                    .map((a) => presenceWait(a.text, spec))
+                    .filter((w) => w !== undefined)),
+            });
+        }
+    // Longest first, so the run a longer sequence covers is not claimed by a shorter
+    // helper that shares its opening actions.
+    return out.sort((a, b) => b.steps.length - a.steps.length);
+}

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

@@ -15,13 +15,68 @@ export type UtilsViolationKind = "duplicate-helper" | "body-assertion" | "scenar
 /** Python only: the spec imports the shared module in a form that cannot resolve
  *  in the customer's repo. Not marker-eligible — a broken import has no reason to
  *  stay. */
- | "import-form";
+ | "import-form"
+/** A `reuse-verify: allow` marker that no finding of this pass consumes. The
+ *  decline it documents is not in the delivered files: either it never was, or the
+ *  agent went on to fix the fault and left the marker behind, so the file states a
+ *  reason its own code contradicts. Not marker-eligible — a marker that documents
+ *  nothing is deleted, and documenting it would only add a second one. */
+ | "stale-allow"
+/** A shared helper whose request body no parameter of its signature reaches, beside
+ *  a spec that defines its OWN helper for the same route. The pair is the fault: a
+ *  body the helper holds is the right default while one caller exists, and becomes
+ *  wrong the moment a second caller needs another. Marker-eligible — a caller that
+ *  genuinely needs a different REQUEST, not a different body, is a decline worth
+ *  documenting rather than a shape to force. */
+ | "frozen-body"
+/** A shared helper's expected-status parameter — the one its status assertion
+ *  reads — carries a default (or is optional). A call site may then omit the
+ *  status it expects, and the spec states its expectation nowhere a reader can
+ *  see it; a helper named for the happy path defaulting to a rejection reads as
+ *  a bug on sight. Keyed on what the assertion READS, not on the parameter's
+ *  name, which diverges between runs. Marker-eligible. Routed to `advisories`
+ *  for now — see the classification pass in verify.ts. */
+ | "status-default"
+/** The spec asserts the status of a response returned by a helper that already
+ *  asserted it — the same literal stated twice, and the two can disagree. The
+ *  expectation is stated once, as the call's status argument. Marker-eligible. */
+ | "status-restated"
+/** A helper defined at HEAD whose parameter list this run narrowed — a default
+ *  removed, a parameter renamed, removed or reordered, or a required one added.
+ *  Callers this run cannot see depend on the signature at HEAD. Not
+ *  marker-eligible: an incumbent is restored, not documented away. See incumbent.ts. */
+ | "incumbent-signature"
+/** TypeScript only: the delivered module or spec fails the compiler under its most
+ *  permissive settings — an error under EVERY configuration, so the customer's own
+ *  `tsc` is the next thing to report it (the executor transpiles without checking
+ *  types). Not marker-eligible: a file that cannot compile has no reason to stay
+ *  as it is. An error that exists only under the repository's tsconfig is the
+ *  `tsconfig-type-error` ADVISORY instead. */
+ | "type-error"
+/** The spec imports a name from one of the repository's own modules that the
+ *  module does not define. Not marker-eligible: the marker grammar lives in a
+ *  Skyramp module, and nothing of ours is written into the customer's file. */
+ | "in-house-unresolved"
+/** A call to an in-house helper passes an argument count outside the range its
+ *  definition accepts (required count to total count). Not marker-eligible. */
+ | "in-house-arity"
+/** This run changed an in-house module in a way that is not additive: a helper
+ *  removed, renamed or rewritten, a parameter added without a default, a line
+ *  outside every helper deleted. Not marker-eligible — the change is undone. */
+ | "in-house-modified"
+/** The spec imports a sibling module this pass cannot recognise: a file with no
+ *  Skyramp header that is not the repository's own (not at HEAD) — this run's
+ *  module written without its header — or an import that resolves to no file.
+ *  The pass cannot verify or stage what it cannot see, and a PASSED here was a
+ *  gate failing open (fixture 12, run 9). Not marker-eligible: the remedy is the
+ *  header line, or the path, both named in the finding. */
+ | "unresolved-module";
 /** Kinds that only ever advise. Kept OUT of UtilsViolationKind so that type keeps
  *  meaning "a kind the allow grammar and the gate know about" — an advisory can
  *  never fail a verify and never needs (or accepts) an allow marker. */
-export declare const UTILS_ADVISORY_KINDS: readonly ["untyped-parameter", "duplicate-action"];
+export declare const UTILS_ADVISORY_KINDS: readonly ["unusable-parameter-type", "fixed-sleep", "module-name", "duplicate-body-reach", "duplicate-action", "tsconfig-type-error", "ambient-type-error", "in-house-duplicate"];
 export type UtilsAdvisoryKind = (typeof UTILS_ADVISORY_KINDS)[number];
-export declare const MARKERABLE_UTILS_KINDS: readonly ["duplicate-helper", "body-assertion", "scenario-name", "assertion-loss"];
+export declare const MARKERABLE_UTILS_KINDS: readonly ["frozen-body", "duplicate-helper", "body-assertion", "scenario-name", "assertion-loss", "status-default", "status-restated"];
 /** A kind the allow grammar accepts. `guard-removed` is a gate kind but never
  *  markerable — a guard is restored, not documented away — so the grammar itself
  *  cannot spell it; the regex below is built from this list. */
@@ -30,9 +85,73 @@ export interface UtilsAllow {
     kind: MarkerableUtilsKind;
     helper: string;
     reason: string;
+    /** 1-based line the marker sits on — where a finding about the marker points. */
+    line: number;
 }
+/**
+ * The documented-decline marker for a utils-file invariant, written in the utils file:
+ *
+ *     # reuse-verify: allow <kind> <helper> — <reason>      (Python)
+ *     // reuse-verify: allow <kind> <helper> — <reason>     (TS/JS)
+ *
+ * ONE grammar, used by both the gate and the report. The POM path's `// kept inline:`
+ * marker had two — the gate's regex and the report parser disagreed on the separator
+ * and on the file extension — and the gap was a run where the gate blocked execution
+ * on declines the report listed correctly (mcp#716, run 30965653402). Here the gate
+ * and the report call this one function.
+ *
+ * The separator is an em/en dash or a hyphen with whitespace on BOTH sides, so a
+ * hyphen inside a helper name cannot be mistaken for it. `(?!<reason)` rejects the
+ * paste-ready line from the failure text when it was pasted unedited: publishing the
+ * placeholder as the stated reason is worse than no marker.
+ */
+export declare const ALLOW_RE: RegExp;
+/** Anything that announces a decline in this grammar, well-formed or not. Exported
+ *  so the delivery-time strip recognises the grammar from its one declaration here
+ *  rather than re-spelling it. */
+export declare const ALLOW_LOOSE_RE: RegExp;
+/** THIS grammar at the start of what a comment says. `reuse-verify: allow` is not a
+ *  phrase a customer writes, so an own-line comment opening with it is gate-addressed
+ *  whatever follows — the delivery strip removes it without being able to READ it.
+ *  `kept inline:` cannot claim that: it opens ordinary English too. */
+export declare const ALLOW_START_RE: RegExp;
+/** A marker's SHAPE, whatever kind it names: the announcement, then a subject, then
+ *  the separator and a reason. Ordinary prose that merely opens with the phrase — `//
+ *  kept inline: this loop is kept inline for performance` — carries no separator and
+ *  is not matched. Used where a line must be recognised as gate-addressed without the
+ *  grammar being able to READ it: an advisory kind is inert by design, so the verify
+ *  pass passes it and the comment would otherwise ship. */
+export declare const MARKER_SHAPE_RE: RegExp;
 /** The exact line to paste for a violation — what the failure text hands the agent. */
 export declare function allowMarkerLine(spec: UtilsLanguageSpec, kind: MarkerableUtilsKind, helper: string): string;
+/**
+ * The marker text, when the marker's comment OWNS its line: whitespace, the comment
+ * prefix, then the marker and nothing else.
+ *
+ * One placement, because it is the one both gates instruct and the only one that can
+ * be removed from a delivered file by deleting a line. A marker after code, inside a
+ * block comment or on a JSDoc continuation is reported as malformed instead — the
+ * decline is never dropped in silence, and the failure text gives back the line to
+ * paste in its place.
+ *
+ * A line whose first characters are the comment prefix cannot be a regex literal or a
+ * trailing comment, so this needs no lexer beyond the blanked strings. It cannot tell
+ * whether the prefix OPENS anything, though — inside `/* … *\/` a `//` opens nothing,
+ * the block does — so the caller settles that with `lineCommentOpeners` first. The
+ * parser asked the text while the strip asked the lexer, and a marker in a block
+ * comment was then read as a decline that the strip could not remove: the fault was
+ * authorised and the note shipped.
+ */
+export declare function markerOnOwnLine(raw: string, code: string, prefix: "//" | "#"): string | undefined;
+/**
+ * Line indices whose first non-space characters OPEN a line comment.
+ *
+ * `undefined` where the language has no block comment: every line with the prefix at
+ * its head opens one, and the caller needs no check. Stated ONCE, because the parser
+ * and the delivery strip must not disagree about which lines are comments — when they
+ * did, one authorised a decline the other refused to remove.
+ */
+export declare function lineCommentOpeners(content: string, prefix: "//" | "#"): Set<number> | undefined;
 export declare function parseUtilsAllows(content: string, spec: UtilsLanguageSpec): {
     allows: UtilsAllow[];
     /** Marker lines the loose pattern recognises but the grammar cannot read — a decline