@skyramp/mcp 0.3.5 → 0.3.6-rc.1

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/reportVerification.d.ts

@@ -25,7 +25,7 @@ import { DriftAction } from "../types/TestAnalysis.js";
  */
 export declare function listChangedFilesAcross(roots: Array<string | undefined>): Promise<string[]>;
 export declare function listChangedFiles(repoRoot: string): Promise<string[]>;
-export interface UnbackedClaimsInput {
+export interface UnchangedFileClaimsInput {
     /** Absolute path of the primary repo checkout the report pertains to. */
     repoRoot: string;
     /** Repo-relative paths that have a working-tree change (from listChangedFiles). */
@@ -49,8 +49,14 @@ export interface UnbackedClaimsInput {
 }
 /**
  * Cross-check report claims against files that actually changed in the working
- * tree, returning a human-readable description for each claim NOT backed by a
- * real change. An empty result means every claim is backed.
+ * tree, returning a human-readable description for each claim whose file has no
+ * change. An empty result means every claim is backed.
+ *
+ * Not to be confused with `findInvalidSourceCitations` below. This one is about
+ * files the agent says IT wrote — a created test, a maintained test — so the test
+ * is "did this file change in this run". That one is about application code the
+ * agent POINTS AT as the home of a defect, which it never edits, so the test is
+ * "does this file and symbol exist in the checkout at all".
  *
  * The delivery path can only ship what the agent actually edited (SKYR-3883), so
  * a report must never claim file work the tree doesn't reflect. This is the
@@ -73,4 +79,58 @@ export interface UnbackedClaimsInput {
  *  - Claims for files outside this checkout (cross-repo `repository`, or an
  *    absolute path resolving outside `repoRoot`) — a different checkout owns them.
  */
-export declare function findUnbackedClaims(input: UnbackedClaimsInput): string[];
+export declare function findUnchangedFileClaims(input: UnchangedFileClaimsInput): string[];
+/** One checkout of the run, and the owner/repo it holds. */
+export interface RepoCheckout {
+    /** Absolute checkout path. */
+    root: string;
+    /** owner/repo of this checkout, when the run recorded one. Undefined means the
+     *  checkout cannot be named, so nothing resolved in it can be attributed. */
+    repository?: string;
+    /** True for the run's primary checkout — the repo an entry with no `repository`
+     *  already means downstream, so its citations are never stamped. */
+    primary?: boolean;
+}
+export interface SourceCitationInput {
+    /** Checkouts to resolve a citation against: the primary repo plus every related
+     *  repo in the run. Empty means no checkout is known — see below. */
+    checkouts: RepoCheckout[];
+    /** LLM-supplied issuesFound entries in submission order. The index is quoted back
+     *  to the agent so it can find the entry it has to fix. */
+    issues: {
+        sourceFile?: string;
+        sourceSymbol?: string;
+        repository?: string;
+    }[];
+}
+export interface SourceCitationCheck {
+    /** One message per DEFINITE mismatch. Empty means the citations may ship. */
+    invalid: string[];
+    /** owner/repo to stamp on the entry at the same index of `issues`, or undefined
+     *  to ship the attribution exactly as submitted. */
+    repository: (string | undefined)[];
+}
+/**
+ * Check every `sourceFile`/`sourceSymbol` citation on the submitted issuesFound
+ * entries against the repository, and say which repo each one belongs to.
+ * Returns one message per DEFINITE mismatch — an empty `invalid` means the report
+ * may be written — plus, per entry, the owner/repo the citation resolved in.
+ *
+ * The attribution is the reason this resolves against every checkout instead of
+ * the first hit: the consumer must not have to guess a cited file's repo from the
+ * path, which is what makes it link the primary repo's copy of a related repo's
+ * file. Where the citation resolves is the answer, so it is returned rather than
+ * discarded. Only a related repo is stamped: an absent `repository` already means
+ * the primary repo downstream, so a primary-repo citation ships as submitted.
+ *
+ * Rejects four things: a path that no known checkout contains, a symbol absent
+ * from the file that was found, an attribution that names a different repo than
+ * the one holding the code, and a file that resolves in several named checkouts
+ * with no attribution to choose between them. Everything uncertain is ACCEPTED —
+ * no checkout, an unreadable file, a checkout with no owner/repo, a directory
+ * listing that fails. The check must behave the same on any repo, in any
+ * language, at any size, and it must never become a loop the agent cannot exit.
+ * Symbol matching is a plain substring search for the same reason: no parser, so
+ * no language it silently mishandles.
+ */
+export declare function findInvalidSourceCitations(input: SourceCitationInput): Promise<SourceCitationCheck>;