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

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

@@ -0,0 +1,39 @@
+export declare const SELECTION_CAP = 10;
+export declare const FINAL_CAP = 25;
+export declare function findRoot(startDir: string): Promise<string>;
+/** Reads `use.testIdAttribute` out of a playwright.config.{js,ts,mjs,cjs} at root, if present. Never throws. */
+export declare function readTestIdAttribute(root: string): Promise<string | undefined>;
+export type ScopedPom = {
+    file: string;
+    score: number;
+    rareHits: number;
+    matchedTokens: string[];
+};
+export type ScopeResult = {
+    tier1: ScopedPom[];
+    tier2: ScopedPom[];
+    diagnostics: {
+        selectors: number;
+        pomFiles: number;
+        scoped: number;
+        /** How the POM set was found: conventional globs, selector-grep fallback (no conventional dirs matched),
+         * no discovery attempted/needed, or the repo was too large for the fallback scan to run. */
+        discovery: "globs" | "selector-grep" | "none" | "skipped-too-large";
+    };
+};
+/**
+ * Split candidates into tier1 (high relevance) / tier2 (supporting), capped at FINAL_CAP
+ * with lowest-score eviction. Note: the score arm uses strict `>` rather than the `>=`
+ * boundary — with `>=`, a candidate whose score lands exactly on maxScore/4 (an exact tie,
+ * not a rounding artifact — e.g. a token shared by exactly 4 files when another candidate's
+ * sole rare token is unique) would spuriously qualify for tier1 instead of tier2.
+ */
+export declare function tierAndCap(candidates: ScopedPom[], maxScore: number): {
+    tier1: ScopedPom[];
+    tier2: ScopedPom[];
+};
+/** Deterministic POM pre-scoping. tier1/tier2 both [] ⇒ caller must fall back to the unscoped prompt. */
+export declare function selectScopedPoms(opts: {
+    testFile: string;
+    specContent?: string;
+}): Promise<ScopeResult>;

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

