@intentius/chant-lexicon-azure 0.28.0 → 0.30.0

package/dist/describe-resources.d.ts

@@ -8,12 +8,27 @@
  * (using props.name from #39's entity-prop pass-through). The environment
  * argument is treated as the Azure resource group name.
  *
- * Resource-not-found is silent — `state diff --live` then reports as missing.
- * Nested resource types (e.g. `Microsoft.Storage/storageAccounts/blobServices`)
- * are warn-skipped since `az resource show` doesn't accept them directly; they
- * need a different query path.
+ * Resource-not-found is an absence — `state diff --live` then reports it as
+ * missing. Nested resource types (e.g.
+ * `Microsoft.Storage/storageAccounts/blobServices`) are NOT-OBSERVED
+ * (`unsupported-kind`, #1089): `az resource show` doesn't accept a compound
+ * type, so chant never asks, and a blob service that already exists must not
+ * come back as a proposed `create`. Auth failures and unreachable subscriptions
+ * are holes for the same reason.
  */
-import type { ResourceMetadata } from "@intentius/chant/lexicon";
+import type { ObservationResult, UnobservedReason } from "@intentius/chant/lexicon";
+/**
+ * Classify an `az resource show` failure (#1089). Only the CLI's explicit
+ * not-found establishes absence; everything else — an expired login, a
+ * subscription that can't be resolved, a network failure — proves nothing.
+ */
+export declare function classifyAzFailure(err: unknown): {
+    absent: true;
+} | {
+    absent: false;
+    reason: UnobservedReason;
+    detail: string;
+};
 export declare function describeResources(options: {
     environment: string;
     buildOutput: string;
@@ -22,5 +37,5 @@ export declare function describeResources(options: {
         entityType: string;
         props: Record<string, unknown>;
     }>;
-}): Promise<Record<string, ResourceMetadata>>;
+}): Promise<ObservationResult>;
 //# sourceMappingURL=describe-resources.d.ts.map

package/dist/describe-resources.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"describe-resources.d.ts","sourceRoot":"","sources":["../src/describe-resources.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAIH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAkCjE,wBAAsB,iBAAiB,CAAC,OAAO,EAAE;IAC/C,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,CAAC,CAAC;CAC/E,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC,CAgD5C"}
+{"version":3,"file":"describe-resources.d.ts","sourceRoot":"","sources":["../src/describe-resources.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAIH,OAAO,KAAK,EAAE,iBAAiB,EAAsC,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAmCxH;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,OAAO,GAAG;IAAE,MAAM,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,MAAM,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,gBAAgB,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAkC9H;AAED,wBAAsB,iBAAiB,CAAC,OAAO,EAAE;IAC/C,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,CAAC,CAAC;CAC/E,GAAG,OAAO,CAAC,iBAAiB,CAAC,CA2E7B"}

package/dist/integrity.json

@@ -1,7 +1,7 @@
 {
   "algorithm": "sha256",
   "artifacts": {
-    "manifest.json": "81cfbd61238ba8f1a39800628a3deb9d6762b463e84fd6b02b03a72839b492ba",
+    "manifest.json": "50025ac710a4bd52992e4a6b196a56d2ff14735a095dd7f72cf8bcb389b761ea",
     "meta.json": "051fb4ee43f7de48a36f1abc59c8ff5207c3b75aa28f13db6440b9f5b0337605",
     "types/index.d.ts": "617a6de433bd92a126170a7f5ae903d6d7aa83fbb0b57169d3450b5a13e72e0d",
     "rules/hardcoded-location.ts": "a9b1d1cec93f2ca9c5206641f53fc9621cefcfd2c00b3ab89c194b30a75fa949",
@@ -33,5 +33,5 @@
     "skills/chant-azure-patterns.md": "1a3bacfac612826b77332d2692a59195638db9f1b5e8ea2eda7579621d25f603",
     "skills/chant-azure-aks.md": "2d4e0098c1a22b54ffadd410564d9df0f3a04cb4eb7c6261f20ae33106e7aca8"
   },
-  "composite": "9b71ffb460db8547a31947c1b50460dd28971b2758c282498e3c11ec8772baca"
+  "composite": "923cf13c8ea5dfb598f2aecae0e957d42e977bc511747871532644ab9230d8ed"
 }

package/dist/manifest.json

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

package/package.json

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

package/src/describe-resources.test.ts

@@ -50,7 +50,7 @@ describe("azure describeResources", () => {
     expect(receivedCmd).toContain("--name mydata");
     expect(receivedCmd).toContain("--resource-type Microsoft.Storage/storageAccounts");
 
-    expect(result["dataAccount"]).toMatchObject({
+    expect(result.resources["dataAccount"]).toMatchObject({
       type: "Microsoft.Storage/storageAccounts",
       physicalId: "/subscriptions/sub/resourceGroups/prod-rg/providers/Microsoft.Storage/storageAccounts/mydata",
       status: "Succeeded",
@@ -70,10 +70,10 @@ describe("azure describeResources", () => {
 
     const result = await describeResources({ environment: "prod-rg", buildOutput: "", entityNames: ["vnet"], entities });
 
-    expect(result["vnet"].status).toBe("PRESENT");
+    expect(result.resources["vnet"].status).toBe("PRESENT");
   });
 
-  test("az failure (resource not found) leaves entity out", async () => {
+  test("az failure (resource not found) leaves entity out — a confirmed absence", async () => {
     execMock.mockImplementation(() => { throw new Error("ResourceNotFound: ..."); });
 
     const entities = makeEntities([
@@ -82,10 +82,28 @@ describe("azure describeResources", () => {
 
     const result = await describeResources({ environment: "prod-rg", buildOutput: "", entityNames: ["missing"], entities });
 
-    expect(result).toEqual({});
+    expect(result.resources).toEqual({});
+    expect(result.unobserved ?? {}).toEqual({});
   });
 
-  test("nested-type entities are warn-skipped", async () => {
+  test("an expired az login is unobserved, not absent (#1089)", async () => {
+    execMock.mockImplementation(() => {
+      throw Object.assign(new Error("az failed"), {
+        stderr: "Please run 'az login' to setup account.",
+      });
+    });
+
+    const entities = makeEntities([
+      { name: "acct", entityType: "Microsoft.Storage/storageAccounts", props: { name: "acct" } },
+    ]);
+
+    const result = await describeResources({ environment: "prod-rg", buildOutput: "", entityNames: ["acct"], entities });
+
+    expect(result.resources).toEqual({});
+    expect(result.unobserved?.acct?.reason).toBe("no-credentials");
+  });
+
+  test("nested-type entities are unobserved, not absent (#1089)", async () => {
     const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
     const entities = makeEntities([
       { name: "nested", entityType: "Microsoft.Storage/storageAccounts/blobServices", props: { name: "x" } },
@@ -93,31 +111,37 @@ describe("azure describeResources", () => {
 
     const result = await describeResources({ environment: "prod-rg", buildOutput: "", entityNames: ["nested"], entities });
 
-    expect(result).toEqual({});
+    expect(result.resources).toEqual({});
+    expect(result.unobserved?.nested).toMatchObject({
+      type: "Microsoft.Storage/storageAccounts/blobServices",
+      reason: "unsupported-kind",
+    });
     expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining("nested-type"));
     expect(execMock).not.toHaveBeenCalled();
     warnSpy.mockRestore();
   });
 
-  test("non-Azure entity types are skipped", async () => {
+  test("non-Azure entity types are unobserved — no ARM type to query", async () => {
     const entities = makeEntities([
       { name: "x", entityType: "AWS::S3::Bucket", props: { name: "x" } },
     ]);
 
     const result = await describeResources({ environment: "prod-rg", buildOutput: "", entityNames: ["x"], entities });
 
-    expect(result).toEqual({});
+    expect(result.resources).toEqual({});
+    expect(result.unobserved?.x?.reason).toBe("unsupported-kind");
     expect(execMock).not.toHaveBeenCalled();
   });
 
-  test("entity without name is silently skipped", async () => {
+  test("entity without name is unobserved — nothing was queried", async () => {
     const entities = makeEntities([
       { name: "broken", entityType: "Microsoft.Storage/storageAccounts", props: {} },
     ]);
 
     const result = await describeResources({ environment: "prod-rg", buildOutput: "", entityNames: ["broken"], entities });
 
-    expect(result).toEqual({});
+    expect(result.resources).toEqual({});
+    expect(result.unobserved?.broken?.reason).toBe("read-failed");
     expect(execMock).not.toHaveBeenCalled();
   });
 });

package/src/describe-resources.ts

@@ -8,15 +8,19 @@
  * (using props.name from #39's entity-prop pass-through). The environment
  * argument is treated as the Azure resource group name.
  *
- * Resource-not-found is silent — `state diff --live` then reports as missing.
- * Nested resource types (e.g. `Microsoft.Storage/storageAccounts/blobServices`)
- * are warn-skipped since `az resource show` doesn't accept them directly; they
- * need a different query path.
+ * Resource-not-found is an absence — `state diff --live` then reports it as
+ * missing. Nested resource types (e.g.
+ * `Microsoft.Storage/storageAccounts/blobServices`) are NOT-OBSERVED
+ * (`unsupported-kind`, #1089): `az resource show` doesn't accept a compound
+ * type, so chant never asks, and a blob service that already exists must not
+ * come back as a proposed `create`. Auth failures and unreachable subscriptions
+ * are holes for the same reason.
  */
 
 import { exec } from "node:child_process";
 import { promisify } from "node:util";
-import type { ResourceMetadata } from "@intentius/chant/lexicon";
+import type { ObservationResult, ResourceMetadata, UnobservedEntity, UnobservedReason } from "@intentius/chant/lexicon";
+import { observation } from "@intentius/chant/observation";
 
 const execAsync = promisify(exec);
 
@@ -50,25 +54,88 @@ function isTopLevelType(entityType: string): boolean {
   return slashCount === 1;
 }
 
+/**
+ * Classify an `az resource show` failure (#1089). Only the CLI's explicit
+ * not-found establishes absence; everything else — an expired login, a
+ * subscription that can't be resolved, a network failure — proves nothing.
+ */
+export function classifyAzFailure(err: unknown): { absent: true } | { absent: false; reason: UnobservedReason; detail: string } {
+  const raw =
+    typeof err === "object" && err !== null && typeof (err as { stderr?: unknown }).stderr === "string"
+      ? ((err as { stderr: string }).stderr.trim() || String((err as { message?: unknown }).message ?? err))
+      : String((err as { message?: unknown } | undefined)?.message ?? err);
+  const lower = raw.toLowerCase();
+  const detail = (raw.split("\n").find((l) => l.trim().length > 0) ?? raw).trim().slice(0, 200);
+
+  if (
+    lower.includes("resourcenotfound") ||
+    lower.includes("was not found") ||
+    lower.includes("could not be found") ||
+    lower.includes("does not exist")
+  ) {
+    return { absent: true };
+  }
+  if (
+    lower.includes("please run 'az login'") ||
+    lower.includes("az login") ||
+    lower.includes("authenticationfailed") ||
+    lower.includes("expired") ||
+    lower.includes("authorizationfailed") ||
+    lower.includes("forbidden")
+  ) {
+    return { absent: false, reason: "no-credentials", detail };
+  }
+  if (
+    lower.includes("subscriptionnotfound") ||
+    lower.includes("no subscription") ||
+    lower.includes("please run 'az account set'")
+  ) {
+    return { absent: false, reason: "no-binding", detail };
+  }
+  return { absent: false, reason: "read-failed", detail };
+}
+
 export async function describeResources(options: {
   environment: string;
   buildOutput: string;
   entityNames: string[];
   entities: Map<string, { entityType: string; props: Record<string, unknown> }>;
-}): Promise<Record<string, ResourceMetadata>> {
+}): Promise<ObservationResult> {
   const result: Record<string, ResourceMetadata> = {};
+  const unobserved: Record<string, UnobservedEntity> = {};
   const skippedNested: string[] = [];
 
   for (const [entityName, { entityType, props }] of options.entities) {
-    if (!entityType.startsWith("Microsoft.")) continue;
+    if (!entityType.startsWith("Microsoft.")) {
+      // Not an ARM resource type, so `az resource show` has nothing to ask for.
+      // Unobserved rather than skipped: a silent skip reads as absence (#1089).
+      unobserved[entityName] = {
+        type: entityType,
+        reason: "unsupported-kind",
+        detail: "not an ARM resource type (expected Microsoft.<provider>/<kind>)",
+      };
+      continue;
+    }
 
     if (!isTopLevelType(entityType)) {
       skippedNested.push(entityName);
+      unobserved[entityName] = {
+        type: entityType,
+        reason: "unsupported-kind",
+        detail: "az resource show does not accept a nested ARM type; chant never queried this resource",
+      };
       continue;
     }
 
     const name = props.name as string | undefined;
-    if (!name) continue;
+    if (!name) {
+      unobserved[entityName] = {
+        type: entityType,
+        reason: "read-failed",
+        detail: "declared entity has no name to query by",
+      };
+      continue;
+    }
 
     const cmd = [
       "az", "resource", "show",
@@ -90,17 +157,22 @@ export async function describeResources(options: {
           tags: obj.tags,
         }),
       };
-    } catch {
-      // az returned non-zero (not found, auth, etc.) — leave entity out
+    } catch (err) {
+      // Not-found leaves the entity out (absence). Auth/binding/other failures
+      // are recorded as holes so they can't become creates (#1089).
+      const outcome = classifyAzFailure(err);
+      if (!outcome.absent) {
+        unobserved[entityName] = { type: entityType, reason: outcome.reason, detail: outcome.detail };
+      }
     }
   }
 
   if (skippedNested.length > 0) {
     // eslint-disable-next-line no-console
     console.warn(
-      `[azure] skipped ${skippedNested.length} nested-type entity(ies) — az resource show doesn't accept compound types: ${skippedNested.slice(0, 5).join(", ")}${skippedNested.length > 5 ? ", ..." : ""}`,
+      `[azure] ${skippedNested.length} nested-type entity(ies) reported as unobserved (not absent) — az resource show doesn't accept compound types: ${skippedNested.slice(0, 5).join(", ")}${skippedNested.length > 5 ? ", ..." : ""}`,
     );
   }
 
-  return result;
+  return observation(result, unobserved);
 }

package/src/lifecycle-integration.test.ts

@@ -31,6 +31,8 @@ vi.mock("node:child_process", async () => {
 const { azurePlugin } = await import("./plugin");
 const { liveImportFromPlugins } = await import("@intentius/chant/cli/commands/import");
 const { buildChangeSet } = await import("@intentius/chant/lifecycle/change-set");
+const { normalizeObservation } = await import("@intentius/chant/observation");
+const { describeObservationConformance } = await import("@intentius/chant-test-utils");
 
 const liveTemplate = {
   $schema:
@@ -85,14 +87,16 @@ describe("azure lifecycle integration (#163)", () => {
         : new Error("unexpected"),
     );
 
-    const observedNow = await azurePlugin.describeResources!({
-      environment: "prod",
-      buildOutput: "",
-      entityNames: ["myStore"],
-      entities: new Map([
-        ["myStore", { entityType: "Microsoft.Storage/storageAccounts", props: { name: "mystore" } }],
-      ]),
-    });
+    const { resources: observedNow } = normalizeObservation(
+      await azurePlugin.describeResources!({
+        environment: "prod",
+        buildOutput: "",
+        entityNames: ["myStore"],
+        entities: new Map([
+          ["myStore", { entityType: "Microsoft.Storage/storageAccounts", props: { name: "mystore" } }],
+        ]),
+      }),
+    );
     expect(observedNow.myStore?.type).toBe("Microsoft.Storage/storageAccounts");
 
     const cs = buildChangeSet("prod", {
@@ -112,3 +116,46 @@ describe("azure lifecycle integration (#163)", () => {
     expect(cs2.entries.find((e) => e.name === "myStore")!.action).toBe("noop");
   });
 });
+
+// The shared conformance suite (#1089).
+describeObservationConformance({
+  lexicon: "azure",
+  scenarios: [
+    {
+      name: "a nested ARM type az resource show cannot query",
+      declared: ["blobSvc", "gone"],
+      expectUnobserved: ["blobSvc"],
+      expectAbsent: ["gone"],
+      run: () => {
+        execMock.mockImplementation(() => new Error("ResourceNotFound: gone"));
+        return azurePlugin.describeResources!({
+          environment: "prod",
+          buildOutput: "",
+          entityNames: ["blobSvc", "gone"],
+          entities: new Map([
+            ["blobSvc", { entityType: "Microsoft.Storage/storageAccounts/blobServices", props: { name: "blob" } }],
+            ["gone", { entityType: "Microsoft.Storage/storageAccounts", props: { name: "gone" } }],
+          ]),
+        });
+      },
+    },
+    {
+      name: "an expired login",
+      declared: ["myStore"],
+      expectUnobserved: ["myStore"],
+      run: () => {
+        execMock.mockImplementation(() =>
+          Object.assign(new Error("az failed"), { stderr: "Please run 'az login' to setup account." }),
+        );
+        return azurePlugin.describeResources!({
+          environment: "prod",
+          buildOutput: "",
+          entityNames: ["myStore"],
+          entities: new Map([
+            ["myStore", { entityType: "Microsoft.Storage/storageAccounts", props: { name: "mystore" } }],
+          ]),
+        });
+      },
+    },
+  ],
+});