@skyramp/mcp 0.3.1 → 0.3.2-rc.pom-2

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

@@ -0,0 +1,57 @@
+/**
+ * Extracts selector *value tokens* from a generated test's source. Tokens are
+ * the join key between the raw spec and the POM layer: we grep POM files for
+ * these strings to find which page objects cover the test's actions.
+ */
+// Default test-id attribute family. Playwright's own default is data-testid, but
+// data-test/data-qa/data-cy are common conventions in the wild — match them all.
+export const DEFAULT_TESTID_ATTRS = ["data-test", "data-testid", "data-qa", "data-cy"];
+// Full regex-escape for attr names — a config-supplied testIdAttribute could contain
+// a stray metachar, which must not be allowed to distort the pattern.
+const esc = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+// [data-test="X"] incl. prefix/suffix matchers; allows embedded escapes (\\/)
+// but a backslash pair may not consume a quote, so the escaped closing \" terminates
+const attrPattern = (attrs) => new RegExp(`\\[(?:${attrs.map(esc).join("|")})[$^*~|]?=\\\\?["']((?:\\\\[^"']|[^"'\\\\\\]])+)`, "g");
+// Attribute-shaped anchor (no captured value) used to detect whether a raw locator
+// 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.
+];
+// 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
+// (and vice versa) — the common has-text('...') / has-text("...") idiom nests the
+// other quote character. Each branch allows escapes (\\.) or any char but its own
+// quote/backslash.
+const RAW_LOCATOR = /\.(?:locator|frameLocator)\(\s*(?:"((?:\\.|[^"\\])+)"|'((?:\\.|[^'\\])+)')\s*\)/g;
+function normalize(token) {
+    return token.replace(/\\/g, "");
+}
+function isUseful(token) {
+    return token.length >= 3 && !/^\d+$/.test(token);
+}
+export function extractSelectors(specContent, 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 m of specContent.matchAll(re)) {
+            const t = normalize(m[1]);
+            if (isUseful(t))
+                tokens.add(t);
+        }
+    }
+    for (const m of specContent.matchAll(RAW_LOCATOR)) {
+        const raw = normalize(m[1] ?? m[2]);
+        if (anchor.test(raw))
+            continue; // value already captured above
+        if (isUseful(raw))
+            tokens.add(raw);
+    }
+    return [...tokens];
+}

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

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,67 @@
+import { extractSelectors } from "./selector-extractor.js";
+describe("extractSelectors", () => {
+    it("extracts data-test attribute values", () => {
+        const spec = `await page.locator("[data-test=\\"login-sign-in\\"]").click();
+await page.locator('[data-test="add-template-name-input-field"]').fill("x");`;
+        const t = extractSelectors(spec);
+        expect(t).toContain("login-sign-in");
+        expect(t).toContain("add-template-name-input-field");
+    });
+    it("extracts getByTestId / getByRole / getByText tokens", () => {
+        const spec = `page.getByTestId("tpl-add");
+page.getByRole("button", { name: "Save Template" });
+page.getByText("Templates");`;
+        const t = extractSelectors(spec);
+        expect(t).toEqual(expect.arrayContaining(["tpl-add", "button", "Save Template", "Templates"]));
+    });
+    it("normalizes escaped slashes and dedupes", () => {
+        const spec = `page.locator("[data-test=\\"menu-link-\\\\/alerts-item\\"]");
+page.locator('[data-test="menu-link-/alerts-item"]');`;
+        const t = extractSelectors(spec);
+        expect(t.filter((x) => x === "menu-link-/alerts-item")).toHaveLength(1);
+        expect(t).not.toContain("menu-link-");
+    });
+    it("extracts values from prefix/suffix data-test matchers", () => {
+        const spec = `page.locator('[data-test^="ai-integrations-item-"]'); page.locator('[data-test*="row-cell"]');`;
+        const t = extractSelectors(spec);
+        expect(t).toEqual(expect.arrayContaining(["ai-integrations-item-", "row-cell"]));
+    });
+    it("keeps non-data-test raw locator strings, drops short/numeric tokens", () => {
+        const spec = `page.locator(".step-deduplication"); page.locator("#a"); page.getByText("42");`;
+        const t = extractSelectors(spec);
+        expect(t).toContain(".step-deduplication");
+        expect(t).not.toContain("#a");
+        expect(t).not.toContain("42");
+    });
+    it("returns [] for content with no selectors", () => {
+        expect(extractSelectors("const x = 1;")).toEqual([]);
+    });
+    it("matches the test-id attribute family (data-testid default, data-qa, data-cy)", () => {
+        const spec = `page.locator('[data-testid="submit-order"]'); page.locator('[data-qa="cart-total"]'); page.locator('[data-cy="nav-home"]');`;
+        const t = extractSelectors(spec);
+        expect(t).toEqual(expect.arrayContaining(["submit-order", "cart-total", "nav-home"]));
+    });
+    it("accepts extra custom attributes", () => {
+        const t = extractSelectors(`page.locator('[data-pw="widget-x"]');`, ["data-pw"]);
+        expect(t).toContain("widget-x");
+    });
+    it("keeps raw css locators that merely contain a family-attr substring", () => {
+        const t = extractSelectors(`page.locator(".data-testing-notes"); page.locator(".data-qatar-widget"); page.locator(".data-cycle-indicator");`);
+        expect(t).toEqual(expect.arrayContaining([".data-testing-notes", ".data-qatar-widget", ".data-cycle-indicator"]));
+    });
+    it("matches locator strings containing the other quote type (has-text idiom)", () => {
+        const spec = `page.locator('button:has-text("資産登録")'); page.locator("li:has-text('確認')");`;
+        const t = extractSelectors(spec);
+        expect(t).toEqual(expect.arrayContaining(['button:has-text("資産登録")', "li:has-text('確認')"]));
+    });
+    it("still dedups bracketed test-id raw locators regardless of quote nesting", () => {
+        const t = extractSelectors(`page.locator('[data-test="pay-now"]');`);
+        expect(t).toEqual(["pay-now"]); // attribute value only — raw form still skipped
+    });
+    it("extracts frameLocator selector args (iframe-scoped POM evidence)", () => {
+        const spec = `page.frameLocator('iframe#asset-list').locator('button:has-text("資産登録")').click();
+page.frameLocator("#application-new-applied").getByRole("button", { name: "提出" });`;
+        const t = extractSelectors(spec);
+        expect(t).toEqual(expect.arrayContaining(["iframe#asset-list", "#application-new-applied", 'button:has-text("資産登録")']));
+    });
+});

