@intentius/chant 0.108.0 → 0.109.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/cli/main.ts

@@ -486,6 +486,17 @@ export function parseArgs(args: string[]): ParsedArgs {
       // `chant ci workflow --install <command>` (#3573): a step before the tick that installs what --chant runs.
       result.ciInstall = args[++i];
       if (!result.ciInstall || result.ciInstall.startsWith("-")) throw new Error("--install needs the install command, such as \"npm install\": --install <command>");
+    } else if (arg === "--token-secret") {
+      // `chant ci workflow --token-secret <NAME>` (#3573): the secret the tick's tag push authenticates with.
+      result.ciTokenSecret = args[++i];
+      if (!result.ciTokenSecret || result.ciTokenSecret.startsWith("-")) throw new Error("--token-secret needs a repository secret's name, such as CI_GREEN_TOKEN: --token-secret <NAME>");
+    } else if (arg === "--app-id-var") {
+      // `chant ci workflow --app-id-var <VAR> --app-key-secret <NAME>` (#3573): a GitHub App token pushes the tags.
+      result.ciAppIdVar = args[++i];
+      if (!result.ciAppIdVar || result.ciAppIdVar.startsWith("-")) throw new Error("--app-id-var needs the Actions variable holding the App's id: --app-id-var <VAR>");
+    } else if (arg === "--app-key-secret") {
+      result.ciAppKeySecret = args[++i];
+      if (!result.ciAppKeySecret || result.ciAppKeySecret.startsWith("-")) throw new Error("--app-key-secret needs the secret holding the App's private key: --app-key-secret <NAME>");
     } else if (arg === "--verdict") {
       // `chant workspace records review <id> --verdict agree|dissent|abstain` (#2670)
       result.verdict = args[++i];
@@ -873,10 +884,13 @@ CI:
                         Reads check runs from the forge, pushes the tags.
   ci workflow [--workflow <name>]... [--output <file>]  Write
               [--chant <command>] [--install <command>]
+              [--token-secret <NAME> | --app-id-var <VAR> --app-key-secret <NAME>]
                         .github/workflows/chant-ci-green.yml, which runs the
                         tick when a required workflow completes and every 15m.
                         --chant replaces the npx @intentius/chant pin the tick
-                        runs; --install adds a step before it.
+                        runs; --install adds a step before it. --token-secret,
+                        or a GitHub App's id and key, pushes the tags with a
+                        token that may tag commits changing workflow files.
 
 Change sets:
   change-set summary <file>  The grouped plan summary of a change-set

package/src/cli/registry.ts

@@ -400,6 +400,12 @@ export interface ParsedArgs {
   ciChant?: string;
   /** `chant ci workflow --install <command>` (#3573): a step before the tick that installs what `--chant` runs. */
   ciInstall?: string;
+  /** `chant ci workflow --token-secret <NAME>` (#3573): the repository secret the tick's tag push authenticates with. */
+  ciTokenSecret?: string;
+  /** `chant ci workflow --app-id-var <VAR>` (#3573): the Actions variable holding the GitHub App id whose token pushes the tags. */
+  ciAppIdVar?: string;
+  /** `chant ci workflow --app-key-secret <NAME>` (#3573): the secret holding that App's private key. */
+  ciAppKeySecret?: string;
   /**
    * `chant workspace records review <id> --by <principal>` (#2670): the
    * reviewer, as the caller names them. Also `chant workspace records new

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)) {