@skyramp/mcp 0.3.2 → 0.3.3

package/build/utils/gitStaging.d.ts

@@ -10,6 +10,11 @@ export declare function isInsideDir(child: string, parent: string): boolean;
  * is unset or the path is already inside it.
  */
 export declare function resolveOutputDir(outputDir: string, testsRepoDir: string | undefined): string;
+/**
+ * Detect the git repository root for a given file or directory path.
+ * Returns undefined if detection fails (not inside a git repo).
+ */
+export declare function detectGitRoot(filePath: string): string | undefined;
 /**
  * Stages a file path an MCP tool just wrote into the git index by
  * running `git add -- <path>`.

package/build/utils/gitStaging.js

@@ -33,7 +33,7 @@ const execFileAsync = promisify(execFile);
  * Detect the git repository root for a given file or directory path.
  * Returns undefined if detection fails (not inside a git repo).
  */
-function detectGitRoot(filePath) {
+export function detectGitRoot(filePath) {
     if (!path.isAbsolute(filePath))
         return undefined;
     try {

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

@@ -0,0 +1,23 @@
+export declare const POM_CATALOG_FILENAME = "skyramp-pom-catalog.md";
+/**
+ * The one canonical path for a test file's `skyramp-pom-catalog.md`:
+ * `<repoRoot>/.skyramp/skyramp-pom-catalog.md`.
+ *
+ * The catalog is cross-run state, and one path per repository is what keeps it
+ * usable — two runs writing at different depths fork the cache so neither finds
+ * the other's. It sits beside `workspace.yml` rather than in the customer's test
+ * directory because it is generated tooling state, not a deliverable, and
+ * delivery stages it by name (SKYR-4125).
+ *
+ * The root is resolved in priority order:
+ * 1. `getTestsRepoDir()` — the test-repo clone root set by `skyramp_analyze_changes`
+ *    when `testsRepoDir` is provided. In cross-repo delivery testbot commits ONLY
+ *    to this clone, so the catalog must anchor here or it is never staged and the
+ *    cache dies silently.
+ * 2. `detectGitRoot` — the fallback for same-repo runs (where nothing sets the
+ *    tests-repo dir) and for the NL path, where a developer drives
+ *    `skyramp_ui_test_generation`/`skyramp_reuse_code` directly without ever
+ *    calling `skyramp_analyze_changes`.
+ * 3. The test file's own directory, for a path in no repository at all.
+ */
+export declare function resolvePomCatalogPath(testFile: string): string;

package/build/utils/pom-catalog.js

@@ -0,0 +1,30 @@
+import path from "path";
+import { getTestsRepoDir } from "./AnalysisStateManager.js";
+import { detectGitRoot } from "./gitStaging.js";
+export const POM_CATALOG_FILENAME = "skyramp-pom-catalog.md";
+/**
+ * The one canonical path for a test file's `skyramp-pom-catalog.md`:
+ * `<repoRoot>/.skyramp/skyramp-pom-catalog.md`.
+ *
+ * The catalog is cross-run state, and one path per repository is what keeps it
+ * usable — two runs writing at different depths fork the cache so neither finds
+ * the other's. It sits beside `workspace.yml` rather than in the customer's test
+ * directory because it is generated tooling state, not a deliverable, and
+ * delivery stages it by name (SKYR-4125).
+ *
+ * The root is resolved in priority order:
+ * 1. `getTestsRepoDir()` — the test-repo clone root set by `skyramp_analyze_changes`
+ *    when `testsRepoDir` is provided. In cross-repo delivery testbot commits ONLY
+ *    to this clone, so the catalog must anchor here or it is never staged and the
+ *    cache dies silently.
+ * 2. `detectGitRoot` — the fallback for same-repo runs (where nothing sets the
+ *    tests-repo dir) and for the NL path, where a developer drives
+ *    `skyramp_ui_test_generation`/`skyramp_reuse_code` directly without ever
+ *    calling `skyramp_analyze_changes`.
+ * 3. The test file's own directory, for a path in no repository at all.
+ */
+export function resolvePomCatalogPath(testFile) {
+    const abs = path.resolve(testFile);
+    const root = getTestsRepoDir() ?? detectGitRoot(abs) ?? path.dirname(abs);
+    return path.join(root, ".skyramp", POM_CATALOG_FILENAME);
+}

package/build/utils/pom-scope/pom-files.d.ts

@@ -1,3 +1,17 @@
+/**
+ * Spec/test basenames. POM discovery excludes them; {@link globSpecFiles}
+ * targets them.
+ */
+export declare const SPEC_BASENAME: RegExp;
 export declare function globPomFiles(root: string): Promise<string[]>;
+/**
+ * Spec files anywhere under `root`, by basename rather than by directory.
+ *
+ * Suites are often grouped by feature or customer rather than under `tests/`
+ * (e.g. `box/workflow.spec.ts`), so the directory name gives nothing away — but
+ * the filename always does. Keeps the cypress/`__tests__` trees that POM
+ * discovery skips: here the tests are the subject, not the thing to skip past.
+ */
+export declare function globSpecFiles(root: string): Promise<string[]>;
 /** Fallback discovery for repos whose POM layer doesn't match the conventional glob patterns. */
 export declare function globAllSourceFiles(root: string): Promise<string[]>;

package/build/utils/pom-scope/pom-files.js

@@ -16,18 +16,24 @@ const POM_GLOBS = [
     "**/{test,tests,e2e,playwright}/**/{lib,utils,helpers,support}/**/*.{ts,js}",
     "**/{testUtils,test-utils,testHelpers,test-helpers}.{ts,js}",
 ];
-const EXCLUDED_BASENAME = /\.(spec|test|cy)\.(ts|js|tsx|jsx|mjs|cjs)$/;
+/**
+ * Spec/test basenames. POM discovery excludes them; {@link globSpecFiles}
+ * targets them.
+ */
+export const SPEC_BASENAME = /\.(spec|test|cy)\.(ts|js|tsx|jsx|mjs|cjs)$/;
 const ALL_SOURCE_GLOBS = ["**/*.{ts,js,tsx,jsx,mjs,cjs}"];
-const ALL_SOURCE_IGNORE = [
+/** Never source: dependencies, build output, VCS metadata. */
+const BUILD_IGNORE = [
     "**/node_modules/**",
     "**/dist/**",
     "**/build/**",
     "**/coverage/**",
     "**/.git/**",
     "**/vendor/**",
-    "**/cypress/**",
-    "**/__tests__/**",
 ];
+/** Test trees a POM is not expected to live in. Not skipped when the tests themselves are the subject. */
+const TEST_TREE_IGNORE = ["**/cypress/**", "**/__tests__/**"];
+const ALL_SOURCE_IGNORE = [...BUILD_IGNORE, ...TEST_TREE_IGNORE];
 export async function globPomFiles(root) {
     const matches = await fg(POM_GLOBS, {
         cwd: root,
@@ -37,7 +43,27 @@ export async function globPomFiles(root) {
         followSymbolicLinks: false,
     });
     return [...new Set(matches)]
-        .filter((f) => !EXCLUDED_BASENAME.test(path.basename(f)))
+        .filter((f) => !SPEC_BASENAME.test(path.basename(f)))
+        .sort();
+}
+/**
+ * Spec files anywhere under `root`, by basename rather than by directory.
+ *
+ * Suites are often grouped by feature or customer rather than under `tests/`
+ * (e.g. `box/workflow.spec.ts`), so the directory name gives nothing away — but
+ * the filename always does. Keeps the cypress/`__tests__` trees that POM
+ * discovery skips: here the tests are the subject, not the thing to skip past.
+ */
+export async function globSpecFiles(root) {
+    const matches = await fg(ALL_SOURCE_GLOBS, {
+        cwd: root,
+        absolute: true,
+        ignore: BUILD_IGNORE,
+        suppressErrors: true,
+        followSymbolicLinks: false,
+    });
+    return [...new Set(matches)]
+        .filter((f) => SPEC_BASENAME.test(path.basename(f)))
         .sort();
 }
 /** Fallback discovery for repos whose POM layer doesn't match the conventional glob patterns. */
@@ -50,6 +76,6 @@ export async function globAllSourceFiles(root) {
         followSymbolicLinks: false,
     });
     return [...new Set(matches)]
-        .filter((f) => !EXCLUDED_BASENAME.test(path.basename(f)))
+        .filter((f) => !SPEC_BASENAME.test(path.basename(f)))
         .sort();
 }

package/build/utils/pom-scope/testIdDiscovery.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Which attribute does this repository use for test ids?
+ *
+ * The blueprint capture anchors every element's xpath on a test-id attribute
+ * when it can find one, and assumes Playwright's `data-testid` otherwise. A repo
+ * using anything else gets no anchor and a positional xpath instead — which
+ * resolves at capture time and breaks later, so the miss is invisible.
+ *
+ * Enumerating popular names (`data-test`, `data-qa`, ...) only covers the repos
+ * someone thought of. The repository already answers the question itself: its
+ * page objects and specs name the attribute every time they select on it. So
+ * read the answer out of the selectors rather than guessing at it.
+ */
+export type AttributeCount = {
+    attribute: string;
+    count: number;
+};
+export type TestIdDiscovery = {
+    /** Most-used qualifying attribute, or undefined when nothing qualified. */
+    attribute?: string;
+    /** Every qualifying attribute with its selector count, most-used first. */
+    counts: AttributeCount[];
+    /**
+     * Most-used attributes overall, qualifying or not.
+     *
+     * The point of reporting these is the case no name rule can reach: a suite
+     * selecting on something arbitrary like `xyz-id` produces no qualifying
+     * candidate, and the miss is otherwise invisible. Printed on a miss, this names
+     * the attribute an operator would set explicitly.
+     */
+    observed: AttributeCount[];
+    filesScanned: number;
+};
+/**
+ * Report which test-id attribute this repository's page objects and specs use.
+ *
+ * Never throws: an unreadable tree yields no attribute, which leaves the capture
+ * on Playwright's default.
+ */
+export declare function discoverTestIdAttribute(root: string): Promise<TestIdDiscovery>;

package/build/utils/pom-scope/testIdDiscovery.js

@@ -0,0 +1,104 @@
+/**
+ * Which attribute does this repository use for test ids?
+ *
+ * The blueprint capture anchors every element's xpath on a test-id attribute
+ * when it can find one, and assumes Playwright's `data-testid` otherwise. A repo
+ * using anything else gets no anchor and a positional xpath instead — which
+ * resolves at capture time and breaks later, so the miss is invisible.
+ *
+ * Enumerating popular names (`data-test`, `data-qa`, ...) only covers the repos
+ * someone thought of. The repository already answers the question itself: its
+ * page objects and specs name the attribute every time they select on it. So
+ * read the answer out of the selectors rather than guessing at it.
+ */
+import { readFile } from "fs/promises";
+import { globPomFiles, globSpecFiles } from "./pom-files.js";
+import { DEFAULT_TESTID_ATTRS } from "./selector-extractor.js";
+/** Bound the read — a monorepo scan must not delay server startup. */
+const MAX_FILES = 400;
+const MAX_BYTES_PER_FILE = 256 * 1024;
+/**
+ * Attribute name inside an attribute selector: `[data-test="x"]`, `[qa-id='y']`.
+ *
+ * Deliberately open-ended, which is why it cannot reuse `selector-extractor`'s
+ * pattern: that one is built from a known attribute list to *extract values for
+ * attributes we already named*, whereas this has to surface names nobody listed.
+ */
+const ATTR_SELECTOR_RE = /\[\s*([A-Za-z][A-Za-z0-9_:-]*)\s*[~^$*|]?=\s*["']/g;
+/**
+ * Tokens by which an attribute name declares itself to be about testing.
+ *
+ * Matched as whole tokens, never as prefixes. `auto` is deliberately absent —
+ * it admitted `data-auto-play` and `data-auto-height`, and `automation` already
+ * covers the convention it was there for (`data-automation-id`).
+ */
+const TEST_TOKENS = new Set(["test", "testid", "tests", "qa", "cy", "cypress", "e2e", "automation"]);
+/**
+ * Whether a name plausibly denotes a test id.
+ *
+ * A name heuristic, safe only because of what it is applied to: an attribute the
+ * repository's own tests already select on. A name that is both used as a
+ * selector and self-describes as test-related is not going to be
+ * `data-testimonial`. Applied to raw DOM attributes the same rule would be
+ * reckless.
+ *
+ * Requiring a token is also what keeps the standard attributes out — `type`,
+ * `role`, `href`, `aria-label`, `placeholder` and the rest carry no such token,
+ * so no exclusion list is needed alongside this. (`autocomplete` tokenises as one
+ * word, so it does not match `auto`.)
+ */
+function looksLikeTestId(attr) {
+    const lower = attr.toLowerCase();
+    if (DEFAULT_TESTID_ATTRS.includes(lower))
+        return true;
+    const tokens = lower.split(/[^a-z0-9]+/).filter(Boolean);
+    if (tokens.some((t) => TEST_TOKENS.has(t)))
+        return true;
+    // Glued forms like `datatestid`. Anchored at the end on purpose: a
+    // `startsWith("test")` catch-all also admits `data-testimonial`, and since
+    // candidates are ranked by use count, a false positive used more often than
+    // the real attribute becomes the anchor for the whole repo.
+    return tokens.some((t) => t.endsWith("testid"));
+}
+const OBSERVED_REPORT_LIMIT = 5;
+/**
+ * Report which test-id attribute this repository's page objects and specs use.
+ *
+ * Never throws: an unreadable tree yields no attribute, which leaves the capture
+ * on Playwright's default.
+ */
+export async function discoverTestIdAttribute(root) {
+    let files;
+    try {
+        const [poms, specs] = await Promise.all([globPomFiles(root), globSpecFiles(root)]);
+        files = [...new Set([...poms, ...specs])].slice(0, MAX_FILES);
+    }
+    catch {
+        return { counts: [], observed: [], filesScanned: 0 };
+    }
+    const all = new Map();
+    for (const file of files) {
+        let content;
+        try {
+            content = (await readFile(file, "utf8")).slice(0, MAX_BYTES_PER_FILE);
+        }
+        catch {
+            continue;
+        }
+        for (const match of content.matchAll(ATTR_SELECTOR_RE)) {
+            const attr = match[1];
+            all.set(attr, (all.get(attr) ?? 0) + 1);
+        }
+    }
+    // Count first; name as a tiebreak so the result never depends on walk order.
+    const ranked = [...all.entries()]
+        .map(([attribute, count]) => ({ attribute, count }))
+        .sort((a, b) => b.count - a.count || a.attribute.localeCompare(b.attribute));
+    const counts = ranked.filter((c) => looksLikeTestId(c.attribute));
+    return {
+        attribute: counts[0]?.attribute,
+        counts,
+        observed: ranked.slice(0, OBSERVED_REPORT_LIMIT),
+        filesScanned: files.length,
+    };
+}

package/build/utils/reportVerification.d.ts

@@ -26,10 +26,12 @@ export interface UnbackedClaimsInput {
         fileName?: string;
         repository?: string;
     }[];
-    /** Maintenance verdicts (server-derived from skyramp_actions). */
+    /** Maintenance verdicts (server-derived from skyramp_actions). `pomFile`, when set, is
+     *  the file the edit actually lands in — see the UPDATE rule below. */
     verdicts: {
         action: DriftAction;
         testFilePath: string;
+        pomFile?: string;
     }[];
     /** owner/repo of the primary repo — used to exempt cross-repo newTest claims
      *  whose files live in a different checkout. */
@@ -46,7 +48,10 @@ export interface UnbackedClaimsInput {
  * edit (or drops the claim) rather than hallucinating it into the report.
  *
  * Only UPDATE verdicts are gated: an UPDATE is a targeted in-place edit that
- * reliably implies a working-tree change. Exemptions:
+ * reliably implies a working-tree change — in `pomFile` when the verdict names one,
+ * otherwise in `testFilePath`. For a POM-based test those are different files: the spec
+ * is what runs, the page object is what gets patched, so checking only `testFilePath`
+ * would reject maintenance that did land (SKYR-4129). Exemptions:
  *  - REGENERATE verdicts — on an EXTERNAL (user-authored Playwright/Cypress/RTL)
  *    test these are report-only (Skyramp can't auto-regenerate them; the developer
  *    acts manually), so no working-tree change is expected; and even an internal

package/build/utils/reportVerification.js

@@ -50,7 +50,10 @@ export async function listChangedFiles(repoRoot) {
  * edit (or drops the claim) rather than hallucinating it into the report.
  *
  * Only UPDATE verdicts are gated: an UPDATE is a targeted in-place edit that
- * reliably implies a working-tree change. Exemptions:
+ * reliably implies a working-tree change — in `pomFile` when the verdict names one,
+ * otherwise in `testFilePath`. For a POM-based test those are different files: the spec
+ * is what runs, the page object is what gets patched, so checking only `testFilePath`
+ * would reject maintenance that did land (SKYR-4129). Exemptions:
  *  - REGENERATE verdicts — on an EXTERNAL (user-authored Playwright/Cypress/RTL)
  *    test these are report-only (Skyramp can't auto-regenerate them; the developer
  *    acts manually), so no working-tree change is expected; and even an internal
@@ -96,8 +99,11 @@ export function findUnbackedClaims(input) {
         // change, and internal ones may regenerate to identical content.
         if (v.action !== DriftAction.Update)
             continue;
-        if (!isBacked(v.testFilePath)) {
-            unbacked.push(`testMaintenance ${v.action} claims an edit to "${path.basename(v.testFilePath)}", but that file has no working-tree change`);
+        // The edit target, not the spec: for a POM-based test the page object is what
+        // gets patched while testFilePath stays the spec (SKYR-4129).
+        const editTarget = v.pomFile ?? v.testFilePath;
+        if (!isBacked(editTarget)) {
+            unbacked.push(`testMaintenance ${v.action} claims an edit to "${path.basename(editTarget)}", but that file has no working-tree change`);
         }
     }
     return unbacked;

package/build/utils/versions.d.ts

@@ -1,4 +1,4 @@
-export declare const SKYRAMP_IMAGE_VERSION = "v1.3.37";
-export declare const EXECUTOR_DOCKER_IMAGE = "skyramp/executor:v1.3.37";
-export declare const WORKER_DOCKER_IMAGE = "skyramp/worker:v1.3.37";
+export declare const SKYRAMP_IMAGE_VERSION = "v1.3.38";
+export declare const EXECUTOR_DOCKER_IMAGE = "skyramp/executor:v1.3.38";
+export declare const WORKER_DOCKER_IMAGE = "skyramp/worker:v1.3.38";
 export declare const WORKER_CONTROL_PORT = 35142;

package/build/utils/versions.js

@@ -1,4 +1,4 @@
-export const SKYRAMP_IMAGE_VERSION = "v1.3.37";
+export const SKYRAMP_IMAGE_VERSION = "v1.3.38";
 export const EXECUTOR_DOCKER_IMAGE = `skyramp/executor:${SKYRAMP_IMAGE_VERSION}`;
 export const WORKER_DOCKER_IMAGE = `skyramp/worker:${SKYRAMP_IMAGE_VERSION}`;
 // Control port the Skyramp worker listens on (SDK `CONTAINER_PORT`).