@intentius/chant 0.28.0 → 0.30.0

package/src/cli/main.test.ts

@@ -95,6 +95,12 @@ describe("parseArgs", () => {
     expect(result.down).toBe(true);
   });
 
+  test("parses graph --components --format ir --projection <lexicon>", () => {
+    const result = parseArgs(["graph", "--components", "--format", "ir", "--projection", "gitlab"]);
+    expect(result.components).toBe(true);
+    expect(result.projection).toBe("gitlab");
+  });
+
   test("combines multiple options", () => {
     const result = parseArgs([
       "build",

package/src/cli/main.ts

@@ -64,6 +64,7 @@ const BOOLEAN_FLAGS = new Set([
   "--json",
   "--progress-json",
   "--update-snapshot",
+  "--update-baseline",
   "--run-examples",
   "--check",
   "--bump",
@@ -269,6 +270,8 @@ export function parseArgs(args: string[]): ParsedArgs {
       result.progressJson = true;
     } else if (arg === "--update-snapshot") {
       result.updateSnapshot = true;
+    } else if (arg === "--update-baseline") {
+      result.updateBaseline = true;
     } else if (arg === "--run-examples") {
       result.runExamples = true;
     } else if (arg === "--pinned-digest") {
@@ -312,6 +315,8 @@ export function parseArgs(args: string[]): ParsedArgs {
       (result.param ??= []).push(args[++i]);
     } else if (arg === "--params-file") {
       result.paramsFile = args[++i];
+    } else if (arg === "--projection") {
+      result.projection = args[++i];
     } else if (arg.startsWith("--")) {
       // chant #1127 — every recognized flag is matched above; anything left
       // starting with `--` is unrecognized, whether it arrived bare
@@ -421,12 +426,19 @@ Ops:
                         --layout-engine graphviz to use dot instead;
                         --detail 0..3: stacks|composites|declarables|attributes;
                         --lens lexicon:<n>|stack:<n>|blast:<node> (--up/--down))
+                        --components --format ir --projection gitlab|github|forgejo:
+                        add the CI/pipeline projection (stages/jobs/needs) to
+                        the component-graph IR, from the same generator
+                        'build --components --generate' uses (#989)
 
 Lifecycle (alias: lc):
   lifecycle snapshot <env>  Query API, save metadata to orphan branch
   lifecycle show <env>      Show latest lifecycle snapshot
   lifecycle diff <env>      Compare current build against last snapshot
                             --live: query cloud now and detect drift
+                            (lexicons with a deep reader also report
+                            property-level drift; --update-baseline records
+                            what it reports as accepted so it stops alerting)
   lifecycle plan <env>      Typed change set (create/update/delete/adopt) vs live
   lifecycle affected        Stacks a change affects (--base <ref> [--include-dependents])
                             --json: emit the ChangeSet as JSON

package/src/cli/registry.ts

@@ -118,6 +118,14 @@ export interface ParsedArgs {
   theme?: string;
   /** `chant dev surface-diff --update-snapshot` — write the fresh snapshot as the new baseline */
   updateSnapshot?: boolean;
+  /**
+   * `chant lifecycle diff <env> --live --update-baseline` (#1014) — record every
+   * property-level deviation this run reports as *accepted*, so it stops
+   * re-alerting. Value-bound: a later change to the accepted value is drift
+   * again. Writes `<env>/observation-baseline.json` on the chant/lifecycle
+   * orphan branch; never touches the cloud.
+   */
+  updateBaseline?: boolean;
   /** `chant dev surface-diff --run-examples` — also run the example build harness */
   runExamples?: boolean;
   /** `chant dev surface-diff --pinned-digest <file>` — path to SHA-256 digest file for supply-chain verification */
@@ -154,6 +162,12 @@ export interface ParsedArgs {
   param?: string[];
   /** `chant build --params-file <path>` (#1064) — a JSON file of `{ "name": value }` build-time parameter values. Second precedence, after `--param`. */
   paramsFile?: string;
+  /** `chant graph --components --format ir --projection <lexicon>` (#989) — add
+   * the CI/pipeline projection (stages/jobs/`needs`) to the component-graph IR,
+   * synthesized by `<lexicon>`'s `generateComponentPipeline` (gitlab, github,
+   * forgejo today) — the same generator `chant build --components --generate
+   * <lexicon>` uses, reused rather than re-derived. */
+  projection?: string;
 }
 
 /**

package/src/config.test.ts

@@ -5,6 +5,9 @@ import {
   resolveAutoReleaseDisabled,
   resolveFoldEnabled,
   resolveSbomFormat,
+  environmentName,
+  environmentNames,
+  environmentEndpoint,
 } from "./config";
 import { writeFileSync, mkdirSync, rmSync } from "fs";
 import { join } from "path";
@@ -134,6 +137,78 @@ describe("loadChantConfig", () => {
   });
 });
 
+// #1166 — `environments` accepts either a bare name (unchanged) or
+// `{ name, endpoint }`, so a declared environment can be self-sufficient for
+// `--live` reads without an ambient AWS_ENDPOINT_URL export.
+describe("environments (#1166 — string or { name, endpoint })", () => {
+  test("bare string environments load exactly as before", async () => {
+    writeFileSync(
+      join(TEST_DIR, "chant.config.json"),
+      JSON.stringify({ environments: ["dev", "prod"] }),
+    );
+
+    const result = await loadChantConfig(TEST_DIR);
+    expect(result.config.environments).toEqual(["dev", "prod"]);
+  });
+
+  test("an object entry with a declared endpoint loads alongside bare strings", async () => {
+    writeFileSync(
+      join(TEST_DIR, "chant.config.json"),
+      JSON.stringify({
+        environments: ["prod", { name: "floci", endpoint: "http://localhost:4566" }],
+      }),
+    );
+
+    const result = await loadChantConfig(TEST_DIR);
+    expect(result.config.environments).toEqual([
+      "prod",
+      { name: "floci", endpoint: "http://localhost:4566" },
+    ]);
+  });
+
+  test("an object entry with no endpoint is legal (name-only, same as a bare string)", async () => {
+    writeFileSync(
+      join(TEST_DIR, "chant.config.json"),
+      JSON.stringify({ environments: [{ name: "staging" }] }),
+    );
+
+    const result = await loadChantConfig(TEST_DIR);
+    expect(result.config.environments).toEqual([{ name: "staging" }]);
+  });
+
+  test("rejects an environments entry that is neither a string nor { name }", async () => {
+    writeFileSync(
+      join(TEST_DIR, "chant.config.json"),
+      JSON.stringify({ environments: [{ endpoint: "http://localhost:4566" }] }),
+    );
+
+    await expect(loadChantConfig(TEST_DIR)).rejects.toThrow(/environments/);
+  });
+});
+
+describe("environmentName / environmentNames / environmentEndpoint (#1166)", () => {
+  test("environmentName reduces either form to its name", () => {
+    expect(environmentName("prod")).toBe("prod");
+    expect(environmentName({ name: "floci", endpoint: "http://localhost:4566" })).toBe("floci");
+    expect(environmentName({ name: "staging" })).toBe("staging");
+  });
+
+  test("environmentNames maps a mixed list, and passes undefined through", () => {
+    expect(environmentNames(["prod", { name: "floci", endpoint: "http://x" }])).toEqual(["prod", "floci"]);
+    expect(environmentNames(undefined)).toBeUndefined();
+    expect(environmentNames([])).toEqual([]);
+  });
+
+  test("environmentEndpoint resolves the declared endpoint, or undefined otherwise", () => {
+    const environments = ["prod", { name: "floci", endpoint: "http://localhost:4566" }, { name: "staging" }];
+    expect(environmentEndpoint(environments, "floci")).toBe("http://localhost:4566");
+    expect(environmentEndpoint(environments, "prod")).toBeUndefined(); // bare string, no endpoint
+    expect(environmentEndpoint(environments, "staging")).toBeUndefined(); // object, but no endpoint set
+    expect(environmentEndpoint(environments, "unknown")).toBeUndefined(); // not declared at all
+    expect(environmentEndpoint(undefined, "floci")).toBeUndefined();
+  });
+});
+
 describe("resolveFoldEnabled (#1134 — fold is the default build path)", () => {
   test("default (no flag, no config) → fold ON", () => {
     expect(resolveFoldEnabled({})).toBe(true);

package/src/config.ts

@@ -10,13 +10,61 @@ import type { BuildParamsConfig } from "./build-params";
 import { findProjectConfig } from "./project-root";
 import { evaluateProjectConfig } from "./config-sandbox";
 
+/**
+ * One project-declared environment (chant #1166). Historically always a bare
+ * name (`"floci"`); an entry can now instead carry the endpoint that
+ * environment's `--live` reads should target (`{ name: "floci", endpoint:
+ * "http://localhost:4566" }`), so a project pointed at a local emulator is
+ * self-sufficient — no ambient `AWS_ENDPOINT_URL` export required to avoid
+ * silently querying real AWS. See {@link environmentName}, {@link
+ * environmentNames}, {@link environmentEndpoint} below, and
+ * `./live-endpoint.ts`'s `applyLiveEndpoint`, the CLI-side consumer.
+ */
+export type EnvironmentDeclaration = string | { name: string; endpoint?: string };
+
+/** The declared name of one `environments` entry, whichever form it takes. */
+export function environmentName(entry: EnvironmentDeclaration): string {
+  return typeof entry === "string" ? entry : entry.name;
+}
+
+/**
+ * Every declared environment's name, in `environments` order. `undefined` in,
+ * `undefined` out — mirrors the field itself being optional, so a caller that
+ * already writes `config.environments?.something` can keep doing so:
+ * `environmentNames(config.environments)?.includes(name)`.
+ */
+export function environmentNames(environments: EnvironmentDeclaration[] | undefined): string[] | undefined {
+  return environments?.map(environmentName);
+}
+
+/**
+ * The endpoint `name` declares (chant #1166) — `undefined` for a bare-string
+ * entry, an entry with no `endpoint` set, or a name this project doesn't
+ * declare at all. `./live-endpoint.ts`'s `applyLiveEndpoint` is the consumer:
+ * it injects this into the ambient env var each observing lexicon's CLI
+ * shell-out reads (e.g. `AWS_ENDPOINT_URL`), unless that var is already set —
+ * ambient always wins.
+ */
+export function environmentEndpoint(environments: EnvironmentDeclaration[] | undefined, name: string): string | undefined {
+  const found = environments?.find((e) => environmentName(e) === name);
+  return found && typeof found !== "string" ? found.endpoint : undefined;
+}
+
 /**
  * Zod schema for ChantConfig validation.
  */
+const EnvironmentEntrySchema = z.union([
+  z.string().min(1),
+  z.object({
+    name: z.string().min(1),
+    endpoint: z.string().min(1).optional(),
+  }),
+]);
+
 export const ChantConfigSchema = z.object({
   lexicons: z.array(z.string().min(1)).optional(),
   capabilities: z.array(z.string().min(1)).optional(),
-  environments: z.array(z.string().min(1)).optional(),
+  environments: z.array(EnvironmentEntrySchema).optional(),
   sourceDir: z.string().min(1).optional(),
   lint: z.record(z.string(), z.unknown()).optional(),
   ownership: z.object({
@@ -87,8 +135,18 @@ export interface ChantConfig {
    */
   capabilities?: string[];
 
-  /** Environment names (e.g. ["staging", "prod"]) */
-  environments?: string[];
+  /**
+   * Declared environments (e.g. `["staging", "prod"]`). An entry is either a
+   * bare name (unchanged since always) or `{ name, endpoint }` (#1166) when
+   * that environment's `--live` reads should target a specific endpoint —
+   * a local emulator like Floci (`{ name: "floci", endpoint:
+   * "http://localhost:4566" }`) chief among them. See {@link
+   * environmentEndpoint} and `./live-endpoint.ts`'s `applyLiveEndpoint`, which
+   * injects the declared endpoint into the ambient env var each observing
+   * lexicon's CLI shell-out reads (e.g. `AWS_ENDPOINT_URL`) — unless that var
+   * is already set, in which case the ambient value always wins.
+   */
+  environments?: EnvironmentDeclaration[];
 
   /**
    * Directory (relative to the project root) that holds the chant infrastructure

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);
+  });
+});