@intentius/chant 0.31.0 → 0.33.0

package/src/cli/command-group.ts

@@ -0,0 +1,199 @@
+import type { LexiconPlugin } from "../lexicon";
+
+/**
+ * The lexicon command-group seam (chant #1078).
+ *
+ * A lexicon may contribute one CLI verb group, mounted under `chant <name>
+ * <verb>` (e.g. `chant kube get`). Core's only job is to find the group and
+ * call the matched verb's handler — it never inspects, validates, or
+ * special-cases what a verb does. That is the whole point: `get -o wide -l
+ * app=x --field-selector` is Kubernetes vocabulary, not something core could
+ * generalize even if it tried (see #1078's motivating case, consumed by
+ * #1079's `chant kube`).
+ *
+ * This is a DIFFERENT shape from `LexiconPlugin.emulator` (#920): the
+ * emulator capability is DATA that core itself aggregates across every
+ * configured lexicon (`chant emulator up --all` loops every plugin with an
+ * `emulator`). A command group is BEHAVIOR owned end-to-end by one lexicon —
+ * core dispatches to it wholesale and never loops or merges across plugins.
+ * The two capabilities are not layers of the same thing; migrating
+ * `emulator` onto this seam would be a worse fit, not a simplification.
+ */
+
+/** Context handed to a mounted command's handler. */
+export interface CommandGroupContext {
+  /** The verb invoked, e.g. `"get"` for `chant kube get pods`. */
+  verb: string;
+  /**
+   * Every CLI token after the group name and verb, unparsed — e.g. `chant
+   * kube get pods -o wide` hands `["pods", "-o", "wide"]`. Core does not
+   * interpret these: it has no vocabulary for a lexicon's own verbs. A
+   * handler that wants #1127's joined-`--flag=value` splitting and
+   * unknown-flag rejection can reuse {@link splitJoinedFlags} /
+   * {@link unknownFlagError} from this module for the same discipline core's
+   * own parser applies, scoped to whatever flags this verb actually accepts.
+   */
+  rawArgs: string[];
+}
+
+/** One verb within a lexicon-contributed command group. */
+export interface CommandGroupCommand {
+  /** Verb name, e.g. `"get"`, `"logs"`, `"version"`. */
+  name: string;
+  /** One-line description shown in `chant --help` and in usage errors. */
+  description: string;
+  /** Runs the verb. Returns the process exit code. */
+  handler: (ctx: CommandGroupContext) => Promise<number>;
+}
+
+/**
+ * A CLI verb group contributed by a lexicon (chant #1078). Mounted under
+ * `chant <name> <verb>`. Returned from {@link LexiconPlugin.commands}.
+ */
+export interface CommandGroup {
+  /** Namespace this group mounts under, e.g. `"kube"` for `chant kube <verb>`. */
+  name: string;
+  /** One-line description shown in `chant --help`'s composed listing. */
+  description: string;
+  /** Verbs in this group. */
+  commands: CommandGroupCommand[];
+}
+
+/**
+ * Top-level command words core's own static registry already owns
+ * (`packages/core/src/cli/main.ts`'s `registry`). A lexicon's `commands()`
+ * group name colliding with one of these is always unreachable — core's own
+ * registry is resolved first, unconditionally — so `checkConflicts`
+ * (./conflict-check.ts) treats a collision as a hard, loud failure at
+ * plugin-load time rather than a silently-ignored command group. Hand
+ * maintained alongside the registry; update both together.
+ */
+export const RESERVED_COMMAND_NAMES: ReadonlySet<string> = new Set([
+  "build", "lint", "list", "describe", "import", "audit", "migrate", "carve",
+  "init", "update", "doctor", "dev", "run", "graph", "vendor", "lifecycle",
+  "lc", "components", "emulator", "serve",
+]);
+
+/**
+ * chant #1127 — split a joined `--flag=value` token into two array elements
+ * (`--flag`, `value`), the same discipline core's own `parseArgs` applies,
+ * generalized so a lexicon's mounted command can reuse it for its own flag
+ * vocabulary instead of reimplementing the split. Throws the same shape of
+ * error as core's parser when `flag` is declared boolean but was given a
+ * value — a boolean has nothing to assign, and silently reinterpreting the
+ * joined value as the next positional would be exactly the silent misparse
+ * #1127 closed for core's own flags.
+ */
+export function splitJoinedFlags(args: string[], booleanFlags: ReadonlySet<string> = new Set()): string[] {
+  const out: string[] = [];
+  for (const arg of args) {
+    if (arg.startsWith("--") && arg.includes("=")) {
+      const eq = arg.indexOf("=");
+      const flag = arg.slice(0, eq);
+      const value = arg.slice(eq + 1);
+      if (booleanFlags.has(flag)) {
+        throw new Error(`${arg} — ${flag} is a boolean flag and does not take a value. Pass ${flag} on its own.`);
+      }
+      out.push(flag, value);
+    } else {
+      out.push(arg);
+    }
+  }
+  return out;
+}
+
+/**
+ * Same "Unknown flag" error shape core's own `parseArgs` throws (#1127), for
+ * a mounted command's own flag vocabulary — core doesn't know that
+ * vocabulary, so it can't produce this error itself; the handler does, using
+ * this helper for a consistent message.
+ */
+export function unknownFlagError(flag: string, hint = `Run "chant --help" to see supported flags.`): Error {
+  return new Error(`Unknown flag: ${flag}\n${hint}`);
+}
+
+/** Result of looking up a command group + verb among loaded plugins. */
+export type CommandGroupLookup =
+  | { kind: "no-group" }
+  | { kind: "no-verb"; group: CommandGroup }
+  | { kind: "unknown-verb"; group: CommandGroup }
+  | { kind: "matched"; plugin: LexiconPlugin; group: CommandGroup; command: CommandGroupCommand };
+
+/**
+ * Find the plugin (if any) whose `commands()` group is named `groupName`,
+ * and the verb within it named `verbName`. Pure — does no I/O, calls
+ * `plugin.commands()` at most once per plugin (registration, not execution:
+ * this never invokes a verb's handler).
+ */
+export function resolveCommandGroupVerb(
+  plugins: readonly LexiconPlugin[],
+  groupName: string,
+  verbName: string | undefined,
+): CommandGroupLookup {
+  for (const plugin of plugins) {
+    const group = plugin.commands?.();
+    if (!group || group.name !== groupName) continue;
+    if (verbName === undefined) return { kind: "no-verb", group };
+    const command = group.commands.find((c) => c.name === verbName);
+    if (!command) return { kind: "unknown-verb", group };
+    return { kind: "matched", plugin, group, command };
+  }
+  return { kind: "no-group" };
+}
+
+/** Every command group contributed by the given loaded plugins, in plugin order. */
+export function collectCommandGroups(plugins: readonly LexiconPlugin[]): CommandGroup[] {
+  const groups: CommandGroup[] = [];
+  for (const plugin of plugins) {
+    const group = plugin.commands?.();
+    if (group) groups.push(group);
+  }
+  return groups;
+}
+
+/** Result of {@link dispatchCommandGroup}. */
+export type CommandGroupDispatch =
+  | { kind: "no-group" }
+  | { kind: "usage-error"; message: string; hint: string }
+  | { kind: "ran"; exitCode: number };
+
+/**
+ * Resolve `groupName`/`verbName` against the loaded plugins and, if matched,
+ * run the verb's handler with `rawArgs`. Returns `{ kind: "no-group" }` when
+ * nothing claims `groupName` at all — the caller's cue to fall back to its
+ * own "unknown command" handling — and a printable usage error when the
+ * group matched but the verb didn't (or was omitted).
+ */
+export async function dispatchCommandGroup(
+  plugins: readonly LexiconPlugin[],
+  groupName: string,
+  verbName: string | undefined,
+  rawArgs: string[],
+): Promise<CommandGroupDispatch> {
+  const lookup = resolveCommandGroupVerb(plugins, groupName, verbName);
+  if (lookup.kind === "no-group") return { kind: "no-group" };
+  if (lookup.kind === "matched") {
+    const exitCode = await lookup.command.handler({ verb: verbName as string, rawArgs });
+    return { kind: "ran", exitCode };
+  }
+  const verbs = lookup.group.commands.map((c) => `  ${c.name.padEnd(14)} ${c.description}`).join("\n");
+  const message =
+    lookup.kind === "unknown-verb"
+      ? `Unknown ${groupName} subcommand: ${verbName}`
+      : `Usage: chant ${groupName} <verb> [args...]`;
+  return { kind: "usage-error", message, hint: `Available verbs:\n${verbs}` };
+}
+
+/**
+ * Render the `--help` section listing every lexicon-contributed command
+ * group. Empty string when there are none, so a caller can splice it in
+ * unconditionally without an extra length check.
+ */
+export function formatCommandGroupsHelp(groups: readonly CommandGroup[]): string {
+  if (groups.length === 0) return "";
+  const lines = groups.flatMap((g) => [
+    `  ${g.name.padEnd(20)}  ${g.description}`,
+    ...g.commands.map((c) => `    ${g.name} ${c.name.padEnd(Math.max(1, 17 - g.name.length))}${c.description}`),
+  ]);
+  return `Lexicon commands:\n${lines.join("\n")}\n`;
+}

