@intentius/chant 0.18.30 → 0.18.31

package/dist/cli/handlers/components.d.ts

@@ -1,4 +1,5 @@
 import type { CommandContext } from "../registry.js";
+import type { Phase } from "../../components/component.js";
 /**
  * chant components release <env> --component <name> --digest <sha256:...>
  *   [--git-sha <sha>] [--run-id <id>] [--actor <name>]
@@ -17,6 +18,32 @@ import type { CommandContext } from "../registry.js";
  * timestamp from the environment/CLI at record time."
  */
 export declare function runComponentsReleaseRecord(ctx: CommandContext): Promise<number>;
+/**
+ * chant components status [env] [--live] [--json] [--compare-to <env>]
+ *
+ * Answers "what's built" and "what's deployed where," joined by digest.
+ * Without `--live`, reports the release ledger alone (recorded vs unrecorded
+ * is meaningless without live evidence, so every recorded row reports
+ * `unknown` reconciliation — still useful as a pure ledger read). With
+ * `--live`, joins against `lifecycle diff --live` + ownership (reusing
+ * `buildChangeSet`, the same classification `lifecycle plan` already
+ * trusts) to flag unrecorded deploys and drift.
+ *
+ * Omitting `<env>` reports every environment that has release records.
+ * `--compare-to <env>` answers the single-query cross-environment question
+ * the epic names explicitly: "which build is in `<env>`, and is it the one
+ * tested in `<compare-to>`."
+ */
+/** Every distinct `cfn-deploy` stack name a component's deploy phases target. A
+ * step may itself be a nested `Phase`, so walk recursively; a resolved component
+ * carries the stack as a concrete string.
+ *
+ * Exported for `chant graph --live` (../handlers/graph.ts's `runGraphLive`,
+ * #57): the same per-component stack resolution this file uses for `chant
+ * components status --live` is also how the live graph learns which stacks to
+ * observe on a multi-stack, per-component project (`describeResources`'s
+ * single-stack-named-after-the-environment convention never matches one). */
+export declare function cfnDeployStacks(deploy: Phase[]): string[];
 export declare function runComponentsStatus(ctx: CommandContext): Promise<number>;
 /** Fallback for `chant components` with no/unknown subcommand. */
 export declare function runComponentsUnknown(ctx: CommandContext): Promise<number>;

package/dist/cli/handlers/components.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"components.d.ts","sourceRoot":"","sources":["../../../src/cli/handlers/components.ts"],"names":[],"mappings":"AA6CA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAIlD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,0BAA0B,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAuErF;AAqHD,wBAAsB,mBAAmB,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAuN9E;AAED,kEAAkE;AAClE,wBAAsB,oBAAoB,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAM/E"}
+{"version":3,"file":"components.d.ts","sourceRoot":"","sources":["../../../src/cli/handlers/components.ts"],"names":[],"mappings":"AA6CA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAElD,OAAO,KAAK,EAAE,KAAK,EAAa,MAAM,4BAA4B,CAAC;AAEnE;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,0BAA0B,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAuErF;AAyCD;;;;;;;;;;;;;;;GAeG;AACH;;;;;;;;6EAQ6E;AAC7E,wBAAgB,eAAe,CAAC,MAAM,EAAE,KAAK,EAAE,GAAG,MAAM,EAAE,CAiBzD;AAwCD,wBAAsB,mBAAmB,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAuN9E;AAED,kEAAkE;AAClE,wBAAsB,oBAAoB,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAM/E"}

