[Copilot]

Adds apiops compare — a new subcommand that compares two APIM instances via the ARM REST API and reports resource-level differences. Designed for deployment verification and environment drift investigation.

Normalization logic is ported from tests/integration/all-resource-types/Compare-ApimInstance.ps1.

New modules

• src/lib/compare-normalizer.ts — Strips ARM envelope fields, read-only/timestamp properties, and replaces instance-specific values with stable placeholders before comparison:

  • Subscription IDs, resource groups, service names → {{sub}}, {{rg}}, {{apim-name}}
  • Key Vault URIs, App Insights/Event Hub resource names → placeholders
  • 24-char hex auto-generated IDs and GUIDs → {{auto-id}} / {{guid}}
  • Resources with auto-generated names keyed by sorted normalized content as {{auto-id-0}}, {{auto-id-1}}, … for stable cross-instance matching
  • APIM ARM paths derived from context.baseUrl (via getArmPathFromBaseUrl / splitAtProviders) — no hardcoded provider type strings

• src/lib/compare-differ.ts — Deep recursive JSON diff with dot-notation paths; skips .properties.value on secret named values and .properties.credentials on EventHub/AppInsights loggers. Each ResourceDiff carries an explicit status field (missing | extra | different) for structured output.

• src/services/compare-service.ts — Hierarchical orchestrator using the same dependency graph and resource-path libraries as extract and publish:

  • Top-level types derived from TIER_1_RESOURCES, TIER_2_RESOURCES, and non-child TIER_3_RESOURCES (via isChildType()) — same pattern as extract-service.ts
  • Child types per parent (API, Product, Gateway) derived from getDependencies() via getChildTypesOf() — new resource types added to the dependency graph are automatically included
  • Per-type options (exclusion lists, secret/credential skip flags) centralized in a TYPE_OPTIONS map
  • Built-in exclusions: echo-api, administrators/developers/guests, starter/unlimited, master

• src/cli/compare-command.ts — Commander subcommand with --format text|table|json output modes and plain-text (emoji-free) console output:

  • text (default): per-type summary with field-level diff details
  • table: ASCII table with Resource (by resource ID), Status (missing, extra, different, skipped), and Notes columns
  • json: same row structure as table, machine-readable

CLI interface

apiops compare \
  --source-subscription-id <id> \
  --source-resource-group <rg> --source-service-name <name> \
  --target-subscription-id <id> \
  --target-resource-group <rg> --target-service-name <name> \
  [--format text|table|json]

All six resource-identity flags are required. --source-subscription-id and --target-subscription-id are independent — use them when the instances are in different subscriptions or the same one.

Exit codes: 0 = identical, 1 = differences found, 2 = fatal error

Supporting changes

• src/cli/index.ts — --subscription-id removed from global options; it is now a per-command required option on extract and publish (with AZURE_SUBSCRIPTION_ID env var fallback)
• src/cli/extract-command.ts / src/cli/publish-command.ts — --subscription-id added as a mandatory per-command option
• src/models/config.ts — adds CompareConfig
• specs/contracts/cli-commands.md — updated global options table, extract/publish option tables, and compare command documentation
• specs/tasks.md — Phase 9 added with all compare tasks

[Elizabeth Maher (EMaher)]

These resource urls shouldn't have hardcode types. The code should use resource-types.ts model and resource-paths.ts and resource-url.ts in the lib,

[Copilot]

Fixed in c680d66. normalizeString now derives the APIM ARM path by calling getArmPathFromBaseUrl(context.baseUrl) — which extracts the path component from the already-constructed baseUrl (built by buildArmBaseUrl in cloud-config.ts). The subscription+RG prefix is then derived via splitAtProviders(). The hardcoded Microsoft.ApiManagement/service string is gone from the normalizer; the provider path comes from the context instead.

[Elizabeth Maher (EMaher)]

sourceSubscriptionId and targetSubscriptionId should only be used if the source and target apim resources are not in the same subscription. User should either specify subscriptionId or (sourceSubscriptionId and targetSubscriptionId). They are mutually exclusive.

