@intentius/chant 0.15.3 → 0.16.0

package/src/cli/handlers/graph.ts

@@ -1,8 +1,11 @@
 import { resolve } from "node:path";
 import { discoverOps } from "../../op/discover";
 import { discover } from "../../discovery/index";
-import { partitionByLexicon, computeStackGraph } from "../../build";
-import { buildGraphIr, type GraphIR } from "../../graph-ir";
+import { partitionByLexicon, computeStackGraph, build } from "../../build";
+import { buildGraphIr, buildLiveGraphIr, overlayGraphs, type GraphIR } from "../../graph-ir";
+import { reconstructEdges, mergeCatalogs, containmentGroups, type ReferenceCatalog, type ContainmentPair } from "../../graph-refs";
+import { observeResources } from "../../lifecycle/observe";
+import { loadChantConfig } from "../../config";
 import { applyDetail, type DetailLevel } from "../../graph-detail";
 import { applyLens, parseLens } from "../../graph-lens";
 import { toMermaid } from "../../graph-mermaid";
@@ -24,7 +27,13 @@ import { computeComponentGraph } from "../../components/cli-support";
  */
 export async function runGraph(ctx: CommandContext): Promise<number> {
   const viewFormats = ["ir", "mermaid", "dot", "layout"] as const;
-  if ((viewFormats as readonly string[]).includes(ctx.args.format)) {
+  const isViewFormat = (viewFormats as readonly string[]).includes(ctx.args.format);
+  // `--live` graphs the provisioned (observed) infrastructure, not the declared
+  // source (epic #776). It only makes sense as a view format; default to `ir`.
+  if (ctx.args.live) {
+    return runGraphLive(ctx, isViewFormat ? (ctx.args.format as (typeof viewFormats)[number]) : "ir");
+  }
+  if (isViewFormat) {
     return runGraphView(ctx, ctx.args.format as (typeof viewFormats)[number]);
   }
   if (ctx.args.components) return runComponentGraph(ctx);
@@ -32,6 +41,116 @@ export async function runGraph(ctx: CommandContext): Promise<number> {
   return runOpGraph();
 }
 
+/**
+ * `chant graph --live --env <name> [--format ir|mermaid|dot|layout]` — the
+ * **provisioned** graph (C1 of epic #776). Queries each lexicon's
+ * `describeResources()` for the environment (managed-only: `owned`) and projects
+ * the observed resources into IR nodes. Nodes only — edges are reconstructed by
+ * the reference resolver (#778), containment by #779. No lint gate: this reads
+ * the cloud, not source.
+ */
+async function runGraphLive(
+  ctx: CommandContext,
+  format: "ir" | "mermaid" | "dot" | "layout",
+): Promise<number> {
+  const { args, plugins } = ctx;
+  const environment = args.env;
+  if (!environment) {
+    console.error(formatError({ message: "chant graph --live needs an environment: --live --env <name>" }));
+    return 1;
+  }
+
+  const projectPath = resolve(".");
+  const { config } = await loadChantConfig(projectPath);
+  if (config.environments && !config.environments.includes(environment)) {
+    console.error(formatError({
+      message: `Unknown environment "${environment}"`,
+      hint: `Defined environments: ${config.environments.join(", ")}`,
+    }));
+    return 1;
+  }
+
+  // Build to get each lexicon's entity names + output (the scope
+  // describeResources needs), mirroring `chant lifecycle snapshot`.
+  const buildResult = await build(resolve(args.src ?? config.sourceDir ?? "."), plugins.map((p) => p.serializer));
+  if (buildResult.errors.length > 0) {
+    console.error(formatError({ message: "Build failed — fix errors before graphing live state" }));
+    return 1;
+  }
+
+  const observing = plugins.filter((p) => p.describeResources);
+  if (observing.length === 0) {
+    console.error(formatError({ message: "No lexicons implement describeResources — nothing to observe live." }));
+    return 1;
+  }
+
+  const { observations, errors } = await observeResources(environment, observing, buildResult, { owned: true });
+  for (const e of errors) console.error(formatWarning({ message: e }));
+
+  let ir: GraphIR = buildLiveGraphIr(observations);
+
+  // Enrich node attrs from the fuller live config (#784) so references are
+  // present for edge reconstruction — describeResources metadata alone is often
+  // too thin (e.g. AWS returns stack outputs, not per-resource references).
+  for (const p of observing) {
+    if (!p.enrichLiveAttrs) continue;
+    try {
+      const enriched = await p.enrichLiveAttrs({ environment, owned: true });
+      ir = {
+        ...ir,
+        nodes: ir.nodes.map((n) =>
+          n.lexicon === p.name && enriched[n.id] ? { ...n, attrs: { ...n.attrs, ...enriched[n.id] } } : n,
+        ),
+      };
+    } catch (err) {
+      console.error(formatWarning({ message: `${p.name}: live attr enrichment failed — edges may be sparse (${err instanceof Error ? err.message : String(err)})` }));
+    }
+  }
+
+  // Reconstruct edges + containment from live references (#778): merge the
+  // observing lexicons' reference catalogs and resolve them over the live nodes.
+  const catalogs = observing.map((p) => p.referenceCatalog).filter((c): c is ReferenceCatalog => !!c);
+  let containment: ContainmentPair[] = [];
+  if (catalogs.length > 0) {
+    const reconstructed = reconstructEdges(ir.nodes, mergeCatalogs(catalogs));
+    ir = { ...ir, edges: reconstructed.edges };
+    containment = reconstructed.containment;
+  }
+
+  // Drift overlay (#780): classify the provisioned graph against declared source
+  // (managed / foreign / pending) so a renderer colours the drift.
+  if (args.overlay) {
+    const declared = await discover(resolve(args.src ?? config.sourceDir ?? "."));
+    if (declared.errors.length === 0) {
+      ir = overlayGraphs(ir, buildGraphIr(declared.entities, projectPath));
+    } else {
+      console.error(formatWarning({ message: "overlay: source has discovery errors — showing the provisioned graph without the declared overlay" }));
+    }
+  }
+
+  if (args.lens) {
+    try {
+      ir = applyLens(ir, parseLens(args.lens, { up: args.up, down: args.down }));
+    } catch (err) {
+      console.error(formatError({ message: err instanceof Error ? err.message : String(err) }));
+      return 1;
+    }
+  }
+  ir = applyDetail(ir, (args.detail ?? 2) as DetailLevel);
+
+  // Containment grouping (#779) → boundary boxes. Built after lens/detail and
+  // filtered to surviving nodes, so a lens can't leave dangling group refs.
+  if (containment.length > 0) {
+    const present = new Set(ir.nodes.map((n) => n.id));
+    const byContainer = containmentGroups(containment.filter((c) => present.has(c.child) && present.has(c.parent)));
+    if (Object.keys(byContainer).length > 0) {
+      ir = { ...ir, groups: { ...ir.groups, byContainer } };
+    }
+  }
+
+  return emitIr(ir, ctx, format);
+}
+
 /**
  * `chant graph --components` (#560) — dependency order/waves for discovered
  * `Component` declarations, mirroring `runStackGraph`'s presentation
@@ -124,7 +243,16 @@ async function runGraphView(
     }
   }
   ir = applyDetail(ir, level as DetailLevel);
+  return emitIr(ir, ctx, format);
+}
 
+/** Emit a built IR in the requested view format — shared by the source
+ * (`runGraphView`) and live (`runGraphLive`) paths. */
+async function emitIr(
+  ir: GraphIR,
+  ctx: CommandContext,
+  format: "ir" | "mermaid" | "dot" | "layout",
+): Promise<number> {
   switch (format) {
     case "mermaid":
       console.log(toMermaid(ir));

package/src/cli/main.ts

@@ -92,6 +92,8 @@ export function parseArgs(args: string[]): ParsedArgs {
       }
     } else if (arg === "--live") {
       result.live = true;
+    } else if (arg === "--overlay") {
+      result.overlay = true;
     } else if (arg === "--from") {
       // Shared by `migrate --from <lexicon>` and `import --from <env>`; the
       // two commands never run together, so one field carries both.

package/src/cli/registry.ts

@@ -58,6 +58,9 @@ export interface ParsedArgs {
   env?: string;
   /** `chant graph --stacks` — render the cross-stack apply-ordering graph */
   stacks?: boolean;
+  /** `chant graph --live --overlay` — classify the provisioned graph against
+   * declared source: managed / foreign / pending (#780). */
+  overlay?: boolean;
   /** `chant list --components` / `chant graph --components` — surface discovered
    * `Component` declarations (#560) instead of/alongside lexicon resources. */
   components?: boolean;

package/src/graph-ir-live.test.ts

@@ -0,0 +1,88 @@
+import { describe, it, expect } from "vitest";
+import { buildLiveGraphIr, overlayGraphs, type LiveObservation, type GraphIR } from "./graph-ir";
+
+// A fixture "snapshot" — what a lexicon's describeResources() returns for a live
+// environment (managed-only). Two AWS resources; the subnet references the VPC by
+// physical id (that reference is #778's job, not this one — here we only project
+// nodes).
+const observations: LiveObservation[] = [
+  {
+    lexicon: "aws",
+    resources: {
+      "web-vpc": {
+        type: "AWS::EC2::VPC",
+        status: "CREATE_COMPLETE",
+        physicalId: "vpc-0a1b",
+        attributes: { CidrBlock: "10.0.0.0/16" },
+        ownership: "owned",
+      },
+      "app-subnet": {
+        type: "AWS::EC2::Subnet",
+        status: "CREATE_COMPLETE",
+        physicalId: "subnet-0c2d",
+        attributes: { VpcId: "vpc-0a1b", CidrBlock: "10.0.1.0/24" },
+        ownership: "owned",
+      },
+    },
+  },
+];
+
+describe("buildLiveGraphIr", () => {
+  it("projects observed resources into IR nodes — nodes only, no edges", () => {
+    const ir = buildLiveGraphIr(observations);
+    expect(ir.nodes.map((n) => n.id)).toEqual(["app-subnet", "web-vpc"]); // sorted
+    expect(ir.edges).toEqual([]);
+  });
+
+  it("carries kind, lexicon, physicalId, ownership, and live attrs on each node", () => {
+    const ir = buildLiveGraphIr(observations);
+    const vpc = ir.nodes.find((n) => n.id === "web-vpc")!;
+    expect(vpc.kind).toBe("AWS::EC2::VPC");
+    expect(vpc.lexicon).toBe("aws");
+    expect(vpc.physicalId).toBe("vpc-0a1b"); // the reference index key for #778
+    expect(vpc.ownership).toBe("owned");
+    expect(vpc.attrs).toEqual({ CidrBlock: "10.0.0.0/16" });
+  });
+
+  it("groups by lexicon and stack", () => {
+    const ir = buildLiveGraphIr(observations);
+    expect(ir.groups.byLexicon).toEqual({ aws: ["app-subnet", "web-vpc"] });
+    expect(ir.groups.byStack).toEqual({ aws: ["app-subnet", "web-vpc"] });
+  });
+
+  it("omits physicalId/ownership when the observation lacks them", () => {
+    const ir = buildLiveGraphIr([
+      { lexicon: "k8s", resources: { pod: { type: "Pod", status: "Running" } } },
+    ]);
+    const node = ir.nodes[0];
+    expect(node.physicalId).toBeUndefined();
+    expect(node.ownership).toBeUndefined();
+    expect(node.attrs).toEqual({});
+  });
+
+  it("is deterministic for a fixed observation set", () => {
+    expect(JSON.stringify(buildLiveGraphIr(observations))).toBe(
+      JSON.stringify(buildLiveGraphIr(observations)),
+    );
+  });
+});
+
+describe("overlayGraphs (#780 drift overlay)", () => {
+  const node = (id: string) => ({ id, kind: "AWS::EC2::VPC", lexicon: "aws", attrs: {} });
+  const live: GraphIR = { nodes: [node("web-vpc"), node("rogue-sg")], edges: [], groups: {} };
+  const declared: GraphIR = { nodes: [node("web-vpc"), node("planned-db")], edges: [], groups: {} };
+
+  it("classifies managed / foreign / pending via _status", () => {
+    const ir = overlayGraphs(live, declared);
+    const statusOf = (id: string) => (ir.nodes.find((n) => n.id === id)!.attrs as { _status?: string })._status;
+    expect(statusOf("web-vpc")).toBe("good"); // declared + provisioned
+    expect(statusOf("rogue-sg")).toBe("warn"); // provisioned, not declared → foreign
+    expect(statusOf("planned-db")).toBe("accent"); // declared, not provisioned → pending
+  });
+
+  it("appends pending nodes and keeps live edges/groups", () => {
+    const ir = overlayGraphs({ ...live, edges: [{ from: "rogue-sg", to: "web-vpc", kind: "ref" }] }, declared);
+    expect(ir.nodes.map((n) => n.id).sort()).toEqual(["planned-db", "rogue-sg", "web-vpc"]);
+    expect(ir.edges).toHaveLength(1);
+  });
+});

package/src/graph-ir.ts

@@ -5,6 +5,7 @@ import { type Declarable, isDeclarable } from "./declarable";
 import { isLexiconOutput, type LexiconOutput } from "./lexicon-output";
 import { getProvenance } from "./provenance";
 import { INTRINSIC_MARKER } from "./intrinsic";
+import type { ResourceMetadata } from "./lexicon";
 
 /**
  * Graph IR — the engine-neutral, lint-gated representation of a project's
@@ -54,6 +55,17 @@ export interface IRNode {
   attrs: Record<string, unknown>;
   /** Where the node was declared. */
   sourceLoc?: SourceLoc;
+  /**
+   * Live-only (`chant graph --live`): the observed physical identifier
+   * (id / ARN). Absent for source-derived IR. The reference resolver (#778)
+   * indexes on this to reconstruct edges from live resource references.
+   */
+  physicalId?: string;
+  /**
+   * Live-only: ownership verdict read from the resource's marker (#119/#120).
+   * `owned` = chant-managed. Absent for source-derived IR.
+   */
+  ownership?: "owned" | "foreign";
 }
 
 /** A directed dependency: `from` references an attribute of `to`. */
@@ -76,6 +88,12 @@ export interface IRGroups {
    * partition today; #513 phase 2 regroups by nested child-project. Consumers
    * (e.g. pinhole's boundary boxes) read this rather than inferring stacks. */
   byStack?: Record<string, string[]>;
+  /** Live containment (#779): a container node id → the node ids directly inside
+   * it (VPC → subnets/SGs, subnet → instances/service). Nested *flatly* — a
+   * subnet is both a member of its VPC's entry and a key with its own members —
+   * so a boundary-box renderer recurses it. Populated by `chant graph --live`
+   * from the reference resolver's containment output; absent for source IR. */
+  byContainer?: Record<string, string[]>;
 }
 
 /** A cross-stack export this stack publishes (a `stackOutput`/`output`): its
@@ -331,3 +349,75 @@ function sortKeys(rec: Record<string, string[]>): Record<string, string[]> {
   for (const k of Object.keys(rec).sort()) out[k] = rec[k];
   return out;
 }
+
+/** One lexicon's observed resources, keyed by logical name — the output of a
+ * plugin's `describeResources()`. The input to {@link buildLiveGraphIr}. */
+export interface LiveObservation {
+  lexicon: string;
+  resources: Record<string, ResourceMetadata>;
+}
+
+/**
+ * Build the graph IR from **live-observed** resources (`chant graph --live`) —
+ * the provisioned graph, not the declared one. This is the C1 half of epic #776:
+ * nodes only. Edges are reconstructed separately by the per-lexicon reference
+ * resolver (#778); containment grouping by #779. Pure and deterministic given a
+ * fixed observation set (nodes and group ids sorted), so the same snapshot yields
+ * identical IR.
+ *
+ * Each node carries the observed `physicalId` (the reference resolver's index
+ * key) and `ownership` marker. `attrs` is the resource's observed attributes.
+ */
+export function buildLiveGraphIr(observations: LiveObservation[]): GraphIR {
+  const nodes: IRNode[] = [];
+  const byLexicon: Record<string, string[]> = {};
+  const byStack: Record<string, string[]> = {};
+
+  for (const { lexicon, resources } of observations) {
+    for (const [name, meta] of Object.entries(resources)) {
+      const node: IRNode = {
+        id: name,
+        kind: meta.type,
+        lexicon,
+        attrs: meta.attributes ?? {},
+      };
+      if (meta.physicalId) node.physicalId = meta.physicalId;
+      if (meta.ownership) node.ownership = meta.ownership;
+      nodes.push(node);
+      (byLexicon[lexicon] ??= []).push(name);
+      // A live lexicon maps to one deployable stack, same as the source IR.
+      (byStack[lexicon] ??= []).push(name);
+    }
+  }
+
+  nodes.sort((a, b) => a.id.localeCompare(b.id));
+  for (const ids of Object.values(byLexicon)) ids.sort();
+  for (const ids of Object.values(byStack)) ids.sort();
+
+  const groups: IRGroups = {};
+  if (Object.keys(byLexicon).length) groups.byLexicon = sortKeys(byLexicon);
+  if (Object.keys(byStack).length) groups.byStack = sortKeys(byStack);
+
+  return { nodes, edges: [], groups };
+}
+
+/**
+ * Overlay the declared graph on the provisioned one (#780, `chant graph --live
+ * --overlay`) and classify each resource, tagging a `_status` a renderer colours:
+ *   - **managed** (declared + provisioned) → `good`
+ *   - **foreign** (provisioned, not declared) → `warn`
+ *   - **pending** (declared, not yet provisioned) → `accent`
+ * Live nodes keep their edges/containment; pending nodes are appended (they have
+ * no live edges). Sorted; the live groups pass through unchanged.
+ */
+export function overlayGraphs(live: GraphIR, declared: GraphIR): GraphIR {
+  const declaredIds = new Set(declared.nodes.map((n) => n.id));
+  const liveIds = new Set(live.nodes.map((n) => n.id));
+  const tagged = (n: IRNode, status: "good" | "warn" | "accent"): IRNode => ({ ...n, attrs: { ...n.attrs, _status: status } });
+
+  const nodes: IRNode[] = live.nodes.map((n) => tagged(n, declaredIds.has(n.id) ? "good" : "warn"));
+  for (const n of declared.nodes) if (!liveIds.has(n.id)) nodes.push(tagged(n, "accent"));
+  nodes.sort((a, b) => a.id.localeCompare(b.id));
+
+  return { ...live, nodes };
+}

package/src/graph-refs.test.ts

@@ -0,0 +1,131 @@
+import { describe, it, expect } from "vitest";
+import { reconstructEdges, readPath, mergeCatalogs, containmentGroups, type ReferenceCatalog } from "./graph-refs";
+import type { IRNode } from "./graph-ir";
+
+const node = (id: string, kind: string, attrs: Record<string, unknown>, physicalId?: string): IRNode => ({
+  id,
+  kind,
+  lexicon: "test",
+  attrs,
+  ...(physicalId ? { physicalId } : {}),
+});
+
+describe("readPath", () => {
+  it("reads nested keys", () => {
+    expect(readPath({ a: { b: "x" } }, "a.b")).toEqual(["x"]);
+  });
+  it("fans out over arrays", () => {
+    expect(readPath({ sgs: [{ id: "sg-1" }, { id: "sg-2" }] }, "sgs[].id")).toEqual(["sg-1", "sg-2"]);
+  });
+  it("reads an array of scalars", () => {
+    expect(readPath({ subnets: ["s-1", "s-2"] }, "subnets[]")).toEqual(["s-1", "s-2"]);
+  });
+  it("returns nothing for a missing path", () => {
+    expect(readPath({ a: 1 }, "b.c")).toEqual([]);
+  });
+});
+
+describe("reconstructEdges", () => {
+  // A tiny synthetic model: a "box" contains "things"; things reference a "peer".
+  const catalog: ReferenceCatalog = {
+    identities: [
+      { kind: "Box", ids: ["BoxId"] },
+      { kind: "Thing", ids: ["ThingId"] },
+      { kind: "Peer", ids: ["PeerId"] },
+    ],
+    refs: [
+      { from: "Thing", path: "boxId", targetKind: "Box", relation: "containment", label: "in box" },
+      { from: "Thing", path: "peerIds[]", targetKind: "Peer", relation: "reference", label: "uses" },
+    ],
+  };
+
+  const nodes: IRNode[] = [
+    node("box", "Box", { BoxId: "box-1" }),
+    node("thing", "Thing", { ThingId: "thing-1", boxId: "box-1", peerIds: ["peer-1", "peer-2"] }),
+    node("peerA", "Peer", { PeerId: "peer-1" }),
+    node("peerB", "Peer", { PeerId: "peer-2" }),
+  ];
+
+  it("emits reference edges (holder → referenced)", () => {
+    const { edges } = reconstructEdges(nodes, catalog);
+    expect(edges).toEqual([
+      { from: "thing", to: "peerA", kind: "ref", viaAttr: "uses" },
+      { from: "thing", to: "peerB", kind: "ref", viaAttr: "uses" },
+    ]);
+  });
+
+  it("emits containment separately, not as edges", () => {
+    const { edges, containment } = reconstructEdges(nodes, catalog);
+    expect(containment).toEqual([{ child: "thing", parent: "box", label: "in box" }]);
+    // containment is NOT in edges
+    expect(edges.some((e) => e.to === "box")).toBe(false);
+  });
+
+  it("surfaces references to absent targets as dangling, never a wrong edge", () => {
+    const withDangling = [...nodes, node("orphan", "Thing", { ThingId: "t-2", boxId: "box-1", peerIds: ["peer-GONE"] })];
+    const { edges, dangling } = reconstructEdges(withDangling, catalog);
+    expect(dangling).toContainEqual({ from: "orphan", path: "peerIds[]", value: "peer-GONE", targetKind: "Peer" });
+    expect(edges.some((e) => e.to === undefined)).toBe(false);
+  });
+
+  it("resolves against physicalId too", () => {
+    const cat: ReferenceCatalog = { identities: [], refs: [{ from: "Thing", path: "peer", relation: "reference" }] };
+    const ns = [node("t", "Thing", { peer: "phys-9" }), node("p", "Peer", {}, "phys-9")];
+    expect(reconstructEdges(ns, cat).edges).toEqual([{ from: "t", to: "p", kind: "ref", viaAttr: "peer" }]);
+  });
+
+  it("disambiguates identifier collisions by targetKind", () => {
+    const cat: ReferenceCatalog = {
+      identities: [{ kind: "A", ids: ["id"] }, { kind: "B", ids: ["id"] }],
+      refs: [{ from: "H", path: "ref", targetKind: "B", relation: "reference" }],
+    };
+    const ns = [node("a", "A", { id: "dup" }), node("b", "B", { id: "dup" }), node("h", "H", { ref: "dup" })];
+    expect(reconstructEdges(ns, cat).edges).toEqual([{ from: "h", to: "b", kind: "ref", viaAttr: "ref" }]);
+  });
+
+  it("drops self-references", () => {
+    const cat: ReferenceCatalog = { identities: [{ kind: "SG", ids: ["id"] }], refs: [{ from: "SG", path: "peers[]", relation: "reference" }] };
+    const ns = [node("sg", "SG", { id: "sg-1", peers: ["sg-1"] })];
+    expect(reconstructEdges(ns, cat).edges).toEqual([]);
+  });
+
+  it("is deterministic", () => {
+    expect(JSON.stringify(reconstructEdges(nodes, catalog))).toBe(JSON.stringify(reconstructEdges(nodes, catalog)));
+  });
+});
+
+describe("containmentGroups", () => {
+  it("inverts pairs into container → members, representing nesting flatly", () => {
+    const groups = containmentGroups([
+      { child: "subnetA", parent: "vpc" },
+      { child: "subnetB", parent: "vpc" },
+      { child: "instance1", parent: "subnetA" },
+    ]);
+    // vpc contains its subnets; subnetA is a key with its own members (nesting).
+    expect(groups).toEqual({ vpc: ["subnetA", "subnetB"], subnetA: ["instance1"] });
+  });
+
+  it("dedupes members and sorts keys + members", () => {
+    expect(
+      containmentGroups([
+        { child: "b", parent: "a" },
+        { child: "b", parent: "a" },
+        { child: "a", parent: "z" },
+      ]),
+    ).toEqual({ a: ["b"], z: ["a"] });
+  });
+
+  it("is empty for no containment", () => {
+    expect(containmentGroups([])).toEqual({});
+  });
+});
+
+describe("mergeCatalogs", () => {
+  it("concatenates identities and refs", () => {
+    const a: ReferenceCatalog = { identities: [{ kind: "A", ids: ["x"] }], refs: [{ from: "A", path: "p", relation: "reference" }] };
+    const b: ReferenceCatalog = { identities: [{ kind: "B", ids: ["y"] }], refs: [] };
+    const m = mergeCatalogs([a, b]);
+    expect(m.identities).toHaveLength(2);
+    expect(m.refs).toHaveLength(1);
+  });
+});