@intentius/chant 0.108.1 → 0.110.0

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

@@ -1,9 +1,10 @@
 import { describe, test, expect, vi, beforeEach, afterEach } from "vitest";
-import { sep } from "node:path";
+import { join, sep } from "node:path";
 import { createMockPlugin, staticDescribeResources, staticObservation, staticDeepObservation, staticListArtifacts } from "@intentius/chant-test-utils";
 import type { LexiconPlugin, ResourceMetadata } from "../../lexicon";
 import { deepObservation } from "../../deep-observation";
 import { heldElsewhere } from "../../held-elsewhere";
+import { setProvenance } from "../../provenance";
 import type { BuildResult } from "../../build";
 import type { ParsedArgs } from "../registry";
 
@@ -739,6 +740,110 @@ describe("runLifecycleDiff --live", () => {
     });
   });
 
+  // #3597 — a drifted field names where it came from: the composite argument
+  // and its line, the composite that fixes it, or an unknown origin and why.
+  describe("drift names its origin in source (#3597)", () => {
+    const app = join(process.cwd(), "src", "app.ts");
+    const call = { file: app, line: 10, column: 20 };
+    const names = ["webDeployment", "webService", "worker", "legacy"];
+
+    const runOriginDiff = async (args: Partial<ParsedArgs> = {}) => {
+      const build = makeBuildResult({ k8s: names });
+      const declare = (name: string, provenance?: Parameters<typeof setProvenance>[1]) => {
+        const entity = { lexicon: "k8s", entityType: "Deployment", props: { spec: { replicas: 3 } } };
+        if (provenance) setProvenance(entity, provenance);
+        build.entities.set(name, entity as never);
+      };
+      declare("webDeployment", {
+        sourceFile: app,
+        composite: "WebApp",
+        compositeInstance: "web",
+        compositeCall: call,
+        paths: {
+          "spec.replicas": {
+            kind: "composite-parameter",
+            composite: "WebApp",
+            parameters: ["replicas"],
+            arguments: [{ parameter: "replicas", file: app, line: 12, column: 3, text: "replicas: 3" }],
+          },
+        },
+      });
+      declare("webService", {
+        sourceFile: app,
+        composite: "WebApp",
+        compositeInstance: "web",
+        compositeCall: call,
+        paths: { "spec.replicas": { kind: "composite-literal", composite: "WebApp" } },
+      });
+      declare("worker", { sourceFile: app });
+      declare("legacy", { sourceFile: app, composite: "LegacyApp", compositeInstance: "legacy" });
+      buildMock.mockResolvedValue(build);
+      fetchLifecycleMock.mockResolvedValue(undefined);
+      readSnapshotMock.mockResolvedValue(null);
+      const live = Object.fromEntries(names.map((n) => [n, { type: "Deployment", properties: { spec: { replicas: 5 } } }]));
+      const plugins: LexiconPlugin[] = [
+        createMockPlugin({
+          name: "k8s",
+          describeResources: staticObservation(Object.fromEntries(names.map((n) => [n, meta({ type: "Deployment" })]))),
+          observeResourcesDeep: staticDeepObservation(live),
+        }),
+      ];
+      return runLifecycleDiff({
+        args: makeArgs({ command: "state", path: "diff", extraPositional: "prod", live: true, ...args }),
+        plugins,
+        serializers: plugins.map((p) => p.serializer),
+      } as never);
+    };
+
+    test("the human report names the argument and line, the fixing composite, and an unknown origin", async () => {
+      await runOriginDiff();
+      const output = stdoutBuf.join("\n");
+      expect(output).toContain(
+        "spec.replicas on Deployment webDeployment comes from WebApp({ replicas: 3 }) at src/app.ts:12",
+      );
+      expect(output).toContain("change parameter `replicas` of the `web` call of composite WebApp at src/app.ts:12");
+      expect(output).toContain(
+        "spec.replicas on Deployment webService is fixed inside composite WebApp; no argument to the call at src/app.ts:10 moves it",
+      );
+      expect(output).toContain(
+        "spec.replicas on Deployment legacy has an unknown origin: expanded by a composite whose factory this build did not interpret",
+      );
+      // Direct keeps today's output: the row, and nothing under it.
+      expect(output).not.toContain("on Deployment worker");
+      const workerRow = output.split("\n").findIndex((l) => l.includes("- worker (Deployment)"));
+      expect(output.split("\n")[workerRow + 1]).toMatch(/^ {6}spec\.replicas: 3 → 5/);
+      expect(output.split("\n")[workerRow + 2] ?? "").not.toMatch(/^ {8}\S/);
+      // An unknown origin is never shown as a direct declaration.
+      expect(output).not.toMatch(/legacy.*declared directly/);
+    });
+
+    test("--json carries the origin object for every drifted field", async () => {
+      await runOriginDiff({ json: true });
+      const payload = JSON.parse(stdoutBuf.join("\n")) as {
+        lexicons: { k8s: { reconcile: Array<{ entity: string; origin: Record<string, unknown>; summary: string }> } };
+      };
+      const byEntity = Object.fromEntries(payload.lexicons.k8s.reconcile.map((r) => [r.entity, r]));
+      expect(byEntity.webDeployment.origin).toEqual({
+        kind: "composite-parameter",
+        composite: "WebApp",
+        instance: "web",
+        parameters: ["replicas"],
+        call,
+        arguments: [{ parameter: "replicas", file: app, line: 12, column: 3, text: "replicas: 3" }],
+      });
+      expect(byEntity.webService.origin).toEqual({ kind: "composite-literal", composite: "WebApp", instance: "web", call });
+      expect(byEntity.worker.origin).toEqual({ kind: "direct" });
+      expect(byEntity.legacy.origin).toEqual({ kind: "unknown", reason: "composite-not-interpreted" });
+      expect(byEntity.webDeployment.summary).toContain("at src/app.ts:12");
+    });
+
+    test("the diff builds the way `chant build` does, folding by default", async () => {
+      await runOriginDiff();
+      const options = buildMock.mock.calls[0][3] as { fold?: boolean };
+      expect(options.fold).toBe(true);
+    });
+  });
+
   // #2162 — a `heldElsewhere()` marker reports as held, not drift, and a
   // held property nothing ever writes is flagged suspicious on stderr.
   describe("heldElsewhere() markers (#2162)", () => {

package/src/cli/handlers/lifecycle.ts

@@ -41,6 +41,7 @@ import { loadChantConfig, environmentNames, matchesDeclaredEnvironment, resolveO
 import { unknownEnvError, isProdLikeEnvironment } from "../../env";
 import { planTeardown, executeTeardown, type TeardownPlan, type TeardownReport } from "../../lifecycle/teardown";
 import { collectBuildRootContributors } from "../plugins";
+import { resolveBuildModes, resolveProjectBuildOptions } from "../build-options";
 import { applyLiveEndpoint } from "../../live-endpoint";
 import { isObservableDeclarable } from "../../declarable";
 import { formatError, formatWarning, formatSuccess, formatBold } from "../format";
@@ -378,11 +379,22 @@ export async function runLifecycleDiff(ctx: CommandContext): Promise<number> {
   const endpointResult = applyLiveEndpoint(config.environments, environment, liveLexicons);
   if (endpointResult.notice) console.error(formatWarning({ message: endpointResult.notice }));
 
-  const diffBuildRoots = collectBuildRootContributors(plugins, config as unknown as Record<string, unknown>, resolve("."));
+  // The build `chant build` would produce for this project (#2002's one
+  // place), so the diff folds by default as `chant build` does. A run build
+  // cannot say which composite argument produced a field, so without this
+  // every composite field in the live diff read as unknown (#3597).
+  const projectRoot = resolve(".");
+  const diffBuildOptions = resolveProjectBuildOptions({
+    config,
+    configDir: projectRoot,
+    plugins,
+    modes: resolveBuildModes(config, { fold: args.fold, sandbox: args.sandbox }),
+    buildParams: declaredParams,
+  });
 
   try {
     for (const target of targets) {
-      const buildResult = await build(target.root, targetSerializers, undefined, { buildParams: declaredParams, buildRoots: diffBuildRoots });
+      const buildResult = await build(target.root, targetSerializers, undefined, diffBuildOptions);
       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` }));
@@ -434,6 +446,7 @@ export async function runLifecycleDiff(ctx: CommandContext): Promise<number> {
           baseline,
           updateBaseline: args.updateBaseline,
           ...(args.namespace ? { namespace: args.namespace } : {}),
+          projectRoot,
         });
         totalDrift += r.totalDrift;
         totalUnobserved += r.totalUnobserved;
@@ -687,6 +700,8 @@ interface LiveDiffArgs {
   /** `--namespace <ns>` (#1629): where to read entities that declare no
    * namespace of their own. */
   namespace?: string;
+  /** Directory source locations in the report are printed relative to (#3597). */
+  projectRoot?: string;
 }
 
 interface LiveDiffOutcome {
@@ -902,8 +917,8 @@ async function runLifecycleDiffLive(args: LiveDiffArgs): Promise<LiveDiffOutcome
         if (args.json) {
           const entry = (byLexicon[lexiconName] ??= {});
           entry.deep = deep;
-          entry.reconcile = resolveDeepDrift(deep.drifted, provenanceOf);
-        } else renderDeepDiff(lexiconName, deep, provenanceOf);
+          entry.reconcile = resolveDeepDrift(deep.drifted, provenanceOf, { root: args.projectRoot });
+        } else renderDeepDiff(lexiconName, deep, provenanceOf, args.projectRoot);
         // Printed on stderr regardless of `--json` (#2162), same reason the
         // unobserved/disruption notices are: a shape with no column for
         // "suspicious" must not read as clean.
@@ -971,6 +986,7 @@ function renderDeepDiff(
   lexiconName: string,
   deep: DeepDiffResult,
   provenanceOf: (entity: string) => EntityProvenance | undefined = () => undefined,
+  projectRoot?: string,
 ): void {
   const drift = countPropertyDrift(deep);
   const unclaimedCount = countUnclaimed(deep);
@@ -1018,15 +1034,20 @@ function renderDeepDiff(
         // something today's behaviour would get wrong. A field the author
         // declared directly is left unremarked: editing it IS today's
         // behaviour, and saying so on every row would bury the two that matter.
-        const { resolution } = resolveDriftedField({
+        // #3597 — the line before the proposal names the composite call and
+        // the argument behind the field, with the file and line it was written on.
+        const { resolution, summary } = resolveDriftedField({
           entity: entity.name,
+          entityType: entity.type,
           path: change.path,
           ...("declared" in change ? { declared: change.declared } : {}),
           ...("live" in change ? { live: change.live } : {}),
           ...(change.origin ? { origin: change.origin } : {}),
           ...(provenance ? { provenance } : {}),
+          ...(projectRoot ? { root: projectRoot } : {}),
         });
         if (resolution.kind !== "edit-declaration") {
+          console.log(`        ${summary}`);
           console.log(`        ${resolution.description}`);
         }
       }

package/src/composite.ts

@@ -134,6 +134,16 @@ export function Composite<P, M extends CompositeFactoryMembers = CompositeMember
       }
     }
 
+    // chant#3608 — every member records the composite that built it, here,
+    // when the instance is made. A member destructured from the call
+    // (`export const { vpc } = VpcDefault({})`) is never expanded, so this is
+    // the only trace that a composite wrote it; `collectEntities` reads it
+    // through {@link compositeOfMember}. A nested instance recorded its own
+    // members first and the first record is kept, so a member keeps its
+    // innermost composite. Kept off the provenance record so the composite
+    // `expandComposite` records for an instance exported whole is unchanged.
+    markCompositeMembers(members, compositeName);
+
     // Define `members` and `_definition` as non-enumerable so spreading a
     // composite instance (`...someComposite`) only exposes the actual member
     // resources, not the framework's bookkeeping properties. Without this, a
@@ -156,6 +166,33 @@ export function Composite<P, M extends CompositeFactoryMembers = CompositeMember
   return definition;
 }
 
+/** Non-enumerable, symbol-keyed: invisible to serializers, spreads and comparisons, like provenance. */
+const COMPOSITE_MEMBER_OF = Symbol.for("chant.composite.memberOf");
+
+/** Record `compositeName` on each declarable member, descending into nested instances. First record wins. */
+function markCompositeMembers(members: object, compositeName: string): void {
+  for (const member of Object.values(members)) {
+    if (isCompositeInstance(member)) {
+      markCompositeMembers(member.members, compositeName);
+    } else if (
+      isDeclarable(member) &&
+      Object.isExtensible(member) &&
+      !Object.prototype.hasOwnProperty.call(member, COMPOSITE_MEMBER_OF)
+    ) {
+      Object.defineProperty(member, COMPOSITE_MEMBER_OF, { value: compositeName, enumerable: false, configurable: true });
+    }
+  }
+}
+
+/**
+ * chant#3608 — the composite whose call built `entity`, or `undefined` for an
+ * entity no chant composite built.
+ */
+export function compositeOfMember(entity: object): string | undefined {
+  const name = (entity as Record<symbol, unknown>)[COMPOSITE_MEMBER_OF];
+  return typeof name === "string" ? name : undefined;
+}
+
 /**
  * Expands a CompositeInstance into a flat Map of prefixed entity names to Declarables.
  * Handles nested composites recursively.

package/src/discovery/collect.ts

@@ -1,6 +1,6 @@
 import { basename, dirname, relative, resolve } from "node:path";
 import { isDeclarable, type Declarable } from "../declarable";
-import { isCompositeInstance, expandComposite } from "../composite";
+import { isCompositeInstance, expandComposite, compositeOfMember } from "../composite";
 import { isLexiconOutput } from "../lexicon-output";
 import { DiscoveryError } from "../errors";
 import { setProvenance, type EntityProvenance } from "../provenance";
@@ -43,6 +43,16 @@ function stackPrefix(file: string, buildRoot: string | undefined): string {
  */
 const AUTHORED_ROOT: EntityProvenance["paths"] = { "": { kind: "authored" } };
 
+/**
+ * The record for an entity exported on its own. chant#3608: one destructured
+ * from a composite call also names that composite, so fold provenance reads
+ * its unattributed paths as `unknown` rather than as the file's own `direct`.
+ */
+function authoredProvenance(entity: Declarable, file: string): EntityProvenance {
+  const composite = compositeOfMember(entity);
+  return { sourceFile: file, ...(composite ? { composite } : {}), paths: AUTHORED_ROOT };
+}
+
 /** 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
@@ -82,12 +92,12 @@ function enumerateEntries(
     for (const [rawName, value] of sortedExports) {
       const name = exportKey(rawName, file);
       if (isDeclarable(value)) {
-        entries.push({ bareKey: name, value, file, provenance: { sourceFile: file, paths: AUTHORED_ROOT } });
+        entries.push({ bareKey: name, value, file, provenance: authoredProvenance(value, file) });
       } else if (Array.isArray(value)) {
         for (let i = 0; i < value.length; i++) {
           const item = value[i];
           if (isDeclarable(item)) {
-            entries.push({ bareKey: `${name}_${i}`, value: item, file, provenance: { sourceFile: file, paths: AUTHORED_ROOT } });
+            entries.push({ bareKey: `${name}_${i}`, value: item, file, provenance: authoredProvenance(item, file) });
           } else if (isCompositeInstance(item)) {
             const indexedName = `${name}_${i}`;
             for (const [expandedName, entity] of expandComposite(indexedName, item)) {

package/src/discovery/fold-composite.test.ts

@@ -353,6 +353,28 @@ describe("composite factory interpretation (chant #1023)", () => {
     expect(JSON.parse(folded).readersReader.props.Description).toEqual({ GetAtt: ["webBucket", "Arn"] });
   });
 
+  test("a same-file call result read in an argument is bound for that argument only (chant#3610)", async () => {
+    await writeComposite(
+      ADMISSIBLE_BODY,
+      `export const Reader = Composite((props) => {
+        const reader = new Role({ RoleName: props.name, Description: props.bucket.Arn });
+        return { reader };
+      }, "Reader");`,
+    );
+    // `plain` reads `web` outside any argument. Under F-Call step 6 that read
+    // does not resolve, whichever declarator comes first, so the file runs.
+    await writeMain(`
+      import { Reader, WebApp } from "../composites";
+      export const web = WebApp({ name: "data" });
+      export const readers = Reader({ name: "readers", bucket: web.bucket });
+      export const plain = { inner: web.bucket };
+    `);
+
+    const result = await build(srcDir, [specSerializer], undefined, { fold: true, lexicons: [LEXICON_NAME] });
+
+    expect(result.foldDecisions.map((d) => d.mode)).toEqual(["run"]);
+  });
+
   test("provenance is stamped from the source's own composite name", async () => {
     await writeComposite(ADMISSIBLE_BODY);
     await writeMain(CALL_WEBAPP);

package/src/discovery/fold-host-composite.test.ts

@@ -86,6 +86,29 @@ describe("a host's composite registration form (chant#2442)", () => {
     });
   });
 
+  test("a host composite's result read inside an argument folds (chant#3610)", async () => {
+    writeFileSync(
+      join(root, "shapes.ts"),
+      'import { Bucket, Composite } from "@tsad/shapes";\n' +
+        'export const Store = Composite(({ name }) => ({ bucket: new Bucket({ name }) }), "Store");\n' +
+        'export const Wrap = Composite(({ inner }) => ({ inner }), "Wrap");\n',
+    );
+    const file = app(
+      'import { Store, Wrap } from "./shapes";\n' +
+        'export const s = Store({ name: "a" });\n' +
+        "export const w = Wrap({ inner: s.bucket });\n",
+    );
+
+    const verdict = (
+      await foldProject([file], [], { lexiconPackages: ["@tsad/shapes"], sandbox: true })
+    ).get(file)!;
+
+    expect(verdict.verdict).toBe("fold");
+    const exports = Object.fromEntries(verdict.exports!) as Record<string, { bucket?: unknown; inner?: unknown }>;
+    // One instance per file: the argument reads the declarator's own result.
+    expect(exports.w.inner).toBe(exports.s.bucket);
+  });
+
   test("a factory outside the subset is still refused rather than invoked", async () => {
     // `S-FactoryParams`: two parameters is outside it, so interpretation
     // declines and the invocation arm refuses under the sandbox.