@intentius/chant 0.41.20 → 0.42.1

package/src/cli/handlers/components.ts

@@ -42,6 +42,7 @@ import { findBuildManifestByArtifactDigest } from "../../lifecycle/build-ledger-
 import type { ComponentBomSummary } from "../../lifecycle/build-ledger";
 import { loadChantConfig } from "../../config";
 import { applyLiveEndpoint } from "../../live-endpoint";
+import { isResourceDeclarable } from "../../declarable";
 import { build } from "../../build";
 import { discoverComponents } from "../../components/discover";
 import { formatError, formatWarning, formatSuccess, formatBold } from "../format";
@@ -397,11 +398,12 @@ export async function runComponentsStatus(ctx: CommandContext): Promise<number>
           const declared = new Set<string>();
           const entities = new Map<string, { entityType: string; props: Record<string, unknown> }>();
           for (const [name, entity] of buildResult.entities) {
-            if (entity.lexicon === plugin.name) {
+            // Resource declarables only (see lifecycle/observe.ts).
+            if (entity.lexicon === plugin.name && isResourceDeclarable(entity)) {
               declared.add(name);
               entities.set(name, {
                 entityType: entity.entityType,
-                props: ("props" in entity && entity.props != null ? entity.props : {}) as Record<string, unknown>,
+                props: (entity.props != null ? entity.props : {}) as Record<string, unknown>,
               });
             }
           }

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

@@ -0,0 +1,93 @@
+import { describe, test, expect, vi, beforeEach, afterEach } from "vitest";
+import { mkdtemp, readFile, rm, stat } from "node:fs/promises";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { DECLARABLE_MARKER, type Declarable } from "../../declarable";
+import type { ParsedArgs } from "../registry";
+
+const discoverMock = vi.fn();
+vi.mock("../../discovery/index", () => ({
+  discover: (...a: unknown[]) => discoverMock(...a),
+}));
+
+import { runExplain } from "./explain";
+
+function decl<T extends object>(base: T): Declarable & T {
+  return { [DECLARABLE_MARKER]: true, ...base } as Declarable & T;
+}
+
+function ctx(overrides: Partial<ParsedArgs>): Parameters<typeof runExplain>[0] {
+  return {
+    args: { command: "explain", path: ".", format: "", fix: false, watch: false, verbose: false, help: false, live: false, ...overrides } as ParsedArgs,
+    plugins: [],
+    serializers: [],
+  };
+}
+
+function discoveryResult() {
+  const vpc = decl({ lexicon: "gcp", entityType: "Vpc" });
+  const subnet = decl({ lexicon: "gcp", entityType: "Subnet" });
+  return {
+    entities: new Map<string, Declarable>([
+      ["vpc", vpc],
+      ["subnet", subnet],
+    ]),
+    dependencies: new Map([["subnet", new Set(["vpc"])]]),
+    sourceFiles: ["net.ts"],
+    errors: [],
+    foldDecisions: [],
+  };
+}
+
+describe("runExplain", () => {
+  let outDir: string;
+  let logSpy: ReturnType<typeof vi.spyOn>;
+
+  beforeEach(async () => {
+    outDir = await mkdtemp(join(tmpdir(), "chant-explain-okf-"));
+    logSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+    vi.spyOn(console, "error").mockImplementation(() => {});
+    discoverMock.mockResolvedValue(discoveryResult());
+  });
+
+  afterEach(async () => {
+    vi.restoreAllMocks();
+    await rm(outDir, { recursive: true, force: true });
+  });
+
+  test("--format okf -o <dir> writes the bundle as a directory tree", async () => {
+    const code = await runExplain(ctx({ format: "okf", output: outDir }));
+    expect(code).toBe(0);
+
+    expect((await stat(join(outDir, "index.md"))).isFile()).toBe(true);
+    const subnet = await readFile(join(outDir, "gcp", "subnet.md"), "utf-8");
+    expect(subnet).toContain("type: Subnet");
+    expect(subnet).toContain("- [vpc](/gcp/vpc.md)");
+  });
+
+  test("--format okf without -o prints the bundle as JSON path -> content", async () => {
+    const code = await runExplain(ctx({ format: "okf" }));
+    expect(code).toBe(0);
+
+    const parsed = JSON.parse(logSpy.mock.calls[0][0] as string);
+    expect(parsed.okf_version).toBe("0.2");
+    expect(Object.keys(parsed.files).sort()).toEqual(["gcp/subnet.md", "gcp/vpc.md", "index.md"]);
+  });
+
+  test("default format renders the markdown summary", async () => {
+    const code = await runExplain(ctx({}));
+    expect(code).toBe(0);
+    expect(logSpy.mock.calls[0][0]).toContain("# Project Summary");
+  });
+
+  test("an unknown format is rejected", async () => {
+    const code = await runExplain(ctx({ format: "xml" }));
+    expect(code).toBe(1);
+  });
+
+  test("discovery errors surface as a non-zero exit for okf", async () => {
+    discoverMock.mockResolvedValue({ ...discoveryResult(), errors: [new Error("boom")] });
+    const code = await runExplain(ctx({ format: "okf" }));
+    expect(code).toBe(1);
+  });
+});

package/src/cli/handlers/explain.ts

@@ -0,0 +1,60 @@
+import { resolve, join, dirname } from "node:path";
+import { mkdir, writeFile } from "node:fs/promises";
+import { discover } from "../../discovery/index";
+import { buildOkfBundle, OKF_VERSION, type OkfFile } from "../../okf";
+import { handleExplain } from "../mcp/tools/explain";
+import { formatError, formatSuccess } from "../format";
+import type { CommandContext } from "../registry";
+
+const EXPLAIN_FORMATS = ["markdown", "json", "okf"] as const;
+type ExplainFormat = (typeof EXPLAIN_FORMATS)[number];
+
+/**
+ * `chant explain [path] [--format markdown|json|okf] [-o <dir>]` — the CLI
+ * path of the MCP `explain` tool (#1058): a structured summary of every
+ * discovered entity. `--format okf` emits an OKF v0.2 knowledge bundle
+ * instead — one markdown concept per entity plus an `index.md` — written as a
+ * directory tree under `-o <dir>`, or printed as JSON (path → content) when
+ * no output directory is given.
+ */
+export async function runExplain(ctx: CommandContext): Promise<number> {
+  const { args } = ctx;
+  const format = (args.format || "markdown") as ExplainFormat;
+  if (!EXPLAIN_FORMATS.includes(format)) {
+    console.error(formatError({
+      message: `Invalid --format: ${format}. Expected one of ${EXPLAIN_FORMATS.join(", ")}.`,
+    }));
+    return 1;
+  }
+
+  const projectPath = resolve(args.path === "." ? "." : args.path);
+
+  if (format === "okf") {
+    const result = await discover(projectPath);
+    for (const err of result.errors) console.error(formatError({ message: err.message }));
+    const bundle = buildOkfBundle(result, projectPath);
+    if (args.output) {
+      await writeBundle(bundle, resolve(args.output));
+      console.log(formatSuccess(`Wrote OKF v${OKF_VERSION} bundle: ${bundle.length} file(s) under ${args.output}`));
+    } else {
+      console.log(JSON.stringify({
+        okf_version: OKF_VERSION,
+        files: Object.fromEntries(bundle.map((f) => [f.path, f.content])),
+      }, null, 2));
+    }
+    return result.errors.length > 0 ? 1 : 0;
+  }
+
+  const summary = await handleExplain({ path: projectPath, format });
+  console.log(typeof summary === "string" ? summary : JSON.stringify(summary, null, 2));
+  return 0;
+}
+
+/** Write the bundle's files under `outDir`, creating subdirectories as needed. */
+async function writeBundle(bundle: OkfFile[], outDir: string): Promise<void> {
+  for (const file of bundle) {
+    const target = join(outDir, file.path);
+    await mkdir(dirname(target), { recursive: true });
+    await writeFile(target, file.content, "utf-8");
+  }
+}

package/src/cli/handlers/lifecycle.ts

@@ -32,6 +32,7 @@ import { affectedStacks } from "../../lifecycle/affected";
 import { rollbackToRevision } from "../../lifecycle/rollback";
 import { loadChantConfig, environmentNames } from "../../config";
 import { applyLiveEndpoint } from "../../live-endpoint";
+import { isResourceDeclarable } from "../../declarable";
 import { formatError, formatWarning, formatSuccess, formatBold } from "../format";
 import type { CommandContext } from "../registry";
 import type { LifecycleSnapshot } from "../../lifecycle/types";
@@ -758,17 +759,18 @@ async function runLifecycleDiffLive(args: LiveDiffArgs): Promise<LiveDiffOutcome
       continue;
     }
 
