feat(import): add stable per-resource source keys to the importer contract (#614)

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>

plugins/importer-postman/tests/fixtures/auth.output.json

@@ -300,5 +300,8 @@
       }
     ],
     "folders": []
+  },
+  "sourceKeys": {
+    "GENERATE_ID::WORKSPACE_0": "collection:9e6dfada-256c-49ea-a38f-7d1b05b7ca2d"
   }
 }

plugins/importer-postman/tests/fixtures/nested.output.json

@@ -88,5 +88,8 @@
         "folderId": "GENERATE_ID::FOLDER_0"
       }
     ]
+  },
+  "sourceKeys": {
+    "GENERATE_ID::WORKSPACE_1": "collection:9e6dfada-256c-49ea-a38f-7d1b05b7ca2d"
   }
 }

plugins/importer-postman/tests/fixtures/params.output.json

@@ -100,5 +100,8 @@
       }
     ],
     "folders": []
+  },
+  "sourceKeys": {
+    "GENERATE_ID::WORKSPACE_2": "collection:9e6dfada-256c-49ea-a38f-7d1b05b7ca2d"
   }
 }

plugins/importer-postman/tests/index.test.ts

@@ -87,4 +87,55 @@ describe("importer-postman", () => {
       }),
     ]);
   });
+
+  test("Keys items by their Postman ID, unchanged by a rename", () => {
+    const collection = (requestName: string) =>
+      JSON.stringify({
+        info: {
+          _postman_id: "collection-id",
+          name: "Keys",
+          schema: "https://schema.getpostman.com/json/collection/v2.1.0/collection.json",
+        },
+        item: [
+          {
+            id: "folder-id",
+            name: "Folder",
+            item: [
+              {
+                id: "request-id",
+                name: requestName,
+                request: { method: "GET", url: "https://yaak.app" },
+              },
+            ],
+          },
+        ],
+      });
+
+    const before = convertPostman(collection("Original"));
+    const after = convertPostman(collection("Renamed"));
+
+    const keyOf = (result: ReturnType<typeof convertPostman>, id: string | undefined) =>
+      id == null ? undefined : result?.sourceKeys?.[id];
+
+    expect(keyOf(before, before?.resources.httpRequests[0]?.id)).toBe("item:request-id");
+    expect(keyOf(after, after?.resources.httpRequests[0]?.id)).toBe("item:request-id");
+    expect(keyOf(before, before?.resources.folders[0]?.id)).toBe("item:folder-id");
+    expect(keyOf(before, before?.resources.workspaces[0]?.id)).toBe("collection:collection-id");
+  });
+
+  test("Omits keys for items the collection never identified", () => {
+    const result = convertPostman(
+      JSON.stringify({
+        info: {
+          name: "No IDs",
+          schema: "https://schema.getpostman.com/json/collection/v2.1.0/collection.json",
+        },
+        item: [{ name: "Request", request: { method: "GET", url: "https://yaak.app" } }],
+      }),
+    );
+
+    const requestId = result?.resources.httpRequests[0]?.id;
+    expect(requestId).toBeDefined();
+    expect(result?.sourceKeys).not.toHaveProperty(requestId as string);
+  });
 });