@@ -0,0 +1,120 @@
+import { readFile, stat } from "fs/promises";
+import * as path from "path";
+import { extractSelectors, DEFAULT_TESTID_ATTRS } from "./selector-extractor.js";
+import { globPomFiles, globAllSourceFiles } from "./pom-files.js";
+import { scorePoms } from "./scoring.js";
+import { expandImports } from "./import-expansion.js";
+/** Beyond this many candidate source files, the selector-grep discovery fallback is skipped (too slow / too broad). */
+const DISCOVERY_FILE_CAP = 3000;
+export const SELECTION_CAP = 10;
+export const FINAL_CAP = 25;
+const PLAYWRIGHT_CONFIG_NAMES = ["playwright.config.ts", "playwright.config.js", "playwright.config.mjs", "playwright.config.cjs"];
+const TESTID_ATTRIBUTE_RE = /testIdAttribute\s*:\s*["']([^"']+)["']/;
+export async function findRoot(startDir) {
+    let dir = startDir;
+    for (let i = 0; i < 8; i++) {
+        for (const marker of ["package.json", "tsconfig.json", "jsconfig.json", ".git"]) {
+            try {
+                await stat(path.join(dir, marker));
+                return dir;
+            }
+            catch { /* keep walking */ }
+        }
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return startDir;
+}
+/** Reads `use.testIdAttribute` out of a playwright.config.{js,ts,mjs,cjs} at root, if present. Never throws. */
+export async function readTestIdAttribute(root) {
+    for (const name of PLAYWRIGHT_CONFIG_NAMES) {
+        try {
+            const content = await readFile(path.join(root, name), "utf8");
+            const m = content.match(TESTID_ATTRIBUTE_RE);
+            if (m)
+                return m[1];
+        }
+        catch { /* try next filename */ }
+    }
+    return undefined;
+}
+/**
+ * Split candidates into tier1 (high relevance) / tier2 (supporting), capped at FINAL_CAP
+ * with lowest-score eviction. Note: the score arm uses strict `>` rather than the `>=`
+ * boundary — with `>=`, a candidate whose score lands exactly on maxScore/4 (an exact tie,
+ * not a rounding artifact — e.g. a token shared by exactly 4 files when another candidate's
+ * sole rare token is unique) would spuriously qualify for tier1 instead of tier2.
+ */
+export function tierAndCap(candidates, maxScore) {
+    const kept = [...candidates].sort((a, b) => b.score - a.score).slice(0, FINAL_CAP);
+    const tier1 = kept.filter((c) => c.score > maxScore / 4 || c.rareHits >= 2);
+    const tier2 = kept.filter((c) => !tier1.includes(c));
+    return { tier1, tier2 };
+}
+/** Deterministic POM pre-scoping. tier1/tier2 both [] ⇒ caller must fall back to the unscoped prompt. */
+export async function selectScopedPoms(opts) {
+    const empty = (selectors = 0, pomFiles = 0, discovery = "none") => ({ tier1: [], tier2: [], diagnostics: { selectors, pomFiles, scoped: 0, discovery } });
+    let spec = opts.specContent ?? "";
+    try {
+        spec = await readFile(opts.testFile, "utf8");
+    }
+    catch { /* use provided specContent */ }
+    const root = await findRoot(path.dirname(opts.testFile));
+    const testIdAttribute = await readTestIdAttribute(root);
+    const extraTestIdAttrs = testIdAttribute && !DEFAULT_TESTID_ATTRS.includes(testIdAttribute) ? [testIdAttribute] : [];
+    const selectors = extractSelectors(spec, extraTestIdAttrs);
+    if (selectors.length === 0)
+        return empty();
+    // Conventional dirs/names first. Fall back to a repo-wide selector grep when either:
+    // (a) no conventional dirs matched at all (e.g. a `screens/`-only POM layer), or
+    // (b) conventional dirs matched but scored zero overlap with this test's selectors — e.g. a
+    //     `screens/` POM coexists with an unrelated `pages/` POM, and glob-scoping alone would
+    //     silently miss it AND falsely claim "no repo-wide overlap" when only `pages/` was scored.
+    let discovery = "globs";
+    let pomFiles = await globPomFiles(root);
+    let ranked = pomFiles.length > 0 ? await scorePoms(selectors, pomFiles) : [];
+    // Universe for import-expansion recall: conventional files ∪ any discovery-fresh files scanned
+    // (even ones that scored 0 selectors themselves) -- so expandImports can still pull in a
+    // zero-overlap base/helper class that a discovered POM imports. pomFiles alone (scored matches
+    // only) would silently exclude that base class from the expansion universe.
+    let expansionUniverse = pomFiles;
+    if (pomFiles.length === 0 || ranked.length === 0) {
+        const conventional = new Set(pomFiles); // already proved to score 0 (if non-empty) — skip re-reading
+        const all = await globAllSourceFiles(root);
+        const fresh = all.filter((f) => !conventional.has(f));
+        if (fresh.length > DISCOVERY_FILE_CAP) {
+            discovery = "skipped-too-large";
+            pomFiles = [];
+            ranked = [];
+        }
+        else {
+            ranked = await scorePoms(selectors, fresh);
+            pomFiles = ranked.map((r) => r.file); // only files containing >=1 selector
+            expansionUniverse = [...new Set([...expansionUniverse, ...fresh])];
+            discovery = pomFiles.length > 0 ? "selector-grep" : "none";
+        }
+    }
+    if (pomFiles.length === 0 || ranked.length === 0)
+        return empty(selectors.length, pomFiles.length, discovery);
+    const maxScore = ranked[0].score;
+    const selected = ranked
+        .filter((r) => r.score >= maxScore / 10 || r.rareHits >= 1)
+        .slice(0, SELECTION_CAP)
+        .map((r) => r.file);
+    const rankedByFile = new Map(ranked.map((r) => [r.file, r]));
+    const expanded = await expandImports(selected, expansionUniverse);
+    const candidates = expanded.map(({ file, referrer }) => {
+        const own = rankedByFile.get(file);
+        if (own)
+            return { file: own.file, score: own.score, rareHits: own.rareHits, matchedTokens: own.matchedTokens };
+        return { file, score: rankedByFile.get(referrer).score, rareHits: 0, matchedTokens: [] };
+    });
+    const { tier1, tier2 } = tierAndCap(candidates, maxScore);
+    return {
+        tier1,
+        tier2,
+        diagnostics: { selectors: selectors.length, pomFiles: pomFiles.length, scoped: tier1.length + tier2.length, discovery },
+    };
+}

package/build/utils/pom-scope/index.test.d.ts

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

package/build/utils/pom-scope/index.test.js

@@ -0,0 +1,239 @@
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+import { fileURLToPath } from "url";
+import { expandImports } from "./import-expansion.js";
+import { FINAL_CAP, selectScopedPoms, tierAndCap } from "./index.js";
+import { globPomFiles } from "./pom-files.js";
+import { RARE_DF } from "./scoring.js";
+const FIX = path.join(path.dirname(fileURLToPath(import.meta.url)), "__fixtures__");
+describe("expandImports", () => {
+    it("adds one-hop imports/extends but not transitive closure beyond them", async () => {
+        const all = await globPomFiles(FIX);
+        const widgets = all.find((f) => f.endsWith("widgetsPage.js"));
+        const out = (await expandImports([widgets], all)).map((e) => path.basename(e.file));
+        expect(out).toContain("widgetsPage.js");
+        expect(out).toContain("basePage.js"); // via import { BasePage } from './basePage.js'
+        expect(out).not.toContain("loginPage.js"); // not referenced by widgetsPage
+    });
+    it("tags one-hop additions with their referrer", async () => {
+        const all = await globPomFiles(FIX);
+        const widgets = all.find((f) => f.endsWith("widgetsPage.js"));
+        const out = await expandImports([widgets], all);
+        expect(out[0]).toEqual({ file: widgets }); // selected: no referrer
+        const base = out.find((e) => e.file.endsWith("basePage.js"));
+        expect(base.referrer).toBe(widgets);
+    });
+});
+describe("tierAndCap", () => {
+    it("evicts by lowest score at FINAL_CAP", () => {
+        const mk = (i, score) => ({ file: `f${i}.js`, score, rareHits: 0, matchedTokens: [] });
+        const candidates = Array.from({ length: 30 }, (_, i) => mk(i, 30 - i)); // scores 30..1
+        const { tier1, tier2 } = tierAndCap(candidates, 30);
+        expect(tier1.length + tier2.length).toBe(25);
+        const kept = [...tier1, ...tier2].map((p) => p.score);
+        expect(Math.min(...kept)).toBe(6); // scores 1..5 evicted
+    });
+});
+describe("selectScopedPoms", () => {
+    it("scopes to the relevant files for a spec's selectors", async () => {
+        const spec = `await page.locator('[data-test="login-sign-in"]').click();
+await page.locator('[data-test="widget-add-btn"]').click();`;
+        const { tier1, tier2, diagnostics } = await selectScopedPoms({
+            testFile: path.join(FIX, "someTests", "generated.spec.js"),
+            specContent: spec,
+        });
+        const all = [...tier1, ...tier2];
+        const names = all.map((f) => path.basename(f.file));
+        expect(names).toEqual(expect.arrayContaining(["loginPage.js", "widgetsPage.js", "basePage.js"]));
+        expect(names).not.toContain("toastPage.js"); // no matching selector
+        expect(all.length).toBeLessThanOrEqual(FINAL_CAP);
+        expect(diagnostics.scoped).toBe(all.length);
+    });
+    it("tiers by score and inherits referrer score for expansion additions", async () => {
+        const spec = `page.locator('[data-test="widget-add-btn"]'); page.locator('[data-test="o-toast-message"]');`;
+        const { tier1, tier2 } = await selectScopedPoms({
+            testFile: path.join(FIX, "someTests", "generated.spec.js"), specContent: spec
+        });
+        const t1 = tier1.map((p) => path.basename(p.file));
+        expect(t1).toEqual(expect.arrayContaining(["widgetsPage.js", "basePage.js"])); // base inherits widgets' score
+        const t2 = tier2.map((p) => path.basename(p.file));
+        expect(t2).toEqual(expect.arrayContaining(["toastPage.js"])); // weak shared token only
+        expect(tier1.find((p) => p.file.endsWith("widgetsPage.js")).matchedTokens).toContain("widget-add-btn");
+    });
+    it("returns [] when no selectors extract (fallback signal)", async () => {
+        const { tier1, tier2 } = await selectScopedPoms({
+            testFile: path.join(FIX, "someTests", "generated.spec.js"),
+            specContent: "const x = 1;",
+        });
+        expect(tier1).toEqual([]);
+        expect(tier2).toEqual([]);
+    });
+    it("returns [] when no POM files exist under the root", async () => {
+        // Hermetic: anchor the root walk inside a fresh temp dir (empty package.json),
+        // so the walk cannot escape to the ambient filesystem.
+        const dir = fs.mkdtempSync(path.join(os.tmpdir(), "pom-scope-empty-"));
+        try {
+            fs.writeFileSync(path.join(dir, "package.json"), "{}");
+            const { tier1, tier2 } = await selectScopedPoms({
+                testFile: path.join(dir, "sub", "generated.spec.js"),
+                specContent: '[data-test="a-b-c"]',
+            });
+            expect(tier1).toEqual([]);
+            expect(tier2).toEqual([]);
+        }
+        finally {
+            fs.rmSync(dir, { recursive: true, force: true });
+        }
+    });
+    it("excludes files that fail both cutoff arms (low score, no rare hits)", async () => {
+        // RARE_DF+1 POMs all share one common token, and richPage also has it, so
+        // df = (RARE_DF+1) + 1 = RARE_DF+2 > RARE_DF => the token grants no rareHits to anyone.
+        // one POM (richPage) additionally holds 12 distinct rare tokens (df=1 each).
+        // The other RARE_DF+1 score 1/df < maxScore/10 with rareHits=0 => excluded.
+        const dir = fs.mkdtempSync(path.join(os.tmpdir(), "pom-scope-cutoff-"));
+        try {
+            fs.writeFileSync(path.join(dir, "package.json"), "{}");
+            const pages = path.join(dir, "pages");
+            fs.mkdirSync(pages);
+            const rareTokens = Array.from({ length: 12 }, (_, i) => `only-here-${i + 1}`);
+            for (let n = 1; n <= RARE_DF + 1; n++) {
+                fs.writeFileSync(path.join(pages, `commonOnly${n}Page.js`), `export class CommonOnly${n}Page { constructor(page){ this.x = page.locator('[data-test="shared-everywhere-token"]'); } }\n`);
+            }
+            fs.writeFileSync(path.join(pages, "richPage.js"), `export class RichPage { constructor(page){ this.x = page.locator('[data-test="shared-everywhere-token"]'); ` +
+                rareTokens.map((t, i) => `this.r${i} = page.locator('[data-test="${t}"]');`).join(" ") +
+                ` } }\n`);
+            const specContent = ["shared-everywhere-token", ...rareTokens]
+                .map((t) => `page.locator('[data-test="${t}"]');`)
+                .join("\n");
+            const { tier1, tier2, diagnostics } = await selectScopedPoms({
+                testFile: path.join(dir, "tests", "generated.spec.js"),
+                specContent,
+            });
+            const all = [...tier1, ...tier2];
+            expect(all.map((f) => path.basename(f.file))).toEqual(["richPage.js"]);
+            expect(tier1.map((f) => path.basename(f.file))).toEqual(["richPage.js"]); // lone survivor lands in tier1
+            expect(diagnostics.pomFiles).toBe(RARE_DF + 2);
+        }
+        finally {
+            fs.rmSync(dir, { recursive: true, force: true });
+        }
+    });
+    it("reads testIdAttribute from playwright.config and scopes by it", async () => {
+        const dir = fs.mkdtempSync(path.join(os.tmpdir(), "pom-scope-tia-"));
+        try {
+            fs.writeFileSync(path.join(dir, "package.json"), "{}");
+            fs.writeFileSync(path.join(dir, "playwright.config.ts"), `export default { use: { testIdAttribute: "data-zzz" } };`);
+            const pages = path.join(dir, "pages");
+            fs.mkdirSync(pages);
+            fs.writeFileSync(path.join(pages, "fooPage.js"), `export class FooPage { constructor(page){ this.x = page.locator('[data-zzz="foo-unique-btn"]'); } }\n`);
+            const { tier1, tier2 } = await selectScopedPoms({
+                testFile: path.join(dir, "t", "g.spec.js"),
+                specContent: `page.locator('[data-zzz="foo-unique-btn"]');`,
+            });
+            expect([...tier1, ...tier2].map((p) => path.basename(p.file))).toContain("fooPage.js");
+        }
+        finally {
+            fs.rmSync(dir, { recursive: true, force: true });
+        }
+    });
+    it("discovers POMs outside conventional dirs via selector grep", async () => {
+        const dir = fs.mkdtempSync(path.join(os.tmpdir(), "pom-scope-disc-"));
+        try {
+            fs.writeFileSync(path.join(dir, "package.json"), "{}");
+            const screens = path.join(dir, "screens");
+            fs.mkdirSync(screens); // NOT a conventional POM dir
+            fs.writeFileSync(path.join(screens, "checkoutScreen.js"), `export class CheckoutScreen { constructor(page){ this.pay = page.locator('[data-test="pay-now-btn"]'); } }\n`);
+            const { tier1, tier2, diagnostics } = await selectScopedPoms({
+                testFile: path.join(dir, "t", "g.spec.js"),
+                specContent: `page.locator('[data-test="pay-now-btn"]');`,
+            });
+            expect([...tier1, ...tier2].map((p) => path.basename(p.file))).toContain("checkoutScreen.js");
+            expect(diagnostics.discovery).toBe("selector-grep");
+        }
+        finally {
+            fs.rmSync(dir, { recursive: true, force: true });
+        }
+    });
+    it("expands imports into a discovery-fresh base class even when it scored zero selectors itself", async () => {
+        // checkoutScreen.js is the only file scoring the spec's selector, but it extends baseScreen.js
+        // which shares no selector tokens with the spec at all. baseScreen.js must still be pulled in
+        // via one-hop import expansion -- the expansion universe has to include ALL discovery-fresh
+        // files (scored or not), not just the ones that individually matched a selector.
+        const dir = fs.mkdtempSync(path.join(os.tmpdir(), "pom-scope-expand-univ-"));
+        try {
+            fs.writeFileSync(path.join(dir, "package.json"), "{}");
+            const screens = path.join(dir, "screens");
+            fs.mkdirSync(screens); // NOT a conventional POM dir
+            fs.writeFileSync(path.join(screens, "baseScreen.js"), `export class BaseScreen { constructor(page){ this.page = page; } }\n`);
+            fs.writeFileSync(path.join(screens, "checkoutScreen.js"), `import { BaseScreen } from './baseScreen.js';\nexport class CheckoutScreen extends BaseScreen { constructor(page){ super(page); this.pay = page.locator('[data-test="pay-now-btn"]'); } }\n`);
+            const { tier1, tier2 } = await selectScopedPoms({
+                testFile: path.join(dir, "t", "g.spec.js"),
+                specContent: `page.locator('[data-test="pay-now-btn"]');`,
+            });
+            const names = [...tier1, ...tier2].map((f) => path.basename(f.file));
+            expect(names).toContain("checkoutScreen.js");
+            expect(names).toContain("baseScreen.js");
+        }
+        finally {
+            fs.rmSync(dir, { recursive: true, force: true });
+        }
+    });
+    it("reports a clean no-overlap scan distinctly from machinery failure", async () => {
+        const dir = fs.mkdtempSync(path.join(os.tmpdir(), "pom-scope-noov-"));
+        try {
+            fs.writeFileSync(path.join(dir, "package.json"), "{}");
+            fs.mkdirSync(path.join(dir, "src"));
+            fs.writeFileSync(path.join(dir, "src", "app.js"), `export const x = 1;\n`);
+            const r = await selectScopedPoms({ testFile: path.join(dir, "t", "g.spec.js"), specContent: `page.locator('[data-test="zzz-never"]');` });
+            expect(r.tier1).toEqual([]);
+            expect(r.tier2).toEqual([]);
+            expect(r.diagnostics.discovery).toBe("none");
+        }
+        finally {
+            fs.rmSync(dir, { recursive: true, force: true });
+        }
+    });
+    it("does not discover a Cypress spec file (*.cy.js) as a fallback POM", async () => {
+        // Cypress specs are full of data-cy selectors (a member of DEFAULT_TESTID_ATTRS), so without
+        // an exclusion the selector-grep fallback would score and select the test file itself as a POM.
+        const dir = fs.mkdtempSync(path.join(os.tmpdir(), "pom-scope-cy-"));
+        try {
+            fs.writeFileSync(path.join(dir, "package.json"), "{}");
+            const e2e = path.join(dir, "cypress", "e2e");
+            fs.mkdirSync(e2e, { recursive: true });
+            fs.writeFileSync(path.join(e2e, "checkout.cy.js"), `it("pays", () => { cy.get('[data-cy="pay-now"]').click(); });\n`);
+            const { tier1, tier2, diagnostics } = await selectScopedPoms({
+                testFile: path.join(dir, "t", "g.spec.js"),
+                specContent: `page.locator('[data-cy="pay-now"]');`,
+            });
+            expect(tier1).toEqual([]);
+            expect(tier2).toEqual([]);
+            expect(diagnostics.discovery).toBe("none");
+        }
+        finally {
+            fs.rmSync(dir, { recursive: true, force: true });
+        }
+    });
+    it("falls through to repo-wide discovery when conventional dirs match nothing", async () => {
+        const dir = fs.mkdtempSync(path.join(os.tmpdir(), "pom-scope-coex-"));
+        try {
+            fs.writeFileSync(path.join(dir, "package.json"), "{}");
+            const pages = path.join(dir, "pages");
+            fs.mkdirSync(pages);
+            fs.writeFileSync(path.join(pages, "otherPage.js"), `export class OtherPage { constructor(page){ this.x = page.locator('[data-test="unrelated-btn"]'); } }\n`);
+            const screens = path.join(dir, "screens");
+            fs.mkdirSync(screens);
+            fs.writeFileSync(path.join(screens, "checkoutScreen.js"), `export class CheckoutScreen { constructor(page){ this.pay = page.locator('[data-test="pay-now-btn"]'); } }\n`);
+            const { tier1, tier2, diagnostics } = await selectScopedPoms({
+                testFile: path.join(dir, "t", "g.spec.js"),
+                specContent: `page.locator('[data-test="pay-now-btn"]');`,
+            });
+            expect([...tier1, ...tier2].map((p) => path.basename(p.file))).toContain("checkoutScreen.js");
+            expect(diagnostics.discovery).toBe("selector-grep");
+        }
+        finally {
+            fs.rmSync(dir, { recursive: true, force: true });
+        }
+    });
+});

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

@@ -0,0 +1,3 @@
+export declare function globPomFiles(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

@@ -0,0 +1,48 @@
+import fg from "fast-glob";
+import * as path from "path";
+/** Mirrors the prompt's STEP 1 globs; exclusion is by BASENAME only (see fix 8bded34a). */
+const POM_GLOBS = [
+    "**/pageobjects/**/*.{ts,js}",
+    "**/page-objects/**/*.{ts,js}",
+    "**/pages/**/*.{ts,js}",
+    "**/*.page.{ts,js}",
+    "**/*Page.{ts,js}",
+    "**/pom/**/*.{ts,js}",
+];
+const EXCLUDED_BASENAME = /\.(spec|test|cy)\.(ts|js|tsx|jsx|mjs|cjs)$/;
+const ALL_SOURCE_GLOBS = ["**/*.{ts,js,tsx,jsx,mjs,cjs}"];
+const ALL_SOURCE_IGNORE = [
+    "**/node_modules/**",
+    "**/dist/**",
+    "**/build/**",
+    "**/coverage/**",
+    "**/.git/**",
+    "**/vendor/**",
+    "**/cypress/**",
+    "**/__tests__/**",
+];
+export async function globPomFiles(root) {
+    const matches = await fg(POM_GLOBS, {
+        cwd: root,
+        absolute: true,
+        ignore: ["**/node_modules/**"],
+        suppressErrors: true,
+        followSymbolicLinks: false,
+    });
+    return [...new Set(matches)]
+        .filter((f) => !EXCLUDED_BASENAME.test(path.basename(f)))
+        .sort();
+}
+/** Fallback discovery for repos whose POM layer doesn't match the conventional glob patterns. */
+export async function globAllSourceFiles(root) {
+    const matches = await fg(ALL_SOURCE_GLOBS, {
+        cwd: root,
+        absolute: true,
+        ignore: ALL_SOURCE_IGNORE,
+        suppressErrors: true,
+        followSymbolicLinks: false,
+    });
+    return [...new Set(matches)]
+        .filter((f) => !EXCLUDED_BASENAME.test(path.basename(f)))
+        .sort();
+}

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

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

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

@@ -0,0 +1,29 @@
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+import { fileURLToPath } from "url";
+import { globPomFiles } from "./pom-files.js";
+const FIX = path.join(path.dirname(fileURLToPath(import.meta.url)), "__fixtures__");
+describe("globPomFiles", () => {
+    it("finds POM files, excludes node_modules and .spec/.test basenames, keeps 'spec' substrings", async () => {
+        const files = await globPomFiles(FIX);
+        expect(files.every((f) => path.isAbsolute(f))).toBe(true);
+        const sorted = [...files].sort();
+        expect(files).toEqual(sorted);
+        const names = files.map((f) => path.basename(f));
+        expect(names).toEqual(expect.arrayContaining([
+            "loginPage.js", "widgetsPage.js", "toastPage.js", "basePage.js", "page-manager.js", "inspectorPage.js",
+        ]));
+        expect(names).not.toContain("loginPage.spec.js");
+        expect(names).not.toContain("somePage.js");
+    });
+    it("returns [] for a root with no POM files", async () => {
+        const empty = fs.mkdtempSync(path.join(os.tmpdir(), "pom-empty-"));
+        try {
+            expect(await globPomFiles(empty)).toEqual([]);
+        }
+        finally {
+            fs.rmSync(empty, { recursive: true, force: true });
+        }
+    });
+});

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

@@ -0,0 +1,20 @@
+export declare const RARE_DF = 5;
+export type PomScore = {
+    file: string;
+    score: number;
+    hits: number;
+    rareHits: number;
+    matchedTokens: string[];
+};
+/**
+ * IDF-style scoring: each selector contributes 1/df to every file containing it
+ * (df = number of files containing the selector). Rare selectors dominate;
+ * ubiquitous ones (global toasts, shared menus) contribute ~0.
+ * Backslashes are stripped on both sides so `menu-link-\/x` matches `menu-link-/x`.
+ *
+ * RARE_DF=5 (adjusted from 3): family-shared iframe/element ids can legitimately
+ * span several files in a POM family — e.g. AssetForce's `#application-new-applied`
+ * spans 4 of 63 POMs — and should still grant rare-hit selection. df<=5 is the
+ * evidence-adjusted best-guess threshold for "rare enough to count".
+ */
+export declare function scorePoms(selectors: string[], files: string[]): Promise<PomScore[]>;

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

@@ -0,0 +1,45 @@
+import { readFile } from "fs/promises";
+export const RARE_DF = 5;
+/**
+ * IDF-style scoring: each selector contributes 1/df to every file containing it
+ * (df = number of files containing the selector). Rare selectors dominate;
+ * ubiquitous ones (global toasts, shared menus) contribute ~0.
+ * Backslashes are stripped on both sides so `menu-link-\/x` matches `menu-link-/x`.
+ *
+ * RARE_DF=5 (adjusted from 3): family-shared iframe/element ids can legitimately
+ * span several files in a POM family — e.g. AssetForce's `#application-new-applied`
+ * spans 4 of 63 POMs — and should still grant rare-hit selection. df<=5 is the
+ * evidence-adjusted best-guess threshold for "rare enough to count".
+ */
+export async function scorePoms(selectors, files) {
+    if (selectors.length === 0 || files.length === 0)
+        return [];
+    const contents = new Map();
+    await Promise.all(files.map(async (f) => {
+        try {
+            contents.set(f, (await readFile(f, "utf8")).replace(/\\/g, ""));
+        }
+        catch { /* unreadable file: skip */ }
+    }));
+    const fileMatches = new Map(); // selector -> files containing it
+    for (const sel of selectors) {
+        const needle = sel.replace(/\\/g, "");
+        const matched = [...contents.entries()].filter(([, c]) => c.includes(needle)).map(([f]) => f);
+        if (matched.length > 0)
+            fileMatches.set(sel, matched);
+    }
+    const scores = new Map();
+    for (const [sel, matched] of fileMatches) {
+        const df = matched.length;
+        for (const f of matched) {
+            const s = scores.get(f) ?? { file: f, score: 0, hits: 0, rareHits: 0, matchedTokens: [] };
+            s.score += 1 / df;
+            s.hits += 1;
+            if (df <= RARE_DF)
+                s.rareHits += 1;
+            s.matchedTokens.push(sel.replace(/\\/g, ""));
+            scores.set(f, s);
+        }
+    }
+    return [...scores.values()].sort((a, b) => b.score - a.score);
+}

package/build/utils/pom-scope/scoring.test.d.ts

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

package/build/utils/pom-scope/scoring.test.js

@@ -0,0 +1,39 @@
+import * as path from "path";
+import { fileURLToPath } from "url";
+import { globPomFiles } from "./pom-files.js";
+import { scorePoms } from "./scoring.js";
+const FIX = path.join(path.dirname(fileURLToPath(import.meta.url)), "__fixtures__");
+describe("scorePoms", () => {
+    it("ranks rare-selector files high; ubiquitous selectors contribute ~nothing", async () => {
+        const files = await globPomFiles(FIX);
+        // widget-add-btn appears only in widgetsPage (df=1) → strong.
+        // o-toast-message appears in 3 files (df=3) → weak-ish but still rare in this tiny fixture;
+        // login-sign-in only in loginPage (df=1) → strong.
+        const ranked = await scorePoms(["widget-add-btn", "login-sign-in", "o-toast-message"], files);
+        const names = ranked.map((r) => path.basename(r.file));
+        expect(names[0]).toBe("widgetsPage.js"); // 1/1 + 1/3
+        expect(names[1]).toBe("loginPage.js"); // 1/1 + 1/3
+        const toastOnly = ranked.find((r) => path.basename(r.file) === "toastPage.js");
+        expect(toastOnly.score).toBeLessThan(0.5); // only the shared toast selector
+        expect(toastOnly.rareHits).toBeGreaterThanOrEqual(0);
+    });
+    it("matches through backslash escaping", async () => {
+        const files = await globPomFiles(FIX);
+        // fixture loginPage has plain value; simulate escaped token from spec
+        const ranked = await scorePoms(["login-sign-in"], files);
+        expect(path.basename(ranked[0].file)).toBe("loginPage.js");
+        expect(ranked[0].hits).toBe(1);
+    });
+    it("returns empty for no selectors or no files", async () => {
+        expect(await scorePoms([], ["x"])).toEqual([]);
+        expect(await scorePoms(["a-b-c"], [])).toEqual([]);
+    });
+    it("records which tokens matched each file", async () => {
+        const files = await globPomFiles(FIX);
+        const ranked = await scorePoms(["widget-add-btn", "o-toast-message"], files);
+        const widgets = ranked.find((r) => path.basename(r.file) === "widgetsPage.js");
+        expect(widgets.matchedTokens).toEqual(["widget-add-btn", "o-toast-message"]);
+        const toast = ranked.find((r) => path.basename(r.file) === "toastPage.js");
+        expect(toast.matchedTokens).toEqual(["o-toast-message"]);
+    });
+});

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

@@ -0,0 +1,7 @@
+/**
+ * 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.
+ */
+export declare const DEFAULT_TESTID_ATTRS: string[];
+export declare function extractSelectors(specContent: string, extraTestIdAttrs?: string[]): string[];