Adding support for specification updates when in incremental mode.

Author: EMaher

src/lib/resource-path.ts

@@ -20,6 +20,15 @@ const ASSOCIATION_TYPES = new Set<ResourceType>([
   ResourceType.GatewayApi,
 ]);
 
+const SUPPORTED_SPECIFICATION_EXTENSIONS = new Set([
+  'yaml',
+  'yml',
+  'json',
+  'graphql',
+  'wsdl',
+  'wadl',
+]);
+
 /**
  * Fills all positional `{i}` tokens in a template string with `nameParts[i]`.
  * Throws if a placeholder index has no corresponding entry in `nameParts`.
@@ -385,6 +394,79 @@ export function parseArtifactPath(
   return undefined;
 }
 
+/**
+ * Parse a changed artifact file path into a ResourceDescriptor.
+ *
+ * This extends `parseArtifactPath` with support for supplemental artifact
+ * files that belong to a resource but are not the primary info file.
+ *
+ * Currently supports:
+ * - API specification files (`apis/{api}/specification.{ext}`)
+ * - Workspace-scoped API specification files
+ *   (`workspaces/{workspace}/apis/{api}/specification.{ext}`)
+ */
+export function parseArtifactChangePath(
+  baseDir: string,
+  filePath: string
+): ResourceDescriptor | undefined {
+  const directDescriptor = parseArtifactPath(baseDir, filePath);
+  if (directDescriptor) {
+    return directDescriptor;
+  }
+
+  const relativePath = toTemplatePath(path.relative(baseDir, filePath));
+
+  const rootApiSpec = parseTemplatePath('apis/{0}/specification.{1}', relativePath);
+  if (rootApiSpec && rootApiSpec.length === 2) {
+    const apiName = getCapture(rootApiSpec, 0);
+    const extension = getCapture(rootApiSpec, 1);
+    if (apiName && isSupportedSpecificationExtension(extension)) {
+      return {
+        type: ResourceType.Api,
+        nameParts: [apiName],
+      };
+    }
+  }
+
+  const workspaceApiSpec = parseTemplatePath(
+    'workspaces/{0}/apis/{1}/specification.{2}',
+    relativePath
+  );
+  if (workspaceApiSpec && workspaceApiSpec.length === 3) {
+    const workspace = getCapture(workspaceApiSpec, 0);
+    const apiName = getCapture(workspaceApiSpec, 1);
+    const extension = getCapture(workspaceApiSpec, 2);
+    if (workspace && apiName && isSupportedSpecificationExtension(extension)) {
+      return {
+        type: ResourceType.Api,
+        nameParts: [apiName],
+        workspace,
+      };
+    }
+  }
+
+  return undefined;
+}
+
+function toTemplatePath(relativePath: string): string {
+  return relativePath.split(path.sep).join('/');
+}
+
+function getCapture(captures: string[], index: number): string | undefined {
+  if (captures.length <= index) {
+    return undefined;
+  }
+  return captures[index];
+}
+
+function isSupportedSpecificationExtension(extension: string | undefined): boolean {
+  if (!extension) {
+    return false;
+  }
+
+  return SUPPORTED_SPECIFICATION_EXTENSIONS.has(extension.toLowerCase());
+}
+
 /**
  * Check if a resource type is a singleton (no list, only get).
  * Singletons have armPathSuffix ending with a fixed segment (no `{n}` placeholder).

src/services/api-publisher.ts

@@ -255,23 +255,34 @@ async function publishApiChildren(
   // schemaId/typeName references in representations. Re-include operations that
   // carry such references so those links are explicitly restored via PUT.
   if (specImported) {
+    // In incremental mode, avoid re-publishing operation artifacts after spec
+    // import. This prevents stale operation JSON from overwriting newly
+    // imported OpenAPI operation metadata (for example descriptions).
+    const shouldRepublishSchemaRefOps = !config.commitId;
+
     const operationDescriptors = allDescriptors.filter(
       (d) =>
         d.type === ResourceType.ApiOperation &&
         getNamePart(d.nameParts, 0) === getNamePart(apiDescriptor.nameParts, 0)
     );
 
-    const schemaRefOps = await filterOperationsWithSchemaRefs(
-      store,
-      config.sourceDir,
-      operationDescriptors
-    );
+    if (shouldRepublishSchemaRefOps) {
+      const schemaRefOps = await filterOperationsWithSchemaRefs(
+        store,
+        config.sourceDir,
+        operationDescriptors
+      );
 
-    if (schemaRefOps.length > 0) {
+      if (schemaRefOps.length > 0) {
+        logger.debug(
+          `Re-publishing ${schemaRefOps.length} operation(s) with schema references after spec import for "${getNamePart(apiDescriptor.nameParts, 0)}"`
+        );
+        childDescriptors = [...childDescriptors, ...schemaRefOps];
+      }
+    } else {
       logger.debug(
-        `Re-publishing ${schemaRefOps.length} operation(s) with schema references after spec import for "${getNamePart(apiDescriptor.nameParts, 0)}"`
+        `Skipping schema-reference operation re-publish for "${getNamePart(apiDescriptor.nameParts, 0)}" in incremental mode`
       );
-      childDescriptors = [...childDescriptors, ...schemaRefOps];
     }
 
     // Re-include explicitly named schemas (non-auto-generated IDs).

src/services/git-diff-service.ts

@@ -7,7 +7,7 @@
 import { simpleGit, SimpleGit } from 'simple-git';
 import * as path from 'node:path';
 import { ResourceDescriptor } from '../models/types.js';
-import { parseArtifactPath } from '../lib/resource-path.js';
+import { parseArtifactChangePath } from '../lib/resource-path.js';
 import { logger } from '../lib/logger.js';
 
 export interface GitDiffResult {
@@ -61,7 +61,7 @@ export async function computeGitDiff(
     // Get diff between parent and current commit
     // If no parent, diff against empty tree (shows all files as added)
     const diffTarget = hasParent ? parentCommit : '4b825dc642cb6eb9a060e54bf8d69288fbee4904'; // Git empty tree SHA
-    const diffOutput = await git.diff(['--name-status', diffTarget, commitId]);
+    const diffOutput = await git.diff(['--name-status', '--relative', diffTarget, commitId]);
 
     return parseDiffOutput(diffOutput, sourceDir);
   } catch (error) {
@@ -105,12 +105,7 @@ function parseDiffOutput(diffOutput: string, sourceDir: string): GitDiffResult {
       continue;
     }
 
-    // Convert relative path to absolute for parsing
-    const absolutePath = path.isAbsolute(filePath)
-      ? filePath
-      : path.join(sourceDir, filePath);
-
-    const descriptor = parseArtifactPath(sourceDir, absolutePath);
+    const descriptor = parseDescriptorFromDiffPath(sourceDir, filePath);
     if (!descriptor) {
       continue;
     }
@@ -119,30 +114,16 @@ function parseDiffOutput(diffOutput: string, sourceDir: string): GitDiffResult {
     const key = descriptorKey(descriptor);
 
     if (status === 'D') {
-      // Deleted file
-      if (!seenDeleted.has(key)) {
-        deletedDescriptors.push(descriptor);
-        seenDeleted.add(key);
-      }
+      addUniqueDescriptor(deletedDescriptors, seenDeleted, descriptor, key);
     } else if (status === 'M' || status === 'A' || status === 'R' || status === 'C') {
-      // Modified, added, renamed, or copied file
-      if (!seenChanged.has(key)) {
-        changedDescriptors.push(descriptor);
-        seenChanged.add(key);
-      }
+      addUniqueDescriptor(changedDescriptors, seenChanged, descriptor, key);
 
       // For renames, also parse the new path (in parts[2])
-      if (status === 'R' && parts[2]) {
-        const newPath = path.isAbsolute(parts[2])
-          ? parts[2]
-          : path.join(sourceDir, parts[2]);
-        const newDescriptor = parseArtifactPath(sourceDir, newPath);
+      if (status === 'R' && parts.length > 2 && parts[2]) {
+        const newDescriptor = parseDescriptorFromDiffPath(sourceDir, parts[2]);
         if (newDescriptor) {
           const newKey = descriptorKey(newDescriptor);
-          if (!seenChanged.has(newKey)) {
-            changedDescriptors.push(newDescriptor);
-            seenChanged.add(newKey);
-          }
+          addUniqueDescriptor(changedDescriptors, seenChanged, newDescriptor, newKey);
         }
       }
     }
@@ -161,3 +142,28 @@ function parseDiffOutput(diffOutput: string, sourceDir: string): GitDiffResult {
 function descriptorKey(descriptor: ResourceDescriptor): string {
   return [descriptor.type, ...descriptor.nameParts, descriptor.workspace ?? ''].join('::');
 }
+
+function addUniqueDescriptor(
+  target: ResourceDescriptor[],
+  seen: Set<string>,
+  descriptor: ResourceDescriptor,
+  key: string
+): void {
+  if (seen.has(key)) {
+    return;
+  }
+
+  target.push(descriptor);
+  seen.add(key);
+}
+
+function parseDescriptorFromDiffPath(
+  sourceDir: string,
+  diffPath: string
+): ResourceDescriptor | undefined {
+  const absolutePath = path.isAbsolute(diffPath)
+    ? diffPath
+    : path.join(sourceDir, diffPath);
+
+  return parseArtifactChangePath(sourceDir, absolutePath);
+}

tests/unit/lib/resource-path.test.ts

@@ -13,6 +13,7 @@ import {
   buildSpecificationFilePath,
   buildAssociationFilePath,
   parseArtifactPath,
+  parseArtifactChangePath,
   deriveListPaths,
   hasNestedParent,
   getPublishTier,
@@ -323,6 +324,51 @@ describe('parseArtifactPath', () => {
   });
 });
 
+describe('parseArtifactChangePath', () => {
+  it('should parse regular info files via parseArtifactPath fallback', () => {
+    const filePath = path.join(baseDir, 'apis', 'my-api', 'apiInformation.json');
+    const result = parseArtifactChangePath(baseDir, filePath);
+
+    expect(result).toBeDefined();
+    expect(result!.type).toBe(ResourceType.Api);
+    expect(result!.nameParts).toEqual(['my-api']);
+  });
+
+  it('should parse API specification file to Api descriptor', () => {
+    const filePath = path.join(baseDir, 'apis', 'my-api', 'specification.yaml');
+    const result = parseArtifactChangePath(baseDir, filePath);
+
+    expect(result).toBeDefined();
+    expect(result!.type).toBe(ResourceType.Api);
+    expect(result!.nameParts).toEqual(['my-api']);
+    expect(result!.workspace).toBeUndefined();
+  });
+
+  it('should parse workspace-scoped API specification file', () => {
+    const filePath = path.join(
+      baseDir,
+      'workspaces',
+      'dev',
+      'apis',
+      'my-api',
+      'specification.json'
+    );
+    const result = parseArtifactChangePath(baseDir, filePath);
+
+    expect(result).toBeDefined();
+    expect(result!.type).toBe(ResourceType.Api);
+    expect(result!.nameParts).toEqual(['my-api']);
+    expect(result!.workspace).toBe('dev');
+  });
+
+  it('should ignore unsupported specification extensions', () => {
+    const filePath = path.join(baseDir, 'apis', 'my-api', 'specification.txt');
+    const result = parseArtifactChangePath(baseDir, filePath);
+
+    expect(result).toBeUndefined();
+  });
+});
+
 describe('buildArtifactFilePath + parseArtifactPath roundtrip', () => {
   const topLevelTypes: { type: ResourceType; nameParts: string[] }[] = [
     { type: ResourceType.NamedValue, nameParts: ['nv1'] },

tests/unit/services/api-publisher.test.ts

@@ -766,6 +766,59 @@ describe('api-publisher', () => {
       expect(totalTasks).toBe(2);
     });
 
+    it('should not re-publish schema-reference operations in incremental mode after spec import', async () => {
+      const client = createMockClient();
+      const children = [
+        { type: ResourceType.ApiPolicy, nameParts: ['petstore', 'policy-1'] },
+        { type: ResourceType.ApiOperation, nameParts: ['petstore', 'create-item'] },
+      ];
+      const store = createMockStore(children);
+
+      store.readResource.mockImplementation(async (_dir: string, descriptor: ResourceDescriptor) => {
+        if (descriptor.type === ResourceType.Api) {
+          return { name: 'petstore', properties: { path: 'petstore' } };
+        }
+        if (
+          descriptor.type === ResourceType.ApiOperation &&
+          (descriptor.nameParts[1] ?? '') === 'create-item'
+        ) {
+          return {
+            name: 'create-item',
+            properties: {
+              request: {
+                representations: [{ contentType: 'application/json', schemaId: 'my-schema' }],
+              },
+            },
+          };
+        }
+        return null;
+      });
+      store.readContent.mockResolvedValue({
+        content: 'openapi: "3.0.0"',
+        format: 'yaml',
+      });
+
+      const apiDescriptor: ResourceDescriptor = {
+        type: ResourceType.Api,
+        nameParts: ['petstore'],
+      };
+
+      const incrementalConfig: PublishConfig = {
+        ...testConfig,
+        commitId: 'abc123',
+      };
+
+      await publishApi(client, store, testContext, apiDescriptor, incrementalConfig);
+
+      // Only ApiPolicy should be published as child. The schema-ref operation
+      // must be skipped in incremental mode to preserve imported spec metadata.
+      const totalTasks = mockRunParallel.mock.calls.reduce((sum, call) => {
+        const tasks = call[0] as unknown[];
+        return sum + tasks.length;
+      }, 0);
+      expect(totalTasks).toBe(1);
+    });
+
     it('should re-publish operations with schema references in response representations', async () => {
       const client = createMockClient();
       const children = [