@intentius/chant-lexicon-azure 0.124.51 → 0.124.54

package/dist/integrity.json

@@ -1,7 +1,7 @@
 {
   "algorithm": "sha256",
   "artifacts": {
-    "manifest.json": "09473a32d53a4334e98360f7e3f23a4eac7508d0aced79fafb4e40cc5e7c5155",
+    "manifest.json": "cbd7212af4cd764e203bd8abb25b0ad3acaa1f99ad654ad55ceea486569ac10a",
     "meta.json": "d2521221ed616d882ded4296f0071685bd74e4b645d55dabc9685733c37dc419",
     "types/index.d.ts": "29631032bda9533849178968290e65d72250eab0b8bab424f2d9ef9b4e8546a4",
     "rules/hardcoded-location.ts": "0b895449c8c94066e81721c46be24249231029fe13b471477456df5c4e45b8bf",
@@ -37,5 +37,5 @@
     "skills/chant-azure-patterns.md": "2d8cb8bbeda73b695856cec4ddaf5b3a0efce76e4ee6e3cf14b90ca69dee5757",
     "skills/chant-azure-aks.md": "2d4e0098c1a22b54ffadd410564d9df0f3a04cb4eb7c6261f20ae33106e7aca8"
   },
-  "composite": "0c1e77d476de2c9346621d16e62a4f1264d19b6bf90bfef0fa413aefe5833f0b"
+  "composite": "35bb0b445290640e7c5eca09fb8e9d91dc7346604547adce69576d6ba9bc47d2"
 }

package/dist/listed-types.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Resource Graph's type names as azure lexicon kinds (#4521).
+ *
+ * behold#1029 lists Azure through Resource Graph, which lowercases every
+ * type and joins a child to its parent with `/`
+ * (`microsoft.network/virtualnetworks/subnets`). The lexicon's kinds come
+ * from the ARM schema ids, mixed case with `_` between a child and its parent
+ * (`Microsoft.Network/virtualNetworks_subnets`). So the mapping is a lookup:
+ * every kind, through {@link armType} and lowercased, is the listed type it
+ * answers to. ARM type names are case-insensitive, so no two kinds share one.
+ *
+ * A Resource Graph row has ARM's resource shape (`properties` beside
+ * `location`, `sku`, `identity`), and the deep reader flattens that shape
+ * before the hooks run (./deep-observe.ts `buildLiveProperties`), so an
+ * indexed row is flattened the same way.
+ */
+import type { ListedTypeMapping } from "@intentius/chant/lifecycle/type-listing";
+/** `Microsoft.Network/virtualNetworks_subnets` as Resource Graph spells it: `microsoft.network/virtualnetworks/subnets`. */
+export declare function azureListedTypeForKind(kind: string): string;
+/** Listed type to kind, over a set of kinds. */
+export declare function azureListedTypeIndex(kinds: Iterable<string>): Map<string, string>;
+/**
+ * The azure kind for a Resource Graph type, or undefined. Without a registry
+ * nothing maps: Resource Graph's lowercase spelling cannot be turned back
+ * into the kind's casing by rule.
+ */
+export declare function azureKindForListedType(listedType: string, index?: Map<string, string> | null): string | undefined;
+/** A Resource Graph row in the tree the deep reader compares. */
+export declare function azureObservedTree(properties: Record<string, unknown>): Record<string, unknown>;
+export declare const azureListedTypes: ListedTypeMapping;
+//# sourceMappingURL=listed-types.d.ts.map

package/dist/listed-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"listed-types.d.ts","sourceRoot":"","sources":["../src/listed-types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,yCAAyC,CAAC;AAKjF,4HAA4H;AAC5H,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE3D;AAED,gDAAgD;AAChD,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAIjF;AAeD;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,GAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAuB,GAAG,MAAM,GAAG,SAAS,CAEnI;AAED,iEAAiE;AACjE,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAE9F;AAED,eAAO,MAAM,gBAAgB,EAAE,iBAI9B,CAAC"}

package/dist/listed-types.js

@@ -0,0 +1,44 @@
+import { armType } from "./arm-type.js";
+import { buildLiveProperties } from "./deep-observe.js";
+import { loadApiVersions } from "./serializer.js";
+/** `Microsoft.Network/virtualNetworks_subnets` as Resource Graph spells it: `microsoft.network/virtualnetworks/subnets`. */
+export function azureListedTypeForKind(kind) {
+    return armType(kind).toLowerCase();
+}
+/** Listed type to kind, over a set of kinds. */
+export function azureListedTypeIndex(kinds) {
+    const out = new Map();
+    for (const kind of kinds)
+        out.set(azureListedTypeForKind(kind), kind);
+    return out;
+}
+let cachedIndex;
+/** Built from the generated registry, or null in a checkout that has not generated. */
+function generatedIndex() {
+    if (cachedIndex !== undefined)
+        return cachedIndex;
+    try {
+        cachedIndex = azureListedTypeIndex(loadApiVersions().keys());
+    }
+    catch {
+        cachedIndex = null;
+    }
+    return cachedIndex;
+}
+/**
+ * The azure kind for a Resource Graph type, or undefined. Without a registry
+ * nothing maps: Resource Graph's lowercase spelling cannot be turned back
+ * into the kind's casing by rule.
+ */
+export function azureKindForListedType(listedType, index = generatedIndex()) {
+    return index?.get(listedType.toLowerCase());
+}
+/** A Resource Graph row in the tree the deep reader compares. */
+export function azureObservedTree(properties) {
+    return buildLiveProperties(properties);
+}
+export const azureListedTypes = {
+    substrate: "azure",
+    kindFor: (listedType) => azureKindForListedType(listedType),
+    observedTree: (properties) => azureObservedTree(properties),
+};

