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

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

plugins/importer-openapi/src/index.ts

@@ -110,6 +110,7 @@ export async function convertOpenApi(contents: string): Promise<ImportPluginResp
 
   const folderIdsByTag = new Map<string, string>();
   const routeLabels = new Map<string, string>();
+  const sourceKeys: Record<string, string> = {};
   for (const tag of toArray(spec.tags)) {
     const tagRecord = toRecord(tag);
     const name = stringAt(tagRecord, "name");
@@ -126,6 +127,7 @@ export async function convertOpenApi(contents: string): Promise<ImportPluginResp
     };
     resources.folders.push(folder);
     folderIdsByTag.set(name, folder.id);
+    sourceKeys[folder.id] = tagSourceKey(name);
   }
 
   for (const [rawPath, rawPathItem] of Object.entries(toRecord(spec.paths))) {
@@ -139,6 +141,7 @@ export async function convertOpenApi(contents: string): Promise<ImportPluginResp
         importState,
         operation,
         resources,
+        sourceKeys,
         workspaceId: workspace.id,
       });
 
@@ -160,6 +163,11 @@ export async function convertOpenApi(contents: string): Promise<ImportPluginResp
         authenticationVariables,
       });
       routeLabels.set(request.id, `${method.toUpperCase()} ${rawPath}`);
+      sourceKeys[request.id] = operationSourceKey(
+        stringAt(operation, "operationId"),
+        method,
+        rawPath,
+      );
       resources.httpRequests.push(request);
     }
   }
@@ -241,6 +249,7 @@ export async function convertOpenApi(contents: string): Promise<ImportPluginResp
       websocketRequests: [],
       workspaces: resources.workspaces,
     }) as PartialImportResources,
+    sourceKeys,
   };
 }
 
@@ -681,12 +690,14 @@ function findOrCreateFolderId({
   importState,
   operation,
   resources,
+  sourceKeys,
   workspaceId,
 }: {
   folderIdsByTag: Map<string, string>;
   importState: ImportState;
   operation: UnknownRecord;
   resources: ImportResources;
+  sourceKeys: Record<string, string>;
   workspaceId: string;
 }): string | null {
   const tag = toArray(operation.tags).find((t): t is string => typeof t === "string");
@@ -705,9 +716,20 @@ function findOrCreateFolderId({
   };
   resources.folders.push(folder);
   folderIdsByTag.set(tag, folder.id);
+  sourceKeys[folder.id] = tagSourceKey(tag);
   return folder.id;
 }
 
+function operationSourceKey(operationId: string | undefined, method: string, path: string): string {
+  return operationId != null && operationId !== ""
+    ? `op:${operationId}`
+    : `route:${method.toUpperCase()} ${path}`;
+}
+
+function tagSourceKey(tag: string): string {
+  return `tag:${tag}`;
+}
+
 /**
  * Yaak's `:name` placeholders only substitute when they span a whole path
  * segment and hold a single plain value. Templates elsewhere in a segment