fix publish drift issue with api operation description

Author: EMaher

src/services/api-publisher.ts

@@ -11,6 +11,7 @@ import type { IApimClient } from '../clients/iapim-client.js';
 import type { IArtifactStore } from '../clients/iartifact-store.js';
 import type { ApimServiceContext, ResourceDescriptor } from '../models/types.js';
 import type { PublishConfig } from '../models/config.js';
+import * as yaml from 'js-yaml';
 import { ResourceType } from '../models/resource-types.js';
 import { publishResource, type ResourcePublishResult } from './resource-publisher.js';
 import { runParallel } from '../lib/parallel-runner.js';
@@ -56,6 +57,15 @@ export async function publishApi(
       return rootResult;
     }
 
+    if (rootResult.specImported && rootResult.operationIdsWithNullDescription?.length) {
+      await alignImportedOperationDescriptions(
+        client,
+        context,
+        descriptor,
+        rootResult.operationIdsWithNullDescription
+      );
+    }
+
     // Step 2: Find and publish revisions in numeric order
     const publishedRevisionCount = await publishApiRevisions(client, store, context, descriptor, config);
 
@@ -125,6 +135,7 @@ function getImportFormat(specFormat: string, _apiType?: string): string | undefi
 interface RootApiResult {
   status: 'success' | 'skipped';
   specImported: boolean;
+  operationIdsWithNullDescription?: string[];
   isCurrent?: boolean;
 }
 
@@ -162,6 +173,7 @@ async function publishRootApi(
 
   // Try to read the specification file for this API
   let specImported = false;
+  let operationIdsWithNullDescription: string[] = [];
   const includeSpecification = options?.includeSpecification ?? true;
   const specResult = includeSpecification
     ? await store.readContent(config.sourceDir, descriptor, 'specification')
@@ -197,6 +209,14 @@ async function publishRootApi(
           value: specResult.content,
         },
       };
+
+      if (importFormat === 'openapi' || importFormat === 'openapi+json') {
+        operationIdsWithNullDescription = getOpenApiOperationIdsWithNullDescription(
+          specResult.content,
+          specResult.format
+        );
+      }
+
       specImported = true;
       logger.info(`Including ${specResult.format} specification in API import for "${getNamePart(descriptor.nameParts, 0)}"`);
     }
@@ -210,6 +230,7 @@ async function publishRootApi(
     status: 'success',
     action: 'put',
     specImported,
+    operationIdsWithNullDescription,
     isCurrent,
   };
 }
@@ -453,3 +474,91 @@ function getApiIsCurrent(json: Record<string, unknown>): boolean | undefined {
   const isCurrent = properties?.isCurrent;
   return typeof isCurrent === 'boolean' ? isCurrent : undefined;
 }
+
+async function alignImportedOperationDescriptions(
+  client: IApimClient,
+  context: ApimServiceContext,
+  apiDescriptor: ResourceDescriptor,
+  operationIdsWithNullDescription: string[]
+): Promise<void> {
+  const apiName = getNamePart(apiDescriptor.nameParts, 0);
+
+  for (const operationName of operationIdsWithNullDescription) {
+    const operationDescriptor: ResourceDescriptor = {
+      type: ResourceType.ApiOperation,
+      nameParts: [apiName, operationName],
+      workspace: apiDescriptor.workspace,
+    };
+
+    const operation = await client.getResource(context, operationDescriptor);
+    if (!operation) {
+      continue;
+    }
+
+    const props = operation.properties as Record<string, unknown> | undefined;
+    if (!props || props.description === null) {
+      continue;
+    }
+
+    await client.putResource(context, operationDescriptor, {
+      ...operation,
+      properties: {
+        ...props,
+        description: null,
+      },
+    });
+  }
+}
+
+function getOpenApiOperationIdsWithNullDescription(
+  specContent: string,
+  specFormat?: string
+): string[] {
+  try {
+    const parsed: unknown =
+      specFormat === 'json'
+        ? JSON.parse(specContent)
+        : yaml.load(specContent);
+
+    if (!parsed || typeof parsed !== 'object') {
+      return [];
+    }
+
+    const parsedRecord = parsed as Record<string, unknown>;
+    const pathsValue = parsedRecord.paths;
+    if (!pathsValue || typeof pathsValue !== 'object') {
+      return [];
+    }
+
+    const paths = pathsValue as Record<string, unknown>;
+
+    const methods = new Set(['get', 'put', 'post', 'delete', 'options', 'head', 'patch', 'trace']);
+    const operationIds = new Set<string>();
+
+    for (const pathItem of Object.values(paths)) {
+      if (!pathItem || typeof pathItem !== 'object') {
+        continue;
+      }
+
+      for (const [methodName, operation] of Object.entries(pathItem as Record<string, unknown>)) {
+        if (!methods.has(methodName.toLowerCase()) || !operation || typeof operation !== 'object') {
+          continue;
+        }
+
+        const operationRecord = operation as Record<string, unknown>;
+        const operationId = operationRecord.operationId;
+        if (typeof operationId !== 'string' || operationId.length === 0) {
+          continue;
+        }
+
+        if (!Object.hasOwn(operationRecord, 'description') || operationRecord.description == null) {
+          operationIds.add(operationId);
+        }
+      }
+    }
+
+    return [...operationIds];
+  } catch {
+    return [];
+  }
+}