package/build/utils/pom-verify/__fixtures__/af-style/asset-list.page.d.ts

@@ -0,0 +1,5 @@
+import { WorkflowFooter } from './workflow-footer.page.js';
+export declare class AssetListPage {
+    readonly footer: WorkflowFooter;
+    constructor(page: any);
+}

package/build/utils/pom-verify/__fixtures__/af-style/asset-list.page.js

@@ -0,0 +1,5 @@
+import { WorkflowFooter } from './workflow-footer.page.js';
+export class AssetListPage {
+    footer;
+    constructor(page) { this.footer = new WorkflowFooter(page); }
+}

package/build/utils/pom-verify/__fixtures__/af-style/pageobjects/asset-list-page.d.ts

@@ -0,0 +1,5 @@
+export declare class AssetListPage {
+    searchBtn: any;
+    constructor(page: any);
+    clickSearch(): void;
+}

package/build/utils/pom-verify/__fixtures__/af-style/pageobjects/asset-list-page.js

@@ -0,0 +1,9 @@
+export class AssetListPage {
+    searchBtn;
+    constructor(page) {
+        this.searchBtn = page.locator('[data-test="search-btn"]');
+    }
+    clickSearch() {
+        this.searchBtn.click();
+    }
+}

package/build/utils/pom-verify/__fixtures__/af-style/report.iframe.page.d.ts

@@ -0,0 +1,4 @@
+export declare class ReportIframePage {
+    readonly exportBtn: any;
+    constructor(frame: any);
+}

package/build/utils/pom-verify/__fixtures__/af-style/report.iframe.page.js

@@ -0,0 +1,4 @@
+export class ReportIframePage {
+    exportBtn;
+    constructor(frame) { this.exportBtn = frame.locator('[data-test="export-btn"]'); }
+}