package/dist/cli/handlers/graph.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"graph.d.ts","sourceRoot":"","sources":["../../../src/cli/handlers/graph.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAGlD;;;;;;;;;GASG;AACH,wBAAsB,QAAQ,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAmBnE"}
+{"version":3,"file":"graph.d.ts","sourceRoot":"","sources":["../../../src/cli/handlers/graph.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAKlD;;;;;;;;;GASG;AACH,wBAAsB,QAAQ,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAmBnE"}

package/dist/lifecycle/observe.d.ts

@@ -24,8 +24,21 @@ export interface ObserveResult {
  * 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.
+ *
+ * `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
+ * single-stack convention (`lexicons/aws/src/plugin.ts`'s `describeResources`,
+ * absent an explicit `stack`) queries a stack that simply doesn't exist there,
+ * so the single-call path always observes zero nodes. When `stacks` is
+ * present and non-empty, each observing plugin's `describeResources` is
+ * called once per stack (same `environment`/`entities`/`entityNames`, only
+ * `stack` varies) and the returned resource maps are unioned — a resource
+ * appears under whichever stack contains its logical id. When `stacks` is
+ * absent or empty, behavior is exactly the single call of before (no `stack`
+ * key at all), so a single-stack project is unaffected.
  */
 export declare function observeResources(environment: string, plugins: ObservationLexicon[], buildResult: BuildResult, opts?: {
     owned?: boolean;
+    stacks?: string[];
 }): Promise<ObserveResult>;
 //# sourceMappingURL=observe.d.ts.map

package/dist/lifecycle/observe.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"observe.d.ts","sourceRoot":"","sources":["../../src/lifecycle/observe.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,KAAK,EAAE,kBAAkB,EAAoB,MAAM,YAAY,CAAC;AACvE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAE5C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAEnD,MAAM,WAAW,aAAa;IAC5B,YAAY,EAAE,eAAe,EAAE,CAAC;IAChC,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED;;;;;;;GAOG;AACH,wBAAsB,gBAAgB,CACpC,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,kBAAkB,EAAE,EAC7B,WAAW,EAAE,WAAW,EACxB,IAAI,CAAC,EAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE,GACzB,OAAO,CAAC,aAAa,CAAC,CA+CxB"}
+{"version":3,"file":"observe.d.ts","sourceRoot":"","sources":["../../src/lifecycle/observe.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,KAAK,EAAE,kBAAkB,EAAoB,MAAM,YAAY,CAAC;AACvE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAE5C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAEnD,MAAM,WAAW,aAAa;IAC5B,YAAY,EAAE,eAAe,EAAE,CAAC;IAChC,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,gBAAgB,CACpC,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,kBAAkB,EAAE,EAC7B,WAAW,EAAE,WAAW,EACxB,IAAI,CAAC,EAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,EAAE,CAAA;CAAE,GAC5C,OAAO,CAAC,aAAa,CAAC,CAgExB"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant",
-  "version": "0.18.30",
+  "version": "0.18.31",
   "description": "Declarative infrastructure-as-code toolkit \u2014 TypeScript on Node.js",
   "license": "Apache-2.0",
   "homepage": "https://intentius.io/chant",

package/src/cli/handlers/components.ts

@@ -194,8 +194,14 @@ interface StatusJsonRow {
  */
 /** Every distinct `cfn-deploy` stack name a component's deploy phases target. A
  * step may itself be a nested `Phase`, so walk recursively; a resolved component
- * carries the stack as a concrete string. */
-function cfnDeployStacks(deploy: Phase[]): string[] {
+ * carries the stack as a concrete string.
+ *
+ * Exported for `chant graph --live` (../handlers/graph.ts's `runGraphLive`,
+ * #57): the same per-component stack resolution this file uses for `chant
+ * components status --live` is also how the live graph learns which stacks to
+ * observe on a multi-stack, per-component project (`describeResources`'s
+ * single-stack-named-after-the-environment convention never matches one). */
+export function cfnDeployStacks(deploy: Phase[]): string[] {
   const stacks = new Set<string>();
   const walkSteps = (steps: Phase["steps"]): void => {
     for (const step of steps) {

package/src/cli/handlers/graph.test.ts

@@ -44,6 +44,14 @@ const observeMock = vi.fn();
 vi.mock("../../lifecycle/observe", () => ({
   observeResources: (...a: unknown[]) => observeMock(...a),
 }));
+// `runGraphLive` resolves each component's `cfn-deploy` stack(s) (#57) so a
+// multi-stack, per-component project observes the right stacks; default to
+// "no components" (empty map, no errors) so the existing single-stack --live
+// test is unaffected unless a test opts into a component layout below.
+const discoverComponentsMock = vi.fn();
+vi.mock("../../components/discover", () => ({
+  discoverComponents: (...a: unknown[]) => discoverComponentsMock(...a),
+}));
 vi.mock("../../config", () => ({
   loadChantConfig: () => Promise.resolve({ config: {} }),
 }));
@@ -93,6 +101,12 @@ describe("runGraph", () => {
     lintMock.mockReset();
     layoutMock.mockReset();
     componentGraphMock.mockReset();
+    discoverComponentsMock.mockReset();
+    // Default: no components — the single-stack --live path most tests exercise.
+    discoverComponentsMock.mockResolvedValue({ components: new Map(), sourceFiles: [], errors: [] });
+    observeMock.mockReset();
+    loadPluginsMock.mockReset();
+    resolveLexMock.mockReset();
   });
 
   describe("Op graph (default)", () => {
@@ -326,5 +340,83 @@ describe("runGraph", () => {
       expect(out).not.toContain("No lexicons implement describeResources");
       expect(out).toContain("web-vpc");
     });
+
+    // Regression for #57: a single-stack project (no `*.component.ts` files —
+    // discoverComponents returns an empty map) must observe exactly as before,
+    // no `stacks` collected.
+    test("single-stack project (no components): observeResources gets an empty stacks list", async () => {
+      resolveLexMock.mockResolvedValue(["aws"]);
+      loadPluginsMock.mockResolvedValue([
+        { name: "aws", serializer: {}, describeResources: () => Promise.resolve({}) },
+      ]);
+      observeMock.mockResolvedValue({ observations: [], errors: [] });
+      const exit = await runGraph({ args: makeArgs({ format: "ir", live: true, env: "prod" }), plugins: [], serializers: [] });
+      expect(exit).toBe(0);
+      expect(observeMock).toHaveBeenCalledWith("prod", expect.anything(), expect.anything(), {
+        owned: true,
+        stacks: [],
+      });
+    });
+
+    // The bug this branch fixes (#57): a multi-stack, per-component project
+    // (loomster/Floci) has no stack literally named after the environment, so
+    // the live graph must resolve each component's own `cfn-deploy` stack(s)
+    // and pass them through to `observeResources` for the per-stack union.
+    test("multi-stack component project: resolves each component's cfn-deploy stack(s) and passes them to observeResources", async () => {
+      resolveLexMock.mockResolvedValue(["aws"]);
+      loadPluginsMock.mockResolvedValue([
+        { name: "aws", serializer: {}, describeResources: () => Promise.resolve({}) },
+      ]);
+      discoverComponentsMock.mockResolvedValue({
+        errors: [],
+        sourceFiles: [],
+        components: new Map([
+          ["loom-db", { component: { name: "loom-db", dependsOn: [], deploy: [
+            { phase: "deploy", steps: [{ kind: "cfn-deploy", stack: "loom-local-a-loom-db" }] },
+          ] }, exportName: "loomDb", filePath: "components/loom-db.component.ts" }],
+          // Multi-stack component: two cfn-deploy steps, nested under a sub-phase.
+          ["loom-backend", { component: { name: "loom-backend", dependsOn: ["loom-db"], deploy: [
+            { phase: "deploy", steps: [
+              { phase: "nested", steps: [{ kind: "cfn-deploy", stack: "loom-local-a-loom-backend" }] },
+              { kind: "cfn-deploy", stack: "loom-local-a-loom-backend-jobs" },
+            ] },
+          ] }, exportName: "loomBackend", filePath: "components/loom-backend.component.ts" }],
+          // Non-aws / no cfn-deploy component: contributes no stacks.
+          ["loom-frontend", { component: { name: "loom-frontend", dependsOn: [], deploy: [
+            { phase: "deploy", steps: [{ kind: "s3-sync" }] },
+          ] }, exportName: "loomFrontend", filePath: "components/loom-frontend.component.ts" }],
+        ]),
+      });
+      observeMock.mockResolvedValue({
+        observations: [{ lexicon: "aws", resources: { "loom-db": { type: "AWS::RDS::DBInstance", status: "OK" } } }],
+        errors: [],
+      });
+      const exit = await runGraph({ args: makeArgs({ format: "ir", live: true, env: "local" }), plugins: [], serializers: [] });
+      expect(exit).toBe(0);
+      expect(observeMock).toHaveBeenCalledTimes(1);
+      const [, , , opts] = observeMock.mock.calls[0];
+      expect((opts as { stacks: string[] }).stacks.sort()).toEqual([
+        "loom-local-a-loom-backend",
+        "loom-local-a-loom-backend-jobs",
+        "loom-local-a-loom-db",
+      ]);
+      expect((opts as { owned: boolean }).owned).toBe(true);
+    });
+
+    test("component discovery errors: falls back to the single-stack path with a warning", async () => {
+      resolveLexMock.mockResolvedValue(["aws"]);
+      loadPluginsMock.mockResolvedValue([
+        { name: "aws", serializer: {}, describeResources: () => Promise.resolve({}) },
+      ]);
+      discoverComponentsMock.mockResolvedValue({ errors: [{ message: "bad component" }], sourceFiles: [], components: new Map() });
+      observeMock.mockResolvedValue({ observations: [], errors: [] });
+      const exit = await runGraph({ args: makeArgs({ format: "ir", live: true, env: "prod" }), plugins: [], serializers: [] });
+      expect(exit).toBe(0);
+      expect(observeMock).toHaveBeenCalledWith("prod", expect.anything(), expect.anything(), {
+        owned: true,
+        stacks: [],
+      });
+      expect(stderrBuf.join("\n")).toMatch(/component discovery failed/i);
+    });
   });
 });

package/src/cli/handlers/graph.ts

@@ -17,6 +17,8 @@ import { readFileSync } from "node:fs";
 import { formatError, formatWarning, formatBold } from "../format";
 import type { CommandContext } from "../registry";
 import { computeComponentGraph } from "../../components/cli-support";
+import { discoverComponents } from "../../components/discover";
+import { cfnDeployStacks } from "./components";
 
 /**
  * `chant graph` — the Op dependency graph by default; `--stacks` renders the
@@ -96,7 +98,31 @@ async function runGraphLive(
     return 1;
   }
 
-  const { observations, errors } = await observeResources(environment, observing, buildResult, { owned: true });
+  // Multi-stack, per-component projects (loomster/Floci, #57): AWS's
+  // single-stack convention (`describeResources` defaults to a stack named
+  // after the environment, lexicons/aws/src/plugin.ts) never matches a
+  // per-component layout (e.g. `loom-local-a-<component>`), so the plain
+  // single call always observes zero nodes. Resolve every discovered
+  // component's `cfn-deploy` stack(s) — the same walk `chant components
+  // status --live` uses (`cfnDeployStacks`, ./components.ts) — and hand them
+  // to `observeResources`, which queries `describeResources` once per stack
+  // and unions the results. A project with no components (or whose discovery
+  // errors) yields no stacks, so `observeResources` falls back to its
+  // original single-stack call — unchanged.
+  const componentsDiscovery = await discoverComponents(resolve(args.src ?? config.sourceDir ?? "."));
+  const stacks = new Set<string>();
+  if (componentsDiscovery.errors.length === 0) {
+    for (const { component } of componentsDiscovery.components.values()) {
+      for (const stack of cfnDeployStacks(component.deploy)) stacks.add(stack);
+    }
+  } else {
+    console.error(formatWarning({ message: "component discovery failed — observing the single-stack convention instead" }));
+  }
+
+  const { observations, errors } = await observeResources(environment, observing, buildResult, {
+    owned: true,
+    stacks: [...stacks],
+  });
   for (const e of errors) console.error(formatWarning({ message: e }));
 
   let ir: GraphIR = buildLiveGraphIr(observations);

package/src/lifecycle/observe.test.ts

@@ -62,4 +62,52 @@ describe("observeResources", () => {
     const { observations } = await observeResources("prod", [empty, noObserve], mockBuild());
     expect(observations).toEqual([]);
   });
+
+  it("with no stacks: calls describeResources exactly once with no `stack` key (unchanged single-stack path)", async () => {
+    const calls: Array<{ stack?: string }> = [];
+    const plugins = [
+      awsPlugin((opts) => {
+        calls.push(opts as { stack?: string });
+        return { "web-vpc": { type: "AWS::EC2::VPC", status: "CREATE_COMPLETE" } };
+      }),
+    ];
+    const { observations } = await observeResources("prod", plugins, mockBuild());
+    expect(calls).toHaveLength(1);
+    expect(calls[0]).not.toHaveProperty("stack");
+    expect(Object.keys(observations[0].resources)).toEqual(["web-vpc"]);
+  });
+
+  it("with stacks: [s1, s2] — calls describeResources once per stack and unions the results", async () => {
+    const calls: Array<string | undefined> = [];
+    const plugins = [
+      awsPlugin((opts) => {
+        const stack = (opts as { stack?: string }).stack;
+        calls.push(stack);
+        // Different resources per stack — the multi-stack, per-component case.
+        const resources: Record<string, ResourceMetadata> =
+          stack === "s1"
+            ? { "db-a": { type: "AWS::RDS::DBInstance", status: "AVAILABLE" } }
+            : { "db-b": { type: "AWS::RDS::DBInstance", status: "AVAILABLE" } };
+        return resources;
+      }),
+    ];
+    const { observations, errors } = await observeResources("prod", plugins, mockBuild(), { stacks: ["s1", "s2"] });
+    expect(calls).toEqual(["s1", "s2"]);
+    expect(errors).toEqual([]);
+    expect(observations).toHaveLength(1);
+    expect(Object.keys(observations[0].resources).sort()).toEqual(["db-a", "db-b"]);
+  });
+
+  it("with an empty stacks array — falls back to the single unstacked call", async () => {
+    const calls: Array<{ stack?: string }> = [];
+    const plugins = [
+      awsPlugin((opts) => {
+        calls.push(opts as { stack?: string });
+        return { "web-vpc": { type: "AWS::EC2::VPC", status: "CREATE_COMPLETE" } };
+      }),
+    ];
+    await observeResources("prod", plugins, mockBuild(), { stacks: [] });
+    expect(calls).toHaveLength(1);
+    expect(calls[0]).not.toHaveProperty("stack");
+  });
 });

