@intentius/chant 0.37.2 → 0.39.0

package/src/cli/handlers/search.ts

@@ -1,6 +1,6 @@
 import { resolve } from "node:path";
 import { build } from "../../build";
-import { buildGraphIr, buildLiveGraphIr, sourceOverlayGraphs, type GraphIR, type IRNode } from "../../graph-ir";
+import { buildGraphIr, buildLiveGraphIr, sourceOverlayGraphs, type GraphIR, type IRNode, type IREdge } from "../../graph-ir";
 import { buildDeclaredPerStack } from "../../graph-declared";
 import { enrichEffectiveTopology } from "../../graph-effective";
 import { reconstructEdges, mergeCatalogs, type ReferenceCatalog } from "../../graph-refs";
@@ -127,6 +127,8 @@ export async function runSearch(ctx: CommandContext): Promise<number> {
       source = { kind: "live" };
     }
     let live = buildLiveGraphIr(observations);
+    // Containment edges, kept aside until after the overlay (see below).
+    let containmentEdges: IREdge[] = [];
     // Live-only: enrichment is a provider call, so it has no place in a replay.
     // A recorded answer that quietly reached for the API would stop being one.
     if (!args.at) {
@@ -147,13 +149,24 @@ export async function runSearch(ctx: CommandContext): Promise<number> {
     // topology has nothing to traverse on anything the declared graph does not
     // already model.
     const catalogs = observing.map((p) => p.referenceCatalog).filter((c): c is ReferenceCatalog => !!c);
+    // Held back until after the overlay — see where it is merged for why.
     if (catalogs.length > 0) {
       // Merge, never replace. A lexicon reports relationships a catalog cannot
       // reconstruct (#1273) — an instance placed in a subnet it did not declare
       // carries a template `Ref` in its attributes, not the physical subnet id,
       // so no identity index resolves it. Overwriting here dropped exactly those
       // edges and left the fold with a chain missing its first hop.
-      const reconstructed = reconstructEdges(live.nodes, mergeCatalogs(catalogs)).edges;
+      // Containment travels with the references here, and only here. `->`/`<-`
+      // asks which nodes reach which, and being inside something is a way of
+      // reaching it: "which subnets have no network interfaces IN them" and
+      // "which VPCs have no instances IN them" are containment questions, and
+      // with only peer references to walk the negation matched everything.
+      //
+      // `graph` still reads `.containment` on its own and draws boundary boxes,
+      // so nothing gains a line it did not have.
+      const rebuilt = reconstructEdges(live.nodes, mergeCatalogs(catalogs));
+      containmentEdges = rebuilt.containmentEdges;
+      const reconstructed = rebuilt.edges;
       const seen = new Set((live.edges ?? []).map((e) => `${e.from}|${e.to}|${e.viaAttr ?? ""}`));
       live = {
         ...live,
@@ -177,6 +190,36 @@ export async function runSearch(ctx: CommandContext): Promise<number> {
         ? await buildDeclaredPerStack(stacks, projectPath)
         : buildGraphIr((await discover(resolve(args.src ?? config.sourceDir ?? "."))).entities, projectPath);
     ir = sourceOverlayGraphs(declared, live);
+    // Containment goes on AFTER the overlay, not through it.
+    //
+    // `sourceOverlayGraphs` admits a live edge only when one end is foreign,
+    // because "declared edges already cover every declared relationship". That
+    // is true of the references it was written for and false of containment:
+    // the declared canvas carries what the source *says*, and no source says
+    // "this instance is in this VPC" — the instance declares a subnet, and the
+    // VPC is implied by the account.
+    //
+    // So an instance and its VPC, both declared, had their containment dropped
+    // between them, while an instance in the account's DEFAULT VPC kept it
+    // because that VPC is foreign. "Which VPCs have no instances" answered
+    // correctly for the one VPC nobody declared and wrongly for every VPC
+    // somebody did.
+    if (containmentEdges.length > 0) {
+      const present = new Set(ir.nodes.map((n) => n.id));
+      const seen = new Set(ir.edges.map((e) => `${e.from}|${e.to}|${e.viaAttr ?? ""}`));
+      ir = {
+        ...ir,
+        edges: [
+          ...ir.edges,
+          ...containmentEdges.filter(
+            (e) =>
+              present.has(e.from) &&
+              present.has(e.to) &&
+              !seen.has(`${e.from}|${e.to}|${e.viaAttr ?? ""}`),
+          ),
+        ],
+      };
+    }
     // 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
@@ -190,6 +233,9 @@ export async function runSearch(ctx: CommandContext): Promise<number> {
   // Fold derived reachability facts (effectiveIngress, internetFacing) onto
   // instance nodes so multi-hop/launch-template joins are one node predicate (#1139).
   ir = enrichEffectiveTopology(ir);
+  // Resolve `kind:` terms against what is actually in this graph, before any
+  // node is tested against them.
+  resolveKindTerms(terms, ir.nodes);
   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) {
@@ -489,7 +535,7 @@ function describeTerm(t: Term): string {
   return leaf(t);
 }
 
-interface Term {
+export interface Term {
   kind: "word" | "kind" | "tag" | "attr" | "edge";
   /** `!term` — the node must NOT satisfy this (#1280). */
   negated?: boolean;
@@ -498,6 +544,53 @@ interface Term {
   /** For edge terms: the direction and the sub-predicate matched at the far end. */
   dir?: "out" | "in";
   sub?: Term;
+  /**
+   * For kind terms: the kinds this term actually means, resolved against the
+   * graph (see {@link resolveKindTerms}). Absent when nothing resolved it, in
+   * which case the substring rule applies unchanged.
+   */
+  kinds?: Set<string>;
+}
+
+/**
+ * Decide which kinds a `kind:` term means, given what is in the graph.
+ *
+ * `kind:` is documented as a substring, and substrings of a CloudFormation type
+ * cross kind boundaries: `kind:EC2::VPC` also matches
+ * `AWS::EC2::VPCGatewayAttachment`, and `kind:EC2::Subnet` also matches
+ * `AWS::EC2::SubnetRouteTableAssociation`. An estate with 6 VPCs answers 9, and
+ * the caller has no reason to suspect the number they were given.
+ *
+ * That cost real answers. Asked how many VPCs have no instances, agents named
+ * the right VPCs and reported "9 VPCs in the estate" beside them; the grader
+ * failed the answer for contradicting the estate, which it did.
+ *
+ * So: a term that lines up with `::` boundaries means those kinds and only
+ * those. `EC2::VPC` is the last two segments of `AWS::EC2::VPC` and is not any
+ * run of segments in `AWS::EC2::VPCGatewayAttachment`, because
+ * `VPCGatewayAttachment` is not `VPC`.
+ *
+ * Substring is kept as the fallback, so `kind:Gateway` still finds both
+ * `InternetGateway` and `VPCGatewayAttachment` — a genuine substring search
+ * that no segment rule would serve. Most specific wins; nothing else changes.
+ */
+export function resolveKindTerms(terms: Term[], nodes: IRNode[]): void {
+  const present = [...new Set(nodes.map((n) => n.kind).filter((k): k is string => !!k))];
+  const walk = (t: Term): void => {
+    if (t.sub) walk(t.sub);
+    if (t.kind !== "kind") return;
+    const want = t.a.toLowerCase().split("::").filter(Boolean);
+    if (want.length === 0) return;
+    const onBoundary = present.filter((k) => {
+      const have = k.toLowerCase().split("::");
+      for (let i = 0; i + want.length <= have.length; i++) {
+        if (want.every((w, j) => have[i + j] === w)) return true;
+      }
+      return false;
+    });
+    if (onBoundary.length > 0) t.kinds = new Set(onBoundary);
+  };
+  terms.forEach(walk);
 }
 
 function parseLeaf(tok: string): Term {
@@ -616,7 +709,12 @@ function matchTerm(n: IRNode, t: Term, ir?: GraphIR, byId?: Map<string, IRNode>)
       .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 === "kind") {
+    // Resolved kinds when the term lined up with `::` boundaries; the
+    // documented substring otherwise.
+    if (t.kinds) return t.kinds.has(n.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());

package/src/cli/main.ts

@@ -6,6 +6,7 @@ import { formatSuccess, formatError } from "./format";
 import { loadPlugins, resolveProjectLexicons } from "./plugins";
 import { resolveCommand, type CommandDef, type ParsedArgs } from "./registry";
 import { loadChantConfigUpward } from "../config";
+import { validateLexiconConfig, formatLexiconConfigProblems } from "../lexicon-config";
 import { armSandboxConfigEvaluation } from "../config-sandbox";
 import { armSandboxPolicyExecution } from "../lint/policy-import";
 import { ENV_VAR, unknownEnvError } from "../env";
@@ -559,16 +560,17 @@ Options:
                         project source; network egress is NOT blocked (see
                         docs). Default: off (also settable via
                         chant.config.ts's build.sandbox: true; #1045)
-  --param <name=value>  (build) Bind a declared build-time parameter
-                        (chant.config.ts's buildParams) to a value, for
-                        source to read as params.<name> (#1064) instead of
-                        process.env — repeatable. Distinct from the AWS
-                        lexicon's deploy-time Parameter(): this resolves
-                        before synthesis, so it can change which resources
-                        are produced at all. Highest precedence.
-  --params-file <path>  (build) JSON file of { "name": value } build-time
-                        parameter values (#1064). Second precedence, after
-                        --param.
+  --param <name=value>  (build, graph, run --components) Bind a declared
+                        build-time parameter (chant.config.ts's buildParams)
+                        to a value, for source to read as params.<name>
+                        (#1064) instead of process.env — repeatable.
+                        Distinct from the AWS lexicon's deploy-time
+                        Parameter(): this resolves before synthesis, so it
+                        can change which resources are produced at all.
+                        Highest precedence.
+  --params-file <path>  (build, graph, run --components) JSON file of
+                        { "name": value } build-time parameter values
+                        (#1064). Second precedence, after --param.
 
 Examples:
   chant build ./infra/
@@ -668,6 +670,26 @@ async function loadPluginsOrExit(path: string): Promise<import("../lexicon").Lex
     process.exit(1);
   }
 
+  // #1344 — a lexicon that declares the shape of its own `chant.config.ts`
+  // namespace gets it validated here, once, before any command runs. The
+  // config schema is `.passthrough()`, so before this an unknown key inside a
+  // namespace was accepted and silently ignored: `forgejo: { runnerLabel: … }`
+  // left the dialect on its defaults with nothing said. A namespace whose
+  // lexicon declares no schema keeps that passthrough.
+  try {
+    const { config } = await loadChantConfigUpward(resolve(path));
+    const problems = validateLexiconConfig(plugins, config);
+    if (problems.length > 0) {
+      console.error(formatError({
+        message: `Invalid lexicon configuration in chant.config:\n${formatLexiconConfigProblems(problems)}`,
+        hint: "Remove or correct the key. A lexicon's namespace accepts only the keys it declares.",
+      }));
+      process.exit(1);
+    }
+  } catch {
+    // No config, or one that failed to load — the caller's own handling stands.
+  }
+
   return plugins;
 }
 

package/src/cli/mcp/server.test.ts

@@ -1151,3 +1151,85 @@ describe("McpServer", () => {
     });
   });
 });
+
+describe("plugin namespacing is idempotent (#1341)", () => {
+  const tool = (name: string) => ({
+    name,
+    description: "d",
+    inputSchema: { type: "object" as const, properties: {} },
+    handler: async () => "",
+  });
+  const resource = (uri: string) => ({
+    uri,
+    name: "n",
+    description: "d",
+    mimeType: "text/plain",
+    handler: async () => "",
+  });
+
+  async function registeredToolNames(plugin: LexiconPlugin): Promise<string[]> {
+    const s = new McpServer([plugin]);
+    const res = await s.handleRequest({ jsonrpc: "2.0", id: 1, method: "tools/list" });
+    return (res.result as { tools: Array<{ name: string }> }).tools.map((t) => t.name);
+  }
+
+  async function registeredResourceUris(plugin: LexiconPlugin): Promise<string[]> {
+    const s = new McpServer([plugin]);
+    const res = await s.handleRequest({ jsonrpc: "2.0", id: 1, method: "resources/list" });
+    return (res.result as { resources: Array<{ uri: string }> }).resources.map((r) => r.uri);
+  }
+
+  test("a tool declared bare registers under one namespace", async () => {
+    const names = await registeredToolNames(
+      createMockPlugin({ name: "gitlab", mcpTools: () => [tool("migrate")] }),
+    );
+    expect(names).toContain("gitlab:migrate");
+  });
+
+  test("a tool that already carries its prefix is not prefixed twice", async () => {
+    // createDiffTool emits `${lexiconName}:diff`, and eleven lexicons write the
+    // prefix by hand — this is the case that shipped as `gitlab:gitlab:diff`.
+    const names = await registeredToolNames(
+      createMockPlugin({ name: "gitlab", mcpTools: () => [tool("gitlab:diff")] }),
+    );
+    expect(names).toContain("gitlab:diff");
+    expect(names).not.toContain("gitlab:gitlab:diff");
+  });
+
+  test("a prefix that merely looks like the lexicon's is left alone", async () => {
+    const names = await registeredToolNames(
+      createMockPlugin({ name: "git", mcpTools: () => [tool("gitlab:diff")] }),
+    );
+    expect(names).toContain("git:gitlab:diff");
+  });
+
+  test("a resource declared as a bare path registers under the lexicon", async () => {
+    const uris = await registeredResourceUris(
+      createMockPlugin({ name: "aws", mcpResources: () => [resource("examples/s3")] }),
+    );
+    expect(uris).toContain("chant://aws/examples/s3");
+  });
+
+  test("a resource carrying the colon form is not doubled", async () => {
+    const uris = await registeredResourceUris(
+      createMockPlugin({ name: "aws", mcpResources: () => [resource("aws:resource-catalog")] }),
+    );
+    expect(uris).toContain("chant://aws/resource-catalog");
+  });
+
+  test("the chant://lexicon/<name>/ form the authoring docs taught is normalized", async () => {
+    // azure followed lsp-mcp.mdx and shipped `chant://azure/chant://lexicon/azure/catalog`.
+    const uris = await registeredResourceUris(
+      createMockPlugin({ name: "azure", mcpResources: () => [resource("chant://lexicon/azure/catalog")] }),
+    );
+    expect(uris).toContain("chant://azure/catalog");
+    expect(uris.every((u) => u.indexOf("chant://", 1) === -1)).toBe(true);
+  });
+
+  test("an already-registered uri passes through unchanged", async () => {
+    const uris = await registeredResourceUris(
+      createMockPlugin({ name: "aws", mcpResources: () => [resource("chant://aws/catalog")] }),
+    );
+    expect(uris).toContain("chant://aws/catalog");
+  });
+});

package/src/cli/mcp/server.ts

@@ -12,6 +12,33 @@ import { createSnapshotTool, createDiffTool } from "./lifecycle-tools";
 import { createOpListTool, createOpRunTool, createOpStatusTool, createOpSignalTool, createOpReportTool } from "./op-tools";
 import { buildResourcesList, handleResourcesRead } from "./resource-handlers";
 
+/**
+ * The name a lexicon's MCP tool is registered under: `<lexicon>:<verb>`,
+ * whether or not the lexicon already wrote the prefix itself (#1341).
+ */
+export function namespacedToolName(lexicon: string, name: string): string {
+  const prefix = `${lexicon}:`;
+  return name.startsWith(prefix) ? name : `${prefix}${name}`;
+}
+
+/**
+ * The URI a lexicon's MCP resource is registered under: `chant://<lexicon>/<path>`.
+ *
+ * Three authored forms reach here (#1341). The bare path is the intended one.
+ * `createCatalogResource` emits `<lexicon>:resource-catalog`, and
+ * `lexicon-authoring/lsp-mcp.mdx` taught `chant://lexicon/<lexicon>/<path>` —
+ * which azure followed, and which produced the unusable
+ * `chant://azure/chant://lexicon/azure/catalog`.
+ */
+export function namespacedResourceUri(lexicon: string, uri: string): string {
+  const base = `chant://${lexicon}/`;
+  if (uri.startsWith(base)) return uri;
+  for (const authored of [`chant://lexicon/${lexicon}/`, `${lexicon}:`]) {
+    if (uri.startsWith(authored)) return `${base}${uri.slice(authored.length)}`;
+  }
+  return `${base}${uri}`;
+}
+
 /**
  * MCP Server implementation
  */
@@ -52,15 +79,22 @@ export class McpServer {
   }
 
   /**
-   * Register tools contributed by a plugin, namespaced as `lexicon:toolName`
+   * Register tools contributed by a plugin, namespaced as `lexicon:toolName`.
+   *
+   * Namespacing is idempotent (#1341). Core is not the only place that applies
+   * a prefix: `createDiffTool` in ../../lexicon-plugin-helpers.ts already emits
+   * `${lexiconName}:diff`, and eleven lexicons write the prefix into the name by
+   * hand. Applying it unconditionally produced `gitlab:gitlab:diff` and
+   * `aws:aws:diff` in every `chant serve mcp` session, while every doc named the
+   * single-prefixed form. A tool declared either way now registers under exactly
+   * one namespace.
    */
   private registerPluginTools(plugin: LexiconPlugin): void {
     const tools = plugin.mcpTools?.() ?? [];
     for (const tool of tools) {
-      const namespacedName = `${plugin.name}:${tool.name}`;
       this.registerTool(
         {
-          name: namespacedName,
+          name: namespacedToolName(plugin.name, tool.name),
           description: tool.description,
           inputSchema: tool.inputSchema,
         },
@@ -70,12 +104,13 @@ export class McpServer {
   }
 
   /**
-   * Register resources contributed by a plugin, namespaced as `chant://lexicon/uri`
+   * Register resources contributed by a plugin, namespaced as
+   * `chant://lexicon/uri`, idempotently — see {@link registerPluginTools}.
    */
   private registerPluginResources(plugin: LexiconPlugin): void {
     const resources = plugin.mcpResources?.() ?? [];
     for (const resource of resources) {
-      const namespacedUri = `chant://${plugin.name}/${resource.uri}`;
+      const namespacedUri = namespacedResourceUri(plugin.name, resource.uri);
       this.pluginResources.set(namespacedUri, {
         definition: {
           uri: namespacedUri,

package/src/cli/param-flag-scope.test.ts

@@ -0,0 +1,69 @@
+import { describe, test, expect } from "vitest";
+import { readFileSync, readdirSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+/**
+ * `--param`/`--params-file` started as build-only flags and grew: `chant graph`
+ * gained them with #1359 (graph and build disagreed about the same source),
+ * `chant run --components` with #1108. The help text in `./main.ts` kept saying
+ * "(build)", so the CLI's own documentation told users the flag did nothing on
+ * the two commands that had just learned it.
+ *
+ * Asserting the property rather than the wording: every handler that actually
+ * reads `args.param` must be named in the flag's help annotation. A new handler
+ * honoring the flag fails this test until the help is updated with it.
+ */
+const here = dirname(fileURLToPath(import.meta.url));
+const handlersDir = join(here, "handlers");
+
+/** The command name a handler file implements — `handlers/graph.ts` backs `chant graph`. */
+function commandOf(file: string): string {
+  return file.replace(/\.ts$/, "");
+}
+
+function handlersReadingParamFlags(): string[] {
+  return readdirSync(handlersDir)
+    .filter((f) => f.endsWith(".ts") && !f.endsWith(".test.ts"))
+    .filter((f) => /\bargs\.param\b/.test(readFileSync(join(handlersDir, f), "utf-8")))
+    .map(commandOf)
+    .sort();
+}
+
+/**
+ * The help text for one flag: everything from its marker up to the next flag
+ * entry or the end of the options block, whichever comes first. Both bounds
+ * matter — the LAST flag in a block has no `--` after it, and without the
+ * blank-line bound its "block" would run to the end of the file and match
+ * every command name incidentally.
+ */
+function helpBlockFor(flag: string): string {
+  const source = readFileSync(join(here, "main.ts"), "utf-8");
+  const start = source.indexOf(`  ${flag}`);
+  expect(start, `${flag} is not documented in main.ts's help`).toBeGreaterThan(-1);
+  const rest = source.slice(start + flag.length);
+  const ends = [rest.search(/\n {2}--/), rest.search(/\n\s*\n/)].filter((i) => i !== -1);
+  expect(ends.length, `${flag}'s help block has no terminator`).toBeGreaterThan(0);
+  return rest.slice(0, Math.min(...ends));
+}
+
+describe("--param help annotation tracks the handlers that honor it", () => {
+  test("at least build, graph and run read the flag", () => {
+    // Guards the test itself: if the detection regex ever stops matching, the
+    // assertions below would pass vacuously against an empty set.
+    expect(handlersReadingParamFlags()).toEqual(expect.arrayContaining(["build", "graph", "run"]));
+  });
+
+  test.each(["--param <name=value>", "--params-file <path>"])(
+    "%s names every command that honors it",
+    (flag) => {
+      const block = helpBlockFor(flag);
+      for (const command of handlersReadingParamFlags()) {
+        expect(
+          block.includes(command),
+          `handlers/${command}.ts reads args.param, but ${flag}'s help does not mention "${command}"`,
+        ).toBe(true);
+      }
+    },
+  );
+});

package/src/cli/plugins.test.ts

@@ -1,5 +1,5 @@
 import { describe, test, expect } from "vitest";
-import { loadPlugin, loadPlugins } from "./plugins";
+import { loadPlugin, loadPlugins, resolveLexiconVersions } from "./plugins";
 import { isLexiconPlugin } from "../lexicon";
 
 describe("loadPlugin", () => {
@@ -29,3 +29,35 @@ describe("loadPlugins", () => {
     expect(plugins).toHaveLength(0);
   });
 });
+
+/**
+ * chant #1442 — the installed version of each lexicon package, read for the
+ * build digest.
+ */
+describe("resolveLexiconVersions", () => {
+  test("reads the real installed version of a workspace lexicon", () => {
+    const versions = resolveLexiconVersions(["k8s"]);
+    expect(versions.k8s).toMatch(/^\d+\.\d+\.\d+/);
+  });
+
+  test("resolves several lexicons in one call", () => {
+    const versions = resolveLexiconVersions(["k8s", "aws"]);
+    expect(Object.keys(versions).sort()).toEqual(["aws", "k8s"]);
+  });
+
+  test("omits a lexicon that is not installed rather than inventing a version", () => {
+    // "unknown" would compare unequal to itself across builds and report a
+    // version change on every diff.
+    expect(resolveLexiconVersions(["definitely-not-a-lexicon"])).toEqual({});
+  });
+
+  test("an unresolvable name does not prevent the resolvable ones", () => {
+    const versions = resolveLexiconVersions(["definitely-not-a-lexicon", "k8s"]);
+    expect(versions.k8s).toBeDefined();
+    expect(versions["definitely-not-a-lexicon"]).toBeUndefined();
+  });
+
+  test("no names yields an empty map", () => {
+    expect(resolveLexiconVersions([])).toEqual({});
+  });
+});

package/src/cli/plugins.ts

@@ -1,3 +1,6 @@
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+import { existsSync, readFileSync } from "node:fs";
 import { isLexiconPlugin, type LexiconPlugin } from "../lexicon";
 import { loadChantConfigUpward } from "../config";
 import { findInfraFiles, detectLexicons } from "../index";
@@ -40,6 +43,58 @@ export async function loadPlugin(lexiconName: string): Promise<LexiconPlugin> {
   throw new Error(`Package ${packageName} does not export a LexiconPlugin or Serializer`);
 }
 
+/**
+ * The installed version of each named lexicon package (chant #1442).
+ *
+ * A `LexiconPlugin` does not carry its own version — `LexiconManifest` does,
+ * but that is an artifact type describing generated output, not something the
+ * plugin object exposes. The version wanted here is a property of the
+ * *installed package*, so it is read from the package's own `package.json`.
+ *
+ * Resolved by walking up from the package's entry point rather than resolving
+ * `<pkg>/package.json` directly: lexicon packages declare an `exports` map
+ * that does not include `./package.json`, so the direct specifier is blocked
+ * by Node. `./manifest` (→ `dist/manifest.json`) is not used either — it is a
+ * `prepack` build artifact, absent in a monorepo dev tree, and its absence
+ * once read as four unrelated bugs (#1367).
+ *
+ * A lexicon whose version cannot be determined is omitted rather than
+ * recorded as `"unknown"`: a digest that says nothing is honest, one that
+ * says `unknown` compares unequal to itself across builds.
+ */
+export function resolveLexiconVersions(lexiconNames: readonly string[]): Record<string, string> {
+  const require_ = createRequire(import.meta.url);
+  const versions: Record<string, string> = {};
+
+  for (const name of lexiconNames) {
+    const packageName = `@intentius/chant-lexicon-${name}`;
+    try {
+      let dir = dirname(require_.resolve(packageName));
+      // Bounded walk — a resolved entry point is never deeply nested inside
+      // its own package, and an unbounded loop here would climb to `/`.
+      for (let depth = 0; depth < 10; depth++) {
+        const candidate = join(dir, "package.json");
+        if (existsSync(candidate)) {
+          const pkg = JSON.parse(readFileSync(candidate, "utf-8")) as { name?: string; version?: string };
+          // Only the lexicon's OWN package.json — a nested dependency's
+          // manifest would otherwise be read as the lexicon's version.
+          if (pkg.name === packageName && pkg.version) {
+            versions[name] = pkg.version;
+            break;
+          }
+        }
+        const parent = dirname(dir);
+        if (parent === dir) break;
+        dir = parent;
+      }
+    } catch {
+      // Not installed, or not resolvable from here — omit it.
+    }
+  }
+
+  return versions;
+}
+
 /**
  * Load plugins for all detected lexicon names.
  * Calls `init()` on each plugin if present.

package/src/codegen/registry.test.ts

@@ -0,0 +1,56 @@
+import { describe, test, expect } from "vitest";
+import { mkdtempSync, mkdirSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { loadLexiconRegistry, LexiconRegistryMissingError } from "./registry";
+
+const REGISTRY = { Bucket: { resourceType: "AWS::S3::Bucket", kind: "resource" } };
+
+function pkg(): string {
+  return mkdtempSync(join(tmpdir(), "chant-registry-"));
+}
+
+describe("loadLexiconRegistry (#1367)", () => {
+  test("reads the dev copy — src/generated, which is what a working checkout has", () => {
+    const dir = pkg();
+    mkdirSync(join(dir, "src", "generated"), { recursive: true });
+    writeFileSync(join(dir, "src", "generated", "lexicon-aws.json"), JSON.stringify(REGISTRY));
+    expect(loadLexiconRegistry(dir, "aws")).toEqual(REGISTRY);
+  });
+
+  test("falls back to dist/meta.json — what an installed package ships", () => {
+    const dir = pkg();
+    mkdirSync(join(dir, "dist"), { recursive: true });
+    writeFileSync(join(dir, "dist", "meta.json"), JSON.stringify(REGISTRY));
+    expect(loadLexiconRegistry(dir, "aws")).toEqual(REGISTRY);
+  });
+
+  test("prefers the dev copy when both exist", () => {
+    const dir = pkg();
+    mkdirSync(join(dir, "src", "generated"), { recursive: true });
+    mkdirSync(join(dir, "dist"), { recursive: true });
+    writeFileSync(join(dir, "src", "generated", "lexicon-aws.json"), JSON.stringify({ Dev: REGISTRY.Bucket }));
+    writeFileSync(join(dir, "dist", "meta.json"), JSON.stringify({ Dist: REGISTRY.Bucket }));
+    expect(Object.keys(loadLexiconRegistry(dir, "aws"))).toEqual(["Dev"]);
+  });
+
+  test("throws with the command to run, rather than a module-not-found or an empty map", () => {
+    // The whole point. An empty map reads downstream as a lexicon with no
+    // resource types, which is how azure's import came to emit
+    // `// Unknown resource type: Microsoft.…` and look like a coverage gap.
+    const dir = pkg();
+    expect(() => loadLexiconRegistry(dir, "azure")).toThrow(LexiconRegistryMissingError);
+    expect(() => loadLexiconRegistry(dir, "azure")).toThrow(/npm run --prefix lexicons\/azure prepack/);
+  });
+
+  test("names the lexicon that is missing, not a generic one", () => {
+    const dir = pkg();
+    try {
+      loadLexiconRegistry(dir, "gcp");
+      throw new Error("should have thrown");
+    } catch (err) {
+      expect((err as LexiconRegistryMissingError).lexicon).toBe("gcp");
+      expect((err as Error).message).toContain("lexicons/gcp");
+    }
+  });
+});