@intentius/chant 0.18.19 → 0.18.21

package/src/cli/handlers/lifecycle.ts

@@ -1,7 +1,7 @@
 import { resolve } from "node:path";
 import { build } from "../../build";
 import { takeSnapshot } from "../../lifecycle/snapshot";
-import { readSnapshot, readSnapshotAt, readEnvironmentSnapshots, listSnapshots, fetchLifecycle, StaleLifecycleBranchError } from "../../lifecycle/git";
+import { readSnapshot, readSnapshotAt, readEnvironmentSnapshots, listSnapshots, fetchLifecycle, snapshotStorageKey, StaleLifecycleBranchError } from "../../lifecycle/git";
 import { computeBuildDigest, diffDigests } from "../../lifecycle/digest";
 import { diffLive, diffLiveArtifacts, diffSnapshots, type LiveDiffResult, type LiveArtifactDiffResult, type SnapshotDiffResult } from "../../lifecycle/live-diff";
 import { buildChangeSet, renderChangeSet, gitlabMrReport, type ChangeSet } from "../../lifecycle/change-set";
@@ -29,6 +29,34 @@ function resolveBuildRoot(args: ParsedArgs, config: ChantConfig): string {
   return resolve(args.src ?? config.sourceDir ?? ".");
 }
 
+/** One stack a lifecycle command operates on: its build root and, for a
+ * multi-stack project, the deployed CloudFormation stack name it observes
+ * against. */
+interface StackTarget {
+  /** The deployed stack name to observe (undefined ⇒ single-stack convention:
+   * the stack named after the environment). */
+  stack?: string;
+  /** Build root to synthesize this stack from, scoped so its logical ids match
+   * what the stack actually deploys. */
+  root: string;
+}
+
+/**
+ * The stacks a lifecycle command (`snapshot`/`diff`) iterates. A multi-stack
+ * project declares them via `stacks` in chant.config (#932) — each built from
+ * its own `src` and observed against its own live stack `name`. A single-stack
+ * project (no `stacks`) resolves to one target built from `sourceDir`/root and
+ * observed as the stack named after the environment (unchanged behavior). An
+ * explicit `--src` always wins and forces a single scoped target.
+ */
+function resolveStackTargets(args: ParsedArgs, config: ChantConfig): StackTarget[] {
+  if (args.src) return [{ root: resolve(args.src) }];
+  if (config.stacks && config.stacks.length > 0) {
+    return config.stacks.map((s) => ({ stack: s.name, root: resolve(s.src) }));
+  }
+  return [{ root: resolveBuildRoot(args, config) }];
+}
+
 /**
  * chant lifecycle snapshot <environment> [lexicon]
  */
@@ -59,13 +87,6 @@ export async function runLifecycleSnapshot(ctx: CommandContext): Promise<number>
     : plugins;
   const targetSerializers = targetPlugins.map((p) => p.serializer);
 