package/src/lifecycle/observe.ts

@@ -27,14 +27,27 @@ export interface ObserveResult {
  * 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.
+ *
+ * `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
+ * single-stack convention (`lexicons/aws/src/plugin.ts`'s `describeResources`,
+ * absent an explicit `stack`) queries a stack that simply doesn't exist there,
+ * so the single-call path always observes zero nodes. When `stacks` is
+ * present and non-empty, each observing plugin's `describeResources` is
+ * called once per stack (same `environment`/`entities`/`entityNames`, only
+ * `stack` varies) and the returned resource maps are unioned — a resource
+ * appears under whichever stack contains its logical id. When `stacks` is
+ * absent or empty, behavior is exactly the single call of before (no `stack`
+ * key at all), so a single-stack project is unaffected.
  */
 export async function observeResources(
   environment: string,
   plugins: ObservationLexicon[],
   buildResult: BuildResult,
-  opts?: { owned?: boolean },
+  opts?: { owned?: boolean; stacks?: string[] },
 ): Promise<ObserveResult> {
   const owned = opts?.owned ?? true;
+  const stacks = opts?.stacks ?? [];
   const observations: LiveObservation[] = [];
   const warnings: string[] = [];
   const errors: string[] = [];
@@ -64,13 +77,29 @@ export async function observeResources(
     }
 
     try {
-      const resources: Record<string, ResourceMetadata> = await plugin.describeResources({
-        environment,
-        buildOutput,
-        entityNames,
-        entities,
-        owned,
-      });
+      let resources: Record<string, ResourceMetadata>;
+      if (stacks.length > 0) {
+        resources = {};
+        for (const stack of stacks) {
+          const perStack = 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 });
       }