@intentius/chant 0.44.5 → 0.44.6

package/dist/cli/commands/carve.d.ts

@@ -7,6 +7,8 @@
  * emit/boundary/apply phases stay in #197, gated on demand.
  */
 import { type Peelability } from "../../terraform/score.js";
+import { type BoundaryEdge } from "../../terraform/carve.js";
+import type { TfGraph } from "../../terraform/types.js";
 export interface CarveAdviseOptions {
     /** Terraform estate directory (from `--from`). */
     from?: string;
@@ -20,10 +22,65 @@ export interface CarveAdviseResult {
     error?: string;
     from?: string;
     results?: Peelability[];
+    /**
+     * The parsed dependency graph the scores came from. Kept so the JSON report
+     * can carry the boundary edge lists (#1636) rather than only their counts.
+     * Not part of the JSON payload — `carveJson` derives from it.
+     */
+    graph?: TfGraph;
 }
 export declare function carveAdvise(opts: CarveAdviseOptions): Promise<CarveAdviseResult>;
-/** The `--json` / `--report` payload. */
-export declare function carveJson(result: CarveAdviseResult): unknown;
+/**
+ * The schema version of the `--json` / `--report` payload (#1636).
+ *
+ * The report is a cross-tool contract — behold renders it as a graph — so it
+ * says which shape it is. The promise attached to this number:
+ *
+ *  - **Additive within a version.** New top-level fields, new per-resource
+ *    fields, and new entries in an existing list may appear in any release. A
+ *    reader must ignore keys it does not know.
+ *  - **A removal, a rename, or a changed meaning bumps it.** So does narrowing
+ *    a field's type (an optional becoming required is additive; the reverse is
+ *    not).
+ *  - A reader that does not know the version it is handed should refuse the
+ *    report rather than half-read it.
+ */
+export declare const CARVE_REPORT_VERSION = 1;
+/** One ranked resource in the JSON report: its score, plus the boundary its carve would cut. */
+export interface CarveJsonResource extends Peelability {
+    /**
+     * Every dependency edge carving this resource would cut (#1636), in chant's
+     * own `BoundaryEdge` shape — the same classification the emit/bridge path
+     * runs on. `inbound` edges need a Terraform `data`-source patch the moment
+     * the carve lands; `outbound` edges become deploy-time inputs, deferred
+     * until apply.
+     *
+     * The lists are the *carve set's* boundary, so a folded sub-resource never
+     * appears as an endpoint: it carves with its parent, and the parent's edges
+     * stand in for it. Edges internal to the carve set are not boundary work and
+     * are not listed.
+     *
+     * Present (possibly with two empty lists) whenever the graph was available;
+     * absent means this chant did not compute it — "none" and "not reported" are
+     * different claims. `breakdown.inbound`/`outbound` keep the counts.
+     */
+    boundary?: {
+        inbound: BoundaryEdge[];
+        outbound: BoundaryEdge[];
+    };
+}
+/** The `chant carve advise --json` / `--report` payload. Versioned; see {@link CARVE_REPORT_VERSION}. */
+export interface CarveJsonReport {
+    version: number;
+    from?: string;
+    advisory: string;
+    count: number;
+    /** Band name -> how many resources landed in it. */
+    bands: Record<string, number>;
+    resources: CarveJsonResource[];
+}
+/** Build the `--json` / `--report` payload. */
+export declare function carveJson(result: CarveAdviseResult): CarveJsonReport;
 /** Human-readable banded, ranked summary. */
 export declare function formatCarveReport(result: CarveAdviseResult): string;
 //# sourceMappingURL=carve.d.ts.map

package/dist/cli/commands/carve.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"carve.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/carve.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,EAAe,KAAK,WAAW,EAAwB,MAAM,uBAAuB,CAAC;AAE5F,MAAM,WAAW,kBAAkB;IACjC,kDAAkD;IAClD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,iFAAiF;IACjF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,wEAAwE;IACxE,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,OAAO,CAAC;IACZ,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,WAAW,EAAE,CAAC;CACzB;AAID,wBAAsB,WAAW,CAAC,IAAI,EAAE,kBAAkB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAwBtF;AAED,yCAAyC;AACzC,wBAAgB,SAAS,CAAC,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAY5D;AAED,6CAA6C;AAC7C,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,iBAAiB,GAAG,MAAM,CAyBnE"}
+{"version":3,"file":"carve.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/carve.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,EAAe,KAAK,WAAW,EAAwB,MAAM,uBAAuB,CAAC;AAC5F,OAAO,EAAkB,KAAK,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAC1E,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAC;AAErD,MAAM,WAAW,kBAAkB;IACjC,kDAAkD;IAClD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,iFAAiF;IACjF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,wEAAwE;IACxE,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,OAAO,CAAC;IACZ,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,WAAW,EAAE,CAAC;IACxB;;;;OAIG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAID,wBAAsB,WAAW,CAAC,IAAI,EAAE,kBAAkB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CA2BtF;AAED;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,oBAAoB,IAAI,CAAC;AAEtC,gGAAgG;AAChG,MAAM,WAAW,iBAAkB,SAAQ,WAAW;IACpD;;;;;;;;;;;;;;;OAeG;IACH,QAAQ,CAAC,EAAE;QAAE,OAAO,EAAE,YAAY,EAAE,CAAC;QAAC,QAAQ,EAAE,YAAY,EAAE,CAAA;KAAE,CAAC;CAClE;AAED,yGAAyG;AACzG,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,oDAAoD;IACpD,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC9B,SAAS,EAAE,iBAAiB,EAAE,CAAC;CAChC;AAED,+CAA+C;AAC/C,wBAAgB,SAAS,CAAC,MAAM,EAAE,iBAAiB,GAAG,eAAe,CAapE;AAUD,6CAA6C;AAC7C,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,iBAAiB,GAAG,MAAM,CAyBnE"}

