@intentius/chant 0.32.0 → 0.33.1

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

@@ -0,0 +1,159 @@
+import { describe, test, expect, vi } from "vitest";
+import { __searchInternals } from "./search";
+
+const { parseQuery, matchTerm, formatRow, explain, describeTerm, derivedSurface, availableAttrs } = __searchInternals;
+
+function node(id: string, kind: string, attrs: Record<string, unknown> = {}) {
+  return { id, kind, lexicon: "aws", attrs } as never;
+}
+
+describe("search query parsing", () => {
+  test("splits bare words, keyed terms, and quoted phrases", () => {
+    const terms = parseQuery('kind:EC2::Instance tag:Name=Public "public subnet"');
+    expect(terms).toEqual([
+      { kind: "kind", a: "EC2::Instance" },
+      { kind: "tag", a: "Name", b: "Public" },
+      { kind: "word", a: "public subnet" },
+    ]);
+  });
+});
+
+describe("search matching", () => {
+  const inst = node("webServer", "AWS::EC2::Instance", {
+    physicalId: "i-abc",
+    Tags: [{ Key: "Name", Value: "Public" }],
+    MapPublicIpOnLaunch: true,
+  });
+
+  test("kind: is substring on the resource kind", () => {
+    expect(matchTerm(inst, { kind: "kind", a: "EC2::Instance" })).toBe(true);
+    expect(matchTerm(inst, { kind: "kind", a: "SecurityGroup" })).toBe(false);
+  });
+
+  test("tag: matches Key with optional Value substring", () => {
+    expect(matchTerm(inst, { kind: "tag", a: "Name", b: "Pub" })).toBe(true);
+    expect(matchTerm(inst, { kind: "tag", a: "Name", b: "Private" })).toBe(false);
+    expect(matchTerm(inst, { kind: "tag", a: "Owner" })).toBe(false);
+  });
+
+  test("attr: matches presence or value substring", () => {
+    expect(matchTerm(inst, { kind: "attr", a: "MapPublicIpOnLaunch", b: "true" })).toBe(true);
+    expect(matchTerm(inst, { kind: "attr", a: "MapPublicIpOnLaunch" })).toBe(true);
+    expect(matchTerm(inst, { kind: "attr", a: "Nonexistent" })).toBe(false);
+  });
+
+  test("bare word searches id, kind, and attr values", () => {
+    expect(matchTerm(inst, { kind: "word", a: "webserver" })).toBe(true);
+    expect(matchTerm(inst, { kind: "word", a: "i-abc" })).toBe(true);
+    expect(matchTerm(inst, { kind: "word", a: "nope" })).toBe(false);
+  });
+});
+
+describe("search formatting", () => {
+  test("compact row with live physical id, skipping object placeholders", () => {
+    const live = node("webServer", "AWS::EC2::Instance", { physicalId: "i-abc" });
+    expect(formatRow(live, [])).toBe("webServer  AWS::EC2::Instance  i-abc");
+    const src = node("webServer", "AWS::EC2::Instance", { InstanceId: { $ref: "webServer.InstanceId" } });
+    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");
+  });
+});
+
+describe("search edge traversal", () => {
+  const ir = {
+    nodes: [
+      node("webServer", "AWS::EC2::Instance", { physicalId: "i-1" }),
+      node("privSubnet", "AWS::EC2::Subnet", { MapPublicIpOnLaunch: false }),
+      node("pubSubnet", "AWS::EC2::Subnet", { MapPublicIpOnLaunch: true }),
+      node("privServer", "AWS::EC2::Instance", { physicalId: "i-2" }),
+    ],
+    edges: [
+      { from: "webServer", to: "pubSubnet", kind: "ref", viaAttr: "SubnetId" },
+      { from: "privServer", to: "privSubnet", kind: "ref", viaAttr: "SubnetId" },
+    ],
+  } as never;
+
+  test("->attr resolves the instance→subnet→public join", () => {
+    const byId = new Map((ir as { nodes: { id: string }[] }).nodes.map((n) => [n.id, n]));
+    const terms = parseQuery("kind:EC2::Instance ->attr:MapPublicIpOnLaunch=true");
+    const matches = (ir as { nodes: never[] }).nodes.filter((n) =>
+      terms.every((t) => matchTerm(n as never, t, ir, byId as never)),
+    );
+    expect(matches.map((n: { id: string }) => n.id)).toEqual(["webServer"]);
+  });
+
+  test("parses -> and <- into directional edge terms", () => {
+    expect(parseQuery("->kind:Subnet")).toEqual([{ kind: "edge", a: "", dir: "out", sub: { kind: "kind", a: "Subnet" } }]);
+    expect(parseQuery("<-kind:Instance")).toEqual([{ kind: "edge", a: "", dir: "in", sub: { kind: "kind", a: "Instance" } }]);
+  });
+
+  test("--explain footer: universe count + why the non-match was excluded", () => {
+    const byId = new Map((ir as { nodes: { id: string }[] }).nodes.map((n) => [n.id, n]));
+    const query = "kind:EC2::Instance ->attr:MapPublicIpOnLaunch=true";
+    const terms = parseQuery(query);
+    const matches = (ir as { nodes: never[] }).nodes.filter((n) => terms.every((t) => matchTerm(n as never, t, ir, byId as never)));
+    const lines: string[] = [];
+    const spy = vi.spyOn(console, "log").mockImplementation((s: string) => { lines.push(s); });
+    explain(terms as never, matches as never, ir, byId as never, query);
+    spy.mockRestore();
+    // 1 of 2 Instances matched (webServer public, privServer excluded).
+    expect(lines[0]).toContain("1 of 2 AWS::EC2::Instance matched");
+    expect(lines.join("\n")).toContain("excluded privServer");
+    expect(lines.join("\n")).toContain("MapPublicIpOnLaunch=true");
+  });
+
+  test("describeTerm renders an edge term with direction and no-such-edge reason", () => {
+    expect(describeTerm({ kind: "edge", a: "", dir: "out", sub: { kind: "attr", a: "MapPublicIpOnLaunch", b: "true" } } as never))
+      .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");
+  });
+});

