@intentius/chant 0.49.0 → 0.51.0

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

@@ -47,7 +47,8 @@ describe("McpServer", () => {
 
       expect(response.error).toBeUndefined();
       const result = response.result as Record<string, unknown>;
-      expect(result.protocolVersion).toBe("2024-11-05");
+      // No requested version → negotiates to the latest supported revision (#1194).
+      expect(result.protocolVersion).toBe("2026-07-28");
       expect(result.capabilities).toBeDefined();
       expect((result.serverInfo as Record<string, unknown>).name).toBe("chant");
       expect((result.serverInfo as Record<string, unknown>).version).toBe("0.1.0");
@@ -60,11 +61,273 @@ describe("McpServer", () => {
         method: "initialize",
         params: {},
       });
-      const result = response.result as Record<string, unknown>;
+      const result = response!.result as Record<string, unknown>;
       const caps = result.capabilities as Record<string, unknown>;
       expect(caps.tools).toBeDefined();
       expect(caps.resources).toBeDefined();
     });
+
+    // -----------------------------------------------------------------------
+    // Dual-revision negotiation (#1194)
+    // -----------------------------------------------------------------------
+
+    test("a 2024-11-05 client requesting its own version gets it back unchanged", async () => {
+      const response = await server.handleRequest({
+        jsonrpc: "2.0",
+        id: 1,
+        method: "initialize",
+        params: { protocolVersion: "2024-11-05", clientInfo: { name: "old-client", version: "1.0" } },
+      });
+      expect(response!.error).toBeUndefined();
+      const result = response!.result as Record<string, unknown>;
+      expect(result.protocolVersion).toBe("2024-11-05");
+    });
+
+    test("a 2026-07-28 client requesting its version gets the latest revision", async () => {
+      const response = await server.handleRequest({
+        jsonrpc: "2.0",
+        id: 1,
+        method: "initialize",
+        params: { _meta: { protocolVersion: "2026-07-28" } },
+      });
+      expect(response!.error).toBeUndefined();
+      const result = response!.result as Record<string, unknown>;
+      expect(result.protocolVersion).toBe("2026-07-28");
+    });
+
+    test("an unrecognized requested version falls back to the latest supported", async () => {
+      const response = await server.handleRequest({
+        jsonrpc: "2.0",
+        id: 1,
+        method: "initialize",
+        params: { protocolVersion: "1999-01-01" },
+      });
+      const result = response!.result as Record<string, unknown>;
+      expect(result.protocolVersion).toBe("2026-07-28");
+    });
+
+    test("no requested version at all defaults to the latest supported", async () => {
+      const response = await server.handleRequest({
+        jsonrpc: "2.0",
+        id: 1,
+        method: "initialize",
+        params: {},
+      });
+      const result = response!.result as Record<string, unknown>;
+      expect(result.protocolVersion).toBe("2026-07-28");
+    });
+  });
+
+  // -----------------------------------------------------------------------
+  // _meta parsing (#1194)
+  // -----------------------------------------------------------------------
+
+  describe("_meta parsing", () => {
+    test("reads requested protocol version from _meta on initialize", async () => {
+      const response = await server.handleRequest({
+        jsonrpc: "2.0",
+        id: 1,
+        method: "initialize",
+        params: { _meta: { protocolVersion: "2024-11-05" } },
+      });
+      const result = response!.result as Record<string, unknown>;
+      expect(result.protocolVersion).toBe("2024-11-05");
+    });
+
+    test("_meta protocolVersion takes precedence over a legacy top-level one", async () => {
+      const response = await server.handleRequest({
+        jsonrpc: "2.0",
+        id: 1,
+        method: "initialize",
+        params: { protocolVersion: "2024-11-05", _meta: { protocolVersion: "2026-07-28" } },
+      });
+      const result = response!.result as Record<string, unknown>;
+      expect(result.protocolVersion).toBe("2026-07-28");
+    });
+
+    test("client identity in _meta does not interfere with tool dispatch", async () => {
+      const response = await server.handleRequest({
+        jsonrpc: "2.0",
+        id: 1,
+        method: "tools/call",
+        params: {
+          name: "search",
+          arguments: { query: "bucket" },
+          _meta: {
+            protocolVersion: "2026-07-28",
+            "io.modelcontextprotocol/clientInfo": { name: "some-agent", version: "3.0" },
+          },
+        },
+      });
+      expect(response!.error).toBeUndefined();
+      const result = response!.result as { content: Array<{ text: string }>; isError?: boolean };
+      expect(result.isError).toBeUndefined();
+      const parsed = JSON.parse(result.content[0].text);
+      expect(parsed.query).toBe("bucket");
+    });
+
+    test("a request with no _meta and no legacy fields is unaffected", async () => {
+      const response = await server.handleRequest({
+        jsonrpc: "2.0",
+        id: 1,
+        method: "tools/list",
+        params: {},
+      });
+      expect(response!.error).toBeUndefined();
+    });
+  });
+
+  // -----------------------------------------------------------------------
+  // Notification silence (#1194)
+  // -----------------------------------------------------------------------
+
+  describe("notifications", () => {
+    test("a message with no id gets no response", async () => {
+      const response = await server.handleRequest({
+        jsonrpc: "2.0",
+        method: "notifications/initialized",
+        params: {},
+      });
+      expect(response).toBeNull();
+    });
+
+    test("an id-less message is not routed through dispatch as Unknown method", async () => {
+      // notifications/initialized isn't a dispatch case; silence must come
+      // from the id check, not from swallowing a dispatch error.
+      const response = await server.handleRequest({
+        jsonrpc: "2.0",
+        method: "notifications/anything",
+      });
+      expect(response).toBeNull();
+    });
+
+    test("a message with id 0 (falsy but present) still gets a response", async () => {
+      const response = await server.handleRequest({
+        jsonrpc: "2.0",
+        id: 0,
+        method: "tools/list",
+      });
+      expect(response).not.toBeNull();
+      expect(response!.id).toBe(0);
+    });
+  });
+
+  // -----------------------------------------------------------------------
+  // server/discover (#1194)
+  // -----------------------------------------------------------------------
+
+  describe("server/discover", () => {
+    test("a 2026-07-28 client can discover capabilities without calling initialize", async () => {
+      const response = await server.handleRequest({
+        jsonrpc: "2.0",
+        id: 1,
+        method: "server/discover",
+        params: { _meta: { protocolVersion: "2026-07-28" } },
+      });
+      expect(response!.error).toBeUndefined();
+      const result = response!.result as Record<string, unknown>;
+      expect(result.protocolVersion).toBe("2026-07-28");
+      expect(result.serverInfo).toBeDefined();
+      expect(result.capabilities).toBeDefined();
+      expect(Array.isArray(result.tools)).toBe(true);
+      expect(Array.isArray(result.resources)).toBe(true);
+    });
+
+    test("discover's tools list matches tools/list", async () => {
+      const discover = await server.handleRequest({ jsonrpc: "2.0", id: 1, method: "server/discover", params: {} });
+      const list = await server.handleRequest({ jsonrpc: "2.0", id: 2, method: "tools/list" });
+      const discoverNames = (discover!.result as { tools: Array<{ name: string }> }).tools.map((t) => t.name).sort();
+      const listNames = (list!.result as { tools: Array<{ name: string }> }).tools.map((t) => t.name).sort();
+      expect(discoverNames).toEqual(listNames);
+    });
+
+    test("discover's resources list matches resources/list, including plugin contributions", async () => {
+      const plugin = createMockPlugin({
+        name: "test-lex",
+        mcpResources: () => [
+          {
+            uri: "catalog",
+            name: "Test Catalog",
+            description: "Test resource catalog",
+            mimeType: "application/json",
+            handler: async () => "[]",
+          },
+        ],
+      });
+      const s = new McpServer([plugin]);
+      const discover = await s.handleRequest({ jsonrpc: "2.0", id: 1, method: "server/discover", params: {} });
+      const list = await s.handleRequest({ jsonrpc: "2.0", id: 2, method: "resources/list" });
+      const discoverUris = (discover!.result as { resources: Array<{ uri: string }> }).resources.map((r) => r.uri).sort();
+      const listUris = (list!.result as { resources: Array<{ uri: string }> }).resources.map((r) => r.uri).sort();
+      expect(discoverUris).toEqual(listUris);
+      expect(discoverUris).toContain("chant://test-lex/catalog");
+    });
+
+    test("negotiates protocol version the same way as initialize", async () => {
+      const response = await server.handleRequest({
+        jsonrpc: "2.0",
+        id: 1,
+        method: "server/discover",
+        params: { protocolVersion: "2024-11-05" },
+      });
+      const result = response!.result as Record<string, unknown>;
+      expect(result.protocolVersion).toBe("2024-11-05");
+    });
+  });
+
+  // -----------------------------------------------------------------------
+  // Structured tool output (#1194)
+  // -----------------------------------------------------------------------
+
+  describe("structured tool output", () => {
+    test("an object-returning handler gets structuredContent alongside text", async () => {
+      const response = await server.handleRequest({
+        jsonrpc: "2.0",
+        id: 1,
+        method: "tools/call",
+        params: { name: "search", arguments: { query: "bucket" } },
+      });
+      const result = response!.result as { content: Array<{ text: string }>; structuredContent?: Record<string, unknown> };
+      expect(result.structuredContent).toBeDefined();
+      expect(result.structuredContent!.query).toBe("bucket");
+      const parsedText = JSON.parse(result.content[0].text);
+      expect(result.structuredContent).toEqual(parsedText);
+    });
+
+    test("a string-returning handler has no structuredContent", async () => {
+      const plugin = createMockPlugin({
+        name: "test-lex",
+        mcpTools: () => [
+          {
+            name: "greet",
+            description: "Greet",
+            inputSchema: { type: "object", properties: {} },
+            handler: async () => "hello from plugin",
+          },
+        ],
+      });
+      const s = new McpServer([plugin]);
+      const response = await s.handleRequest({
+        jsonrpc: "2.0",
+        id: 1,
+        method: "tools/call",
+        params: { name: "test-lex:greet", arguments: {} },
+      });
+      const result = response!.result as { structuredContent?: unknown };
+      expect(result.structuredContent).toBeUndefined();
+    });
+
+    test("an isError response has no structuredContent", async () => {
+      const response = await server.handleRequest({
+        jsonrpc: "2.0",
+        id: 1,
+        method: "tools/call",
+        params: { name: "unknown-tool", arguments: {} },
+      });
+      const result = response!.result as { isError: boolean; structuredContent?: unknown };
+      expect(result.isError).toBe(true);
+      expect(result.structuredContent).toBeUndefined();
+    });
   });
 
   describe("error handling", () => {

package/src/cli/mcp/server.ts

@@ -7,11 +7,50 @@ import { explainTool, handleExplain } from "./tools/explain";
 import { scaffoldTool, createScaffoldHandler } from "./tools/scaffold";
 import { searchTool, createSearchHandler } from "./tools/search";
 import type { LexiconPlugin } from "../../lexicon";
-import type { McpRequest, McpResponse, ToolDefinition, ToolHandler, ResourceDefinition } from "./types";
+import type { McpRequest, McpResponse, McpRequestMeta, ToolDefinition, ToolHandler, ResourceDefinition } from "./types";
 import { createSnapshotTool, createDiffTool } from "./lifecycle-tools";
 import { createOpListTool, createOpRunTool, createOpStatusTool, createOpSignalTool, createOpReportTool } from "./op-tools";
 import { buildResourcesList, handleResourcesRead } from "./resource-handlers";
 
+/**
+ * Protocol versions this server understands, newest first. `initialize` and
+ * `server/discover` both negotiate against this list rather than assuming
+ * the client's revision (#1194).
+ */
+const SUPPORTED_PROTOCOL_VERSIONS = ["2026-07-28", "2024-11-05"] as const;
+const LATEST_PROTOCOL_VERSION = SUPPORTED_PROTOCOL_VERSIONS[0];
+
+/**
+ * Pick the protocol version to answer with: the client's requested version
+ * when we support it, otherwise our latest. A 2024-11-05 client that asks
+ * for `2024-11-05` gets it back unchanged; a 2026-07-28 client — or one
+ * that never says — gets the latest revision (#1194).
+ */
+export function negotiateProtocolVersion(requested: string | undefined): string {
+  if (requested && (SUPPORTED_PROTOCOL_VERSIONS as readonly string[]).includes(requested)) {
+    return requested;
+  }
+  return LATEST_PROTOCOL_VERSION;
+}
+
+/**
+ * Parse the `_meta` envelope the 2026-07-28 revision puts on every request
+ * (client identity, requested protocol version), falling back to the
+ * top-level `protocolVersion`/`clientInfo` fields a prior-revision client
+ * sends on `initialize`. Read-side only — the server holds no handshake
+ * state to update (#1194).
+ */
+export function parseMeta(params: Record<string, unknown>): { protocolVersion?: string; clientInfo?: { name: string; version?: string } } {
+  const meta = (params._meta ?? {}) as McpRequestMeta;
+  const protocolVersion =
+    (typeof meta.protocolVersion === "string" ? meta.protocolVersion : undefined) ??
+    (typeof params.protocolVersion === "string" ? params.protocolVersion : undefined);
+  const clientInfo =
+    meta["io.modelcontextprotocol/clientInfo"] ??
+    (params.clientInfo as { name: string; version?: string } | undefined);
+  return { protocolVersion, clientInfo };
+}
+
 /**
  * The name a lexicon's MCP tool is registered under: `<lexicon>:<verb>`,
  * whether or not the lexicon already wrote the prefix itself (#1341).
@@ -135,9 +174,19 @@ export class McpServer {
   }
 
   /**
-   * Handle incoming MCP request
+   * Handle incoming MCP request.
+   *
+   * A message with no `id` is a notification — `notifications/initialized`
+   * being the one every client sends — and gets no response in any
+   * protocol revision (#1194). Returns `null` for those; callers (see
+   * {@link start}) simply skip writing anything back.
    */
-  async handleRequest(request: McpRequest): Promise<McpResponse> {
+  async handleRequest(request: McpRequest & { id: string | number }): Promise<McpResponse>;
+  async handleRequest(request: McpRequest): Promise<McpResponse | null>;
+  async handleRequest(request: McpRequest): Promise<McpResponse | null> {
+    if (request.id === undefined) {
+      return null;
+    }
     try {
       const result = await this.dispatch(request.method, request.params ?? {});
       return {
@@ -157,16 +206,35 @@ export class McpServer {
     }
   }
 
+  /**
+   * The `initialize` result — also the basis of `server/discover` below.
+   */
+  private buildInitializeResult(params: Record<string, unknown>): Record<string, unknown> {
+    const { protocolVersion } = parseMeta(params);
+    return {
+      protocolVersion: negotiateProtocolVersion(protocolVersion),
+      capabilities: { tools: {}, resources: {} },
+      serverInfo: { name: "chant", version: "0.1.0" },
+    };
+  }
+
   /**
    * Dispatch request to appropriate handler
    */
   private async dispatch(method: string, params: Record<string, unknown>): Promise<unknown> {
     switch (method) {
       case "initialize":
+        // Answered for prior-revision clients too — negotiated, not hard-coded (#1194).
+        return this.buildInitializeResult(params);
+
+      case "server/discover":
+        // On-demand capability discovery (#1194): the initialize result
+        // merged with the tools/resources listings, so a 2026-07-28 client
+        // never has to call `initialize` at all.
         return {
-          protocolVersion: "2024-11-05",
-          capabilities: { tools: {}, resources: {} },
-          serverInfo: { name: "chant", version: "0.1.0" },
+          ...this.buildInitializeResult(params),
+          tools: Array.from(this.tools.values()),
+          resources: buildResourcesList(this.pluginResources).resources,
         };
 
       case "tools/list":
@@ -203,6 +271,7 @@ export class McpServer {
 
     try {
       const result = await handler(toolParams);
+      const isStructured = typeof result === "object" && result !== null;
       return {
         content: [
           {
@@ -210,6 +279,11 @@ export class McpServer {
             text: typeof result === "string" ? result : JSON.stringify(result, null, 2),
           },
         ],
+        // Structured output (2025-06-18+): handlers already return plain
+        // objects that get stringified above, so agents that want the
+        // parsed shape directly get it here too, alongside the text block
+        // kept for backward compatibility (#1194).
+        ...(isStructured ? { structuredContent: result } : {}),
       };
     } catch (error) {
       return {
@@ -238,7 +312,10 @@ export class McpServer {
       try {
         const request = JSON.parse(line) as McpRequest;
         const response = await this.handleRequest(request);
-        console.log(JSON.stringify(response));
+        // Notifications (#1194) get no response at all — not even an empty one.
+        if (response !== null) {
+          console.log(JSON.stringify(response));
+        }
       } catch (error) {
         const errorResponse: McpResponse = {
           jsonrpc: "2.0",

package/src/cli/mcp/types.ts

@@ -1,9 +1,13 @@
 /**
  * MCP message types
+ *
+ * `id` is optional per JSON-RPC 2.0: a message with no `id` is a
+ * notification (e.g. `notifications/initialized`) and gets no response,
+ * in every protocol revision (#1194).
  */
 export interface McpRequest {
   jsonrpc: "2.0";
-  id: string | number;
+  id?: string | number;
   method: string;
   params?: Record<string, unknown>;
 }
@@ -19,6 +23,18 @@ export interface McpResponse {
   };
 }
 
+/**
+ * The `_meta` envelope the 2026-07-28 revision puts on every request so it
+ * is self-contained: client identity and the client's requested protocol
+ * version travel here instead of living in handshake state (#1194). A
+ * prior-revision client instead sends `protocolVersion`/`clientInfo` as
+ * top-level `initialize` params — both forms are read by {@link parseMeta}.
+ */
+export interface McpRequestMeta {
+  protocolVersion?: string;
+  "io.modelcontextprotocol/clientInfo"?: { name: string; version?: string };
+}
+
 /**
  * Tool definition for MCP
  */
@@ -30,6 +46,16 @@ export interface ToolDefinition {
     properties: Record<string, unknown>;
     required?: string[];
   };
+  /**
+   * JSON schema for `structuredContent` (2025-06-18+), when a tool's result
+   * shape is obvious and stable enough to declare. Optional and additive —
+   * most tools omit it (#1194).
+   */
+  outputSchema?: {
+    type: "object";
+    properties: Record<string, unknown>;
+    required?: string[];
+  };
 }
 
 /**

package/src/cli/registry.ts

@@ -26,7 +26,20 @@ export interface ParsedArgs {
   temporal?: boolean;
   /** `chant run` — emit the structured OpRunResult as JSON on stdout. */
   json?: boolean;
-  /** `chant run --components <name|all> --progress-json` — stream one NDJSON `RunProgressEvent` (../../components/run-progress.ts) per line to stdout while the run executes (local executor only), so a consumer can render live wave/component/phase/step progress instead of tailing raw logs. Purely additive: run semantics, ordering, and exit code are unchanged; omitted (undefined, not false) when the flag isn't passed. */
+  /**
+   * `chant run --components <name|all> --progress-json` (local executor) —
+   * stream one NDJSON `RunProgressEvent` (../../components/run-progress.ts)
+   * per line to stdout while the run executes, so a consumer can render live
+   * wave/component/phase/step progress instead of tailing raw logs.
+   *
+   * `chant run <name> --temporal --progress-json` (chant #1676) — the same
+   * flag on an Op's durable path streams one NDJSON `StepRecord`
+   * (../../op/local-executor.ts, reconstructed from workflow history by
+   * ../handlers/op-progress.ts) per settled step instead.
+   *
+   * Both are purely additive: run semantics, ordering, and exit code are
+   * unchanged; omitted (undefined, not false) when the flag isn't passed.
+   */
   progressJson?: boolean;
   live: boolean;
   /** `chant migrate --from <name>` (default "github") */
@@ -185,6 +198,25 @@ export interface ParsedArgs {
    * what is declared, which is a broader read and a different claim.
    */
   ambient?: boolean;
+  /**
+   * `chant search "<q>" --at <ref> --check-live --env <name>` (#1268) —
+   * additionally read the estate live and diff the matched rows against the
+   * snapshot the answer came from, reusing `diffLive` (the same engine
+   * `lifecycle diff --live` uses) scoped to just those rows. Requires `--at`.
+   */
+  checkLive?: boolean;
+  /**
+   * `chant search "<q>" --live --check-snapshot --env <name>` (#1268) — the
+   * reverse of `--check-live`: answer live, diff the matched rows against the
+   * most recently recorded snapshot. Requires `--live`.
+   */
+  checkSnapshot?: boolean;
+  /**
+   * `chant search "<q>" --check-live|--check-snapshot --fail-on-drift`
+   * (#1268) — exit non-zero when the scoped check finds drift, so it is usable
+   * as a CI gate. Meaningless without one of the two flags above.
+   */
+  failOnDrift?: boolean;
 
   /** `chant dev surface-diff --run-examples` — also run the example build harness */
   runExamples?: boolean;
@@ -194,9 +226,9 @@ export interface ParsedArgs {
   check?: boolean;
   /** `chant dev surface-diff --update-snapshot --bump` — bump the lexicon's package.json version by the drift severity so the accepted surface is publishable (#616). */
   bump?: boolean;
-  /** `chant components release record --component <name>` (#568) — component name for the release record being appended. */
+  /** `chant components release record --component <name>` (#568) — component name for the release record being appended. Also `chant components export <env> --component <name>` (#929) — which component's most recent recorded build to export. */
   component?: string;
-  /** `chant components release record --digest <sha256:...>` (#568) — artifact digest to record, joining this release to the build archive/ledger. */
+  /** `chant components release record --digest <sha256:...>` (#568) — artifact digest to record, joining this release to the build archive/ledger. Also `chant components export --digest <manifestDigest>` (#929) — a build archive manifest digest to export directly, bypassing env/component resolution. */
   digest?: string;
   /** `chant components release record --git-sha <sha>` (#568) — git commit the deploy was built from. */
   gitSha?: string;
@@ -218,6 +250,10 @@ export interface ParsedArgs {
   fold?: boolean;
   /** `chant build --sandbox` (#1045 Phase 2) — opt-in: run-fallback source files (or every file, without `--fold`) execute together, isolated, in one sandboxed child process instead of in-process. Also settable project-wide via `chant.config.ts`'s `build.sandbox: true`; the flag always wins when set. Default (flag omitted): in-process execution, unchanged. */
   sandbox?: boolean;
+  /** `chant build --fold --fold-rank` (#1083) — after a `--fold` build, print blockers ranked by dominator retained-count over the forward import-failure graph, plus the separate reverse-taint bucket (chant #1044). Bare boolean form; see {@link foldRankCollapsedFile} for the file-writing form. No-op without `--fold`. */
+  foldRank?: boolean;
+  /** `chant build --fold --fold-rank <path>` (#1083) — same ranking as {@link foldRank}, ALSO exported in Brendan Gregg collapsed stack format (weighted by retained count) to `<path>`, so it renders in any flame/icicle viewer. Mutually exclusive with the bare-boolean form at the parse level (same context-sensitive lookahead as `--report`), but the text report still prints either way. */
+  foldRankCollapsedFile?: string;
   /** `chant build --param name=value` (#1064) — repeatable. Bound to `params.<name>` (`@intentius/chant/params`) for source to reference, after validation against `chant.config.ts`'s declared `buildParams`. Highest precedence over `--params-file`/a declared `env` mapping/the declared `default`. */
   param?: string[];
   /** `chant build --params-file <path>` (#1064) — a JSON file of `{ "name": value }` build-time parameter values. Second precedence, after `--param`. */
@@ -228,6 +264,14 @@ export interface ParsedArgs {
    * forgejo today) — the same generator `chant build --components --generate
    * <lexicon>` uses, reused rather than re-derived. */
   projection?: string;
+  /** `chant operator --interval <duration>` (#1485) — poll interval between rounds, e.g. "30s", "5m". Default: 60s. */
+  interval?: string;
+  /** `chant operator --lease-ttl <duration>` (#1485) — how long an acquired lease is valid before it's reclaimable by another operator. Default: 5m. */
+  leaseTtl?: string;
+  /** `chant operator --once` (#1485) — run a single round and exit, instead of looping until Ctrl-C. Also the offline test/cron-invoker story. */
+  once?: boolean;
+  /** `chant approve <op> <gate> --note <text>` (#1485) — optional free-text context recorded on the gate-resolution fact (e.g. a PR URL). */
+  note?: string;
 }
 
 /**

package/src/codegen/docs-rule-scanning.test.ts

@@ -0,0 +1,42 @@
+import { describe, test, expect, beforeAll, afterAll } from "vitest";
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from "fs";
+import { join } from "path";
+import { tmpdir } from "os";
+import { scanRules } from "./docs-rule-scanning";
+
+// #1938: a post-synth check's `description` string containing a
+// backslash-escaped quote used to truncate at the first embedded `"`,
+// garbling the generated docs table entry.
+describe("scanRules — post-synth description extraction (#1938)", () => {
+  let dir: string;
+
+  beforeAll(() => {
+    dir = mkdtempSync(join(tmpdir(), "docs-rule-scanning-"));
+    mkdirSync(join(dir, "lint", "post-synth"), { recursive: true });
+    writeFileSync(
+      join(dir, "lint", "post-synth", "wk8505.ts"),
+      [
+        "export const wk8505 = {",
+        '  id: "WK8505",',
+        '  description: "A rule\'s \\"why\\" must be non-empty, and a backslash like C:\\\\path must survive intact",',
+        "  check() { return []; },",
+        "};",
+        "",
+      ].join("\n"),
+    );
+  });
+
+  afterAll(() => {
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  test("extracts the full description past an escaped quote and a backslash", () => {
+    const rules = scanRules(dir);
+    const rule = rules.find((r) => r.id === "WK8505");
+
+    expect(rule).toBeDefined();
+    expect(rule?.description).toBe(
+      'A rule\'s "why" must be non-empty, and a backslash like C:\\path must survive intact',
+    );
+  });
+});

package/src/codegen/docs-rule-scanning.ts

@@ -92,7 +92,7 @@ function scanDir(dir: string, type: "lint" | "post-synth", out: ScannedRule[]):
     } else {
       // Extract from PostSynthCheck objects: id, description
       const idMatch = content.match(/id:\s*"([^"]+)"/);
-      const descMatch = content.match(/description:\s*"([^"]+)"/);
+      const descMatch = content.match(/description:\s*"((?:[^"\\]|\\.)*)"/);
 
       if (idMatch) {
         out.push({
@@ -100,7 +100,7 @@ function scanDir(dir: string, type: "lint" | "post-synth", out: ScannedRule[]):
             id: idMatch[1],
             severity: "error",
             category: "post-synth",
-            description: descMatch?.[1] ?? idMatch[1],
+            description: descMatch ? unescapeStringLiteral(descMatch[1]) : idMatch[1],
             type: "post-synth",
           },
           source: content,
@@ -110,6 +110,29 @@ function scanDir(dir: string, type: "lint" | "post-synth", out: ScannedRule[]):
   }
 }
 
+/**
+ * Undo the backslash escaping of a double-quoted JS/TS string literal body
+ * captured by a regex like `/description:\s*"((?:[^"\\]|\\.)*)"/` — the
+ * capture group still has the source's escape sequences (`\"`, `\\`, `\n`,
+ * ...) in it verbatim, so a description written as `"say \"hi\""` would
+ * otherwise render in generated docs as `say \"hi\"` instead of `say "hi"`.
+ */
+function unescapeStringLiteral(raw: string): string {
+  return raw.replace(/\\(.)/g, (_, ch: string) => {
+    switch (ch) {
+      case "n":
+        return "\n";
+      case "t":
+        return "\t";
+      case "r":
+        return "\r";
+      default:
+        // \" -> ", \\ -> \, \' -> ', and anything else -> itself unescaped
+        return ch;
+    }
+  });
+}
+
 function extractDescriptionFromComment(
   content: string,
   ruleId: string,

package/src/components/README.md

@@ -33,6 +33,13 @@ adopting chant.
   work for a component whose own name isn't the entity/resource name it
   deploys, falling back to `name` itself when omitted. See
   docs/src/content/docs/components/observability.mdx.
+- **Composite mapping** — `composites` (#1492), optional: the composite kind
+  name(s) this component's deployed resources come from, when a consumer
+  joining a composite graph to the component DAG (e.g. `chant graph
+  --components --format ir`'s node `attrs.composites`, ../cli/handlers/
+  graph.ts) can't infer it by kebab-casing `name` against each composite's
+  kind. Omitted entirely (the default), that naming convention stays in
+  effect with no behavior change.
 - **The three archetypes** — service (build → publish → apply → verify),
   infra (apply → verify, no build), and producer/library (build → publish
   only, no service apply). `deploy` being a plain composition is what makes