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

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

@@ -0,0 +1,61 @@
+import { extractPomCalls } from "./calls.js";
+describe("extractPomCalls -- oo-style", () => {
+    const loginBinding = { kind: "instance", name: "login", classFile: "/fake/loginPage.js" };
+    const fnBinding = { kind: "function", name: "openNavFlyout", sourceFile: "/fake/commonActions.js" };
+    it("first-hop method call -> strict:true", () => {
+        const spec = `await login.signInAs(user);`;
+        expect(extractPomCalls(spec, [loginBinding])).toEqual([{ binding: "login", chain: ["signInAs"], strict: true }]);
+    });
+    it("property-only use (e.g. inside expect()) counts as a call too", () => {
+        const spec = `expect(login.toast).toBeVisible();`;
+        expect(extractPomCalls(spec, [loginBinding])).toEqual([{ binding: "login", chain: ["toast"], strict: true }]);
+    });
+    it("chains beyond the first hop are strict:false", () => {
+        const spec = `await login.signIn.click();`;
+        expect(extractPomCalls(spec, [loginBinding])).toEqual([{ binding: "login", chain: ["signIn", "click"], strict: false }]);
+    });
+    it("a free-function binding's direct call has an empty chain and is strict", () => {
+        const spec = `await openNavFlyout(page);`;
+        expect(extractPomCalls(spec, [fnBinding])).toEqual([{ binding: "openNavFlyout", chain: [], strict: true }]);
+    });
+    it("dedupes identical (binding, chain) occurrences", () => {
+        const spec = `
+      await login.signIn.click();
+      await login.signIn.click();
+    `;
+        expect(extractPomCalls(spec, [loginBinding])).toEqual([{ binding: "login", chain: ["signIn", "click"], strict: false }]);
+    });
+    it("a page-manager-style dotted binding name doesn't double-count against a shorter binding sharing its suffix", () => {
+        const pmLoginBinding = { kind: "instance", name: "pm.loginPage", classFile: "/fake/loginPage.js" };
+        const plainLoginBinding = { kind: "instance", name: "loginPage", classFile: "/fake/loginPage.js" };
+        const spec = `await pm.loginPage.signIn.click();`;
+        const calls = extractPomCalls(spec, [pmLoginBinding, plainLoginBinding]);
+        expect(calls).toEqual([{ binding: "pm.loginPage", chain: ["signIn", "click"], strict: false }]);
+    });
+    it("does not let quotes inside regex literals swallow real code", () => {
+        const spec = `page.getByText(/Don't have an account/).click();\nawait login.signIn.click();\nawait login.logout();`;
+        const calls = extractPomCalls(spec, [{ kind: "instance", name: "login", classFile: "/x/login.js" }]);
+        expect(calls).toEqual(expect.arrayContaining([
+            { binding: "login", chain: ["signIn", "click"], strict: false },
+            { binding: "login", chain: ["logout"], strict: true },
+        ]));
+    });
+    it("ignores calls appearing in comments and string/template literals", () => {
+        const spec = `// setup: login.signIn.click() manually
+/* login.signIn.click() */
+const doc = "call login.signIn.click()";
+const t = \`use login.signIn.click()\`;
+login.realCall();`;
+        const calls = extractPomCalls(spec, [{ kind: "instance", name: "login", classFile: "/x/login.js" }]);
+        expect(calls).toEqual([{ binding: "login", chain: ["realCall"], strict: true }]);
+    });
+});
+describe("extractPomCalls -- af-style", () => {
+    it("a deep component-property chain (list.footer.okBtn) is strict:false", () => {
+        const listBinding = { kind: "instance", name: "list", classFile: "/fake/asset-list.page.ts" };
+        const spec = `await list.footer.okBtn.click();`;
+        expect(extractPomCalls(spec, [listBinding])).toEqual([
+            { binding: "list", chain: ["footer", "okBtn", "click"], strict: false },
+        ]);
+    });
+});

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