[Copilot]

Fixed in a91ee14. The two subscription ID modes are now mutually exclusive:

• Same subscription: use --subscription-id <id> (global flag) or AZURE_SUBSCRIPTION_ID env var — applied to both source and target.
• Different subscriptions: use --source-subscription-id <id> and --target-subscription-id <id> together.

Mixing both groups exits with code 2, as does specifying only one of the per-side flags. The validation is extracted into a pure resolveSubscriptionIds() function covered by 9 unit tests. The spec doc has been updated with a usage table.

[Elizabeth Maher (EMaher)]

I don't like hard-coded things. Resource comparison should be using same libraries/models and dependency analysis as the extract and publish command.

[Copilot]

Fixed in a706159. compare-service.ts now derives all resource type groupings from the same libraries as extract and publish:

• Top-level types: [...TIER_1_RESOURCES, ...TIER_2_RESOURCES, ...TIER_3_RESOURCES.filter(t => !isChildType(t))] — mirrors the extract-service pattern
• Child types per parent: getChildTypesOf(parentType) uses getDependencies() from dependency-graph.ts — no explicit lists
• Per-type options (exclusions, skip flags): consolidated in a TYPE_OPTIONS map keyed by ResourceType

New resource types added to the dependency graph are automatically picked up without touching compare-service.ts. As a side effect, McpServer (which was missing from the old hardcoded list) is now correctly compared as an API child type.

[Elizabeth Maher (EMaher)]

Again, why is the type hard-coded. Isn't there lists of top level resource types already defined in another library?

[Copilot]

Fixed in a706159. The top-level type list is now [...TIER_1_RESOURCES, ...TIER_2_RESOURCES, ...TIER_3_RESOURCES.filter(t => !isChildType(t))] from dependency-graph.ts and resource-path.ts — the same approach extract-service.ts uses for its tier loops. Child type groups per parent (API, Product, Gateway) are derived from getDependencies() via a getChildTypesOf(parentType) helper, so no type-specific constants appear anywhere in the comparison logic.

[Elizabeth Maher (EMaher)]

Actually, I don't like that the subscription-id and source-subscription-id mean the same thing. It's confusing. Remove subscription-id as a global parameter. Only the extract and publish commands should have a subscription-id option. It should be required for both those commands

[Copilot]

Fixed in 6790702. --subscription-id has been removed from global options. It is now a per-command required option on extract and publish (accepting AZURE_SUBSCRIPTION_ID as an env var fallback via Commander's .env()). The compare command never accepted the global flag and now uses only --source-subscription-id and --target-subscription-id (both required).

[Elizabeth Maher (EMaher)]

make source subscription-id and target subscription-id required.

[Copilot]

Fixed in 6790702. Both --source-subscription-id and --target-subscription-id are now declared with requiredOption() on the compare command — Commander enforces them at parse time. The old resolveSubscriptionIds() helper and global subscription-id fallback logic have been removed.

[Elizabeth Maher (EMaher)]

Remove emojis from text output

[Copilot]

Fixed in 6790702. All emojis removed from compare text output — ✅ PASS, ❌ FAIL, ⚠️ SKIPPED, 💥 ERROR replaced with plain-text PASS, FAIL, SKIPPED, ERROR prefixes. The emoji-laden diff strings in compare-differ.ts were also cleaned up.

[Elizabeth Maher (EMaher)]

should also have optional output format option that can be text, table or json. Text calls outputText. Table output show table that is resource (by resource id), Status (missing, extra, different, skipped), Notes which includes any notes about why something was skipped. Json is same information as in table, but in json format.

[Copilot]

Fixed in 6790702. The compare command now has --format text|table|json:

• text (default) — existing per-type detailed output, no emojis
• table — ASCII table with three columns: Resource (label/name), Status (missing, extra, different, skipped), Notes (skip reason or first 3 diff paths)
• json — same row structure as table: { exitCode, summary, resources: [{ resource, status, notes }] }

The --format is a compare-level option with enforced choices; the global --format (text/json) continues to apply to extract and publish.