@zereight/mcp-gitlab 2.1.69 → 2.2.0

package/build/scripts/tool-coverage/coverage.js

@@ -1,341 +0,0 @@
-/**
- * Portable pure logic for MCP `tools/call` coverage detection.
- *
- * A tool counts as invoked when test source sends that name through MCP, in one
- * of these syntax-scoped positions only:
- *
- * - `callTool("name")`, `callToolJson("name")`, `client.callTool("name")`,
- *   `callTool(envOrUrl, "name")` — the name is a string literal directly in the
- *   argument list of a `callTool*` callee (identifier or property access).
- * - `client.callTool({ name: "name", arguments })` — SDK shape: the name is the
- *   `name` property of an object literal passed as the FIRST argument.
- * - `{ method: "tools/call", params: { name: "name" } }` — the `name` property of
- *   a `params` object inside the SAME object literal that carries the method.
- * - `send(proc, "tools/call", { name: "name" })` — the `name` property of an
- *   object literal passed as the argument right after a `"tools/call"` method
- *   argument (request-helper shape, any callee).
- *
- * Deliberately not counted:
- *
- * - `callTool(toolName, { name: "other" })` — object past the first argument is
- *   tool input, not the invoked name.
- * - `name: "tool"` properties outside a `tools/call` payload (fixtures, `tools/list`
- *   mocks, tool arguments) in files that merely mention `tools/call`.
- * - variable names (`callTool(env, toolName)`) — not statically resolvable.
- *
- * No filesystem or registry access here; the caller supplies file texts and the
- * tool-name set. The only dependency is the TypeScript parser (devDependency).
- */
-import ts from "typescript";
-export const SKIP_FILES = new Set(["tool-description-quality.test.ts"]);
-export const GROUP_ORDER = [
-    "projects",
-    "repositories",
-    "branches",
-    "groups",
-    "merge_requests",
-    "issues",
-    "labels",
-    "workitems",
-    "ci",
-    "pipelines",
-    "milestones",
-    "wiki",
-    "releases",
-    "tags",
-    "users",
-    "variables",
-    "webhooks",
-    "search",
-    "dependency_proxy",
-    "vulnerabilities",
-    "orbit",
-    "snippets",
-];
-export const GROUP_TITLE = {
-    merge_requests: "Merge Requests",
-    issues: "Issues",
-    repositories: "Projects & Files",
-    branches: "Branches & Commits",
-    projects: "Projects & Namespaces",
-    labels: "Labels",
-    ci: "CI Lint",
-    groups: "Groups",
-    pipelines: "Pipelines, Jobs & Deployments",
-    milestones: "Milestones",
-    wiki: "Wiki",
-    releases: "Releases",
-    tags: "Tags",
-    users: "Users & Events",
-    workitems: "Work Items",
-    webhooks: "Webhooks",
-    search: "Search",
-    variables: "Variables",
-    dependency_proxy: "Dependency Proxy",
-    vulnerabilities: "Vulnerabilities",
-    orbit: "GitLab Orbit",
-    snippets: "Snippets",
-    meta: "Meta & GraphQL",
-};
-export const CANARY_INVOKED = [
-    "list_project_variables",
-    "orbit_query",
-    "list_pipeline_schedules",
-    "search_code",
-];
-export const MIN_INVOKED = 146;
-const CALL_TOOL_CALLEE = /^callTool[A-Za-z]*$/;
-function unwrap(expression) {
-    let current = expression;
-    while (ts.isAsExpression(current) ||
-        ts.isSatisfiesExpression(current) ||
-        ts.isParenthesizedExpression(current) ||
-        ts.isNonNullExpression(current)) {
-        current = current.expression;
-    }
-    return current;
-}
-function stringValue(expression) {
-    const inner = unwrap(expression);
-    if (ts.isStringLiteral(inner) || ts.isNoSubstitutionTemplateLiteral(inner)) {
-        return inner.text;
-    }
-    return undefined;
-}
-function propertyKey(prop) {
-    const key = prop.name;
-    if (ts.isIdentifier(key) || ts.isStringLiteral(key)) {
-        return key.text;
-    }
-    return undefined;
-}
-function namePropertyOf(object) {
-    for (const prop of object.properties) {
-        if (!ts.isPropertyAssignment(prop)) {
-            continue;
-        }
-        if (propertyKey(prop) !== "name") {
-            continue;
-        }
-        return stringValue(prop.initializer);
-    }
-    return undefined;
-}
-function callToolCalleeName(callee) {
-    if (ts.isIdentifier(callee)) {
-        return callee.text;
-    }
-    if (ts.isPropertyAccessExpression(callee)) {
-        return callee.name.text;
-    }
-    return undefined;
-}
-function collectCallHits(node, toolNames) {
-    const calleeName = callToolCalleeName(node.expression);
-    if (!calleeName || !CALL_TOOL_CALLEE.test(calleeName)) {
-        return [];
-    }
-    const hits = [];
-    node.arguments.forEach((arg, index) => {
-        const direct = stringValue(arg);
-        if (direct && toolNames.has(direct)) {
-            hits.push(direct);
-            return;
-        }
-        // SDK shape only: client.callTool({ name, arguments }) — the object must be
-        // the first argument. Objects in later positions are tool input.
-        if (index === 0 && ts.isObjectLiteralExpression(unwrap(arg))) {
-            const named = namePropertyOf(unwrap(arg));
-            if (named && toolNames.has(named)) {
-                hits.push(named);
-            }
-        }
-    });
-    return hits;
-}
-function collectMethodArgHit(node, toolNames) {
-    const args = node.arguments;
-    for (let index = 0; index + 1 < args.length; index++) {
-        if (stringValue(args[index]) !== "tools/call") {
-            continue;
-        }
-        const params = unwrap(args[index + 1]);
-        if (!ts.isObjectLiteralExpression(params)) {
-            continue;
-        }
-        const named = namePropertyOf(params);
-        if (named && toolNames.has(named)) {
-            return named;
-        }
-    }
-    return undefined;
-}
-function collectPayloadHit(node, toolNames) {
-    let isToolsCall = false;
-    let paramsName;
-    for (const prop of node.properties) {
-        if (!ts.isPropertyAssignment(prop)) {
-            continue;
-        }
-        const key = propertyKey(prop);
-        if (key === "method" && stringValue(prop.initializer) === "tools/call") {
-            isToolsCall = true;
-        }
-        if (key === "params") {
-            const params = unwrap(prop.initializer);
-            if (ts.isObjectLiteralExpression(params)) {
-                paramsName = namePropertyOf(params);
-            }
-        }
-    }
-    if (isToolsCall && paramsName && toolNames.has(paramsName)) {
-        return paramsName;
-    }
-    return undefined;
-}
-/**
- * Scan one source text and return the invoked tool names found in supported
- * call positions. `fileName` selects the TS/JS grammar; unknown extensions
- * parse as TypeScript.
- */
-export function scanSourceForInvocations(sourceText, fileName, toolNames) {
-    const hits = new Set();
-    const scriptKind = fileName.endsWith(".js") ? ts.ScriptKind.JS : ts.ScriptKind.TS;
-    const sourceFile = ts.createSourceFile(fileName, sourceText, ts.ScriptTarget.Latest, false, scriptKind);
-    function visit(node) {
-        if (ts.isCallExpression(node)) {
-            for (const hit of collectCallHits(node, toolNames)) {
-                hits.add(hit);
-            }
-            const methodHit = collectMethodArgHit(node, toolNames);
-            if (methodHit) {
-                hits.add(methodHit);
-            }
-        }
-        if (ts.isObjectLiteralExpression(node)) {
-            const hit = collectPayloadHit(node, toolNames);
-            if (hit) {
-                hits.add(hit);
-            }
-        }
-        ts.forEachChild(node, visit);
-    }
-    visit(sourceFile);
-    return hits;
-}
-/**
- * Aggregate per-file scan results into tool -> sorted file list. Every known
- * tool gets an entry so uncovered tools render as `- [ ]`.
- */
-export function collectInvocations(files, toolNames) {
-    const hits = new Map();
-    for (const name of toolNames) {
-        hits.set(name, []);
-    }
-    for (const file of files) {
-        for (const name of scanSourceForInvocations(file.text, file.path, toolNames)) {
-            const list = hits.get(name);
-            if (list && !list.includes(file.path)) {
-                list.push(file.path);
-            }
-        }
-    }
-    for (const list of hits.values()) {
-        list.sort();
-    }
-    return hits;
-}
-export function countInvoked(toolNames, hits) {
-    return toolNames.filter(name => (hits.get(name) ?? []).length > 0).length;
-}
-export function groupToolsByToolset(toolNames, definitions) {
-    const categorized = new Set();
-    const grouped = [];
-    for (const id of GROUP_ORDER) {
-        const definition = definitions.find(item => item.id === id);
-        if (!definition) {
-            throw new Error(`GROUP_ORDER lists '${id}' but TOOLSET_DEFINITIONS does not`);
-        }
-        const tools = [...definition.tools];
-        for (const name of tools) {
-            categorized.add(name);
-        }
-        grouped.push({ id, tools });
-    }
-    const meta = toolNames.filter(name => !categorized.has(name));
-    if (meta.length > 0) {
-        grouped.push({ id: "meta", tools: meta });
-    }
-    return grouped;
-}
-export function percent(invoked, total) {
-    if (total === 0) {
-        return "0.0%";
-    }
-    return `${((invoked / total) * 100).toFixed(1)}%`;
-}
-export function toolDocsHref(groupId, toolName) {
-    const slug = groupId.replace(/_/g, "-");
-    return `../tools/${slug}.md#${toolName}`;
-}
-export function formatFiles(files) {
-    return files.map(file => `\`${file}\``).join(", ");
-}
-export function buildCoverageMarkdown(toolNames, hits, grouped) {
-    const invokedCount = countInvoked(toolNames, hits);
-    const lines = [
-        "# Tool invocation coverage",
-        "",
-        "<!-- Generated by scripts/generate-tool-coverage.ts. Do not edit. -->",
-        "",
-        "This is **MCP `tools/call` coverage**, not GitLab REST coverage and not line coverage.",
-        "",
-        'A tool counts as invoked when a test sends that name through MCP (`callTool` / `callToolJson` / `callToolAsync` / `client.callTool`, or a `tools/call` payload with `name: "…"`). Listing a name in a toolset filter or description-quality test does not count. `test:live` (`test/validate-api.js`) is a REST smoke check and is not included.',
-        "",
-        "| | |",
-        "| --- | ---: |",
-        `| Tools | ${toolNames.length} |`,
-        `| Invoked | ${invokedCount} |`,
-        `| Coverage | ${percent(invokedCount, toolNames.length)} |`,
-        "",
-        "## By toolset",
-        "",
-        "| Toolset | Invoked | Total | Coverage |",
-        "| --- | ---: | ---: | ---: |",
-    ];
-    for (const group of grouped) {
-        const invoked = countInvoked(group.tools, hits);
-        const title = GROUP_TITLE[group.id] ?? group.id;
-        lines.push(`| [${title}](#${group.id}) | ${invoked} | ${group.tools.length} | ${percent(invoked, group.tools.length)} |`);
-    }
-    lines.push("");
-    for (const group of grouped) {
-        const title = GROUP_TITLE[group.id] ?? group.id;
-        lines.push(`## ${title}`);
-        lines.push("");
-        lines.push(`<a id="${group.id}"></a>`);
-        lines.push("");
-        for (const name of group.tools) {
-            const files = hits.get(name) ?? [];
-            const link = `[\`${name}\`](${toolDocsHref(group.id, name)})`;
-            if (files.length > 0) {
-                lines.push(`- [x] ${link} — ${formatFiles(files)}`);
-            }
-            else {
-                lines.push(`- [ ] ${link}`);
-            }
-        }
-        lines.push("");
-    }
-    return `${lines.join("\n").trimEnd()}\n`;
-}
-export function assertDetectorHealthy(hits, invokedCount) {
-    if (invokedCount < MIN_INVOKED) {
-        throw new Error(`scanner found ${invokedCount} invoked tools; expected at least ${MIN_INVOKED} (detector probably broken)`);
-    }
-    for (const name of CANARY_INVOKED) {
-        if ((hits.get(name) ?? []).length === 0) {
-            throw new Error(`canary tool ${name} was not detected as invoked (detector probably broken)`);
-        }
-    }
-}