@@ -0,0 +1,4 @@
+export * from "./bindings.js";
+export * from "./calls.js";
+export * from "./resolve.js";
+export * from "./verify.js";

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

@@ -0,0 +1,4 @@
+export * from "./bindings.js";
+export * from "./calls.js";
+export * from "./resolve.js";
+export * from "./verify.js";

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

@@ -0,0 +1,7 @@
+import type { PomBinding } from "./bindings.js";
+/** Greps `member` (as its own token, e.g. followed by `(`, `:`, `=`, or a plain word boundary) in
+ * the binding's class/source file and its one-hop relative imports that are themselves POM files. */
+export declare function resolveMemberSource(binding: PomBinding, member: string, pomFiles: string[]): Promise<{
+    found: boolean;
+    searched: string[];
+}>;

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

@@ -0,0 +1,27 @@
+import { readFile } from "fs/promises";
+import { expandImports } from "../pom-scope/import-expansion.js";
+import { stripCommentsAndStrings } from "./strip.js";
+function escapeRegExp(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/** Greps `member` (as its own token, e.g. followed by `(`, `:`, `=`, or a plain word boundary) in
+ * the binding's class/source file and its one-hop relative imports that are themselves POM files. */
+export async function resolveMemberSource(binding, member, pomFiles) {
+    const primaryFile = binding.kind === "instance" ? binding.classFile : binding.sourceFile;
+    const candidates = await expandImports([primaryFile], pomFiles);
+    const memberRe = new RegExp(`\\b${escapeRegExp(member)}\\b`);
+    const searched = [];
+    for (const { file } of candidates) {
+        searched.push(file);
+        let content;
+        try {
+            content = stripCommentsAndStrings(await readFile(file, "utf8"));
+        }
+        catch {
+            continue;
+        }
+        if (memberRe.test(content))
+            return { found: true, searched };
+    }
+    return { found: false, searched };
+}

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

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

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

@@ -0,0 +1,68 @@
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+import { fileURLToPath } from "url";
+import { resolveMemberSource } from "./resolve.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("resolveMemberSource -- oo-style", () => {
+    it("finds a member defined directly in the binding's own class file", async () => {
+        const binding = { kind: "instance", name: "login", classFile: path.join(OO, "loginPage.js") };
+        const result = await resolveMemberSource(binding, "signInAs", OO_POM_FILES);
+        expect(result).toEqual({ found: true, searched: [path.join(OO, "loginPage.js")] });
+    });
+    it("falls through to a one-hop imported submodule when the member isn't in the class file itself", async () => {
+        // "dragWidget" is defined only in widgetHelpers.js -- widgetsPage.js neither imports nor
+        // mentions it, so a hit here can only come from the one-hop expansion, not the primary file.
+        const binding = { kind: "instance", name: "widgets", classFile: path.join(OO, "widgetsPage.js") };
+        const result = await resolveMemberSource(binding, "dragWidget", OO_POM_FILES);
+        expect(result.found).toBe(true);
+        expect(result.searched).toEqual([path.join(OO, "widgetsPage.js"), path.join(OO, "widgetHelpers.js")]);
+    });
+    it("resolves a free-function binding directly in its source file", async () => {
+        const binding = { kind: "function", name: "openNavFlyout", sourceFile: path.join(OO, "commonActions.js") };
+        const result = await resolveMemberSource(binding, "openNavFlyout", OO_POM_FILES);
+        expect(result).toEqual({ found: true, searched: [path.join(OO, "commonActions.js")] });
+    });
+    it("reports not-found with the full searched list when the member exists nowhere", async () => {
+        const binding = { kind: "instance", name: "login", classFile: path.join(OO, "loginPage.js") };
+        const result = await resolveMemberSource(binding, "doesNotExistAnywhere", OO_POM_FILES);
+        expect(result.found).toBe(false);
+        expect(result.searched).toContain(path.join(OO, "loginPage.js"));
+    });
+});
+describe("resolveMemberSource -- comment stripping", () => {
+    it("does not count a member name that appears only in a comment", async () => {
+        const dir = fs.mkdtempSync(path.join(os.tmpdir(), "pom-resolve-comment-"));
+        try {
+            const file = path.join(dir, "widgetsPage.js");
+            fs.writeFileSync(file, `// TODO: add dragWidget\nexport class WidgetsPage {}\n`);
+            const binding = { kind: "instance", name: "widgets", classFile: file };
+            const result = await resolveMemberSource(binding, "dragWidget", [file]);
+            expect(result).toEqual({ found: false, searched: [file] });
+        }
+        finally {
+            fs.rmSync(dir, { recursive: true, force: true });
+        }
+    });
+});
+describe("resolveMemberSource -- af-style", () => {
+    it("finds a component-chain member via the one-hop imported component file", async () => {
+        const binding = { kind: "instance", name: "list", classFile: path.join(AF, "asset-list.page.ts") };
+        const result = await resolveMemberSource(binding, "okBtn", AF_POM_FILES);
+        expect(result.found).toBe(true);
+        expect(result.searched).toEqual([path.join(AF, "asset-list.page.ts"), path.join(AF, "workflow-footer.page.ts")]);
+    });
+});

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