package/package.json

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

package/src/cli/commands/carve.test.ts

@@ -2,7 +2,7 @@ import { describe, test, expect } from "vitest";
 import { mkdtempSync, writeFileSync, rmSync, readFileSync } from "fs";
 import { tmpdir } from "os";
 import { join } from "path";
-import { carveAdvise, carveJson, formatCarveReport } from "./carve";
+import { carveAdvise, carveJson, formatCarveReport, CARVE_REPORT_VERSION } from "./carve";
 import { loadHcl2json } from "../../terraform/parse";
 
 let parserAvailable = false;
@@ -78,9 +78,25 @@ describe("carveAdvise", () => {
 
       // report file is valid JSON with the advisory banner + band counts
       const payload = JSON.parse(readFileSync(reportFile, "utf-8"));
+      expect(payload.version).toBe(CARVE_REPORT_VERSION);
       expect(payload.advisory).toContain("read-only");
       expect(payload.bands["clean leaf"]).toBeGreaterThanOrEqual(1);
       expect(payload.count).toBe(r.results!.length);
+
+      // The written report carries the edge lists, not just the counts (#1636).
+      const written = payload.resources.find((x: { address: string }) => x.address === "aws_s3_bucket.assets");
+      expect(written.boundary.inbound).toEqual([
+        {
+          direction: "inbound",
+          survivor: "aws_lambda_function.api",
+          carved: "aws_s3_bucket.assets",
+          attrs: ["bucket"],
+          via: ["environment"],
+          bridge: "tf-data-source",
+          required: "immediately",
+        },
+      ]);
+      expect(written.boundary.outbound).toEqual([]);
     });
   });
 
@@ -96,9 +112,34 @@ describe("carveAdvise", () => {
     });
   });
 
-  test("carveJson carries the read-only advisory banner", () => {
-    const payload = carveJson({ ok: true, from: "x", results: [] }) as { advisory: string; count: number };
+  test("carveJson carries the read-only advisory banner and the schema version", () => {
+    const payload = carveJson({ ok: true, from: "x", results: [] });
     expect(payload.advisory).toContain("read-only");
     expect(payload.count).toBe(0);
+    expect(payload.version).toBe(1);
+  });
+
+  test("carveJson omits boundary entirely with no graph — 'none' and 'not reported' differ", () => {
+    const payload = carveJson({
+      ok: true,
+      from: "x",
+      results: [
+        {
+          address: "aws_vpc.main",
+          kind: "resource",
+          score: 100,
+          band: "clean leaf",
+          breakdown: {
+            inbound: 0,
+            outbound: 0,
+            tier: 1,
+            hasDynamic: false,
+            instances: 1,
+            penalties: { inbound: 0, outbound: 0, tier: 0, dynamic: 0, instances: 0 },
+          },
+        },
+      ],
+    });
+    expect(payload.resources[0]).not.toHaveProperty("boundary");
   });
 });