package/build/scripts/tool-coverage/coverage.test.js

@@ -1,142 +0,0 @@
-import { describe, test } from "node:test";
-import assert from "node:assert";
-import { assertDetectorHealthy, buildCoverageMarkdown, CANARY_INVOKED, collectInvocations, countInvoked, formatFiles, GROUP_ORDER, groupToolsByToolset, MIN_INVOKED, percent, scanSourceForInvocations, toolDocsHref, } from "./coverage.js";
-const TOOLS = new Set(["list_issues", "get_project", "orbit_query"]);
-function scan(source) {
-    return scanSourceForInvocations(source, "probe.ts", TOOLS);
-}
-describe("scanSourceForInvocations", () => {
-    test("counts a string literal directly in the argument list", () => {
-        assert.deepStrictEqual(scan(`await callTool("list_issues", { project_id: "1" });`), new Set(["list_issues"]));
-    });
-    test("counts the name in second position after env", () => {
-        assert.deepStrictEqual(scan(`await callToolAsync(baseEnv(url), "orbit_query", { query });`), new Set(["orbit_query"]));
-    });
-    test("counts property-access callees", () => {
-        assert.deepStrictEqual(scan(`await client.callTool("get_project", { project_id: "1" });`), new Set(["get_project"]));
-    });
-    test("counts the SDK object shape when it is the first argument", () => {
-        assert.deepStrictEqual(scan(`await client.callTool({ name: "list_issues", arguments: {} });`), new Set(["list_issues"]));
-    });
-    test("ignores a name object past the first argument (tool input, not invocation)", () => {
-        assert.deepStrictEqual(scan(`await callTool(toolName, { name: "get_project" });`), new Set([]));
-    });
-    test("ignores literals after the call expression closes", () => {
-        assert.deepStrictEqual(scan(`await callTool(env, toolName, args);\nconst label = "get_project";`), new Set([]));
-    });
-    test("ignores variable names", () => {
-        assert.deepStrictEqual(scan(`await callTool(env, toolName, args);`), new Set([]));
-    });
-    test("ignores callees that are not callTool*", () => {
-        assert.deepStrictEqual(scan(`await callListIssues({ project_id: "1" }, env);\nnotify("get_project");`), new Set([]));
-    });
-    test("counts a name inside the same literal as method tools/call", () => {
-        assert.deepStrictEqual(scan(`JSON.stringify({
-        jsonrpc: "2.0",
-        id: 1,
-        method: "tools/call",
-        params: { name: "list_issues", arguments: args },
-      });`), new Set(["list_issues"]));
-    });
-    test("ignores name properties outside the tools/call payload", () => {
-        assert.deepStrictEqual(scan(`
-        const listing = { tools: [{ name: "orbit_query", description: "q" }] };
-        JSON.stringify({ method: "tools/call", params: { name: "list_issues", arguments: {} } });
-      `), new Set(["list_issues"]));
-    });
-    test("ignores a variable name in the payload", () => {
-        assert.deepStrictEqual(scan(`JSON.stringify({ method: "tools/call", params: { name: toolName } });`), new Set([]));
-    });
-    test("counts a request-helper call with method and params arguments", () => {
-        assert.deepStrictEqual(scan(`await sendMcpRequest(proc, "tools/call", { name: "get_project", arguments: {} });`), new Set(["get_project"]));
-    });
-    test("ignores request-helper calls for other methods", () => {
-        assert.deepStrictEqual(scan(`await sendMcpRequest(proc, "initialize", { name: "get_project" });`), new Set([]));
-    });
-    test("ignores request-helper calls with non-object params", () => {
-        assert.deepStrictEqual(scan(`await sendMcpRequest(proc, "tools/call", params);`), new Set([]));
-    });
-    test("ignores tools/call when params is not an inline object", () => {
-        assert.deepStrictEqual(scan(`JSON.stringify({ method: "tools/call", params });`), new Set([]));
-    });
-    test("accepts quoted property keys and single quotes", () => {
-        assert.deepStrictEqual(scan(`JSON.stringify({ "method": 'tools/call', "params": { "name": 'get_project' } });`), new Set(["get_project"]));
-    });
-    test("unwraps as expressions around the name", () => {
-        assert.deepStrictEqual(scan(`await callTool("list_issues" as string);`), new Set(["list_issues"]));
-    });
-    test("ignores names outside the known tool set", () => {
-        assert.deepStrictEqual(scan(`await callTool("no_such_tool", {});`), new Set([]));
-    });
-    test("parses .js sources", () => {
-        const hits = scanSourceForInvocations(`await callTool("get_project", {});`, "probe.js", TOOLS);
-        assert.deepStrictEqual(hits, new Set(["get_project"]));
-    });
-});
-describe("collectInvocations", () => {
-    test("aggregates per-file hits into sorted file lists", () => {
-        const hits = collectInvocations([
-            { path: "test/b.ts", text: `callTool("get_project", {});` },
-            { path: "test/a.ts", text: `callTool("get_project", {}); callTool("list_issues", {});` },
-            { path: "test/a.ts", text: `callTool("get_project", {});` },
-        ], TOOLS);
-        assert.deepStrictEqual(hits.get("get_project"), ["test/a.ts", "test/b.ts"]);
-        assert.deepStrictEqual(hits.get("list_issues"), ["test/a.ts"]);
-        assert.deepStrictEqual(hits.get("orbit_query"), []);
-    });
-});
-describe("groupToolsByToolset", () => {
-    test("groups known toolsets and buckets the rest as meta", () => {
-        const definitions = GROUP_ORDER.map(id => ({
-            id,
-            tools: id === "issues" ? ["list_issues"] : [],
-        }));
-        const grouped = groupToolsByToolset(["list_issues", "stray_tool"], definitions);
-        assert.strictEqual(grouped.find(g => g.id === "issues")?.tools.join(","), "list_issues");
-        assert.strictEqual(grouped.at(-1)?.id, "meta");
-        assert.deepStrictEqual(grouped.at(-1)?.tools, ["stray_tool"]);
-    });
-    test("throws when GROUP_ORDER names a missing toolset", () => {
-        assert.throws(() => groupToolsByToolset([], []), /GROUP_ORDER lists 'projects'/);
-    });
-});
-describe("markdown helpers", () => {
-    test("percent handles zero totals", () => {
-        assert.strictEqual(percent(1, 2), "50.0%");
-        assert.strictEqual(percent(0, 0), "0.0%");
-    });
-    test("toolDocsHref slugifies the group id", () => {
-        assert.strictEqual(toolDocsHref("merge_requests", "list_issues"), "../tools/merge-requests.md#list_issues");
-    });
-    test("formatFiles wraps paths in code spans", () => {
-        assert.strictEqual(formatFiles(["test/a.ts", "test/b.ts"]), "`test/a.ts`, `test/b.ts`");
-    });
-    test("countInvoked counts tools with at least one file", () => {
-        const hits = new Map([
-            ["list_issues", ["test/a.ts"]],
-            ["get_project", []],
-        ]);
-        assert.strictEqual(countInvoked(["list_issues", "get_project"], hits), 1);
-    });
-    test("buildCoverageMarkdown renders checked and unchecked rows", () => {
-        const markdown = buildCoverageMarkdown(["list_issues", "get_project"], new Map([
-            ["list_issues", ["test/a.ts"]],
-            ["get_project", []],
-        ]), [{ id: "issues", tools: ["list_issues", "get_project"] }]);
-        assert.match(markdown, /\| Invoked \| 1 \|/);
-        assert.match(markdown, /- \[x\] \[`list_issues`\].*`test\/a\.ts`/);
-        assert.match(markdown, /- \[ \] \[`get_project`\]/);
-    });
-});
-describe("assertDetectorHealthy", () => {
-    test("passes at the floor with all canaries present", () => {
-        const hits = new Map(CANARY_INVOKED.map(name => [name, ["test/a.ts"]]));
-        assert.doesNotThrow(() => assertDetectorHealthy(hits, MIN_INVOKED));
-    });
-    test("throws below the floor", () => {
-        assert.throws(() => assertDetectorHealthy(new Map(), MIN_INVOKED - 1), /expected at least/);
-    });
-    test("throws when a canary is missing", () => {
-        assert.throws(() => assertDetectorHealthy(new Map(), MIN_INVOKED + 10), /canary tool/);
-    });
-});