@intentius/chant 0.28.0 → 0.29.0

package/src/observation.test.ts

@@ -0,0 +1,96 @@
+/**
+ * The observation contract itself (#1089) — the normalizer, the envelope
+ * discriminant, and the multi-stack merge.
+ */
+import { describe, test, expect } from "vitest";
+import {
+  UNOBSERVED_REASONS,
+  formatUnobserved,
+  isObservationResult,
+  isUnobservedReason,
+  mergeObservations,
+  normalizeObservation,
+  observation,
+  unobservedAll,
+  unobservedReasonText,
+} from "./observation";
+import type { ResourceMetadata } from "./lexicon";
+
+const meta = (over: Partial<ResourceMetadata> = {}): ResourceMetadata => ({
+  type: "Fake::Resource",
+  status: "OK",
+  ...over,
+});
+
+describe("normalizeObservation", () => {
+  test("a bare map means 'I looked at everything'", () => {
+    expect(normalizeObservation({ a: meta() })).toEqual({ resources: { a: meta() }, unobserved: {} });
+  });
+
+  test("the envelope carries both halves", () => {
+    const value = observation({ a: meta() }, { b: { reason: "read-failed" } });
+    expect(normalizeObservation(value)).toEqual({
+      resources: { a: meta() },
+      unobserved: { b: { reason: "read-failed" } },
+    });
+  });
+
+  test("undefined normalizes to two empty maps", () => {
+    expect(normalizeObservation(undefined)).toEqual({ resources: {}, unobserved: {} });
+  });
+
+  test("an entity literally named `observation` cannot be mistaken for the envelope", () => {
+    const bare = { observation: meta({ type: "Odd::Name" }) };
+    expect(isObservationResult(bare)).toBe(false);
+    expect(normalizeObservation(bare).resources.observation.type).toBe("Odd::Name");
+  });
+
+  test("the envelope omits an empty unobserved map", () => {
+    expect(observation({ a: meta() }, {})).toEqual({ observation: "v1", resources: { a: meta() } });
+  });
+});
+
+describe("unobservedAll", () => {
+  test("marks every named entity with one reason, carrying declared types", () => {
+    const entities = new Map([["a", { entityType: "AWS::S3::Bucket" }]]);
+    expect(unobservedAll(["a", "b"], "no-credentials", "token expired", entities)).toEqual({
+      a: { reason: "no-credentials", type: "AWS::S3::Bucket", detail: "token expired" },
+      b: { reason: "no-credentials", detail: "token expired" },
+    });
+  });
+});
+
+describe("mergeObservations (multi-stack)", () => {
+  test("present beats not-observed beats absent", () => {
+    const merged = mergeObservations([
+      { resources: {}, unobserved: { a: { reason: "read-failed" }, b: { reason: "no-binding" } } },
+      { resources: { a: meta() }, unobserved: {} },
+    ]);
+    expect(Object.keys(merged.resources)).toEqual(["a"]);
+    expect(Object.keys(merged.unobserved)).toEqual(["b"]);
+  });
+
+  test("an entity nobody looked for in any stack stays absent", () => {
+    const merged = mergeObservations([
+      { resources: { a: meta() }, unobserved: {} },
+      { resources: { b: meta() }, unobserved: {} },
+    ]);
+    expect(merged.unobserved).toEqual({});
+  });
+});
+
+describe("reason totality", () => {
+  test("every reason has human text and passes the guard", () => {
+    for (const reason of UNOBSERVED_REASONS) {
+      expect(isUnobservedReason(reason)).toBe(true);
+      expect(unobservedReasonText(reason).length).toBeGreaterThan(0);
+    }
+    expect(isUnobservedReason("made-up")).toBe(false);
+  });
+
+  test("formatUnobserved names the entity, the type and the detail", () => {
+    expect(
+      formatUnobserved("widget", { type: "K8s::X::Widget", reason: "unsupported-kind", detail: "no mapping" }),
+    ).toBe("widget (K8s::X::Widget) — no reader for this resource kind: no mapping");
+  });
+});

package/src/observation.ts