package/src/cli/commands/carve.ts

@@ -10,6 +10,8 @@
 import { existsSync, statSync, writeFileSync } from "fs";
 import { parseTerraformDir, Hcl2JsonNotInstalled } from "../../terraform/parse";
 import { scoreEstate, type Peelability, type PeelabilityBand } from "../../terraform/score";
+import { boundaryReport, type BoundaryEdge } from "../../terraform/carve";
+import type { TfGraph } from "../../terraform/types";
 
 export interface CarveAdviseOptions {
   /** Terraform estate directory (from `--from`). */
@@ -25,6 +27,12 @@ export interface CarveAdviseResult {
   error?: string;
   from?: string;
   results?: Peelability[];
+  /**
+   * The parsed dependency graph the scores came from. Kept so the JSON report
+   * can carry the boundary edge lists (#1636) rather than only their counts.
+   * Not part of the JSON payload — `carveJson` derives from it.
+   */
+  graph?: TfGraph;
 }
 
 const BAND_ORDER: PeelabilityBand[] = ["clean leaf", "carvable w/ edits", "leave in Terraform"];
@@ -40,36 +48,97 @@ export async function carveAdvise(opts: CarveAdviseOptions): Promise<CarveAdvise
     return { ok: false, error: `State file not found: ${opts.statePath}` };
   }
 
+  let graph: TfGraph;
   let results: Peelability[];
   try {
-    results = scoreEstate(await parseTerraformDir(opts.from, { statePath: opts.statePath }));
+    graph = await parseTerraformDir(opts.from, { statePath: opts.statePath });
+    results = scoreEstate(graph);
   } catch (err) {
     if (err instanceof Hcl2JsonNotInstalled) return { ok: false, error: err.message };
     return { ok: false, error: `Failed to parse Terraform in ${opts.from}: ${err instanceof Error ? err.message : String(err)}` };
   }
 
+  const result: CarveAdviseResult = { ok: true, from: opts.from, results, graph };
   if (opts.reportFile) {
-    writeFileSync(opts.reportFile, JSON.stringify(carveJson({ ok: true, from: opts.from, results }), null, 2));
+    writeFileSync(opts.reportFile, JSON.stringify(carveJson(result), null, 2));
   }
 
-  return { ok: true, from: opts.from, results };
+  return result;
 }
 