package/src/cli/handlers/search.ts

@@ -0,0 +1,314 @@
+import { resolve } from "node:path";
+import { build } from "../../build";
+import { buildGraphIr, buildLiveGraphIr, sourceOverlayGraphs, type GraphIR, type IRNode } from "../../graph-ir";
+import { buildDeclaredPerStack } from "../../graph-declared";
+import { enrichEffectiveTopology } from "../../graph-effective";
+import { discover } from "../../discovery/index";
+
+import { observeResources } from "../../lifecycle/observe";
+import { loadChantConfig } from "../../config";
+import { loadPlugins, resolveProjectLexicons } from "../plugins";
+import { formatError, formatWarning } from "../format";
+import type { CommandContext } from "../registry";
+
+/**
+ * `chant search <query> [--live --env <name>]` — answer an estate question with
+ * a COMPACT result instead of the whole graph. The point (measured on aws-bench,
+ * #1139): a small model shouldn't ingest a multi-thousand-token IR dump to answer
+ * "which instances are in public subnets" — it should query and get a few rows.
+ *
+ * Query grammar (space-separated terms, all must match — AND):
+ *   bare word            case-insensitive substring over id, kind, and attrs
+ *   kind:<substr>        node kind contains <substr> (e.g. kind:EC2::Instance)
+ *   tag:<key>=<val>      a Tags entry with Key=key and Value containing val
+ *   attr:<name>=<val>    attribute <name> equals/contains <val>
+ *   ->kind:X / ->attr:.. this node has an edge TO a node matching the right side
+ *   <-kind:X / <-attr:.. this node has an edge FROM a node matching the right side
+ *
+ * The edge operators are the point of "edge-aware" search (#1139): a small
+ * model shouldn't hand-join instance→subnet→public across many results — one
+ * query does the traversal. `kind:Instance ->attr:MapPublicIpOnLaunch=true`
+ * = instances that reference a public subnet.
+ *
+ * Output: one line per match — `<id>  <kind>  <key=val ...>` — with only the
+ * physical id and any attributes named in `attr:`/`--show`. Tens of tokens, not
+ * thousands.
+ */
+export async function runSearch(ctx: CommandContext): Promise<number> {
+  const { args } = ctx;
+  const query = (args.path ?? "").trim();
+  if (!query) {
+    console.error(formatError({ message: "chant search needs a query: chant search \"<terms>\" [--live --env <name>]" }));
+    return 1;
+  }
+  const terms = parseQuery(query);
+  const show = parseShow(args);
+
+  const projectPath = resolve(".");
+  const { config } = await loadChantConfig(projectPath);
+
+  let ir: GraphIR;
+  if (args.live) {
+    const environment = args.env;
+    if (!environment) {
+      console.error(formatError({ message: "chant search --live needs an environment: --live --env <name>" }));
+      return 1;
+    }
+    if (config.environments && !config.environments.includes(environment)) {
+      console.error(formatError({ message: `Unknown environment "${environment}"` }));
+      return 1;
+    }
+    const plugins = ctx.plugins.length > 0 ? ctx.plugins : await loadPlugins(await resolveProjectLexicons(projectPath));
+    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 searching live state" }));
+      return 1;
+    }
+    const observing = plugins.filter((p) => p.describeResources);
+    const stacks = (config.stacks ?? []).map((s) => ({ name: s.name, region: s.region, src: s.src }));
+    const { observations, errors } = await observeResources(environment, observing, buildResult, {
+      owned: true,
+      stacks,
+    });
+    for (const e of errors) console.error(formatWarning({ message: e }));
+    let live = buildLiveGraphIr(observations);
+    const liveAttrs: Record<string, Record<string, unknown>> = {};
+    for (const p of observing) {
+      if (!p.enrichLiveAttrs) continue;
+      try {
+        const enriched = await p.enrichLiveAttrs({ environment, owned: true, stacks });
+        for (const [id, a] of Object.entries(enriched)) liveAttrs[id] = { ...liveAttrs[id], ...a };
+        live = { ...live, nodes: live.nodes.map((n) => (enriched[n.id] ? { ...n, attrs: { ...n.attrs, ...enriched[n.id] } } : n)) };
+      } catch {
+        /* enrichment is best-effort; search still works on describe attrs */
+      }
+    }
+    // Overlay live identity onto the SOURCE graph (same as `graph --overlay`):
+    // the declared graph is the canvas — its edges carry the topology so ->/<-
+    // resolves, while the live side supplies physical ids.
+    //
+    // Multi-stack (#1162): build the declared graph PER STACK (scoped to each
+    // stack's src, the way it deploys) and stack-qualify node ids + edges as
+    // `${stack}::${id}` — matching how observation qualifies. A flat whole-
+    // project discovery would disambiguate colliding names by module path
+    // (UsEast1Src…), which never matches the observed bare LogicalResourceIds.
+    const declared =
+      stacks.length > 0
+        ? await buildDeclaredPerStack(stacks, projectPath)
+        : buildGraphIr((await discover(resolve(args.src ?? config.sourceDir ?? "."))).entities, projectPath);
+    ir = sourceOverlayGraphs(declared, live);
+    // Carry live-derived attrs onto the declared canvas — some facts only exist
+    // in live account state (e.g. `internetFacing` for an instance in the
+    // account's default VPC, whose route table chant does not model). The
+    // overlay copies physical identity but not attrs, so merge them here.
+    ir = { ...ir, nodes: ir.nodes.map((n) => (liveAttrs[n.id] ? { ...n, attrs: { ...n.attrs, ...liveAttrs[n.id] } } : n)) };
+  } else {
+    const discovered = await discover(resolve(args.src ?? config.sourceDir ?? "."));
+    ir = buildGraphIr(discovered.entities);
+  }
+
+  // Fold derived reachability facts (effectiveIngress, internetFacing) onto
+  // instance nodes so multi-hop/launch-template joins are one node predicate (#1139).
+  ir = enrichEffectiveTopology(ir);
+  const nodeById = new Map(ir.nodes.map((n) => [n.id, n]));
+  const matches = ir.nodes.filter((n) => terms.every((t) => matchTerm(n, t, ir, nodeById)));
+  if (matches.length === 0) {
+    console.log("(no matches)");
+    availableAttrs(terms, ir);
+    if (args.explain) explain(terms, matches, ir, nodeById, query);
+    return 0;
+  }
+  for (const n of matches) {
+    console.log(formatRow(n, show));
+  }
+  derivedSurface(terms, matches, ir);
+  if (args.explain) explain(terms, matches, ir, nodeById, query);
+  return 0;
+}
+
+/**
+ * Name the facts chant computed for the kinds in this result that the query did not use.
+ *
+ * A provider API can only return what it stores; chant additionally folds multi-hop topology
+ * onto a node, and a caller has no way to know that surface exists. Reporting it turns a
+ * one-shot query into a conversation with the graph — ask something, learn what else is
+ * knowable about the same resources, refine.
+ *
+ * The names come from {@link GraphIR.derivedAttrs}, recorded by whichever enrichment pass
+ * produced them. Nothing here knows what any attribute means or which question it answers;
+ * add a pass and its facts appear, remove one and they stop.
+ */
+function derivedSurface(terms: Term[], matches: IRNode[], ir: GraphIR): void {
+  const derived = ir.derivedAttrs;
+  if (!derived || matches.length === 0) return;
+  const used = new Set(terms.filter((t) => t.kind === "attr").map((t) => t.a));
+  const unused = new Set<string>();
+  for (const n of matches) {
+    for (const [kind, names] of Object.entries(derived)) {
+      if (!n.kind?.includes(kind)) continue;
+      for (const name of names) if (!used.has(name)) unused.add(name);
+    }
+  }
+  if (unused.size === 0) return;
+  console.log(`— also derived for these resources: ${[...unused].sort().join(", ")}`);
+}
+
+/**
+ * `--explain` footer (#1139): a compact, model-DERIVED summary that gives a
+ * small model a reason to trust the result instead of re-deriving it with a
+ * lossy CLI sweep. It reports the universe count ("4 of 6 Instances") — chant's
+ * structural edge, since the typed graph knows the denominator a live sweep
+ * doesn't — and, for the near-miss set, WHY each was excluded (which query term
+ * it fails). Everything here is a property of the query over the graph, not of
+ * any expected answer, so it stays a fair, question-agnostic capability.
+ */
+function explain(terms: Term[], matches: IRNode[], ir: GraphIR, byId: Map<string, IRNode>, query: string): void {
+  const kinds = new Set(matches.map((n) => n.kind).filter((k): k is string => !!k));
+  const universe = kinds.size > 0 ? ir.nodes.filter((n) => n.kind && kinds.has(n.kind)) : ir.nodes;
+  const matched = new Set(matches.map((n) => n.id));
+  const excluded = universe.filter((n) => !matched.has(n.id));
+  const kindLabel = kinds.size > 0 ? [...kinds].join("/") : "nodes";
+  console.log(`— ${matches.length} of ${universe.length} ${kindLabel} matched  (query: ${query})`);
+  // Inclusion evidence: for a derived fact a CLI can't easily re-verify
+  // (internetFacing, resolved across the default VPC's routing), name WHY each
+  // match qualifies, so the agent trusts the result instead of dropping it.
+  for (const t of terms) {
+    if (t.kind !== "attr") continue;
+    for (const n of matches) {
+      const via = (n.attrs as Record<string, unknown> | undefined)?.[`${t.a}Via`];
+      const id = n.id.includes("::") ? n.id.slice(n.id.lastIndexOf("::") + 2) : n.id;
+      if (typeof via === "string") console.log(`  ✓ ${id} ${t.a} via ${via}`);
+    }
+  }
+  const shown = excluded.slice(0, 8);
+  for (const n of shown) {
+    const failing = terms.find((t) => !matchTerm(n, t, ir, byId));
+    const id = n.id.includes("::") ? n.id.slice(n.id.lastIndexOf("::") + 2) : n.id;
+    console.log(`  · excluded ${id} — fails ${failing ? describeTerm(failing) : "(query)"}`);
+  }
+  if (excluded.length > shown.length) console.log(`  · …and ${excluded.length - shown.length} more excluded`);
+}
+
+/**
+ * On a miss, name the attributes the queried kind actually carries. A graph knows
+ * its own schema, so a caller who guessed an attribute name — or did not know a
+ * derived one existed — can see what is queryable instead of falling back to a
+ * lossy CLI sweep. Read off the nodes present, so it stays a property of the
+ * graph rather than of any expected answer: whatever the estate holds is what
+ * this lists, and it says nothing about which attribute answers a question.
+ */
+function availableAttrs(terms: Term[], ir: GraphIR): void {
+  const kindTerm = terms.find((t) => t.kind === "kind");
+  if (!kindTerm) return;
+  const of = ir.nodes.filter((n) => n.kind?.includes(kindTerm.a));
+  if (of.length === 0) return;
+  const names = new Set<string>();
+  for (const n of of) for (const k of Object.keys((n.attrs as Record<string, unknown>) ?? {})) names.add(k);
+  const queried = new Set(terms.filter((t) => t.kind === "attr").map((t) => t.a));
+  const unused = [...names].filter((k) => !queried.has(k)).sort();
+  if (unused.length === 0) return;
+  console.log(`  · ${of.length} ${kindTerm.a} node(s) carry: ${unused.join(", ")}`);
+}
+
+function describeTerm(t: Term): string {
+  const leaf = (x: Term): string =>
+    x.kind === "kind" ? `kind:${x.a}` : x.kind === "attr" ? `attr:${x.a}${x.b !== undefined ? "=" + x.b : ""}`
+      : x.kind === "tag" ? `tag:${x.a}${x.b !== undefined ? "=" + x.b : ""}` : `"${x.a}"`;
+  if (t.kind === "edge" && t.sub) return `${t.dir === "out" ? "→" : "←"}${leaf(t.sub)} (no such edge)`;
+  return leaf(t);
+}
+
+interface Term {
+  kind: "word" | "kind" | "tag" | "attr" | "edge";
+  a: string;
+  b?: string;
+  /** For edge terms: the direction and the sub-predicate matched at the far end. */
+  dir?: "out" | "in";
+  sub?: Term;
+}
+
+function parseLeaf(tok: string): Term {
+  const m = /^(kind|tag|attr):(.*)$/i.exec(tok);
+  if (m) {
+    const key = m[1].toLowerCase() as Term["kind"];
+    const rest = m[2];
+    const eq = rest.indexOf("=");
+    if (eq >= 0) return { kind: key, a: rest.slice(0, eq), b: rest.slice(eq + 1) };
+    return { kind: key, a: rest };
+  }
+  return { kind: "word", a: tok };
+}
+
+function parseQuery(query: string): Term[] {
+  // Split on whitespace but keep quoted phrases together.
+  const tokens = query.match(/"[^"]*"|\S+/g) ?? [];
+  return tokens.map((raw) => {
+    const tok = raw.replace(/^"|"$/g, "");
+    if (tok.startsWith("->")) return { kind: "edge", a: "", dir: "out", sub: parseLeaf(tok.slice(2)) };
+    if (tok.startsWith("<-")) return { kind: "edge", a: "", dir: "in", sub: parseLeaf(tok.slice(2)) };
+    return parseLeaf(tok);
+  });
+}
+
+function parseShow(args: { show?: string }): string[] {
+  return args.show ? args.show.split(",").map((s) => s.trim()).filter(Boolean) : [];
+}
+
+function attrString(v: unknown): string {
+  if (v == null) return "";
+  if (typeof v === "object") {
+    // AttrRef placeholder ({$ref}) or nested — stringify shallowly.
+    return JSON.stringify(v);
+  }
+  return String(v);
+}
+
+function matchTerm(n: IRNode, t: Term, ir?: GraphIR, byId?: Map<string, IRNode>): boolean {
+  const attrs = n.attrs ?? {};
+  if (t.kind === "edge") {
+    if (!ir || !byId || !t.sub) return false;
+    // A node matches if it has an edge (out or in) to a node satisfying `sub`.
+    const edges = ir.edges ?? [];
+    const neighbors = edges
+      .filter((e) => (t.dir === "out" ? e.from === n.id : e.to === n.id))
+      .map((e) => byId.get(t.dir === "out" ? e.to : e.from))
+      .filter((x): x is IRNode => !!x);
+    return neighbors.some((m) => matchTerm(m, t.sub!, ir, byId));
+  }
+  if (t.kind === "kind") return (n.kind ?? "").toLowerCase().includes(t.a.toLowerCase());
+  if (t.kind === "attr") {
+    const val = attrString((attrs as Record<string, unknown>)[t.a]);
+    return t.b === undefined ? t.a in attrs : val.toLowerCase().includes(t.b.toLowerCase());
+  }
+  if (t.kind === "tag") {
+    const tags = (attrs as Record<string, unknown>)["Tags"];
+    if (!Array.isArray(tags)) return false;
+    return tags.some((tag) => {
+      const key = attrString((tag as Record<string, unknown>)?.Key);
+      const val = attrString((tag as Record<string, unknown>)?.Value);
+      return key.toLowerCase() === t.a.toLowerCase() && (t.b === undefined || val.toLowerCase().includes(t.b.toLowerCase()));
+    });
+  }
+  // bare word: substring over id, kind, and all attr values
+  const hay = [n.id, n.kind, ...Object.values(attrs).map(attrString)].join(" ").toLowerCase();
+  return hay.includes(t.a.toLowerCase());
+}
+
+function formatRow(n: IRNode, show: string[]): string {
+  const attrs = (n.attrs ?? {}) as Record<string, unknown>;
+  // Display the bare logical id, not the `${stack}::` qualification (#1162).
+  const displayId = n.id.includes("::") ? n.id.slice(n.id.lastIndexOf("::") + 2) : n.id;
+  const parts: string[] = [displayId, n.kind ?? ""];
+  // Prefer the node-level live physicalId (set by the overlay), then attrs;
+  // skip source-mode AttrRef placeholders (objects).
+  const physical = (n as { physicalId?: unknown }).physicalId ?? attrs["physicalId"] ?? attrs["InstanceId"] ?? attrs["Id"];
+  if (physical != null && typeof physical !== "object") parts.push(String(physical));
+  for (const key of show) {
+    const v = attrs[key];
+    if (v != null && typeof v !== "object") parts.push(`${key}=${attrString(v)}`);
+  }
+  return parts.filter(Boolean).join("  ");
+}
+
+/** Internals exposed for unit tests. */
+export const __searchInternals = { parseQuery, matchTerm, formatRow, explain, describeTerm, derivedSurface, availableAttrs };