-    // Build per-lexicon entity index
+    // Build per-lexicon entity index. Resource declarables only — outputs,
+    // parameters and serializer directives have no live counterpart, and a
+    // declared name the reader can never resolve reads as missing (see
+    // lifecycle/observe.ts).
     const declared = new Set<string>();
     const entities = new Map<string, { entityType: string; props: Record<string, unknown> }>();
     for (const [name, entity] of args.buildResult.entities) {
-      if (entity.lexicon === lexiconName) {
+      if (entity.lexicon === lexiconName && isResourceDeclarable(entity)) {
         declared.add(name);
         entities.set(name, {
           entityType: entity.entityType,
-          props: ("props" in entity && entity.props != null
-            ? entity.props
-            : {}) as Record<string, unknown>,
+          props: (entity.props != null ? entity.props : {}) as Record<string, unknown>,
         });
       }
     }
@@ -1119,11 +1121,11 @@ export async function runLifecyclePlan(ctx: CommandContext): Promise<number> {
       const declared = new Set<string>();
       const entities = new Map<string, { entityType: string; props: Record<string, unknown> }>();
       for (const [name, entity] of buildResult.entities) {
-        if (entity.lexicon === lexiconName) {
+        if (entity.lexicon === lexiconName && isResourceDeclarable(entity)) {
           declared.add(name);
           entities.set(name, {
             entityType: entity.entityType,
-            props: ("props" in entity && entity.props != null ? entity.props : {}) as Record<string, unknown>,
+            props: (entity.props != null ? entity.props : {}) as Record<string, unknown>,
           });
         }
       }

package/src/cli/main.ts

@@ -26,6 +26,7 @@ import { runCarveApply } from "./handlers/carve-apply";
 import { runLifecycleSnapshot, runLifecycleShow, runLifecycleDiff, runLifecycleRollback, runLifecyclePlan, runLifecycleAffected, runLifecycleLog, runLifecycleUnknown } from "./handlers/lifecycle";
 import { runComponentsStatus, runComponentsReleaseRecord, runComponentsUnknown } from "./handlers/components";
 import { runGraph } from "./handlers/graph";
+import { runExplain } from "./handlers/explain";
 import { runSearch } from "./handlers/search";
 import { runOp, runOpList, runOpStatus, runOpSignal, runOpCancel, runOpLog } from "./handlers/run";
 import { runEmulator } from "./handlers/emulator";
@@ -212,6 +213,8 @@ export function parseArgs(args: string[]): ParsedArgs {
       result.carveStack = args[++i];
     } else if (arg === "--write") {
       result.write = true;
+    } else if (arg === "--write-source") {
+      result.writeSource = true;
     } else if (arg === "--to") {
       result.migrateTo = args[++i];
     } else if (arg === "--emit") {
@@ -385,6 +388,10 @@ Commands:
   lint                  Check specifications for issues
   list                  List discovered entities
   describe              Show the effective config for one component
+  explain               Summarize discovered entities (--format markdown|json|okf;
+                        okf emits an OKF v0.2 knowledge bundle — one markdown
+                        concept per entity + index.md; -o <dir> writes the
+                        bundle tree, otherwise JSON path→content on stdout)
   vendor                Pull pinned, checksummed patterns into your repo
   import                Import external template into TypeScript
   audit [path|url]      Audit a repo's CI YAML for security issues
@@ -402,14 +409,22 @@ Commands:
                         --select <addr>   (recommended for TF-managed resources); --env
                         --state|--env     <env> adopts via live cloud import (--live-name
                                           <logical-id> narrows a multi-resource stack).
+                                          Persists a carve manifest bridge/apply compose
+                                          with; scaffolds the output dir into a buildable
+                                          chant project (src/ + config + package.json).
   carve bridge          Generate the surviving-TF patch (data sources + rewired
-                        --from <tf-dir>   refs) + deferred inputs + reversible runbook.
-                        --select <addr>   Writes proposals for review; --apply-rewrites
-                                          edits the .tf in place.
+                        --from <tf-dir>   refs) + deferred inputs + reversible runbook,
+                        [--select <addr>] plus one git-applyable .patch for the whole
+                                          edit. Writes proposals for review;
+                                          --apply-rewrites edits the .tf in place.
+                                          --select is optional when the output dir
+                                          holds one carve manifest.
   carve apply           Apply graduation: ownership marker + finalized apply
                         --from <tf-dir>   runbook (dial-turn observe→apply). BYOL —
-                        --select <addr>   no cloud call; --write saves the doc.
-                        --env <env>
+                        [--select <addr>] no cloud call; --write saves the doc. --select
+                        --env <env>       is optional with a carve manifest present.
+                                          --write-source stamps the ownership marker
+                                          into the emitted chant source.
 
 Ops:
   run <name>            Start an Op workflow (spawns worker + submits to Temporal)
@@ -705,6 +720,7 @@ const registry: CommandDef[] = [
   { name: "lint", handler: runLint },
   { name: "list", handler: runList },
   { name: "describe", handler: runDescribe },
+  { name: "explain", handler: runExplain },
   { name: "search", handler: runSearch },
   { name: "import", handler: runImport },
   { name: "audit", handler: runAudit },

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

@@ -327,6 +327,23 @@ describe("McpServer", () => {
       expect(parsed.sourceFiles).toBeDefined();
     });
 
+    test("calls explain tool with okf format (#1058)", async () => {
+      const response = await server.handleRequest({
+        jsonrpc: "2.0",
+        id: 1,
+        method: "tools/call",
+        params: { name: "explain", arguments: { path: testDir, format: "okf" } },
+      });
+
+      expect(response.error).toBeUndefined();
+      const result = response.result as { content: Array<{ text: string }> };
+      const parsed = JSON.parse(result.content[0].text);
+      expect(parsed.okf_version).toBe("0.2");
+      // Even an empty project yields a bundle with a root index.md.
+      expect(Object.keys(parsed.files)).toEqual(["index.md"]);
+      expect(parsed.files["index.md"]).toContain("okf_version: '0.2'");
+    });
+
     test("calls scaffold tool with generic fallback", async () => {
       const response = await server.handleRequest({
         jsonrpc: "2.0",

package/src/cli/mcp/tools/explain.ts

@@ -1,5 +1,6 @@
 import { resolve } from "path";
 import { discover } from "../../../discovery/index";
+import { buildOkfBundle, OKF_VERSION } from "../../../okf";
 
 /**
  * Explain tool definition for MCP
@@ -16,8 +17,8 @@ export const explainTool = {
       },
       format: {
         type: "string",
-        enum: ["markdown", "json"],
-        description: "Output format (default: markdown)",
+        enum: ["markdown", "json", "okf"],
+        description: "Output format (default: markdown). okf: an OKF v0.2 knowledge bundle — one markdown concept per entity plus an index.md (#1058)",
       },
     },
     required: ["path"],
@@ -29,11 +30,22 @@ export const explainTool = {
  */
 export async function handleExplain(params: Record<string, unknown>): Promise<unknown> {
   const path = params.path as string;
-  const format = (params.format as "markdown" | "json") ?? "markdown";
+  const format = (params.format as "markdown" | "json" | "okf") ?? "markdown";
 
   const infraPath = resolve(path);
   const result = await discover(infraPath);
 
+  // OKF knowledge bundle (#1058): one concept document per entity plus a root
+  // index.md, returned as bundle-relative path → content. The CLI path writes
+  // the same files to a directory.
+  if (format === "okf") {
+    return {
+      okf_version: OKF_VERSION,
+      files: Object.fromEntries(buildOkfBundle(result, infraPath).map((f) => [f.path, f.content])),
+      errors: result.errors.map((e) => e.message),
+    };
+  }
+
   // Group entities by lexicon and kind
   const byLexicon = new Map<string, { resources: string[]; properties: string[] }>();
 

package/src/cli/registry.ts

@@ -45,6 +45,8 @@ export interface ParsedArgs {
   carveStack?: string;
   /** `chant carve apply --write` — save the graduation doc */
   write?: boolean;
+  /** `chant carve apply --write-source` — stamp the ownership marker into the emitted source */
+  writeSource?: boolean;
   /** `chant migrate --to <name>` (default "gitlab") */
   migrateTo?: string;
   /** `chant migrate --emit yaml|ts` */

package/src/codegen/__snapshots__/okf-lexicon.test.ts.snap

@@ -0,0 +1,170 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`buildLexiconOkfBundle > registry-style and dts-style bundles snapshot stably 1`] = `
+[
+  {
+    "content": "---
+okf_version: '0.2'
+---
+
+# Resource types
+
+* [Service](/types/Service.md) - Mock::Compose::Service
+* [Volume](/types/Volume.md) - Mock::Compose::Volume
+
+# Rules
+
+* [MCK001](/rules/MCK001.md) - Avoid :latest image references on a Service
+* [MCK010](/rules/MCK010.md) - A declared Volume must be mounted somewhere
+",
+    "path": "index.md",
+  },
+  {
+    "content": "---
+type: lint-rule
+title: MCK001
+description: Avoid :latest image references on a Service
+id: MCK001
+severity: warning
+category: correctness
+lexicon: mockdocker
+docs: https://intentius.io/chant/lexicons/mockdocker/rules/
+---
+Avoid :latest image references on a Service
+
+## Applies to
+
+- [Service](/types/Service.md)
+",
+    "path": "rules/MCK001.md",
+  },
+  {
+    "content": "---
+type: post-synth-check
+title: MCK010
+description: A declared Volume must be mounted somewhere
+id: MCK010
+severity: error
+category: post-synth
+lexicon: mockdocker
+docs: https://intentius.io/chant/lexicons/mockdocker/rules/
+---
+A declared Volume must be mounted somewhere
+
+## Applies to
+
+- [Volume](/types/Volume.md)
+",
+    "path": "rules/MCK010.md",
+  },
+  {
+    "content": "---
+type: resource-type
+title: Service
+description: A containerized service definition
+name: Service
+lexicon: mockdocker
+resource_type: Mock::Compose::Service
+---
+A containerized service definition
+
+## Properties
+
+- \`image\` (\`string\`): Container image to use
+- \`ports\` (\`string[]\`): Published ports
+
+## Governed by
+
+- [MCK001](/rules/MCK001.md): Avoid :latest image references on a Service
+",
+    "path": "types/Service.md",
+  },
+  {
+    "content": "---
+type: resource-type
+title: Volume
+description: A named volume
+name: Volume
+lexicon: mockdocker
+resource_type: Mock::Compose::Volume
+---
+A named volume
+
+## Properties
+
+- \`driver\` (\`string\`): Volume driver
+
+## Governed by
+
+- [MCK010](/rules/MCK010.md): A declared Volume must be mounted somewhere
+",
+    "path": "types/Volume.md",
+  },
+]
+`;
+
+exports[`buildLexiconOkfBundle > registry-style and dts-style bundles snapshot stably 2`] = `
+[
+  {
+    "content": "---
+okf_version: '0.2'
+---
+
+# Resource types
+
+* [Bucket](/types/Bucket.md) - Mock::S3::Bucket
+
+# Rules
+
+* [MAW006](/rules/MAW006.md) - Detects Bucket creation without encryption
+",
+    "path": "index.md",
+  },
+  {
+    "content": "---
+type: lint-rule
+title: MAW006
+description: Detects Bucket creation without encryption
+id: MAW006
+severity: warning
+category: security
+lexicon: mockaws
+docs: https://intentius.io/chant/lexicons/mockaws/rules/
+---
+Detects Bucket creation without encryption
+
+## Applies to
+
+- [Bucket](/types/Bucket.md)
+",
+    "path": "rules/MAW006.md",
+  },
+  {
+    "content": "---
+type: resource-type
+title: Bucket
+description: mockaws resource type Mock::S3::Bucket
+name: Bucket
+lexicon: mockaws
+resource_type: Mock::S3::Bucket
+---
+\`Mock::S3::Bucket\`, a resource type of the mockaws lexicon.
+
+## Properties
+
+- \`BucketName\` (\`string\`, optional): A name for the bucket.
+- \`VersioningConfiguration\` (\`Bucket_VersioningConfiguration\`, optional): The versioning state.
+
+## Attributes
+
+- \`Arn\`
+- \`DomainName\`
+
+## Governed by
+
+- [MAW006](/rules/MAW006.md): Detects Bucket creation without encryption
+",
+    "path": "types/Bucket.md",
+  },
+]
+`;

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

@@ -11,12 +11,27 @@ import { join } from "path";
 import { escapeMdx } from "./docs-file-markers";
 import type { DocsConfig, RuleMeta } from "./docs-types";
 
+/** A scanned rule: its extracted metadata plus the source it came from. */
+export interface ScannedRule {
+  meta: RuleMeta;
+  source: string;
+}
+
 /**
  * Scan lint rule and post-synth check source files to extract metadata.
  * Uses regex to find id, severity, category, and description from source.
  */
 export function scanRules(srcDir: string): RuleMeta[] {
-  const rules: RuleMeta[] = [];
+  return scanRulesWithSources(srcDir).map((r) => r.meta);
+}
+
+/**
+ * Like {@link scanRules}, but keeps each rule's source text alongside its
+ * metadata — the OKF bundle builder (#1060) reads the source to associate a
+ * rule with the resource types it mentions.
+ */
+export function scanRulesWithSources(srcDir: string): ScannedRule[] {
+  const rules: ScannedRule[] = [];
 
   // Scan lint rules
   scanDir(join(srcDir, "lint", "rules"), "lint", rules);
@@ -27,7 +42,7 @@ export function scanRules(srcDir: string): RuleMeta[] {
   return rules;
 }
 
-function scanDir(dir: string, type: "lint" | "post-synth", out: RuleMeta[]): void {
+function scanDir(dir: string, type: "lint" | "post-synth", out: ScannedRule[]): void {
   let entries: string[];
   try {
     entries = readdirSync(dir);
@@ -62,13 +77,16 @@ function scanDir(dir: string, type: "lint" | "post-synth", out: RuleMeta[]): voi
         );
 
         out.push({
-          id: idMatch[1],
-          severity: severityMatch?.[1] ?? "warning",
-          category: categoryMatch?.[1] ?? "general",
-          description:
-            descMatch?.[1]?.trim() ??
-            extractDescriptionFromComment(content, idMatch[1]),
-          type: "lint",
+          meta: {
+            id: idMatch[1],
+            severity: severityMatch?.[1] ?? "warning",
+            category: categoryMatch?.[1] ?? "general",
+            description:
+              descMatch?.[1]?.trim() ??
+              extractDescriptionFromComment(content, idMatch[1]),
+            type: "lint",
+          },
+          source: content,
         });
       }
     } else {
@@ -78,11 +96,14 @@ function scanDir(dir: string, type: "lint" | "post-synth", out: RuleMeta[]): voi
 
       if (idMatch) {
         out.push({
-          id: idMatch[1],
-          severity: "error",
-          category: "post-synth",
-          description: descMatch?.[1] ?? idMatch[1],
-          type: "post-synth",
+          meta: {
+            id: idMatch[1],
+            severity: "error",
+            category: "post-synth",
+            description: descMatch?.[1] ?? idMatch[1],
+            type: "post-synth",
+          },
+          source: content,
         });
       }
     }