@intentius/chant 0.31.0 → 0.33.0

package/src/cli/handlers/search.ts

@@ -0,0 +1,263 @@
+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)");
+    if (args.explain) explain(terms, matches, ir, nodeById, query);
+    return 0;
+  }
+  for (const n of matches) {
+    console.log(formatRow(n, show));
+  }
+  if (args.explain) explain(terms, matches, ir, nodeById, query);
+  return 0;
+}
+
+/**
+ * `--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.
+  if (terms.some((t) => t.kind === "attr" && t.a === "internetFacing")) {
+    for (const n of matches) {
+      const via = (n.attrs as Record<string, unknown> | undefined)?.["internetFacingVia"];
+      const id = n.id.includes("::") ? n.id.slice(n.id.lastIndexOf("::") + 2) : n.id;
+      if (typeof via === "string") console.log(`  ✓ ${id} internet-facing 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`);
+}
+
+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 };

package/src/cli/main.ts

@@ -25,8 +25,11 @@ 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";
+import type { LexiconPlugin } from "../lexicon";
 
 /**
  * Long-form flags that are pure booleans in {@link parseArgs} — their branch
@@ -47,6 +50,7 @@ const BOOLEAN_FLAGS = new Set([
   "--verbose",
   "--live",
   "--overlay",
+  "--explain",
   "--owned",
   "--verbatim",
   "--apply-rewrites",
@@ -118,31 +122,24 @@ export function parseArgs(args: string[]): ParsedArgs {
     env: undefined,
   };
 
+  // chant #1127 — generic joined `--flag=value` support, factored out to
+  // ./command-group.ts (chant #1078) so a lexicon's own mounted command can
+  // apply the identical splitting discipline to its own flag vocabulary.
+  // Every value-taking flag below is matched by an exact `arg === "--flag"`
+  // check and then consumes the *next* array element (`args[++i]`) as its
+  // value; a joined token like `--env=prod` never matches any of those,
+  // doesn't match the trailing positional branch either (it starts with
+  // `-`), and used to vanish with no error. Splitting the token at its FIRST
+  // `=` and re-dispatching as two array elements makes every flag below see
+  // the exact shape it already handles — including a flag like `--param`
+  // whose own value legitimately contains `=` (`--param=tier=production`
+  // splits to flag `--param`, value `tier=production`, not further split on
+  // the second `=`).
+  args = splitJoinedFlags(args, BOOLEAN_FLAGS);
+
   let i = 0;
   while (i < args.length) {
-    let arg = args[i];
-
-    // chant #1127 — generic joined `--flag=value` support. Every value-taking
-    // flag below is matched by an exact `arg === "--flag"` check and then
-    // consumes the *next* array element (`args[++i]`) as its value; a joined
-    // token like `--env=prod` never matches any of those, doesn't match the
-    // trailing positional branch either (it starts with `-`), and used to
-    // vanish with no error. Splitting the token at its FIRST `=` and
-    // re-dispatching as two array elements makes every flag below see the
-    // exact shape it already handles — including a flag like `--param`
-    // whose own value legitimately contains `=` (`--param=tier=production`
-    // splits to flag `--param`, value `tier=production`, not further split
-    // on the second `=`).
-    if (arg.startsWith("--") && arg.includes("=")) {
-      const eq = arg.indexOf("=");
-      const flag = arg.slice(0, eq);
-      const value = arg.slice(eq + 1);
-      if (BOOLEAN_FLAGS.has(flag)) {
-        throw new Error(`${arg} — ${flag} is a boolean flag and does not take a value. Pass ${flag} on its own.`);
-      }
-      args.splice(i, 1, flag, value);
-      arg = args[i];
-    }
+    const arg = args[i];
 
     if (arg === "--help" || arg === "-h") {
       result.help = true;
@@ -246,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") {
@@ -348,9 +349,12 @@ export function parseArgs(args: string[]): ParsedArgs {
 }
 
 /**
- * Print help message
+ * Print help message. `groups` — lexicon-contributed command groups
+ * (chant #1078), best-effort loaded from the current project; composed in
+ * below the static command list so `--help` lists every mounted verb group
+ * alongside core's own commands.
  */
