@intentius/chant 0.27.0 → 0.29.0

package/src/lifecycle/live-diff.test.ts

@@ -23,6 +23,7 @@ describe("diffLive", () => {
       newlyObserved: [],
       driftedSinceSnapshot: [],
       unchanged: [],
+      unobserved: [],
     });
   });
 
@@ -112,6 +113,44 @@ describe("diffLive", () => {
     expect(result.driftedSinceSnapshot.map((d) => d.name)).toEqual(["c"]);
     expect(result.unchanged).toEqual(["b"]);
   });
+
+  // ── The observation tri-state (#1089) ─────────────────────────────────────
+
+  test("declared and not observed → unobserved, not missing", () => {
+    const result = diffLive({
+      declared: new Set(["crd", "gone"]),
+      observedNow: {},
+      observedThen: undefined,
+      unobserved: { crd: { type: "K8s::X::Widget", reason: "unsupported-kind", detail: "no reader" } },
+    });
+    expect(result.missing).toEqual(["gone"]);
+    expect(result.unobserved).toEqual([
+      { name: "crd", type: "K8s::X::Widget", reason: "unsupported-kind", detail: "no reader" },
+    ]);
+  });
+
+  test("an unobserved entity in the last snapshot has not disappeared", () => {
+    const result = diffLive({
+      declared: new Set(["crd"]),
+      observedNow: {},
+      observedThen: { crd: meta() },
+      unobserved: { crd: { reason: "no-credentials" } },
+    });
+    expect(result.disappeared).toEqual([]);
+    expect(result.missing).toEqual([]);
+    expect(result.unobserved.map((u) => u.name)).toEqual(["crd"]);
+  });
+
+  test("a resource that was returned is never also unobserved", () => {
+    const result = diffLive({
+      declared: new Set(["a"]),
+      observedNow: { a: meta() },
+      observedThen: undefined,
+      unobserved: { a: { reason: "read-failed" } },
+    });
+    expect(result.unobserved).toEqual([]);
+    expect(result.newlyObserved).toEqual(["a"]);
+  });
 });
 
 describe("diffLiveArtifacts", () => {

package/src/lifecycle/live-diff.ts

@@ -13,6 +13,7 @@
  *                        outside chant's entity model)
  */
 import type { ResourceMetadata, ArtifactMetadata } from "../lexicon";
+import type { UnobservedEntity, UnobservedReason } from "../observation";
 
 export interface AttributeChange {
   /** Attribute path (e.g. "status", "physicalId", "attributes.tags.env"). */
@@ -27,8 +28,20 @@ export interface ResourceDrift {
   changes: AttributeChange[];
 }
 
+/** A declared entity the lexicon could not observe, as reported by the diff (#1089). */
+export interface UnobservedResource {
+  name: string;
+  type?: string;
+  reason: UnobservedReason;
+  detail?: string;
+}
+
 export interface LiveDiffResult {
-  /** Declared in current build, but not observed in cloud right now. */
+  /**
+   * Declared in current build, and the provider reported it absent. Entities
+   * the lexicon could not observe are NOT here — they are in `unobserved`
+   * (#1089), so "missing" keeps meaning "confirmed not there".
+   */
   missing: string[];
   /** Observed in cloud right now, but not declared. */
   orphan: string[];
@@ -40,6 +53,12 @@ export interface LiveDiffResult {
   driftedSinceSnapshot: ResourceDrift[];
   /** Observed both then and now; metadata identical. */
   unchanged: string[];
+  /**
+   * Declared, and the lexicon could not look (#1089) — no reader for the kind,
+   * the read failed, no credentials, no binding. Not drift, not absence: a hole
+   * in the observation. Sorted by name.
+   */
+  unobserved: UnobservedResource[];
 }
 
 export interface DiffLiveInput {
@@ -49,6 +68,12 @@ export interface DiffLiveInput {
   observedNow: Record<string, ResourceMetadata>;
   /** Resources captured by the previous snapshot, if any. */
   observedThen: Record<string, ResourceMetadata> | undefined;
+  /**
+   * Declared entities `describeResources()` reported as NOT-OBSERVED (#1089),
+   * keyed by entity name. Absent/empty means every declared entity was looked
+   * at, so absence from `observedNow` is a confirmed absence.
+   */
+  unobserved?: Record<string, UnobservedEntity>;
 }
 
 const TRACKED_FIELDS: Array<keyof ResourceMetadata> = [
@@ -135,6 +160,12 @@ export function diffLive(input: DiffLiveInput): LiveDiffResult {
   const observedThenMap = observedThen ?? {};
   const observedNowNames = new Set(Object.keys(observedNow));
   const observedThenNames = new Set(Object.keys(observedThenMap));
+  // A resource the lexicon returned is observed, whatever it also said about
+  // it — present beats not-observed.
+  const unobservedMap = input.unobserved ?? {};
+  const unobservedNames = new Set(
+    Object.keys(unobservedMap).filter((n) => !observedNowNames.has(n)),
+  );
 
   const missing: string[] = [];
   const orphan: string[] = [];
@@ -142,10 +173,23 @@ export function diffLive(input: DiffLiveInput): LiveDiffResult {
   const newlyObserved: string[] = [];
   const driftedSinceSnapshot: ResourceDrift[] = [];
   const unchanged: string[] = [];
+  const unobserved: UnobservedResource[] = [];
+
+  for (const name of unobservedNames) {
+    const entry = unobservedMap[name];
+    unobserved.push({
+      name,
+      ...(entry.type ? { type: entry.type } : {}),
+      reason: entry.reason,
+      ...(entry.detail ? { detail: entry.detail } : {}),
+    });
+  }
 
-  // Declared but not observed in cloud right now → missing
+  // Declared, looked at, and the provider said it isn't there → missing.
+  // Declared but never looked at is `unobserved`, not missing — the whole point
+  // of #1089: "we didn't check" must not read as "it isn't there".
   for (const name of declared) {
-    if (!observedNowNames.has(name)) {
+    if (!observedNowNames.has(name) && !unobservedNames.has(name)) {
       missing.push(name);
     }
   }
@@ -157,9 +201,10 @@ export function diffLive(input: DiffLiveInput): LiveDiffResult {
     }
   }
 
-  // In previous snapshot but not observed now → disappeared
+  // In previous snapshot but not observed now → disappeared. An entity nobody
+  // could look at has not disappeared; it is unobserved.
   for (const name of observedThenNames) {
-    if (!observedNowNames.has(name)) {
+    if (!observedNowNames.has(name) && !unobservedNames.has(name)) {
       disappeared.push(name);
     }
   }
@@ -194,6 +239,7 @@ export function diffLive(input: DiffLiveInput): LiveDiffResult {
     newlyObserved: newlyObserved.sort(),
     driftedSinceSnapshot: driftedSinceSnapshot.sort((a, b) => a.name.localeCompare(b.name)),
     unchanged: unchanged.sort(),
+    unobserved: unobserved.sort((a, b) => a.name.localeCompare(b.name)),
   };
 }
 

package/src/lifecycle/observe.test.ts

@@ -1,5 +1,6 @@
 import { describe, it, expect } from "vitest";
 import { observeResources } from "./observe";
+import { observation } from "../observation";
 import type { ObservationLexicon, ResourceMetadata } from "../lexicon";
 import type { BuildResult } from "../build";
 
@@ -47,13 +48,20 @@ describe("observeResources", () => {
     expect(names).toEqual(["web-vpc"]);
   });
 
-  it("collects a throwing plugin into errors instead of failing the whole graph", async () => {
+  it("collects a throwing plugin into errors instead of failing the whole graph, and reports its entities unobserved (#1089)", async () => {
     const plugins = [
       awsPlugin(() => { throw new Error("access denied"); }),
     ];
-    const { observations, errors } = await observeResources("prod", plugins, mockBuild());
-    expect(observations).toEqual([]);
+    const { observations, errors, warnings } = await observeResources("prod", plugins, mockBuild());
     expect(errors).toEqual(["aws: access denied"]);
+    // The failed read is a hole, not an empty environment: every declared
+    // entity comes back NOT-OBSERVED so nothing downstream reads it as absent.
+    expect(observations).toHaveLength(1);
+    expect(observations[0].resources).toEqual({});
+    expect(observations[0].unobserved).toEqual({
+      "web-vpc": { reason: "read-failed", type: "AWS::EC2::VPC", detail: "access denied" },
+    });
+    expect(warnings.join("\n")).toContain("web-vpc");
   });
 
   it("skips plugins with no describeResources and drops empty results", async () => {
@@ -63,6 +71,69 @@ describe("observeResources", () => {
     expect(observations).toEqual([]);
   });
 
+  // #1166 — this is exactly the "wrong endpoint" shape: AWS's stackDoesNotExist
+  // branch returns an empty map (bare `{}`, no #1089 envelope) for a declared
+  // entity nobody could actually observe. Before the fix this vanished with
+  // neither an observation nor a warning; now it must say so.
+  it("warns when a lexicon with declared entities observes zero resources and nothing is unobserved either (#1166)", async () => {
+    const empty = awsPlugin(() => ({}));
+    const { observations, warnings } = await observeResources("prod", [empty], mockBuild());
+    expect(observations).toEqual([]); // still no observation pushed — nothing to graph
+    expect(warnings).toEqual([
+      'aws: 0 live resources for env "prod" (1 declared) — check the endpoint/credentials',
+    ]);
+  });
+
+  it("does not warn about zero resources when the lexicon declares no entities at all", async () => {
+    const empty = awsPlugin(() => ({}));
+    const noEntities: BuildResult = { outputs: new Map(), entities: new Map(), errors: [] } as unknown as BuildResult;
+    const { warnings } = await observeResources("prod", [empty], noEntities);
+    expect(warnings).toEqual([]);
+  });
+
+  it("does not double-warn when the emptiness is already explained by #1089 unobserved", async () => {
+    const plugin = {
+      name: "aws",
+      serializer: {} as ObservationLexicon["serializer"],
+      describeResources: async () =>
+        observation({}, { "web-vpc": { type: "AWS::EC2::VPC", reason: "no-binding" } }),
+    } as unknown as ObservationLexicon;
+    const { warnings } = await observeResources("prod", [plugin], mockBuild());
+    // Only the #1089 per-entity warning — no separate "0 live resources" line.
+    expect(warnings).toHaveLength(1);
+    expect(warnings[0]).toContain("no binding for this environment");
+  });
+
+  it("carries a plugin's own unobserved entities through (#1089)", async () => {
+    const plugin = {
+      name: "aws",
+      serializer: {} as ObservationLexicon["serializer"],
+      describeResources: async () =>
+        observation({}, { "web-vpc": { type: "AWS::EC2::VPC", reason: "unsupported-kind" } }),
+    } as unknown as ObservationLexicon;
+    const { observations, warnings, errors } = await observeResources("prod", [plugin], mockBuild());
+    expect(errors).toEqual([]);
+    expect(observations[0].unobserved).toEqual({
+      "web-vpc": { type: "AWS::EC2::VPC", reason: "unsupported-kind" },
+    });
+    expect(warnings[0]).toContain("no reader for this resource kind");
+  });
+
+  it("merges multi-stack reads with present > not-observed > absent (#1089)", async () => {
+    const stacks = ["a", "b"];
+    const plugin = {
+      name: "aws",
+      serializer: {} as ObservationLexicon["serializer"],
+      describeResources: async (opts: { stack?: string }) =>
+        opts.stack === "a"
+          ? observation({}, { "web-vpc": { reason: "read-failed", detail: "stack a unreadable" } })
+          : observation({ "web-vpc": { type: "AWS::EC2::VPC", status: "CREATE_COMPLETE" } }),
+    } as unknown as ObservationLexicon;
+    const { observations } = await observeResources("prod", [plugin], mockBuild(), { stacks });
+    expect(Object.keys(observations[0].resources)).toEqual(["web-vpc"]);
+    expect(observations[0].unobserved).toBeUndefined();
+  });
+
   it("with no stacks: calls describeResources exactly once with no `stack` key (unchanged single-stack path)", async () => {
     const calls: Array<{ stack?: string }> = [];
     const plugins = [

package/src/lifecycle/observe.ts

@@ -9,10 +9,18 @@
  * side effects. Snapshotting keeps its own copy for now; a future refactor can
  * fold both onto this primitive.
  */
-import type { ObservationLexicon, ResourceMetadata } from "../lexicon";
+import type { ObservationLexicon } from "../lexicon";
 import type { BuildResult } from "../build";
 import type { SerializerResult } from "../serializer";
 import type { LiveObservation } from "../graph-ir";
+import {
+  mergeObservations,
+  normalizeObservation,
+  unobservedAll,
+  formatUnobserved,
+  type NormalizedObservation,
+} from "../observation";
+import { zeroResourcesWarning } from "../live-endpoint";
 
 export interface ObserveResult {
   observations: LiveObservation[];
@@ -25,8 +33,10 @@ export interface ObserveResult {
  * `environment`. `owned` (default true for the managed-only diagram, epic #776)
  * restricts to resources carrying chant's ownership marker; a lexicon with no
  * marker channel logs and returns everything (its own contract). Plugins that
- * throw are collected into `errors` and skipped — one failing lexicon never
- * sinks the whole graph.
+ * throw are collected into `errors` — one failing lexicon never sinks the whole
+ * graph — and every entity they were asked about is recorded as NOT-OBSERVED
+ * (`read-failed`, #1089) rather than dropped, so a failed read is visibly a
+ * hole instead of a silent absence.
  *
  * `stacks` (#57) is for a multi-stack, per-component project (e.g. loomster)
  * where there is no single stack named after the environment — AWS's
@@ -77,36 +87,86 @@ export async function observeResources(
     }
 
     try {
-      let resources: Record<string, ResourceMetadata>;
+      let observed: NormalizedObservation;
       if (stacks.length > 0) {
-        resources = {};
+        const parts: NormalizedObservation[] = [];
         for (const stack of stacks) {
-          const perStack = await plugin.describeResources({
+          parts.push(
+            normalizeObservation(
+              await plugin.describeResources({
+                environment,
+                buildOutput,
+                entityNames,
+                entities,
+                owned,
+                stack,
+              }),
+            ),
+          );
+        }
+        observed = mergeObservations(parts);
+      } else {
+        observed = normalizeObservation(
+          await plugin.describeResources({
             environment,
             buildOutput,
             entityNames,
             entities,
             owned,
-            stack,
-          });
-          Object.assign(resources, perStack);
-        }
-      } else {
-        resources = await plugin.describeResources({
-          environment,
-          buildOutput,
-          entityNames,
-          entities,
-          owned,
-        });
-      }
-      if (Object.keys(resources).length > 0) {
-        observations.push({ lexicon: plugin.name, resources });
+          }),
+        );
       }
+      pushObservation(observations, warnings, plugin.name, observed, environment, entityNames.length);
     } catch (err) {
-      errors.push(`${plugin.name}: ${err instanceof Error ? err.message : String(err)}`);
+      // A thrown read is the whole-lexicon failure: every declared entity is
+      // NOT-OBSERVED, not absent (#1089). Emitting nothing here is what made a
+      // failed read look like "none of these exist" to every consumer.
+      const message = err instanceof Error ? err.message : String(err);
+      errors.push(`${plugin.name}: ${message}`);
+      pushObservation(
+        observations,
+        warnings,
+        plugin.name,
+        {
+          resources: {},
+          unobserved: unobservedAll(entityNames, "read-failed", message, entities),
+        },
+        environment,
+        entityNames.length,
+      );
     }
   }
 
   return { observations, warnings, errors };
 }
+
+/** Record one lexicon's observation, warning once per unobserved entity. */
+function pushObservation(
+  observations: LiveObservation[],
+  warnings: string[],
+  lexicon: string,
+  observed: NormalizedObservation,
+  environment: string,
+  declaredCount: number,
+): void {
+  const hasResources = Object.keys(observed.resources).length > 0;
+  const unobservedNames = Object.keys(observed.unobserved);
+  for (const name of unobservedNames) {
+    warnings.push(`${lexicon}: not observed — ${formatUnobserved(name, observed.unobserved[name])}`);
+  }
+  if (!hasResources && unobservedNames.length === 0) {
+    // #1166 — this is exactly the "wrong endpoint" shape (AWS's
+    // stackDoesNotExist branch returns an empty map with no #1089 hole): a
+    // declared entity list with nothing observed and nothing explained.
+    // Previously this fell straight through with neither an observation nor a
+    // warning — silently indistinguishable from "nothing is deployed yet".
+    const notice = zeroResourcesWarning(lexicon, environment, declaredCount, observed);
+    if (notice) warnings.push(notice);
+    return;
+  }
+  observations.push({
+    lexicon,
+    resources: observed.resources,
+    ...(unobservedNames.length > 0 ? { unobserved: observed.unobserved } : {}),
+  });
+}

package/src/lifecycle/snapshot.test.ts

@@ -1,5 +1,5 @@
 import { describe, test, expect, vi, beforeEach } from "vitest";
-import { createMockPlugin, staticDescribeResources, staticListArtifacts } from "@intentius/chant-test-utils";
+import { createMockPlugin, staticDescribeResources, staticObservation, staticListArtifacts } from "@intentius/chant-test-utils";
 import type { BuildResult } from "../build";
 
 const writeSnapshotMock = vi.fn();
@@ -114,6 +114,44 @@ describe("takeSnapshot", () => {
     expect(result.errors.some((e) => e.includes("aws") && e.includes("no valid"))).toBe(true);
   });
 
+  // #1089 — a snapshot is evidence of what was seen. An entity nobody could
+  // read must be recorded as a hole, not omitted (which the next diff would
+  // read back as "was not there").
+  test("records unobserved entities alongside the resources", async () => {
+    const plugin = createMockPlugin({
+      name: "k8s",
+      describeResources: staticObservation(
+        { web: { type: "K8s::Apps::Deployment", status: "READY" } },
+        { widget: { type: "K8s::X::Widget", reason: "unsupported-kind", detail: "no reader" } },
+      ),
+    });
+    const result = await takeSnapshot("prod", [plugin], makeBuildResult({ k8s: ["web", "widget"] }));
+    expect(result.snapshots[0].unobserved).toEqual({
+      widget: { type: "K8s::X::Widget", reason: "unsupported-kind", detail: "no reader" },
+    });
+    expect(result.warnings.some((w) => w.includes("widget") && w.includes("not observed"))).toBe(true);
+  });
+
+  test("an entirely unreadable environment is not snapshotted as empty", async () => {
+    const plugin = createMockPlugin({
+      name: "k8s",
+      describeResources: staticObservation({}, { web: { reason: "no-credentials" } }),
+    });
+    const result = await takeSnapshot("prod", [plugin], makeBuildResult({ k8s: ["web"] }));
+    expect(result.snapshots).toEqual([]);
+    expect(result.errors.some((e) => e.includes("could not be read"))).toBe(true);
+  });
+
+  test("a throwing plugin reports each declared entity as unobserved in the warnings", async () => {
+    const plugin = createMockPlugin({
+      name: "k8s",
+      describeResources: async () => { throw new Error("kubeconfig missing"); },
+    });
+    const result = await takeSnapshot("prod", [plugin], makeBuildResult({ k8s: ["web"] }));
+    expect(result.snapshots).toEqual([]);
+    expect(result.warnings.some((w) => w.includes("web") && w.includes("kubeconfig missing"))).toBe(true);
+  });
+
   test("resources missing required type/status are dropped with warning", async () => {
     const plugin = createMockPlugin({
       name: "aws",

package/src/lifecycle/snapshot.ts

@@ -9,6 +9,7 @@ import type { LifecycleSnapshot } from "./types";
 import { computeBuildDigest } from "./digest";
 import { writeSnapshot, snapshotStorageKey, getHeadCommit, pushLifecycle } from "./git";
 import { sortedJsonReplacer } from "../utils";
+import { formatUnobserved, normalizeObservation, unobservedAll, type UnobservedEntity } from "../observation";
 
 /** Patterns in attribute names that suggest sensitive data. */
 const SENSITIVE_PATTERNS = [
@@ -124,22 +125,32 @@ export async function takeSnapshot(
 
     let resources: Record<string, ResourceMetadata> = {};
     let artifacts: Record<string, ArtifactMetadata> = {};
+    let unobserved: Record<string, UnobservedEntity> = {};
 
     try {
       if (plugin.describeResources) {
-        const raw = await plugin.describeResources({
-          environment,
-          buildOutput,
-          entityNames,
-          entities,
-          stack,
-        });
-        const { valid, dropped, warnings: validationWarnings } = validateResources(raw);
+        const observed = normalizeObservation(
+          await plugin.describeResources({
+            environment,
+            buildOutput,
+            entityNames,
+            entities,
+            stack,
+          }),
+        );
+        const { valid, dropped, warnings: validationWarnings } = validateResources(observed.resources);
         warnings.push(...validationWarnings);
         if (dropped.length > 0) {
           warnings.push(`${plugin.name}: dropped ${dropped.length} invalid resource(s)`);
         }
         resources = valid;
+        // Record the holes (#1089). A snapshot is evidence of what was seen; an
+        // entity nobody could read must not be recorded as "was not there",
+        // because the next diff would then read it back as absent.
+        unobserved = observed.unobserved;
+        for (const [name, entry] of Object.entries(unobserved)) {
+          warnings.push(`${plugin.name}: not observed — ${formatUnobserved(name, entry)}`);
+        }
       }
 
       if (plugin.listArtifacts) {
@@ -153,7 +164,12 @@ export async function takeSnapshot(
       }
 
       if (Object.keys(resources).length === 0 && Object.keys(artifacts).length === 0) {
-        errors.push(`${plugin.name}: no valid resources or artifacts returned`);
+        const unreadable = Object.keys(unobserved).length;
+        errors.push(
+          unreadable > 0
+            ? `${plugin.name}: nothing observed — ${unreadable} declared entity(ies) could not be read (see warnings); not snapshotting an unread environment as empty`
+            : `${plugin.name}: no valid resources or artifacts returned`,
+        );
         continue;
       }
 
@@ -164,15 +180,24 @@ export async function takeSnapshot(
         commit: headCommit,
         timestamp,
         resources,
+        ...(Object.keys(unobserved).length > 0 && { unobserved }),
         ...(Object.keys(artifacts).length > 0 && { artifacts }),
         digest,
       };
 
       snapshots.push(snapshot);
     } catch (err) {
+      // A thrown read is not an empty environment — record nothing and say so
+      // (#1089). Writing a snapshot here would persist "none of this exists".
       errors.push(
         `${plugin.name}: ${err instanceof Error ? err.message : String(err)}`,
       );
+      const message = err instanceof Error ? err.message : String(err);
+      for (const [name, entry] of Object.entries(
+        unobservedAll(entityNames, "read-failed", message, entities),
+      )) {
+        warnings.push(`${plugin.name}: not observed — ${formatUnobserved(name, entry)}`);
+      }
     }
   }