@skyramp/mcp 0.3.4 → 0.3.6-rc.1

package/build/utils/planMatchKeys.js

@@ -14,6 +14,7 @@
  *    matching (contract tests, or a fallback when names drift between
  *    register and generate).
  */
+import { isParamSegment, isOpaqueIdSegment } from "./routeParsers.js";
 /** Lowercase, collapse non-alphanumeric runs to '-', trim leading/trailing '-'. */
 export function slugifyName(name) {
     return (name ?? "")
@@ -22,9 +23,22 @@ export function slugifyName(name) {
         .replace(/^-+|-+$/g, "");
 }
 /**
- * Normalize a path so param segments collapse: numeric ids, `{brace}` params,
- * `:colon` params, and long hex/uuid segments all become `:p`. Mirrors
- * discriminators.ts's normalizePath (duplicated here rather than imported —
+ * Normalize a path so param/id segments collapse: `{brace}`, `:colon`,
+ * `[bracket]` params in any of routeParsers.ts's syntaxes, plus numeric,
+ * UUID, and long-hex id VALUES, all become `:p`. Delegates to
+ * routeParsers.ts's `isParamSegment`/`isOpaqueIdSegment` (SKYR-4214 task 5)
+ * rather than a second inline copy — this module previously had its own
+ * looser hex rule (`/^[0-9a-fA-F-]{16,}$/`, accepting `-`) and no
+ * bracket-syntax rule at all, so a Next.js `[id]` segment never collapsed
+ * and kept a match key from matching its `{id}`-spelled counterpart (the
+ * SKYR-4123 failure mode: a generated test's key stops matching its plan
+ * item). The characterization test in
+ * `pathSegmentClassification.characterization.test.ts` confirms every
+ * previously-agreeing input (UUID, numeric, 16+/24-char hex) still
+ * collapses to `:p` after this change — safe within one run because the
+ * register-time key and the generation-time query are computed by the same
+ * build; a plan file is never persisted across builds. Mirrors
+ * discriminators.ts's normalizePath (duplicated rather than imported —
  * that function verifies discriminator claims against a diff, a different
  * concern from plan matching, and keeping them independent avoids coupling
  * this module's stability to phase 1's internal helper).
@@ -36,13 +50,12 @@ export function normalizeMatchPath(rawPath) {
         .map((seg) => {
         if (seg === "")
             return seg;
-        if (/^\{.*\}$/.test(seg))
-            return ":p";
-        if (/^:.+/.test(seg))
-            return ":p";
-        if (/^\d+$/.test(seg))
-            return ":p";
-        if (/^[0-9a-fA-F-]{16,}$/.test(seg))
+        // `isParamSegment` covers the well-formed colon family — `:id`,
+        // `:id(\d+)`, `:id?`, `:id*`, `:id+`. The `/^:/` test in front of it is
+        // deliberate breadth for the colon segments that regex rejects, such as
+        // `:1abc` or `:id-x`: a malformed param must still normalize to `:p`,
+        // or a registered `/users/:1abc` stops endpoint-matching `/users/42`.
+        if (/^:/.test(seg) || isParamSegment(seg) || isOpaqueIdSegment(seg))
             return ":p";
         return seg.toLowerCase();
     })
@@ -74,6 +87,9 @@ export function buildApprovedPlanItem(candidate) {
         category: candidate.scenario.category,
         source: candidate.source,
         ...(candidate.verifiedDiscriminator ? { verifiedDiscriminator: candidate.verifiedDiscriminator } : {}),
+        ...(candidate.scenario.subjectEndpoints !== undefined
+            ? { subjectEndpoints: candidate.scenario.subjectEndpoints }
+            : {}),
         matchKeys: computeMatchKeys(candidate.scenario),
     };
 }

package/build/utils/pluralization.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Convert a plural resource name to its singular form for use in field names
+ * and step descriptions.
+ *
+ * Handles the most common irregular plurals found in REST API paths:
+ *   -ies → -y  (categories → category, companies → company)
+ *   -ses → -s  (statuses → status, classes → class)
+ * Falls back to removing the trailing "s" for regular plurals.
+ */
+export declare function singularize(word: string): string;

package/build/utils/pluralization.js

@@ -0,0 +1,18 @@
+/**
+ * Convert a plural resource name to its singular form for use in field names
+ * and step descriptions.
+ *
+ * Handles the most common irregular plurals found in REST API paths:
+ *   -ies → -y  (categories → category, companies → company)
+ *   -ses → -s  (statuses → status, classes → class)
+ * Falls back to removing the trailing "s" for regular plurals.
+ */
+export function singularize(word) {
+    if (word.endsWith("ies") && word.length > 3) {
+        return word.slice(0, -3) + "y";
+    }
+    if (word.endsWith("ses") && word.length > 4) {
+        return word.slice(0, -2); // statuses → status
+    }
+    return word.endsWith("s") && word.length > 1 ? word.slice(0, -1) : word;
+}

package/build/utils/pom-catalog-parse.d.ts

@@ -0,0 +1,52 @@
+import type { ReuseMissedEntry } from "../types/ReuseOutcome.js";
+/**
+ * Parses the agent-written POM catalog (`.skyramp/skyramp-pom-catalog.md`, path owned
+ * by `pom-catalog.ts`) and joins it against the raw locators a delivered spec still
+ * carries inline.
+ *
+ * Why the catalog and not `selectScopedPoms`: that join is a whole-token substring
+ * test (`pomContent.includes(specToken)`), which is structurally blind to
+ * prefix-parameterized selectors — the exact thing a good page object does. Measured
+ * on openobserve run 31662701508 it misses the covering file entirely and returns two
+ * unrelated pages; widening it to prefix matching finds the right file but pulls in 32
+ * more. The catalog is already scoped and records the wildcard form, so the same match
+ * is precise there.
+ *
+ * Everything here is informational — no caller gates on it — so the bias throughout is
+ * to under-report rather than assert. A malformed catalog yields no members, and a
+ * member with no recorded selector simply covers nothing.
+ */
+/** One catalogued property or method, with its selectors as wildcard patterns. */
+export interface CatalogMember {
+    className: string;
+    /** As the catalog names it: `propertyName` or `methodName(a, b)`. */
+    member: string;
+    kind: "property" | "method";
+    /** Basename of the class's `Import:` path — extension-less, see ReuseMissedEntry. */
+    pageObject: string;
+    /** Wildcard patterns; `*` matches any run of characters. */
+    selectors: string[];
+}
+/**
+ * Every property and method in the catalog. Returns `[]` for anything that is not a
+ * catalog — this runs on a file the agent wrote, so unparseable input is an expected
+ * state, not an error.
+ */
+export declare function parsePomCatalog(markdown: string): CatalogMember[];
+/**
+ * Raw locators the delivered spec still carries, and which of them a catalogued member
+ * covers.
+ *
+ * The spec side is `extractRawLocatorTokens`, a sibling of the POM-detection
+ * `extractSelectors` that excludes `getByRole`'s role token and the bare `name:`
+ * field — those are detection evidence, not locators, and `name:` in particular can
+ * capture a POM method's own data argument (e.g. `fp.createFunction({ name: "myFunction" })`).
+ * Both numbers come from one pass so the denominator and the misses cannot disagree.
+ *
+ * First match wins per locator. A locator covered by two members is still one missed
+ * reuse, and naming one of them is enough to send a reviewer to the right file.
+ */
+export declare function findMissedReuse(specContent: string, members: CatalogMember[]): {
+    rawLocatorsInline: number;
+    missed: ReuseMissedEntry[];
+};

package/build/utils/pom-catalog-parse.js

@@ -0,0 +1,141 @@
+import * as path from "path";
+import { extractRawLocatorTokens } from "./pom-scope/selector-extractor.js";
+import { escapeRegExp } from "./regex.js";
+const CLASS_HEADING_RE = /^##\s+(.+?)\s*$/;
+const IMPORT_RE = /^-\s+\*\*Import:\*\*\s+`([^`]+)`/;
+const PROPERTIES_RE = /^-\s+\*\*Properties:\*\*/;
+const METHODS_RE = /^-\s+\*\*Methods:\*\*/;
+const OTHER_FIELD_RE = /^-\s+\*\*/;
+/** A member bullet: indented, backticked name, dash separator, then the description. */
+const MEMBER_RE = /^\s+-\s+`([^`]+)`\s*[—–-]\s*(.*)$/;
+const BACKTICKED_RE = /`([^`]+)`/g;
+/** `[data-test="value"]`, including prefix/suffix matchers — the value is the token. */
+const ATTR_VALUE_RE = /\[[A-Za-z-]+[$^*~|]?="([^"]+)"\]/g;
+/** A bare token that looks like a selector value rather than prose. */
+const BARE_TOKEN_RE = /^[A-Za-z0-9][A-Za-z0-9._:-]*\*?$/;
+/** Below this, a bare token is too generic to claim coverage of anything. Attribute
+ *  values are exempt: `[data-test="x"]` is unambiguous evidence regardless of length. */
+const MIN_BARE_TOKEN_LENGTH = 6;
+/** `${...}` and `*` both mean "any run of characters" — normalize to one form. */
+function normalizeWildcards(token) {
+    return token.replace(/\$\{[^}]*\}/g, "*");
+}
+/** Selector patterns in a member's DESCRIPTION — the text after the dash, never the
+ *  member name itself. Scanning the whole bullet would make a property register its own
+ *  name as a selector (`addFunctionButton` is a valid bare token), so a spec locator that
+ *  happened to equal a property name would read as covered by that property, which is
+ *  circular. */
+function selectorsFrom(description) {
+    const out = new Set();
+    for (const [, backticked] of description.matchAll(BACKTICKED_RE)) {
+        const token = normalizeWildcards(backticked);
+        let sawAttr = false;
+        for (const [, value] of token.matchAll(ATTR_VALUE_RE)) {
+            out.add(value);
+            sawAttr = true;
+        }
+        // A bare token is only a selector if the whole backticked run is one — otherwise
+        // it is prose, or an attribute selector already harvested above.
+        if (!sawAttr && BARE_TOKEN_RE.test(token) && token.length >= MIN_BARE_TOKEN_LENGTH) {
+            out.add(token);
+        }
+    }
+    return [...out];
+}
+/**
+ * Every property and method in the catalog. Returns `[]` for anything that is not a
+ * catalog — this runs on a file the agent wrote, so unparseable input is an expected
+ * state, not an error.
+ */
+export function parsePomCatalog(markdown) {
+    const members = [];
+    let className;
+    let pageObject = "";
+    let section;
+    for (const line of markdown.split("\n")) {
+        const heading = CLASS_HEADING_RE.exec(line);
+        if (heading) {
+            // Free-function module headings carry a trailing gloss — `bookingHelpers
+            // (module functions, not a class)` (SKYR-4157 finding 4) — strip it so
+            // `className` is the bare module/class name, not prose.
+            className = heading[1].replace(/\s*\([^)]*\)\s*$/, "");
+            pageObject = "";
+            section = undefined;
+            continue;
+        }
+        if (!className)
+            continue;
+        const imported = IMPORT_RE.exec(line);
+        if (imported) {
+            // Extension-less by construction: the catalog records an import specifier, and
+            // `path.basename` of `../../pages/functionsPages/functionsPage` is what a reader
+            // needs to find the file.
+            pageObject = path.basename(imported[1]).replace(/\.(ts|js|mjs|cjs)$/, "");
+            continue;
+        }
+        if (PROPERTIES_RE.test(line)) {
+            section = "property";
+            continue;
+        }
+        if (METHODS_RE.test(line)) {
+            section = "method";
+            continue;
+        }
+        // Any other `- **Field:**` line (Iframe, depth markers) closes the current section.
+        if (OTHER_FIELD_RE.test(line)) {
+            section = undefined;
+            continue;
+        }
+        if (!section)
+            continue;
+        const member = MEMBER_RE.exec(line);
+        if (!member)
+            continue;
+        members.push({
+            className,
+            member: member[1],
+            kind: section,
+            pageObject,
+            // Description only — see selectorsFrom on why the member name is excluded.
+            selectors: selectorsFrom(member[2]),
+        });
+    }
+    return members;
+}
+/** Anchored matcher for one wildcard pattern. */
+function toMatcher(pattern) {
+    return new RegExp(`^${pattern.split("*").map(escapeRegExp).join(".*")}$`);
+}
+/** The member name without its parameter list, for the `Class.member` label. */
+function bareMemberName(member) {
+    return member.replace(/\(.*$/, "");
+}
+/**
+ * Raw locators the delivered spec still carries, and which of them a catalogued member
+ * covers.
+ *
+ * The spec side is `extractRawLocatorTokens`, a sibling of the POM-detection
+ * `extractSelectors` that excludes `getByRole`'s role token and the bare `name:`
+ * field — those are detection evidence, not locators, and `name:` in particular can
+ * capture a POM method's own data argument (e.g. `fp.createFunction({ name: "myFunction" })`).
+ * Both numbers come from one pass so the denominator and the misses cannot disagree.
+ *
+ * First match wins per locator. A locator covered by two members is still one missed
+ * reuse, and naming one of them is enough to send a reviewer to the right file.
+ */
+export function findMissedReuse(specContent, members) {
+    const locators = extractRawLocatorTokens(specContent);
+    const compiled = members.map((m) => ({ m, matchers: m.selectors.map(toMatcher) }));
+    const missed = [];
+    for (const locator of locators) {
+        const hit = compiled.find(({ matchers }) => matchers.some((re) => re.test(locator)));
+        if (!hit)
+            continue;
+        missed.push({
+            locator,
+            pageObject: hit.m.pageObject,
+            member: `${hit.m.className}.${bareMemberName(hit.m.member)}`,
+        });
+    }
+    return { rawLocatorsInline: locators.length, missed };
+}

package/build/utils/pom-scope/selector-extractor.d.ts

@@ -4,4 +4,16 @@
  * these strings to find which page objects cover the test's actions.
  */
 export declare const DEFAULT_TESTID_ATTRS: string[];
+/** POM-detection token set (SKYR-4157 finding 1: also used for scoring, unchanged
+ *  behaviour) — includes role names and bare `name:` values as evidence, even
+ *  though those are not themselves raw locators. Used by the POM scoping path
+ *  (`pom-scope/index.ts`); do not repurpose for coverage counting. */
 export declare function extractSelectors(specContent: string, extraTestIdAttrs?: string[]): string[];
+/** Genuine raw LOCATOR tokens only: test-id attribute values, `getByTestId`,
+ *  `getByText`/`getByLabel`/`getByPlaceholder`, and raw `.locator()`/
+ *  `.frameLocator()` strings. Excludes `getByRole`'s role token and the bare
+ *  `name:` field — neither is a locator, and `name:` in particular can capture a
+ *  POM method's own data argument (SKYR-4157 finding 1). Used for coverage
+ *  counting (`pom-catalog-parse.ts`), where the denominator must be actual
+ *  locators still inline, not detection evidence. */
+export declare function extractRawLocatorTokens(specContent: string, extraTestIdAttrs?: string[]): string[];

package/build/utils/pom-scope/selector-extractor.js

@@ -16,12 +16,19 @@ const attrPattern = (attrs) => new RegExp(`\\[(?:${attrs.map(esc).join("|")})[$^
 // string is actually a family-attr selector, vs. one that merely CONTAINS the
 // substring (e.g. ".data-testing-notes" contains "data-test" but isn't one).
 const attrAnchor = (attrs) => new RegExp(`\\[(?:${attrs.map(esc).join("|")})[$^*~|]?=`);
-const OTHER_PATTERNS = [
-    /getByTestId\(\s*["']([^"']+)["']/g, // getByTestId("X")
-    /getByRole\(\s*["']([^"']+)["']/g, // getByRole("role", ...)
-    /name:\s*["']([^"']+)["']/g, // { name: "Accessible Name" }
-    /getBy(?:Text|Label|Placeholder)\(\s*["']([^"']+)["']/g, // getByText("T") etc.
-];
+// getByTestId("X"), getByText/Label/Placeholder("T") — these capture genuine raw
+// locator values, shared by both extractSelectors and extractRawLocatorTokens.
+const GET_BY_TEST_ID = /getByTestId\(\s*["']([^"']+)["']/g;
+const GET_BY_TEXT_LABEL_PLACEHOLDER = /getBy(?:Text|Label|Placeholder)\(\s*["']([^"']+)["']/g;
+const LOCATOR_PATTERNS = [GET_BY_TEST_ID, GET_BY_TEXT_LABEL_PLACEHOLDER];
+// getByRole("role", ...) and bare `name: "..."` object keys are useful evidence for
+// POM *detection* (scoring which page objects a test's actions touch), but they are
+// NOT raw locator values: a role name isn't a selector, and `name:` matches ANY bare
+// object key so named — including a POM method's own data argument (SKYR-4157
+// finding 1). Only extractSelectors (the detection path) includes these.
+const GET_BY_ROLE = /getByRole\(\s*["']([^"']+)["']/g;
+const BARE_NAME_FIELD = /name:\s*["']([^"']+)["']/g;
+const OTHER_PATTERNS = [GET_BY_TEST_ID, GET_BY_ROLE, BARE_NAME_FIELD, GET_BY_TEXT_LABEL_PLACEHOLDER];
 // Raw .locator("...")/.frameLocator("...") strings that are NOT test-id-attribute based
 // (e.g. ".step-deduplication", "iframe#asset-list").
 // Quote-type-aware alternates: a double-quoted arg may contain unescaped single quotes
@@ -35,11 +42,13 @@ function normalize(token) {
 function isUseful(token) {
     return token.length >= 3 && !/^\d+$/.test(token);
 }
-export function extractSelectors(specContent, extraTestIdAttrs = []) {
+/** Shared core: test-id-attribute values, the given value-bearing patterns, and raw
+ *  `.locator()`/`.frameLocator()` strings not already covered by an attribute match. */
+function collectTokens(specContent, patterns, extraTestIdAttrs) {
     const testIdAttrs = [...DEFAULT_TESTID_ATTRS, ...extraTestIdAttrs];
     const anchor = attrAnchor(testIdAttrs);
     const tokens = new Set();
-    for (const re of [attrPattern(testIdAttrs), ...OTHER_PATTERNS]) {
+    for (const re of [attrPattern(testIdAttrs), ...patterns]) {
         for (const m of specContent.matchAll(re)) {
             const t = normalize(m[1]);
             if (isUseful(t))
@@ -55,3 +64,20 @@ export function extractSelectors(specContent, extraTestIdAttrs = []) {
     }
     return [...tokens];
 }
+/** POM-detection token set (SKYR-4157 finding 1: also used for scoring, unchanged
+ *  behaviour) — includes role names and bare `name:` values as evidence, even
+ *  though those are not themselves raw locators. Used by the POM scoping path
+ *  (`pom-scope/index.ts`); do not repurpose for coverage counting. */
+export function extractSelectors(specContent, extraTestIdAttrs = []) {
+    return collectTokens(specContent, OTHER_PATTERNS, extraTestIdAttrs);
+}
+/** Genuine raw LOCATOR tokens only: test-id attribute values, `getByTestId`,
+ *  `getByText`/`getByLabel`/`getByPlaceholder`, and raw `.locator()`/
+ *  `.frameLocator()` strings. Excludes `getByRole`'s role token and the bare
+ *  `name:` field — neither is a locator, and `name:` in particular can capture a
+ *  POM method's own data argument (SKYR-4157 finding 1). Used for coverage
+ *  counting (`pom-catalog-parse.ts`), where the denominator must be actual
+ *  locators still inline, not detection evidence. */
+export function extractRawLocatorTokens(specContent, extraTestIdAttrs = []) {
+    return collectTokens(specContent, LOCATOR_PATTERNS, extraTestIdAttrs);
+}

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

@@ -7,13 +7,14 @@ export type ReuseViolation = {
 export type VerifyResult = {
     ok: boolean;
     violations: ReuseViolation[];
-    unverifiable: string[];
+    unverifiableCalls: string[];
+    unrecognizedBindings: string[];
     parseError?: string;
     checkedCalls: number;
-    /** Every POM call found in the spec, verifiable or not. NOT checkedCalls +
-     *  unverifiable.length: `unverifiable` also absorbs `unrecognized` bindings,
-     *  which are not calls at all, so that sum overcounts. This is the count of
-     *  POM members the delivered spec actually reuses. */
+    /** Every POM call found in the spec, verifiable or not. Equals
+     *  `checkedCalls + unverifiableCalls.length`: `unrecognizedBindings` is kept
+     *  separate precisely because those are not calls and would overcount. This is
+     *  the count of POM members the delivered spec actually reuses. */
     reusedCalls: number;
 };
 export declare function verifyReuse(testFile: string, language: string): Promise<VerifyResult>;

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

@@ -126,18 +126,19 @@ export async function verifyReuse(testFile, language) {
     const calls = extractPomCalls(spec, bindings);
     const bindingsByName = new Map(bindings.map((b) => [b.name, b]));
     const violations = [];
-    const unverifiable = [];
+    const unverifiableCalls = [];
+    const unrecognizedBindings = [];
     let checkedCalls = 0;
     for (const call of calls) {
         const binding = bindingsByName.get(call.binding);
         if (!binding) {
             // Shouldn't happen -- extractPomCalls only matches against the bindings it was given --
             // but degrade to unverifiable rather than throw if the invariant ever breaks.
-            unverifiable.push([call.binding, ...call.chain].join("."));
+            unverifiableCalls.push([call.binding, ...call.chain].join("."));
             continue;
         }
         if (!call.strict) {
-            unverifiable.push([call.binding, ...call.chain].join("."));
+            unverifiableCalls.push([call.binding, ...call.chain].join("."));
             continue;
         }
         checkedCalls++;
@@ -156,7 +157,7 @@ export async function verifyReuse(testFile, language) {
                 // remap/demote loop the agent cannot win (no candidates to remap to → forced demote
                 // of possibly-correct reuse). Degrade to unverifiable — the fail-open contract at
                 // the reachability level, matching resolve.ts's permissive stance on shapes.
-                unverifiable.push([call.binding, ...call.chain].join("."));
+                unverifiableCalls.push([call.binding, ...call.chain].join("."));
                 checkedCalls--;
                 continue;
             }
@@ -164,7 +165,7 @@ export async function verifyReuse(testFile, language) {
         }
     }
     for (const u of unrecognized)
-        unverifiable.push(u);
+        unrecognizedBindings.push(u);
     let parseError;
     if (language === "javascript") {
         try {
@@ -179,7 +180,8 @@ export async function verifyReuse(testFile, language) {
     return {
         ok: violations.length === 0 && parseError === undefined,
         violations,
-        unverifiable,
+        unverifiableCalls,
+        unrecognizedBindings,
         parseError,
         checkedCalls,
         reusedCalls: calls.length,

package/build/utils/reportLanguage.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Report-language enforcement for `skyramp_submit_report` (SKYR-4185).
+ *
+ * The report language (SKYR-4023) reaches the MCP server only as a testbot
+ * prompt/resource arg, and the instruction to write free-text report fields in
+ * that language is prose the agent sometimes ignores — the customer-visible
+ * failure this module exists to close. The prompt render captures the language
+ * here (same server process serves the prompt and later handles the report
+ * tool), and the report tool rejects submissions whose free-text fields leaked
+ * back into English.
+ *
+ * Capture is fail-open by design: if the testbot prompt was never served
+ * (local/IDE flows, or a run broken enough that the agent has no instructions),
+ * the language stays unset and no report is ever falsely rejected.
+ */
+/** Capture the report language at prompt-serve time. Last render wins:
+ *  `undefined` clears any earlier capture, so a long-lived server (IDE use)
+ *  that renders a ja prompt and later an English/argless one disarms the
+ *  guardrail rather than falsely rejecting a legitimately-English report. */
+export declare function setReportLanguage(language: string | undefined): void;
+export declare function getReportLanguage(): string | undefined;
+/** Test isolation only — module state persists across tests in one process. */
+export declare function resetReportLanguage(): void;
+export declare function isEnforcedReportLanguage(language: string | undefined): language is string;
+/** English display name for a language code, falling back to the raw code when
+ *  Intl rejects it as a structurally invalid tag (e.g. "ja_JP") — the code is
+ *  ultimately caller-supplied, and a name lookup must never throw. */
+export declare function reportLanguageDisplayName(language: string): string;
+export interface ReportTextField {
+    /** Where the text came from, in the tool's input terms (e.g. "testResults[2].details"). */
+    path: string;
+    text: string;
+}
+/** Field paths whose text leaked English under an enforced report language.
+ *  Empty for non-enforced languages — unknown languages are skipped, never guessed. */
+export declare function findLanguageViolations(fields: ReportTextField[], language: string): string[];
+/** Field paths in the deliberately-lenient band: some English prose, but under
+ *  the rejection threshold (i.e. exactly one stray word at the current
+ *  MIN_PROSE_WORDS of 2). These SHIP — the guardrail accepts them so a lone
+ *  technical word ("flaky", "timeout") never blocks a report. Counted into the
+ *  submit-report analytics event so the residual leak rate is measurable
+ *  before anyone tightens the threshold. */
+export declare function findLanguageNearMisses(fields: ReportTextField[], language: string): string[];

package/build/utils/reportLanguage.js

@@ -0,0 +1,125 @@
+/**
+ * Report-language enforcement for `skyramp_submit_report` (SKYR-4185).
+ *
+ * The report language (SKYR-4023) reaches the MCP server only as a testbot
+ * prompt/resource arg, and the instruction to write free-text report fields in
+ * that language is prose the agent sometimes ignores — the customer-visible
+ * failure this module exists to close. The prompt render captures the language
+ * here (same server process serves the prompt and later handles the report
+ * tool), and the report tool rejects submissions whose free-text fields leaked
+ * back into English.
+ *
+ * Capture is fail-open by design: if the testbot prompt was never served
+ * (local/IDE flows, or a run broken enough that the agent has no instructions),
+ * the language stays unset and no report is ever falsely rejected.
+ */
+let sessionReportLanguage;
+/** Capture the report language at prompt-serve time. Last render wins:
+ *  `undefined` clears any earlier capture, so a long-lived server (IDE use)
+ *  that renders a ja prompt and later an English/argless one disarms the
+ *  guardrail rather than falsely rejecting a legitimately-English report. */
+export function setReportLanguage(language) {
+    sessionReportLanguage = language;
+}
+export function getReportLanguage() {
+    return sessionReportLanguage;
+}
+/** Test isolation only — module state persists across tests in one process. */
+export function resetReportLanguage() {
+    sessionReportLanguage = undefined;
+}
+// Languages the guardrail can enforce: detection is script-presence-based, so a
+// language is enforceable only when its expected script is disjoint from Latin.
+// English ('en') is deliberately absent — it is the default, not enforced.
+// A Map, not a plain object: the key is caller-supplied, and object indexing
+// would resolve prototype keys ("toString") to inherited members whose later
+// .test() call crashes the tool.
+const TARGET_SCRIPTS = new Map([
+    // Hiragana, Katakana (incl. halfwidth), CJK ideographs (incl. ext A / compat).
+    ["ja", /[぀-ヿ㐀-䶿一-鿿豈-﫿ｦ-ﾟ]/],
+]);
+export function isEnforcedReportLanguage(language) {
+    return language !== undefined && TARGET_SCRIPTS.has(language);
+}
+/** English display name for a language code, falling back to the raw code when
+ *  Intl rejects it as a structurally invalid tag (e.g. "ja_JP") — the code is
+ *  ultimately caller-supplied, and a name lookup must never throw. */
+export function reportLanguageDisplayName(language) {
+    try {
+        return new Intl.DisplayNames(["en"], { type: "language" }).of(language) ?? language;
+    }
+    catch {
+        return language;
+    }
+}
+// Tokens that are legitimate untranslated content in any report language — the
+// prompt's own "do NOT translate" list: enum values, HTTP verbs, test types.
+const UNTRANSLATED_WORDS = new Set([
+    // Exact enum values only. NOT "passed"/"failed" — those are ordinary English
+    // prose and are exactly what leaks in pytest summaries ("1 passed in 0.88s",
+    // "failed: count was 13"; see letsramp/api-insight#215).
+    "pass", "fail", "skipped", "error", "unknown",
+    "critical", "high", "medium", "low",
+    "get", "post", "put", "patch", "delete", "head", "options",
+    "ui", "e2e", "api", "contract", "integration", "smoke", "fuzz", "load", "mock",
+    "http", "https", "json", "yaml", "ok",
+]);
+/** A field must contain at least this many plain English prose words (after the
+ *  stripping below) to be flagged — so identifier-and-timing-only details like
+ *  "10.8s, products_contract_test.py" stay legal, and one stray word ("flaky")
+ *  never rejects a report. Two is deliberate: the shortest real leak observed
+ *  ("1 passed in 0.88s", api-insight#215) has exactly two prose words. */
+const MIN_PROSE_WORDS = 2;
+/** Count the plain English prose words in `text`, or return 0 when the target
+ *  language's script is present (the field is compliant regardless of any
+ *  English around it). Backticked spans, file names/paths, identifiers
+ *  (snake_case/camelCase/ALL-CAPS), digit-bearing tokens, and the prompt's
+ *  untranslated vocabulary are all excluded from the count. */
+function countProseWords(text, script) {
+    if (script.test(text))
+        return 0;
+    const withoutCode = text.replace(/`[^`]*`/g, " ");
+    let proseWords = 0;
+    for (const raw of withoutCode.split(/\s+/)) {
+        const token = raw.replace(/^[^A-Za-z0-9]+/, "").replace(/[^A-Za-z0-9]+$/, "");
+        // Pure alphabetic words only: anything with digits or interior punctuation
+        // (paths, file names, snake_case, versions, "10.8s") is not prose.
+        if (token.length < 2 || !/^[A-Za-z]+$/.test(token))
+            continue;
+        if (/[a-z][A-Z]/.test(token))
+            continue; // camelCase identifier
+        if (token === token.toUpperCase())
+            continue; // acronym / enum shout (GET, FAILED)
+        if (UNTRANSLATED_WORDS.has(token.toLowerCase()))
+            continue;
+        proseWords++;
+    }
+    return proseWords;
+}
+/** Field paths whose text leaked English under an enforced report language.
+ *  Empty for non-enforced languages — unknown languages are skipped, never guessed. */
+export function findLanguageViolations(fields, language) {
+    const script = TARGET_SCRIPTS.get(language);
+    if (!script)
+        return [];
+    return fields
+        .filter((f) => countProseWords(f.text, script) >= MIN_PROSE_WORDS)
+        .map((f) => f.path);
+}
+/** Field paths in the deliberately-lenient band: some English prose, but under
+ *  the rejection threshold (i.e. exactly one stray word at the current
+ *  MIN_PROSE_WORDS of 2). These SHIP — the guardrail accepts them so a lone
+ *  technical word ("flaky", "timeout") never blocks a report. Counted into the
+ *  submit-report analytics event so the residual leak rate is measurable
+ *  before anyone tightens the threshold. */
+export function findLanguageNearMisses(fields, language) {
+    const script = TARGET_SCRIPTS.get(language);
+    if (!script)
+        return [];
+    return fields
+        .filter((f) => {
+        const words = countProseWords(f.text, script);
+        return words > 0 && words < MIN_PROSE_WORDS;
+    })
+        .map((f) => f.path);
+}