@@ -0,0 +1,213 @@
+/**
+ * The observation contract (#1089) — what a lexicon's `describeResources()`
+ * is allowed to mean.
+ *
+ * Before this module there were two ways for an observation to return nothing
+ * for a declared entity and no way to tell them apart:
+ *
+ *   1. The provider was asked and said the resource does not exist.
+ *   2. The lexicon never looked — no reader for that kind, the read errored,
+ *      no credentials, no cluster/subscription binding.
+ *
+ * Both arrived at the change set as "absent", and absent + declared classifies
+ * as `create`. So `chant lifecycle plan` proposed creating a Kubernetes CRD
+ * that already existed in the cluster, with nothing in the plan to say the tool
+ * had simply not looked (a warn on stderr is not a signal in a change set).
+ *
+ * The contract is a tri-state, per declared entity:
+ *
+ *   - **OBSERVED-PRESENT** — a key in `resources`. The provider returned it.
+ *   - **OBSERVED-ABSENT** — in neither map. The lexicon looked and the provider
+ *     reported it missing. This is the only shape that may become a `create`.
+ *   - **NOT-OBSERVED** — a key in `unobserved`, carrying a total
+ *     {@link UnobservedReason}. Never a `create`, never a `delete`; consumers
+ *     surface it and stop.
+ *
+ * Compatibility: `describeResources()` may still return the bare
+ * `name → ResourceMetadata` map it always did — that means "everything I was
+ * asked about, I looked at" and normalizes to an empty `unobserved`. Reporting
+ * NOT-OBSERVED requires the explicitly versioned {@link ObservationResult}
+ * envelope, which is discriminated by its literal `observation: "v1"` field (a
+ * bare map's value at any key is a `ResourceMetadata` object, never that
+ * string, so the two shapes can never be confused).
+ */
+
+import type { ResourceMetadata } from "./lexicon";
+
+/**
+ * Why a declared entity was not observed. Total: a lexicon that cannot observe
+ * an entity must pick one of these, and consumers may switch exhaustively.
+ *
+ * - `read-failed` — the provider was reached and the read errored (a non-zero
+ *   CLI exit, a 5xx, an unparseable response).
+ * - `no-credentials` — no usable credentials/authorization for the target.
+ * - `no-binding` — the environment resolves to no concrete target (no kubectl
+ *   context, no subscription, no stack, no endpoint).
+ * - `unsupported-kind` — the lexicon has no reader for this entity type (the
+ *   K8s CRD case, Azure's nested ARM types). The resource may well exist.
+ * - `filtered` — the entity was reached but withheld by a caller-requested
+ *   filter (`owned: true` against a resource carrying no chant marker). The
+ *   result deliberately says nothing about it, which is still not absence: a
+ *   declared resource that exists but is foreign must not classify as `create`.
+ */
+export type UnobservedReason =
+  | "read-failed"
+  | "no-credentials"
+  | "no-binding"
+  | "unsupported-kind"
+  | "filtered";
+
+/** Every legal {@link UnobservedReason}, for validation and conformance checks. */
+export const UNOBSERVED_REASONS: readonly UnobservedReason[] = [
+  "read-failed",
+  "no-credentials",
+  "no-binding",
+  "unsupported-kind",
+  "filtered",
+];
+
+/** True when `value` is a legal {@link UnobservedReason}. */
+export function isUnobservedReason(value: unknown): value is UnobservedReason {
+  return typeof value === "string" && (UNOBSERVED_REASONS as readonly string[]).includes(value);
+}
+
+/** One declared entity the lexicon could not observe, and why. */
+export interface UnobservedEntity {
+  /** Declared entity type, when the lexicon knows it (it usually does — the entity is declared). */
+  type?: string;
+  /** Total verdict. */
+  reason: UnobservedReason;
+  /** Human-readable detail: the command that failed, the missing binding key, the unsupported kind. */
+  detail?: string;
+}
+
+/**
+ * The observation envelope — a `describeResources()` return value that can say
+ * "I did not look at this one". Explicitly versioned: `observation: "v1"`.
+ */
+export interface ObservationResult {
+  /** Discriminant + wire version. Distinguishes the envelope from the bare `name → ResourceMetadata` map. */
+  readonly observation: "v1";
+  /** OBSERVED-PRESENT, keyed by chant entity name. */
+  resources: Record<string, ResourceMetadata>;
+  /** NOT-OBSERVED, keyed by chant entity name. Omit or leave empty when everything asked about was looked at. */
+  unobserved?: Record<string, UnobservedEntity>;
+}
+
+/**
+ * What `describeResources()` may return: the bare map (pre-#1089, still valid —
+ * "I looked at everything") or the {@link ObservationResult} envelope.
+ */
+export type DescribeResourcesResult = Record<string, ResourceMetadata> | ObservationResult;
+
+/** Normalized form every consumer works with. Both maps always present. */
+export interface NormalizedObservation {
+  resources: Record<string, ResourceMetadata>;
+  unobserved: Record<string, UnobservedEntity>;
+}
+
+/** True when `value` is the versioned {@link ObservationResult} envelope. */
+export function isObservationResult(value: unknown): value is ObservationResult {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    (value as { observation?: unknown }).observation === "v1"
+  );
+}
+
+/**
+ * Build an {@link ObservationResult}. Lexicons use this rather than writing the
+ * discriminant by hand.
+ */
+export function observation(
+  resources: Record<string, ResourceMetadata>,
+  unobserved?: Record<string, UnobservedEntity>,
+): ObservationResult {
+  return {
+    observation: "v1",
+    resources,
+    ...(unobserved && Object.keys(unobserved).length > 0 ? { unobserved } : {}),
+  };
+}
+
+/**
+ * Normalize either accepted return shape. `undefined` (a lexicon that returned
+ * nothing at all) normalizes to two empty maps — which reads as "everything was
+ * observed absent", so callers that mean "the read failed" must say so with
+ * {@link unobservedAll} rather than returning nothing.
+ */
+export function normalizeObservation(value: DescribeResourcesResult | undefined): NormalizedObservation {
+  if (!value) return { resources: {}, unobserved: {} };
+  if (isObservationResult(value)) {
+    return { resources: value.resources ?? {}, unobserved: value.unobserved ?? {} };
+  }
+  return { resources: value, unobserved: {} };
+}
+
+/**
+ * Mark every named entity NOT-OBSERVED with one reason — the whole-lexicon
+ * failure case (the provider CLI is missing, the cluster binding refused, the
+ * credentials are gone). Core applies this when `describeResources()` throws,
+ * so a thrown read degrades to an honest "did not look" for each declared
+ * entity instead of an empty map that classifies as N creates.
+ */
+export function unobservedAll(
+  names: Iterable<string>,
+  reason: UnobservedReason,
+  detail?: string,
+  types?: Map<string, { entityType: string }> | Record<string, string>,
+): Record<string, UnobservedEntity> {
+  const typeOf = (name: string): string | undefined => {
+    if (!types) return undefined;
+    if (types instanceof Map) return types.get(name)?.entityType;
+    return types[name];
+  };
+  const out: Record<string, UnobservedEntity> = {};
+  for (const name of names) {
+    const type = typeOf(name);
+    out[name] = { reason, ...(type ? { type } : {}), ...(detail ? { detail } : {}) };
+  }
+  return out;
+}
+
+/**
+ * Union several observations of the same lexicon (the multi-stack read, where
+ * `describeResources` runs once per stack). Precedence is
+ * present > not-observed > absent: a resource found in any stack is present; an
+ * entity nobody could look at stays not-observed; an entity every reader looked
+ * for and did not find is absent.
+ */
+export function mergeObservations(parts: Iterable<NormalizedObservation>): NormalizedObservation {
+  const resources: Record<string, ResourceMetadata> = {};
+  const unobserved: Record<string, UnobservedEntity> = {};
+  for (const part of parts) {
+    Object.assign(resources, part.resources);
+    Object.assign(unobserved, part.unobserved);
+  }
+  // Present wins: a stack that could not be read does not un-observe a resource
+  // another stack returned.
+  for (const name of Object.keys(resources)) delete unobserved[name];
+  return { resources, unobserved };
+}
+
+/** One-line human phrasing of a reason, for CLI output. */
+export function unobservedReasonText(reason: UnobservedReason): string {
+  switch (reason) {
+    case "read-failed":
+      return "read failed";
+    case "no-credentials":
+      return "no credentials";
+    case "no-binding":
+      return "no binding for this environment";
+    case "unsupported-kind":
+      return "no reader for this resource kind";
+    case "filtered":
+      return "withheld by the --owned filter";
+  }
+}
+
+/** `name — reason (detail)`, the shared rendering for CLI and plan output. */
+export function formatUnobserved(name: string, entry: UnobservedEntity): string {
+  const base = `${name}${entry.type ? ` (${entry.type})` : ""} — ${unobservedReasonText(entry.reason)}`;
+  return entry.detail ? `${base}: ${entry.detail}` : base;
+}

