@skyramp/mcp 0.4.0 → 0.4.1-rc.2

package/build/utils/utils-verify/parse.js

@@ -1,46 +1,82 @@
 import { normalizePath } from "./language-spec.js";
+import { actionKeyOf } from "./action-key.js";
 import { stripComments, stripCommentsAndStrings, stripStrings, } from "../pom-scope/strip.js";
-/** The parameter names in a TS signature that carry no `: type`. Reads the signature
- *  from the definition line to its `{` (Prettier wraps long signatures), takes the
- *  first balanced `(...)`, and splits it on top-level commas. */
-export function untypedParamsOf(sigLines) {
+/** Whether the `<` at `i` opens a generic (`Record<string, …>`, `Array<{…}>`) rather
+ *  than comparing (`i < 3`): a generic follows an identifier or `>` and is followed
+ *  by a type start; a comparison is followed by a number, a space and a value, or
+ *  an operator. */
+function opensGeneric(sig, i) {
+    let p = i - 1;
+    while (p >= 0 && /\s/.test(sig[p]))
+        p--;
+    if (p < 0 || !/[\w$>\]]/.test(sig[p]))
+        return false;
+    let n = i + 1;
+    while (n < sig.length && /\s/.test(sig[n]))
+        n++;
+    return /[A-Za-z_${[(]/.test(sig[n] ?? "");
+}
+/** Bracket depth tracker for a signature: `(`/`[`/`{` always nest; `<` nests only as
+ *  a generic and `>` closes only an open generic — never the `>` of `=>`, and never
+ *  a comparison in a default value (`qty = max > 0 ? max : 1`). */
+function bracketStep(sig, i, d) {
+    const ch = sig[i];
+    if ("([{".includes(ch))
+        d.depth++;
+    else if (")]}".includes(ch))
+        d.depth--;
+    else if (ch === "<" && opensGeneric(sig, i)) {
+        d.depth++;
+        d.angle++;
+    }
+    else if (ch === ">" && d.angle > 0 && sig[i - 1] !== "=") {
+        d.depth--;
+        d.angle--;
+    }
+}
+/** The declared parameters of a signature, raw text trimmed, empty entries dropped
+ *  (a trailing comma). Reads the signature from the definition line to its body
+ *  opener (Prettier wraps long signatures), takes the first balanced `(...)`, and
+ *  splits it on top-level commas — so a comma inside a default value, a generic, or
+ *  a binding pattern never splits. `undefined` when the text holds no readable
+ *  parameter list. Language-neutral: both a TS `{` and a Python `:` terminator lie
+ *  outside the parentheses this reads. */
+export function signatureParams(sigLines) {
     const sig = sigLines.join(" ");
-    const open = sig.indexOf("(");
+    // The parameter list's `(` is the first one outside a generic: a constraint may
+    // hold parentheses of its own (`<T extends (a: string) => void>(page, cb)`).
+    let open = -1;
+    const d = { depth: 0, angle: 0 };
+    for (let i = 0; i < sig.length; i++) {
+        if (sig[i] === "(" && d.angle === 0) {
+            open = i;
+            break;
+        }
+        bracketStep(sig, i, d);
+    }
     if (open === -1) {
-        // Bare-arrow form: `export const open = async page => …` — one parameter,
-        // untyped by construction (a typed single parameter requires parentheses).
+        // Bare-arrow form: `export const open = async page => …` — one parameter.
         const bare = /(?:^|=)\s*(?:async\s+)?([A-Za-z_$][\w$]*)\s*=>/.exec(sig);
-        return bare ? [bare[1]] : [];
+        return bare ? [bare[1]] : undefined;
     }
-    // `>` closes a nesting level only when it is not the arrow token's tail:
-    // `(callback: (x: string) => void, page)` must not close at `=>`.
-    const closes = (ch, prev) => ch === ")" || ch === "]" || ch === "}" || (ch === ">" && prev !== "=");
-    let depth = 0;
     let close = -1;
+    const c = { depth: 0, angle: 0 };
     for (let i = open; i < sig.length; i++) {
-        const ch = sig[i];
-        if ("([{<".includes(ch))
-            depth++;
-        else if (closes(ch, sig[i - 1] ?? "")) {
-            depth--;
-            if (depth === 0) {
-                close = i;
-                break;
-            }
+        bracketStep(sig, i, c);
+        if (c.depth === 0) {
+            close = i;
+            break;
         }
     }
     if (close === -1)
-        return [];
+        return undefined;
     const params = [];
     let cur = "";
-    depth = 0;
+    const e = { depth: 0, angle: 0 };
     for (let i = open + 1; i < close; i++) {
         const ch = sig[i];
-        if ("([{<".includes(ch))
-            depth++;
-        else if (closes(ch, sig[i - 1] ?? ""))
-            depth--;
-        if (ch === "," && depth === 0) {
+        bracketStep(sig, i, e);
+        if (ch === "," && e.depth === 0) {
             params.push(cur);
             cur = "";
         }
@@ -48,11 +84,17 @@ export function untypedParamsOf(sigLines) {
             cur += ch;
     }
     params.push(cur);
+    // Python's bare `*` and `/` are keyword-only / positional-only MARKERS, not
+    // parameters.
+    return params
+        .map((p) => p.trim())
+        .filter((p) => p !== "" && p !== "*" && p !== "/");
+}
+/** The parameter names in a TS signature that carry no `: type`. */
+export function untypedParamsOf(sigLines) {
     const out = [];
-    for (const raw of params) {
-        const param = raw.trim().replace(/^\.\.\./, "");
-        if (!param)
-            continue;
+    for (const raw of signatureParams(sigLines) ?? []) {
+        const param = raw.replace(/^\.\.\./, "");
         // A default value means TypeScript infers the type — not a finding, even
         // unannotated (`expectedStatus = 200`). `=>` inside a function-type
         // annotation is not a default.
@@ -62,17 +104,13 @@ export function untypedParamsOf(sigLines) {
         // `{ page: browserPage }` is implicitly any unless a `:` follows the
         // complete pattern.
         if (param.startsWith("{") || param.startsWith("[")) {
-            let d = 0;
+            const bd = { depth: 0, angle: 0 };
             let after = -1;
             for (let i = 0; i < param.length; i++) {
-                if ("([{<".includes(param[i]))
-                    d++;
-                else if (closes(param[i], param[i - 1] ?? "")) {
-                    d--;
-                    if (d === 0) {
-                        after = i + 1;
-                        break;
-                    }
+                bracketStep(param, i, bd);
+                if (bd.depth === 0) {
+                    after = i + 1;
+                    break;
                 }
             }
             if (after === -1 || !param.slice(after).trimStart().startsWith(":"))
@@ -103,6 +141,11 @@ export function untypedParamsOf(sigLines) {
  */
 export function parseUtilsFile(content, spec) {
     const lines = content.split("\n");
+    // Structure — where a body ends — is read on a copy with comments and string
+    // contents blanked (same line count and lengths): a `{` typed into a field
+    // (`fill("{")`) or a `#` in a Python string must not move a helper's end and
+    // swallow every helper after it.
+    const structure = blankCommentsAndStrings(content, spec).split("\n");
     const helpers = [];
     let i = 0;
     while (i < lines.length) {
@@ -114,13 +157,23 @@ export function parseUtilsFile(content, spec) {
         const name = m.slice(1).find((g) => g !== undefined) ?? "";
         const start = i;
         const end = spec.language === "python"
-            ? pythonBodyEnd(lines, start)
-            : braceBodyEnd(lines, start);
+            ? pythonBodyEnd(structure, start)
+            : braceBodyEnd(structure, start);
+        // A `typing.overload` stub declares a signature of the ONE function that follows
+        // it; it is not a second helper, and reading it as one would report the pair as
+        // a name collision.
+        if (spec.language === "python" && isOverloadStub(lines, start)) {
+            i = Math.max(end, start + 1);
+            continue;
+        }
         const body = lines.slice(start, end);
         // Scan a copy with comments and string contents blanked, so a commented-out
         // `path=` or an `expect(` inside a string never keys or flags anything; the
         // original line is what the agent is shown.
         const scan = blankCommentsAndStrings(body.join("\n"), spec).split("\n");
+        // The blanked copy: a comment inside a wrapped signature must not reach the
+        // agent as a "parameter", and a comma inside a default string must not split one.
+        const signature = signatureLines(scan);
         const helper = {
             name,
             line: start + 1,
@@ -128,11 +181,11 @@ export function parseUtilsFile(content, spec) {
             wrapsRequest: false,
             hasGuard: hasPageErrorGuard(body.join("\n"), spec),
             assertions: [],
-            untypedParams: spec.language === "typescript"
-                ? // The blanked copy: a comment inside a wrapped signature must not
-                    // reach the agent as a "parameter".
-                    untypedParamsOf(signatureLines(scan))
-                : [],
+            untypedParams: spec.language === "typescript" ? untypedParamsOf(signature) : [],
+            arity: signatureParams(signature)?.length,
+            // Comments blanked, strings kept: a commented-out click is not a step, and
+            // the selector literals are the key.
+            actionKey: actionKeyOf(blankComments(body.join("\n"), spec), spec.language),
         };
         let requests = 0;
         for (let k = 0; k < body.length; k++) {
@@ -198,8 +251,9 @@ function depthOf(code) {
             d--;
     return d;
 }
-/** True when the `path` value is a single string literal ending the argument. */
-function isSingleLiteral(line, m) {
+/** True when the `path` value is a single string literal ending the argument — a
+ *  concatenation (`"/api/orders/" + str(id) + "/items"`) has no route this can name. */
+export function isSingleLiteral(line, m) {
     const after = line.slice(m.index + m[0].length).replace(/^\s+/, "");
     return (after === "" ||
         after.startsWith(",") ||
@@ -299,13 +353,30 @@ function signatureLines(body) {
     }
     return out;
 }
+/** Whether the def at `start` carries `@overload` / `@typing.overload` anywhere in
+ *  its decorator stack (comments and other decorators may sit between). */
+function isOverloadStub(lines, start) {
+    // The decorator stack sits above the def with comments and blank lines allowed
+    // between; any `@overload` in that stack marks the def a stub.
+    for (let i = start - 1; i >= 0; i--) {
+        const l = lines[i].trim();
+        if (l === "" || l.startsWith("#"))
+            continue;
+        if (!l.startsWith("@"))
+            return false;
+        if (/^@(?:typing\.)?overload\b/.test(l))
+            return true;
+    }
+    return false;
+}
 /** Exclusive end index of a Python def starting at `start`: the next non-blank line at
- *  column 0 (a following def, import, or module statement). */
+ *  column 0 (a following def, import, or module statement). A column-0 `):` is the
+ *  close of a Black-wrapped signature, not a statement — it stays in the helper. */
 function pythonBodyEnd(lines, start) {
     let i = start + 1;
     while (i < lines.length) {
         const l = lines[i];
-        if (l.trim() !== "" && !/^\s/.test(l))
+        if (l.trim() !== "" && !/^[\s)]/.test(l))
             break;
         i++;
     }

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

@@ -1,4 +1,4 @@
-import { type InlineCallSite } from "./call-sites.js";
+import { type InlineCallSite, type UnextractedDuplicate } from "./call-sites.js";
 import { type UtilsAdvisoryKind, type UtilsViolationKind } from "./allow.js";
 import { type SingleImporterHelper } from "./importers.js";
 import { type HelperFamilySpec, type UtilsLanguageSpec } from "./language-spec.js";
@@ -27,6 +27,8 @@ export interface UtilsVerifyResult {
     helpers: number;
     /** Helper names the delivered spec imports from those files. */
     imported: number;
+    /** Those names, sorted — what the report row shows beside the count. */
+    importedNames: string[];
     violations: UtilsViolation[];
     /** Violations covered by a `reuse-verify: allow` marker — a documented decline. */
     allowed: UtilsViolation[];
@@ -47,9 +49,23 @@ export interface UtilsVerifyResult {
     /** Advisory (does not affect `ok`): inline request calls in sibling generated tests
      *  that a utils helper already wraps — see findSiblingInlineCallSites. API family only. */
     inlineCallSites: InlineCallSite[];
+    /** Advisory (does not affect `ok`): operations written in two or more sibling
+     *  generated tests (this one included) that NO utils helper wraps — the extraction
+     *  not performed, beside `inlineCallSites`' helper not used. See
+     *  findUnextractedDuplicates. API family only. */
+    unextractedDuplicates: UnextractedDuplicate[];
     /** Helpers imported by 0 or 1 delivered test (SKYR-4276 A6). Advisory: a first run
      *  seeds every helper single-use by design; the count is the trend to watch. */
     singleImporters: SingleImporterHelper[];
+    /** The numbers the baseline assertion check compared — present only when a
+     *  baseline was supplied and the spec was readable. The check is a COUNT: it
+     *  cannot see one assertion swapped for another. The caller's text says so. */
+    assertionCount?: {
+        baseline: number;
+        delivered: number;
+        inSpec: number;
+        inHelpers: number;
+    };
 }
 export interface VerifyUtilsParams {
     testFile: string;
@@ -70,8 +86,14 @@ export interface VerifyUtilsParams {
  *
  * Three invariants, each a class of drift measured in the SKYR-4196 Part B evals:
  *  - `duplicate-helper`: two helpers for one method+path (run 4 — `create_product`
- *    beside `create_list_reflect_product`); the shared file must hold one canonical
- *    helper per step, extended with defaulted parameters rather than duplicated.
+ *    beside `create_list_reflect_product`), or one NAME defined with two parameter
+ *    lists in any family (`addProductToCart(page, quantity)` beside
+ *    `addProductToCart(page)`); the shared file must hold one canonical helper per
+ *    step, extended with defaulted parameters rather than duplicated. Browser helpers
+ *    have no route; two of them performing one action sequence (see actionKeyOf)
+ *    are the `duplicate-action` ADVISORY.
+ *  - `helper-redefined`: one name defined twice in ONE file — the module does not
+ *    load (TypeScript) or the second def replaces the first (Python). Never markerable.
  *  - `body-assertion`: any assertion other than a status-code comparison inside a
  *    helper (runs 5 and 11 — `assert total_amount == 16.0` in `update_order`); a
  *    body assertion carries one scenario's values into a function every scenario calls.
@@ -82,6 +104,14 @@ export interface VerifyUtilsParams {
  * except to count what the spec imports.
  */
 export declare function verifyUtils(params: VerifyUtilsParams): Promise<UtilsVerifyResult>;
+/** The compared counts as one phrase, shared by the assertion-loss detail and the
+ *  PASSED line's note so the two cannot drift. */
+export declare function describeAssertionCount(c: {
+    baseline: number;
+    delivered: number;
+    inSpec: number;
+    inHelpers: number;
+}): string;
 /**
  * Python only. The import form that works here is not the one that works in the
  * customer's repo, and the difference is invisible in this run.

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

@@ -4,7 +4,7 @@ import { logger } from "../logger.js";
 import { locateUtilsFiles } from "./locate.js";
 import { blankCommentsAndStrings, countAssertions, hasPageErrorGuard, parseUtilsFile, } from "./parse.js";
 import { escapeRegExp } from "../regex.js";
-import { findSiblingInlineCallSites, generatedSiblings, } from "./call-sites.js";
+import { findSiblingInlineCallSites, findUnextractedDuplicates, generatedSiblings, } from "./call-sites.js";
 import { parseUtilsAllows, } from "./allow.js";
 import { singleImporterHelpers, } from "./importers.js";
 import { helperFamilyFor, helperFamilyOf, scenarioNameViolation, utilsSpecFor, utilsSpecForFile, } from "./language-spec.js";
@@ -13,8 +13,14 @@ import { helperFamilyFor, helperFamilyOf, scenarioNameViolation, utilsSpecFor, u
  *
  * Three invariants, each a class of drift measured in the SKYR-4196 Part B evals:
  *  - `duplicate-helper`: two helpers for one method+path (run 4 — `create_product`
- *    beside `create_list_reflect_product`); the shared file must hold one canonical
- *    helper per step, extended with defaulted parameters rather than duplicated.
+ *    beside `create_list_reflect_product`), or one NAME defined with two parameter
+ *    lists in any family (`addProductToCart(page, quantity)` beside
+ *    `addProductToCart(page)`); the shared file must hold one canonical helper per
+ *    step, extended with defaulted parameters rather than duplicated. Browser helpers
+ *    have no route; two of them performing one action sequence (see actionKeyOf)
+ *    are the `duplicate-action` ADVISORY.
+ *  - `helper-redefined`: one name defined twice in ONE file — the module does not
+ *    load (TypeScript) or the second def replaces the first (Python). Never markerable.
  *  - `body-assertion`: any assertion other than a status-code comparison inside a
  *    helper (runs 5 and 11 — `assert total_amount == 16.0` in `update_order`); a
  *    body assertion carries one scenario's values into a function every scenario calls.
@@ -39,6 +45,7 @@ export async function verifyUtils(params) {
         utilsFiles,
         helpers: 0,
         imported: 0,
+        importedNames: [],
         violations: [],
         allowed: [],
         advisories: [],
@@ -46,6 +53,7 @@ export async function verifyUtils(params) {
         spec,
         fallbackFamily: family,
         inlineCallSites: [],
+        unextractedDuplicates: [],
         singleImporters: [],
     };
     if (!spec)
@@ -65,9 +73,12 @@ export async function verifyUtils(params) {
     const importedNames = new Set();
     const importedByFile = new Map();
     const helpersOfFile = new Map();
-    // Route map spans every utils file: the reuse prompt allows the helpers to split
-    // across files, and the same method+path in two of them is still one duplicate.
+    // Route and name maps span every utils file: the reuse prompt allows the helpers
+    // to split across files, and the same method+path — or the same name — in two of
+    // them is still one duplicate.
     const byRoute = new Map();
+    const byName = new Map();
+    const byAction = new Map();
     for (const file of utilsFiles) {
         let content;
         try {
@@ -120,7 +131,7 @@ export async function verifyUtils(params) {
             const k = `${a.kind}\0${a.helper}`;
             budget.set(k, (budget.get(k) ?? 0) + 1);
         }
-        for (const v of violationsIn(helpers, file, family, spec, byRoute)) {
+        for (const v of violationsIn(helpers, file, family, spec, { byRoute, byName, byAction }, result.advisories)) {
             const k = `${v.kind}\0${v.helper}`;
             const left = budget.get(k) ?? 0;
             if (left > 0) {
@@ -136,7 +147,8 @@ export async function verifyUtils(params) {
         }
     }
     result.imported = importedNames.size;
-    // One directory walk feeds both advisories: every sibling is read exactly once.
+    result.importedNames = [...importedNames].sort();
+    // One directory walk feeds every sibling advisory: each sibling is read exactly once.
     let siblings = [];
     try {
         siblings = await generatedSiblings(params.testFile, spec, {
@@ -170,7 +182,14 @@ export async function verifyUtils(params) {
                     guardInHelpers = true;
             }
         }
-        for (const v of baselineViolations(params.baseline, params.testFile, spec, specContent, inHelpers, guardInHelpers)) {
+        const inSpec = countAssertions(specContent, spec);
+        result.assertionCount = {
+            baseline: params.baseline.assertions,
+            delivered: inSpec + inHelpers,
+            inSpec,
+            inHelpers,
+        };
+        for (const v of baselineViolations(params.baseline, params.testFile, spec, specContent, inSpec, inHelpers, guardInHelpers)) {
             // A marker in any utils file documents an assertion-loss (never a removed
             // guard). At most one loss finding exists per verify, so a matching marker's
             // presence is the whole budget — nothing to consume.
@@ -194,15 +213,25 @@ export async function verifyUtils(params) {
         catch {
             /* advisory only — never fails a verify */
         }
+        try {
+            result.unextractedDuplicates = await findUnextractedDuplicates(params.testFile, utilsFiles, spec, siblings);
+        }
+        catch {
+            /* advisory only — never fails a verify */
+        }
     }
     return result;
 }
+/** The compared counts as one phrase, shared by the assertion-loss detail and the
+ *  PASSED line's note so the two cannot drift. */
+export function describeAssertionCount(c) {
+    return `${c.baseline} assertions at the modularization hand-out, ${c.delivered} delivered (${c.inSpec} in the test, ${c.inHelpers} in the helpers it imports and calls)`;
+}
 /** The baseline (A7/A8) findings for a delivered spec — pure; marker handling is the
  *  caller's. Runs whether or not a utils file was located: deleting the utils file
  *  (with the moved assertions and guard in it) must not read as "nothing to verify". */
-function baselineViolations(baseline, testFile, spec, specContent, inHelpers, guardInHelpers) {
+function baselineViolations(baseline, testFile, spec, specContent, inSpec, inHelpers, guardInHelpers) {
     const found = [];
-    const inSpec = countAssertions(specContent, spec);
     const delivered = inSpec + inHelpers;
     // Marker grammar takes an identifier: `orders.spec.ts` → `orders_spec_ts`.
     const stem = path.basename(testFile).replace(/\W/g, "_");
@@ -212,7 +241,7 @@ function baselineViolations(baseline, testFile, spec, specContent, inHelpers, gu
             file: testFile,
             helper: stem,
             line: 1,
-            detail: `${baseline.assertions} assertions at the modularization hand-out, ${delivered} delivered (${inSpec} in the test, ${inHelpers} in the helpers it imports and calls) — restore each removed check in the test body after the helper call it verifies, or document a deliberate consolidation with the allow marker`,
+            detail: `${describeAssertionCount({ baseline: baseline.assertions, delivered, inSpec, inHelpers })} — restore each removed check in the test body after the helper call it verifies, or document a deliberate consolidation with the allow marker`,
         });
     if (baseline.pageErrorGuard &&
         !guardInHelpers &&
@@ -334,14 +363,19 @@ export function importFormViolations(testFile, specContent, utilsFiles) {
 function blankTripleQuoted(src) {
     return src.replace(/("""|''')[\s\S]*?\1/g, (m) => m.replace(/[^\n]/g, " "));
 }
-function violationsIn(helpers, file, fallback, spec, byRoute) {
+function violationsIn(helpers, file, fallback, spec, seen, advisories) {
+    const { byRoute, byName, byAction } = seen;
+    // Names seen in THIS file: a second definition here is a redefinition, not drift.
+    const inThisFile = new Map();
     const out = [];
     for (const h of helpers) {
         const family = helperFamilyOf(h, fallback);
+        let routeDuplicateOf;
         if (family.routeDuplicates && h.method && h.normalizedPath) {
             const key = `${h.method} ${h.normalizedPath}`;
             const first = byRoute.get(key);
             if (first) {
+                routeDuplicateOf = first;
                 out.push({
                     kind: "duplicate-helper",
                     file,
@@ -354,6 +388,75 @@ function violationsIn(helpers, file, fallback, spec, byRoute) {
                 byRoute.set(key, { ...h, file });
             }
         }
+        // One name defined twice. In ONE file that is a redefinition, whatever the
+        // parameter lists: a TypeScript module with two top-level functions of one name
+        // does not load, and in Python the second def silently replaces the first — so it
+        // blocks and takes no marker. Across two files each caller imports the module it
+        // uses; different parameter lists there are the drift the ticket measured
+        // (`addProductToCart(page, quantity)` in one run, `addProductToCart(page)` in
+        // the next), reported as `duplicate-helper`, documentable, once per pair — a pair
+        // the route check already reported carries its repair. Same name, same arity,
+        // two files: nothing here; the action key speaks if the bodies agree.
+        let nameReported = false;
+        const inFile = inThisFile.get(h.name);
+        const sameName = byName.get(h.name);
+        if (inFile) {
+            nameReported = true;
+            out.push({
+                kind: "helper-redefined",
+                file,
+                helper: h.name,
+                line: h.line,
+                detail: spec.language === "python"
+                    ? `${h.name} is defined twice in this file (also at ${path.basename(inFile.file)}:${inFile.line}); this def silently replaces the first, and every caller written against the first signature breaks. Keep ONE definition, give every parameter the other had a default, and update the call sites`
+                    : `${h.name} is defined twice in this file (also at ${path.basename(inFile.file)}:${inFile.line}); a module with two top-level functions of one name does not load. Keep ONE definition, give every parameter the other had a default, and update the call sites`,
+            });
+        }
+        else if (sameName &&
+            h.arity !== undefined &&
+            sameName.arity !== undefined &&
+            h.arity !== sameName.arity &&
+            !(routeDuplicateOf?.file === sameName.file &&
+                routeDuplicateOf?.line === sameName.line)) {
+            nameReported = true;
+            out.push({
+                kind: "duplicate-helper",
+                file,
+                helper: h.name,
+                line: h.line,
+                detail: `${h.name} is defined in two modules with different parameter lists — ${h.arity} parameter${h.arity === 1 ? "" : "s"} here, ${sameName.arity} at ${path.basename(sameName.file)}:${sameName.line}; the two modules disagree on one operation's signature, and the next test to import it gets whichever it finds first. Keep ONE definition, give every parameter the other lacked a default, and point every importer at it`,
+            });
+        }
+        if (!inFile)
+            inThisFile.set(h.name, { ...h, file });
+        if (!sameName)
+            byName.set(h.name, { ...h, file });
+        // The browser analogue of the route key: two request-free helpers performing one
+        // action sequence are one operation under two names. Advisory — the key is read
+        // from selector literals, and its false positive must not block a run. A pair the
+        // name checks just reported is one finding, not two; a same-name pair they were
+        // silent on (two files, equal arity) is this check's — exactly one detector
+        // speaks for any pair.
+        if (family.family === "browser" && h.actionKey) {
+            const first = byAction.get(h.actionKey);
+            if (first && !(nameReported && first.name === h.name)) {
+                advisories.push({
+                    kind: "duplicate-action",
+                    file,
+                    helper: h.name,
+                    line: h.line,
+                    // Only the parameter COUNT is compared, and only when both were read.
+                    detail: first.name === h.name
+                        ? `${h.name} is defined twice (also at ${path.basename(first.file)}:${first.line}) with the same ${h.arity !== undefined && h.arity === first.arity
+                            ? "parameter count and the same "
+                            : ""}action sequence: ${describeActionKey(h.actionKey)}; keep one definition and point every importer at it`
+                        : `${h.name} and ${first.name} (${path.basename(first.file)}:${first.line}) perform the same action sequence: ${describeActionKey(h.actionKey)}`,
+                });
+            }
+            else if (!first) {
+                byAction.set(h.actionKey, { ...h, file });
+            }
+        }
         for (const a of h.assertions) {
             if (!family.isAllowed(spec, a.text)) {
                 out.push({
@@ -378,3 +481,14 @@ function violationsIn(helpers, file, fallback, spec, byRoute) {
     }
     return out;
 }
+/** `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. */
+function describeActionKey(key) {
+    return key
+        .split("; ")
+        .map((step) => {
+        const at = step.indexOf(" ");
+        return `${step.slice(0, at)} \`${step.slice(at + 1)}\``;
+    })
+        .join("; ");
+}