feat: add --tools filter to issues command

Allow filtering issues by tool using UUIDs or human-friendly names.
Resolution logic: exact match on name/shortName, then substring search
on name/shortName/prefix (only when unambiguous). Ambiguous or unknown
inputs produce a clear error message.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: alerizzo

src/commands/issues.test.ts

@@ -2,8 +2,10 @@ import { describe, it, expect, vi, beforeEach } from "vitest";
 import { Command } from "commander";
 import { registerIssuesCommand } from "./issues";
 import { AnalysisService } from "../api/client/services/AnalysisService";
+import { ToolsService } from "../api/client/services/ToolsService";
 
 vi.mock("../api/client/services/AnalysisService");
+vi.mock("../api/client/services/ToolsService");
 vi.mock("../utils/credentials", () => ({ loadCredentials: vi.fn(() => null) }));
 vi.spyOn(console, "log").mockImplementation(() => {});
 
@@ -612,6 +614,159 @@ describe("issues command", () => {
     );
   });
 
+  describe("--tools filter", () => {
+    const mockToolList = {
+      data: [
+        { uuid: "uuid-eslint", name: "ESLint", shortName: "eslint", prefix: "ESLint_" },
+        { uuid: "uuid-eslint9", name: "ESLint 9", shortName: "eslint9", prefix: "ESLint9_" },
+        { uuid: "uuid-semgrep", name: "Semgrep", shortName: "semgrep", prefix: "Semgrep_" },
+        { uuid: "uuid-markdownlint", name: "Markdownlint", shortName: "markdownlint", prefix: "Markdownlint_" },
+        { uuid: "uuid-remarklint", name: "Remarklint", shortName: "remarklint", prefix: "Remarklint_" },
+      ],
+      pagination: undefined,
+    };
+
+    it("should pass a UUID directly to body.toolUuids", async () => {
+      vi.mocked(AnalysisService.searchRepositoryIssues).mockResolvedValue({
+        data: [],
+      } as any);
+
+      const program = createProgram();
+      await program.parseAsync([
+        "node", "test", "issues", "gh", "test-org", "test-repo",
+        "--tools", "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
+      ]);
+
+      expect(ToolsService.listTools).not.toHaveBeenCalled();
+      expect(AnalysisService.searchRepositoryIssues).toHaveBeenCalledWith(
+        "gh", "test-org", "test-repo", undefined, 100,
+        { toolUuids: ["a1b2c3d4-e5f6-7890-abcd-ef1234567890"] },
+      );
+    });
+
+    it("should resolve an exact tool name to its UUID", async () => {
+      vi.mocked(ToolsService.listTools).mockResolvedValue(mockToolList as any);
+      vi.mocked(AnalysisService.searchRepositoryIssues).mockResolvedValue({
+        data: [],
+      } as any);
+
+      const program = createProgram();
+      await program.parseAsync([
+        "node", "test", "issues", "gh", "test-org", "test-repo",
+        "--tools", "eslint",
+      ]);
+
+      expect(ToolsService.listTools).toHaveBeenCalled();
+      expect(AnalysisService.searchRepositoryIssues).toHaveBeenCalledWith(
+        "gh", "test-org", "test-repo", undefined, 100,
+        { toolUuids: ["uuid-eslint"] },
+      );
+    });
+
+    it("should resolve a shortName match to its UUID", async () => {
+      vi.mocked(ToolsService.listTools).mockResolvedValue(mockToolList as any);
+      vi.mocked(AnalysisService.searchRepositoryIssues).mockResolvedValue({
+        data: [],
+      } as any);
+
+      const program = createProgram();
+      await program.parseAsync([
+        "node", "test", "issues", "gh", "test-org", "test-repo",
+        "--tools", "semgrep",
+      ]);
+
+      expect(AnalysisService.searchRepositoryIssues).toHaveBeenCalledWith(
+        "gh", "test-org", "test-repo", undefined, 100,
+        { toolUuids: ["uuid-semgrep"] },
+      );
+    });
+
+    it("should resolve a substring match via prefix when only one tool matches", async () => {
+      vi.mocked(ToolsService.listTools).mockResolvedValue(mockToolList as any);
+      vi.mocked(AnalysisService.searchRepositoryIssues).mockResolvedValue({
+        data: [],
+      } as any);
+
+      const program = createProgram();
+      // "eslint9" matches shortName "eslint9" exactly
+      await program.parseAsync([
+        "node", "test", "issues", "gh", "test-org", "test-repo",
+        "--tools", "eslint9",
+      ]);
+
+      expect(AnalysisService.searchRepositoryIssues).toHaveBeenCalledWith(
+        "gh", "test-org", "test-repo", undefined, 100,
+        { toolUuids: ["uuid-eslint9"] },
+      );
+    });
+
+    it("should error when tool name is ambiguous", async () => {
+      vi.mocked(ToolsService.listTools).mockResolvedValue(mockToolList as any);
+
+      const mockExit = vi.spyOn(process, "exit").mockImplementation(() => {
+        throw new Error("process.exit called");
+      });
+      const mockStderr = vi.spyOn(console, "error").mockImplementation(() => {});
+
+      const program = createProgram();
+      await expect(
+        program.parseAsync([
+          "node", "test", "issues", "gh", "test-org", "test-repo",
+          "--tools", "mark",
+        ]),
+      ).rejects.toThrow("process.exit called");
+
+      expect(mockStderr).toHaveBeenCalledWith(
+        expect.stringContaining("ambiguous"),
+      );
+
+      mockExit.mockRestore();
+      mockStderr.mockRestore();
+    });
+
+    it("should error when tool name is not found", async () => {
+      vi.mocked(ToolsService.listTools).mockResolvedValue(mockToolList as any);
+
+      const mockExit = vi.spyOn(process, "exit").mockImplementation(() => {
+        throw new Error("process.exit called");
+      });
+      const mockStderr = vi.spyOn(console, "error").mockImplementation(() => {});
+
+      const program = createProgram();
+      await expect(
+        program.parseAsync([
+          "node", "test", "issues", "gh", "test-org", "test-repo",
+          "--tools", "nonexistent",
+        ]),
+      ).rejects.toThrow("process.exit called");
+
+      expect(mockStderr).toHaveBeenCalledWith(
+        expect.stringContaining('not found'),
+      );
+
+      mockExit.mockRestore();
+      mockStderr.mockRestore();
+    });
+
+    it("should handle mixed UUIDs and tool names", async () => {
+      vi.mocked(ToolsService.listTools).mockResolvedValue(mockToolList as any);
+      vi.mocked(AnalysisService.searchRepositoryIssues).mockResolvedValue({
+        data: [],
+      } as any);
+
+      const program = createProgram();
+      await program.parseAsync([
+        "node", "test", "issues", "gh", "test-org", "test-repo",
+        "--tools", "a1b2c3d4-e5f6-7890-abcd-ef1234567890,semgrep",
+      ]);
+
+      expect(AnalysisService.searchRepositoryIssues).toHaveBeenCalledWith(
+        "gh", "test-org", "test-repo", undefined, 100,
+        { toolUuids: ["a1b2c3d4-e5f6-7890-abcd-ef1234567890", "uuid-semgrep"] },
+      );
+    });
+  });
+
   it("should fail when CODACY_API_TOKEN is not set", async () => {
     delete process.env.CODACY_API_TOKEN;
 

src/commands/issues.ts

@@ -10,8 +10,10 @@ import {
   printJson,
   printPaginationWarning,
 } from "../utils/output";
-import { printSection, printIssueCard } from "../utils/formatting";
+import { printSection, printIssueCard, resolveToolUuids } from "../utils/formatting";
 import { AnalysisService } from "../api/client/services/AnalysisService";
+import { ToolsService } from "../api/client/services/ToolsService";
+import { Tool } from "../api/client/models/Tool";
 import { CommitIssue } from "../api/client/models/CommitIssue";
 import { SeverityLevel } from "../api/client/models/SeverityLevel";
 import { SearchRepositoryIssuesBody } from "../api/client/models/SearchRepositoryIssuesBody";
@@ -169,6 +171,7 @@ export function registerIssuesCommand(program: Command) {
     .argument("<repository>", "repository name")
     .option("-b, --branch <branch>", "branch name (defaults to the main branch)")
     .option("-p, --patterns <patterns>", "comma-separated list of pattern IDs")
+    .option("-T, --tools <tools>", "comma-separated tool UUIDs or names to filter by")
     .option(
       "-s, --severities <severities>",
       "comma-separated severity levels: Critical, High, Medium, Minor (or Error, Warning, Info)",
@@ -189,6 +192,7 @@ Examples:
   $ codacy issues gh my-org my-repo
   $ codacy issues gh my-org my-repo --branch main --severities Critical,Medium
   $ codacy issues gh my-org my-repo --categories Security --overview
+  $ codacy issues gh my-org my-repo --tools eslint,semgrep
   $ codacy issues gh my-org my-repo --limit 500
   $ codacy issues gh my-org my-repo --output json`,
     )
@@ -220,6 +224,20 @@ Examples:
         const author = parseCommaList(opts.authors);
         if (author) body.authorEmails = author;
 
+        const toolInputs = parseCommaList(opts.tools);
+        if (toolInputs) {
+          body.toolUuids = await resolveToolUuids(toolInputs, async () => {
+            const tools: Tool[] = [];
+            let cursor: string | undefined;
+            do {
+              const resp = await ToolsService.listTools(cursor, 100);
+              tools.push(...resp.data);
+              cursor = resp.pagination?.cursor;
+            } while (cursor);
+            return tools;
+          });
+        }
+
         const limit = Math.min(Math.max(parseInt(opts.limit, 10) || 100, 1), 1000);
 
         const spinner = ora(

src/utils/formatting.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect, vi, beforeEach } from "vitest";
-import { formatAnalysisStatus } from "./formatting";
+import { formatAnalysisStatus, resolveToolUuids } from "./formatting";
 
 // Mock ansis to return raw text for easier testing
 vi.mock("ansis", () => ({
@@ -92,3 +92,92 @@ describe("formatAnalysisStatus", () => {
     expect(result).toBe("Never");
   });
 });
+
+describe("resolveToolUuids", () => {
+  const mockTools = [
+    { uuid: "uuid-eslint", name: "ESLint", shortName: "eslint", prefix: "ESLint_" },
+    { uuid: "uuid-eslint9", name: "ESLint 9", shortName: "eslint9", prefix: "ESLint9_" },
+    { uuid: "uuid-semgrep", name: "Semgrep", shortName: "semgrep", prefix: "Semgrep_" },
+    { uuid: "uuid-markdownlint", name: "Markdownlint", shortName: "markdownlint", prefix: "Markdownlint_" },
+    { uuid: "uuid-remarklint", name: "Remarklint", shortName: "remarklint", prefix: "Remarklint_" },
+  ] as any[];
+
+  const fetchTools = vi.fn(async () => mockTools);
+
+  beforeEach(() => {
+    fetchTools.mockClear();
+  });
+
+  it("should pass UUIDs through without fetching tools", async () => {
+    const result = await resolveToolUuids(
+      ["a1b2c3d4-e5f6-7890-abcd-ef1234567890"],
+      fetchTools,
+    );
+    expect(result).toEqual(["a1b2c3d4-e5f6-7890-abcd-ef1234567890"]);
+    expect(fetchTools).not.toHaveBeenCalled();
+  });
+
+  it("should resolve exact name match (case-insensitive)", async () => {
+    const result = await resolveToolUuids(["eslint"], fetchTools);
+    expect(result).toEqual(["uuid-eslint"]);
+  });
+
+  it("should resolve exact shortName match (case-insensitive)", async () => {
+    const result = await resolveToolUuids(["eslint9"], fetchTools);
+    expect(result).toEqual(["uuid-eslint9"]);
+  });
+
+  it("should resolve a unique substring match via name", async () => {
+    const result = await resolveToolUuids(["semgr"], fetchTools);
+    expect(result).toEqual(["uuid-semgrep"]);
+  });
+
+  it("should error on ambiguous substring match", async () => {
+    const mockExit = vi.spyOn(process, "exit").mockImplementation(() => {
+      throw new Error("process.exit called");
+    });
+    vi.spyOn(console, "error").mockImplementation(() => {});
+
+    await expect(resolveToolUuids(["mark"], fetchTools)).rejects.toThrow(
+      "process.exit called",
+    );
+
+    expect(console.error).toHaveBeenCalledWith(
+      expect.stringContaining("ambiguous"),
+    );
+
+    mockExit.mockRestore();
+    (console.error as any).mockRestore();
+  });
+
+  it("should error when tool is not found", async () => {
+    const mockExit = vi.spyOn(process, "exit").mockImplementation(() => {
+      throw new Error("process.exit called");
+    });
+    vi.spyOn(console, "error").mockImplementation(() => {});
+
+    await expect(resolveToolUuids(["zzz"], fetchTools)).rejects.toThrow(
+      "process.exit called",
+    );
+
+    expect(console.error).toHaveBeenCalledWith(
+      expect.stringContaining("not found"),
+    );
+
+    mockExit.mockRestore();
+    (console.error as any).mockRestore();
+  });
+
+  it("should handle mixed UUIDs and names, fetching tools only once", async () => {
+    const result = await resolveToolUuids(
+      ["a1b2c3d4-e5f6-7890-abcd-ef1234567890", "semgrep", "eslint"],
+      fetchTools,
+    );
+    expect(result).toEqual([
+      "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
+      "uuid-semgrep",
+      "uuid-eslint",
+    ]);
+    expect(fetchTools).toHaveBeenCalledTimes(1);
+  });
+});