@zereight/mcp-gitlab 2.1.62 → 2.1.64

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

@@ -0,0 +1,339 @@
+/**
+ * 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",
+];
+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",
+    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

@@ -0,0 +1,142 @@
+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/);
+    });
+});

package/build/test/get-merge-request-discussion-schema.test.js

@@ -0,0 +1,30 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { GetMergeRequestDiscussionSchema, GitLabDiscussionSchema } from "../schemas.js";
+test("get discussion input coerces numeric ids and keeps discussion id", () => {
+    const parsed = GetMergeRequestDiscussionSchema.parse({
+        project_id: 42,
+        merge_request_iid: 7,
+        discussion_id: "abc123",
+    });
+    assert.equal(parsed.project_id, "42");
+    assert.equal(parsed.merge_request_iid, "7");
+    assert.equal(parsed.discussion_id, "abc123");
+});
+test("get discussion input rejects a missing discussion id", () => {
+    assert.throws(() => GetMergeRequestDiscussionSchema.parse({
+        project_id: "42",
+        merge_request_iid: "7",
+    }));
+});
+test("single discussion response parses the GitLab discussion item shape", () => {
+    const parsed = GitLabDiscussionSchema.parse({
+        id: "abc123",
+        individual_note: false,
+        notes: [{ id: 1, body: "please fix", resolvable: true, resolved: false }],
+    });
+    assert.equal(parsed.id, "abc123");
+    assert.equal(parsed.individual_note, false);
+    assert.equal(parsed.notes.length, 1);
+    assert.equal(parsed.notes[0].body, "please fix");
+});