package/src/cli/conflict-check.test.ts

@@ -1,6 +1,6 @@
 import { describe, test, expect } from "vitest";
 import { checkConflicts } from "./conflict-check";
-import type { LexiconPlugin } from "../lexicon";
+import type { LexiconPlugin, CommandGroup } from "../lexicon";
 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 const mockSerializer = { name: "test", serialize: () => ({}) } as any;
@@ -14,6 +14,7 @@ function makePlugin(
     skills?: { name: string }[];
     mcpTools?: { name: string }[];
     mcpResources?: { uri: string }[];
+    commandGroup?: CommandGroup;
   } = {},
 ): LexiconPlugin {
   const plugin: LexiconPlugin = {
@@ -57,6 +58,11 @@ function makePlugin(
     (plugin as any).mcpTools = () => tools;
   }
 
+  if (opts.commandGroup) {
+    const group = opts.commandGroup;
+    plugin.commands = () => group;
+  }
+
   if (opts.mcpResources) {
     const resources = opts.mcpResources.map((r) => ({
       uri: r.uri,
@@ -202,6 +208,35 @@ describe("checkConflicts", () => {
     expect(report.warnings.filter((w) => w.type === "mcp-resource")).toHaveLength(0);
   });
 
+  // -----------------------------------------------------------------------
+  // Command-group name conflicts (hard, chant #1078)
+  // -----------------------------------------------------------------------
+
+  test("detects two lexicons claiming the same command-group name as a hard conflict", () => {
+    const plugins = [
+      makePlugin("k8s", { commandGroup: { name: "kube", description: "d", commands: [] } }),
+      makePlugin("fly", { commandGroup: { name: "kube", description: "d2", commands: [] } }),
+    ];
+    const report = checkConflicts(plugins);
+    expect(report.conflicts).toEqual([{ type: "command-group-name", key: "kube", plugins: ["k8s", "fly"] }]);
+    expect(report.warnings).toHaveLength(0);
+  });
+
+  test("detects a command-group name colliding with a reserved core command word", () => {
+    const plugins = [makePlugin("rogue", { commandGroup: { name: "build", description: "d", commands: [] } })];
+    const report = checkConflicts(plugins);
+    expect(report.conflicts).toEqual([{ type: "command-group-name", key: "build", plugins: ["rogue"] }]);
+  });
+
+  test("no conflict for a single lexicon's own, non-reserved command-group name", () => {
+    const plugins = [
+      makePlugin("k8s", { commandGroup: { name: "kube", description: "d", commands: [] } }),
+      makePlugin("aws"),
+    ];
+    const report = checkConflicts(plugins);
+    expect(report.conflicts.filter((c) => c.type === "command-group-name")).toHaveLength(0);
+  });
+
   // -----------------------------------------------------------------------
   // Combined
   // -----------------------------------------------------------------------

package/src/cli/conflict-check.ts

@@ -1,7 +1,8 @@
 import type { LexiconPlugin } from "../lexicon";
+import { RESERVED_COMMAND_NAMES } from "./command-group";
 
 export interface ConflictEntry {
-  type: "rule-id" | "skill-name" | "mcp-tool" | "mcp-resource";
+  type: "rule-id" | "skill-name" | "mcp-tool" | "mcp-resource" | "command-group-name";
   key: string;
   plugins: string[];
 }
@@ -85,5 +86,25 @@ export function checkConflicts(plugins: LexiconPlugin[]): ConflictReport {
     }
   }
 
+  // Check command-group name conflicts (hard, chant #1078). Two shapes:
+  // two lexicons claiming the same group name (only one would ever be
+  // reachable, silently), or one lexicon claiming a name core's own static
+  // registry already owns (permanently unreachable — core resolves its own
+  // registry first, unconditionally). Either is a silent-shadowing bug
+  // class, so both are hard conflicts rather than warnings.
+  const commandGroupNames = new Map<string, string[]>();
+  for (const plugin of plugins) {
+    const group = plugin.commands?.();
+    if (!group) continue;
+    const existing = commandGroupNames.get(group.name) ?? [];
+    existing.push(plugin.name);
+    commandGroupNames.set(group.name, existing);
+  }
+  for (const [name, owners] of commandGroupNames) {
+    if (owners.length > 1 || RESERVED_COMMAND_NAMES.has(name)) {
+      conflicts.push({ type: "command-group-name", key: name, plugins: owners });
+    }
+  }
+
   return { conflicts, warnings };
 }

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

@@ -490,7 +490,7 @@ describe("runGraph", () => {
       expect(exit).toBe(0);
       expect(observeMock).toHaveBeenCalledTimes(1);
       const [, , , opts] = observeMock.mock.calls[0];
-      expect((opts as { stacks: string[] }).stacks.sort()).toEqual([
+      expect((opts as { stacks: Array<{name:string}> }).stacks.map((x)=>x.name).sort()).toEqual([
         "loom-local-a-loom-backend",
         "loom-local-a-loom-backend-jobs",
         "loom-local-a-loom-db",

package/src/cli/handlers/graph.ts

@@ -3,6 +3,7 @@ import { discoverOps } from "../../op/discover";
 import { discover } from "../../discovery/index";
 import { partitionByLexicon, computeStackGraph, build } from "../../build";
 import { buildGraphIr, buildLiveGraphIr, collectUnobserved, overlayGraphs, sourceOverlayGraphs, type GraphIR, type IRPipeline, type LiveObservation } from "../../graph-ir";
+import { buildDeclaredPerStack } from "../../graph-declared";
 import { reconstructEdges, mergeCatalogs, containmentGroups, type ReferenceCatalog, type ContainmentPair } from "../../graph-refs";
 import { observeResources } from "../../lifecycle/observe";
 import { loadChantConfig, environmentNames } from "../../config";
@@ -126,14 +127,21 @@ async function runGraphLive(
   const componentsDiscovery = await discoverComponents(resolve(args.src ?? config.sourceDir ?? "."), {
     sandbox: args.sandbox,
   });
-  const stacks = new Set<string>();
+  const stacks: Array<{ name: string; region?: string; src?: string }> = [];
+  const seenStacks = new Set<string>();
   if (componentsDiscovery.errors.length === 0) {
     for (const { component } of componentsDiscovery.components.values()) {
-      for (const stack of cfnDeployStacks(component.deploy)) stacks.add(stack);
+      for (const stack of cfnDeployStacks(component.deploy)) {
+        if (!seenStacks.has(stack)) { seenStacks.add(stack); stacks.push({ name: stack }); }
+      }
     }
   } else {
     console.error(formatWarning({ message: "component discovery failed — observing the single-stack convention instead" }));
   }
+  // ChantConfig.stacks (with optional per-stack region) — multi-region estates.
+  for (const declared of config.stacks ?? []) {
+    if (!seenStacks.has(declared.name)) { seenStacks.add(declared.name); stacks.push({ name: declared.name, region: declared.region, src: declared.src }); }
+  }
 
   // #1166 — an environment can declare its own endpoint (a local emulator like
   // Floci), so this read is self-sufficient even when the ambient shell never
@@ -174,7 +182,7 @@ async function runGraphLive(
     for (const p of observing) {
       if (!p.enrichLiveAttrs) continue;
       try {
-        const enriched = await p.enrichLiveAttrs({ environment, owned: true });
+        const enriched = await p.enrichLiveAttrs({ environment, owned: true, stacks });
         ir = {
           ...ir,
           nodes: ir.nodes.map((n) =>
@@ -205,19 +213,33 @@ async function runGraphLive(
   //     so cross-substrate topology survives; live status joined per node.
   //   - live (#780): provisioned graph is the canvas — reconstructed live edges.
   if (args.overlay) {
-    const declared = await discover(resolve(args.src ?? config.sourceDir ?? "."));
-    if (declared.errors.length === 0) {
-      const declaredIr = buildGraphIr(declared.entities, projectPath);
-      // Declared nodes chant could not read are painted `neutral`, not
-      // `accent`/pending (#1089) — a wrong-cluster or unsupported-kind read
-      // must not draw the estate as "not deployed yet".
-      const overlayOpts = { unobserved: collectUnobserved(observations) };
+    // Declared nodes chant could not read are painted `neutral`, not
+    // `accent`/pending (#1089) — a wrong-cluster or unsupported-kind read must
+    // not draw the estate as "not deployed yet".
+    const overlayOpts = { unobserved: collectUnobserved(observations) };
+    // Multi-stack (#1162): the live `ir` keys nodes by `${stack}::${logicalId}`,
+    // so the declared canvas must qualify identically — build each stack's src
+    // scoped rather than a flat whole-project discovery (whose disambiguated
+    // names never match the observed bare ids). Fall back to the flat build when
+    // no stack carries a `src`.
+    const scopedStacks = stacks.filter((s) => s.src);
+    if (scopedStacks.length > 0) {
+      const declaredIr = await buildDeclaredPerStack(scopedStacks, projectPath);
       ir =
         args.overlayAnchor === "live"
           ? overlayGraphs(ir, declaredIr, overlayOpts)
           : sourceOverlayGraphs(declaredIr, ir, overlayOpts);
     } else {
-      console.error(formatWarning({ message: "overlay: source has discovery errors — showing the provisioned graph without the declared overlay" }));
+      const declared = await discover(resolve(args.src ?? config.sourceDir ?? "."));
+      if (declared.errors.length === 0) {
+        const declaredIr = buildGraphIr(declared.entities, projectPath);
+        ir =
+          args.overlayAnchor === "live"
+            ? overlayGraphs(ir, declaredIr, overlayOpts)
+            : sourceOverlayGraphs(declaredIr, ir, overlayOpts);
+      } else {
+        console.error(formatWarning({ message: "overlay: source has discovery errors — showing the provisioned graph without the declared overlay" }));
+      }
     }
   }
 

package/src/cli/handlers/lifecycle.ts

@@ -857,6 +857,7 @@ function renderLiveDiff(lexiconName: string, environment: string, diff: LiveDiff
     `${diff.missing.length} missing, ${diff.orphan.length} orphan, ` +
     `${diff.disappeared.length} disappeared, ${diff.newlyObserved.length} newly observed, ` +
     `${diff.driftedSinceSnapshot.length} drifted, ${diff.unchanged.length} unchanged` +
+    (diff.runtimeChildren.length > 0 ? `, ${diff.runtimeChildren.length} runtime` : "") +
     (diff.unobserved.length > 0 ? `, ${diff.unobserved.length} unobserved` : "");
 
   console.log(`\n${formatBold(lexiconName)} — environment: ${environment}`);
@@ -877,6 +878,10 @@ function renderLiveDiff(lexiconName: string, environment: string, diff: LiveDiff
     console.log(formatBold("\nORPHAN (in cloud, not declared):"));
     for (const name of diff.orphan) console.log(`  - ${name}`);
   }
+  if (diff.runtimeChildren.length > 0) {
+    console.log(formatBold("\nRUNTIME (owned by a declared resource; not drift, not an orphan — #1077):"));
+    for (const r of diff.runtimeChildren) console.log(`  - ${r.name} (${r.type}) — owned by ${r.owner}`);
+  }
   if (diff.disappeared.length > 0) {
     console.log(formatBold("\nDISAPPEARED (in last snapshot, gone now):"));
     for (const name of diff.disappeared) console.log(`  - ${name}`);

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

@@ -0,0 +1,113 @@
+import { describe, test, expect, vi } from "vitest";
+import { __searchInternals } from "./search";
+
+const { parseQuery, matchTerm, formatRow, explain, describeTerm } = __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)");
+  });
+});