@intentius/chant 0.18.20 → 0.18.22

package/src/discovery/collect.ts

@@ -1,9 +1,9 @@
-import { basename } from "node:path";
+import { basename, dirname, relative, resolve } from "node:path";
 import { isDeclarable, type Declarable } from "../declarable";
 import { isCompositeInstance, expandComposite } from "../composite";
 import { isLexiconOutput } from "../lexicon-output";
 import { DiscoveryError } from "../errors";
-import { setProvenance } from "../provenance";
+import { setProvenance, type EntityProvenance } from "../provenance";
 
 /**
  * The entity key for an export. `export default` is per-module — the `Op` pattern
@@ -18,84 +18,177 @@ function exportKey(rawName: string, file: string): string {
 }
 
 /**
- * Collects all declarable entities from imported modules.
- * CompositeInstance exports are expanded into individual entities
- * with `{exportName}_{memberName}` naming.
- * LexiconOutput exports are also collected so that build() can
- * extract them and pass them to the serializer.
- *
- * @param modules - Array of module records with their exports
- * @returns Map of export name to Declarable entity
- * @throws {DiscoveryError} with type "resolution" if duplicate export names are found
+ * A stable, CloudFormation-valid prefix identifying the stack directory a file
+ * belongs to, relative to the build root. Used to disambiguate an entity name
+ * that legitimately repeats across sibling stack directories (see
+ * {@link collectEntities}). Derived from the path *relative to the build root*
+ * (not the absolute path) so the resulting key — and therefore any build digest
+ * that hashes it — is portable across machines and checkouts. Punctuation
+ * (`/`, `-`, `.`) is dropped and each segment PascalCased, keeping the key
+ * within CloudFormation's `^[A-Za-z0-9]+$` logical-id grammar.
  */