-/** The `--json` / `--report` payload. */
-export function carveJson(result: CarveAdviseResult): unknown {
+/**
+ * The schema version of the `--json` / `--report` payload (#1636).
+ *
+ * The report is a cross-tool contract — behold renders it as a graph — so it
+ * says which shape it is. The promise attached to this number:
+ *
+ *  - **Additive within a version.** New top-level fields, new per-resource
+ *    fields, and new entries in an existing list may appear in any release. A
+ *    reader must ignore keys it does not know.
+ *  - **A removal, a rename, or a changed meaning bumps it.** So does narrowing
+ *    a field's type (an optional becoming required is additive; the reverse is
+ *    not).
+ *  - A reader that does not know the version it is handed should refuse the
+ *    report rather than half-read it.
+ */
+export const CARVE_REPORT_VERSION = 1;
+
+/** One ranked resource in the JSON report: its score, plus the boundary its carve would cut. */
+export interface CarveJsonResource extends Peelability {
+  /**
+   * Every dependency edge carving this resource would cut (#1636), in chant's
+   * own `BoundaryEdge` shape — the same classification the emit/bridge path
+   * runs on. `inbound` edges need a Terraform `data`-source patch the moment
+   * the carve lands; `outbound` edges become deploy-time inputs, deferred
+   * until apply.
+   *
+   * The lists are the *carve set's* boundary, so a folded sub-resource never
+   * appears as an endpoint: it carves with its parent, and the parent's edges
+   * stand in for it. Edges internal to the carve set are not boundary work and
+   * are not listed.
+   *
+   * Present (possibly with two empty lists) whenever the graph was available;
+   * absent means this chant did not compute it — "none" and "not reported" are
+   * different claims. `breakdown.inbound`/`outbound` keep the counts.
+   */
+  boundary?: { inbound: BoundaryEdge[]; outbound: BoundaryEdge[] };
+}
+
+/** The `chant carve advise --json` / `--report` payload. Versioned; see {@link CARVE_REPORT_VERSION}. */
+export interface CarveJsonReport {
+  version: number;
+  from?: string;
+  advisory: string;
+  count: number;
+  /** Band name -> how many resources landed in it. */
+  bands: Record<string, number>;
+  resources: CarveJsonResource[];
+}
+
+/** Build the `--json` / `--report` payload. */
+export function carveJson(result: CarveAdviseResult): CarveJsonReport {
   const results = result.results ?? [];
   const counts = Object.fromEntries(
     BAND_ORDER.map((b) => [b, results.filter((r) => r.band === b).length]),
   );
   return {
+    version: CARVE_REPORT_VERSION,
     from: result.from,
     advisory: "read-only — emits nothing, patches nothing, touches no live resource",
     count: results.length,
     bands: counts,
-    resources: results,
+    resources: results.map((r) => withBoundary(r, result.graph)),
   };
 }
 
+/** A scored resource plus its carve boundary, when the graph is at hand (#1636). */
+function withBoundary(r: Peelability, graph?: TfGraph): CarveJsonResource {
+  if (!graph) return r;
+  const report = boundaryReport(graph, r.address);
+  if (!report) return r;
+  return { ...r, boundary: { inbound: report.inbound, outbound: report.outbound } };
+}
+
 /** Human-readable banded, ranked summary. */
 export function formatCarveReport(result: CarveAdviseResult): string {
   const results = result.results ?? [];

package/src/terraform/__fixtures__/advise.test.ts

@@ -1,6 +1,12 @@
 import { describe, test, expect } from "vitest";
 import { join } from "path";
-import { carveAdvise, formatCarveReport } from "../../cli/commands/carve";
+import {
+  carveAdvise,
+  carveJson,
+  formatCarveReport,
+  CARVE_REPORT_VERSION,
+  type CarveJsonResource,
+} from "../../cli/commands/carve";
 import { loadHcl2json } from "../parse";
 
 /**
@@ -49,3 +55,108 @@ describe("carve advise against the sample estate", () => {
     expect(text).not.toMatch(/state rm|apply|destroy/i);
   });
 });
+
+/**
+ * The JSON payload as a cross-tool contract (#1636): a schema version, and the
+ * boundary edge LISTS beside the counts. behold's carve lens renders these —
+ * the counts alone can't be paired back into edges (this estate has 4 inbound
+ * and 4 outbound, which admits several matchings), so the lists are the thing
+ * that makes a predicted diff drawable.
+ */
+describe("carve advise --json against the sample estate", () => {
+  test("is a versioned report whose resources carry their boundary edges", async () => {
+    if (!parserAvailable) return;
+    const report = carveJson(await carveAdvise({ from: ESTATE }));
+
+    expect(report.version).toBe(CARVE_REPORT_VERSION);
+    expect(report.count).toBe(8);
+    expect(report.resources).toHaveLength(8);
+
+    const byAddr = Object.fromEntries(report.resources.map((x) => [x.address, x]));
+
+    // The VPC's three subnets: each one a data-source patch to surviving TF.
+    expect(byAddr["aws_vpc.main"].boundary!.inbound).toEqual([
+      { direction: "inbound", survivor: "aws_subnet.a", carved: "aws_vpc.main", attrs: ["id"], via: ["vpc_id"], bridge: "tf-data-source", required: "immediately" },
+      { direction: "inbound", survivor: "aws_subnet.b", carved: "aws_vpc.main", attrs: ["id"], via: ["vpc_id"], bridge: "tf-data-source", required: "immediately" },
+      { direction: "inbound", survivor: "aws_subnet.c", carved: "aws_vpc.main", attrs: ["id"], via: ["vpc_id"], bridge: "tf-data-source", required: "immediately" },
+    ]);
+    expect(byAddr["aws_vpc.main"].boundary!.outbound).toEqual([]);
+
+    // The same cut, seen from the other end: the subnet's carve defers a value.
+    expect(byAddr["aws_subnet.a"].boundary!.outbound).toEqual([
+      { direction: "outbound", survivor: "aws_vpc.main", carved: "aws_subnet.a", attrs: ["id"], via: ["vpc_id"], bridge: "deferred-input", required: "at-apply" },
+    ]);
+
+    // A clean leaf nothing touches reports two empty lists, not a missing key:
+    // "none" is a claim the advisor is willing to make.
+    expect(byAddr["aws_cloudwatch_log_group.api"].boundary).toEqual({ inbound: [], outbound: [] });
+
+    // The Lambda reads two of the bucket's attributes — one edge, both attrs.
+    expect(byAddr["aws_lambda_function.api"].boundary!.outbound).toEqual([
+      { direction: "outbound", survivor: "aws_s3_bucket.assets", carved: "aws_lambda_function.api", attrs: ["arn", "bucket"], via: ["environment"], bridge: "deferred-input", required: "at-apply" },
+    ]);
+  });
+
+  test("every edge endpoint is a real Terraform address in the estate", async () => {
+    if (!parserAvailable) return;
+    const report = carveJson(await carveAdvise({ from: ESTATE }));
+    const ranked = new Set(report.resources.map((r) => r.address));
+
+    for (const edge of allEdges(report.resources)) {
+      // The carved side is always ranked — it is the resource reporting it.
+      expect(ranked.has(edge.carved)).toBe(true);
+      // The survivor side is a real address too. Every survivor in this estate
+      // is itself carvable, so it is ranked; in general a survivor may be an
+      // unranked address (a folded sub-resource's parent is never one, but an
+      // unsupported type is), which is why this checks the estate's own set.
+      expect(ranked.has(edge.survivor)).toBe(true);
+      expect(edge.survivor).not.toBe(edge.carved);
+    }
+  });
+
+  test("a folded sub-resource is never an edge endpoint — it carves with its parent", async () => {
+    if (!parserAvailable) return;
+    const report = carveJson(await carveAdvise({ from: ESTATE }));
+    const endpoints = allEdges(report.resources).flatMap((e) => [e.survivor, e.carved]);
+
+    // `aws_s3_bucket_versioning.assets` references its bucket, but that edge is
+    // internal to the bucket's carve set: not boundary work, and not an endpoint.
+    expect(endpoints).not.toContain("aws_s3_bucket_versioning.assets");
+    expect(report.resources.map((r) => r.address)).not.toContain("aws_s3_bucket_versioning.assets");
+  });
+
+  test("the counts and the edge lists tell the same story", async () => {
+    if (!parserAvailable) return;
+    const report = carveJson(await carveAdvise({ from: ESTATE }));
+
+    // `breakdown.inbound`/`outbound` are what the score was computed from and
+    // stay for backward compatibility. They must agree with the lists, or the
+    // arithmetic a reader prints beside the drawn edges is a lie.
+    for (const r of report.resources) {
+      expect([r.address, r.boundary!.inbound.length]).toEqual([r.address, r.breakdown.inbound]);
+      expect([r.address, r.boundary!.outbound.length]).toEqual([r.address, r.breakdown.outbound]);
+    }
+
+    const inbound = report.resources.reduce((s, r) => s + r.breakdown.inbound, 0);
+    const outbound = report.resources.reduce((s, r) => s + r.breakdown.outbound, 0);
+    expect([inbound, outbound]).toEqual([4, 4]);
+
+    // Each cut is reported from both ends — inbound from the depended-on side,
+    // outbound from the depending side — so the two totals are the same set of
+    // edges seen twice. Keyed in dependency direction, that is 4 distinct cuts.
+    const cuts = new Set(
+      allEdges(report.resources).map((e) =>
+        e.direction === "inbound" ? `${e.survivor} -> ${e.carved}` : `${e.carved} -> ${e.survivor}`,
+      ),
+    );
+    expect([...cuts].sort()).toEqual([
+      "aws_lambda_function.api -> aws_s3_bucket.assets",
+      "aws_subnet.a -> aws_vpc.main",
+      "aws_subnet.b -> aws_vpc.main",
+      "aws_subnet.c -> aws_vpc.main",
+    ]);
+  });
+});
+
+const allEdges = (resources: CarveJsonResource[]) =>
+  resources.flatMap((r) => [...(r.boundary?.inbound ?? []), ...(r.boundary?.outbound ?? [])]);