fix(workitems): align linkType enum to GitLab API values (#178)

polaz · web-flow · commit 3b4ba6ecd176 · 2026-01-24T14:20:15.000Z
* fix(workitems): align linkType enum to GitLab API values Replace custom enum values (IS_BLOCKED_BY, RELATES_TO) with actual GitLab GraphQL API values (BLOCKED_BY, RELATED). Remove the translation layer that caused IS_BLOCKED_BY to fail with 100% error rate. Closes #177 * fix(workitems): remove unnecessary type assertions in link handlers The Zod schema enum values and WorkItemLinkType are identical, making the `as WorkItemLinkType` casts redundant. Remove them along with the now-unused import. * test(workitems): assert BLOCKED_BY is passed directly to GraphQL API Add assertion verifying the BLOCKED_BY linkType value reaches the GraphQL request without mapping, confirming enum alignment fix. * fix(workitems): document why legacy linkType aliases are not kept IS_BLOCKED_BY caused 100% API failure, RELATES_TO only worked via a mapping layer that masked the bug. No backward compatibility needed for values that never worked correctly. * refactor(workitems): remove redundant linkType spread and clean up comments Remove no-op `linkType: node.linkType` property that duplicated the spread operator. Simplify schema comment to reference issue number instead of spelling out legacy values.
diff --git a/docs/TOOLS.md b/docs/TOOLS.md
@@ -1889,7 +1889,7 @@ Find and inspect issues, epics, tasks, and other work items. Actions: list (grou
 
 ### manage_work_item [tier: Free]
 
-Create, update, delete, or link work items (issues, epics, tasks). Actions: create (epics need GROUP namespace, issues/tasks need PROJECT), update (widgets: dates, time tracking, weight, iterations, health, progress, hierarchy), delete (permanent), add_link/remove_link (BLOCKS/IS_BLOCKED_BY/RELATES_TO). Related: browse_work_items for discovery.
+Create, update, delete, or link work items (issues, epics, tasks). Actions: create (epics need GROUP namespace, issues/tasks need PROJECT), update (widgets: dates, time tracking, weight, iterations, health, progress, hierarchy), delete (permanent), add_link/remove_link (BLOCKS/BLOCKED_BY/RELATED). Related: browse_work_items for discovery.
 
 #### Actions
 
@@ -1908,7 +1908,7 @@ Create, update, delete, or link work items (issues, epics, tasks). Actions: crea
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
 | `id` | string | Yes | Source work item ID |
-| `linkType` | string | Yes | Relationship type: BLOCKS (this blocks target), IS_BLOCKED_BY (this is blocked by target), RELATES_TO (general relationship) |
+| `linkType` | string | Yes | Relationship type: BLOCKS (this blocks target), BLOCKED_BY (this is blocked by target), RELATED (general relationship) |
 | `targetId` | string | Yes | Target work item ID to link to |
 
 **Action `create`**:
@@ -1945,7 +1945,7 @@ Create, update, delete, or link work items (issues, epics, tasks). Actions: crea
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
 | `id` | string | Yes | Source work item ID |
-| `linkType` | string | Yes | Relationship type: BLOCKS (this blocks target), IS_BLOCKED_BY (this is blocked by target), RELATES_TO (general relationship) |
+| `linkType` | string | Yes | Relationship type: BLOCKS (this blocks target), BLOCKED_BY (this is blocked by target), RELATED (general relationship) |
 | `targetId` | string | Yes | Target work item ID to unlink |
 
 **Action `update`**:
diff --git a/src/entities/workitems/registry.ts b/src/entities/workitems/registry.ts
@@ -36,7 +36,6 @@ import {
   WORK_ITEM_REMOVE_LINKED_ITEMS,
   WorkItemUpdateInput,
   WorkItem as GraphQLWorkItem,
-  WorkItemLinkType,
 } from "../../graphql/workItems";
 
 // Types for work item structure - flexible widget interface for runtime processing
@@ -371,7 +370,7 @@ export const workitemsToolRegistry: ToolRegistry = new Map<string, EnhancedToolD
     {
       name: "manage_work_item",
       description:
-        "Create, update, delete, or link work items (issues, epics, tasks). Actions: create (epics need GROUP namespace, issues/tasks need PROJECT), update (widgets: dates, time tracking, weight, iterations, health, progress, hierarchy), delete (permanent), add_link/remove_link (BLOCKS/IS_BLOCKED_BY/RELATES_TO). Related: browse_work_items for discovery.",
+        "Create, update, delete, or link work items (issues, epics, tasks). Actions: create (epics need GROUP namespace, issues/tasks need PROJECT), update (widgets: dates, time tracking, weight, iterations, health, progress, hierarchy), delete (permanent), add_link/remove_link (BLOCKS/BLOCKED_BY/RELATED). Related: browse_work_items for discovery.",
       inputSchema: z.toJSONSchema(ManageWorkItemSchema),
       gate: { envVar: "USE_WORKITEMS", defaultValue: true },
       handler: async (args: unknown): Promise<unknown> => {
@@ -781,15 +780,11 @@ export const workitemsToolRegistry: ToolRegistry = new Map<string, EnhancedToolD
             const connectionManager = ConnectionManager.getInstance();
             const client = connectionManager.getClient();
 
-            // Map user-facing link type to GraphQL enum
-            const graphqlLinkType: WorkItemLinkType =
-              linkType === "RELATES_TO" ? "RELATED" : linkType;
-
             const response = await client.request(WORK_ITEM_ADD_LINKED_ITEMS, {
               input: {
                 id: toGid(id, "WorkItem"),
                 workItemsIds: [toGid(targetId, "WorkItem")],
-                linkType: graphqlLinkType,
+                linkType,
               },
             });
 
@@ -817,15 +812,11 @@ export const workitemsToolRegistry: ToolRegistry = new Map<string, EnhancedToolD
             const connectionManager = ConnectionManager.getInstance();
             const client = connectionManager.getClient();
 
-            // Map user-facing link type to GraphQL enum
-            const graphqlLinkType: WorkItemLinkType =
-              linkType === "RELATES_TO" ? "RELATED" : linkType;
-
             const response = await client.request(WORK_ITEM_REMOVE_LINKED_ITEMS, {
               input: {
                 id: toGid(id, "WorkItem"),
                 workItemsIds: [toGid(targetId, "WorkItem")],
-                linkType: graphqlLinkType,
+                linkType,
               },
             });
 
diff --git a/src/entities/workitems/schema.ts b/src/entities/workitems/schema.ts
@@ -44,11 +44,11 @@ const workItemIdField = WorkItemIdSchema.describe(
   "Work item ID - use numeric ID from list results (e.g., '5953')"
 );
 
-// --- Link type enum ---
+// --- Link type enum (matches GitLab GraphQL API values directly, see #177) ---
 const LinkTypeSchema = z
-  .enum(["BLOCKS", "IS_BLOCKED_BY", "RELATES_TO"])
+  .enum(["BLOCKS", "BLOCKED_BY", "RELATED"])
   .describe(
-    "Relationship type: BLOCKS (this blocks target), IS_BLOCKED_BY (this is blocked by target), RELATES_TO (general relationship)"
+    "Relationship type: BLOCKS (this blocks target), BLOCKED_BY (this is blocked by target), RELATED (general relationship)"
   );
 
 // --- Date validation pattern ---
diff --git a/src/graphql/workItems.ts b/src/graphql/workItems.ts
@@ -1926,7 +1926,7 @@ export const CREATE_WORK_ITEM_WITH_WIDGETS: TypedDocumentNode<
 `;
 
 // Linked items mutations (Free tier)
-export type WorkItemLinkType = "RELATED" | "BLOCKS" | "IS_BLOCKED_BY";
+export type WorkItemLinkType = "RELATED" | "BLOCKS" | "BLOCKED_BY";
 
 export interface WorkItemAddLinkedItemsInput {
   id: string;
diff --git a/src/utils/idConversion.ts b/src/utils/idConversion.ts
@@ -257,14 +257,12 @@ export function cleanWorkItemResponse(workItem: GitLabWorkItem): GitLabWorkItem
         };
       }
 
-      // Clean linked item IDs and normalize linkType in LINKED_ITEMS widget
+      // Clean linked item GIDs in LINKED_ITEMS widget
       if (widget.type === "LINKED_ITEMS" && widget.linkedItems?.nodes) {
         cleanedWidget.linkedItems = {
           ...widget.linkedItems,
           nodes: widget.linkedItems.nodes.map(node => ({
             ...node,
-            // Map GraphQL RELATED back to user-facing RELATES_TO
-            linkType: node.linkType === "RELATED" ? "RELATES_TO" : node.linkType,
             workItem: node.workItem
               ? { ...node.workItem, id: extractSimpleId(node.workItem.id) }
               : node.workItem,
diff --git a/tests/unit/entities/workitems/registry.test.ts b/tests/unit/entities/workitems/registry.test.ts
@@ -1448,39 +1448,6 @@ describe("Workitems Registry - CQRS Tools", () => {
         expect(result).toHaveProperty("id");
       });
 
-      it("should map RELATES_TO to RELATED for GraphQL API", async () => {
-        mockClient.request.mockResolvedValueOnce({
-          workItemAddLinkedItems: {
-            workItem: {
-              id: "gid://gitlab/WorkItem/100",
-              iid: "10",
-              title: "Source",
-              state: "OPEN",
-              workItemType: { id: "gid://gitlab/WorkItems::Type/2", name: "Issue" },
-              webUrl: "https://gitlab.com/-/work_items/10",
-              widgets: [],
-            },
-            errors: [],
-          },
-        });
-
-        const tool = workitemsToolRegistry.get("manage_work_item");
-        await tool?.handler({
-          action: "add_link",
-          id: "100",
-          targetId: "200",
-          linkType: "RELATES_TO",
-        });
-
-        expect(mockClient.request).toHaveBeenCalledWith(expect.anything(), {
-          input: {
-            id: "gid://gitlab/WorkItem/100",
-            workItemsIds: ["gid://gitlab/WorkItem/200"],
-            linkType: "RELATED",
-          },
-        });
-      });
-
       it("should handle GraphQL errors in add_link action", async () => {
         mockClient.request.mockResolvedValueOnce({
           workItemAddLinkedItems: {
@@ -1506,9 +1473,18 @@ describe("Workitems Registry - CQRS Tools", () => {
             action: "add_link",
             id: "100",
             targetId: "200",
-            linkType: "IS_BLOCKED_BY",
+            linkType: "BLOCKED_BY",
           })
         ).rejects.toThrow("Add linked item failed - no work item returned");
+
+        // Verify BLOCKED_BY is passed directly to GraphQL API without mapping
+        expect(mockClient.request).toHaveBeenCalledWith(expect.anything(), {
+          input: {
+            id: "gid://gitlab/WorkItem/100",
+            workItemsIds: ["gid://gitlab/WorkItem/200"],
+            linkType: "BLOCKED_BY",
+          },
+        });
       });
     });
 
@@ -1547,39 +1523,6 @@ describe("Workitems Registry - CQRS Tools", () => {
         expect(result).toHaveProperty("id");
       });
 
-      it("should map RELATES_TO to RELATED in remove_link", async () => {
-        mockClient.request.mockResolvedValueOnce({
-          workItemRemoveLinkedItems: {
-            workItem: {
-              id: "gid://gitlab/WorkItem/100",
-              iid: "10",
-              title: "Source",
-              state: "OPEN",
-              workItemType: { id: "gid://gitlab/WorkItems::Type/2", name: "Issue" },
-              webUrl: "https://gitlab.com/-/work_items/10",
-              widgets: [],
-            },
-            errors: [],
-          },
-        });
-
-        const tool = workitemsToolRegistry.get("manage_work_item");
-        await tool?.handler({
-          action: "remove_link",
-          id: "100",
-          targetId: "200",
-          linkType: "RELATES_TO",
-        });
-
-        expect(mockClient.request).toHaveBeenCalledWith(expect.anything(), {
-          input: {
-            id: "gid://gitlab/WorkItem/100",
-            workItemsIds: ["gid://gitlab/WorkItem/200"],
-            linkType: "RELATED",
-          },
-        });
-      });
-
       it("should handle GraphQL errors in remove_link action", async () => {
         mockClient.request.mockResolvedValueOnce({
           workItemRemoveLinkedItems: {
diff --git a/tests/unit/utils/idConversion.test.ts b/tests/unit/utils/idConversion.test.ts
@@ -212,7 +212,7 @@ describe("idConversion utils", () => {
       expect(result.workItemType).toBe("Epic");
     });
 
-    it("should clean linked items widget GIDs and map RELATED to RELATES_TO", () => {
+    it("should clean linked items widget GIDs", () => {
       const workItem: GitLabWorkItem = {
         id: "gid://gitlab/WorkItem/100",
         widgets: [
@@ -236,7 +236,7 @@ describe("idConversion utils", () => {
 
       const result = cleanWorkItemResponse(workItem);
       const linkedWidget = result.widgets?.[0];
-      expect(linkedWidget?.linkedItems?.nodes?.[0].linkType).toBe("RELATES_TO");
+      expect(linkedWidget?.linkedItems?.nodes?.[0].linkType).toBe("RELATED");
       expect(linkedWidget?.linkedItems?.nodes?.[0].workItem?.id).toBe("200");
       expect(linkedWidget?.linkedItems?.nodes?.[1].linkType).toBe("BLOCKS");
       expect(linkedWidget?.linkedItems?.nodes?.[1].workItem?.id).toBe("300");
