chore: merge main into feat/publish-filtering

Author: Alexander Zaslonov

package-lock.json

@@ -207,9 +207,18 @@ export class ApimClient implements IApimClient {
 
         return response;
       } catch (error) {
-        // Do not retry client errors (4xx) — they are deterministic, not transient.
-        // 429 rate-limiting is already handled above and never reaches here.
-        if (error instanceof HttpError && error.status >= 400 && error.status < 500) {
+        // APIM reports operations blocked by an API's in-progress async operation
+        // as a transient 409. Other client errors are deterministic.
+        const isPessimisticConcurrencyConflict =
+          error instanceof HttpError &&
+          error.status === 409 &&
+          error.code === 'PessimisticConcurrencyConflict';
+        if (
+          error instanceof HttpError &&
+          error.status >= 400 &&
+          error.status < 500 &&
+          !isPessimisticConcurrencyConflict
+        ) {
           throw error;
         }
         if (attempt >= ApimClient.MAX_RETRIES) {
@@ -454,7 +463,18 @@ export class ApimClient implements IApimClient {
     context: ApimServiceContext,
     descriptor: ResourceDescriptor
   ): Promise<boolean> {
-    const url = buildArmUri(context, descriptor);
+    let url = buildArmUri(context, descriptor);
+
+    // Deleting an API that has revisions requires deleteRevisions=true; without it
+    // APIM refuses the base (current-revision) delete with "Cannot delete the
+    // current revision of an API." This also removes all revisions in one call,
+    // so callers skip the individual ;rev=N deletes.
+    if (
+      descriptor.type === ResourceType.Api &&
+      !(descriptor.nameParts[0] ?? '').includes(';rev=')
+    ) {
+      url += '&deleteRevisions=true';
+    }
 
     for (let attempt = 1; ; attempt++) {
       try {
@@ -482,6 +502,15 @@ export class ApimClient implements IApimClient {
         if (message.includes('404')) {
           return false;
         }
+        // Resource is still referenced by another entity (e.g. a policy fragment
+        // used by the service policy). It cannot be deleted until the reference is
+        // removed; skip it with a warning instead of failing the whole prune.
+        if (message.includes('is used by the following entities')) {
+          logger.warn(
+            `Skipping delete of ${buildResourceLabel(descriptor)}: still referenced by another entity`
+          );
+          return false;
+        }
         // Transient optimistic-concurrency conflict: cascade deletes of related
         // resources (subscriptions, product/gateway associations) can modify
         // the resource while its async DELETE is in flight. Retry the DELETE.

src/clients/apim-client.ts

@@ -143,6 +143,16 @@ export function getNamePart(nameParts: string[], index: number): string {
   return value;
 }
 
+/** True when an API name carries a revision suffix (e.g. "my-api;rev=2"). */
+export function isApiRevisionName(apiName: string): boolean {
+  return apiName.includes(';rev=');
+}
+
+/** Root API name with any ";rev=N" suffix stripped. */
+export function getApiRootName(apiName: string): string {
+  return apiName.split(';rev=')[0] ?? apiName;
+}
+
 /**
  * Create a case-insensitive identity key for a resource descriptor.
  */

src/lib/resource-path.ts

@@ -200,8 +200,10 @@ async function extractApiRevisions(
     for await (const revision of revisions) {
       try {
         const revNumber = (revision.apiRevision ?? revision.revisionNumber) as string | undefined;
-        if (!revNumber || revNumber === '1') {
-          // Skip revision 1 — it's the main API
+        // Skip the current revision — it is represented by the main API folder.
+        // Using isCurrent (not a hard-coded '1') correctly handles APIs whose
+        // current revision is not revision 1.
+        if (!revNumber || revision.isCurrent === true) {
           continue;
         }
 

src/services/api-extractor.ts

@@ -15,8 +15,10 @@ import * as yaml from 'js-yaml';
 import { ResourceType } from '../models/resource-types.js';
 import {
   applyApiPathPrefix,
+  normalizeApiAuthenticationSettings,
   normalizeMcpToolOperationIds,
   normalizeApiVersionSetId,
+  prefersLegacyAuthOverride,
   publishResource,
   type ResourcePublishResult,
 } from './resource-publisher.js';
@@ -77,6 +79,7 @@ export async function publishApi(
   allowedDescriptors?: ResourceDescriptor[]
 ): Promise<ResourcePublishResult> {
   let publicationPlan: ApiPublicationPlan;
+  let rootPutDescriptor: ResourceDescriptor;
   let rootPublished = false;
   try {
     publicationPlan = await planApiPublication(
@@ -85,6 +88,20 @@ export async function publishApi(
       config,
       allowedDescriptors
     );
+
+    // Deployed (env-mapped) base descriptor — derived once and used for every
+    // direct APIM call so canonical and affixed names can never diverge.
+    const deployedDescriptor = config.envMapping
+      ? mapDescriptor(descriptor, config.envMapping)
+      : descriptor;
+    rootPutDescriptor = await resolveRootApiPutDescriptor(
+      client,
+      store,
+      context,
+      descriptor,
+      deployedDescriptor,
+      config
+    );
   } catch (error) {
     return {
       descriptor,
@@ -98,6 +115,7 @@ export async function publishApi(
     // Step 1: Publish root API (with spec import if available)
     const rootResult = await publishRootApi(client, store, context, descriptor, config, {
       includeSpecification: publicationPlan.importSpecification,
+      putDescriptor: rootPutDescriptor,
     });
     if (rootResult.status !== 'success') {
       return rootResult;
@@ -213,7 +231,7 @@ export async function planApiPublication(
     ? new Set(allowedDescriptors.map(getResourceDescriptorKey))
     : undefined;
   const rootName = apiName.toLowerCase();
-  const revisions = allDescriptors
+  let revisions = allDescriptors
     .filter(
       (descriptor) =>
         descriptor.type === ResourceType.Api &&
@@ -234,6 +252,14 @@ export async function planApiPublication(
   const mergedApiJson = apiJson
     ? applyOverrides(apiDescriptor, apiJson, config.overrides)
     : undefined;
+  const rootRevision = (apiJson?.properties as Record<string, unknown> | undefined)?.apiRevision;
+  if (typeof rootRevision === 'string' && rootRevision !== '') {
+    const rootRevisionNumber = Number(rootRevision);
+    revisions = revisions.filter(
+      (revision) =>
+        extractRevisionNumber(getNamePart(revision.nameParts, 0)) !== rootRevisionNumber
+    );
+  }
   const specificationAllowed =
     subFilter?.operations === undefined &&
     subFilter?.schemas === undefined &&
@@ -387,6 +413,49 @@ interface RootApiResult {
 
 interface PublishRootApiOptions {
   includeSpecification?: boolean;
+  /** Descriptor to PUT to (defaults to the artifact descriptor). Lets the root
+   * API be created at apis/{name};rev=N while still reading apis/{name} artifacts. */
+  putDescriptor?: ResourceDescriptor;
+}
+
+/**
+ * A plain root PUT creates a brand-new API as revision 1, which collides with
+ * a ;rev=1 revision artifact and silently absorbs it whenever the source's
+ * current revision number is > 1. When the API does not yet exist on the
+ * target, PUT the root at its true revision number (apis/{name};rev=N) instead.
+ * Existing APIs keep the plain root PUT — their current revision cannot be
+ * renumbered.
+ *
+ * Reads artifacts via the canonical descriptor; all APIM lookups and the
+ * returned PUT target use the deployed (env-mapped) descriptor, with ;rev=N
+ * appended after affixing so suffix mappings cannot corrupt it.
+ */
+async function resolveRootApiPutDescriptor(
+  client: IApimClient,
+  store: IArtifactStore,
+  context: ApimServiceContext,
+  descriptor: ResourceDescriptor,
+  deployedDescriptor: ResourceDescriptor,
+  config: PublishConfig
+): Promise<ResourceDescriptor> {
+  const json = await store.readResource(config.sourceDir, descriptor);
+  const rev = (json?.properties as Record<string, unknown> | undefined)?.apiRevision;
+  if (typeof rev !== 'string' || rev === '' || rev === '1') {
+    return deployedDescriptor;
+  }
+
+  const existing = await client.getResource(context, deployedDescriptor);
+  if (existing) {
+    return deployedDescriptor;
+  }
+
+  return {
+    ...deployedDescriptor,
+    nameParts: [
+      `${getNamePart(deployedDescriptor.nameParts, 0)};rev=${rev}`,
+      ...deployedDescriptor.nameParts.slice(1),
+    ],
+  };
 }
 
 /**
@@ -420,6 +489,12 @@ async function publishRootApi(
 
   // Apply overrides
   json = applyOverrides(descriptor, json, config.overrides);
+  json = normalizeApiAuthenticationSettings(json, {
+    preferLegacyFields: prefersLegacyAuthOverride(
+      getNamePart(descriptor.nameParts, 0),
+      config.overrides?.apis
+    ),
+  });
   const isCurrent = getApiIsCurrent(json);
 
   // Try to read the specification file for this API
@@ -482,7 +557,7 @@ async function publishRootApi(
 
   // PUT the API resource to APIM
   try {
-    await client.putResource(context, deployedDescriptor, json);
+    await client.putResource(context, options?.putDescriptor ?? deployedDescriptor, json);
   } catch (error) {
     throw new ApiPutAttemptError(error);
   }
@@ -525,7 +600,13 @@ async function publishApiRevisions(
   // Publish each revision in order
   const results: ResourcePublishResult[] = [];
   for (const revDescriptor of revisionDescriptors) {
-    results.push(await publishResource(client, store, context, revDescriptor, config));
+    const result = await publishResource(client, store, context, revDescriptor, config);
+    if (result.status === 'failed') {
+      throw new Error(
+        `Failed to publish revision ${getNamePart(revDescriptor.nameParts, 0)}: ${result.error?.message ?? 'unknown error'}`
+      );
+    }
+    results.push(result);
   }
 
   return results;

src/services/api-publisher.ts

@@ -29,10 +29,54 @@ import type { ApimServiceContext, ResourceDescriptor } from '../models/types.js'
 import type { PublishConfig } from '../models/config.js';
 import { ResourceType } from '../models/resource-types.js';
 import { getTopologicalOrder } from '../lib/dependency-graph.js';
-import { getNameFromNameParts } from '../lib/resource-path.js';
+import {
+  getNameFromNameParts,
+  getNamePart,
+  getApiRootName,
+  isApiRevisionName,
+} from '../lib/resource-path.js';
 import { logger } from '../lib/logger.js';
 import { toCanonicalDescriptor } from './env-mapper.js';
 
+/**
+ * Drop ;rev=N API deletes whose base API (same workspace) is also queued for
+ * deletion. The base API delete uses deleteRevisions=true and removes all
+ * revisions in one call, so individual revision deletes are redundant and can
+ * hit APIM's "Cannot delete the current revision of an API" error.
+ *
+ * Shared by the real delete path and the dry-run reporter so the preview
+ * matches what publish would actually delete.
+ */
+export function filterRevisionDeletesHandledByBaseApi(
+  descriptors: ResourceDescriptor[]
+): ResourceDescriptor[] {
+  const baseApiKeys = new Set<string>();
+  for (const descriptor of descriptors) {
+    if (descriptor.type !== ResourceType.Api) {
+      continue;
+    }
+    const apiName = getNamePart(descriptor.nameParts, 0);
+    if (!isApiRevisionName(apiName)) {
+      baseApiKeys.add(`${descriptor.workspace ?? ''}::${apiName}`);
+    }
+  }
+
+  if (baseApiKeys.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 !baseApiKeys.has(`${descriptor.workspace ?? ''}::${getApiRootName(apiName)}`);
+  });
+}
+
 /**
  * Built-in groups that should never be deleted
  */

src/services/delete-unmatched-service.ts

@@ -15,7 +15,10 @@ import { getTopologicalOrder } from '../lib/dependency-graph.js';
 import { buildResourceLabel } from '../lib/resource-uri.js';
 import { getResourceDescriptorKey } from '../lib/resource-path.js';
 import { logger } from '../lib/logger.js';
-import { computeDeleteActions } from './delete-unmatched-service.js';
+import {
+  computeDeleteActions,
+  filterRevisionDeletesHandledByBaseApi,
+} from './delete-unmatched-service.js';
 import { applyOverrides } from './override-merger.js';
 import {
   evaluateResourceEligibility,
@@ -156,8 +159,10 @@ export async function generateDryRunReport(
 
   // In incremental mode, use precomputed deleted descriptors from git diff.
   // Otherwise, if delete-unmatched is enabled, calculate full unmatched deletes.
+  // Apply the same ;rev=N filtering as the real delete path so the preview
+  // matches what publish would actually delete.
   if (incrementalDeletedDescriptors.length > 0) {
-    for (const descriptor of incrementalDeletedDescriptors) {
+    for (const descriptor of filterRevisionDeletesHandledByBaseApi(incrementalDeletedDescriptors)) {
       try {
         const deployedDescriptor = config.envMapping
           ? mapDescriptor(descriptor, config.envMapping)
@@ -212,12 +217,14 @@ export async function generateDryRunReport(
       }
     }
   } else if (config.deleteUnmatched && !config.commitId) {
-    const deleteActions = await computeDeleteActionsForDryRun(
-      client,
-      store,
-      context,
-      config,
-      targetDescriptors
+    const deleteActions = filterRevisionDeletesHandledByBaseApi(
+      await computeDeleteActionsForDryRun(
+        client,
+        store,
+        context,
+        config,
+        targetDescriptors
+      )
     );
 
     for (const descriptor of deleteActions) {