@intentius/chant-lexicon-azure 0.41.20 → 0.44.1

package/src/lint/post-synth/azr032.ts

@@ -0,0 +1,60 @@
+/**
+ * AZR032: Policy Definition Assigned Nowhere (#793, epic #787 C3)
+ *
+ * Flags custom Microsoft.Authorization/policyDefinitions with no
+ * policyAssignments referencing them in the same template. The
+ * GovernanceBaseline composite always pairs definition and assignment; a
+ * definition alone is the leftover of a dropped guardrail assignment.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { parseArmTemplate } from "./arm-refs";
+
+/**
+ * True when a policyDefinitionId expression targets the definition name —
+ * either a quoted literal inside resourceId()/managementGroupResourceId()
+ * or the trailing segment of a literal resource id.
+ */
+function references(definitionName: string, policyDefinitionId: unknown): boolean {
+  if (typeof policyDefinitionId !== "string") return false;
+  return (
+    policyDefinitionId.includes(`'${definitionName}'`) ||
+    policyDefinitionId.endsWith(`/${definitionName}`) ||
+    policyDefinitionId === definitionName
+  );
+}
+
+export const azr032: PostSynthCheck = {
+  id: "AZR032",
+  description: "Custom policy definition assigned nowhere — a defined but unassigned guardrail enforces nothing",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const [_lexicon, output] of ctx.outputs) {
+      const template = parseArmTemplate(output);
+      if (!template?.resources) continue;
+
+      const assignmentIds = template.resources
+        .filter((r) => r.type === "Microsoft.Authorization/policyAssignments")
+        .map((r) => r.properties?.policyDefinitionId);
+
+      for (const resource of template.resources) {
+        if (resource.type !== "Microsoft.Authorization/policyDefinitions") continue;
+        if (typeof resource.name !== "string") continue;
+        const name = resource.name;
+        if (assignmentIds.some((id) => references(name, id))) continue;
+
+        diagnostics.push({
+          checkId: "AZR032",
+          severity: "error",
+          message: `Policy definition "${name}" is assigned nowhere in this template — pair it with a policy assignment or the guardrail enforces nothing`,
+          entity: name,
+          lexicon: "azure",
+        });
+      }
+    }
+
+    return diagnostics;
+  },
+};

package/src/lint/post-synth/azr033.test.ts

@@ -0,0 +1,49 @@
+import { describe, expect, test } from "vitest";
+import { createPostSynthContext } from "@intentius/chant-test-utils";
+import { azr033 } from "./azr033";
+
+function makeCtx(template: object) {
+  return createPostSynthContext({ azure: template });
+}
+
+const SCHEMA = "https://schema.management.azure.com/schemas/2019-08-01/tenantDeploymentTemplate.json#";
+
+function tenantPolicy(block: boolean) {
+  return {
+    $schema: SCHEMA,
+    contentVersion: "1.0.0.0",
+    resources: [
+      {
+        type: "Microsoft.Subscription/policies",
+        apiVersion: "2021-10-01",
+        name: "default",
+        properties: { blockSubscriptionsLeavingTenant: block },
+      },
+    ],
+  };
+}
+
+describe("AZR033: subscriptions may leave the tenant", () => {
+  test("flags blockSubscriptionsLeavingTenant: false", () => {
+    const diags = azr033.check(makeCtx(tenantPolicy(false)));
+    expect(diags).toHaveLength(1);
+    expect(diags[0].checkId).toBe("AZR033");
+    expect(diags[0].severity).toBe("error");
+    expect(diags[0].entity).toBe("default");
+  });
+
+  test("no diagnostic when the leave-block is on", () => {
+    expect(azr033.check(makeCtx(tenantPolicy(true)))).toHaveLength(0);
+  });
+
+  test("ignores other resource types", () => {
+    const ctx = makeCtx({
+      $schema: SCHEMA,
+      contentVersion: "1.0.0.0",
+      resources: [
+        { type: "Microsoft.Management/managementGroups", apiVersion: "2023-04-01", name: "Security", properties: {} },
+      ],
+    });
+    expect(azr033.check(ctx)).toHaveLength(0);
+  });
+});

