@intentius/chant 0.41.20 → 0.44.1

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/plugins.ts

@@ -95,6 +95,23 @@ export function resolveLexiconVersions(lexiconNames: readonly string[]): Record<
   return versions;
 }
 
+/**
+ * Bind each loaded plugin's `buildRoots` hook (#1548 piece 3) to this
+ * invocation's config and project root, producing the closures
+ * `BuildOptions.buildRoots` takes — the same extract-then-thread shape the
+ * CLI uses for `intrinsics`. Plugins without the hook contribute nothing;
+ * an empty array is the common case and `build()` treats it as absent.
+ */
+export function collectBuildRootContributors(
+  plugins: readonly LexiconPlugin[] | undefined,
+  config: Record<string, unknown>,
+  projectRoot: string,
+): Array<() => Promise<import("../lexicon").BuildRootContribution>> {
+  return (plugins ?? [])
+    .filter((plugin) => typeof plugin.buildRoots === "function")
+    .map((plugin) => () => plugin.buildRoots!({ projectRoot, config }));
+}
+
 /**
  * Load plugins for all detected lexicon names.
  * Calls `init()` on each plugin if present.

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,
         });
       }
     }

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

@@ -0,0 +1,248 @@
+import { describe, test, expect } from "vitest";
+import { buildLexiconOkfBundle, type LexiconOkfInput } from "./okf-lexicon";
+import { okfConformanceProblems, splitFrontmatter, OKF_VERSION, type OkfFile } from "../okf";
+import { parseYAML } from "../yaml";
+
+function fileMap(bundle: OkfFile[]): Map<string, string> {
+  return new Map(bundle.map((f) => [f.path, f.content]));
+}
+
+/** A docker-style registry: descriptions carried in the registry itself. */
+const registryStyleInput: LexiconOkfInput = {
+  name: "mockdocker",
+  registry: JSON.stringify({
+    Service: {
+      resourceType: "Mock::Compose::Service",
+      kind: "resource",
+      description: "A containerized service definition",
+      properties: {
+        image: { type: "string", description: "Container image to use" },
+        ports: { type: "string[]", description: "Published ports" },
+      },
+    },
+    Volume: {
+      resourceType: "Mock::Compose::Volume",
+      kind: "resource",
+      description: "A named volume",
+      properties: { driver: { type: "string", description: "Volume driver" } },
+    },
+    Service_Healthcheck: {
+      resourceType: "Mock::Compose::Service.Healthcheck",
+      kind: "property",
+    },
+  }),
+  typesDTS: "",
+  rules: [
+    {
+      meta: {
+        id: "MCK001",
+        severity: "warning",
+        category: "correctness",
+        description: "Avoid :latest image references on a Service",
+        type: "lint",
+      },
+      source: `// Checks each Service's image prop\nexport const rule = { id: "MCK001" };`,
+    },
+    {
+      meta: {
+        id: "MCK010",
+        severity: "error",
+        category: "post-synth",
+        description: "A declared Volume must be mounted somewhere",
+        type: "post-synth",
+      },
+      source: `export const check = { id: "MCK010", description: "..." }; // walks Volume mounts`,
+    },
+  ],
+};
+
+/** A CFN-style registry: no descriptions, JSDoc lives in the declarations. */
+const dtsStyleInput: LexiconOkfInput = {
+  name: "mockaws",
+  registry: JSON.stringify({
+    Bucket: {
+      resourceType: "Mock::S3::Bucket",
+      kind: "resource",
+      lexicon: "mockaws",
+      attrs: { Arn: "Arn", DomainName: "DomainName" },
+    },
+    // An alias entry for the same resource type must not mint a second concept.
+    S3Bucket: {
+      resourceType: "Mock::S3::Bucket",
+      kind: "resource",
+      lexicon: "mockaws",
+      attrs: { Arn: "Arn", DomainName: "DomainName" },
+    },
+    Bucket_VersioningConfiguration: {
+      resourceType: "Mock::S3::Bucket.VersioningConfiguration",
+      kind: "property",
+      lexicon: "mockaws",
+    },
+  }),
+  typesDTS: [
+    "export declare class Bucket {",
+    "  constructor(props: {",
+    "    /** A name for the bucket. */",
+    "    BucketName?: string;",
+    "    /** The versioning state. */",
+    "    VersioningConfiguration?: Bucket_VersioningConfiguration;",
+    "  }, attributes?: Record<string, unknown>);",
+    "  readonly Arn: string;",
+    "}",
+  ].join("\n"),
+  rules: [
+    {
+      meta: {
+        id: "MAW006",
+        severity: "warning",
+        category: "security",
+        description: "Detects Bucket creation without encryption",
+        type: "lint",
+      },
+      source: `if (expression.text === "Bucket") { /* Mock::S3::Bucket */ }`,
+    },
+  ],
+};
+
+describe("buildLexiconOkfBundle", () => {
+  test("emits a conformant bundle from a registry-described lexicon", () => {
+    const bundle = buildLexiconOkfBundle(registryStyleInput);
+    expect(okfConformanceProblems(bundle)).toEqual([]);
+    expect(bundle.map((f) => f.path)).toEqual([
+      "index.md",
+      "rules/MCK001.md",
+      "rules/MCK010.md",
+      "types/Service.md",
+      "types/Volume.md",
+    ]);
+  });
+
+  test("concept type is the category, the resource type rides in resource_type", () => {
+    const files = fileMap(buildLexiconOkfBundle(registryStyleInput));
+    const front = parseYAML(splitFrontmatter(files.get("types/Service.md")!)!.frontmatter);
+    expect(front.type).toBe("resource-type");
+    expect(front.resource_type).toBe("Mock::Compose::Service");
+    expect(front.title).toBe("Service");
+    expect(front.lexicon).toBe("mockdocker");
+    expect(front.description).toBe("A containerized service definition");
+  });
+
+  test("registry-carried property descriptions land in the concept body", () => {
+    const files = fileMap(buildLexiconOkfBundle(registryStyleInput));
+    const body = splitFrontmatter(files.get("types/Service.md")!)!.body;
+    expect(body).toContain("## Properties");
+    expect(body).toContain("- `image` (`string`): Container image to use");
+    expect(body).toContain("- `ports` (`string[]`): Published ports");
+  });
+
+  test("declaration JSDoc fills in property descriptions when the registry has none", () => {
+    const files = fileMap(buildLexiconOkfBundle(dtsStyleInput));
+    const body = splitFrontmatter(files.get("types/Bucket.md")!)!.body;
+    expect(body).toContain("- `BucketName` (`string`, optional): A name for the bucket.");
+    expect(body).toContain("- `VersioningConfiguration` (`Bucket_VersioningConfiguration`, optional): The versioning state.");
+    expect(body).toContain("## Attributes");
+    expect(body).toContain("- `Arn`");
+  });
+
+  test("rules and resource types cross-link in both directions", () => {
+    const files = fileMap(buildLexiconOkfBundle(registryStyleInput));
+    expect(splitFrontmatter(files.get("types/Service.md")!)!.body).toContain(
+      "- [MCK001](/rules/MCK001.md): Avoid :latest image references on a Service",
+    );
+    expect(splitFrontmatter(files.get("rules/MCK001.md")!)!.body).toContain("- [Service](/types/Service.md)");
+    // MCK010 mentions Volume, not Service.
+    expect(splitFrontmatter(files.get("rules/MCK010.md")!)!.body).toContain("- [Volume](/types/Volume.md)");
+    expect(splitFrontmatter(files.get("rules/MCK010.md")!)!.body).not.toContain("types/Service.md");
+    expect(splitFrontmatter(files.get("types/Volume.md")!)!.body).toContain("- [MCK010](/rules/MCK010.md)");
+  });
+
+  test("rule concepts carry id, severity, category, and a docs page", () => {
+    const files = fileMap(buildLexiconOkfBundle(registryStyleInput));
+    const lint = parseYAML(splitFrontmatter(files.get("rules/MCK001.md")!)!.frontmatter);
+    expect(lint.type).toBe("lint-rule");
+    expect(lint.id).toBe("MCK001");
+    expect(lint.severity).toBe("warning");
+    expect(lint.category).toBe("correctness");
+    expect(lint.docs).toBe("https://intentius.io/chant/lexicons/mockdocker/rules/");
+
+    const postSynth = parseYAML(splitFrontmatter(files.get("rules/MCK010.md")!)!.frontmatter);
+    expect(postSynth.type).toBe("post-synth-check");
+    expect(postSynth.severity).toBe("error");
+  });
+
+  test("alias registry entries collapse into one concept per resource type", () => {
+    const bundle = buildLexiconOkfBundle(dtsStyleInput);
+    const typePaths = bundle.map((f) => f.path).filter((p) => p.startsWith("types/"));
+    expect(typePaths).toEqual(["types/Bucket.md"]);
+    expect(okfConformanceProblems(bundle)).toEqual([]);
+  });
+
+  test("property-kind registry entries do not become concepts", () => {
+    const files = fileMap(buildLexiconOkfBundle(registryStyleInput));
+    expect([...files.keys()].some((p) => p.includes("Healthcheck"))).toBe(false);
+  });
+
+  test("index.md sections resource types and rules with okf_version its only frontmatter", () => {
+    const index = fileMap(buildLexiconOkfBundle(registryStyleInput)).get("index.md")!;
+    expect(index).toContain(`okf_version: '${OKF_VERSION}'`);
+    expect(index).toContain("# Resource types");
+    expect(index).toContain("* [Service](/types/Service.md) - Mock::Compose::Service");
+    expect(index).toContain("# Rules");
+    expect(index).toContain("* [MCK001](/rules/MCK001.md) - Avoid :latest image references on a Service");
+  });
+
+  test("an empty lexicon still emits a conformant bundle", () => {
+    const bundle = buildLexiconOkfBundle({ name: "bare", registry: "{}", typesDTS: "", rules: [] });
+    expect(bundle.map((f) => f.path)).toEqual(["index.md"]);
+    expect(okfConformanceProblems(bundle)).toEqual([]);
+  });
+
+  test("deterministic: the same input yields byte-identical files", () => {
+    expect(buildLexiconOkfBundle(registryStyleInput)).toEqual(buildLexiconOkfBundle(registryStyleInput));
+  });
+
+  test("multi-line spec descriptions collapse to a single frontmatter line", () => {
+    const input: LexiconOkfInput = {
+      name: "mock",
+      registry: JSON.stringify({
+        Thing: {
+          resourceType: "Mock::A::Thing",
+          kind: "resource",
+          description: "First line.\nSecond line with detail.",
+        },
+      }),
+      typesDTS: "",
+      rules: [],
+    };
+    const bundle = buildLexiconOkfBundle(input);
+    expect(okfConformanceProblems(bundle)).toEqual([]);
+    const front = parseYAML(splitFrontmatter(fileMap(bundle).get("types/Thing.md")!)!.frontmatter);
+    expect(front.description).toBe("First line. Second line with detail.");
+  });
+
+  test("registry-style and dts-style bundles snapshot stably", () => {
+    expect(buildLexiconOkfBundle(registryStyleInput)).toMatchSnapshot();
+    expect(buildLexiconOkfBundle(dtsStyleInput)).toMatchSnapshot();
+  });
+});
+
+describe("okfConformanceProblems", () => {
+  test("flags a concept without frontmatter and a bundle without an index", () => {
+    const problems = okfConformanceProblems([{ path: "types/Broken.md", content: "no frontmatter here" }]);
+    expect(problems).toContain("types/Broken.md: no frontmatter block");
+    expect(problems).toContain("bundle has no root index.md");
+  });
+
+  test("flags an empty type and a relative cross-link", () => {
+    const bundle: OkfFile[] = [
+      {
+        path: "types/Bad.md",
+        content: "---\ntype: ''\n---\n\n- [x](x.md)\n",
+      },
+      { path: "index.md", content: `---\nokf_version: '${OKF_VERSION}'\n---\n` },
+    ];
+    const problems = okfConformanceProblems(bundle);
+    expect(problems.some((p) => p.includes("no non-empty type"))).toBe(true);
+    expect(problems.some((p) => p.includes('link target "x.md"'))).toBe(true);
+  });
+});