src/services/publish-service.ts

@@ -284,10 +284,12 @@ async function executePuts(
         );
       }
     } else if (tier === 2) {
+      const tier2Descriptors = filterApiRevisionsHandledByRootApis(descriptors);
+
       const { mcpApis, regularTier2 } = await splitMcpApis(
         store,
         config.sourceDir,
-        descriptors
+        tier2Descriptors
       );
 
       await publishAndOutput(client, store, context, config, regularTier2, results);
@@ -472,9 +474,13 @@ async function publishTier(
   const tasks = descriptors.map((descriptor) => async () => {
     try {
       let publishResult: ResourcePublishResult;
+      const apiName = descriptor.type === ResourceType.Api
+        ? getNamePart(descriptor.nameParts, 0)
+        : undefined;
+      const isApiRevision = typeof apiName === 'string' && isApiRevisionName(apiName);
 
       // Use specialized publishers for Api and Product types
-      if (descriptor.type === ResourceType.Api) {
+      if (descriptor.type === ResourceType.Api && !isApiRevision) {
         publishResult = await publishApi(client, store, context, descriptor, config);
       } else if (descriptor.type === ResourceType.Product) {
         publishResult = await publishProduct(client, store, context, descriptor, config);
@@ -524,6 +530,47 @@ async function publishTier(
   });
 }
 
+function filterApiRevisionsHandledByRootApis(
+  descriptors: ResourceDescriptor[]
+): ResourceDescriptor[] {
+  const rootApiNames = new Set<string>();
+  for (const descriptor of descriptors) {
+    if (descriptor.type !== ResourceType.Api) {
+      continue;
+    }
+
+    const apiName = getNamePart(descriptor.nameParts, 0);
+    if (!isApiRevisionName(apiName)) {
+      rootApiNames.add(apiName);
+    }
+  }
+
+  if (rootApiNames.size === 0) {
+    return descriptors;
+  }
+
+  return descriptors.filter((descriptor) => {
+    if (descriptor.type !== ResourceType.Api) {
+      return true;
+    }
+
+    const apiName = getNamePart(descriptor.nameParts, 0);
+    if (!isApiRevisionName(apiName)) {
+      return true;
+    }
+
+    return !rootApiNames.has(getApiRootName(apiName));
+  });
+}
+
+function isApiRevisionName(apiName: string): boolean {
+  return apiName.includes(';rev=');
+}
+
+function getApiRootName(apiName: string): string {
+  return apiName.split(';rev=')[0] ?? apiName;
+}
+
 /**
  * Execute DELETE operations in reverse dependency order (tier 4 → tier 1).
  */

src/services/resource-publisher.ts

@@ -112,6 +112,13 @@ export async function publishResource(
     // Apply overrides (deep merge, preserves opaque structure)
     json = applyOverrides(descriptor, json, config.overrides);
 
+    // API operations: enforce explicit empty strings for text fields when omitted.
+    // APIM may synthesize description from displayName when description is absent,
+    // causing extract/publish round-trip drift.
+    if (descriptor.type === ResourceType.ApiOperation) {
+      json = normalizeApiOperationTextFields(json);
+    }
+
     // For KeyVault-backed NamedValues:
     //   1. Strip properties.value — APIM must not receive both keyVault and value
     //      in the same PUT body, as it causes indefinite provisioning or rejection.
@@ -508,6 +515,32 @@ function normalizeMcpToolOperationIds(
   };
 }
 
+function normalizeApiOperationTextFields(
+  json: Record<string, unknown>
+): Record<string, unknown> {
+  const props = json.properties as Record<string, unknown> | undefined;
+  if (!props) {
+    return json;
+  }
+
+  const normalizedProps: Record<string, unknown> = {
+    ...props,
+  };
+
+  if (normalizedProps.displayName == null) {
+    normalizedProps.displayName = '';
+  }
+
+  if (normalizedProps.description == null) {
+    normalizedProps.description = '';
+  }
+
+  return {
+    ...json,
+    properties: normalizedProps,
+  };
+}
+
 function isAutoGeneratedProductSubscription(
   subscriptionName: string,
   scope?: string