package/src/lint/post-synth/azr033.ts

@@ -0,0 +1,40 @@
+/**
+ * AZR033: Subscriptions May Leave the Tenant (#793, epic #787 C3)
+ *
+ * Flags a Microsoft.Subscription/policies resource that sets
+ * blockSubscriptionsLeavingTenant to false — the tenant-level leave-block
+ * the landing-zone foundation declares, explicitly weakened.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { parseArmTemplate } from "./arm-refs";
+
+export const azr033: PostSynthCheck = {
+  id: "AZR033",
+  description: "Tenant subscription policy does not block subscriptions from leaving",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const [_lexicon, output] of ctx.outputs) {
+      const template = parseArmTemplate(output);
+      if (!template?.resources) continue;
+
+      for (const resource of template.resources) {
+        if (resource.type !== "Microsoft.Subscription/policies") continue;
+        if (resource.properties?.blockSubscriptionsLeavingTenant !== false) continue;
+
+        const name = typeof resource.name === "string" ? resource.name : String(resource.name);
+        diagnostics.push({
+          checkId: "AZR033",
+          severity: "error",
+          message: `Subscription tenant policy "${name}" sets blockSubscriptionsLeavingTenant: false — subscriptions can be moved out of the tenant`,
+          entity: name,
+          lexicon: "azure",
+        });
+      }
+    }
+
+    return diagnostics;
+  },
+};

package/src/lint/post-synth/index.ts

@@ -20,6 +20,10 @@ import { azr026 } from "./azr026";
 import { azr027 } from "./azr027";
 import { azr028 } from "./azr028";
 import { azr029 } from "./azr029";
+import { azr030 } from "./azr030";
+import { azr031 } from "./azr031";
+import { azr032 } from "./azr032";
+import { azr033 } from "./azr033";
 
 export const postSynthChecks: PostSynthCheck[] = [
   azr010,
@@ -42,4 +46,8 @@ export const postSynthChecks: PostSynthCheck[] = [
   azr027,
   azr028,
   azr029,
+  azr030,
+  azr031,
+  azr032,
+  azr033,
 ];

package/src/op/activities/az-apply.ts

@@ -388,7 +388,7 @@ export async function azApply(
  * Kubernetes label, while `gcpApply` writes GCP REST labels, where it is not.
  * Two surfaces, two key vocabularies. Azure has one surface.)
  */
-const LEGACY_OWNERSHIP_TAG_KEY = "managed-by";
+export const LEGACY_OWNERSHIP_TAG_KEY = "managed-by";
 
 /**
  * The ownership tags azApply stamps on every resource it applies.

package/src/package-cli.ts

@@ -5,7 +5,7 @@
  */
 import { generate, writeGeneratedFiles } from "./codegen/generate";
 import { packageLexicon } from "./codegen/package";
-import { writeFileSync, mkdirSync } from "fs";
+import { writeBundleSpec } from "@intentius/chant/codegen/package";
 import { join, dirname } from "path";
 import { fileURLToPath } from "url";
 