package/build/utils/pom-verify/__fixtures__/af-style/workflow-footer.page.d.ts

@@ -0,0 +1,4 @@
+export declare class WorkflowFooter {
+    readonly okBtn: any;
+    constructor(page: any);
+}

package/build/utils/pom-verify/__fixtures__/af-style/workflow-footer.page.js

@@ -0,0 +1,4 @@
+export class WorkflowFooter {
+    okBtn;
+    constructor(page) { this.okBtn = page.locator('[data-test="footer-ok-btn"]'); }
+}

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

@@ -0,0 +1,19 @@
+export type PomBinding = {
+    kind: "instance";
+    name: string;
+    classFile: string;
+} | {
+    kind: "function";
+    name: string;
+    sourceFile: string;
+};
+export declare function extractPomBindings(specContent: string, opts: {
+    specDir: string;
+    pomFiles: string[];
+    pageManagerFile?: string;
+    /** Prefix -> absolute dir, for resolving non-relative specifiers (tsconfig/jsconfig `paths`). */
+    aliasMap?: Record<string, string>;
+}): Promise<{
+    bindings: PomBinding[];
+    unrecognized: string[];
+}>;

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

@@ -0,0 +1,161 @@
+import { readFile } from "fs/promises";
+import * as path from "path";
+import { stripComments, stripStrings } from "./strip.js";
+/** Matches `import { A, B } from '<ref>'` and `const { A, B } = require('<ref>')`. */
+const IMPORT_RE = /import\s*\{([^}]+)\}\s*from\s*["']([^"']+)["']|const\s*\{([^}]+)\}\s*=\s*require\(\s*["']([^"']+)["']\s*\)/g;
+/** Matches `import X from '<ref>'` (default import) and `const X = require('<ref>')` (non-destructured). */
+const DEFAULT_IMPORT_RE = /import\s+(\w+)\s*from\s*["']([^"']+)["']|const\s+(\w+)\s*=\s*require\(\s*["']([^"']+)["']\s*\)/g;
+/** `const v = new ClassName(...)` / `let` / `var`. */
+const NEW_RE = /\b(?:const|let|var)\s+(\w+)\s*=\s*new\s+(\w+)\s*\(/g;
+/** Inside a page-manager file: `this.member = new ClassName(...)`. */
+const PM_MEMBER_RE = /this\.(\w+)\s*=\s*new\s+(\w+)\s*\(/g;
+function escapeRegExp(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/** One-hop import resolution against the known POM set (no existence check beyond membership).
+ * Relative specifiers (`./`, `../`) resolve against `fromDir`; non-relative specifiers resolve
+ * through `aliasMap` (longest-prefix match, e.g. `@pageobjects/*` -> an absolute dir) when given. */
+function resolveAgainstPomSet(fromDir, ref, pomSet, aliasMap) {
+    let base;
+    if (ref.startsWith(".")) {
+        base = path.resolve(fromDir, ref);
+    }
+    else if (aliasMap) {
+        const prefix = Object.keys(aliasMap)
+            .filter((p) => ref === p || ref.startsWith(`${p}/`))
+            .sort((a, b) => b.length - a.length)[0];
+        if (!prefix)
+            return undefined;
+        base = path.resolve(aliasMap[prefix], ref.slice(prefix.length).replace(/^\//, ""));
+    }
+    else {
+        return undefined;
+    }
+    for (const cand of [base, `${base}.ts`, `${base}.js`, base.replace(/\.js$/, ".ts")]) {
+        if (pomSet.has(cand))
+            return cand;
+    }
+    return undefined;
+}
+/** Parses `import {...} from '...'` / `require(...)` (named/destructured) and `import X from '...'` /
+ * `const X = require('...')` (default/non-destructured) statements, mapping each local name to its
+ * resolved POM file (or `undefined` if imported but not a recognized POM file). */
+function collectImportMap(content, fromDir, pomSet, aliasMap) {
+    const importMap = new Map();
+    for (const m of content.matchAll(IMPORT_RE)) {
+        const names = m[1] ?? m[3];
+        const ref = m[2] ?? m[4];
+        if (!names || !ref)
+            continue;
+        const resolved = resolveAgainstPomSet(fromDir, ref, pomSet, aliasMap);
+        for (const raw of names.split(",")) {
+            const name = raw.trim();
+            if (name)
+                importMap.set(name, resolved);
+        }
+    }
+    for (const m of content.matchAll(DEFAULT_IMPORT_RE)) {
+        const name = m[1] ?? m[3];
+        const ref = m[2] ?? m[4];
+        if (!name || !ref)
+            continue;
+        importMap.set(name, resolveAgainstPomSet(fromDir, ref, pomSet, aliasMap));
+    }
+    return importMap;
+}
+export async function extractPomBindings(specContent, opts) {
+    const pomSet = new Set(opts.pomFiles);
+    const bindings = [];
+    const seenBindings = new Set();
+    const unrecognized = [];
+    const seenUnrecognized = new Set();
+    const pushBinding = (b) => {
+        const key = `${b.kind}:${b.name}`;
+        if (seenBindings.has(key))
+            return;
+        seenBindings.add(key);
+        bindings.push(b);
+    };
+    const pushUnrecognized = (s) => {
+        if (seenUnrecognized.has(s))
+            return;
+        seenUnrecognized.add(s);
+        unrecognized.push(s);
+    };
+    // Strip comments first (string/template literals stay intact so a real import's quoted path
+    // is still readable), collect imports, then blank strings too before scanning for `new`/call/
+    // pm-var syntax -- so neither commented-out code nor code-shaped prose sitting inside a JS
+    // string can be mistaken for a real binding.
+    const specNoComments = stripComments(specContent);
+    const importMap = collectImportMap(specNoComments, opts.specDir, pomSet, opts.aliasMap);
+    const spec = stripStrings(specNoComments);
+    // `new ClassName(...)` assigned to a variable -> instance binding (or unrecognized if the
+    // imported class isn't a recognized POM file).
+    const usedWithNew = new Set();
+    for (const m of spec.matchAll(NEW_RE)) {
+        const [, varName, className] = m;
+        usedWithNew.add(className);
+        if (!importMap.has(className))
+            continue; // not an imported name at all -- not our concern
+        const resolved = importMap.get(className);
+        if (resolved) {
+            pushBinding({ kind: "instance", name: varName, classFile: resolved });
+        }
+        else {
+            pushUnrecognized(varName);
+        }
+    }
+    // Imported names resolving to a POM file, never used with `new`, called directly -> free function.
+    for (const [name, resolved] of importMap) {
+        if (!resolved || usedWithNew.has(name))
+            continue;
+        const directCallRe = new RegExp(`(?<!\\.)\\b${escapeRegExp(name)}\\s*\\(`);
+        if (directCallRe.test(spec)) {
+            pushBinding({ kind: "function", name, sourceFile: resolved });
+        }
+    }
+    // Page-manager convention: `this.member = new Class(...)` inside pageManagerFile, exposed as
+    // `<pmVar>.<member>` bindings for every `const <pmVar> = new PageManager(...)` in the spec.
+    if (opts.pageManagerFile) {
+        let pmContentRaw;
+        try {
+            pmContentRaw = await readFile(opts.pageManagerFile, "utf8");
+        }
+        catch {
+            pmContentRaw = undefined;
+        }
+        if (pmContentRaw) {
+            const pmNoComments = stripComments(pmContentRaw);
+            const pmImportMap = collectImportMap(pmNoComments, path.dirname(opts.pageManagerFile), pomSet, opts.aliasMap);
+            const pmContent = stripStrings(pmNoComments);
+            // `export class X` (ESM) or plain `class X { ... } ... module.exports = X` (CJS, the real
+            // oo-testbed convention) -- the `export` keyword is optional.
+            const pmClassName = pmContent.match(/(?:export\s+)?class\s+(\w+)/)?.[1];
+            if (pmClassName) {
+                const pmVarRe = new RegExp(`\\b(?:const|let|var)\\s+(\\w+)\\s*=\\s*new\\s+${escapeRegExp(pmClassName)}\\s*\\(`, "g");
+                const pmVars = [...spec.matchAll(pmVarRe)].map((m) => m[1]);
+                if (pmVars.length > 0) {
+                    const memberMap = new Map();
+                    for (const m of pmContent.matchAll(PM_MEMBER_RE)) {
+                        const [, member, className] = m;
+                        const resolved = pmImportMap.get(className);
+                        if (resolved)
+                            memberMap.set(member, resolved);
+                    }
+                    for (const pmVar of pmVars) {
+                        for (const [member, classFile] of memberMap) {
+                            pushBinding({ kind: "instance", name: `${pmVar}.${member}`, classFile });
+                        }
+                        const accessRe = new RegExp(`\\b${escapeRegExp(pmVar)}\\.(\\w+)`, "g");
+                        for (const am of spec.matchAll(accessRe)) {
+                            const member = am[1];
+                            if (!memberMap.has(member))
+                                pushUnrecognized(`${pmVar}.${member}`);
+                        }
+                    }
+                }
+            }
+        }
+    }
+    return { bindings, unrecognized };
+}

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

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,164 @@
+import * as path from "path";
+import { fileURLToPath } from "url";
+import { extractPomBindings } from "./bindings.js";
+const OO = path.join(path.dirname(fileURLToPath(import.meta.url)), "__fixtures__", "oo-style");
+const AF = path.join(path.dirname(fileURLToPath(import.meta.url)), "__fixtures__", "af-style");
+const OO_POM_FILES = [
+    path.join(OO, "page-manager.js"),
+    path.join(OO, "loginPage.js"),
+    path.join(OO, "widgetsPage.js"),
+    path.join(OO, "widgetHelpers.js"),
+    path.join(OO, "commonActions.js"),
+];
+const AF_POM_FILES = [
+    path.join(AF, "asset-list.page.ts"),
+    path.join(AF, "workflow-footer.page.ts"),
+    path.join(AF, "report.iframe.page.ts"),
+];
+describe("extractPomBindings -- oo-style (page-manager convention)", () => {
+    it("binds every <pm>.<member> when the spec instantiates the page manager", async () => {
+        const spec = `
+      import { PageManager } from './page-manager.js';
+      const pm = new PageManager(page);
+      await pm.loginPage.signIn.click();
+    `;
+        const { bindings, unrecognized } = await extractPomBindings(spec, {
+            specDir: OO,
+            pomFiles: OO_POM_FILES,
+            pageManagerFile: path.join(OO, "page-manager.js"),
+        });
+        expect(bindings).toEqual(expect.arrayContaining([
+            { kind: "instance", name: "pm.loginPage", classFile: path.join(OO, "loginPage.js") },
+            { kind: "instance", name: "pm.widgetsPage", classFile: path.join(OO, "widgetsPage.js") },
+        ]));
+        expect(unrecognized).toEqual([]);
+    });
+    it("flags an unknown page-manager member as unrecognized instead of fabricating a binding", async () => {
+        const spec = `
+      import { PageManager } from './page-manager.js';
+      const pm = new PageManager(page);
+      await pm.reportsPage.export();
+    `;
+        const { bindings, unrecognized } = await extractPomBindings(spec, {
+            specDir: OO,
+            pomFiles: OO_POM_FILES,
+            pageManagerFile: path.join(OO, "page-manager.js"),
+        });
+        expect(bindings.some((b) => b.name.includes("reportsPage"))).toBe(false);
+        expect(unrecognized).toContain("pm.reportsPage");
+    });
+    it("binds a direct `new` instantiation of an imported POM class (no page manager)", async () => {
+        const spec = `
+      import { LoginPage } from './loginPage.js';
+      const login = new LoginPage(page);
+      await login.signIn.click();
+    `;
+        const { bindings, unrecognized } = await extractPomBindings(spec, { specDir: OO, pomFiles: OO_POM_FILES });
+        expect(bindings).toEqual([{ kind: "instance", name: "login", classFile: path.join(OO, "loginPage.js") }]);
+        expect(unrecognized).toEqual([]);
+    });
+    it("binds an imported free function used as a direct call", async () => {
+        const spec = `
+      import { openNavFlyout } from './commonActions.js';
+      await openNavFlyout(page);
+    `;
+        const { bindings, unrecognized } = await extractPomBindings(spec, { specDir: OO, pomFiles: OO_POM_FILES });
+        expect(bindings).toEqual([{ kind: "function", name: "openNavFlyout", sourceFile: path.join(OO, "commonActions.js") }]);
+        expect(unrecognized).toEqual([]);
+    });
+    it("never fabricates a binding for `new` on an import that isn't a recognized POM file", async () => {
+        const spec = `
+      import { HelperNonPom } from './helperNonPom.js';
+      const helper = new HelperNonPom();
+    `;
+        // helperNonPom.js intentionally excluded from pomFiles -- it's a non-POM utility.
+        const { bindings, unrecognized } = await extractPomBindings(spec, { specDir: OO, pomFiles: OO_POM_FILES });
+        expect(bindings).toEqual([]);
+        expect(unrecognized).toContain("helper");
+    });
+    it("ignores commented-out import/new/call syntax instead of fabricating a binding from it", async () => {
+        const spec = `
+      // import { LoginPage } from './loginPage.js'; const login = new LoginPage(page);
+      /* const helper2 = new LoginPage(page); */
+      const note = "import { LoginPage } from './loginPage.js'; const login2 = new LoginPage(page);";
+      import { openNavFlyout } from './commonActions.js';
+      // await openNavFlyout(page);
+    `;
+        const { bindings, unrecognized } = await extractPomBindings(spec, { specDir: OO, pomFiles: OO_POM_FILES });
+        expect(bindings).toEqual([]);
+        expect(unrecognized).toEqual([]);
+    });
+});
+describe("extractPomBindings -- oo-style (CJS page-manager convention)", () => {
+    it("binds pm.<member> from a page-manager file with no `export` on its class, a default import, and an extensionless require -- the real oo-testbed shape", async () => {
+        const spec = `
+      const PageManager = require('./page-manager-cjs.js');
+      const pm = new PageManager(page);
+      await pm.loginPage.signInAs(user);
+      await pm.widgetsPage.toggle('foo');
+    `;
+        const { bindings, unrecognized } = await extractPomBindings(spec, {
+            specDir: OO,
+            pomFiles: [...OO_POM_FILES, path.join(OO, "page-manager-cjs.js")],
+            pageManagerFile: path.join(OO, "page-manager-cjs.js"),
+        });
+        expect(bindings).toEqual(expect.arrayContaining([
+            { kind: "instance", name: "pm.loginPage", classFile: path.join(OO, "loginPage.js") },
+            { kind: "instance", name: "pm.widgetsPage", classFile: path.join(OO, "widgetsPage.js") },
+        ]));
+        expect(unrecognized).toEqual([]);
+    });
+});
+describe("extractPomBindings -- alias-import resolution", () => {
+    const AF_PAGEOBJECTS = path.join(AF, "pageobjects");
+    const ASSET_LIST_ALIAS_FILE = path.join(AF_PAGEOBJECTS, "asset-list-page.ts");
+    it("resolves a non-relative specifier through aliasMap when the target is a recognized POM file", async () => {
+        const spec = `
+      import { AssetListPage } from '@pageobjects/asset-list-page';
+      const list = new AssetListPage(page);
+      await list.clickSearch();
+    `;
+        const { bindings, unrecognized } = await extractPomBindings(spec, {
+            specDir: AF,
+            pomFiles: [ASSET_LIST_ALIAS_FILE],
+            aliasMap: { "@pageobjects": AF_PAGEOBJECTS },
+        });
+        expect(bindings).toEqual([{ kind: "instance", name: "list", classFile: ASSET_LIST_ALIAS_FILE }]);
+        expect(unrecognized).toEqual([]);
+    });
+    it("never fabricates a binding through an alias when the resolved file isn't in pomFiles (safety contract)", async () => {
+        const spec = `
+      import { AssetListPage } from '@pageobjects/asset-list-page';
+      const list = new AssetListPage(page);
+    `;
+        const { bindings, unrecognized } = await extractPomBindings(spec, {
+            specDir: AF,
+            pomFiles: [], // asset-list-page.ts intentionally excluded
+            aliasMap: { "@pageobjects": AF_PAGEOBJECTS },
+        });
+        expect(bindings).toEqual([]);
+        expect(unrecognized).toContain("list");
+    });
+});
+describe("extractPomBindings -- af-style (direct instantiation)", () => {
+    it("binds a direct-instantiation class with a component property chain", async () => {
+        const spec = `
+      import { AssetListPage } from './asset-list.page.js';
+      const list = new AssetListPage(page);
+      await list.footer.okBtn.click();
+    `;
+        const { bindings, unrecognized } = await extractPomBindings(spec, { specDir: AF, pomFiles: AF_POM_FILES });
+        expect(bindings).toEqual([{ kind: "instance", name: "list", classFile: path.join(AF, "asset-list.page.ts") }]);
+        expect(unrecognized).toEqual([]);
+    });
+    it("binds a direct-instantiation iframe-scoped class the same way", async () => {
+        const spec = `
+      import { ReportIframePage } from './report.iframe.page.js';
+      const report = new ReportIframePage(frame);
+      await report.exportBtn.click();
+    `;
+        const { bindings, unrecognized } = await extractPomBindings(spec, { specDir: AF, pomFiles: AF_POM_FILES });
+        expect(bindings).toEqual([{ kind: "instance", name: "report", classFile: path.join(AF, "report.iframe.page.ts") }]);
+        expect(unrecognized).toEqual([]);
+    });
+});

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

@@ -0,0 +1,16 @@
+import type { PomBinding } from "./bindings.js";
+export type PomCall = {
+    binding: string;
+    chain: string[];
+    strict: boolean;
+};
+/**
+ * For each binding, finds member-access chains off its name in the spec: `name.method(...)`,
+ * `name.a.b(...)`, and bare property reads like `expect(name.toast)` (property-only uses count
+ * as calls too). Chains are matched greedily (longest run of `.identifier` segments per
+ * occurrence), and bindings are matched longest-name-first with the matched span "consumed" so a
+ * shorter binding name that happens to be a suffix of a longer one (e.g. `loginPage` vs.
+ * `pm.loginPage`) can't double-count the same occurrence. Comments and string/template literals
+ * are blanked out first so prose mentioning a binding's name never fabricates a call.
+ */
+export declare function extractPomCalls(specContent: string, bindings: PomBinding[]): PomCall[];

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

@@ -0,0 +1,42 @@
+import { stripCommentsAndStrings } from "./strip.js";
+function escapeRegExp(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/**
+ * For each binding, finds member-access chains off its name in the spec: `name.method(...)`,
+ * `name.a.b(...)`, and bare property reads like `expect(name.toast)` (property-only uses count
+ * as calls too). Chains are matched greedily (longest run of `.identifier` segments per
+ * occurrence), and bindings are matched longest-name-first with the matched span "consumed" so a
+ * shorter binding name that happens to be a suffix of a longer one (e.g. `loginPage` vs.
+ * `pm.loginPage`) can't double-count the same occurrence. Comments and string/template literals
+ * are blanked out first so prose mentioning a binding's name never fabricates a call.
+ */
+export function extractPomCalls(specContent, bindings) {
+    const content = stripCommentsAndStrings(specContent);
+    const sorted = [...bindings].sort((a, b) => b.name.length - a.name.length);
+    const consumed = [];
+    const isConsumed = (start) => consumed.some(([s, e]) => start >= s && start < e);
+    const seen = new Set();
+    const found = [];
+    for (const binding of sorted) {
+        const escaped = escapeRegExp(binding.name);
+        const pattern = binding.kind === "function"
+            ? new RegExp(`(?<!\\.)\\b${escaped}\\s*\\(`, "g")
+            : new RegExp(`\\b${escaped}((?:\\.[A-Za-z_$][\\w$]*)+)`, "g");
+        let m;
+        while ((m = pattern.exec(content))) {
+            const start = m.index;
+            const end = start + m[0].length;
+            if (isConsumed(start))
+                continue;
+            consumed.push([start, end]);
+            const chain = binding.kind === "function" ? [] : m[1].split(".").filter(Boolean);
+            const key = `${binding.name}|${chain.join(".")}`;
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            found.push({ binding: binding.name, chain, strict: chain.length <= 1, pos: start });
+        }
+    }
+    return found.sort((a, b) => a.pos - b.pos).map(({ binding, chain, strict }) => ({ binding, chain, strict }));
+}

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

@@ -0,0 +1 @@
+export {};