-function printHelp(): void {
+function printHelp(groups: CommandGroup[] = []): void {
   console.log(`
 chant - Declarative infrastructure specification toolkit
 
@@ -575,6 +579,60 @@ Examples:
   chant describe myComponent src/
   chant describe myComponent src/ --format json
 `);
+  const groupsHelp = formatCommandGroupsHelp(groups);
+  if (groupsHelp) console.log(groupsHelp);
+}
+
+/**
+ * Best-effort load the current project's lexicon plugins for a purely
+ * read-only lookup (help composition, plugin-command dispatch) — never
+ * throws, empty on any failure (no config, no lexicons, not a chant
+ * project at all). Mirrors the existing best-effort loading already used
+ * for `emulator`/`components status` in {@link main} below.
+ */
+async function loadPluginsBestEffort(): Promise<LexiconPlugin[]> {
+  try {
+    const lexiconNames = await resolveProjectLexicons(resolve("."));
+    return await loadPlugins(lexiconNames);
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * chant #1078 — the lexicon command-group seam's dispatch-time half. Core's
+ * own `parseArgs`/`resolveCommand` know nothing about a lexicon's mounted
+ * verbs, so this is only ever consulted after BOTH of those have already
+ * failed to make sense of the invocation: either `parseArgs` threw on a flag
+ * it doesn't recognize (which is *expected* for a mounted command's own
+ * vocabulary — core has none), or it parsed fine but `resolveCommand` found
+ * no match in the static registry (a mounted command with no extra flags,
+ * e.g. `chant kube version`). Either way, a lexicon-mounted command's group
+ * name and verb are always the first two CLI tokens (mirrors the `emulator
+ * <up|down|status>` compound shape from #920), so `rawArgv` — the untouched
+ * `process.argv.slice(2)` — is all this needs; nothing from the partially or
+ * fully parsed `ParsedArgs` is used, on purpose, since core's flag-parsing
+ * failure or success is irrelevant to a namespace it doesn't own.
+ *
+ * Returns `undefined` when nothing claims the leading token as a command
+ * group at all, so the caller falls back to its own error handling
+ * unchanged — a project with no lexicon exposing `commands()` (or none of
+ * its plugins matching) is completely unaffected.
+ */
+async function tryPluginCommand(rawArgv: string[]): Promise<number | undefined> {
+  const [groupName, verbName] = rawArgv;
+  if (!groupName || groupName.startsWith("-")) return undefined;
+
+  const plugins = await loadPluginsBestEffort();
+  const rawArgs = rawArgv.slice(2);
+  const result = await dispatchCommandGroup(plugins, groupName, verbName, rawArgs);
+
+  if (result.kind === "no-group") return undefined;
+  if (result.kind === "usage-error") {
+    console.error(formatError({ message: result.message, hint: result.hint }));
+    return 1;
+  }
+  return result.exitCode;
 }
 
 /**
@@ -610,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 },
@@ -688,10 +747,29 @@ const registry: CommandDef[] = [
  * Main entry point
  */
 async function main(): Promise<void> {
-  const args = parseArgs(process.argv.slice(2));
+  const rawArgv = process.argv.slice(2);
+
+  let args: ParsedArgs;
+  try {
+    args = parseArgs(rawArgv);
+  } catch (err) {
+    // chant #1078 — core's parser has no idea what flags a lexicon's own
+    // mounted verb accepts, so an "unknown flag" here is expected, not a
+    // real error, until we've checked whether this invocation actually
+    // targets a command group. `tryPluginCommand` returns `undefined` when
+    // nothing claims the leading token, in which case this was a genuine
+    // core-flag error and the original is rethrown unchanged.
+    const code = await tryPluginCommand(rawArgv);
+    if (code !== undefined) {
+      await flushAndExit(code);
+      return;
+    }
+    throw err;
+  }
 
   if (args.help || !args.command) {
-    printHelp();
+    const groups = await loadPluginsBestEffort().then(collectCommandGroups).catch(() => []);
+    printHelp(groups);
     process.exit(args.help ? 0 : 1);
   }
 
@@ -742,6 +820,15 @@ async function main(): Promise<void> {
 
   const match = resolveCommand(args, registry);
   if (!match) {
+    // chant #1078 — not one of core's own commands; check whether a lexicon
+    // mounted a command group under this name before giving up. This is the
+    // "parsed fine, matched nothing" trigger for the seam — the flag-error
+    // trigger is above, in the `parseArgs` catch block.
+    const code = await tryPluginCommand(rawArgv);
+    if (code !== undefined) {
+      await flushAndExit(code);
+      return;
+    }
     console.error(formatError({
       message: `Unknown command: ${args.command}`,
       hint: 'Run "chant --help" to see available commands',

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/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: {} };
+}

package/src/graph-effective.test.ts

@@ -0,0 +1,97 @@
+import { describe, it, expect } from "vitest";
+import { enrichEffectiveTopology } from "./graph-effective";
+import type { GraphIR } from "./graph-ir";
+
+function node(id: string, kind: string, attrs: Record<string, unknown> = {}) {
+  return { id, kind: `AWS::EC2::${kind}`, attrs };
+}
+const sshRule = { IpProtocol: "tcp", FromPort: 22, ToPort: 22, CidrIp: "0.0.0.0/0" };
+
+/**
+ * webServer:  direct SG with SSH-open, subnet routes to an IGW  → SSH-reachable
+ * ltServer:   SG via LAUNCH TEMPLATE, same public subnet        → SSH-reachable (the CLI-missed hop)
+ * westServer: public subnet (IGW) but its SG has NO ingress     → internet-facing, not SSH-open
+ * privServer: private subnet (no IGW route)                     → not internet-facing
+ */
+const ir: GraphIR = {
+  nodes: [
+    node("webServer", "Instance"),
+    node("ltServer", "Instance"),
+    node("westServer", "Instance"),
+    node("privServer", "Instance"),
+    node("webSg", "SecurityGroup", { SecurityGroupIngress: [sshRule, { IpProtocol: "tcp", FromPort: 80, ToPort: 80, CidrIp: "0.0.0.0/0" }] }),
+    node("westSg", "SecurityGroup", { SecurityGroupIngress: [] }),
+    node("lt", "LaunchTemplate"),
+    node("pubSubnet", "Subnet"),
+    node("westSubnet", "Subnet"),
+    node("privSubnet", "Subnet"),
+    node("pubRt", "RouteTable"),
+    node("westRt", "RouteTable"),
+    node("pubAssoc", "SubnetRouteTableAssociation"),
+    node("westAssoc", "SubnetRouteTableAssociation"),
+    node("pubRoute", "Route", { DestinationCidrBlock: "0.0.0.0/0" }),
+    node("westRoute", "Route", { DestinationCidrBlock: "0.0.0.0/0" }),
+    node("igw", "InternetGateway"),
+    node("westIgw", "InternetGateway"),
+  ] as never,
+  edges: [
+    { from: "webServer", to: "webSg", viaAttr: "SecurityGroupIds" },
+    { from: "webServer", to: "pubSubnet", viaAttr: "SubnetId" },
+    { from: "ltServer", to: "lt", viaAttr: "LaunchTemplate" },
+    { from: "lt", to: "webSg", viaAttr: "LaunchTemplateData" },
+    { from: "ltServer", to: "pubSubnet", viaAttr: "SubnetId" },
+    { from: "westServer", to: "westSg", viaAttr: "SecurityGroupIds" },
+    { from: "westServer", to: "westSubnet", viaAttr: "SubnetId" },
+    { from: "privServer", to: "privSubnet", viaAttr: "SubnetId" },
+    { from: "pubAssoc", to: "pubSubnet", viaAttr: "SubnetId" },
+    { from: "pubAssoc", to: "pubRt", viaAttr: "RouteTableId" },
+    { from: "pubRoute", to: "pubRt", viaAttr: "RouteTableId" },
+    { from: "pubRoute", to: "igw", viaAttr: "GatewayId" },
+    { from: "westAssoc", to: "westSubnet", viaAttr: "SubnetId" },
+    { from: "westAssoc", to: "westRt", viaAttr: "RouteTableId" },
+    { from: "westRoute", to: "westRt", viaAttr: "RouteTableId" },
+    { from: "westRoute", to: "westIgw", viaAttr: "GatewayId" },
+  ] as never,
+  groups: {},
+};
+
+describe("enrichEffectiveTopology", () => {
+  const enriched = enrichEffectiveTopology(ir);
+  const attrs = (id: string) => enriched.nodes.find((n) => n.id === id)!.attrs as Record<string, unknown>;
+
+  it("resolves the security group reached VIA a launch template (the CLI-missed hop)", () => {
+    expect(attrs("ltServer").effectiveIngress).toContain("tcp:22:0.0.0.0/0");
+  });
+
+  it("resolves a direct security group", () => {
+    expect(attrs("webServer").effectiveIngress).toContain("tcp:22:0.0.0.0/0");
+  });
+
+  it("marks instances whose subnet routes to an IGW as internetFacing", () => {
+    expect(attrs("webServer").internetFacing).toBe(true);
+    expect(attrs("ltServer").internetFacing).toBe(true);
+    expect(attrs("westServer").internetFacing).toBe(true);
+    expect(attrs("privServer").internetFacing).toBe(false);
+  });
+
+  it("keeps a live-supplied internetFacing (e.g. default VPC) even with no declared route", () => {
+    // A live enrichment marks an instance internetFacing; its subnet's routing
+    // is not in the declared graph (the account's default VPC). Enrichment
+    // must NOT overwrite that truth back to false.
+    const withLive: GraphIR = {
+      nodes: [node("defaultVpcServer", "Instance", { internetFacing: true })] as never,
+      edges: [] as never,
+      groups: {},
+    };
+    const out = enrichEffectiveTopology(withLive);
+    expect((out.nodes[0].attrs as Record<string, unknown>).internetFacing).toBe(true);
+  });
+
+  it("SSH-reachable = internetFacing AND effectiveIngress tcp:22:0.0.0.0/0 → only web + lt", () => {
+    const reachable = enriched.nodes.filter(
+      (n) => (n.attrs as Record<string, unknown>).internetFacing === true &&
+        ((n.attrs as Record<string, unknown>).effectiveIngress as string[] | undefined)?.includes("tcp:22:0.0.0.0/0"),
+    );
+    expect(reachable.map((n) => n.id).sort()).toEqual(["ltServer", "webServer"]);
+  });
+});