@intentius/chant 0.41.19 → 0.42.1

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/handlers/misc.ts

@@ -1,6 +1,6 @@
 import { listCommand, printListResult } from "../commands/list";
 import { describeCommand, printDescribeResult } from "../commands/describe";
-import { importCommand, importFromLive, importFromLiveStacks, printImportResult } from "../commands/import";
+import { importCommand, importFromContent, importFromLive, importFromLiveStacks, printImportResult } from "../commands/import";
 import { loadChantConfig } from "../../config";
 import { resolve } from "path";
 import { auditCommand, printAuditResult, type AuditFormat, type AuditTier, type AuditFailOn } from "../commands/audit";
@@ -171,6 +171,45 @@ export async function runDescribe(ctx: CommandContext): Promise<number> {
 export async function runImport(ctx: CommandContext): Promise<number> {
   const { args } = ctx;
 
+  // `--kustomize <dir>` (#1548): render the overlay and import the output
+  // through the k8s template parser — the flag NAMES the lexicon, so no JSON
+  // detection. `kustomize build`, falling back to kubectl's vendored
+  // kustomize when the standalone binary is absent; a big overlay renders
+  // megabytes, hence the buffer bound.
+  if (args.kustomize) {
+    const { exec } = await import("node:child_process");
+    const { promisify } = await import("node:util");
+    const execAsync = promisify(exec);
+    const run = (cmd: string) => execAsync(cmd, { maxBuffer: 64 * 1024 * 1024 });
+    const quoted = `'${args.kustomize.replace(/'/g, "'\\''")}'`;
+    let rendered: string;
+    try {
+      ({ stdout: rendered } = await run(`kustomize build ${quoted}`));
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      if (!/ENOENT|not found|command not found|127/.test(message)) {
+        console.error(formatError({ message: `kustomize build failed: ${message.split("\n")[0]}` }));
+        return 1;
+      }
+      try {
+        ({ stdout: rendered } = await run(`kubectl kustomize ${quoted}`));
+      } catch (err2) {
+        console.error(formatError({
+          message: `neither kustomize nor kubectl could render ${args.kustomize}: ${err2 instanceof Error ? err2.message.split("\n")[0] : String(err2)}`,
+        }));
+        return 1;
+      }
+    }
+    const result = await importFromContent({
+      content: rendered,
+      lexicon: "k8s",
+      output: args.output,
+      force: args.force,
+    });
+    printImportResult(result);
+    return result.success ? 0 : 1;
+  }
+
   // `--from <env>` switches import from a template file to a live source.
   if (args.migrateFrom) {
     const selector: ResourceSelector | undefined =

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

@@ -951,7 +951,9 @@ describe("runOpComponents", () => {
       expect(runComponentsMock).toHaveBeenCalledWith(expect.any(String), "svc", expect.objectContaining({
         buildParams: [{ name: "tier", value: "light", source: "default" }],
       }));
-      expect(stderr.join("\n")).toContain("[param] tier");
+      // A parameter at its default collapses into the count line now; the
+      // provenance forwarded above is where its value is asserted.
+      expect(stderr.join("\n")).toContain("at their defaults");
     });
 
     test("--param overrides a declared default and is threaded through to runComponents", async () => {

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";
@@ -188,6 +189,10 @@ export function parseArgs(args: string[]): ParsedArgs {
       // Shared by `migrate --from <lexicon>` and `import --from <env>`; the
       // two commands never run together, so one field carries both.
       result.migrateFrom = args[++i];
+    } else if (arg === "--kustomize") {
+      // `chant import --kustomize <dir>` (#1548): render the overlay, import
+      // the output through the k8s template parser.
+      result.kustomize = args[++i];
     } else if (arg === "--type") {
       result.selectType = args[++i];
     } else if (arg === "--name") {
@@ -208,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") {
@@ -381,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
@@ -398,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)
@@ -701,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

@@ -31,6 +31,8 @@ export interface ParsedArgs {
   live: boolean;
   /** `chant migrate --from <name>` (default "github") */
   migrateFrom?: string;
+  /** `chant import --kustomize <dir>` — render the kustomization, then import (#1548) */
+  kustomize?: string;
   /** `chant carve advise --state <path>` — opt-in .tfstate for accurate instance counts */
   statePath?: string;
   /** `chant carve emit --select <tf-address>` — the Terraform resource to carve */
@@ -43,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,
         });
       }
     }