@intentius/chant 0.75.0 → 0.75.1

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":"AAwBA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAiHlD;;;;;;;;;GASG;AACH,wBAAsB,QAAQ,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAkDnE"}
+{"version":3,"file":"graph.d.ts","sourceRoot":"","sources":["../../../src/cli/handlers/graph.ts"],"names":[],"mappings":"AAwBA,OAAO,KAAK,EAAE,cAAc,EAAc,MAAM,aAAa,CAAC;AAkH9D;;;;;;;;;GASG;AACH,wBAAsB,QAAQ,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAwCnE"}

package/dist/cli/main.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../src/cli/main.ts"],"names":[],"mappings":";AAMA,OAAO,EAAkB,KAAK,UAAU,EAAE,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AA0F9E;;GAEG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,UAAU,CA8WpD;AAocD;;;;;;;;;GASG;AACH,eAAO,MAAM,eAAe,EAAE,UAAU,EAmGvC,CAAC;AAqIF;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,CAAC,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAuB5E"}
+{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../src/cli/main.ts"],"names":[],"mappings":";AAMA,OAAO,EAAkB,KAAK,UAAU,EAAE,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AA0F9E;;GAEG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,UAAU,CA8WpD;AAqcD;;;;;;;;;GASG;AACH,eAAO,MAAM,eAAe,EAAE,UAAU,EAmGvC,CAAC;AAqIF;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,CAAC,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAuB5E"}

package/package.json

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

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

@@ -259,6 +259,66 @@ describe("runGraph", () => {
         expect(ir.nodes.find((n: { id: string }) => n.id === "deploy").attrs.phases).toEqual([]);
       });
 
+      // #2377 / epic #2355: "the live path predicts the account as it stands,
+      // drift included. The declared path predicts the file. The two are shown
+      // as a delta." An earlier draft of #2377 required --live, which forbade
+      // the declared half and so forbade the delta.
+      test("--traffic predicts the declared graph, without --live", async () => {
+        lintClean(); discovered();
+        const seen: Array<{ traffic: string; environment: string }> = [];
+        loadPluginsMock.mockResolvedValue([{
+          name: "gcp",
+          serializer: {},
+          predictBehaviour: (o: { traffic: string; environment: string }) => {
+            seen.push({ traffic: o.traffic, environment: o.environment });
+            return Promise.resolve(behaviourReport(
+              { entityNames: ["vpc"], traffic: o.traffic, edgeCoverage: { verdict: "unknown" } },
+              { engine: "fixture", version: "0.0.1", total: predictedRate(1, "USD") },
+              { vpc: {
+                at: { traffic: o.traffic },
+                cost: predictedRate(1, "USD"),
+                headroom: { cpu: 0.5 },
+                errorRate: 0,
+                resilience: { failure: "one zone lost", verdict: "survives" },
+                provenance: { engine: "fixture", version: "0.0.1", tolerance: "±20%", basis: "modeled" },
+              } },
+              {},
+            ));
+          },
+        }]);
+        resolveLexMock.mockResolvedValue(["gcp"]);
+
+        const exit = await runGraph({
+          args: makeArgs({ format: "ir", traffic: "100 rps, p50" }),
+          plugins: [], serializers: [],
+        });
+
+        expect(exit).toBe(0);
+        expect(seen[0]?.traffic).toBe("100 rps, p50");
+        const ir = JSON.parse(stdoutBuf.join("\n"));
+        expect(ir.meta?._behaviour?.engine).toBe("fixture");
+        expect(ir.nodes.find((n: { id: string }) => n.id === "vpc").attrs._behaviour.cost.perHour).toBe(1);
+      });
+
+      test("the declared path names no environment, because the file is deployed nowhere", async () => {
+        lintClean(); discovered();
+        const seen: string[] = [];
+        loadPluginsMock.mockResolvedValue([{
+          name: "gcp",
+          serializer: {},
+          predictBehaviour: (o: { environment: string }) => {
+            seen.push(o.environment);
+            return Promise.resolve(noBehaviourEngineRefusal("gcp"));
+          },
+        }]);
+        resolveLexMock.mockResolvedValue(["gcp"]);
+
+        await runGraph({ args: makeArgs({ format: "ir", traffic: "100 rps, p50" }), plugins: [], serializers: [] });
+
+        // Naming one would claim the declared estate was deployed there.
+        expect(seen[0]).toBe("");
+      });
+
       test("op-discovery errors are warnings, not a refusal", async () => {
         lintClean(); discovered();
         discoverOpsMock.mockResolvedValue({ ops: new Map(), errors: ["ops/bad.op.ts: boom"] });
@@ -790,18 +850,6 @@ describe("runGraph", () => {
         expect(ir.meta?._behaviour).toBeUndefined();
       });
 
-      test("--traffic without --live is refused rather than silently ignored", async () => {
-        // Accepted-and-ignored would read as "predicted, and everything came
-        // back empty", which is the opposite of what happened.
-        const exit = await runGraph({
-          args: makeArgs({ format: "ir", traffic: "100 rps, p50" }),
-          plugins: [], serializers: [],
-        });
-
-        expect(exit).toBe(1);
-        expect(stderrBuf.join("\n")).toContain("--traffic needs --live");
-      });
-
       test("two predicting lexicons is refused rather than attributed to one", async () => {
         liveEstate();
         loadPluginsMock.mockResolvedValue([

package/src/cli/handlers/graph.ts

@@ -22,7 +22,8 @@ import { lintCommand } from "../commands/lint";
 import { loadPlugins, resolveProjectLexicons, collectBuildRootContributors } from "../plugins";
 import { readFileSync } from "node:fs";
 import { formatError, formatWarning, formatBold } from "../format";
-import type { CommandContext } from "../registry";
+import type { CommandContext, ParsedArgs } from "../registry";
+import type { LexiconPlugin } from "../../lexicon";
 import { computeComponentGraph, generateComponentsPipeline } from "../../components/cli-support";
 import { resolveCliBuildParams, parseParamFlags } from "../build-params-cli";
 import type { BuildParamProvenance } from "../../provenance";
@@ -160,16 +161,6 @@ export async function runGraph(ctx: CommandContext): Promise<number> {
     }));
     return 1;
   }
-  // A prediction is about an estate, and only the live path has one. Without
-  // `--live` the flag would be accepted and do nothing at all, which reads as
-  // "predicted, and everything came back empty" rather than "never ran".
-  if (ctx.args.traffic && !ctx.args.live) {
-    console.error(formatError({
-      message: "--traffic needs --live: a prediction is made about the observed estate, and there is nothing to predict on the declared graph alone.",
-      hint: 'chant graph --format ir --live --env <name> --overlay --traffic "100 rps, p50"',
-    }));
-    return 1;
-  }
   // `--at` graphs a recorded observation instead of reading the estate (#1279).
   // Two different observations with no rule for which wins, so not both.
   if (ctx.args.at && ctx.args.live) {
@@ -448,68 +439,16 @@ async function runGraphLive(
   }
 
   // Behaviour overlay (#2377, epic #2355): carry a prediction on the graph.
-  //
-  // `--traffic` is the trigger, and it is the trigger because the contract
-  // forbids defaulting the level (../../behaviour.ts): every figure an engine
-  // returns is *at* a stated traffic, so inventing one here would silently
-  // decide what every number on the graph means. No flag: nothing is asked,
-  // neither key appears, and a consumer reads that absence as "not looked".
-  //
-  // Placed after the drift overlay so the prediction lands on the final node
-  // set — the canvas is settled by here under either anchoring — and before
-  // the lens below, so a lens filters predicted nodes like any other.
-  if (args.traffic) {
-    const predicting = plugins.filter((p) => p.predictBehaviour);
-    if (predicting.length === 0) {
-      console.error(formatWarning({
-        message:
-          "--traffic: no installed lexicon implements predictBehaviour, so nothing was predicted. The graph is unchanged.",
-      }));
-    } else if (predicting.length > 1) {
-      // Two engines would mean two `meta._behaviour` values and one key. Rather
-      // than pick, say so: a merged prediction across engines is not defined by
-      // the contract, and silently taking the first would attribute one
-      // engine's figures to the other's provenance.
-      console.error(formatError({
-        message: `--traffic: ${predicting.length} lexicons implement predictBehaviour (${predicting.map((p) => p.name).join(", ")}) — chant cannot merge two engines' figures onto one graph.`,
-        hint: "Predict one lexicon at a time, or drop --traffic to graph without a prediction",
-      }));
-      return 1;
-    } else {
-      // The first output the build produced, or empty. Nothing on this path
-      // reads it — the mirror is kept so the four observation methods take the
-      // same shape (../../op/activities/predict-behaviour.ts) — so a build
-      // result without outputs costs an empty string, never the graph.
-      const raw = buildResult.outputs ? [...buildResult.outputs.values()][0] : undefined;
-      const buildOutput = raw === undefined ? "" : typeof raw === "string" ? raw : (raw as SerializerResult).primary;
-      const request = behaviourRequestFromIr(ir, {
-        environment: environment ?? "",
-        traffic: args.traffic,
-        buildOutput,
-        // `unknown`, for the reason the declared path claims it
-        // (../../op/activities/predict-behaviour.ts): reference edges resolved,
-        // containment absent, and no vocabulary here for "this kind is a
-        // boundary whose containment is missing". Claiming `complete` would be
-        // true about references and false about the graph; `partial` has to
-        // name its gap as `dangling` or `unresolvedKinds`, and this gap is
-        // neither.
-        edgeCoverage: { verdict: "unknown" },
-        ...(args.owned === undefined ? {} : { owned: args.owned }),
-      });
-      try {
-        // A refusal is a value, not a throw: it comes back as a result and
-        // rides on `meta._behaviour` whole, which is the one shape behold's
-        // reader branches on (../../behaviour-overlay.ts).
-        const result = await predicting[0].predictBehaviour!(request);
-        ir = applyBehaviourOverlay(ir, behaviourOverlay(result));
-      } catch (err) {
-        // The estate graph is the thing asked for; a broken engine must not
-        // take it away. Say what failed and serve the graph without the block.
-        console.error(formatWarning({
-          message: `--traffic: ${predicting[0].name}'s predictBehaviour failed (${err instanceof Error ? err.message : String(err)}) — showing the graph without a prediction`,
-        }));
-      }
-    }
+  // After the drift overlay so it lands on the final node set beside `_status`,
+  // and before the lens so a lens filters a predicted node like any other.
+  {
+    const raw = buildResult.outputs ? [...buildResult.outputs.values()][0] : undefined;
+    const predicted = await predictOntoIr(ir, plugins, args, {
+      environment: environment ?? "",
+      buildOutput: raw === undefined ? "" : typeof raw === "string" ? raw : (raw as SerializerResult).primary,
+    });
+    if (predicted === REFUSED) return 1;
+    ir = predicted;
   }
 
   if (args.lens) {
@@ -732,6 +671,82 @@ async function buildPipelineProjection(
  * Lint-gated: the IR represents valid infra, so we refuse to emit for source that
  * does not pass lint. Non-zero on discovery errors or a layout-engine failure.
  */
+/** Returned instead of a graph when the prediction cannot be attempted honestly. */
+const REFUSED = Symbol("behaviour-refused");
+
+/**
+ * Carry a prediction on `ir`, if one was asked for (#2377, epic #2355).
+ *
+ * Shared by both graph paths, because the epic wants both: "the live path
+ * predicts the account as it stands, drift included. The declared path
+ * predicts the file. The two are shown as a delta" (#2355). A delta between
+ * two shapes that reached the engine by different routes is the worst possible
+ * input to a delta, so there is one route.
+ *
+ * `--traffic` is the trigger, and it is the trigger rather than the engine
+ * variable because the contract forbids defaulting the level
+ * (../../behaviour.ts): every figure an engine returns is *at* a stated
+ * traffic, so inventing one would silently decide what every number on the
+ * graph means. Without the flag nothing is asked, neither key appears, and a
+ * consumer reads that absence as "not looked" rather than as a refusal.
+ */
+async function predictOntoIr(
+  ir: GraphIR,
+  plugins: LexiconPlugin[],
+  args: ParsedArgs,
+  ctx: { environment: string; buildOutput: string },
+): Promise<GraphIR | typeof REFUSED> {
+  if (!args.traffic) return ir;
+
+  const predicting = plugins.filter((p) => p.predictBehaviour);
+  if (predicting.length === 0) {
+    console.error(formatWarning({
+      message:
+        "--traffic: no installed lexicon implements predictBehaviour, so nothing was predicted. The graph is unchanged.",
+    }));
+    return ir;
+  }
+  if (predicting.length > 1) {
+    // Two engines would mean two `meta._behaviour` values and one key. Rather
+    // than pick, say so: a merged prediction across engines is not defined by
+    // the contract, and silently taking the first would attribute one engine's
+    // figures to the other's provenance.
+    console.error(formatError({
+      message: `--traffic: ${predicting.length} lexicons implement predictBehaviour (${predicting.map((p) => p.name).join(", ")}) — chant cannot merge two engines' figures onto one graph.`,
+      hint: "Predict one lexicon at a time, or drop --traffic to graph without a prediction",
+    }));
+    return REFUSED;
+  }
+
+  const request = behaviourRequestFromIr(ir, {
+    environment: ctx.environment,
+    traffic: args.traffic,
+    buildOutput: ctx.buildOutput,
+    // `unknown`, for the reason the declared path claims it
+    // (../../op/activities/predict-behaviour.ts): reference edges resolved,
+    // containment absent, and no vocabulary here for "this kind is a boundary
+    // whose containment is missing". Claiming `complete` would be true about
+    // references and false about the graph; `partial` has to name its gap as
+    // `dangling` or `unresolvedKinds`, and this gap is neither.
+    edgeCoverage: { verdict: "unknown" },
+    ...(args.owned === undefined ? {} : { owned: args.owned }),
+  });
+
+  try {
+    // A refusal is a value, not a throw: it comes back as a result and rides on
+    // `meta._behaviour` whole, which is the one shape behold's reader branches
+    // on (../../behaviour-overlay.ts).
+    return applyBehaviourOverlay(ir, behaviourOverlay(await predicting[0].predictBehaviour!(request)));
+  } catch (err) {
+    // The estate graph is the thing asked for; a broken engine must not take it
+    // away. Say what failed and serve the graph without the block.
+    console.error(formatWarning({
+      message: `--traffic: ${predicting[0].name}'s predictBehaviour failed (${err instanceof Error ? err.message : String(err)}) — showing the graph without a prediction`,
+    }));
+    return ir;
+  }
+}
+
 async function runGraphView(
   ctx: CommandContext,
   format: "ir" | "mermaid" | "dot" | "layout",
@@ -788,6 +803,24 @@ async function runGraphView(
   // Build the base IR, focus with a lens (declarable-level, most precise), then
   // apply the detail tier — so e.g. blast:<resource> works before any collapse.
   let ir: GraphIR = buildGraphIr(result.entities, projectPath);
+
+  // The declared half of the epic's delta (#2355): this path predicts the
+  // file, the live path predicts the account. Same helper, so the two shapes
+  // reach the engine by one route and stay comparable.
+  {
+    const plugins = ctx.plugins.length > 0
+      ? ctx.plugins
+      : await loadPlugins(await resolveProjectLexicons(projectPath));
+    const predicted = await predictOntoIr(ir, plugins as LexiconPlugin[], ctx.args, {
+      // No environment on the declared path: the file is not deployed anywhere
+      // yet, and naming one would claim it was.
+      environment: ctx.args.env ?? "",
+      buildOutput: "",
+    });
+    if (predicted === REFUSED) return 1;
+    ir = predicted;
+  }
+
   if (ctx.args.lens) {
     try {
       ir = applyLens(ir, parseLens(ctx.args.lens, { up: ctx.args.up, down: ctx.args.down }));

package/src/cli/main.ts

@@ -599,11 +599,12 @@ Ops:
                         add the CI/pipeline projection (stages/jobs/needs) to
                         the component-graph IR, from the same generator
                         'build --components --generate' uses (#989)
-                        --live --overlay --traffic "<level>": ask the project's
-                        predicting lexicon what the overlaid estate does at that
-                        traffic level, and carry each entity's prediction on the
-                        IR. The level is passed to the engine verbatim; without
-                        the flag nothing is asked and nothing is carried (#2377)
+                        --traffic "<level>": ask the project's predicting
+                        lexicon what the estate does at that traffic level, and
+                        carry each entity's prediction on the IR. On the
+                        declared graph it predicts the file; with --live it
+                        predicts the account. The level reaches the engine
+                        verbatim; without the flag nothing is asked (#2377)
 
 Lifecycle (alias: lc):
   lifecycle snapshot <env>  Query API, save metadata to orphan branch