chore: resolve PR #272 conflicts with main

Author: Alexander Zaslonov

src/clients/apim-client.ts

@@ -774,7 +774,8 @@ export class ApimClient implements IApimClient {
 
   async validatePreFlight(context: ApimServiceContext): Promise<void> {
     // Check resource group exists
-    const rgUrl = `https://management.azure.com/subscriptions/${encodeURIComponent(context.subscriptionId)}/resourceGroups/${encodeURIComponent(context.resourceGroup)}?api-version=${ApimClient.RESOURCE_GROUP_API_VERSION}`;
+    const armEndpoint = new URL(context.baseUrl).origin;
+    const rgUrl = `${armEndpoint}/subscriptions/${encodeURIComponent(context.subscriptionId)}/resourceGroups/${encodeURIComponent(context.resourceGroup)}?api-version=${ApimClient.RESOURCE_GROUP_API_VERSION}`;
     let rgResponse: Response;
     try {
       rgResponse = await this.request(rgUrl, { method: 'GET' });

src/lib/auto-generated.ts

@@ -17,6 +17,16 @@
  */
 const AUTO_GENERATED_ID_PATTERN = /^[0-9a-f]{24}$/;
 
+/**
+ * Pattern matching epoch-milliseconds schema IDs (Date.now()-style). The Azure
+ * portal generates these client-side when a definition is added to an API that
+ * has no schema resource yet (operation Frontend editor → "New definition").
+ * Verified: ARM spec import generates 24-hex IDs on every api-version
+ * 2021-08-01 … 2025-09-01-preview, so 13-digit IDs never come from import.
+ * Example: "1786466527403"
+ */
+const PORTAL_SCHEMA_ID_PATTERN = /^\d{13}$/;
+
 /**
  * Checks if a resource name/ID is an auto-generated 24-character hex ID.
  *
@@ -35,3 +45,21 @@ const AUTO_GENERATED_ID_PATTERN = /^[0-9a-f]{24}$/;
 export function isAutoGeneratedId(name: string): boolean {
   return AUTO_GENERATED_ID_PATTERN.test(name);
 }
+
+/**
+ * Checks if a schema name is a portal-generated 13-digit epoch-millis ID.
+ *
+ * Deliberately separate from isAutoGeneratedId: a 13-digit name is a weaker
+ * heuristic than 24-hex, so it must only be applied where a false positive is
+ * harmless — skipping ApiSchema re-publish when a spec import recreates the
+ * schema content anyway. It must NOT gate named values, subscriptions, or
+ * operations, where a silently skipped resource would lose data.
+ *
+ * @example
+ * isPortalGeneratedSchemaId('1786466527403')  // true
+ * isPortalGeneratedSchemaId('178646652740')   // false (12 digits)
+ * isPortalGeneratedSchemaId('my-schema')      // false
+ */
+export function isPortalGeneratedSchemaId(name: string): boolean {
+  return PORTAL_SCHEMA_ID_PATTERN.test(name);
+}

src/services/api-publisher.ts

@@ -31,7 +31,7 @@ import {
   getPublishTier,
   getResourceDescriptorKey,
 } from '../lib/resource-path.js';
-import { isAutoGeneratedId } from '../lib/auto-generated.js';
+import { isAutoGeneratedId, isPortalGeneratedSchemaId } from '../lib/auto-generated.js';
 import { resolveWorkspaceFilter, shouldIncludeResource } from './filter-service.js';
 
 /**
@@ -277,6 +277,7 @@ export async function planApiPublication(
 
   let importSpecification = false;
   let importSpecificationFormat: string | undefined;
+  let importSpecSchemaComponents: Record<string, unknown> | undefined;
   let operationDescriptionPuts: ResourceDescriptor[] = [];
   if (specificationAllowed) {
     const specification = await store.readContent(config.sourceDir, apiDescriptor, 'specification');
@@ -288,6 +289,10 @@ export async function planApiPublication(
         getImportFormat(specification.format ?? 'yaml', apiType, dialect) !== undefined;
       importSpecificationFormat = importSpecification ? specification.format : undefined;
       if (importSpecification) {
+        importSpecSchemaComponents = getSpecComponentSchemas(
+          specification.content,
+          specification.format
+        );
         operationDescriptionPuts = getOpenApiOperationIdsWithNullDescription(
           specification.content,
           specification.format
@@ -316,13 +321,52 @@ export async function planApiPublication(
   }
 
   if (importSpecification) {
-    const explicitSchemas = allDescriptors.filter(
+    const candidateSchemas = allDescriptors.filter(
       (descriptor) =>
         descriptor.type === ResourceType.ApiSchema &&
         getNamePart(descriptor.nameParts, 0).toLowerCase() === apiName.toLowerCase() &&
         descriptor.workspace === apiDescriptor.workspace &&
         !isAutoGeneratedId(getNamePart(descriptor.nameParts, 1))
     );
+    // Portal-created schemas (13-digit Date.now() names) duplicate on re-PUT
+    // because the spec import recreates their content (#274). A 13-digit name
+    // alone is a weak signal, so only skip when the imported spec provably
+    // recreates every component the artifact schema defines — same name AND
+    // structurally identical definition. Any ambiguity → publish the schema
+    // like any explicitly named one.
+    const explicitSchemas = (
+      await Promise.all(
+        candidateSchemas.map(async (descriptor) => {
+          if (!isPortalGeneratedSchemaId(getNamePart(descriptor.nameParts, 1))) {
+            return descriptor;
+          }
+          const specComponents = importSpecSchemaComponents;
+          if (!specComponents || Object.keys(specComponents).length === 0) {
+            return descriptor;
+          }
+          let schemaJson: Record<string, unknown> | undefined;
+          try {
+            schemaJson = await store.readResource(config.sourceDir, descriptor);
+          } catch {
+            return descriptor;
+          }
+          const artifactComponents = getArtifactSchemaComponents(schemaJson);
+          if (!artifactComponents) {
+            return descriptor;
+          }
+          const entries = Object.entries(artifactComponents);
+          if (entries.length === 0) {
+            return descriptor;
+          }
+          const recreatedByImport = entries.every(
+            ([name, definition]) =>
+              Object.hasOwn(specComponents, name) &&
+              deepEqualUnordered(specComponents[name], definition)
+          );
+          return recreatedByImport ? undefined : descriptor;
+        })
+      )
+    ).filter((descriptor): descriptor is ResourceDescriptor => descriptor !== undefined);
     // WSDL-import-generated XSD schemas have GUID names (not 24-hex), so the
     // isAutoGeneratedId filter misses them. APIM recreates them on WSDL import
     // and rejects re-PUTs, so exclude schemas with the XSD content type — but
@@ -1069,6 +1113,86 @@ function detectSpecDialect(content: string, format: string | undefined): ApiSpec
   }
 }
 
+/**
+ * Extracts the schema component definitions declared in an OpenAPI/Swagger
+ * spec document: `components.schemas` (OpenAPI 3.x) or `definitions`
+ * (Swagger 2.0). Returns undefined when the content is not a parseable
+ * OpenAPI/Swagger document (e.g. WSDL/GraphQL) — callers must treat that as
+ * "no evidence" rather than "no schemas".
+ */
+function getSpecComponentSchemas(
+  content: string,
+  format: string | undefined
+): Record<string, unknown> | undefined {
+  if (format !== undefined && format !== 'yaml' && format !== 'json') {
+    return undefined;
+  }
+  try {
+    const doc = yaml.load(content) as Record<string, unknown> | undefined;
+    if (!doc || typeof doc !== 'object') return undefined;
+    const components = (doc.components as Record<string, unknown> | undefined)?.schemas
+      ?? doc.definitions;
+    if (components && typeof components === 'object' && !Array.isArray(components)) {
+      return components as Record<string, unknown>;
+    }
+    return {};
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Extracts the schema component definitions from an ApiSchema artifact's
+ * `properties.document` (`components.schemas` or Swagger `definitions`).
+ * Only OpenAPI/Swagger content types are inspected: in a standalone JSON
+ * Schema document (`schemaType: json`) `definitions` has a different meaning
+ * and the spec import does not recreate such a resource, so returns
+ * undefined ("no evidence") for any other content type.
+ */
+function getArtifactSchemaComponents(
+  json: Record<string, unknown> | null | undefined
+): Record<string, unknown> | undefined {
+  const props = json?.properties as Record<string, unknown> | undefined;
+  const doc = props?.document as Record<string, unknown> | undefined;
+  if (!doc || typeof doc !== 'object') return undefined;
+  const contentType = (props?.contentType as string | undefined)?.toLowerCase() ?? '';
+  if (
+    !contentType.includes('openapi.components') &&
+    !contentType.includes('swagger.definitions')
+  ) {
+    return undefined;
+  }
+  const components = (doc.components as Record<string, unknown> | undefined)?.schemas
+    ?? doc.definitions;
+  if (components && typeof components === 'object' && !Array.isArray(components)) {
+    return components as Record<string, unknown>;
+  }
+  return undefined;
+}
+
+/**
+ * Deep structural equality with order-insensitive object keys (array order
+ * still matters — e.g. `required` lists are order-preserving in serialized
+ * specs but semantically it is safer to demand exact array equality).
+ */
+function deepEqualUnordered(a: unknown, b: unknown): boolean {
+  if (a === b) return true;
+  if (Array.isArray(a) || Array.isArray(b)) {
+    if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length) return false;
+    return a.every((item, i) => deepEqualUnordered(item, b[i]));
+  }
+  if (a && b && typeof a === 'object' && typeof b === 'object') {
+    const aObj = a as Record<string, unknown>;
+    const bObj = b as Record<string, unknown>;
+    const aKeys = Object.keys(aObj);
+    if (aKeys.length !== Object.keys(bObj).length) return false;
+    return aKeys.every(
+      (key) => Object.hasOwn(bObj, key) && deepEqualUnordered(aObj[key], bObj[key])
+    );
+  }
+  return false;
+}
+
 /**
  * Sanitize an OpenAPI spec before importing into APIM.
  * Currently handles:

src/services/resource-publisher.ts

@@ -429,6 +429,7 @@ export async function publishResource(
         descriptor.workspace,
         config.envMapping
       );
+      json = normalizeSubscriptionOwnerId(json);
     }
 
     // ApiRelease: normalize properties.apiId from source ARM path to target ARM path.
@@ -1158,6 +1159,37 @@ function normalizeSubscriptionScope(
   return json;
 }
 
+/**
+ * Normalise the `properties.ownerId` field of a Subscription resource.
+ *
+ * APIM returns ownerId as a full ARM resource path on GET, e.g.:
+ *   /subscriptions/{sub}/resourceGroups/{rg}/providers/Microsoft.ApiManagement/service/{svc}/users/1
+ *
+ * The PUT endpoint requires a relative URL in the format `/users/{userId}`,
+ * so a subscription extracted from one instance would otherwise carry the
+ * source instance's service path. Strip the service ARM prefix like
+ * normalizeSubscriptionScope does for scope. Unlike scope, envMapping
+ * affixes must NOT be applied — a user id is not an affixed resource name.
+ * Already-relative values are left untouched.
+ */
+function normalizeSubscriptionOwnerId(
+  json: Record<string, unknown>
+): Record<string, unknown> {
+  const props = json.properties as Record<string, unknown> | undefined;
+  const ownerId = props?.ownerId;
+  if (typeof ownerId !== 'string') return json;
+
+  const serviceOwnerMatch = ownerId.match(
+    /^\/subscriptions\/[^/]+\/resourceGroups\/[^/]+\/providers\/Microsoft\.ApiManagement\/service\/[^/]+(\/users\/[^/]+)$/i
+  );
+  if (!serviceOwnerMatch?.[1]) return json;
+
+  return {
+    ...json,
+    properties: { ...props, ownerId: serviceOwnerMatch[1] },
+  };
+}
+
 export function applyApiPathPrefix(
   json: Record<string, unknown>,
   descriptor: ResourceDescriptor,

tests/unit/clients/apim-client.test.ts

@@ -9,6 +9,7 @@ import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
 import { ApimClient, HttpError } from '../../../src/clients/apim-client.js';
 import { ResourceType } from '../../../src/models/resource-types.js';
 import { ApimServiceContext } from '../../../src/models/types.js';
+import { buildArmBaseUrl } from '../../../src/lib/cloud-config.js';
 
 const testContext: ApimServiceContext = {
   subscriptionId: 'sub-1',
@@ -31,6 +32,45 @@ function makeResponse(
   });
 }
 
+describe('ApimClient.validatePreFlight', () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+    vi.unstubAllGlobals();
+  });
+
+  it.each([
+    ['public', 'https://management.azure.com'],
+    ['usgov', 'https://management.usgovcloudapi.net'],
+    ['china', 'https://management.chinacloudapi.cn'],
+    ['germany', 'https://management.microsoftazure.de'],
+  ])('should use the %s endpoint for both pre-flight checks', async (cloud, endpoint) => {
+    const client = new ApimClient();
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    vi.spyOn(client as any, 'getToken').mockResolvedValue('fake-token');
+    const fetchSpy = vi.fn().mockImplementation(() => Promise.resolve(makeResponse(200, {})));
+    vi.stubGlobal('fetch', fetchSpy);
+    const context: ApimServiceContext = {
+      ...testContext,
+      resourceGroup: 'rg with spaces',
+      baseUrl: buildArmBaseUrl(cloud, testContext.subscriptionId, 'rg with spaces', testContext.serviceName),
+    };
+
+    await client.validatePreFlight(context);
+
+    expect(fetchSpy).toHaveBeenCalledTimes(2);
+    expect(fetchSpy).toHaveBeenNthCalledWith(
+      1,
+      `${endpoint}/subscriptions/sub-1/resourceGroups/rg%20with%20spaces?api-version=2021-04-01`,
+      expect.objectContaining({ method: 'GET' }),
+    );
+    expect(fetchSpy).toHaveBeenNthCalledWith(
+      2,
+      `${context.baseUrl}?api-version=${context.apiVersion}`,
+      expect.objectContaining({ method: 'GET' }),
+    );
+  });
+});
+
 describe('ApimClient.listResources', () => {
   let client: ApimClient;
   let fetchSpy: ReturnType<typeof vi.fn>;

tests/unit/lib/auto-generated.test.ts

@@ -1,7 +1,7 @@
 // Copyright (c) Microsoft Corporation.
 // Licensed under the MIT license.
 import { describe, it, expect } from 'vitest';
-import { isAutoGeneratedId } from '../../../src/lib/auto-generated.js';
+import { isAutoGeneratedId, isPortalGeneratedSchemaId } from '../../../src/lib/auto-generated.js';
 
 describe('auto-generated', () => {
   describe('isAutoGeneratedId', () => {
@@ -12,6 +12,13 @@ describe('auto-generated', () => {
       expect(isAutoGeneratedId('ffffffffffffffffffffffff')).toBe(true);
     });
 
+    it('should NOT match 13-digit portal schema IDs (handled by isPortalGeneratedSchemaId)', () => {
+      // 13-digit is a weaker heuristic; it must not gate named values,
+      // subscriptions, or operations that share this predicate.
+      expect(isAutoGeneratedId('1786466527403')).toBe(false);
+      expect(isAutoGeneratedId('1700000000000')).toBe(false);
+    });
+
     it('should return false for human-readable schema names', () => {
       expect(isAutoGeneratedId('src-rest-schema-item')).toBe(false);
       expect(isAutoGeneratedId('my-schema')).toBe(false);
@@ -40,4 +47,24 @@ describe('auto-generated', () => {
       expect(isAutoGeneratedId('69f15c3c10a45d29d855583-')).toBe(false);
     });
   });
+
+  describe('isPortalGeneratedSchemaId', () => {
+    it('should return true for 13-digit epoch-millis IDs (portal-created schemas)', () => {
+      expect(isPortalGeneratedSchemaId('1786466527403')).toBe(true);
+      expect(isPortalGeneratedSchemaId('1789146226316')).toBe(true);
+    });
+
+    it('should return false for numeric IDs of other lengths', () => {
+      expect(isPortalGeneratedSchemaId('178646652740')).toBe(false); // 12 digits
+      expect(isPortalGeneratedSchemaId('17864665274031')).toBe(false); // 14 digits
+      expect(isPortalGeneratedSchemaId('1')).toBe(false);
+      expect(isPortalGeneratedSchemaId('')).toBe(false);
+    });
+
+    it('should return false for 24-hex and human-readable names', () => {
+      expect(isPortalGeneratedSchemaId('69f15c3c10a45d29d855583a')).toBe(false);
+      expect(isPortalGeneratedSchemaId('my-schema')).toBe(false);
+      expect(isPortalGeneratedSchemaId('1786466527403x')).toBe(false);
+    });
+  });
 });