@intentius/chant-lexicon-gcp 0.28.0 → 0.30.0

package/dist/describe-resources.d.ts

@@ -9,7 +9,10 @@
  *   GCP::Storage::Bucket    → kubectl get storagebucket.storage.cnrm.cloud.google.com
  *   GCP::Compute::Subnetwork → kubectl get computesubnetwork.compute.cnrm.cloud.google.com
  *
- * Resource-not-found is silent — `state diff --live` reports it as missing.
+ * Resource-not-found is an absence — `state diff --live` reports it as missing.
+ * Everything else the kubectl call can fail with (auth, an unreachable API
+ * server, an entity type with no derivable GVK) is NOT-OBSERVED (#1089), so a
+ * read that never happened cannot become a proposed `create`.
  *
  * Since this reads Config Connector CRDs through the same kubectl path as
  * the K8s lexicon, it resolves the same environment→cluster binding (chant
@@ -18,7 +21,7 @@
  * `gcp.profiles` key, because it is fundamentally the same kubectl context a
  * project's K8s entities would use against the same cluster.
  */
-import type { ResourceMetadata } from "@intentius/chant/lexicon";
+import type { ObservationResult } from "@intentius/chant/lexicon";
 /**
  * Mirror of `lexicons/gcp/src/serializer.ts:deriveGVKFromType` — keeping the
  * derivation logic local so describeResources can compute the kubectl resource
@@ -37,5 +40,5 @@ export declare function describeResources(options: {
         props: Record<string, unknown>;
     }>;
     owned?: boolean;
-}): 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;;;;;;;;;;;;;;;;;;;GAmBG;AAIH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAsBjE;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,UAAU,EAAE,MAAM,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CASpF;AA4BD,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;IAC9E,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB,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;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAIH,OAAO,KAAK,EAAE,iBAAiB,EAAsC,MAAM,0BAA0B,CAAC;AAuBtG;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,UAAU,EAAE,MAAM,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CASpF;AA4BD,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;IAC9E,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CA8E7B"}

package/dist/integrity.json

@@ -1,7 +1,7 @@
 {
   "algorithm": "sha256",
   "artifacts": {
-    "manifest.json": "e3947f44bb23120c8a83b0ab90621adf262b9c578b763f025673669f11112b2a",
+    "manifest.json": "934b2e465f4a0be499267e8b23f84e1df1353c29eb599046ccb50bc20b3c2bd8",
     "meta.json": "475f10909854d059a2e2d4fb541c058803422e38b9c64bd4d6858c0623eedb8c",
     "types/index.d.ts": "5433b54c04b57d6fda8f3d81ef92ed0aca87f7e8e5dd3ea92d8de6e62a3ccfab",
     "rules/hardcoded-project.ts": "228631d3159e1ffcce2359c66073d4ae59bb0285f378e46e446f416aec50481c",
@@ -37,5 +37,5 @@
     "skills/chant-gcp-patterns.md": "a7ef31c1eb2f7244d3f73952c300472ef94c1eb09bd7a1003281b89299b6b704",
     "skills/chant-gcp-gke.md": "be277019da9a722c851e47cd2dfb9c9536668948c3535fb20db7697e934c4e2b"
   },
-  "composite": "7387aef29444d3c55659eaab15b350dda09923008bc2b95b2131b4bc956b7772"
+  "composite": "9b0f2abc33da4def1bad8cc078ec2d56039630e59fe397152d17d1a317f80b30"
 }

package/dist/manifest.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant-lexicon-gcp",
-  "version": "0.28.0",
+  "version": "0.30.0",
   "description": "Google Cloud lexicon for chant — declarative IaC in TypeScript",
   "license": "Apache-2.0",
   "homepage": "https://intentius.io/chant",
@@ -76,7 +76,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

@@ -55,7 +55,7 @@ describe("gcp describeResources (Config Connector)", () => {
     expect(receivedCmd).toContain("data-bucket");
     expect(receivedCmd).toContain("-n config-control");
 
-    expect(result["dataBucket"]).toMatchObject({
+    expect(result.resources["dataBucket"]).toMatchObject({
       type: "GCP::Storage::Bucket",
       physicalId: "uid-1",
       status: "READY",
@@ -99,7 +99,7 @@ describe("gcp describeResources (Config Connector)", () => {
 
     const result = await describeResources({ environment: "prod", buildOutput: "", entityNames: ["x"], entities });
 
-    expect(result["x"].status).toBe("DependencyNotFound");
+    expect(result.resources["x"].status).toBe("DependencyNotFound");
   });
 
   test("missing Ready condition falls back to PRESENT", async () => {
@@ -117,10 +117,10 @@ describe("gcp describeResources (Config Connector)", () => {
 
     const result = await describeResources({ environment: "prod", buildOutput: "", entityNames: ["x"], entities });
 
-    expect(result["x"].status).toBe("PRESENT");
+    expect(result.resources["x"].status).toBe("PRESENT");
   });
 
-  test("kubectl-not-found leaves entity out of result", async () => {
+  test("kubectl-not-found leaves entity out of result (a confirmed absence)", async () => {
     execMock.mockImplementation(() => { throw new Error('Error from server (NotFound): storagebucket "x" not found'); });
 
     const entities = makeEntities([
@@ -129,28 +129,48 @@ describe("gcp describeResources (Config Connector)", () => {
 
     const result = await describeResources({ environment: "prod", buildOutput: "", entityNames: ["x"], entities });
 
-    expect(result).toEqual({});
+    expect(result.resources).toEqual({});
+    expect(result.unobserved ?? {}).toEqual({});
   });
 
-  test("non-GCP entity types are skipped", async () => {
+  test("an unreachable cluster is unobserved, not absent (#1089)", async () => {
+    execMock.mockImplementation(() => {
+      throw Object.assign(new Error("kubectl failed"), {
+        stderr: "Unable to connect to the server: dial tcp: i/o timeout",
+      });
+    });
+
+    const entities = makeEntities([
+      { name: "x", entityType: "GCP::Storage::Bucket", props: { metadata: { name: "x" } } },
+    ]);
+
+    const result = await describeResources({ environment: "prod", buildOutput: "", entityNames: ["x"], entities });
+
+    expect(result.resources).toEqual({});
+    expect(result.unobserved?.x?.reason).toBe("no-binding");
+  });
+
+  test("non-GCP entity types are unobserved — no GVK to query (#1089)", async () => {
     const entities = makeEntities([
       { name: "x", entityType: "AWS::S3::Bucket", props: { metadata: { name: "x" } } },
     ]);
 
     const result = await describeResources({ environment: "prod", 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 metadata.name is silently skipped", async () => {
+  test("entity without metadata.name is unobserved — nothing was queried", async () => {
     const entities = makeEntities([
       { name: "broken", entityType: "GCP::Storage::Bucket", props: {} },
     ]);
 
     const result = await describeResources({ environment: "prod", buildOutput: "", entityNames: ["broken"], entities });
 
-    expect(result).toEqual({});
+    expect(result.resources).toEqual({});
+    expect(result.unobserved?.broken?.reason).toBe("read-failed");
     expect(execMock).not.toHaveBeenCalled();
   });
 
@@ -182,7 +202,7 @@ describe("gcp describeResources (Config Connector)", () => {
       const result = await describeResources({ environment: "prod", buildOutput: "", entityNames: ["dataBucket"], entities: bucketEntities() });
 
       expect(receivedCmd).toContain("--context prod-cnrm");
-      expect(result["dataBucket"]).toMatchObject({ type: "GCP::Storage::Bucket", physicalId: "uid-1", status: "READY" });
+      expect(result.resources["dataBucket"]).toMatchObject({ type: "GCP::Storage::Bucket", physicalId: "uid-1", status: "READY" });
     });
 
     test("bound and ambient context mismatches: refuses loudly instead of observing the wrong cluster", async () => {
@@ -212,7 +232,7 @@ describe("gcp describeResources (Config Connector)", () => {
 
       expect(receivedCmd).not.toContain("--context");
       expect(receivedCmd).not.toContain("current-context");
-      expect(result["dataBucket"]).toMatchObject({ type: "GCP::Storage::Bucket", physicalId: "uid-1", status: "READY" });
+      expect(result.resources["dataBucket"]).toMatchObject({ type: "GCP::Storage::Bucket", physicalId: "uid-1", status: "READY" });
 
       const bindingWarning = warnSpy.mock.calls.find((c) => String(c[0]).includes("no cluster binding"));
       expect(bindingWarning?.[0]).toContain('environment "prod"');

package/src/describe-resources.ts

@@ -9,7 +9,10 @@
  *   GCP::Storage::Bucket    → kubectl get storagebucket.storage.cnrm.cloud.google.com
  *   GCP::Compute::Subnetwork → kubectl get computesubnetwork.compute.cnrm.cloud.google.com
  *
- * Resource-not-found is silent — `state diff --live` reports it as missing.
+ * Resource-not-found is an absence — `state diff --live` reports it as missing.
+ * Everything else the kubectl call can fail with (auth, an unreachable API
+ * server, an entity type with no derivable GVK) is NOT-OBSERVED (#1089), so a
+ * read that never happened cannot become a proposed `create`.
  *
  * Since this reads Config Connector CRDs through the same kubectl path as
  * the K8s lexicon, it resolves the same environment→cluster binding (chant
@@ -21,10 +24,11 @@
 
 import { exec } from "node:child_process";
 import { promisify } from "node:util";
-import type { ResourceMetadata } from "@intentius/chant/lexicon";
+import type { ObservationResult, ResourceMetadata, UnobservedEntity } from "@intentius/chant/lexicon";
+import { observation } from "@intentius/chant/observation";
 import { hasOwnershipMarker, classifyOwnership, LABEL_OWNERSHIP_KEYS } from "@intentius/chant/ownership";
 import { loadChantConfig } from "@intentius/chant/config";
-import { resolveClusterTarget } from "@intentius/chant/kubectl-context";
+import { resolveClusterTarget, classifyKubectlFailure } from "@intentius/chant/kubectl-context";
 
 const execAsync = promisify(exec);
 
@@ -91,8 +95,9 @@ export async function describeResources(options: {
   entityNames: string[];
   entities: Map<string, { entityType: string; props: Record<string, unknown> }>;
   owned?: boolean;
-}): Promise<Record<string, ResourceMetadata>> {
+}): Promise<ObservationResult> {
   const result: Record<string, ResourceMetadata> = {};
+  const unobserved: Record<string, UnobservedEntity> = {};
 
   // Resolve the cluster identity for this environment before touching any
   // resource — a declared-but-mismatched binding throws here, aborting the
@@ -104,11 +109,27 @@ export async function describeResources(options: {
 
   for (const [entityName, { entityType, props }] of options.entities) {
     const gvk = deriveGVK(entityType);
-    if (!gvk) continue;
+    if (!gvk) {
+      // Not a `GCP::Service::Kind` this lexicon can turn into a Config
+      // Connector GVK — nothing was queried, so nothing is known (#1089).
+      unobserved[entityName] = {
+        type: entityType,
+        reason: "unsupported-kind",
+        detail: `cannot derive a Config Connector GVK from ${entityType}`,
+      };
+      continue;
+    }
 
     const metadata = props.metadata as { name?: string; namespace?: string } | undefined;
     const name = metadata?.name;
-    if (!name) continue;
+    if (!name) {
+      unobserved[entityName] = {
+        type: entityType,
+        reason: "read-failed",
+        detail: "declared entity has no metadata.name to query by",
+      };
+      continue;
+    }
 
     const kubectlResource = `${gvk.kind.toLowerCase()}.${gvk.group}`;
     const nsArg = metadata.namespace ? ["-n", metadata.namespace] : [];
@@ -117,8 +138,14 @@ export async function describeResources(options: {
     try {
       const { stdout } = await execAsync(cmd);
       const obj: KubectlResponse = JSON.parse(stdout);
-      // owned filter: skip resources not carrying chant's marker label.
+      // owned filter: withhold resources not carrying chant's marker label.
+      // Withheld is not absent (#1089) — the CR exists, it just isn't chant's.
       if (options.owned && !hasOwnershipMarker(obj.metadata?.labels, LABEL_OWNERSHIP_KEYS)) {
+        unobserved[entityName] = {
+          type: entityType,
+          reason: "filtered",
+          detail: "live resource carries no chant ownership marker and --owned was requested",
+        };
         continue;
       }
       result[entityName] = {
@@ -133,10 +160,17 @@ export async function describeResources(options: {
           annotations: obj.metadata?.annotations,
         }),
       };
-    } catch {
-      // CRD or instance not found — skip silently
+    } catch (err) {
+      // A NotFound is a real absence (the CR isn't there, or Config Connector
+      // doesn't serve that CRD, so no instance can be). Anything else — auth,
+      // an unreachable API server, a context that doesn't resolve — proves
+      // nothing and is reported as a hole rather than an absence (#1089).
+      const outcome = classifyKubectlFailure(err);
+      if (outcome.kind === "unobserved") {
+        unobserved[entityName] = { type: entityType, reason: outcome.reason, detail: outcome.detail };
+      }
     }
   }
 
-  return result;
+  return observation(result, unobserved);
 }

package/src/lifecycle-integration.test.ts

@@ -31,6 +31,8 @@ vi.mock("node:child_process", async () => {
 const { gcpPlugin } = 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 liveBucket = {
   apiVersion: "storage.cnrm.cloud.google.com/v1beta1",
@@ -84,20 +86,22 @@ describe("gcp lifecycle integration (#163)", () => {
         : new Error("not found"),
     );
 
-    const observedNow = await gcpPlugin.describeResources!({
-      environment: "prod",
-      buildOutput: "",
-      entityNames: ["dataBucket"],
-      entities: new Map([
-        [
-          "dataBucket",
-          {
-            entityType: "GCP::Storage::Bucket",
-            props: { metadata: { name: "data-bucket", namespace: "config-control" } },
-          },
-        ],
-      ]),
-    });
+    const { resources: observedNow } = normalizeObservation(
+      await gcpPlugin.describeResources!({
+        environment: "prod",
+        buildOutput: "",
+        entityNames: ["dataBucket"],
+        entities: new Map([
+          [
+            "dataBucket",
+            {
+              entityType: "GCP::Storage::Bucket",
+              props: { metadata: { name: "data-bucket", namespace: "config-control" } },
+            },
+          ],
+        ]),
+      }),
+    );
     expect(observedNow.dataBucket?.type).toBe("GCP::Storage::Bucket");
 
     const cs = buildChangeSet("prod", {
@@ -117,3 +121,46 @@ describe("gcp lifecycle integration (#163)", () => {
     expect(cs2.entries.find((e) => e.name === "dataBucket")!.action).toBe("noop");
   });
 });
+
+// The shared conformance suite (#1089).
+describeObservationConformance({
+  lexicon: "gcp",
+  scenarios: [
+    {
+      name: "an entity type with no derivable Config Connector GVK",
+      declared: ["notGcp", "gone"],
+      expectUnobserved: ["notGcp"],
+      expectAbsent: ["gone"],
+      run: () => {
+        execMock.mockImplementation(() => new Error('Error from server (NotFound): storagebucket "gone" not found'));
+        return gcpPlugin.describeResources!({
+          environment: "prod",
+          buildOutput: "",
+          entityNames: ["notGcp", "gone"],
+          entities: new Map([
+            ["notGcp", { entityType: "AWS::S3::Bucket", props: { metadata: { name: "not-gcp" } } }],
+            ["gone", { entityType: "GCP::Storage::Bucket", props: { metadata: { name: "gone" } } }],
+          ]),
+        });
+      },
+    },
+    {
+      name: "an unreachable Config Connector cluster",
+      declared: ["dataBucket"],
+      expectUnobserved: ["dataBucket"],
+      run: () => {
+        execMock.mockImplementation(() =>
+          Object.assign(new Error("kubectl failed"), { stderr: "Unable to connect to the server: dial tcp: i/o timeout" }),
+        );
+        return gcpPlugin.describeResources!({
+          environment: "prod",
+          buildOutput: "",
+          entityNames: ["dataBucket"],
+          entities: new Map([
+            ["dataBucket", { entityType: "GCP::Storage::Bucket", props: { metadata: { name: "data-bucket" } } }],
+          ]),
+        });
+      },
+    },
+  ],
+});