-export function collectEntities(
-  modules: Array<{ file: string; exports: Record<string, unknown> }>
-): Map<string, Declarable> {
-  const entities = new Map<string, Declarable>();
+function stackPrefix(file: string, buildRoot: string | undefined): string {
+  const dir = dirname(file);
+  const rel = buildRoot ? relative(resolve(buildRoot), resolve(dir)) : dir;
+  const segments = rel.split(/[^A-Za-z0-9]+/).filter((s) => s.length > 0);
+  return segments.map((s) => s.charAt(0).toUpperCase() + s.slice(1)).join("");
+}
+
+/** One entity to be placed into the map, produced by {@link enumerateEntries}. */
+interface PendingEntry {
+  /** The un-disambiguated map key this entity would take (export name, indexed
+   * array name, or composite-expanded member name). */
+  bareKey: string;
+  value: Declarable;
+  file: string;
+  provenance: EntityProvenance;
+}
+
+/**
+ * Flatten every module's exports into the ordered list of entities they
+ * contribute — declarables directly, arrays element-by-element (indexed names),
+ * composite instances expanded into members, and LexiconOutputs. Order is
+ * preserved so downstream serializers emit resources in a stable order.
+ */
+function enumerateEntries(
+  modules: Array<{ file: string; exports: Record<string, unknown> }>,
+): PendingEntry[] {
+  const entries: PendingEntry[] = [];
 
   for (const { file, exports } of modules) {
     for (const [rawName, value] of Object.entries(exports)) {
       const name = exportKey(rawName, file);
       if (isDeclarable(value)) {
-        if (entities.has(name)) {
-          // Same object re-exported from multiple files (e.g. re-exports from multiple files) is fine
-          if (entities.get(name) !== value) {
-            throw new DiscoveryError(
-              file,
-              `Duplicate export name "${name}" found`,
-              "resolution"
-            );
-          }
-        } else {
-          setProvenance(value, { sourceFile: file });
-          entities.set(name, value);
-        }
+        entries.push({ bareKey: name, value, file, provenance: { sourceFile: file } });
       } else if (Array.isArray(value)) {
-        // Arrays of Declarables or CompositeInstances — each element gets an indexed name: exportName_0, ...
         for (let i = 0; i < value.length; i++) {
           const item = value[i];
           if (isDeclarable(item)) {
-            const indexedName = `${name}_${i}`;
-            if (entities.has(indexedName) && entities.get(indexedName) !== item) {
-              throw new DiscoveryError(file, `Duplicate entity name "${indexedName}"`, "resolution");
-            }
-            setProvenance(item, { sourceFile: file });
-            entities.set(indexedName, item);
+            entries.push({ bareKey: `${name}_${i}`, value: item, file, provenance: { sourceFile: file } });
           } else if (isCompositeInstance(item)) {
             const indexedName = `${name}_${i}`;
-            const expanded = expandComposite(indexedName, item);
-            for (const [expandedName, entity] of expanded) {
-              if (entities.has(expandedName)) {
-                throw new DiscoveryError(
-                  file,
-                  `Duplicate entity name "${expandedName}" from composite expansion of "${indexedName}"`,
-                  "resolution",
-                );
-              }
-              setProvenance(entity, { sourceFile: file, compositeInstance: indexedName });
-              entities.set(expandedName, entity);
+            for (const [expandedName, entity] of expandComposite(indexedName, item)) {
+              entries.push({
+                bareKey: expandedName,
+                value: entity,
+                file,
+                provenance: { sourceFile: file, compositeInstance: indexedName },
+              });
             }
           }
         }
       } else if (isCompositeInstance(value)) {
-        const expanded = expandComposite(name, value);
-        for (const [expandedName, entity] of expanded) {
-          if (entities.has(expandedName)) {
-            throw new DiscoveryError(
-              file,
-              `Duplicate entity name "${expandedName}" from composite expansion of "${name}"`,
-              "resolution",
-            );
-          }
-          setProvenance(entity, { sourceFile: file, compositeInstance: name });
-          entities.set(expandedName, entity);
+        for (const [expandedName, entity] of expandComposite(name, value)) {
+          entries.push({
+            bareKey: expandedName,
+            value: entity,
+            file,
+            provenance: { sourceFile: file, compositeInstance: name },
+          });
         }
       } else if (isLexiconOutput(value)) {
-        // LexiconOutput is not a Declarable but build() expects to find them
-        // in the entities map so it can collect and pass them to serializers
-        entities.set(name, value as unknown as Declarable);
+        // LexiconOutput is not a Declarable but build() expects to find them in
+        // the entities map so it can collect and pass them to serializers.
+        entries.push({ bareKey: name, value: value as unknown as Declarable, file, provenance: { sourceFile: file } });
+      }
+    }
+  }
+
+  return entries;
+}
+
+/**
+ * Collects all declarable entities from imported modules.
+ * CompositeInstance exports are expanded into individual entities
+ * with `{exportName}_{memberName}` naming.
+ * LexiconOutput exports are also collected so that build() can
+ * extract them and pass them to the serializer.
+ *
+ * A bare entity name must be unique *within a single stack directory*, not
+ * across the whole project. A multi-stack project (independently-deployed
+ * sibling stacks under one root — e.g. `src/loom-backend/`, `src/loom-agents/`)
+ * legitimately reuses conventional cross-stack `Parameter` names like
+ * `pArtifactBucket`/`pImageUri` across siblings, because each directory is its
+ * own CloudFormation template where that name is the real, deployed logical id.
+ * When the same bare name is declared (as distinct objects) in two different
+ * directories, each is disambiguated by a stack prefix derived from its
+ * directory ({@link stackPrefix}) rather than throwing — so an unscoped
+ * whole-project build / `chant lifecycle snapshot|diff` no longer collides
+ * (#932). A per-stack scoped build (`chant build <dir>`) has a single directory
+ * relative to its root, so nothing is prefixed and the deployed logical ids are
+ * unchanged. A genuine *same-directory* duplicate is still an error.
+ *
+ * @param modules - Array of module records with their exports
+ * @param buildRoot - The build root the discovery ran against; stack prefixes
+ *   are derived relative to it so keys stay portable across machines.
+ * @returns Map of export name to Declarable entity
+ * @throws {DiscoveryError} with type "resolution" if a name is duplicated within one directory
+ */
+export function collectEntities(
+  modules: Array<{ file: string; exports: Record<string, unknown> }>,
+  buildRoot?: string,
+): Map<string, Declarable> {
+  const entries = enumerateEntries(modules);
+
+  // Which bare keys collide across more than one directory (as distinct
+  // objects)? Those — and only those — get a stack prefix. A bare key that
+  // resolves to a single object (even one re-exported from several files) keeps
+  // its raw name, so single-stack projects are unaffected.
+  const dirsByKey = new Map<string, Map<string, Set<Declarable>>>();
+  for (const { bareKey, value, file } of entries) {
+    const dir = dirname(file);
+    let byDir = dirsByKey.get(bareKey);
+    if (!byDir) {
+      byDir = new Map();
+      dirsByKey.set(bareKey, byDir);
+    }
+    let objs = byDir.get(dir);
+    if (!objs) {
+      objs = new Set();
+      byDir.set(dir, objs);
+    }
+    objs.add(value);
+  }
+  const crossDirKeys = new Set<string>();
+  for (const [bareKey, byDir] of dirsByKey) {
+    const dirsWithObjects = [...byDir.values()].filter((objs) => objs.size > 0).length;
+    const distinctObjects = new Set<Declarable>();
+    for (const objs of byDir.values()) for (const o of objs) distinctObjects.add(o);
+    if (dirsWithObjects > 1 && distinctObjects.size > 1) crossDirKeys.add(bareKey);
+  }
+
+  const entities = new Map<string, Declarable>();
+  // Per bare key, the object already claimed for each directory — a second,
+  // *different* object in the same directory is a genuine duplicate.
+  const claimedByDir = new Map<string, Map<string, Declarable>>();
+
+  for (const { bareKey, value, file, provenance } of entries) {
+    const dir = dirname(file);
+    let perDir = claimedByDir.get(bareKey);
+    if (!perDir) {
+      perDir = new Map();
+      claimedByDir.set(bareKey, perDir);
+    }
+    const claimed = perDir.get(dir);
+    if (claimed !== undefined && claimed !== value) {
+      // Same name, same directory, different object → a real collision.
+      throw new DiscoveryError(file, `Duplicate export name "${bareKey}" found`, "resolution");
+    }
+    perDir.set(dir, value);
+
+    const key = crossDirKeys.has(bareKey) ? `${stackPrefix(file, buildRoot)}${bareKey}` : bareKey;
+    const existing = entities.get(key);
+    if (existing !== undefined) {
+      // Same object re-exported (possibly from multiple files) is fine; a
+      // different object landing on the same disambiguated key would only
+      // happen if two directories produced an identical stack prefix.
+      if (existing !== value) {
+        throw new DiscoveryError(file, `Duplicate export name "${bareKey}" found`, "resolution");
       }
+      continue;
     }
+    setProvenance(value, provenance);
+    entities.set(key, value);
   }
 
   return entities;

package/src/discovery/index.ts

@@ -67,7 +67,7 @@ export async function discover(path: string): Promise<DiscoveryResult> {
   let entities = new Map<string, Declarable>();
 
   try {
-    entities = collectEntities(modules);
+    entities = collectEntities(modules, path);
   } catch (error) {
     // Collect resolution errors
     if (error instanceof Error && error.name === "DiscoveryError") {

package/src/lexicon.ts

@@ -372,6 +372,13 @@ export interface LexiconPlugin {
     buildOutput: string;
     entityNames: string[];
     entities: Map<string, { entityType: string; props: Record<string, unknown> }>;
+    /**
+     * The deployed stack name to observe, for a multi-stack project where the
+     * stack is not named after the environment (see `stacks` in {@link
+     * ChantConfig}). When omitted, an implementation keeps its single-stack
+     * convention (AWS: the stack named after `environment`).
+     */
+    stack?: string;
     /**
      * Restrict the result to chant-owned resources (those carrying the
      * ownership marker, #119). Where a lexicon has no durable marker channel,
@@ -399,7 +406,7 @@ export interface LexiconPlugin {
    * thin to carry references (e.g. AWS CloudFormation, where it's sourced from
    * the fuller `exportResources` config).
    */
-  enrichLiveAttrs?(options: { environment: string; owned?: boolean }): Promise<Record<string, Record<string, unknown>>>;
+  enrichLiveAttrs?(options: { environment: string; stack?: string; owned?: boolean }): Promise<Record<string, Record<string, unknown>>>;
 
   /**
    * List runtime artifacts in the given environment. Opt-in.
@@ -418,6 +425,9 @@ export interface LexiconPlugin {
   listArtifacts?(options: {
     environment: string;
     entities: Map<string, { entityType: string; props: Record<string, unknown> }>;
+    /** The deployed stack to scope enumeration to, for a multi-stack project
+     * (see `stacks` in {@link ChantConfig}). Omitted for single-stack projects. */
+    stack?: string;
   }): Promise<Record<string, ArtifactMetadata>>;
 
   // Live export (cloud → code)
@@ -444,6 +454,11 @@ export interface LexiconPlugin {
    */
   exportResources?(options: {
     environment: string;
+    /** The deployed stack to export from, for a multi-stack project (see
+     * `stacks` in {@link ChantConfig}, #932). When omitted, an implementation
+     * keeps its single-stack convention (AWS: the stack named after
+     * `environment`). */
+    stack?: string;
     selector?: ResourceSelector;
     owned?: boolean;
     verbatim?: boolean;

package/src/lifecycle/git.ts

@@ -141,6 +141,19 @@ export async function readBlobFromPath(
   return result.stdout;
 }
 
+/**
+ * Storage key for a snapshot on the orphan branch. Single-stack projects key by
+ * lexicon (`<env>/<lexicon>.json`, unchanged). A multi-stack project (see
+ * `stacks` in ChantConfig, #932) folds the stack in as `<stack>__<lexicon>`
+ * (`<env>/<stack>__<lexicon>.json`) so sibling stacks that deploy the same
+ * lexicon don't overwrite each other's snapshots. The `__` separator can't
+ * collide with a lexicon name (lexicons are single tokens) and round-trips
+ * through `readSnapshot`/`readEnvironmentSnapshots` unchanged.
+ */
+export function snapshotStorageKey(lexicon: string, stack?: string): string {
+  return stack ? `${stack}__${lexicon}` : lexicon;
+}
+
 /**
  * Write a state snapshot JSON to the orphan branch.
  *

package/src/lifecycle/snapshot.test.ts

@@ -8,6 +8,7 @@ const pushLifecycleMock = vi.fn();
 
 vi.mock("./git", () => ({
   writeSnapshot: (...args: unknown[]) => writeSnapshotMock(...args),
+  snapshotStorageKey: (lexicon: string, stack?: string) => (stack ? `${stack}__${lexicon}` : lexicon),
   getHeadCommit: () => getHeadCommitMock(),
   pushLifecycle: () => pushLifecycleMock(),
 }));
@@ -57,6 +58,29 @@ describe("takeSnapshot", () => {
     });
     expect(writeSnapshotMock).toHaveBeenCalledTimes(1);
     expect(pushLifecycleMock).toHaveBeenCalledTimes(1);
+    // Single-stack: written under the bare lexicon key, snapshot carries no stack.
+    expect(writeSnapshotMock.mock.calls[0][1]).toBe("aws");
+    expect(result.snapshots[0].stack).toBeUndefined();
+  });
+
+  // #932 — a multi-stack project observes each stack against its own live stack
+  // and stores its snapshot under a stack-scoped key so siblings don't overwrite.
+  test("stack option: observes the named stack and stores under a stack-scoped key", async () => {
+    let observedStack: string | undefined = "unset";
+    const plugin = createMockPlugin({
+      name: "aws",
+      describeResources: async (options: { stack?: string }) => {
+        observedStack = options.stack;
+        return { bucket: { type: "AWS::S3::Bucket", status: "CREATE_COMPLETE", physicalId: "b" } };
+      },
+    });
+    const result = await takeSnapshot("prod", [plugin], makeBuildResult({ aws: ["bucket"] }), { stack: "loom-backend" });
+    // describeResources was told which live stack to query.
+    expect(observedStack).toBe("loom-backend");
+    // The snapshot records its stack …
+    expect(result.snapshots[0].stack).toBe("loom-backend");
+    // … and is stored under `<stack>__<lexicon>`, not the bare lexicon key.
+    expect(writeSnapshotMock.mock.calls[0][1]).toBe("loom-backend__aws");
   });
 
   test("plugin without describeResources is skipped", async () => {

package/src/lifecycle/snapshot.ts

@@ -7,7 +7,7 @@ import type { BuildResult } from "../build";
 import type { SerializerResult } from "../serializer";
 import type { LifecycleSnapshot } from "./types";
 import { computeBuildDigest } from "./digest";
-import { writeSnapshot, getHeadCommit, pushLifecycle } from "./git";
+import { writeSnapshot, snapshotStorageKey, getHeadCommit, pushLifecycle } from "./git";
 import { sortedJsonReplacer } from "../utils";
 
 /** Patterns in attribute names that suggest sensitive data. */
@@ -84,8 +84,9 @@ export async function takeSnapshot(
   environment: string,
   plugins: ObservationLexicon[],
   buildResult: BuildResult,
-  opts?: { cwd?: string },
+  opts?: { cwd?: string; stack?: string },
 ): Promise<TakeSnapshotResult> {
+  const stack = opts?.stack;
   const warnings: string[] = [];
   const errors: string[] = [];
   const snapshots: LifecycleSnapshot[] = [];
@@ -131,6 +132,7 @@ export async function takeSnapshot(
           buildOutput,
           entityNames,
           entities,
+          stack,
         });
         const { valid, dropped, warnings: validationWarnings } = validateResources(raw);
         warnings.push(...validationWarnings);
@@ -141,7 +143,7 @@ export async function takeSnapshot(
       }
 
       if (plugin.listArtifacts) {
-        const raw = await plugin.listArtifacts({ environment, entities });
+        const raw = await plugin.listArtifacts({ environment, entities, stack });
         const { valid, dropped, warnings: validationWarnings } = validateResources(raw);
         warnings.push(...validationWarnings);
         if (dropped.length > 0) {
@@ -158,6 +160,7 @@ export async function takeSnapshot(
       const snapshot: LifecycleSnapshot = {
         lexicon: plugin.name,
         environment,
+        ...(stack ? { stack } : {}),
         commit: headCommit,
         timestamp,
         resources,
@@ -179,7 +182,7 @@ export async function takeSnapshot(
     const json = JSON.stringify(snapshot, sortedJsonReplacer, 2);
     commitSha = await writeSnapshot(
       snapshot.environment,
-      snapshot.lexicon,
+      snapshotStorageKey(snapshot.lexicon, snapshot.stack),
       json,
       opts,
     );

package/src/lifecycle/types.ts

@@ -8,6 +8,10 @@ export type { ResourceMetadata, ArtifactMetadata } from "../lexicon";
 export interface LifecycleSnapshot {
   lexicon: string;
   environment: string;
+  /** Deployed stack name, for a multi-stack project (see `stacks` in
+   * ChantConfig). Absent for single-stack projects. Snapshots are stored per
+   * `<env>/<stack>/<lexicon>` when set, so sibling stacks don't overwrite. */
+  stack?: string;
   /** Main branch commit this corresponds to */
   commit: string;
   /** ISO timestamp when the snapshot was taken */