@intentius/chant 0.29.0 → 0.31.0

package/src/deep-observation.test.ts

@@ -0,0 +1,234 @@
+import { describe, test, expect } from "vitest";
+import {
+  MASKED,
+  UNRESOLVED,
+  deepObservation,
+  deepPathSet,
+  deepValueEqual,
+  flattenDeepProperties,
+  isDeepObservationResult,
+  isSensitiveKey,
+  normalizeDeepObservation,
+  normalizeDeepProperties,
+  type DeepNormalizationHooks,
+} from "./deep-observation";
+
+describe("the deep observation envelope", () => {
+  test("is discriminated by its version literal", () => {
+    expect(isDeepObservationResult(deepObservation({}))).toBe(true);
+    expect(isDeepObservationResult({ resources: {} })).toBe(false);
+    expect(isDeepObservationResult({ observation: "v1", resources: {} })).toBe(false);
+    expect(isDeepObservationResult(null)).toBe(false);
+  });
+
+  test("omits an empty unobserved map rather than emitting one", () => {
+    expect(deepObservation({}, {})).toEqual({ deepObservation: "v1", resources: {} });
+  });
+
+  test("normalizing undefined yields two empty maps", () => {
+    expect(normalizeDeepObservation(undefined)).toEqual({ resources: {}, unobserved: {} });
+  });
+
+  test("carries the tri-state contract's unobserved entries verbatim", () => {
+    const result = deepObservation(
+      { a: { type: "T", properties: {} } },
+      { b: { type: "T", reason: "unsupported-kind", detail: "no reader" } },
+    );
+    expect(normalizeDeepObservation(result).unobserved.b.reason).toBe("unsupported-kind");
+  });
+});
+
+describe("normalizeDeepProperties", () => {
+  test("canonicalizes object key order", () => {
+    const out = normalizeDeepProperties(
+      { zeta: 1, alpha: 2, mid: { z: 1, a: 2 } },
+      { entityType: "T", side: "live" },
+    );
+    expect(Object.keys(out)).toEqual(["alpha", "mid", "zeta"]);
+    expect(Object.keys(out.mid as Record<string, unknown>)).toEqual(["a", "z"]);
+  });
+
+  test("leaves array order alone with no ordering hook", () => {
+    const out = normalizeDeepProperties({ Tags: [{ Key: "z" }, { Key: "a" }] }, { entityType: "T", side: "live" });
+    expect(out.Tags).toEqual([{ Key: "z" }, { Key: "a" }]);
+  });
+
+  test("orders an array when the hook keys every element", () => {
+    const hooks: DeepNormalizationHooks = {
+      orderKey: (el) => (el.pattern === "Tags" ? String((el.element as { Key: string }).Key) : undefined),
+    };
+    const out = normalizeDeepProperties(
+      { Tags: [{ Key: "z" }, { Key: "a" }], Steps: ["second", "first"] },
+      { entityType: "T", side: "live", hooks },
+    );
+    expect(out.Tags).toEqual([{ Key: "a" }, { Key: "z" }]);
+    // No key for Steps — order is left alone, because list order is often
+    // semantic and a guess here is worse than a stable false negative.
+    expect(out.Steps).toEqual(["second", "first"]);
+  });
+
+  test("a partially-keyed array keeps its order", () => {
+    const hooks: DeepNormalizationHooks = {
+      orderKey: (el) => (el.index === 0 ? "a" : undefined),
+    };
+    const out = normalizeDeepProperties({ List: ["x", "y"] }, { entityType: "T", side: "live", hooks });
+    expect(out.List).toEqual(["x", "y"]);
+  });
+
+  test("prunes by hook, and prunes the whole subtree", () => {
+    const hooks: DeepNormalizationHooks = { prune: (n) => n.pattern === "Status" };
+    const out = normalizeDeepProperties(
+      { Status: { Phase: "Ready", Conditions: [1, 2] }, Name: "n" },
+      { entityType: "T", side: "live", hooks },
+    );
+    expect(out).toEqual({ Name: "n" });
+  });
+
+  test("hooks see an index-erased pattern alongside the exact path", () => {
+    const seen: Array<[string, string]> = [];
+    const hooks: DeepNormalizationHooks = {
+      prune: (n) => {
+        seen.push([n.path, n.pattern]);
+        return false;
+      },
+    };
+    normalizeDeepProperties({ Tags: [{ Key: "a" }] }, { entityType: "T", side: "live", hooks });
+    expect(seen).toContainEqual(["Tags[0].Key", "Tags[].Key"]);
+  });
+
+  test("counterpart is `unknown` for a one-sided pass and resolved when paths are supplied", () => {
+    const seen: Record<string, string> = {};
+    const hooks: DeepNormalizationHooks = {
+      prune: (n) => {
+        seen[n.pattern] = n.counterpart;
+        return false;
+      },
+    };
+    normalizeDeepProperties({ A: 1, B: 2 }, { entityType: "T", side: "live", hooks });
+    expect(seen).toEqual({ A: "unknown", B: "unknown" });
+
+    normalizeDeepProperties(
+      { A: 1, B: 2 },
+      { entityType: "T", side: "live", hooks, counterpartPaths: deepPathSet({ A: 9 }) },
+    );
+    expect(seen).toEqual({ A: "present", B: "absent" });
+  });
+
+  test("an array element counts as declared when the pattern is declared at any index", () => {
+    const seen: Record<string, string> = {};
+    const hooks: DeepNormalizationHooks = {
+      prune: (n) => {
+        seen[n.path] = n.counterpart;
+        return false;
+      },
+    };
+    normalizeDeepProperties(
+      { Tags: [{ Key: "b" }, { Key: "a" }] },
+      { entityType: "T", side: "live", hooks, counterpartPaths: deepPathSet({ Tags: [{ Key: "a" }] }) },
+    );
+    // Source declares one tag; both live tags match the `Tags[].Key` pattern.
+    expect(seen["Tags[1].Key"]).toBe("present");
+  });
+
+  test("masks secret-bearing property names without recursing into them", () => {
+    const out = normalizeDeepProperties(
+      { MasterUserPassword: "hunter2", Nested: { ClientSecret: { a: 1 } }, Tags: [{ Key: "k", Value: "v" }] },
+      { entityType: "T", side: "live" },
+    );
+    expect(out.MasterUserPassword).toBe(MASKED);
+    expect((out.Nested as Record<string, unknown>).ClientSecret).toBe(MASKED);
+    // `Key`/`Value` are not secrets — masking them would be its own drift signal.
+    expect(out.Tags).toEqual([{ Key: "k", Value: "v" }]);
+  });
+
+  test("collapses non-JSON values (an unevaluated intrinsic) to the unresolved sentinel", () => {
+    class SubIntrinsic {
+      constructor(readonly template: string) {}
+    }
+    const out = normalizeDeepProperties(
+      { BucketName: new SubIntrinsic("${AWS::StackName}-data"), Plain: "x" },
+      { entityType: "T", side: "declared" },
+    );
+    expect(out.BucketName).toBe(UNRESOLVED);
+    expect(out.Plain).toBe("x");
+  });
+
+  test("drops undefined but keeps null", () => {
+    const out = normalizeDeepProperties({ a: undefined, b: null }, { entityType: "T", side: "live" });
+    expect("a" in out).toBe(false);
+    expect(out.b).toBeNull();
+  });
+});
+
+describe("isSensitiveKey", () => {
+  test("matches the secret-bearing names and nothing broader", () => {
+    for (const k of ["Password", "clientSecret", "AuthToken", "PrivateKey", "credentials", "ConnectionString"]) {
+      expect(isSensitiveKey(k), k).toBe(true);
+    }
+    for (const k of ["Key", "KeyName", "KmsKeyId", "Value", "Name"]) {
+      expect(isSensitiveKey(k), k).toBe(false);
+    }
+  });
+});
+
+describe("flattenDeepProperties", () => {
+  test("flattens to leaf paths, keeping empty containers as values", () => {
+    const flat = flattenDeepProperties({
+      A: { B: 1 },
+      List: [{ C: "x" }, "y"],
+      EmptyObj: {},
+      EmptyArr: [],
+    });
+    expect(Object.fromEntries(flat)).toEqual({
+      "A.B": 1,
+      "List[0].C": "x",
+      "List[1]": "y",
+      EmptyObj: {},
+      EmptyArr: [],
+    });
+  });
+});
+
+describe("flattenDeepProperties with an ordering hook", () => {
+  const hooks: DeepNormalizationHooks = {
+    orderKey: (el) => (el.pattern === "Tags" ? String((el.element as { Key: string }).Key) : undefined),
+  };
+  const opts = { entityType: "T", side: "live" as const, hooks };
+
+  test("addresses a keyable array by key, so an inserted element shifts nothing", () => {
+    const flat = flattenDeepProperties({ Tags: [{ Key: "env", Value: "prod" }] }, opts);
+    expect([...flat.keys()].sort()).toEqual(["Tags[#env].Key", "Tags[#env].Value"]);
+
+    const withExtra = flattenDeepProperties(
+      { Tags: [{ Key: "cost", Value: "x" }, { Key: "env", Value: "prod" }] },
+      opts,
+    );
+    expect(withExtra.get("Tags[#env].Value")).toBe("prod");
+  });
+
+  test("falls back to positional paths when keys collide", () => {
+    const flat = flattenDeepProperties({ Tags: [{ Key: "env", Value: "a" }, { Key: "env", Value: "b" }] }, opts);
+    expect([...flat.keys()]).toContain("Tags[0].Value");
+  });
+
+  test("falls back to positional paths for an array the hook cannot key", () => {
+    const flat = flattenDeepProperties({ Steps: ["a", "b"] }, opts);
+    expect([...flat.keys()]).toEqual(["Steps[0]", "Steps[1]"]);
+  });
+});
+
+describe("deepPathSet", () => {
+  test("records both the exact path and the index-erased pattern", () => {
+    const set = deepPathSet({ Tags: [{ Key: "a" }] });
+    expect([...set].sort()).toEqual(["Tags", "Tags[0]", "Tags[0].Key", "Tags[]", "Tags[].Key"]);
+  });
+});
+
+describe("deepValueEqual", () => {
+  test("compares structurally", () => {
+    expect(deepValueEqual({ a: [1, 2] }, { a: [1, 2] })).toBe(true);
+    expect(deepValueEqual({ a: [1, 2] }, { a: [2, 1] })).toBe(false);
+    expect(deepValueEqual(null, undefined)).toBe(false);
+    expect(deepValueEqual(1, 1)).toBe(true);
+  });
+});