package/src/cli/main.ts

@@ -25,6 +25,7 @@ import { runCarveApply } from "./handlers/carve-apply";
 import { runLifecycleSnapshot, runLifecycleShow, runLifecycleDiff, runLifecycleRollback, runLifecyclePlan, runLifecycleAffected, runLifecycleLog, runLifecycleUnknown } from "./handlers/lifecycle";
 import { runComponentsStatus, runComponentsReleaseRecord, runComponentsUnknown } from "./handlers/components";
 import { runGraph } from "./handlers/graph";
+import { runSearch } from "./handlers/search";
 import { runOp, runOpList, runOpStatus, runOpSignal, runOpCancel, runOpLog } from "./handlers/run";
 import { runEmulator } from "./handlers/emulator";
 import { splitJoinedFlags, dispatchCommandGroup, collectCommandGroups, formatCommandGroupsHelp, type CommandGroup } from "./command-group";
@@ -49,6 +50,7 @@ const BOOLEAN_FLAGS = new Set([
   "--verbose",
   "--live",
   "--overlay",
+  "--explain",
   "--owned",
   "--verbatim",
   "--apply-rewrites",
@@ -241,6 +243,10 @@ export function parseArgs(args: string[]): ParsedArgs {
       result.detail = Number(args[++i]);
     } else if (arg === "--lens") {
       result.lens = args[++i];
+    } else if (arg === "--explain") {
+      result.explain = true;
+    } else if (arg === "--show") {
+      result.show = args[++i];
     } else if (arg === "--up") {
       result.up = true;
     } else if (arg === "--down") {
@@ -662,6 +668,7 @@ const registry: CommandDef[] = [
   { name: "lint", handler: runLint },
   { name: "list", handler: runList },
   { name: "describe", handler: runDescribe },
+  { name: "search", handler: runSearch },
   { name: "import", handler: runImport },
   { name: "audit", handler: runAudit },
   { name: "migrate", handler: runMigrate },

package/src/cli/registry.ts

@@ -95,6 +95,10 @@ export interface ParsedArgs {
   detail?: number;
   /** `chant graph --lens <kind>:<target>` — focus the graph IR on a slice */
   lens?: string;
+  /** `chant search --show a,b` — extra attributes to include per matched row (#1139). */
+  show?: string;
+  /** `chant search --explain` — append a footer: universe count + why non-matches were excluded (#1139). */
+  explain?: boolean;
   /** `chant graph --lens blast:<node> --up` — include upstream producers */
   up?: boolean;
   /** `chant graph --lens blast:<node> --down` — include downstream dependents */

package/src/codegen/release-wiring.test.ts

@@ -0,0 +1,82 @@
+/**
+ * The release path is two hand-maintained halves that must agree: the
+ * justfile recipes that create and push a tag, and publish.yml's tag
+ * trigger that decides whether pushing it does anything.
+ *
+ * They disagreed. `just release-lexicon <name>` has always tagged
+ * `lexicon-<name>-v<version>`, pushed it, and echoed "publish workflow
+ * triggered" — while publish.yml matched only `chant-v*`. The tag landed,
+ * no workflow ran, and the recipe reported success. fly's 0.33.0 shipped
+ * with zero rules and zero skills and could not be patched by the one
+ * recipe built for patching a single lexicon.
+ *
+ * A release that silently no-ops is worse than one that fails, so this
+ * turns the next divergence into a PR-time failure.
+ */
+
+import { describe, expect, it } from "vitest";
+import { readFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const repoRoot = join(dirname(fileURLToPath(import.meta.url)), "..", "..", "..", "..");
+
+function publishTagPatterns(): string[] {
+  const workflow = readFileSync(join(repoRoot, ".github", "workflows", "publish.yml"), "utf-8");
+  const match = workflow.match(/^\s*tags:\s*\[([^\]]+)\]/m);
+  if (!match) throw new Error("publish.yml: `tags: [...]` trigger not found");
+  return match[1].split(",").map((s) => s.trim().replace(/^['"]|['"]$/g, ""));
+}
+
+/** Tags the justfile actually creates, as literal-prefix + wildcard shapes. */
+function releaseTagShapes(): Array<{ recipe: string; example: string }> {
+  const justfile = readFileSync(join(repoRoot, "justfile"), "utf-8");
+  const shapes: Array<{ recipe: string; example: string }> = [];
+
+  // `git tag "chant-v$next"` / `git tag "lexicon-{{name}}-v$next"`
+  for (const m of justfile.matchAll(/git tag "([^"]+)"/g)) {
+    const raw = m[1];
+    const example = raw
+      .replace(/\{\{name\}\}/g, "docker")
+      .replace(/\$\{?next\}?/g, "9.9.9");
+    shapes.push({ recipe: raw, example });
+  }
+  return shapes;
+}
+
+/** Minimal glob match for the `prefix*` shapes these patterns use. */
+function matchesGlob(pattern: string, value: string): boolean {
+  const rx = new RegExp(
+    "^" + pattern.split("*").map((s) => s.replace(/[.+?^${}()|[\]\\]/g, "\\$&")).join(".*") + "$",
+  );
+  return rx.test(value);
+}
+
+describe("release wiring: justfile tags vs publish.yml trigger", () => {
+  it("finds both halves", () => {
+    expect(publishTagPatterns().length).toBeGreaterThan(0);
+    expect(releaseTagShapes().length).toBeGreaterThan(0);
+  });
+
+  it("every tag a release recipe pushes triggers the publish workflow", () => {
+    const patterns = publishTagPatterns();
+
+    for (const { recipe, example } of releaseTagShapes()) {
+      const hit = patterns.some((p) => matchesGlob(p, example));
+      expect(
+        hit,
+        `justfile creates tag "${recipe}" (e.g. ${example}) but publish.yml triggers on ` +
+          `[${patterns.join(", ")}] — pushing it would publish nothing while the recipe ` +
+          `reports success`,
+      ).toBe(true);
+    }
+  });
+
+  it("covers the two shapes the repo releases by", () => {
+    const examples = releaseTagShapes().map((s) => s.example);
+    // Whole-repo release and single-lexicon patch. If a recipe stops
+    // producing one of these, the assertion above would pass vacuously.
+    expect(examples).toContain("chant-v9.9.9");
+    expect(examples).toContain("lexicon-docker-v9.9.9");
+  });
+});

package/src/config.ts

@@ -172,6 +172,9 @@ export interface ChantConfig {
     name: string;
     /** Source directory to build for this stack, relative to the project root. */
     src: string;
+    /** AWS region this stack is deployed in (multi-region estates). When set,
+     * observation/enrichment target this region instead of the ambient one. */
+    region?: string;
   }>;
 
   /** Lint configuration (rules, extends, overrides, plugins) */

package/src/graph-declared.ts

@@ -0,0 +1,33 @@
+import { resolve } from "node:path";
+import { discover } from "./discovery/index";
+import { buildGraphIr, type GraphIR, type IRNode } from "./graph-ir";
+
+/**
+ * Build the DECLARED graph for a multi-stack project, scoped per stack (#1162).
+ *
+ * A whole-project discovery disambiguates colliding logical names by module path
+ * (two `server`s become `UsEast1Srcserver` / `UsWest1Srcserver`) — names that
+ * never appear in any deployed template, because each stack deploys its OWN
+ * scoped source with BARE LogicalResourceIds. Observation therefore keys live
+ * nodes by `${stack}::${logicalId}` (bare id). To make the declared side join
+ * that live side, build each stack's `src` in isolation and qualify its node ids
+ * and edge endpoints the same way. Stacks are merged into one graph.
+ *
+ * A stack without `src` contributes nothing here — it has no declared source to
+ * scope to (its live nodes still show as foreign in the overlay).
+ */
+export async function buildDeclaredPerStack(
+  stacks: Array<{ name: string; src?: string }>,
+  projectPath: string,
+): Promise<GraphIR> {
+  const nodes: IRNode[] = [];
+  const edges: GraphIR["edges"] = [];
+  for (const st of stacks) {
+    if (!st.src) continue;
+    const g = buildGraphIr((await discover(resolve(projectPath, st.src))).entities, projectPath);
+    const q = (id: string) => `${st.name}::${id}`;
+    for (const n of g.nodes) nodes.push({ ...n, id: q(n.id) });
+    for (const e of g.edges) edges.push({ ...e, from: q(e.from), to: q(e.to) });
+  }
+  return { nodes, edges, groups: {} };
+}