@@ -0,0 +1,9 @@
+/** Blanks line/block comments only, preserving string/template literal contents (e.g. so an
+ * import specifier's quoted path stays readable). Each blanked character becomes a space
+ * (newlines preserved) so remaining code characters keep their original offset. */
+export declare function stripComments(src: string): string;
+/** Blanks string/template literal contents only, preserving comments as-is. */
+export declare function stripStrings(src: string): string;
+/** Blanks both comments and string/template literals -- for scanners (like call-chain matching)
+ * that never need to read quoted text and want prose in either kind fully inert. */
+export declare function stripCommentsAndStrings(src: string): string;

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

@@ -0,0 +1,89 @@
+/**
+ * Single lexer-lite pass over the source classifying every line comment, block comment, and
+ * string/template literal span (escaped quotes handled; a template literal's `${...}`
+ * interpolation is treated as part of the literal, not parsed separately). Callers blank out
+ * whichever kinds they need -- comments only, strings only, or both -- without re-scanning.
+ */
+function classifySpans(src) {
+    const spans = [];
+    let i = 0;
+    const n = src.length;
+    while (i < n) {
+        const c = src[i];
+        const c2 = i + 1 < n ? src[i + 1] : "";
+        if (c === "/" && c2 === "/") {
+            const start = i;
+            while (i < n && src[i] !== "\n")
+                i++;
+            spans.push({ kind: "comment", start, end: i });
+            continue;
+        }
+        if (c === "/" && c2 === "*") {
+            const start = i;
+            i += 2;
+            while (i < n && !(src[i] === "*" && i + 1 < n && src[i + 1] === "/"))
+                i++;
+            i = Math.min(i + 2, n);
+            spans.push({ kind: "comment", start, end: i });
+            continue;
+        }
+        if (c === "'" || c === '"' || c === "`") {
+            const quote = c;
+            const start = i;
+            i++;
+            let brokeOnNewline = false;
+            while (i < n) {
+                if (src[i] === "\\" && i + 1 < n) {
+                    i += 2;
+                    continue;
+                }
+                if (src[i] === quote) {
+                    i++;
+                    break;
+                }
+                // A plain '...' or "..." string can't legally span a raw newline (only backtick templates
+                // can). A quote char that never closes before a newline is almost always a stray apostrophe
+                // (e.g. inside a regex literal: /Don't have an account/) rather than a real string opener --
+                // treat it as plain code instead of blanking everything up to the next matching quote.
+                if (src[i] === "\n" && quote !== "`") {
+                    brokeOnNewline = true;
+                    break;
+                }
+                i++;
+            }
+            if (brokeOnNewline) {
+                i = start + 1;
+                continue;
+            }
+            spans.push({ kind: "string", start, end: i });
+            continue;
+        }
+        i++;
+    }
+    return spans;
+}
+function blankSpans(src, spans) {
+    if (spans.length === 0)
+        return src;
+    const out = src.split("");
+    for (const { start, end } of spans) {
+        for (let i = start; i < end; i++)
+            out[i] = src[i] === "\n" ? "\n" : " ";
+    }
+    return out.join("");
+}
+/** Blanks line/block comments only, preserving string/template literal contents (e.g. so an
+ * import specifier's quoted path stays readable). Each blanked character becomes a space
+ * (newlines preserved) so remaining code characters keep their original offset. */
+export function stripComments(src) {
+    return blankSpans(src, classifySpans(src).filter((s) => s.kind === "comment"));
+}
+/** Blanks string/template literal contents only, preserving comments as-is. */
+export function stripStrings(src) {
+    return blankSpans(src, classifySpans(src).filter((s) => s.kind === "string"));
+}
+/** Blanks both comments and string/template literals -- for scanners (like call-chain matching)
+ * that never need to read quoted text and want prose in either kind fully inert. */
+export function stripCommentsAndStrings(src) {
+    return blankSpans(src, classifySpans(src));
+}

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

