@intentius/chant 0.33.0 → 0.34.0

package/src/cli/handlers/lifecycle.ts

@@ -62,6 +62,11 @@ interface StackTarget {
   /** Build root to synthesize this stack from, scoped so its logical ids match
    * what the stack actually deploys. */
   root: string;
+  /** Region the stack is deployed in, from `stacks[].region` (#1261). Without
+   * it every stack is observed against the ambient region, so a multi-region
+   * estate snapshots only the stacks that happen to share it and reports the
+   * rest as "no valid resources or artifacts returned". */
+  region?: string;
 }
 
 /**
@@ -75,7 +80,7 @@ interface StackTarget {
 function resolveStackTargets(args: ParsedArgs, config: ChantConfig): StackTarget[] {
   if (args.src) return [{ root: resolve(args.src) }];
   if (config.stacks && config.stacks.length > 0) {
-    return config.stacks.map((s) => ({ stack: s.name, root: resolve(s.src) }));
+    return config.stacks.map((s) => ({ stack: s.name, root: resolve(s.src), region: s.region }));
   }
   return [{ root: resolveBuildRoot(args, config) }];
 }
@@ -133,19 +138,39 @@ export async function runLifecycleSnapshot(ctx: CommandContext): Promise<number>
   const endpointResult = applyLiveEndpoint(config.environments, environment, observingPlugins.map((p) => p.name));
   if (endpointResult.notice) console.error(formatWarning({ message: endpointResult.notice }));
 
+  // Build every stack first, so the ambient scan (#1278) can be bounded by the
+  // kinds the PROJECT manages rather than the ones this stack happens to
+  // declare. "Which of my security groups are unused" is a question about the
+  // estate; a region whose stack declares no security group still has a default
+  // one, and scoping the bound per stack silently drops it.
+  const built: Array<{ target: (typeof targets)[number]; buildResult: Awaited<ReturnType<typeof build>> }> = [];
+  for (const target of targets) {
+    const label = target.stack ? `stack "${target.stack}"` : "project";
+    const buildResult = await build(target.root, targetSerializers);
+    if (buildResult.errors.length > 0) {
+      console.error(formatError({ message: `Build failed for ${label} — fix errors before taking a snapshot` }));
+      anyHardError = true;
+      continue;
+    }
+    built.push({ target, buildResult });
+  }
+  const projectKinds = [
+    ...new Set(built.flatMap(({ buildResult }) => [...buildResult.entities.values()].map((e) => e.entityType))),
+  ];
+
   try {
-    for (const target of targets) {
+    for (const { target, buildResult } of built) {
       const label = target.stack ? `stack "${target.stack}"` : "project";
-      const buildResult = await build(target.root, targetSerializers);
-      if (buildResult.errors.length > 0) {
-        console.error(formatError({ message: `Build failed for ${label} — fix errors before taking a snapshot` }));
-        anyHardError = true;
-        continue;
-      }
 
       let result;
       try {
-        result = await takeSnapshot(environment, observingPlugins, buildResult, { stack: target.stack });
+        result = await takeSnapshot(environment, observingPlugins, buildResult, {
+          stack: target.stack,
+          region: target.region,
+          deep: args.deep,
+          ambient: args.ambient,
+          ambientKinds: projectKinds,
+        });
       } catch (err) {
         if (err instanceof StaleLifecycleBranchError) {
           console.error(formatError({
@@ -214,7 +239,15 @@ export async function runLifecycleShow(ctx: CommandContext): Promise<number> {
 
     for (const [lexicon, content] of snapshots) {
       const snapshot: LifecycleSnapshot = JSON.parse(content);
-      console.log(`\n${formatBold(`${environment}/${lexicon}`)} — ${Object.keys(snapshot.resources).length} resources — ${snapshot.timestamp}`);
+      // Depth is stated, not inferred (#1267). An identity snapshot cannot
+      // answer a property question, and a reader that assumes otherwise reads
+      // "no properties recorded" as "no such properties".
+      const depth = snapshot.depth ?? "identity";
+      const depthNote =
+        depth === "deep"
+          ? ` — deep (${Object.keys(snapshot.properties ?? {}).length} property trees)`
+          : " — identity only";
+      console.log(`\n${formatBold(`${environment}/${lexicon}`)} — ${Object.keys(snapshot.resources).length} resources${depthNote} — ${snapshot.timestamp}`);
       printSnapshotTable(snapshot);
     }
   }

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

@@ -1,7 +1,7 @@
 import { describe, test, expect, vi } from "vitest";
 import { __searchInternals } from "./search";
 
-const { parseQuery, matchTerm, formatRow, explain, describeTerm } = __searchInternals;
+const { parseQuery, matchTerm, formatRow, explain, describeTerm, derivedSurface, availableAttrs, ambientHint, regionSpread, showMiss } = __searchInternals;
 
 function node(id: string, kind: string, attrs: Record<string, unknown> = {}) {
   return { id, kind, lexicon: "aws", attrs } as never;
@@ -57,9 +57,23 @@ describe("search formatting", () => {
     expect(formatRow(src, [])).toBe("webServer  AWS::EC2::Instance");
   });
 
-  test("--show adds named primitive attributes only", () => {
-    const n = node("web", "AWS::EC2::Instance", { physicalId: "i-1", InstanceType: "t3.micro", Tags: [{}] });
-    expect(formatRow(n, ["InstanceType", "Tags"])).toBe("web  AWS::EC2::Instance  i-1  InstanceType=t3.micro");
+  test("--show renders a named column whatever shape the value is", () => {
+    // A list used to be dropped silently, so `--show effectiveIngress` — the
+    // derived reachability fact — printed a blank column and read as "chant
+    // does not have this". A column the caller named is a column they get.
+    const n = node("web", "AWS::EC2::Instance", {
+      physicalId: "i-1",
+      InstanceType: "t3.micro",
+      effectiveIngress: ["tcp:22:0.0.0.0/0"],
+    });
+    expect(formatRow(n, ["InstanceType", "effectiveIngress"])).toBe(
+      'web  AWS::EC2::Instance  i-1  InstanceType=t3.micro  effectiveIngress=["tcp:22:0.0.0.0/0"]',
+    );
+  });
+
+  test("--show omits a column the node does not carry", () => {
+    const n = node("web", "AWS::EC2::Instance", { physicalId: "i-1" });
+    expect(formatRow(n, ["VpcId"])).toBe("web  AWS::EC2::Instance  i-1");
   });
 });
 
@@ -111,3 +125,231 @@ describe("search edge traversal", () => {
       .toBe("→attr:MapPublicIpOnLaunch=true (no such edge)");
   });
 });
+
+describe("search surfaces what the graph derived", () => {
+  const insts = [
+    node("webServer", "AWS::EC2::Instance", { internetFacing: true, internetFacingVia: "rtb-1 → igw-1", effectiveIngress: ["tcp:22:0.0.0.0/0"] }),
+    node("privServer", "AWS::EC2::Instance", { internetFacing: false, effectiveIngress: [] }),
+  ];
+  const derivedIr = { nodes: insts, edges: [], groups: {}, derivedAttrs: { Instance: ["internetFacing", "effectiveIngress"] } } as never;
+
+  function capture(fn: () => void): string {
+    const lines: string[] = [];
+    const spy = vi.spyOn(console, "log").mockImplementation((s: string) => { lines.push(s); });
+    fn();
+    spy.mockRestore();
+    return lines.join("\n");
+  }
+
+  test("names derived facts the query did not use, and omits the ones it did", () => {
+    const out = capture(() => derivedSurface(parseQuery("kind:EC2::Instance attr:internetFacing=true") as never, insts as never, derivedIr));
+    expect(out).toContain("effectiveIngress");
+    expect(out).not.toContain("internetFacing");
+  });
+
+  test("says nothing when the query already used every derived fact", () => {
+    const q = "kind:EC2::Instance attr:internetFacing=true attr:effectiveIngress=tcp:22:0.0.0.0/0";
+    expect(capture(() => derivedSurface(parseQuery(q) as never, insts as never, derivedIr))).toBe("");
+  });
+
+  test("says nothing for a graph with no derived facts recorded", () => {
+    const plain = { nodes: insts, edges: [], groups: {} } as never;
+    expect(capture(() => derivedSurface(parseQuery("kind:EC2::Instance") as never, insts as never, plain))).toBe("");
+  });
+
+  test("a miss lists the attributes the queried kind actually carries", () => {
+    const out = capture(() => availableAttrs(parseQuery("kind:EC2::Instance attr:nosuchattr=1") as never, derivedIr));
+    expect(out).toContain("effectiveIngress");
+    expect(out).toContain("internetFacing");
+    expect(out).not.toContain("nosuchattr");
+  });
+
+  test("inclusion evidence is keyed off <attr>Via provenance, not a fixed attribute name", () => {
+    const byId = new Map(insts.map((n: { id: string }) => [n.id, n]));
+    const q = "attr:internetFacing=true";
+    const out = capture(() => explain(parseQuery(q) as never, [insts[0]] as never, derivedIr, byId as never, q));
+    expect(out).toContain("webServer internetFacing via rtb-1 → igw-1");
+  });
+});
+
+// #1280 — absence is a real estate question ("what does nothing reference"),
+// and the grammar could only express presence.
+describe("negated terms (#1280)", () => {
+  const ir = {
+    nodes: [
+      { id: "used", kind: "AWS::EC2::SecurityGroup", lexicon: "aws", attrs: {} },
+      { id: "spare", kind: "AWS::EC2::SecurityGroup", lexicon: "aws", attrs: {} },
+      { id: "web", kind: "AWS::EC2::Instance", lexicon: "aws", attrs: {} },
+    ],
+    edges: [{ from: "web", to: "used", kind: "ref" as const, viaAttr: "SecurityGroupIds" }],
+    groups: {},
+  };
+  const byId = new Map(ir.nodes.map((n) => [n.id, n]));
+  const match = (q: string) =>
+    ir.nodes.filter((n) => parseQuery(q).every((t) => matchTerm(n, t, ir, byId))).map((n) => n.id);
+
+  test("selects what nothing references — the complement of an edge term", () => {
+    expect(match("kind:SecurityGroup !<-kind:EC2::Instance")).toEqual(["spare"]);
+  });
+
+  test("the un-negated query still selects what IS referenced", () => {
+    expect(match("kind:SecurityGroup <-kind:EC2::Instance")).toEqual(["used"]);
+  });
+
+  test("negates a plain attribute term too", () => {
+    const nodes = [
+      { id: "a", kind: "K", lexicon: "x", attrs: { env: "prod" } },
+      { id: "b", kind: "K", lexicon: "x", attrs: { env: "dev" } },
+    ];
+    const g = { nodes, edges: [], groups: {} };
+    const m = new Map(nodes.map((n) => [n.id, n]));
+    expect(
+      nodes.filter((n) => parseQuery("!attr:env=prod").every((t) => matchTerm(n, t, g, m))).map((n) => n.id),
+    ).toEqual(["b"]);
+  });
+
+  test("a bare edge term is refused, and the refusal names the correction", () => {
+    // Accepting it as "no edge in this direction" is coherent and still the
+    // wrong query for "what is unused": it counts every reference, including a
+    // stack output that merely publishes a resource's id, so it omits the very
+    // group the question is about. Measured — refused: 3/3 right; accepted:
+    // wrong in 2 runs of 3.
+    expect(() => parseQuery("kind:Foo !<-")).toThrow(/needs a target/);
+    expect(() => parseQuery("kind:Foo ->")).toThrow(/needs a target/);
+  });
+
+  test("a made-up prefix is refused, and names the correction", () => {
+    // An agent looking for SSH reachability wrote
+    // `effectiveIngress:tcp:22:0.0.0.0/0` — right idea, right attribute, wrong
+    // spelling — and this parsed as a free-text word that matched nothing. It
+    // read the clean empty result as "chant does not hold this fact" and
+    // rebuilt the answer by hand from security-group rows.
+    expect(() => parseQuery("kind:EC2::Instance effectiveIngress:tcp:22")).toThrow(
+      /there is no "effectiveIngress:" prefix/,
+    );
+    try {
+      parseQuery("effectiveIngress:tcp:22");
+    } catch (e) {
+      expect((e as { hint: string }).hint).toContain("attr:effectiveIngress=tcp:22");
+    }
+  });
+
+  test("still accepts a word that merely contains colons", () => {
+    // `AWS::EC2::Instance` and a URL are words, not malformed terms — a real
+    // prefix is one colon, not two.
+    expect(parseQuery("AWS::EC2::Instance")).toEqual([{ kind: "word", a: "AWS::EC2::Instance" }]);
+    expect(parseQuery("https://example.com")).toEqual([{ kind: "word", a: "https://example.com" }]);
+  });
+
+  test("an edge term WITH a target still parses", () => {
+    expect(() => parseQuery("kind:Foo !<-kind:Bar")).not.toThrow();
+  });
+
+  test("--explain says the term was negated, or an exclusion reads inverted", () => {
+    expect(describeTerm(parseQuery("!kind:Foo")[0])).toBe("!kind:Foo");
+  });
+});
+
+// #1278/#1279 — `--ambient` changes what a LIVE read goes and looks for. On a
+// replay it changes nothing: what is ambient in a recording was fixed when the
+// recording was taken.
+describe("the --ambient hint", () => {
+  const sg = node("sg-1", "AWS::EC2::SecurityGroup");
+  const kinds = ["AWS::EC2::SecurityGroup"];
+  const capture = (fn: () => void): string => {
+    const lines: string[] = [];
+    const spy = vi.spyOn(console, "log").mockImplementation((s: string) => { lines.push(s); });
+    fn();
+    spy.mockRestore();
+    return lines.join("\n");
+  };
+
+  test("names the flag on a live read that did not use it", () => {
+    expect(capture(() => ambientHint([sg] as never, kinds, false))).toContain("--ambient");
+  });
+
+  test("says nothing when the caller already asked for it", () => {
+    expect(capture(() => ambientHint([sg] as never, kinds, true))).toBe("");
+  });
+
+  test("says nothing on a replay whose snapshot already holds ambient resources", () => {
+    // The answer is complete. Saying the flag would add something is worse than
+    // silence: an agent read "6 of 6 matched" next to this hint, went looking
+    // for a seventh group, and hand-built a wrong answer from the raw graph.
+    expect(capture(() => ambientHint([sg] as never, kinds, false, { recordedAmbient: true }))).toBe("");
+  });
+
+  test("on a replay without them, points at the recording rather than the query", () => {
+    // `--at --ambient` cannot go and look; only a new snapshot can.
+    const out = capture(() => ambientHint([sg] as never, kinds, false, { recordedAmbient: false }));
+    expect(out).toContain("lifecycle snapshot");
+    expect(out).not.toContain("--ambient includes those");
+  });
+});
+
+// #1279 — asked to list instances "in all regions", an agent printed six
+// correct ids with no region against any of them, and was judged wrong.
+describe("the region spread of an answer", () => {
+  const inst = (id: string, region?: string) =>
+    node(id, "AWS::EC2::Instance", region ? { region } : {});
+  const capture = (fn: () => void): string => {
+    const lines: string[] = [];
+    const spy = vi.spyOn(console, "log").mockImplementation((s: string) => { lines.push(s); });
+    fn();
+    spy.mockRestore();
+    return lines.join("\n");
+  };
+  const spread = (ns: unknown[], show: string[] = [], q = "kind:EC2::Instance") =>
+    capture(() => regionSpread(parseQuery(q) as never, ns as never, show));
+
+  test("names the regions when the answer spans several", () => {
+    const out = spread([inst("a", "us-east-1"), inst("b", "us-west-2")]);
+    expect(out).toContain("us-east-1, us-west-2");
+    expect(out).toContain("2 regions");
+  });
+
+  test("says nothing when everything is in one region", () => {
+    expect(spread([inst("a", "us-east-1"), inst("b", "us-east-1")])).toBe("");
+  });
+
+  test("says nothing when the caller already asked for region", () => {
+    expect(spread([inst("a", "us-east-1"), inst("b", "us-west-2")], ["region"])).toBe("");
+    expect(spread([inst("a", "us-east-1"), inst("b", "us-west-2")], [], "attr:region=us-east-1")).toBe("");
+  });
+
+  test("says nothing when the resources carry no region", () => {
+    expect(spread([inst("a"), inst("b")])).toBe("");
+  });
+});
+
+// #1279 — seven `--show` names in one benchmark run missed on case alone, and
+// a missed name printed nothing at all rather than saying it had missed.
+describe("--show name matching", () => {
+  const n = node("web", "AWS::EC2::Instance", { physicalId: "i-1", region: "us-east-1" });
+  const capture = (fn: () => void): string => {
+    const lines: string[] = [];
+    const spy = vi.spyOn(console, "log").mockImplementation((s: string) => { lines.push(s); });
+    fn();
+    spy.mockRestore();
+    return lines.join("\n");
+  };
+
+  test("matches a column name whatever case the caller used", () => {
+    // AWS names are PascalCase and chant's derived ones are not, so a caller
+    // mixing them is normal. Both are the same request.
+    expect(formatRow(n, ["Region"])).toContain("region=us-east-1");
+    expect(formatRow(n, ["region"])).toContain("region=us-east-1");
+  });
+
+  test("prints the name the resource actually uses, not the one asked for", () => {
+    expect(formatRow(n, ["REGION"])).toContain("region=us-east-1");
+  });
+
+  test("says when nothing carries a requested column", () => {
+    expect(capture(() => showMiss([n] as never, ["VpcId"]))).toContain("VpcId");
+  });
+
+  test("says nothing when every requested column is present", () => {
+    expect(capture(() => showMiss([n] as never, ["Region"]))).toBe("");
+  });
+});