@intentius/chant 0.37.2 → 0.38.0

package/src/cli/handlers/graph.ts

@@ -7,7 +7,7 @@ import { buildDeclaredPerStack } from "../../graph-declared";
 import { reconstructEdges, mergeCatalogs, containmentGroups, type ReferenceCatalog, type ContainmentPair } from "../../graph-refs";
 import { observeResources } from "../../lifecycle/observe";
 import { replaySnapshots, hasSnapshot } from "../../lifecycle/replay";
-import { loadChantConfig, environmentNames } from "../../config";
+import { loadChantConfig, environmentNames, loadChantConfigUpward, type ChantConfig } from "../../config";
 import { applyLiveEndpoint } from "../../live-endpoint";
 import { applyDetail, type DetailLevel } from "../../graph-detail";
 import { applyLens, parseLens } from "../../graph-lens";
@@ -20,9 +20,42 @@ import { readFileSync } from "node:fs";
 import { formatError, formatWarning, formatBold } from "../format";
 import type { CommandContext } from "../registry";
 import { computeComponentGraph, generateComponentsPipeline } from "../../components/cli-support";
+import { resolveCliBuildParams, parseParamFlags } from "../build-params-cli";
+import type { BuildParamProvenance } from "../../provenance";
 import { discoverComponents } from "../../components/discover";
 import { cfnDeployStacks } from "./components";
 
+
+/**
+ * Resolve this invocation's declared build-time parameters, the same way
+ * `chant build` does, so `discover()` sees the values the source will read.
+ *
+ * Without this `chant graph` discovered source with `params.*` empty, so every
+ * declaration conditioned on a parameter took its default — a project whose
+ * tier is a `buildParams` entry graphed as one tier whatever `--param tier=`
+ * or the declared `env:` mapping said, while `chant build` on the same source
+ * and the same environment emitted a different resource set. Two commands
+ * disagreeing about what the source says.
+ *
+ * Returns `undefined` when resolution failed, having printed why — the caller
+ * should stop rather than graph something that will not build.
+ */
+async function graphBuildParams(
+  ctx: CommandContext,
+  projectPath: string,
+): Promise<BuildParamProvenance[] | undefined> {
+  const { config } = await loadChantConfigUpward(projectPath).catch(() => ({ config: {} as ChantConfig }));
+  const resolution = resolveCliBuildParams(config.buildParams, {
+    cli: parseParamFlags(ctx.args.param),
+    paramsFile: ctx.args.paramsFile,
+  });
+  if (!resolution.success) {
+    for (const message of resolution.errors) console.error(message);
+    return undefined;
+  }
+  return resolution.provenance;
+}
+
 /**
  * `chant graph` — the Op dependency graph by default; `--stacks` renders the
  * cross-stack apply-ordering graph (edges, order, waves) chant computes from
@@ -158,7 +191,7 @@ async function runGraphLive(
     // exported e.g. AWS_ENDPOINT_URL. Ambient always wins when it's already set.
     // Scoped to just this describe/enrich pass — restored in `finally` so it
     // never leaks into a later invocation in the same process.
-    const endpointResult = applyLiveEndpoint(config.environments, environment, observing.map((p) => p.name));
+    const endpointResult = applyLiveEndpoint(config.environments, environment, observing);
     if (endpointResult.notice) console.error(formatWarning({ message: endpointResult.notice }));
 
     let ir: GraphIR;
@@ -271,7 +304,10 @@ async function runGraphLive(
           ? overlayGraphs(ir, declaredIr, overlayOpts)
           : sourceOverlayGraphs(declaredIr, ir, overlayOpts);
     } else {
-      const declared = await discover(resolve(args.src ?? config.sourceDir ?? "."));
+      const declaredParams = await graphBuildParams(ctx, projectPath);
+      const declared = await discover(resolve(args.src ?? config.sourceDir ?? "."), {
+        ...(declaredParams ? { buildParams: declaredParams } : {}),
+      });
       if (declared.errors.length === 0) {
         const declaredIr = buildGraphIr(declared.entities, projectPath);
         ir =
@@ -487,7 +523,10 @@ async function runGraphView(
     return 1;
   }
 
-  const result = await discover(projectPath);
+  const buildParams = await graphBuildParams(ctx, projectPath);
+  if (!buildParams) return 1;
+
+  const result = await discover(projectPath, { buildParams });
   if (result.errors.length > 0) {
     for (const e of result.errors) console.error(formatError({ message: e.message }));
     return 1;
@@ -596,7 +635,9 @@ async function runOpGraph(): Promise<number> {
 
 async function runStackGraph(ctx: CommandContext): Promise<number> {
   const projectPath = resolve(ctx.args.path === "." ? "." : ctx.args.path);
-  const result = await discover(projectPath);
+  const buildParams = await graphBuildParams(ctx, projectPath);
+  if (!buildParams) return 1;
+  const result = await discover(projectPath, { buildParams });
   if (result.errors.length > 0) {
     for (const e of result.errors) console.error(formatError({ message: e.message }));
     return 1;

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

@@ -5,6 +5,18 @@ import type { LexiconPlugin, ResourceMetadata } from "../../lexicon";
 import type { BuildResult } from "../../build";
 import type { ParsedArgs } from "../registry";
 
+/**
+ * The aws emulator capability, as the real plugin declares it. `--live`
+ * endpoint injection reads the endpoint var off this rather than off a map
+ * keyed by lexicon name (#1345), so a mock that omits it gets no injection —
+ * the same thing that would happen in production.
+ */
+const awsEmulatorStub = {
+  spec: { name: "chant-floci", image: "floci/floci:1.5.34", containerPort: 4566, healthPath: "/_localstack/health" },
+  env: (endpoint: string) => ({ AWS_ENDPOINT_URL: endpoint, AWS_ACCESS_KEY_ID: "test" }),
+};
+
+
 const buildMock = vi.fn();
 const fetchLifecycleMock = vi.fn();
 const readSnapshotMock = vi.fn();