@@ -0,0 +1,14 @@
+export type ReuseViolation = {
+    binding: string;
+    member: string;
+    searched: string[];
+    availableMembers: string[];
+};
+export type VerifyResult = {
+    ok: boolean;
+    violations: ReuseViolation[];
+    unverifiable: string[];
+    parseError?: string;
+    checkedCalls: number;
+};
+export declare function verifyReuse(testFile: string, language: string): Promise<VerifyResult>;

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

@@ -0,0 +1,158 @@
+import { execFile } from "child_process";
+import { readFile } from "fs/promises";
+import * as path from "path";
+import { promisify } from "util";
+import { findRoot } from "../pom-scope/index.js";
+import { globPomFiles, globAllSourceFiles } from "../pom-scope/pom-files.js";
+import { extractPomBindings } from "./bindings.js";
+import { extractPomCalls } from "./calls.js";
+import { resolveMemberSource } from "./resolve.js";
+import { stripComments, stripCommentsAndStrings } from "./strip.js";
+const pExecFile = promisify(execFile);
+const PAGE_MANAGER_RE = /^page-?manager\.(ts|js)$/i;
+const MAX_PARSE_ERROR_LEN = 500;
+const NODE_CHECK_TIMEOUT_MS = 10_000;
+/**
+ * Module-private, deliberately rough member lister: strips comments/strings then greps three
+ * simple patterns (leading-of-line function decls, `this.member =` assignments, getters). This is
+ * LLM-evidence quality by design -- a plausible-members list for a violation report, NOT a parser,
+ * so it will miss real members (e.g. a method declared mid-line in minified/compact source) and
+ * that's an accepted tradeoff, not a bug to fix.
+ */
+async function listMembers(file) {
+    let content;
+    try {
+        content = stripCommentsAndStrings(await readFile(file, "utf8"));
+    }
+    catch {
+        return [];
+    }
+    const members = new Set();
+    for (const re of [/^\s*(?:async\s+)?(\w+)\s*\(/gm, /this\.(\w+)\s*=/g, /get\s+(\w+)\s*\(/g]) {
+        for (const m of content.matchAll(re))
+            members.add(m[1]);
+    }
+    return [...members];
+}
+function primaryFile(binding) {
+    return binding.kind === "instance" ? binding.classFile : binding.sourceFile;
+}
+/** Reads `compilerOptions.paths` out of a tsconfig/jsconfig JSON string. Tolerates JSONC comments
+ * and trailing commas via a strip-then-parse pass; falls back to a bounded regex scan of the
+ * `"paths"` block if that still doesn't parse. Never throws -- returns undefined on any failure. */
+function extractCompilerPaths(raw) {
+    const tryParse = (text) => {
+        try {
+            const parsed = JSON.parse(text);
+            return parsed?.compilerOptions?.paths;
+        }
+        catch {
+            return undefined;
+        }
+    };
+    const direct = tryParse(raw);
+    if (direct)
+        return direct;
+    const relaxed = tryParse(stripComments(raw).replace(/,(\s*[}\]])/g, "$1"));
+    if (relaxed)
+        return relaxed;
+    // Last-resort bounded regex scan, scoped to the paths block if one is findable.
+    try {
+        const pathsBlock = raw.match(/"paths"\s*:\s*\{([\s\S]*?)\}/)?.[1] ?? raw;
+        const result = {};
+        for (const m of pathsBlock.matchAll(/"([^"]+)"\s*:\s*\[\s*"([^"]+)"/g))
+            result[m[1]] = [m[2]];
+        return Object.keys(result).length > 0 ? result : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Builds a prefix -> absolute-dir alias map from `<root>/tsconfig.json` and `<root>/jsconfig.json`
+ * `compilerOptions.paths` entries of the shape `"@x/*": ["./src/y/*"]`. Never throws. */
+async function loadAliasMap(root) {
+    let aliasMap;
+    for (const fname of ["tsconfig.json", "jsconfig.json"]) {
+        let raw;
+        try {
+            raw = await readFile(path.join(root, fname), "utf8");
+        }
+        catch {
+            continue;
+        }
+        const paths = extractCompilerPaths(raw);
+        if (!paths)
+            continue;
+        for (const [key, targets] of Object.entries(paths)) {
+            const target = targets?.[0];
+            if (typeof target !== "string")
+                continue;
+            if (!target)
+                continue;
+            aliasMap ??= {};
+            aliasMap[key.replace(/\/\*$/, "")] = path.resolve(root, target.replace(/\/\*$/, ""));
+        }
+    }
+    return aliasMap;
+}
+export async function verifyReuse(testFile, language) {
+    const spec = await readFile(testFile, "utf8"); // throws on unreadable testFile -- caller handles
+    const root = await findRoot(path.dirname(testFile));
+    let pomFiles = await globPomFiles(root);
+    if (pomFiles.length === 0)
+        pomFiles = await globAllSourceFiles(root);
+    const pageManagerFile = pomFiles.find((f) => PAGE_MANAGER_RE.test(path.basename(f)));
+    const aliasMap = await loadAliasMap(root);
+    const { bindings, unrecognized } = await extractPomBindings(spec, {
+        specDir: path.dirname(testFile),
+        pomFiles,
+        pageManagerFile,
+        aliasMap,
+    });
+    const calls = extractPomCalls(spec, bindings);
+    const bindingsByName = new Map(bindings.map((b) => [b.name, b]));
+    const violations = [];
+    const unverifiable = [];
+    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("."));
+            continue;
+        }
+        if (!call.strict) {
+            unverifiable.push([call.binding, ...call.chain].join("."));
+            continue;
+        }
+        checkedCalls++;
+        // A free-function binding's direct call has an empty chain (see calls.ts) -- there's no
+        // member to hop to, so resolve the binding's own name against its source file instead.
+        const member = call.chain[0] ?? binding.name;
+        const { found, searched } = await resolveMemberSource(binding, member, pomFiles);
+        if (!found) {
+            violations.push({ binding: call.binding, member, searched, availableMembers: await listMembers(primaryFile(binding)) });
+        }
+    }
+    for (const u of unrecognized)
+        unverifiable.push(u);
+    let parseError;
+    if (language === "javascript") {
+        try {
+            await pExecFile("node", ["--check", testFile], { timeout: NODE_CHECK_TIMEOUT_MS });
+        }
+        catch (err) {
+            const e = err;
+            const stderr = e?.killed ? `node --check timed out after ${NODE_CHECK_TIMEOUT_MS}ms` : (e?.stderr ?? String(err));
+            parseError = stderr.slice(0, MAX_PARSE_ERROR_LEN);
+        }
+    }
+    return {
+        ok: violations.length === 0 && parseError === undefined,
+        violations,
+        unverifiable,
+        parseError,
+        checkedCalls,
+    };
+}

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

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