@@ -20,24 +20,7 @@ console.error(`Generated ${genResult.resources} resources, ${genResult.propertie
 const { spec, stats } = await packageLexicon({ verbose: true });
 
 const distDir = join(pkgDir, "dist");
-mkdirSync(join(distDir, "types"), { recursive: true });
-mkdirSync(join(distDir, "rules"), { recursive: true });
-mkdirSync(join(distDir, "skills"), { recursive: true });
-
-writeFileSync(join(distDir, "manifest.json"), JSON.stringify(spec.manifest, null, 2));
-writeFileSync(join(distDir, "meta.json"), spec.registry);
-writeFileSync(join(distDir, "types", "index.d.ts"), spec.typesDTS);
-
-for (const [name, content] of spec.rules) {
-  writeFileSync(join(distDir, "rules", name), content);
-}
-for (const [name, content] of spec.skills) {
-  writeFileSync(join(distDir, "skills", name), content);
-}
-
-if (spec.integrity) {
-  writeFileSync(join(distDir, "integrity.json"), JSON.stringify(spec.integrity, null, 2));
-}
+writeBundleSpec(spec, distDir);
 
 console.error(`Packaged ${stats.resources} resources, ${stats.ruleCount} rules, ${stats.skillCount} skills`);
 console.error(`dist/ written to ${distDir}`);

package/src/serializer.test.ts

@@ -1,5 +1,6 @@
 import { describe, it, expect } from "vitest";
 import { azureSerializer } from "./serializer";
+import { deploymentScope } from "./deploy-scopes";
 import { DECLARABLE_MARKER } from "@intentius/chant/declarable";
 
 function makeEntity(entityType: string, props: Record<string, unknown> = {}): any {
@@ -200,4 +201,95 @@ describe("azureSerializer", () => {
     expect(resource.type).toBe("Microsoft.Network/applicationGateways");
     expect(resource.sku).toEqual({ name: "WAF_v2", tier: "WAF_v2", capacity: 2 });
   });
+
+  // --- Deployment scope (#1545) ---
+  // These read deployScopes from the generated lexicon (built by
+  // `just _ensure-gen` before tests run).
+
+  it("emits a tenant-scope template for management groups, with no location default", () => {
+    const entities = new Map<string, any>();
+    entities.set("platformMg", makeEntity("Microsoft.Management/managementGroups", {
+      name: "platform",
+      displayName: "Platform",
+    }));
+
+    const result = azureSerializer.serialize(entities);
+    const template = JSON.parse(result as string);
+
+    expect(template.$schema).toContain("tenantDeploymentTemplate");
+    const resource = template.resources[0];
+    expect(resource.type).toBe("Microsoft.Management/managementGroups");
+    // Tenant scope has no resource group to read a location from
+    expect(resource.location).toBeUndefined();
+  });
+
+  it("emits a subscription-scope template for policy definitions", () => {
+    const entities = new Map<string, any>();
+    entities.set("denyPublicIp", makeEntity("Microsoft.Authorization/policyDefinitions", {
+      name: "deny-public-ip",
+      policyType: "Custom",
+      policyRule: { if: { field: "type", equals: "Microsoft.Network/publicIPAddresses" }, then: { effect: "deny" } },
+    }));
+
+    const result = azureSerializer.serialize(entities);
+    const template = JSON.parse(result as string);
+
+    expect(template.$schema).toContain("subscriptionDeploymentTemplate");
+    const resource = template.resources[0];
+    expect(resource.location).toBeUndefined();
+    expect(resource.properties?.policyRule).toBeDefined();
+  });
+
+  it("keeps resource-group scope for policy assignments beside plain resources", () => {
+    const entities = new Map<string, any>();
+    entities.set("myVnet", makeEntity("Microsoft.Network/virtualNetworks", {
+      name: "testvnet",
+    }));
+    entities.set("enforceTags", makeEntity("Microsoft.Authorization/policyAssignments", {
+      name: "enforce-tags",
+    }));
+
+    const result = azureSerializer.serialize(entities);
+    const template = JSON.parse(result as string);
+
+    // policyAssignments deploy at every scope, so resource group wins
+    expect(template.$schema).toContain("/deploymentTemplate.json");
+    const vnet = template.resources.find((r: any) => r.type === "Microsoft.Network/virtualNetworks");
+    expect(vnet.location).toBe("[resourceGroup().location]");
+  });
+
+  it("deploymentScope() pins the template scope over the inferred one", () => {
+    const entities = new Map<string, any>();
+    entities.set("scope", deploymentScope("managementGroup"));
+    entities.set("denyClassic", makeEntity("Microsoft.Authorization/policyDefinitions", {
+      name: "deny-classic-resources",
+      policyType: "Custom",
+      policyRule: { if: { field: "type", like: "Microsoft.Classic*" }, then: { effect: "deny" } },
+    }));
+
+    const result = azureSerializer.serialize(entities);
+    const template = JSON.parse(result as string);
+
+    // Inference alone would pick subscription (the scope closest to a
+    // resource group that policy definitions support)
+    expect(template.$schema).toContain("managementGroupDeploymentTemplate");
+    expect(template.resources).toHaveLength(1);
+    expect(template.resources[0].location).toBeUndefined();
+  });
+
+  it("falls back to resource-group scope when resources share no scope", () => {
+    const entities = new Map<string, any>();
+    entities.set("platformMg", makeEntity("Microsoft.Management/managementGroups", {
+      name: "platform",
+    }));
+    entities.set("myVnet", makeEntity("Microsoft.Network/virtualNetworks", {
+      name: "testvnet",
+    }));
+
+    const result = azureSerializer.serialize(entities);
+    const template = JSON.parse(result as string);
+
+    // No single scope fits both — AZR030 flags the management group
+    expect(template.$schema).toContain("/deploymentTemplate.json");
+  });
 });

package/src/serializer.ts

@@ -24,6 +24,7 @@ import { resolveDependsOn } from "@intentius/chant/resource-attributes";
 import { isDefaultTags, type TagEntry } from "./default-tags";
 import { loadTaggableResources } from "./taggable";
 import { findArmResourceRefs } from "./lint/post-synth/arm-refs";
+import { isDeploymentScope, resolveTemplateScope, TEMPLATE_SCHEMAS, type DeployScope } from "./deploy-scopes";
 
 /** Check if a declarable is a CoreParameter */
 function isCoreParameter(entity: Declarable): entity is CoreParameter {
@@ -177,8 +178,32 @@ function serializeToTemplate(
   outputs?: LexiconOutput[],
   ownership?: OwnershipMarker,
 ): ArmTemplate {
+  // Resolve the deployment scope from the resource types being emitted
+  // (#1545): a template of tenant-only resources (management groups, policy
+  // definitions at management-group scope, ...) must carry the matching
+  // $schema and must not lean on resourceGroup() expressions. Mixed sets
+  // with no common scope fall back to resource-group scope and AZR030
+  // reports the resources that cannot deploy there. A deploymentScope()
+  // pin overrides the inference — policy definitions and assignments
+  // deploy at several scopes, so a management-group guardrail project
+  // cannot be told from a subscription one by its resource set alone
+  // (#791); AZR030 still flags resources the pinned scope cannot hold.
+  let pinnedScope: DeployScope | undefined;
+  const emittedTypes: string[] = [];
+  for (const [, entity] of entities) {
+    if (isStackOutput(entity) || isDefaultTags(entity) || isCoreParameter(entity)) continue;
+    if (isDeploymentScope(entity)) {
+      pinnedScope ??= entity.scope;
+    } else if (isChildProject(entity)) {
+      emittedTypes.push("Microsoft.Resources/deployments");
+    } else if (!isPropertyDeclarable(entity)) {
+      emittedTypes.push(entity.entityType);
+    }
+  }
+  const templateScope = pinnedScope ?? resolveTemplateScope(emittedTypes);
+
   const template: ArmTemplate = {
-    $schema: "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
+    $schema: TEMPLATE_SCHEMAS[templateScope],
     contentVersion: "1.0.0.0",
     resources: [],
   };
@@ -206,7 +231,7 @@ function serializeToTemplate(
   // Process entities
   for (const [name, entity] of entities) {
     // Skip non-resource types
-    if (isStackOutput(entity) || isDefaultTags(entity)) continue;
+    if (isStackOutput(entity) || isDefaultTags(entity) || isDeploymentScope(entity)) continue;
 
     if (isCoreParameter(entity)) {
       if (!template.parameters) template.parameters = {};
@@ -278,8 +303,11 @@ function serializeToTemplate(
         }
       }
 
-      // Default location to resource group location if not specified
-      if (!resource.location) {
+      // Default location to resource group location if not specified.
+      // Above resource-group scope there is no resource group to read a
+      // location from, and the scoped resources (management groups, policy
+      // definitions, ...) have no location field at all (#1545).
+      if (!resource.location && templateScope === "resourceGroup") {
         resource.location = "[resourceGroup().location]";
       }
 

package/src/spec/api-versions.test.ts

@@ -47,8 +47,8 @@ describe("latestVersionPerProvider", () => {
       "schemas/2023-01-01/Microsoft.Network.json",
     ];
     const result = latestVersionPerProvider(paths);
-    expect(result.get("Microsoft.Storage")?.apiVersion).toBe("2023-06-01");
-    expect(result.get("Microsoft.Network")?.apiVersion).toBe("2023-01-01");
+    expect(result.get("Microsoft.Storage")?.map((f) => f.apiVersion)).toEqual(["2023-06-01"]);
+    expect(result.get("Microsoft.Network")?.map((f) => f.apiVersion)).toEqual(["2023-01-01"]);
   });
 });
 
@@ -62,6 +62,35 @@ describe("PROVIDER_VERSION_OVERRIDES", () => {
     const result = latestVersionPerProvider(paths);
     // 2026-03-02 is the naive "latest by date" but drops virtualMachines
     // (a disk-only delta); the override keeps 2026-03-01 instead.
-    expect(result.get("Microsoft.Compute")?.apiVersion).toBe("2026-03-01");
+    expect(result.get("Microsoft.Compute")?.map((f) => f.apiVersion)).toEqual(["2026-03-01"]);
+  });
+
+  it("keeps every pinned Microsoft.Authorization file, in pin order (#1545)", () => {
+    // Shuffled on purpose — the result must follow the pin order (roles
+    // first, then the policy file, then policyExemptions), not path order.
+    const paths = [
+      "schemas/2026-06-01/Microsoft.Authorization.json",
+      "schemas/2022-07-01-preview/Microsoft.Authorization.json",
+      "schemas/2025-01-01/Microsoft.Authorization.json",
+      "schemas/2022-04-01/Microsoft.Authorization.json",
+    ];
+    const result = latestVersionPerProvider(paths);
+    expect(result.get("Microsoft.Authorization")?.map((f) => f.apiVersion)).toEqual([
+      "2022-04-01",
+      "2026-06-01",
+      "2022-07-01-preview",
+    ]);
+  });
+
+  it("pins Microsoft.Management and Microsoft.Subscription to their latest GA dates (#1545)", () => {
+    const paths = [
+      "schemas/2023-04-01/Microsoft.Management.json",
+      "schemas/2024-02-01-preview/Microsoft.Management.json",
+      "schemas/2021-10-01/Microsoft.Subscription.json",
+      "schemas/2025-11-01-preview/Microsoft.Subscription.json",
+    ];
+    const result = latestVersionPerProvider(paths);
+    expect(result.get("Microsoft.Management")?.map((f) => f.apiVersion)).toEqual(["2023-04-01"]);
+    expect(result.get("Microsoft.Subscription")?.map((f) => f.apiVersion)).toEqual(["2021-10-01"]);
   });
 });

package/src/spec/api-versions.ts

@@ -64,23 +64,44 @@ export function parseSchemaPath(
  * (validate.ts's REQUIRED_NAMES and composites/vm-linux.ts depend on it);
  * it drops the disk-only resources (disks, diskAccesses, diskEncryptionSets,
  * snapshots), which nothing here currently references.
+ *
+ * A pin can list several versions (#1545): Azure publishes some providers as
+ * per-family deltas, so no single date carries every resource we need. The
+ * files merge in the order listed — the first file that defines a resource
+ * name wins, later files only contribute resources not yet seen.
+ * Microsoft.Authorization needs three: 2022-04-01 for roleAssignments /
+ * roleDefinitions (#223), 2026-06-01 (latest stable policy file) for
+ * policyAssignments / policyDefinitions / policySetDefinitions and their
+ * _versions children, and 2022-07-01-preview for policyExemptions, which has
+ * no GA date and whose newer preview files (2024-12-01-preview and later)
+ * drag in policy variables we don't want yet.
+ *
+ * Microsoft.Management and Microsoft.Subscription are pinned to their latest
+ * GA dates: the naive latest for both is a preview (2024-02-01-preview adds
+ * serviceGroups; 2025-11-01-preview adds changeTenantRequest), and the
+ * management-group hierarchy should not author against preview apiVersions.
  */
-export const PROVIDER_VERSION_OVERRIDES: Record<string, string> = {
-  "Microsoft.Authorization": "2022-04-01",
-  "Microsoft.Compute": "2026-03-01",
+export const PROVIDER_VERSION_OVERRIDES: Record<string, readonly string[]> = {
+  "Microsoft.Authorization": ["2022-04-01", "2026-06-01", "2022-07-01-preview"],
+  "Microsoft.Compute": ["2026-03-01"],
+  "Microsoft.Management": ["2023-04-01"],
+  "Microsoft.Subscription": ["2021-10-01"],
 };
 
 /**
- * Given a set of schema paths, return only the latest API version per provider,
- * with {@link PROVIDER_VERSION_OVERRIDES} pinning specific providers to a chosen
- * version (used where "latest" drops resources we depend on).
+ * Given a set of schema paths, return the schema files to generate from, per
+ * provider: the single latest API version, unless
+ * {@link PROVIDER_VERSION_OVERRIDES} pins the provider to one or more chosen
+ * versions (used where "latest" drops resources we depend on). For pinned
+ * providers the array preserves the pin order — callers merge the files
+ * first-wins per resource name.
  *
- * Returns a Map of provider → { path, apiVersion }.
+ * Returns a Map of provider → [{ path, apiVersion }, ...].
  */
 export function latestVersionPerProvider(
   paths: string[],
-): Map<string, { path: string; apiVersion: string }> {
-  const best = new Map<string, { path: string; apiVersion: string }>();
+): Map<string, Array<{ path: string; apiVersion: string }>> {
+  const best = new Map<string, Array<{ path: string; apiVersion: string }>>();
 
   for (const p of paths) {
     const parsed = parseSchemaPath(p);
@@ -88,16 +109,20 @@ export function latestVersionPerProvider(
 
     const pinned = PROVIDER_VERSION_OVERRIDES[parsed.provider];
     if (pinned) {
-      // Only accept the pinned version for an overridden provider.
-      if (parsed.apiVersion === pinned) {
-        best.set(parsed.provider, { path: p, apiVersion: parsed.apiVersion });
+      // Only accept the pinned versions for an overridden provider,
+      // slotted into pin order.
+      if (pinned.includes(parsed.apiVersion)) {
+        const files = best.get(parsed.provider) ?? [];
+        files.push({ path: p, apiVersion: parsed.apiVersion });
+        files.sort((a, b) => pinned.indexOf(a.apiVersion) - pinned.indexOf(b.apiVersion));
+        best.set(parsed.provider, files);
       }
       continue;
     }
 
     const existing = best.get(parsed.provider);
-    if (!existing || compareApiDates(parsed.apiVersion, existing.apiVersion) > 0) {
-      best.set(parsed.provider, { path: p, apiVersion: parsed.apiVersion });
+    if (!existing || compareApiDates(parsed.apiVersion, existing[0].apiVersion) > 0) {
+      best.set(parsed.provider, [{ path: p, apiVersion: parsed.apiVersion }]);
     }
   }
 

package/src/spec/fetch.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect } from "vitest";
-import { getCachePath } from "./fetch";
+import { getCachePath, explodeProviderSchema, type ArmProviderSchema } from "./fetch";
 
 describe("fetchArmSchemas", () => {
   it("returns a valid cache path", () => {
@@ -8,3 +8,81 @@ describe("fetchArmSchemas", () => {
     expect(path).toContain("azure-resource-manager-schemas");
   });
 });
+
+function parseEntry(out: Map<string, Buffer>, resourceType: string) {
+  const buf = out.get(resourceType);
+  expect(buf).toBeTruthy();
+  return JSON.parse(buf!.toString("utf-8"));
+}
+
+describe("explodeProviderSchema (#1545)", () => {
+  it("reads only resourceDefinitions for a non-allowlisted provider", () => {
+    const schema: ArmProviderSchema = {
+      resourceDefinitions: { storageAccounts: { type: "object" } },
+      subscription_resourceDefinitions: { subscriptionOnly: { type: "object" } },
+      definitions: {},
+    };
+    const out = new Map<string, Buffer>();
+    explodeProviderSchema("Microsoft.Storage", "2023-06-01", schema, out);
+
+    expect([...out.keys()]).toEqual(["Microsoft.Storage/storageAccounts"]);
+    const entry = parseEntry(out, "Microsoft.Storage/storageAccounts");
+    expect(entry.deployScopes).toEqual(["resourceGroup"]);
+    expect(entry.apiVersion).toBe("2023-06-01");
+  });
+
+  it("reads scope sections for allowlisted providers and unions scopes", () => {
+    const schema: ArmProviderSchema = {
+      resourceDefinitions: { policyAssignments: { type: "object" } },
+      subscription_resourceDefinitions: {
+        policyAssignments: { type: "object" },
+        policyDefinitions: { type: "object" },
+      },
+      managementGroup_resourceDefinitions: { policyDefinitions: { type: "object" } },
+      tenant_resourceDefinitions: { policyAssignments: { type: "object" } },
+      definitions: {},
+    };
+    const out = new Map<string, Buffer>();
+    explodeProviderSchema("Microsoft.Authorization", "2026-06-01", schema, out);
+
+    const assignments = parseEntry(out, "Microsoft.Authorization/policyAssignments");
+    expect(assignments.deployScopes).toEqual(["resourceGroup", "subscription", "tenant"]);
+    const definitions = parseEntry(out, "Microsoft.Authorization/policyDefinitions");
+    expect(definitions.deployScopes).toEqual(["subscription", "managementGroup"]);
+  });
+
+  it("reads tenant-only resources like management groups", () => {
+    const schema: ArmProviderSchema = {
+      tenant_resourceDefinitions: {
+        managementGroups: { type: "object" },
+        managementGroups_subscriptions: { type: "object" },
+      },
+      definitions: {},
+    };
+    const out = new Map<string, Buffer>();
+    explodeProviderSchema("Microsoft.Management", "2023-04-01", schema, out);
+
+    const mg = parseEntry(out, "Microsoft.Management/managementGroups");
+    expect(mg.deployScopes).toEqual(["tenant"]);
+    expect(out.has("Microsoft.Management/managementGroups_subscriptions")).toBe(true);
+  });
+
+  it("keeps the first definition of a resource across a multi-version pin", () => {
+    const out = new Map<string, Buffer>();
+    explodeProviderSchema("Microsoft.Authorization", "2022-04-01", {
+      resourceDefinitions: { roleAssignments: { description: "roles file" } },
+      definitions: {},
+    }, out);
+    explodeProviderSchema("Microsoft.Authorization", "2026-06-01", {
+      resourceDefinitions: { roleAssignments: { description: "policy file" }, policyAssignments: {} },
+      definitions: {},
+    }, out);
+
+    const roles = parseEntry(out, "Microsoft.Authorization/roleAssignments");
+    expect(roles.apiVersion).toBe("2022-04-01");
+    expect(roles.resourceDefinition.description).toBe("roles file");
+    // The later file still contributes resources the first one lacked
+    const policy = parseEntry(out, "Microsoft.Authorization/policyAssignments");
+    expect(policy.apiVersion).toBe("2026-06-01");
+  });
+});