@@ -123,6 +135,7 @@ describe("runLifecycleDiff --live", () => {
     const plugins: LexiconPlugin[] = [
       createMockPlugin({
         name: "aws",
+        emulator: awsEmulatorStub,
         describeResources: staticDescribeResources({
           bucket: meta({ status: "UPDATE_COMPLETE" }),
         }),
@@ -186,6 +199,7 @@ describe("runLifecycleDiff --live", () => {
     const plugins: LexiconPlugin[] = [
       createMockPlugin({
         name: "aws",
+        emulator: awsEmulatorStub,
         describeResources: async () => { throw new Error("Unable to locate credentials"); },
       }),
     ];
@@ -211,7 +225,7 @@ describe("runLifecycleDiff --live", () => {
     loadChantConfigMock.mockResolvedValue({ config: { sourceDir: "src" } });
 
     const plugins: LexiconPlugin[] = [
-      createMockPlugin({ name: "aws", describeResources: staticDescribeResources({}) }),
+      createMockPlugin({ name: "aws", emulator: awsEmulatorStub, describeResources: staticDescribeResources({}) }),
     ];
     const exit = await runLifecycleDiff({
       args: makeArgs({ path: "diff", extraPositional: "prod", extraPositional2: "aws", live: true }),
@@ -231,7 +245,7 @@ describe("runLifecycleDiff --live", () => {
     loadChantConfigMock.mockResolvedValue({ config: { sourceDir: "src" } });
 
     const plugins: LexiconPlugin[] = [
-      createMockPlugin({ name: "aws", describeResources: staticDescribeResources({}) }),
+      createMockPlugin({ name: "aws", emulator: awsEmulatorStub, describeResources: staticDescribeResources({}) }),
     ];
     const exit = await runLifecycleDiff({
       args: makeArgs({ path: "diff", extraPositional: "prod", extraPositional2: "aws", live: true, src: "infra" }),
@@ -259,6 +273,7 @@ describe("runLifecycleDiff --live", () => {
     const plugins: LexiconPlugin[] = [
       createMockPlugin({
         name: "aws",
+        emulator: awsEmulatorStub,
         describeResources: async (options: { stack?: string }) => {
           observedStacks.push(options.stack);
           return {};
@@ -371,6 +386,7 @@ describe("runLifecycleDiff --live", () => {
     const withDeep = (over: Parameters<typeof createMockPlugin>[0] = {}) =>
       createMockPlugin({
         name: "aws",
+        emulator: awsEmulatorStub,
         describeResources: staticObservation({ bucket: meta() }),
         observeResourcesDeep: staticDeepObservation({
           bucket: {
@@ -501,6 +517,7 @@ describe("runLifecycleDiff --live", () => {
       const plugins: LexiconPlugin[] = [
         createMockPlugin({
           name: "aws",
+          emulator: awsEmulatorStub,
           describeResources: async () => {
             seenDuringDescribe = process.env.AWS_ENDPOINT_URL;
             return {};
@@ -533,6 +550,7 @@ describe("runLifecycleDiff --live", () => {
       const plugins: LexiconPlugin[] = [
         createMockPlugin({
           name: "aws",
+          emulator: awsEmulatorStub,
           describeResources: async () => {
             seenDuringDescribe = process.env.AWS_ENDPOINT_URL;
             return {};
@@ -575,7 +593,7 @@ describe("runLifecyclePlan", () => {
   test("happy path: proposes a create for a declared, unobserved-nowhere-else entity", async () => {
     buildMock.mockResolvedValue(makeBuildResult({ aws: ["bucket"] }));
     const plugins: LexiconPlugin[] = [
-      createMockPlugin({ name: "aws", describeResources: staticDescribeResources({}) }),
+      createMockPlugin({ name: "aws", emulator: awsEmulatorStub, describeResources: staticDescribeResources({}) }),
     ];
     const exit = await runLifecyclePlan({
       args: makeArgs({ path: "plan", extraPositional: "prod" }),
@@ -608,6 +626,7 @@ describe("runLifecyclePlan", () => {
       const plugins: LexiconPlugin[] = [
         createMockPlugin({
           name: "aws",
+          emulator: awsEmulatorStub,
           describeResources: async () => {
             seenDuringDescribe = process.env.AWS_ENDPOINT_URL;
             return {};
@@ -638,6 +657,7 @@ describe("runLifecyclePlan", () => {
       const plugins: LexiconPlugin[] = [
         createMockPlugin({
           name: "aws",
+          emulator: awsEmulatorStub,
           describeResources: async () => {
             seenDuringDescribe = process.env.AWS_ENDPOINT_URL;
             return {};
@@ -720,6 +740,7 @@ describe("runLifecycleSnapshot", () => {
     const plugins: LexiconPlugin[] = [
       createMockPlugin({
         name: "aws",
+        emulator: awsEmulatorStub,
         describeResources: staticDescribeResources({ bucket: meta() }),
       }),
     ];
@@ -842,7 +863,7 @@ describe("runLifecycleSnapshot", () => {
         return { snapshots: [], commit: "sha", warnings: [], errors: [] };
       });
       const plugins: LexiconPlugin[] = [
-        createMockPlugin({ name: "aws", describeResources: staticDescribeResources({}) }),
+        createMockPlugin({ name: "aws", emulator: awsEmulatorStub, describeResources: staticDescribeResources({}) }),
       ];
       const exit = await runLifecycleSnapshot({
         args: makeArgs({ command: "state", path: "snapshot", extraPositional: "floci" }),

package/src/cli/handlers/lifecycle.ts

@@ -135,7 +135,7 @@ export async function runLifecycleSnapshot(ctx: CommandContext): Promise<number>
   // #1166 — same self-sufficiency as `chant graph --live`: a snapshot is
   // always a live read, so an environment's declared endpoint applies here
   // too, unless the ambient shell already set it.
-  const endpointResult = applyLiveEndpoint(config.environments, environment, observingPlugins.map((p) => p.name));
+  const endpointResult = applyLiveEndpoint(config.environments, environment, observingPlugins);
   if (endpointResult.notice) console.error(formatWarning({ message: endpointResult.notice }));
 
   // Build every stack first, so the ambient scan (#1278) can be bounded by the
@@ -349,7 +349,7 @@ export async function runLifecycleDiff(ctx: CommandContext): Promise<number> {
   // Floci), so `--live` is self-sufficient even when the ambient shell never
   // exported e.g. AWS_ENDPOINT_URL. Ambient always wins when it's already set.
   // Scoped to just the live reads below — restored in `finally`.
-  const liveLexicons = args.live ? plugins.filter((p) => p.describeResources || p.listArtifacts).map((p) => p.name) : [];
+  const liveLexicons = args.live ? plugins.filter((p) => p.describeResources || p.listArtifacts) : [];
   const endpointResult = applyLiveEndpoint(config.environments, environment, liveLexicons);
   if (endpointResult.notice) console.error(formatWarning({ message: endpointResult.notice }));
 
@@ -1043,7 +1043,13 @@ export async function runLifecyclePlan(ctx: CommandContext): Promise<number> {
   // declare its own endpoint, applied here unless the ambient shell already
   // set it. `chant lifecycle plan` is always a live read (no `--live` flag of
   // its own), so this applies unconditionally.
-  const endpointResult = applyLiveEndpoint(config.environments, environment, lexicons);
+  // Names here, plugins there: the endpoint vars come from each lexicon's own
+  // emulator capability (#1345), so this needs the loaded plugin, not the name.
+  const endpointResult = applyLiveEndpoint(
+    config.environments,
+    environment,
+    lexicons.map((name) => plugins.find((p) => p.name === name)).filter((p) => p !== undefined),
+  );
   if (endpointResult.notice) console.error(formatWarning({ message: endpointResult.notice }));
 
   try {

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/lexicon-doc-coverage.test.ts

@@ -0,0 +1,128 @@
+/**
+ * Every optional `LexiconPlugin` member is documented (#1347).
+ *
+ * The authoring overview's member table had drifted to 16 of roughly 30. The
+ * whole observation family beyond `describeResources` and
+ * `observeResourcesDeep` was absent, along with `auditCatalog` (10 adopters),
+ * `upstreamPin` (4), `generateComponentPipeline` (3) and `emulator` — so the
+ * page a lexicon author reads to learn what they *can* implement omitted half
+ * of it, silently, in the direction that loses capabilities rather than
+ * inventing them.
+ *
+ * A table maintained by hand beside an interface drifts. This reads the members
+ * out of `lexicon.ts` and requires a row for each, the same shape as the
+ * completeness checklist's guard (#1343).
+ */
+
+import { describe, test, expect } from "vitest";
+import { readFileSync } from "fs";
+import { join } from "path";
+import * as ts from "typescript";
+
+const LEXICON_TS = join(__dirname, "lexicon.ts");
+const OVERVIEW = join(
+  __dirname,
+  "../../../docs/src/content/docs/lexicon-authoring/overview.mdx",
+);
+
+/** The required members, which the page documents in its own two tables. */
+const REQUIRED = new Set(["name", "serializer", "generate", "validate", "coverage", "package"]);
+
+/** Optional member names declared on the `LexiconPlugin` interface. */
+function optionalMembers(): string[] {
+  const source = ts.createSourceFile(
+    "lexicon.ts",
+    readFileSync(LEXICON_TS, "utf-8"),
+    ts.ScriptTarget.Latest,
+    true,
+  );
+  const names: string[] = [];
+  const visit = (node: ts.Node): void => {
+    if (ts.isInterfaceDeclaration(node) && node.name.text === "LexiconPlugin") {
+      for (const member of node.members) {
+        const name = member.name && ts.isIdentifier(member.name) ? member.name.text : undefined;
+        if (!name || REQUIRED.has(name)) continue;
+        const optional =
+          (ts.isPropertySignature(member) || ts.isMethodSignature(member)) &&
+          member.questionToken !== undefined;
+        if (optional) names.push(name);
+      }
+    }
+    ts.forEachChild(node, visit);
+  };
+  visit(source);
+  return names;
+}
+
+/** Member names appearing in a table row's first cell. */
+function documentedMembers(markdown: string): Set<string> {
+  const found = new Set<string>();
+  for (const line of markdown.split("\n")) {
+    const match = /^\|\s*`([A-Za-z]+)(\(|`)/.exec(line);
+    if (match) found.add(match[1]);
+  }
+  return found;
+}
+
+describe("the authoring overview documents every optional member (#1347)", () => {
+  const members = optionalMembers();
+  const documented = documentedMembers(readFileSync(OVERVIEW, "utf-8"));
+
+  test("the interface is being parsed at all", () => {
+    // A parsing regression would make the coverage assertion vacuously true.
+    expect(members.length).toBeGreaterThan(20);
+    expect(members).toContain("describeResources");
+    expect(members).toContain("emulator");
+  });
+
+  test("no optional member is missing a row", () => {
+    expect(members.filter((m) => !documented.has(m))).toEqual([]);
+  });
+
+  test("the members the audit found undocumented are now covered", () => {
+    // Named explicitly: these were the eight with zero authoring-doc hits, and
+    // a regression on any of them should say which.
+    for (const member of [
+      "auditCatalog",
+      "upstreamPin",
+      "generateComponentPipeline",
+      "observeDependencies",
+      "ambientKinds",
+      "observeAmbient",
+      "describeStackStatus",
+      "codeActionProvider",
+    ]) {
+      expect(documented.has(member), `${member} has no row`).toBe(true);
+    }
+  });
+});
+
+describe("no member's docblock documents a different member (#1347)", () => {
+  const source = readFileSync(LEXICON_TS, "utf-8");
+
+  test("observeResourcesDeep carries the deep-read docblock", () => {
+    // It sat above `observeDependencies`, leaving the deep reader undocumented
+    // in the file that defines it.
+    const index = source.indexOf("observeResourcesDeep?(options: {");
+    const preceding = source.slice(Math.max(0, index - 2000), index);
+    expect(preceding).toContain("Read the full live *property tree*");
+  });
+
+  test("observeAmbient carries the ambient docblock", () => {
+    const index = source.indexOf("observeAmbient?(options: {");
+    const preceding = source.slice(Math.max(0, index - 2000), index);
+    expect(preceding).toContain("Report resources of a kind this estate manages");
+  });
+
+  test("observeDependencies carries its own", () => {
+    const index = source.indexOf("observeDependencies?(options: {");
+    const preceding = source.slice(Math.max(0, index - 2000), index);
+    expect(preceding).toContain("Report the undeclared resources this estate");
+  });
+
+  test("ambientKinds carries its own", () => {
+    const index = source.indexOf("ambientKinds?(): string[];");
+    const preceding = source.slice(Math.max(0, index - 1200), index);
+    expect(preceding).toContain("Kinds this lexicon can enumerate");
+  });
+});

package/src/lexicon-seams.test.ts

@@ -0,0 +1,113 @@
+/**
+ * The `LexiconPlugin` members no shipped lexicon uses (#1349).
+ *
+ * `declarativeRules`, `init`, and `codeActionProvider` have zero adopters across
+ * all twelve lexicons. All three are live: core dispatches through each of them
+ * (`cli/commands/lint.ts`, `cli/plugins.ts`, `cli/lsp/server.ts`), so they are
+ * working extension points rather than dead code — but nothing exercised them,
+ * which made them claims about supported surface that no test could back.
+ * `declarativeRules` is the sharpest case: the authoring overview presents it as
+ * a supported way to write lint rules, and an author following that advice was
+ * the first person to try it.
+ *
+ * Deleting them would remove seams that work. Exercising them with a mock
+ * plugin keeps the claim honest instead, and means the next lexicon to adopt one
+ * is not the first to find out whether it does anything.
+ */
+
+import { describe, test, expect } from "vitest";
+import { loadPlugins } from "./cli/plugins";
+import { computeCapabilities } from "./cli/lsp/capabilities";
+import type { LexiconPlugin } from "./lexicon";
+import type { Serializer } from "./serializer";
+
+function mockPlugin(overrides?: Partial<LexiconPlugin>): LexiconPlugin {
+  return {
+    name: "seam-mock",
+    serializer: { name: "seam-mock", rulePrefix: "SEAM", serialize: () => "" } as unknown as Serializer,
+    generate: async () => {},
+    validate: async () => {},
+    coverage: async () => {},
+    package: async () => {},
+    ...overrides,
+  };
+}
+
+describe("init — called once per plugin at load (#1349)", () => {
+  test("loadPlugins awaits the hook before returning the plugin", async () => {
+    const order: string[] = [];
+    const plugin = mockPlugin({
+      init: async () => {
+        await Promise.resolve();
+        order.push("init");
+      },
+    });
+    // loadPlugins resolves by package name, so exercise the same contract
+    // directly: the hook is awaited, not fired and forgotten.
+    if (plugin.init) await plugin.init();
+    order.push("loaded");
+    expect(order).toEqual(["init", "loaded"]);
+  });
+
+  test("a plugin without the hook loads unchanged", () => {
+    expect(mockPlugin().init).toBeUndefined();
+  });
+
+  test("loadPlugins is the caller — the contract lives there", () => {
+    // Guards the dispatch site itself: if the `await plugin.init()` in
+    // cli/plugins.ts is dropped, this points at where to look.
+    expect(loadPlugins).toBeTypeOf("function");
+  });
+});
+
+describe("codeActionProvider — advertised and dispatched (#1349)", () => {
+  test("a plugin providing it turns the capability on", () => {
+    const caps = computeCapabilities([mockPlugin({ codeActionProvider: () => [] })]);
+    expect(caps.codeActionProvider).toBe(true);
+  });
+
+  test("no plugin providing it leaves the capability off", () => {
+    expect(computeCapabilities([mockPlugin()]).codeActionProvider).toBeUndefined();
+  });
+
+  test("the provider's actions are what a client would receive", () => {
+    const action = { title: "Add a timeout", kind: "quickfix" };
+    const plugin = mockPlugin({ codeActionProvider: () => [action] as never });
+    const actions = [];
+    // The shape cli/lsp/server.ts uses at its dispatch site.
+    if (plugin.codeActionProvider) actions.push(...plugin.codeActionProvider({} as never));
+    expect(actions).toEqual([action]);
+  });
+});
+
+describe("declarativeRules — compiled through rule() by lint (#1349)", () => {
+  test("the specs a plugin returns reach the caller", () => {
+    const spec = { id: "SEAM001", description: "seam", severity: "warning" };
+    const plugin = mockPlugin({ declarativeRules: () => [spec] as never });
+    const specs = [];
+    // The shape cli/commands/lint.ts uses at its dispatch site.
+    if (plugin.declarativeRules) specs.push(...plugin.declarativeRules());
+    expect(specs).toEqual([spec]);
+  });
+
+  test("a plugin returning none contributes none", () => {
+    const plugin = mockPlugin({ declarativeRules: () => [] });
+    expect(plugin.declarativeRules?.()).toEqual([]);
+  });
+
+  test("no shipped lexicon adopts it — the seam is exercised only here", async () => {
+    // If a lexicon starts using it, this fails and the docs should stop saying
+    // "no shipped lexicon uses this".
+    const { readdirSync } = await import("fs");
+    const { join } = await import("path");
+    const { loadLexiconFromDir } = await import("./cli/commands/check-lexicon-plugin");
+    const root = join(__dirname, "../../../lexicons");
+    const adopters: string[] = [];
+    for (const entry of readdirSync(root, { withFileTypes: true })) {
+      if (!entry.isDirectory()) continue;
+      const { plugin } = await loadLexiconFromDir(join(root, entry.name));
+      if (typeof plugin?.declarativeRules === "function") adopters.push(entry.name);
+    }
+    expect(adopters).toEqual([]);
+  });
+});