-  // Build first to get entity names and build output
-  const buildResult = await build(resolveBuildRoot(args, config), targetSerializers);
-  if (buildResult.errors.length > 0) {
-    console.error(formatError({ message: "Build failed — fix errors before taking a snapshot" }));
-    return 1;
-  }
-
   const observingPlugins = targetPlugins.filter((p) => p.describeResources || p.listArtifacts);
   if (observingPlugins.length === 0) {
     console.error(formatError({
@@ -75,35 +96,55 @@ export async function runLifecycleSnapshot(ctx: CommandContext): Promise<number>
     return 1;
   }
 
-  let result;
-  try {
-    result = await takeSnapshot(environment, observingPlugins, buildResult);
-  } catch (err) {
-    if (err instanceof StaleLifecycleBranchError) {
-      console.error(formatError({
-        message: `Another snapshot completed for chant/lifecycle after this run started (env: ${environment}).`,
-        hint: `Pull and retry: \`git fetch origin ${"chant/lifecycle"}:${"chant/lifecycle"}\` && \`chant lifecycle snapshot ${environment}\`.`,
-      }));
-      return 1;
+  // One target per stack (single-stack projects: exactly one). Each stack builds
+  // from its own scoped root — so its logical ids match what it deploys — and
+  // snapshots against its own live stack name (#932).
+  const targets = resolveStackTargets(args, config);
+  let anySnapshotSaved = false;
+  let anyHardError = false;
+
+  for (const target of targets) {
+    const label = target.stack ? `stack "${target.stack}"` : "project";
+    const buildResult = await build(target.root, targetSerializers);
+    if (buildResult.errors.length > 0) {
+      console.error(formatError({ message: `Build failed for ${label} — fix errors before taking a snapshot` }));
+      anyHardError = true;
+      continue;
     }
-    throw err;
-  }
 
-  for (const w of result.warnings) {
-    console.error(formatWarning({ message: w }));
-  }
-  for (const e of result.errors) {
-    console.error(formatError({ message: e }));
-  }
+    let result;
+    try {
+      result = await takeSnapshot(environment, observingPlugins, buildResult, { stack: target.stack });
+    } catch (err) {
+      if (err instanceof StaleLifecycleBranchError) {
+        console.error(formatError({
+          message: `Another snapshot completed for chant/lifecycle after this run started (env: ${environment}).`,
+          hint: `Pull and retry: \`git fetch origin ${"chant/lifecycle"}:${"chant/lifecycle"}\` && \`chant lifecycle snapshot ${environment}\`.`,
+        }));
+        return 1;
+      }
+      throw err;
+    }
+
+    for (const w of result.warnings) {
+      console.error(formatWarning({ message: w }));
+    }
+    for (const e of result.errors) {
+      console.error(formatError({ message: e }));
+    }
 
-  if (result.snapshots.length > 0) {
-    const counts = result.snapshots
-      .map((s) => `${s.lexicon}(${Object.keys(s.resources).length})`)
-      .join(" ");
-    console.error(formatSuccess(`Snapshot saved to chant/lifecycle (${counts})`));
+    if (result.snapshots.length > 0) {
+      anySnapshotSaved = true;
+      const prefix = target.stack ? `${target.stack}: ` : "";
+      const counts = result.snapshots
+        .map((s) => `${s.lexicon}(${Object.keys(s.resources).length})`)
+        .join(" ");
+      console.error(formatSuccess(`${prefix}Snapshot saved to chant/lifecycle (${counts})`));
+    }
+    if (result.errors.length > 0) anyHardError = true;
   }
 
-  return result.errors.length > 0 && result.snapshots.length === 0 ? 1 : 0;
+  return anyHardError && !anySnapshotSaved ? 1 : 0;
 }
 
 /**
@@ -209,26 +250,68 @@ export async function runLifecycleDiff(ctx: CommandContext): Promise<number> {
     ? plugins.filter((p) => p.name === lexiconFilter).map((p) => p.serializer)
     : serializers;
 
-  // Build to get current state (from the configured source root, not necessarily ".")
+  // Fetch previous snapshots once (all stacks share the orphan branch).
   const { config } = await loadChantConfig(resolve("."));
-  const buildResult = await build(resolveBuildRoot(args, config), targetSerializers);
-  if (buildResult.errors.length > 0) {
-    console.error(formatError({ message: "Build failed — fix errors before diffing" }));
-    return 1;
-  }
-
-  // Fetch and read previous snapshot
   await fetchLifecycle();
 
-  const lexicons = lexiconFilter
-    ? [lexiconFilter]
-    : Array.from(buildResult.manifest.lexicons);
+  // One target per stack (single-stack projects: exactly one), each built from
+  // its own scoped root and diffed against its own live stack name (#932).
+  const targets = resolveStackTargets(args, config);
+  const json = !!args.json;
+  const perStackJson: Record<string, unknown> = {};
+  let combinedLexiconsJson: Record<string, unknown> | undefined;
+  let totalDrift = 0;
+  let totalChecked = 0;
+  let anyBuildError = false;
+
+  for (const target of targets) {
+    const buildResult = await build(target.root, targetSerializers);
+    if (buildResult.errors.length > 0) {
+      const label = target.stack ? `stack "${target.stack}"` : "project";
+      console.error(formatError({ message: `Build failed for ${label} — fix errors before diffing` }));
+      anyBuildError = true;
+      continue;
+    }
+
+    const lexicons = lexiconFilter
+      ? [lexiconFilter]
+      : Array.from(buildResult.manifest.lexicons);
+
+    if (args.live) {
+      const r = await runLifecycleDiffLive({ environment, lexicons, plugins, buildResult, json, stack: target.stack });
+      totalDrift += r.totalDrift;
+      totalChecked += r.totalLexiconsChecked;
+      if (json) {
+        if (target.stack) perStackJson[target.stack] = r.byLexicon;
+        else combinedLexiconsJson = r.byLexicon;
+      }
+    } else {
+      await runLifecycleDiffDigest({ environment, lexicons, buildResult, stack: target.stack });
+    }
+  }
 
   if (args.live) {
-    return runLifecycleDiffLive({ environment, lexicons, plugins, buildResult, json: !!args.json });
+    if (json) {
+      // Single-stack keeps the original `{ environment, lexicons }` shape
+      // (behold's inspect diff, #852); multi-stack nests under `stacks`.
+      console.log(
+        JSON.stringify(
+          combinedLexiconsJson !== undefined
+            ? { environment, lexicons: combinedLexiconsJson }
+            : { environment, stacks: perStackJson },
+        ),
+      );
+    } else if (totalChecked === 0) {
+      console.error(formatWarning({
+        message: "No lexicons implement describeResources or listArtifacts — nothing to diff in --live mode",
+      }));
+      return 1;
+    } else if (totalDrift === 0) {
+      console.error(formatSuccess(`No drift detected across ${totalChecked} lexicon(s)`));
+    }
   }
 
-  return runLifecycleDiffDigest({ environment, lexicons, buildResult });
+  return anyBuildError ? 1 : 0;
 }
 
 interface BetweenDiffArgs {
@@ -300,13 +383,16 @@ interface DigestDiffArgs {
   environment: string;
   lexicons: string[];
   buildResult: BuildResult;
+  /** Deployed stack name for a multi-stack project (#932); scopes the snapshot read. */
+  stack?: string;
 }
 
 async function runLifecycleDiffDigest(args: DigestDiffArgs): Promise<number> {
   const currentDigest = computeBuildDigest(args.buildResult);
+  if (args.stack) console.log(`\n${formatBold(`■ stack ${args.stack}`)}`);
 
   for (const lexicon of args.lexicons) {
-    const content = await readSnapshot(args.environment, lexicon);
+    const content = await readSnapshot(args.environment, snapshotStorageKey(lexicon, args.stack));
     let previousDigest = undefined;
     if (content) {
       const snapshot: LifecycleSnapshot = JSON.parse(content);
@@ -343,17 +429,28 @@ interface LiveDiffArgs {
   buildResult: BuildResult;
   /** Emit machine-readable JSON on stdout instead of the human report (#852). */
   json: boolean;
+  /** Deployed stack name for a multi-stack project (#932); scopes the live
+   * observation (which CloudFormation stack to query) and the snapshot read. */
+  stack?: string;
 }
 
-async function runLifecycleDiffLive(args: LiveDiffArgs): Promise<number> {
-  let totalDrift = 0;
-  let totalLexiconsChecked = 0;
-  // Collected per-lexicon results, emitted as one JSON object when --json is set
-  // (parsed by programmatic consumers, e.g. behold's inspect diff — #852).
-  const byLexicon: Record<
+interface LiveDiffOutcome {
+  byLexicon: Record<
     string,
     { resources?: LiveDiffResult; observed?: Record<string, ResourceMetadata>; artifacts?: LiveArtifactDiffResult }
-  > = {};
+  >;
+  totalDrift: number;
+  totalLexiconsChecked: number;
+}
+
+/** Diff current build vs live cloud for one stack. Renders the human report
+ * inline; returns per-lexicon results so the caller emits the aggregate `--json`
+ * once (single-stack keeps the original shape; multi-stack nests under `stacks`). */
+async function runLifecycleDiffLive(args: LiveDiffArgs): Promise<LiveDiffOutcome> {
+  let totalDrift = 0;
+  let totalLexiconsChecked = 0;
+  const byLexicon: LiveDiffOutcome["byLexicon"] = {};
+  if (!args.json && args.stack) console.log(`\n${formatBold(`■ stack ${args.stack}`)}`);
 
   for (const lexiconName of args.lexicons) {
     const plugin = args.plugins.find((p) => p.name === lexiconName);
@@ -391,7 +488,7 @@ async function runLifecycleDiffLive(args: LiveDiffArgs): Promise<number> {
 
     // Read previous snapshot once; both flows pull what they need.
     let prevSnapshot: LifecycleSnapshot | undefined;
-    const content = await readSnapshot(args.environment, lexiconName);
+    const content = await readSnapshot(args.environment, snapshotStorageKey(lexiconName, args.stack));
     if (content) prevSnapshot = JSON.parse(content);
 
     let lexiconChecked = false;
@@ -405,6 +502,7 @@ async function runLifecycleDiffLive(args: LiveDiffArgs): Promise<number> {
           buildOutput,
           entityNames: Array.from(declared),
           entities,
+          stack: args.stack,
         });
       } catch (err) {
         console.error(formatError({
@@ -427,7 +525,7 @@ async function runLifecycleDiffLive(args: LiveDiffArgs): Promise<number> {
     if (plugin.listArtifacts) {
       let observedNow: Record<string, ArtifactMetadata>;
       try {
-        observedNow = await plugin.listArtifacts({ environment: args.environment, entities });
+        observedNow = await plugin.listArtifacts({ environment: args.environment, entities, stack: args.stack });
       } catch (err) {
         console.error(formatError({
           message: `${lexiconName}: listArtifacts failed — ${err instanceof Error ? err.message : String(err)}`,
@@ -445,23 +543,7 @@ async function runLifecycleDiffLive(args: LiveDiffArgs): Promise<number> {
     if (lexiconChecked) totalLexiconsChecked++;
   }
 
-  if (totalLexiconsChecked === 0) {
-    console.error(formatWarning({
-      message: "No lexicons implement describeResources or listArtifacts — nothing to diff in --live mode",
-    }));
-    return 1;
-  }
-
-  if (args.json) {
-    console.log(JSON.stringify({ environment: args.environment, lexicons: byLexicon }));
-    return 0;
-  }
-
-  if (totalDrift === 0) {
-    console.error(formatSuccess(`No drift detected across ${totalLexiconsChecked} lexicon(s)`));
-  }
-
-  return 0;
+  return { byLexicon, totalDrift, totalLexiconsChecked };
 }
 
 function renderLiveDiff(lexiconName: string, environment: string, diff: LiveDiffResult): void {

package/src/components/cli-support.ts

@@ -160,7 +160,7 @@ export async function computeComponentGraph(path: string): Promise<ComponentGrap
   }
 }
 
-/** A generate-mode target lexicon name — any lexicon whose plugin implements `generateComponentPipeline` (currently gitlab; github/forgejo as they add it). */
+/** A generate-mode target lexicon name — any lexicon whose plugin implements `generateComponentPipeline` (gitlab, github, and forgejo today). */
 export type GenerateLexicon = string;
 
 /** Result of `chant build --components --generate <lexicon>`. */
@@ -213,7 +213,7 @@ export async function generateComponentsPipeline(
   if (!plugin?.generateComponentPipeline) {
     return {
       success: false,
-      error: `Lexicon "${lexicon}" does not support generate mode (no generateComponentPipeline). GitLab is supported today; GitHub/Forgejo as they add it.`,
+      error: `Lexicon "${lexicon}" does not support generate mode (no generateComponentPipeline). GitLab, GitHub, and Forgejo are supported today.`,
     };
   }
 

package/src/config.ts

@@ -82,6 +82,23 @@ export interface ChantConfig {
    */
   sourceDir?: string;
 
+  /**
+   * Multi-stack projects: the independently-deployed CloudFormation stacks this
+   * project comprises, each built from its own source directory. When set,
+   * lifecycle commands (`snapshot`/`diff`) iterate every stack — building each
+   * `src` scoped (so its logical ids match what that stack actually deploys) and
+   * observing it against its own live stack `name` — instead of assuming one
+   * stack per environment. Leave unset for a single-stack project (the default:
+   * one build from `sourceDir`/root, observed as the stack named after the
+   * environment). See {@link resolveStackTargets}.
+   */
+  stacks?: Array<{
+    /** The deployed CloudFormation stack name (what `cfn-deploy` targets). */
+    name: string;
+    /** Source directory to build for this stack, relative to the project root. */
+    src: string;
+  }>;
+
   /** Lint configuration (rules, extends, overrides, plugins) */
   lint?: LintConfig;
 

package/src/discovery/collect.test.ts

@@ -280,6 +280,97 @@ describe("collectEntities", () => {
   });
 });
 
+// #932 — a multi-stack project (independently-deployed sibling stacks under one
+// root) legitimately reuses conventional cross-stack Parameter names across
+// siblings. The unscoped whole-project build must namespace by directory instead
+// of throwing, while a per-stack scoped build keeps the raw (deployed) names.
+describe("collectEntities — cross-directory namespaces (#932)", () => {
+  test("the same bare name in two different directories is disambiguated by a stack prefix, not thrown", () => {
+    const agentsBucket = createMockEntity("param");
+    const backendBucket = createMockEntity("param");
+
+    const result = collectEntities(
+      [
+        { file: "src/loom-agents/params.ts", exports: { pArtifactBucket: agentsBucket } },
+        { file: "src/loom-backend/params.ts", exports: { pArtifactBucket: backendBucket } },
+      ],
+      "src",
+    );
+
+    expect(result.size).toBe(2);
+    expect(result.get("LoomAgentspArtifactBucket")).toBe(agentsBucket);
+    expect(result.get("LoomBackendpArtifactBucket")).toBe(backendBucket);
+    // The raw name is not used when it collides across directories.
+    expect(result.has("pArtifactBucket")).toBe(false);
+    // Disambiguated keys stay within CloudFormation's logical-id grammar.
+    for (const key of result.keys()) expect(key).toMatch(/^[A-Za-z0-9]+$/);
+  });
+
+  test("a genuine same-directory duplicate still throws", async () => {
+    const a = createMockEntity("param");
+    const b = createMockEntity("param");
+
+    await expectToThrow(
+      () =>
+        collectEntities(
+          [
+            { file: "src/loom-backend/params.ts", exports: { pArtifactBucket: a } },
+            { file: "src/loom-backend/more.ts", exports: { pArtifactBucket: b } },
+          ],
+          "src",
+        ),
+      DiscoveryError,
+      (error) => {
+        expect(error.type).toBe("resolution");
+        expect(error.message).toBe('Duplicate export name "pArtifactBucket" found');
+      },
+    );
+  });
+
+  test("the same object re-exported from two directories stays one raw-named entity", () => {
+    const shared = createMockEntity("param");
+
+    const result = collectEntities(
+      [
+        { file: "src/a/x.ts", exports: { shared } },
+        { file: "src/b/y.ts", exports: { shared } },
+      ],
+      "src",
+    );
+
+    expect(result.size).toBe(1);
+    expect(result.get("shared")).toBe(shared);
+  });
+
+  test("non-colliding names in different directories keep their raw names (single-stack subdirs unaffected)", () => {
+    const vpc = createMockEntity("resource");
+    const app = createMockEntity("resource");
+
+    const result = collectEntities(
+      [
+        { file: "src/network/vpc.ts", exports: { vpc } },
+        { file: "src/compute/app.ts", exports: { app } },
+      ],
+      "src",
+    );
+
+    expect(result.size).toBe(2);
+    expect(result.get("vpc")).toBe(vpc);
+    expect(result.get("app")).toBe(app);
+  });
+
+  test("a scoped per-stack build (buildRoot == the stack dir) keeps raw names — deploy fidelity", () => {
+    const bucket = createMockEntity("param");
+
+    const result = collectEntities(
+      [{ file: "src/loom-backend/params.ts", exports: { pArtifactBucket: bucket } }],
+      "src/loom-backend",
+    );
+
+    expect(result.get("pArtifactBucket")).toBe(bucket);
+  });
+});
+
 describe("collectEntities with composites", () => {
   beforeEach(() => {
     CompositeRegistry.clear();