@intentius/chant 0.37.0 → 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/codegen/docs-rule-scanning.ts

@@ -109,17 +109,26 @@ function extractDescriptionFromComment(
   return ruleId;
 }
 
+function plural(n: number, noun: string): string {
+  return `${n} ${noun}${n === 1 ? "" : "s"}`;
+}
+
 export function generateRules(config: DocsConfig, rules: RuleMeta[]): string {
   const lintRules = rules.filter((r) => r.type === "lint");
   const postSynthRules = rules.filter((r) => r.type === "post-synth");
 
   const lines: string[] = [
     "---",
-    `title: "Lint Rules"`,
-    `description: "Lint rules and post-synth checks provided by the ${config.displayName} lexicon"`,
+    // "All Rules", not "Lint Rules": most lexicons also ship a hand-written
+    // page under the latter title that covers a selected subset, and two pages
+    // with the same title reads as a duplicate rather than a complete table.
+    `title: "All Rules"`,
+    `description: "Every lint rule and post-synth check provided by the ${config.displayName} lexicon"`,
     "---",
     "",
-    `The ${config.displayName} lexicon provides **${rules.length}** rules: ${lintRules.length} lint rules and ${postSynthRules.length} post-synth checks.`,
+    `The ${config.displayName} lexicon provides **${rules.length}** rules: ` +
+      `${plural(lintRules.length, "lint rule")} and ` +
+      `${plural(postSynthRules.length, "post-synth check")}.`,
     "",
   ];
 

package/src/codegen/docs-sections.ts

@@ -64,9 +64,11 @@ export function generateOverview(
       `- [Pseudo-Parameters](./pseudo-parameters) — ${Object.keys(manifest.pseudoParameters).length} pseudo-parameters`,
     );
   }
-  const overviewExtraSlugs = new Set((config.extraPages ?? []).map((p) => p.slug));
-  if (!suppress.has("rules") && !overviewExtraSlugs.has("lint-rules") && rules.length > 0) {
-    lines.push(`- [Lint Rules](./rules) — ${rules.length} rules`);
+  // Same reasoning as the sidebar's rules entry: link the complete table on
+  // every lexicon, under the label the sidebar uses, whether or not a prose
+  // `lint-rules` page also exists.
+  if (!suppress.has("rules") && rules.length > 0) {
+    lines.push(`- [All Rules](./rules) — ${rules.length} rules`);
   }
   if (!suppress.has("serialization")) {
     lines.push(`- [Serialization](./serialization) — output format details`);

package/src/codegen/docs-sidebar.ts

@@ -39,8 +39,14 @@ export function buildSidebar(
     items.push({ label: "Pseudo-Parameters", slug: "pseudo-parameters" });
   }
 
-  if (!suppress.has("rules") && !extraSlugs.has("rules") && !extraSlugs.has("lint-rules") && result.pages.has("rules.mdx")) {
-    items.push({ label: "Lint Rules", slug: "rules" });
+  // Every lexicon links its generated rules table, whether or not it also
+  // ships a prose `lint-rules` page. Skipping it when one existed was how gcp
+  // ended up emitting a page nothing pointed at (#1312), and it left readers
+  // with no complete list on the lexicons whose prose covers only part of the
+  // set — aws documented 26 of 50 that way. The label distinguishes the
+  // generated table from a prose page rather than competing with it.
+  if (!suppress.has("rules") && !extraSlugs.has("rules") && result.pages.has("rules.mdx")) {
+    items.push({ label: "All Rules", slug: "rules" });
   }
 
   if (!suppress.has("serialization") && !extraSlugs.has("serialization") && result.pages.has("serialization.mdx")) {

package/src/codegen/docs.ts

@@ -177,6 +177,25 @@ function withGeneratedMarker(config: DocsConfig, content: string): string {
   return `${marker}\n\n${content}`;
 }
 
+/**
+ * Render the complete rules table for a lexicon that has no {@link docsPipeline}
+ * site of its own.
+ *
+ * The docker lexicon hand-authors its docs, which left its rule table the only
+ * one in the repo that could drift from source without anything noticing
+ * (#1312). This is the one page worth generating even when the rest of a site
+ * is hand-written; the caller writes the result to `rules.mdx` and links it.
+ * Returns null when the lexicon declares no rules.
+ */
+export function generateRulesPage(
+  config: DocsConfig,
+  srcDir: string,
+): string | null {
+  const rules = scanRules(srcDir);
+  if (rules.length === 0) return null;
+  return withGeneratedMarker(config, generateRules(config, rules));
+}
+
 /**
  * Marks a page as pipeline output. Used both to warn readers off editing the
  * file and, in {@link writeDocsSite}, to tell a page this pipeline owns from a

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");
+  });
+});