package/src/stack-output.test.ts

@@ -97,6 +97,61 @@ describe("stackOutput", () => {
     expect(out.lexicon).toBe("aws");
     vi.resetModules();
   });
+
+  // chant #1152 — a CloudFormation Parameter carries no attributes at all, so
+  // `Ref(param)` (an intrinsic wrapping the Parameter Declarable directly, not
+  // one of its attributes) could never contain a nested AttrRef for the old
+  // AttrRef-only anchor search to find. Before the fix that meant `firstAttrRef`
+  // always came back empty for this shape and the output's `lexicon` silently
+  // became `"unknown"` — not a thrown error (a Parameter-wrapping `Ref` already
+  // carries the `Intrinsic` marker, so the input-validation guard always
+  // accepted it), but `"unknown"` isn't any real lexicon's partition, so the
+  // output was silently dropped from every serializer's `Outputs` section.
+  const param: Declarable = {
+    lexicon: "aws",
+    entityType: "AWS::CloudFormation::Parameter",
+    [DECLARABLE_MARKER]: true,
+  };
+
+  test("derives lexicon from a Declarable referenced directly by a wrapping intrinsic (Ref(param))", () => {
+    const ref = {
+      [INTRINSIC_MARKER]: true as const,
+      target: param,
+      toJSON: () => ({ Ref: "environment" }),
+    };
+
+    const out = stackOutput(ref, { exportName: "EnvironmentName" });
+    expect(out.lexicon).toBe("aws");
+    expect(out.sourceRef).toBe(ref);
+    expect(out.exportName).toBe("EnvironmentName");
+  });
+
+  test("derives lexicon from a Declarable referenced directly, nested inside a further intrinsic (Sub interpolating Ref(param))", () => {
+    const ref = {
+      [INTRINSIC_MARKER]: true as const,
+      target: param,
+      toJSON: () => ({ Ref: "environment" }),
+    };
+    const sub = {
+      [INTRINSIC_MARKER]: true as const,
+      values: [ref],
+      toJSON: () => ({ "Fn::Sub": "env-${environment}" }),
+    };
+
+    const out = stackOutput(sub);
+    expect(out.lexicon).toBe("aws");
+  });
+
+  test("an explicit options.lexicon still wins over a Declarable-derived anchor", () => {
+    const ref = {
+      [INTRINSIC_MARKER]: true as const,
+      target: param,
+      toJSON: () => ({ Ref: "environment" }),
+    };
+
+    const out = stackOutput(ref, { lexicon: "gcp" });
+    expect(out.lexicon).toBe("gcp");
+  });
 });
 
 describe("isStackOutput", () => {

package/src/stack-output.ts

@@ -6,7 +6,7 @@
  * it via `nestedStack().outputs.name`.
  */
 
-import { DECLARABLE_MARKER, type Declarable } from "./declarable";
+import { DECLARABLE_MARKER, isDeclarable, type Declarable } from "./declarable";
 import { AttrRef } from "./attrref";
 import { isIntrinsic, type Intrinsic } from "./intrinsic";
 import { isAttrRefLike } from "./utils";
@@ -35,25 +35,47 @@ export interface StackOutput extends Declarable {
   readonly exportName?: string;
 }
 
-/** Find the first AttrRef anywhere inside a value (walking intrinsics/objects/
- * arrays), so a wrapping intrinsic can still borrow its parent's lexicon.
- * Duck-type, not `instanceof` (chant #1137): a lexicon built against a
- * separate copy of `@intentius/chant` produces AttrRefs that fail
- * `instanceof AttrRef` here but carry the same shape — missing one would
- * make the walk recurse into the AttrRef's own (unhelpful) fields instead
- * of stopping on it, silently failing to find the anchor. */
-function firstAttrRef(value: unknown, seen = new Set<unknown>()): AttrRef | undefined {
+/** What a wrapping intrinsic's lexicon gets derived from: either a nested
+ * AttrRef (borrow its parent's `.lexicon`) or a Declarable referenced
+ * directly (use its own `.lexicon`). Two shapes, not one, because
+ * `Ref(someEntity)` (chant #1152) wraps the entity itself — a
+ * CloudFormation Parameter carries no attributes at all, so `Ref(param)`
+ * can never contain a nested AttrRef for a single-shape search to find. */
+type Anchor = { readonly kind: "attrRef"; readonly ref: AttrRef } | { readonly kind: "declarable"; readonly entity: Declarable };
+
+/** Find the first AttrRef or directly-referenced Declarable anywhere inside a
+ * value (walking intrinsics/objects/arrays), so a wrapping intrinsic can
+ * still borrow its source's lexicon. Duck-type, not `instanceof` (chant
+ * #1137): a lexicon built against a separate copy of `@intentius/chant`
+ * produces AttrRefs/Declarables that fail `instanceof` here but carry the
+ * same shape (`isDeclarable`'s `Symbol.for` marker is already dual-copy-safe
+ * on its own) — missing one would make the walk recurse into its own
+ * (unhelpful) fields instead of stopping on it, silently failing to find the
+ * anchor. */
+function findAnchor(value: unknown, seen = new Set<unknown>()): Anchor | undefined {
   if (value === null || typeof value !== "object" || seen.has(value)) return undefined;
-  if (isAttrRefLike(value)) return value;
+  if (isAttrRefLike(value)) return { kind: "attrRef", ref: value };
+  if (isDeclarable(value)) return { kind: "declarable", entity: value };
   seen.add(value);
   const children = Array.isArray(value) ? value : Object.values(value as Record<string, unknown>);
   for (const child of children) {
-    const found = firstAttrRef(child, seen);
+    const found = findAnchor(child, seen);
     if (found) return found;
   }
   return undefined;
 }
 
+/** Derive the lexicon an anchor belongs to: an AttrRef borrows its (deref'd)
+ * parent's `.lexicon`; a directly-referenced Declarable reports its own. */
+function anchorLexicon(anchor: Anchor | undefined): string {
+  if (!anchor) return "unknown";
+  if (anchor.kind === "declarable") return anchor.entity.lexicon;
+  const parent = anchor.ref.parent.deref();
+  return parent && typeof (parent as Record<string, unknown>).lexicon === "string"
+    ? ((parent as Record<string, unknown>).lexicon as string)
+    : "unknown";
+}
+
 /**
  * Type guard for StackOutput.
  */
@@ -106,16 +128,15 @@ export function stackOutput(
     );
   }
   // Derive lexicon from the referenced entity — for a bare AttrRef, its parent;
-  // for an intrinsic (Join etc.), the first AttrRef nested inside it. A
-  // foreign-copy AttrRef failing raw `instanceof` here would fall to
-  // `firstAttrRef`, which (before its own #1137 fix) would also miss it —
+  // for an intrinsic (Join etc.), the first AttrRef or directly-referenced
+  // Declarable nested inside it (chant #1152: `Ref(param)`/`Ref(resource)`
+  // wrap the entity itself, not one of its attributes). A foreign-copy
+  // AttrRef/Declarable failing raw `instanceof` here would fall to
+  // `findAnchor`, which (before its own #1137 fix) would also miss it —
   // silently anchoring on nothing and recording `lexicon: "unknown"`.
-  const anchor = typeof ref === "string" ? undefined : isAttrRefLike(ref) ? ref : firstAttrRef(ref);
-  const parent = anchor?.parent.deref();
-  const derived = parent && typeof (parent as Record<string, unknown>).lexicon === "string"
-    ? (parent as Record<string, unknown>).lexicon as string
-    : "unknown";
-  const lexicon = options?.lexicon ?? derived;
+  const anchor: Anchor | undefined =
+    typeof ref === "string" ? undefined : isAttrRefLike(ref) ? { kind: "attrRef", ref } : findAnchor(ref);
+  const lexicon = options?.lexicon ?? anchorLexicon(anchor);
 
   const output: StackOutput = {
     [STACK_OUTPUT_MARKER]: true,