package/dist/manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "azure",
-  "version": "0.124.51",
+  "version": "0.124.54",
   "chantVersion": ">=0.1.0",
   "namespace": "Azure",
   "intrinsics": [

package/dist/plugin.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAgB,MAAM,0BAA0B,CAAC;AA2B5E;;;;;GAKG;AACH,eAAO,MAAM,WAAW,EAAE,aAoezB,CAAC"}
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAgB,MAAM,0BAA0B,CAAC;AA6B5E;;;;;GAKG;AACH,eAAO,MAAM,WAAW,EAAE,aA2ezB,CAAC"}

package/dist/plugin.js

@@ -9,6 +9,8 @@ import { join, dirname } from "path";
 import { fileURLToPath } from "url";
 import { moduleSourceDir } from "@intentius/chant/module-source";
 import { azureSerializer } from "./serializer.js";
+import { azureListedTypes } from "./listed-types.js";
+import { azureReferenceCatalog } from "./reference-catalog.js";
 import { azureGraphEdges } from "./graph-edges.js";
 import { hardcodedLocationRule } from "./lint/rules/hardcoded-location.js";
 import { storageHttpsRule } from "./lint/rules/storage-https.js";
@@ -465,6 +467,11 @@ export const tags = defaultTags([
     },
     /** The noise rules the deep pass applies to both the live and declared trees. */
     deepNormalizationHooks: azureDeepNormalizationHooks,
+    // Cloud inventory type names to kinds, for an indexed resource (#4521).
+    listedTypes: azureListedTypes,
+    // How its resources reference each other, for chant's catalog pass over an
+    // index and a declared graph (#4535; behold#1005 retires behold's matcher on it).
+    referenceCatalog: azureReferenceCatalog,
     /** Runtime health (#4177): Container Apps. Implementation in ./health.ts. */
     healthTypes: ["Microsoft.App/containerApps"],
     async observeHealth(options) {

package/dist/reference-catalog.d.ts

@@ -0,0 +1,43 @@
+import type { ReferenceCatalog } from "@intentius/chant/graph-refs";
+/**
+ * Azure reference catalog (#4535): how Azure resources name each other, so
+ * chant's catalog pass (`reconstructIndexedEdges`, #4522) draws their edges
+ * over an index and over a declared graph, and behold can retire its name
+ * matcher (behold#1005).
+ *
+ * ## Shape
+ *
+ * The paths are the flattened ARM shape: `properties.*` beside `location`,
+ * `sku` and `identity`. That is the tree a Resource Graph row becomes
+ * (./listed-types.ts `azureObservedTree`), the tree the deep reader compares
+ * (./deep-observe.ts `buildLiveProperties`), and the shape the lexicon's
+ * declared props already have, so one rule reads all three. Sub-resources
+ * inside a row (`ipConfigurations[]`, `frontendIPConfigurations[]`) keep
+ * their own `properties` level, because ARM nests them that way.
+ *
+ * ## Values are ARM resource ids
+ *
+ * An Azure reference is a resource id. An indexed node is matched by its
+ * native id, which for Azure is the row's `id`, so the targets need no
+ * identity rule for it. The identities below are the other values a
+ * reference reads: a workspace's `customerId`, an app's FQDN.
+ *
+ * Over a declared graph the same paths usually hold ARM expressions
+ * (`[resourceId(...)]`), which match no node; the lexicon's `graphEdges`
+ * hook (./graph-edges.ts) already draws those references from the
+ * expressions themselves.
+ *
+ * ## What this does not do
+ *
+ * - Matching is exact. ARM compares ids case-insensitively, and a reference
+ *   can spell `resourceGroups` where the target's id spells
+ *   `resourcegroups`. Such a reference is dangling, never joined to the
+ *   wrong node.
+ * - `identity.userAssignedIdentities` names its identities in object keys,
+ *   which `readPath` cannot read. A Container App's identity edge comes from
+ *   `graphEdges` on a declared graph and from nothing over an index.
+ * - A subnet's parent VNet is in the subnet's own id. No attribute names it,
+ *   so there is no containment rule for it.
+ */
+export declare const azureReferenceCatalog: ReferenceCatalog;
+//# sourceMappingURL=reference-catalog.d.ts.map

package/dist/reference-catalog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reference-catalog.d.ts","sourceRoot":"","sources":["../src/reference-catalog.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AAEpE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,eAAO,MAAM,qBAAqB,EAAE,gBAyCnC,CAAC"}

package/dist/reference-catalog.js

@@ -0,0 +1,81 @@
+/**
+ * Azure reference catalog (#4535): how Azure resources name each other, so
+ * chant's catalog pass (`reconstructIndexedEdges`, #4522) draws their edges
+ * over an index and over a declared graph, and behold can retire its name
+ * matcher (behold#1005).
+ *
+ * ## Shape
+ *
+ * The paths are the flattened ARM shape: `properties.*` beside `location`,
+ * `sku` and `identity`. That is the tree a Resource Graph row becomes
+ * (./listed-types.ts `azureObservedTree`), the tree the deep reader compares
+ * (./deep-observe.ts `buildLiveProperties`), and the shape the lexicon's
+ * declared props already have, so one rule reads all three. Sub-resources
+ * inside a row (`ipConfigurations[]`, `frontendIPConfigurations[]`) keep
+ * their own `properties` level, because ARM nests them that way.
+ *
+ * ## Values are ARM resource ids
+ *
+ * An Azure reference is a resource id. An indexed node is matched by its
+ * native id, which for Azure is the row's `id`, so the targets need no
+ * identity rule for it. The identities below are the other values a
+ * reference reads: a workspace's `customerId`, an app's FQDN.
+ *
+ * Over a declared graph the same paths usually hold ARM expressions
+ * (`[resourceId(...)]`), which match no node; the lexicon's `graphEdges`
+ * hook (./graph-edges.ts) already draws those references from the
+ * expressions themselves.
+ *
+ * ## What this does not do
+ *
+ * - Matching is exact. ARM compares ids case-insensitively, and a reference
+ *   can spell `resourceGroups` where the target's id spells
+ *   `resourcegroups`. Such a reference is dangling, never joined to the
+ *   wrong node.
+ * - `identity.userAssignedIdentities` names its identities in object keys,
+ *   which `readPath` cannot read. A Container App's identity edge comes from
+ *   `graphEdges` on a declared graph and from nothing over an index.
+ * - A subnet's parent VNet is in the subnet's own id. No attribute names it,
+ *   so there is no containment rule for it.
+ */
+export const azureReferenceCatalog = {
+    identities: [
+        { kind: "Microsoft.OperationalInsights/workspaces", ids: ["customerId"] },
+        { kind: "Microsoft.App/containerApps", ids: ["configuration.ingress.fqdn", "latestRevisionFqdn"] },
+        { kind: "Microsoft.App/managedEnvironments", ids: ["defaultDomain", "staticIp"] },
+        { kind: "Microsoft.Network/publicIPAddresses", ids: ["ipAddress", "dnsSettings.fqdn"] },
+        { kind: "Microsoft.Web/sites", ids: ["defaultHostName"] },
+    ],
+    refs: [
+        // ── containment (→ boundary boxes) ──
+        { from: "Microsoft.App/managedEnvironments", path: "vnetConfiguration.infrastructureSubnetId", targetKind: "Microsoft.Network/virtualNetworks_subnets", relation: "containment", label: "in subnet" },
+        { from: "Microsoft.App/containerApps", path: "managedEnvironmentId", targetKind: "Microsoft.App/managedEnvironments", relation: "containment", label: "in environment" },
+        // The newer API versions write the same id under this name too.
+        { from: "Microsoft.App/containerApps", path: "environmentId", targetKind: "Microsoft.App/managedEnvironments", relation: "containment", label: "in environment" },
+        { from: "Microsoft.Network/networkInterfaces", path: "ipConfigurations[].properties.subnet.id", targetKind: "Microsoft.Network/virtualNetworks_subnets", relation: "containment", label: "in subnet" },
+        { from: "Microsoft.Network/privateEndpoints", path: "subnet.id", targetKind: "Microsoft.Network/virtualNetworks_subnets", relation: "containment", label: "in subnet" },
+        { from: "Microsoft.ContainerService/managedClusters", path: "agentPoolProfiles[].vnetSubnetID", targetKind: "Microsoft.Network/virtualNetworks_subnets", relation: "containment", label: "in subnet" },
+        { from: "Microsoft.Web/sites", path: "virtualNetworkSubnetId", targetKind: "Microsoft.Network/virtualNetworks_subnets", relation: "containment", label: "in subnet" },
+        { from: "Microsoft.ContainerInstance/containerGroups", path: "subnetIds[].id", targetKind: "Microsoft.Network/virtualNetworks_subnets", relation: "containment", label: "in subnet" },
+        { from: "Microsoft.Network/applicationGateways", path: "gatewayIPConfigurations[].properties.subnet.id", targetKind: "Microsoft.Network/virtualNetworks_subnets", relation: "containment", label: "in subnet" },
+        { from: "Microsoft.Network/loadBalancers", path: "frontendIPConfigurations[].properties.subnet.id", targetKind: "Microsoft.Network/virtualNetworks_subnets", relation: "containment", label: "in subnet" },
+        // ── references (→ edges) ──
+        // A managed environment names its workspace by the workspace's customer
+        // id, not its resource id.
+        { from: "Microsoft.App/managedEnvironments", path: "appLogsConfiguration.logAnalyticsConfiguration.customerId", targetKind: "Microsoft.OperationalInsights/workspaces", relation: "reference", label: "logs to" },
+        { from: "Microsoft.App/containerApps", path: "configuration.registries[].identity", targetKind: "Microsoft.ManagedIdentity/userAssignedIdentities", relation: "reference", label: "pulls as", optional: true },
+        { from: "Microsoft.Network/virtualNetworks_subnets", path: "networkSecurityGroup.id", targetKind: "Microsoft.Network/networkSecurityGroups", relation: "reference", label: "nsg" },
+        { from: "Microsoft.Network/virtualNetworks_subnets", path: "routeTable.id", targetKind: "Microsoft.Network/routeTables", relation: "reference", label: "routes" },
+        { from: "Microsoft.Network/virtualNetworks_subnets", path: "natGateway.id", targetKind: "Microsoft.Network/natGateways", relation: "reference", label: "egress via" },
+        // A VNet row from Resource Graph carries its subnets inline.
+        { from: "Microsoft.Network/virtualNetworks", path: "subnets[].properties.networkSecurityGroup.id", targetKind: "Microsoft.Network/networkSecurityGroups", relation: "reference", label: "nsg" },
+        { from: "Microsoft.Network/virtualNetworks", path: "subnets[].properties.routeTable.id", targetKind: "Microsoft.Network/routeTables", relation: "reference", label: "routes" },
+        { from: "Microsoft.Network/networkInterfaces", path: "networkSecurityGroup.id", targetKind: "Microsoft.Network/networkSecurityGroups", relation: "reference", label: "nsg" },
+        { from: "Microsoft.Network/networkInterfaces", path: "ipConfigurations[].properties.publicIPAddress.id", targetKind: "Microsoft.Network/publicIPAddresses", relation: "reference", label: "address" },
+        { from: "Microsoft.Network/natGateways", path: "publicIpAddresses[].id", targetKind: "Microsoft.Network/publicIPAddresses", relation: "reference", label: "address" },
+        { from: "Microsoft.Network/loadBalancers", path: "frontendIPConfigurations[].properties.publicIPAddress.id", targetKind: "Microsoft.Network/publicIPAddresses", relation: "reference", label: "address" },
+        { from: "Microsoft.Network/applicationGateways", path: "frontendIPConfigurations[].properties.publicIPAddress.id", targetKind: "Microsoft.Network/publicIPAddresses", relation: "reference", label: "address" },
+        { from: "Microsoft.Compute/virtualMachines", path: "networkProfile.networkInterfaces[].id", targetKind: "Microsoft.Network/networkInterfaces", relation: "reference", label: "nic" },
+        { from: "Microsoft.Web/sites", path: "serverFarmId", targetKind: "Microsoft.Web/serverfarms", relation: "reference", label: "on plan" },
+    ],
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant-lexicon-azure",
-  "version": "0.124.51",
+  "version": "0.124.54",
   "description": "Azure lexicon for chant — declarative IaC in TypeScript",
   "license": "Apache-2.0",
   "homepage": "https://intentius.io/chant",
@@ -79,6 +79,6 @@
     "typescript": "^5.9.3"
   },
   "peerDependencies": {
-    "@intentius/chant": "^0.124.51"
+    "@intentius/chant": "^0.124.54"
   }
 }

package/src/listed-types.test.ts

@@ -0,0 +1,68 @@
+/**
+ * #4521 on the azure lexicon: Resource Graph's lowercase type names mapped to
+ * kinds, and a fixture listing typed into nodes through the azure hooks.
+ */
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+import { typeListing, type ListingLexicon, type ListingResult } from "@intentius/chant/lifecycle/type-listing";
+import { MASKED } from "@intentius/chant/deep-observation";
+import { azureKindForListedType, azureListedTypeForKind, azureListedTypeIndex } from "./listed-types";
+import { azurePlugin } from "./plugin";
+
+const here = import.meta.dirname;
+const surface = JSON.parse(readFileSync(join(here, "..", "surface.snapshot.json"), "utf-8")) as {
+  entries: Record<string, { kind: string; resourceType: string }>;
+};
+// A kind is a resource type; the surface can name one type under two exports
+// (AppService and WebApp are both Microsoft.Web/sites), so the kinds are a set.
+const KINDS = [...new Set(Object.values(surface.entries).filter((e) => e.kind === "resource").map((e) => e.resourceType))];
+const INDEX = azureListedTypeIndex(KINDS);
+const listing = JSON.parse(readFileSync(join(here, "testdata", "indexed", "listing.json"), "utf-8")) as ListingResult;
+
+const azure: ListingLexicon = {
+  name: azurePlugin.name,
+  deepNormalizationHooks: azurePlugin.deepNormalizationHooks,
+  listedTypes: { ...azurePlugin.listedTypes!, kindFor: (t) => azureKindForListedType(t, INDEX) },
+};
+
+describe("Resource Graph types to azure kinds", () => {
+  it("every azure resource kind has a lowercase ARM type that maps back to it, and no two kinds share one", () => {
+    const missing = KINDS.filter((k) => azureKindForListedType(azureListedTypeForKind(k), INDEX) !== k);
+    expect(missing).toEqual([]);
+    expect(INDEX.size).toBe(KINDS.length);
+  });
+
+  it("child types join with / as ARM spells them, in any case", () => {
+    expect(azureListedTypeForKind("Microsoft.Network/virtualNetworks_subnets")).toBe("microsoft.network/virtualnetworks/subnets");
+    expect(azureKindForListedType("microsoft.storage/storageaccounts", INDEX)).toBe("Microsoft.Storage/storageAccounts");
+    expect(azureKindForListedType("Microsoft.Storage/storageAccounts", INDEX)).toBe("Microsoft.Storage/storageAccounts");
+    expect(azureKindForListedType("microsoft.contoso/widgets", INDEX)).toBeUndefined();
+  });
+});
+
+describe("the azure fixture listing as typed nodes", () => {
+  const doc = typeListing(listing, [azure]);
+
+  it("produces typed nodes, and keeps the unmapped type as an unknown-kind node", () => {
+    expect(doc.graph.nodes.map((n) => [n.listedType, n.kind, n.lexicon, n.unmappedKind ?? false])).toEqual([
+      ["microsoft.contoso/widgets", "microsoft.contoso/widgets", "azure", true],
+      ["microsoft.network/virtualnetworks/subnets", "Microsoft.Network/virtualNetworks_subnets", "azure", false],
+      ["microsoft.storage/storageaccounts", "Microsoft.Storage/storageAccounts", "azure", false],
+    ]);
+  });
+
+  it("flattens properties as the deep reader does, and prunes what the azure hooks prune", () => {
+    const st = doc.graph.nodes.find((n) => n.listedType === "microsoft.storage/storageaccounts")!;
+    expect(st.attrs.minimumTlsVersion).toBe("TLS1_2");
+    expect(st.attrs.sku).toEqual({ name: "Standard_LRS", tier: "Standard" });
+    expect(st.attrs.properties).toBeUndefined();
+    expect(st.attrs.id).toBeUndefined();
+    expect(st.attrs.provisioningState).toBeUndefined();
+  });
+
+  it("masks a secret on an unmapped node too", () => {
+    const w = doc.graph.nodes.find((n) => n.unmappedKind)!;
+    expect((w.attrs.properties as Record<string, unknown>).connectionString).toBe(MASKED);
+  });
+});

package/src/listed-types.ts

@@ -0,0 +1,65 @@
+/**
+ * Resource Graph's type names as azure lexicon kinds (#4521).
+ *
+ * behold#1029 lists Azure through Resource Graph, which lowercases every
+ * type and joins a child to its parent with `/`
+ * (`microsoft.network/virtualnetworks/subnets`). The lexicon's kinds come
+ * from the ARM schema ids, mixed case with `_` between a child and its parent
+ * (`Microsoft.Network/virtualNetworks_subnets`). So the mapping is a lookup:
+ * every kind, through {@link armType} and lowercased, is the listed type it
+ * answers to. ARM type names are case-insensitive, so no two kinds share one.
+ *
+ * A Resource Graph row has ARM's resource shape (`properties` beside
+ * `location`, `sku`, `identity`), and the deep reader flattens that shape
+ * before the hooks run (./deep-observe.ts `buildLiveProperties`), so an
+ * indexed row is flattened the same way.
+ */
+import type { ListedTypeMapping } from "@intentius/chant/lifecycle/type-listing";
+import { armType } from "./arm-type";
+import { buildLiveProperties, type ArmResourceShowResponse } from "./deep-observe";
+import { loadApiVersions } from "./serializer";
+
+/** `Microsoft.Network/virtualNetworks_subnets` as Resource Graph spells it: `microsoft.network/virtualnetworks/subnets`. */
+export function azureListedTypeForKind(kind: string): string {
+  return armType(kind).toLowerCase();
+}
+
+/** Listed type to kind, over a set of kinds. */
+export function azureListedTypeIndex(kinds: Iterable<string>): Map<string, string> {
+  const out = new Map<string, string>();
+  for (const kind of kinds) out.set(azureListedTypeForKind(kind), kind);
+  return out;
+}
+
+let cachedIndex: Map<string, string> | null | undefined;
+
+/** Built from the generated registry, or null in a checkout that has not generated. */
+function generatedIndex(): Map<string, string> | null {
+  if (cachedIndex !== undefined) return cachedIndex;
+  try {
+    cachedIndex = azureListedTypeIndex(loadApiVersions().keys());
+  } catch {
+    cachedIndex = null;
+  }
+  return cachedIndex;
+}
+
+/**
+ * The azure kind for a Resource Graph type, or undefined. Without a registry
+ * nothing maps: Resource Graph's lowercase spelling cannot be turned back
+ * into the kind's casing by rule.
+ */
+export function azureKindForListedType(listedType: string, index: Map<string, string> | null = generatedIndex()): string | undefined {
+  return index?.get(listedType.toLowerCase());
+}
+
+/** A Resource Graph row in the tree the deep reader compares. */
+export function azureObservedTree(properties: Record<string, unknown>): Record<string, unknown> {
+  return buildLiveProperties(properties as ArmResourceShowResponse);
+}
+
+export const azureListedTypes: ListedTypeMapping = {
+  substrate: "azure",
+  kindFor: (listedType) => azureKindForListedType(listedType),
+  observedTree: (properties) => azureObservedTree(properties),
+};

package/src/plugin.ts

@@ -15,6 +15,8 @@ import { join, dirname } from "path";
 import { fileURLToPath } from "url";
 import { moduleSourceDir } from "@intentius/chant/module-source";
 import { azureSerializer } from "./serializer";
+import { azureListedTypes } from "./listed-types";
+import { azureReferenceCatalog } from "./reference-catalog";
 import { azureGraphEdges } from "./graph-edges";
 import { hardcodedLocationRule } from "./lint/rules/hardcoded-location";
 import { storageHttpsRule } from "./lint/rules/storage-https";
@@ -495,6 +497,13 @@ export const tags = defaultTags([
   /** The noise rules the deep pass applies to both the live and declared trees. */
   deepNormalizationHooks: azureDeepNormalizationHooks,
 
+  // Cloud inventory type names to kinds, for an indexed resource (#4521).
+  listedTypes: azureListedTypes,
+
+  // How its resources reference each other, for chant's catalog pass over an
+  // index and a declared graph (#4535; behold#1005 retires behold's matcher on it).
+  referenceCatalog: azureReferenceCatalog,
+
   /** Runtime health (#4177): Container Apps. Implementation in ./health.ts. */
   healthTypes: ["Microsoft.App/containerApps"],
 

package/src/reference-catalog.test.ts

@@ -0,0 +1,144 @@
+/**
+ * #4535: the azure reference catalog. Each rule draws its edge on a fixture
+ * of its own, the catalog keeps behold#1023's ruling (typed rules, no edge on
+ * ambiguity, scoped join keys), and a Container Apps site in Resource Graph's
+ * shape (the resources example-three-cloud's azure member declares) gets its
+ * topology.
+ */
+import { describe, expect, it } from "vitest";
+import type { IRNode } from "@intentius/chant/graph-ir";
+import { reconstructIndexedEdges, refRuleId, type ReferenceCatalog } from "@intentius/chant/graph-refs";
+import { azureReferenceCatalog } from "./reference-catalog";
+import { azureObservedTree } from "./listed-types";
+import { azurePlugin } from "./plugin";
+
+const LEXICON = "azure";
+const SUB = "/subscriptions/00000000-0000-0000-0000-000000000001";
+const RG = `${SUB}/resourceGroups/local`;
+
+/** attrs with `value` written at a catalog path (`a.b`, `arr[].c`). */
+function atPath(path: string, value: string): Record<string, unknown> {
+  const parts = path.split(".");
+  const build = (i: number): unknown => {
+    if (i === parts.length) return value;
+    const part = parts[i];
+    const isArr = part.endsWith("[]");
+    const inner = build(i + 1);
+    return { [isArr ? part.slice(0, -2) : part]: isArr ? [inner] : inner };
+  };
+  return build(0) as Record<string, unknown>;
+}
+
+/** A node of `kind` named `value`: by its native id (an ARM id), or by the identity path a non-id reference reads. */
+function target(catalog: ReferenceCatalog, kind: string, id: string, value: string, byIdentity: boolean): IRNode {
+  const path = catalog.identities.find((r) => r.kind === kind)?.ids[0];
+  return byIdentity && path ? { id, kind, lexicon: LEXICON, attrs: atPath(path, value) } : { id, kind, lexicon: LEXICON, attrs: {}, nativeId: value };
+}
+
+/** A Resource Graph row as a node: flattened as ./listed-types.ts flattens it, named by its `id`. */
+function row(kind: string, id: string, properties: Record<string, unknown>, extra: Record<string, unknown> = {}): IRNode {
+  return { id, kind, lexicon: LEXICON, nativeId: id, location: "westeurope", attrs: azureObservedTree({ name: id.split("/").pop(), location: "westeurope", properties, ...extra }) };
+}
+
+const scope = (n: IRNode) => ({ account: `azure${SUB}`, ...(n.location ? { region: n.location } : {}) });
+
+describe("azure reference catalog", () => {
+  it("is the plugin's referenceCatalog", () => {
+    expect(azurePlugin.referenceCatalog).toBe(azureReferenceCatalog);
+  });
+
+  it("names a target kind on every rule (behold#1023's ruling)", () => {
+    expect(azureReferenceCatalog.refs.filter((r) => !(r.targetKind ?? r.indexedTargetKind))).toEqual([]);
+  });
+
+  it("has no two rules for one holder kind, path and target kind", () => {
+    const keys = azureReferenceCatalog.refs.map((r) => `${r.from}|${r.path}|${r.targetKind}`);
+    expect(keys.filter((k, i) => keys.indexOf(k) !== i)).toEqual([]);
+  });
+
+  describe("each rule draws its edge", () => {
+    for (const [i, rule] of azureReferenceCatalog.refs.entries()) {
+      const to = rule.targetKind ?? rule.indexedTargetKind!;
+      it(`${rule.from} ${rule.path} -> ${to}`, () => {
+        // An `.id` or `*Id` path holds an ARM id; anything else (a customer
+        // id, an identity's id in a registry entry) names the target by a
+        // value its identity rule lists.
+        const byId = /(^|\.)(id|[A-Za-z]+Id|[A-Za-z]+ID)$/.test(rule.path) || rule.path.endsWith("[].id");
+        const value = byId ? `${RG}/providers/${to.replace("_", "/")}/target-${i}` : `value-${i}`;
+        const holder: IRNode = { id: `holder-${i}`, kind: rule.from, lexicon: LEXICON, attrs: atPath(rule.path, value) };
+        const nodes = [holder, target(azureReferenceCatalog, to, `target-${i}`, value, !byId)];
+        const out = reconstructIndexedEdges(nodes, [{ lexicon: LEXICON, catalog: azureReferenceCatalog }], () => ({ account: "azure/sub" }));
+        const edge = out.edges.find((e) => e.from === holder.id && e.to === `target-${i}`);
+        expect(edge?.rule).toBe(refRuleId(LEXICON, rule.from, rule.path));
+        expect(edge?.relation).toBe(rule.relation);
+      });
+    }
+  });
+
+  describe("a Container Apps site in Resource Graph's shape", () => {
+    const vnet = `${RG}/providers/Microsoft.Network/virtualNetworks/three-cloud-vnet`;
+    const subnet = `${vnet}/subnets/apps`;
+    const logs = `${RG}/providers/Microsoft.OperationalInsights/workspaces/three-cloud-logs`;
+    const identity = `${RG}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/three-cloud-web`;
+    const env = `${RG}/providers/Microsoft.App/managedEnvironments/three-cloud`;
+    const app = `${RG}/providers/Microsoft.App/containerApps/web`;
+    const nodes: IRNode[] = [
+      row("Microsoft.Network/virtualNetworks", vnet, { addressSpace: { addressPrefixes: ["10.40.0.0/16"] }, subnets: [{ id: subnet, name: "apps", properties: { addressPrefix: "10.40.0.0/23" } }] }),
+      row("Microsoft.Network/virtualNetworks_subnets", subnet, { addressPrefix: "10.40.0.0/23" }),
+      row("Microsoft.OperationalInsights/workspaces", logs, { customerId: "6f1c2b3a-0000-4000-8000-000000000001", retentionInDays: 30 }),
+      row("Microsoft.ManagedIdentity/userAssignedIdentities", identity, {}),
+      row("Microsoft.App/managedEnvironments", env, {
+        vnetConfiguration: { infrastructureSubnetId: subnet },
+        appLogsConfiguration: { destination: "log-analytics", logAnalyticsConfiguration: { customerId: "6f1c2b3a-0000-4000-8000-000000000001" } },
+      }),
+      row(
+        "Microsoft.App/containerApps",
+        app,
+        { managedEnvironmentId: env, environmentId: env, configuration: { ingress: { fqdn: "web.three-cloud.westeurope.azurecontainerapps.io", external: true } } },
+        { identity: { type: "UserAssigned", userAssignedIdentities: { [identity]: {} } } },
+      ),
+    ];
+    const out = reconstructIndexedEdges(nodes, [{ lexicon: LEXICON, catalog: azureReferenceCatalog }], scope);
+    const short = (s: string) => s.split("/").slice(-2).join("/");
+
+    it("draws the environment's subnet and workspace and the app's environment", () => {
+      expect(out.edges.map((e) => `${short(e.from)} -> ${short(e.to)} [${e.viaAttr}] ${e.relation}`)).toEqual([
+        "containerApps/web -> managedEnvironments/three-cloud [environmentId] containment",
+        "containerApps/web -> managedEnvironments/three-cloud [managedEnvironmentId] containment",
+        "managedEnvironments/three-cloud -> subnets/apps [vnetConfiguration] containment",
+        "managedEnvironments/three-cloud -> workspaces/three-cloud-logs [appLogsConfiguration] reference",
+      ]);
+      expect(out.containment.map((c) => `${short(c.child)} in ${short(c.parent)}`)).toEqual([
+        "containerApps/web in managedEnvironments/three-cloud",
+        "managedEnvironments/three-cloud in subnets/apps",
+      ]);
+    });
+
+    it("leaves the identity, named in an object key, without an edge rather than guessing", () => {
+      expect(out.edges.some((e) => e.to === identity)).toBe(false);
+      expect(out.dangling).toEqual([]);
+    });
+  });
+
+  it("does not join a reference to the same id in another subscription", () => {
+    const subnet = `${RG}/providers/Microsoft.Network/virtualNetworks/v/subnets/apps`;
+    const nodes: IRNode[] = [
+      { ...row("Microsoft.App/managedEnvironments", "env", { vnetConfiguration: { infrastructureSubnetId: subnet } }) },
+      { ...row("Microsoft.Network/virtualNetworks_subnets", subnet, {}), id: "other-sub-subnet" },
+    ];
+    const out = reconstructIndexedEdges(nodes, [{ lexicon: LEXICON, catalog: azureReferenceCatalog }], (n) => ({ account: n.id === "env" ? "azure/sub-a" : "azure/sub-b", region: "westeurope" }));
+    expect(out.edges).toEqual([]);
+    expect(out.dangling.map((d) => d.value)).toEqual([subnet]);
+  });
+
+  it("draws no edge when a customer id names two workspaces, and records both", () => {
+    const nodes: IRNode[] = [
+      row("Microsoft.App/managedEnvironments", "env", { appLogsConfiguration: { logAnalyticsConfiguration: { customerId: "c-1" } } }),
+      row("Microsoft.OperationalInsights/workspaces", "ws-a", { customerId: "c-1" }),
+      row("Microsoft.OperationalInsights/workspaces", "ws-b", { customerId: "c-1" }),
+    ];
+    const out = reconstructIndexedEdges(nodes, [{ lexicon: LEXICON, catalog: azureReferenceCatalog }], scope);
+    expect(out.edges).toEqual([]);
+    expect(out.ambiguous.map((a) => a.candidates)).toEqual([["ws-a", "ws-b"]]);
+  });
+});

package/src/reference-catalog.ts

@@ -0,0 +1,84 @@
+import type { ReferenceCatalog } from "@intentius/chant/graph-refs";
+
+/**
+ * Azure reference catalog (#4535): how Azure resources name each other, so
+ * chant's catalog pass (`reconstructIndexedEdges`, #4522) draws their edges
+ * over an index and over a declared graph, and behold can retire its name
+ * matcher (behold#1005).
+ *
+ * ## Shape
+ *
+ * The paths are the flattened ARM shape: `properties.*` beside `location`,
+ * `sku` and `identity`. That is the tree a Resource Graph row becomes
+ * (./listed-types.ts `azureObservedTree`), the tree the deep reader compares
+ * (./deep-observe.ts `buildLiveProperties`), and the shape the lexicon's
+ * declared props already have, so one rule reads all three. Sub-resources
+ * inside a row (`ipConfigurations[]`, `frontendIPConfigurations[]`) keep
+ * their own `properties` level, because ARM nests them that way.
+ *
+ * ## Values are ARM resource ids
+ *
+ * An Azure reference is a resource id. An indexed node is matched by its
+ * native id, which for Azure is the row's `id`, so the targets need no
+ * identity rule for it. The identities below are the other values a
+ * reference reads: a workspace's `customerId`, an app's FQDN.
+ *
+ * Over a declared graph the same paths usually hold ARM expressions
+ * (`[resourceId(...)]`), which match no node; the lexicon's `graphEdges`
+ * hook (./graph-edges.ts) already draws those references from the
+ * expressions themselves.
+ *
+ * ## What this does not do
+ *
+ * - Matching is exact. ARM compares ids case-insensitively, and a reference
+ *   can spell `resourceGroups` where the target's id spells
+ *   `resourcegroups`. Such a reference is dangling, never joined to the
+ *   wrong node.
+ * - `identity.userAssignedIdentities` names its identities in object keys,
+ *   which `readPath` cannot read. A Container App's identity edge comes from
+ *   `graphEdges` on a declared graph and from nothing over an index.
+ * - A subnet's parent VNet is in the subnet's own id. No attribute names it,
+ *   so there is no containment rule for it.
+ */
+export const azureReferenceCatalog: ReferenceCatalog = {
+  identities: [
+    { kind: "Microsoft.OperationalInsights/workspaces", ids: ["customerId"] },
+    { kind: "Microsoft.App/containerApps", ids: ["configuration.ingress.fqdn", "latestRevisionFqdn"] },
+    { kind: "Microsoft.App/managedEnvironments", ids: ["defaultDomain", "staticIp"] },
+    { kind: "Microsoft.Network/publicIPAddresses", ids: ["ipAddress", "dnsSettings.fqdn"] },
+    { kind: "Microsoft.Web/sites", ids: ["defaultHostName"] },
+  ],
+  refs: [
+    // ── containment (→ boundary boxes) ──
+    { from: "Microsoft.App/managedEnvironments", path: "vnetConfiguration.infrastructureSubnetId", targetKind: "Microsoft.Network/virtualNetworks_subnets", relation: "containment", label: "in subnet" },
+    { from: "Microsoft.App/containerApps", path: "managedEnvironmentId", targetKind: "Microsoft.App/managedEnvironments", relation: "containment", label: "in environment" },
+    // The newer API versions write the same id under this name too.
+    { from: "Microsoft.App/containerApps", path: "environmentId", targetKind: "Microsoft.App/managedEnvironments", relation: "containment", label: "in environment" },
+    { from: "Microsoft.Network/networkInterfaces", path: "ipConfigurations[].properties.subnet.id", targetKind: "Microsoft.Network/virtualNetworks_subnets", relation: "containment", label: "in subnet" },
+    { from: "Microsoft.Network/privateEndpoints", path: "subnet.id", targetKind: "Microsoft.Network/virtualNetworks_subnets", relation: "containment", label: "in subnet" },
+    { from: "Microsoft.ContainerService/managedClusters", path: "agentPoolProfiles[].vnetSubnetID", targetKind: "Microsoft.Network/virtualNetworks_subnets", relation: "containment", label: "in subnet" },
+    { from: "Microsoft.Web/sites", path: "virtualNetworkSubnetId", targetKind: "Microsoft.Network/virtualNetworks_subnets", relation: "containment", label: "in subnet" },
+    { from: "Microsoft.ContainerInstance/containerGroups", path: "subnetIds[].id", targetKind: "Microsoft.Network/virtualNetworks_subnets", relation: "containment", label: "in subnet" },
+    { from: "Microsoft.Network/applicationGateways", path: "gatewayIPConfigurations[].properties.subnet.id", targetKind: "Microsoft.Network/virtualNetworks_subnets", relation: "containment", label: "in subnet" },
+    { from: "Microsoft.Network/loadBalancers", path: "frontendIPConfigurations[].properties.subnet.id", targetKind: "Microsoft.Network/virtualNetworks_subnets", relation: "containment", label: "in subnet" },
+
+    // ── references (→ edges) ──
+    // A managed environment names its workspace by the workspace's customer
+    // id, not its resource id.
+    { from: "Microsoft.App/managedEnvironments", path: "appLogsConfiguration.logAnalyticsConfiguration.customerId", targetKind: "Microsoft.OperationalInsights/workspaces", relation: "reference", label: "logs to" },
+    { from: "Microsoft.App/containerApps", path: "configuration.registries[].identity", targetKind: "Microsoft.ManagedIdentity/userAssignedIdentities", relation: "reference", label: "pulls as", optional: true },
+    { from: "Microsoft.Network/virtualNetworks_subnets", path: "networkSecurityGroup.id", targetKind: "Microsoft.Network/networkSecurityGroups", relation: "reference", label: "nsg" },
+    { from: "Microsoft.Network/virtualNetworks_subnets", path: "routeTable.id", targetKind: "Microsoft.Network/routeTables", relation: "reference", label: "routes" },
+    { from: "Microsoft.Network/virtualNetworks_subnets", path: "natGateway.id", targetKind: "Microsoft.Network/natGateways", relation: "reference", label: "egress via" },
+    // A VNet row from Resource Graph carries its subnets inline.
+    { from: "Microsoft.Network/virtualNetworks", path: "subnets[].properties.networkSecurityGroup.id", targetKind: "Microsoft.Network/networkSecurityGroups", relation: "reference", label: "nsg" },
+    { from: "Microsoft.Network/virtualNetworks", path: "subnets[].properties.routeTable.id", targetKind: "Microsoft.Network/routeTables", relation: "reference", label: "routes" },
+    { from: "Microsoft.Network/networkInterfaces", path: "networkSecurityGroup.id", targetKind: "Microsoft.Network/networkSecurityGroups", relation: "reference", label: "nsg" },
+    { from: "Microsoft.Network/networkInterfaces", path: "ipConfigurations[].properties.publicIPAddress.id", targetKind: "Microsoft.Network/publicIPAddresses", relation: "reference", label: "address" },
+    { from: "Microsoft.Network/natGateways", path: "publicIpAddresses[].id", targetKind: "Microsoft.Network/publicIPAddresses", relation: "reference", label: "address" },
+    { from: "Microsoft.Network/loadBalancers", path: "frontendIPConfigurations[].properties.publicIPAddress.id", targetKind: "Microsoft.Network/publicIPAddresses", relation: "reference", label: "address" },
+    { from: "Microsoft.Network/applicationGateways", path: "frontendIPConfigurations[].properties.publicIPAddress.id", targetKind: "Microsoft.Network/publicIPAddresses", relation: "reference", label: "address" },
+    { from: "Microsoft.Compute/virtualMachines", path: "networkProfile.networkInterfaces[].id", targetKind: "Microsoft.Network/networkInterfaces", relation: "reference", label: "nic" },
+    { from: "Microsoft.Web/sites", path: "serverFarmId", targetKind: "Microsoft.Web/serverfarms", relation: "reference", label: "on plan" },
+  ],
+};

package/src/testdata/indexed/listing.json

@@ -0,0 +1,56 @@
+{
+  "listing": "v1",
+  "source": { "name": "behold-lister", "version": "0.0.0-fixture" },
+  "scope": { "substrate": "azure", "scopeId": "00000000-0000-0000-0000-000000000001", "locations": "*", "types": "*" },
+  "startedAt": "2026-10-26T09:00:00.000Z",
+  "completedAt": "2026-10-26T09:00:02.000Z",
+  "resources": [
+    {
+      "listedType": "microsoft.storage/storageaccounts",
+      "location": "eastus",
+      "nativeId": "/subscriptions/00000000-0000-0000-0000-000000000001/resourceGroups/shop/providers/Microsoft.Storage/storageAccounts/shopassets",
+      "cloudIds": [
+        { "kind": "provider-id", "value": "/subscriptions/00000000-0000-0000-0000-000000000001/resourceGroups/shop/providers/Microsoft.Storage/storageAccounts/shopassets" },
+        { "kind": "provider-id", "value": "/subscriptions/00000000-0000-0000-0000-000000000001/resourcegroups/shop/providers/microsoft.storage/storageaccounts/shopassets" }
+      ],
+      "tags": { "tofu-estate": "shop" },
+      "properties": {
+        "id": "/subscriptions/00000000-0000-0000-0000-000000000001/resourceGroups/shop/providers/Microsoft.Storage/storageAccounts/shopassets",
+        "name": "shopassets",
+        "type": "microsoft.storage/storageaccounts",
+        "location": "eastus",
+        "resourceGroup": "shop",
+        "subscriptionId": "00000000-0000-0000-0000-000000000001",
+        "kind": "StorageV2",
+        "sku": { "name": "Standard_LRS", "tier": "Standard" },
+        "properties": {
+          "minimumTlsVersion": "TLS1_2",
+          "supportsHttpsTrafficOnly": true,
+          "provisioningState": "Succeeded",
+          "primaryEndpoints": { "blob": "https://shopassets.blob.core.windows.net/" }
+        }
+      },
+      "observedAt": "2026-10-26T09:00:01.000Z"
+    },
+    {
+      "listedType": "microsoft.network/virtualnetworks/subnets",
+      "location": "eastus",
+      "nativeId": "/subscriptions/00000000-0000-0000-0000-000000000001/resourceGroups/shop/providers/Microsoft.Network/virtualNetworks/shop-vnet/subnets/apps",
+      "cloudIds": [{ "kind": "provider-id", "value": "/subscriptions/00000000-0000-0000-0000-000000000001/resourceGroups/shop/providers/Microsoft.Network/virtualNetworks/shop-vnet/subnets/apps" }],
+      "tags": {},
+      "properties": { "name": "apps", "type": "microsoft.network/virtualnetworks/subnets", "properties": { "addressPrefix": "10.0.1.0/24" } },
+      "observedAt": "2026-10-26T09:00:01.000Z"
+    },
+    {
+      "listedType": "microsoft.contoso/widgets",
+      "location": "eastus",
+      "nativeId": "/subscriptions/00000000-0000-0000-0000-000000000001/resourceGroups/shop/providers/Microsoft.Contoso/widgets/w1",
+      "cloudIds": [{ "kind": "provider-id", "value": "/subscriptions/00000000-0000-0000-0000-000000000001/resourceGroups/shop/providers/Microsoft.Contoso/widgets/w1" }],
+      "tags": {},
+      "properties": { "name": "w1", "type": "microsoft.contoso/widgets", "properties": { "connectionString": "<masked>", "size": 3 } },
+      "observedAt": "2026-10-26T09:00:01.000Z"
+    }
+  ],
+  "coverage": [{ "listedType": "*", "location": "*", "verdict": "listed" }],
+  "notes": []
+}