@intentius/chant 0.0.4 → 0.0.8

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

@@ -81,7 +81,7 @@ describe("McpServer", () => {
   // -----------------------------------------------------------------------
 
   describe("tools/list", () => {
-    test("returns core tools (build, lint, import)", async () => {
+    test("returns core tools (build, lint, import, explain, scaffold, search)", async () => {
       const response = await server.handleRequest({
         jsonrpc: "2.0",
         id: 1,
@@ -94,6 +94,9 @@ describe("McpServer", () => {
       expect(toolNames).toContain("build");
       expect(toolNames).toContain("lint");
       expect(toolNames).toContain("import");
+      expect(toolNames).toContain("explain");
+      expect(toolNames).toContain("scaffold");
+      expect(toolNames).toContain("search");
     });
 
     test("each tool has name, description, and inputSchema", async () => {
@@ -148,6 +151,46 @@ describe("McpServer", () => {
       expect(props.source).toBeDefined();
       expect(props.output).toBeDefined();
     });
+
+    test("explain tool schema has path and format properties", async () => {
+      const response = await server.handleRequest({
+        jsonrpc: "2.0",
+        id: 1,
+        method: "tools/list",
+      });
+      const result = response.result as { tools: Array<{ name: string; inputSchema: Record<string, unknown> }> };
+      const tool = result.tools.find((t) => t.name === "explain")!;
+      const props = tool.inputSchema.properties as Record<string, unknown>;
+      expect(props.path).toBeDefined();
+      expect(props.format).toBeDefined();
+    });
+
+    test("scaffold tool schema has pattern and lexicon properties", async () => {
+      const response = await server.handleRequest({
+        jsonrpc: "2.0",
+        id: 1,
+        method: "tools/list",
+      });
+      const result = response.result as { tools: Array<{ name: string; inputSchema: Record<string, unknown> }> };
+      const tool = result.tools.find((t) => t.name === "scaffold")!;
+      const props = tool.inputSchema.properties as Record<string, unknown>;
+      expect(props.pattern).toBeDefined();
+      expect(props.lexicon).toBeDefined();
+    });
+
+    test("search tool schema has query, lexicon, and limit properties", async () => {
+      const response = await server.handleRequest({
+        jsonrpc: "2.0",
+        id: 1,
+        method: "tools/list",
+      });
+      const result = response.result as { tools: Array<{ name: string; inputSchema: Record<string, unknown> }> };
+      const tool = result.tools.find((t) => t.name === "search")!;
+      const props = tool.inputSchema.properties as Record<string, unknown>;
+      expect(props.query).toBeDefined();
+      expect(props.lexicon).toBeDefined();
+      expect(props.limit).toBeDefined();
+    });
   });
 
   describe("tools/call", () => {
@@ -194,6 +237,166 @@ describe("McpServer", () => {
       expect(result.isError).toBe(true);
       expect(result.content[0].text).toContain("Error:");
     });
+
+    test("calls explain tool on empty directory", async () => {
+      const response = await server.handleRequest({
+        jsonrpc: "2.0",
+        id: 1,
+        method: "tools/call",
+        params: { name: "explain", arguments: { path: testDir } },
+      });
+
+      expect(response.error).toBeUndefined();
+      const result = response.result as { content: Array<{ type: string; text: string }> };
+      expect(result.content[0].type).toBe("text");
+      expect(result.content[0].text).toContain("Project Summary");
+    });
+
+    test("calls explain tool with json format", async () => {
+      const response = await server.handleRequest({
+        jsonrpc: "2.0",
+        id: 1,
+        method: "tools/call",
+        params: { name: "explain", arguments: { path: testDir, format: "json" } },
+      });
+
+      expect(response.error).toBeUndefined();
+      const result = response.result as { content: Array<{ text: string }> };
+      const parsed = JSON.parse(result.content[0].text);
+      expect(parsed.totalEntities).toBe(0);
+      expect(parsed.sourceFiles).toBeDefined();
+    });
+
+    test("calls scaffold tool with generic fallback", async () => {
+      const response = await server.handleRequest({
+        jsonrpc: "2.0",
+        id: 1,
+        method: "tools/call",
+        params: { name: "scaffold", arguments: { pattern: "my-service" } },
+      });
+
+      expect(response.error).toBeUndefined();
+      const result = response.result as { content: Array<{ text: string }> };
+      const parsed = JSON.parse(result.content[0].text);
+      expect(parsed.pattern).toBe("my-service");
+      expect(parsed.files).toBeDefined();
+      expect(parsed.files.length).toBeGreaterThan(0);
+    });
+
+    test("calls search tool with no plugins", async () => {
+      const response = await server.handleRequest({
+        jsonrpc: "2.0",
+        id: 1,
+        method: "tools/call",
+        params: { name: "search", arguments: { query: "bucket" } },
+      });
+
+      expect(response.error).toBeUndefined();
+      const result = response.result as { content: Array<{ text: string }> };
+      const parsed = JSON.parse(result.content[0].text);
+      expect(parsed.query).toBe("bucket");
+      expect(parsed.total).toBe(0);
+      expect(parsed.results).toEqual([]);
+    });
+  });
+
+  // -----------------------------------------------------------------------
+  // Search tool with plugins
+  // -----------------------------------------------------------------------
+
+  describe("search with plugins", () => {
+    test("searches plugin resource catalogs", async () => {
+      const plugin = createMockPlugin({
+        name: "test-lex",
+        mcpResources: () => [
+          {
+            uri: "resource-catalog",
+            name: "Test Catalog",
+            description: "Test resource catalog",
+            mimeType: "application/json",
+            handler: async () => JSON.stringify([
+              { className: "Bucket", resourceType: "AWS::S3::Bucket", kind: "resource" },
+              { className: "Table", resourceType: "AWS::DynamoDB::Table", kind: "resource" },
+            ]),
+          },
+        ],
+      });
+
+      const s = new McpServer([plugin]);
+      const response = await s.handleRequest({
+        jsonrpc: "2.0",
+        id: 1,
+        method: "tools/call",
+        params: { name: "search", arguments: { query: "bucket" } },
+      });
+
+      const result = response.result as { content: Array<{ text: string }> };
+      const parsed = JSON.parse(result.content[0].text);
+      expect(parsed.total).toBe(1);
+      expect(parsed.results[0].className).toBe("Bucket");
+      expect(parsed.results[0].lexicon).toBe("test-lex");
+    });
+
+    test("search respects limit parameter", async () => {
+      const entries = Array.from({ length: 30 }, (_, i) => ({
+        className: `Type${i}`,
+        resourceType: `NS::Type${i}`,
+        kind: "resource",
+      }));
+      const plugin = createMockPlugin({
+        name: "big",
+        mcpResources: () => [
+          {
+            uri: "resource-catalog",
+            name: "Big Catalog",
+            description: "Big catalog",
+            mimeType: "application/json",
+            handler: async () => JSON.stringify(entries),
+          },
+        ],
+      });
+
+      const s = new McpServer([plugin]);
+      const response = await s.handleRequest({
+        jsonrpc: "2.0",
+        id: 1,
+        method: "tools/call",
+        params: { name: "search", arguments: { query: "type", limit: 5 } },
+      });
+
+      const parsed = JSON.parse((response.result as { content: Array<{ text: string }> }).content[0].text);
+      expect(parsed.total).toBe(30);
+      expect(parsed.results.length).toBe(5);
+    });
+  });
+
+  // -----------------------------------------------------------------------
+  // Scaffold tool with plugins
+  // -----------------------------------------------------------------------
+
+  describe("scaffold with plugins", () => {
+    test("matches plugin init templates", async () => {
+      const plugin = createMockPlugin({
+        name: "test-lex",
+        initTemplates: () => ({
+          "config.ts": "export const config = {};",
+          "data-bucket.ts": "export const dataBucket = {};",
+        }),
+      });
+
+      const s = new McpServer([plugin]);
+      const response = await s.handleRequest({
+        jsonrpc: "2.0",
+        id: 1,
+        method: "tools/call",
+        params: { name: "scaffold", arguments: { pattern: "bucket", lexicon: "test-lex" } },
+      });
+
+      const parsed = JSON.parse((response.result as { content: Array<{ text: string }> }).content[0].text);
+      expect(parsed.lexicon).toBe("test-lex");
+      expect(parsed.files.length).toBe(1);
+      expect(parsed.files[0].filename).toBe("data-bucket.ts");
+    });
   });
 
   // -----------------------------------------------------------------------
@@ -729,8 +932,8 @@ describe("McpServer", () => {
 
       const toolsRes = await s.handleRequest({ jsonrpc: "2.0", id: 2, method: "tools/list" });
       const tools = (toolsRes.result as { tools: Array<{ name: string }> }).tools;
-      expect(tools).toHaveLength(3);
-      expect(tools.map((t) => t.name).sort()).toEqual(["build", "import", "lint"]);
+      expect(tools).toHaveLength(6);
+      expect(tools.map((t) => t.name).sort()).toEqual(["build", "explain", "import", "lint", "scaffold", "search"]);
 
       const resourcesRes = await s.handleRequest({ jsonrpc: "2.0", id: 3, method: "resources/list" });
       const resources = (resourcesRes.result as { resources: Array<{ uri: string }> }).resources;
@@ -741,7 +944,7 @@ describe("McpServer", () => {
       const s = new McpServer([]);
       const toolsRes = await s.handleRequest({ jsonrpc: "2.0", id: 1, method: "tools/list" });
       const tools = (toolsRes.result as { tools: Array<{ name: string }> }).tools;
-      expect(tools).toHaveLength(3);
+      expect(tools).toHaveLength(6);
     });
   });
 });

package/src/cli/mcp/server.ts

@@ -3,6 +3,9 @@ import { resolve } from "node:path";
 import { buildTool, handleBuild } from "./tools/build";
 import { lintTool, handleLint } from "./tools/lint";
 import { importTool, handleImport } from "./tools/import";
+import { explainTool, handleExplain } from "./tools/explain";
+import { scaffoldTool, createScaffoldHandler } from "./tools/scaffold";
+import { searchTool, createSearchHandler } from "./tools/search";
 import { getContext } from "./resources/context";
 import type { LexiconPlugin } from "../../lexicon";
 import type { McpToolContribution, McpResourceContribution } from "../../mcp/types";
@@ -70,6 +73,9 @@ export class McpServer {
     this.registerTool(buildTool, handleBuild);
     this.registerTool(lintTool, handleLint);
     this.registerTool(importTool, handleImport);
+    this.registerTool(explainTool, handleExplain);
+    this.registerTool(scaffoldTool, createScaffoldHandler(plugins ?? []));
+    this.registerTool(searchTool, createSearchHandler(plugins ?? []));
 
     // Register plugin contributions
     if (plugins) {

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

@@ -0,0 +1,134 @@
+import { resolve } from "path";
+import { discover } from "../../../discovery/index";
+
+/**
+ * Explain tool definition for MCP
+ */
+export const explainTool = {
+  name: "explain",
+  description: "Analyze a chant project directory and return a structured summary of all discovered entities",
+  inputSchema: {
+    type: "object" as const,
+    properties: {
+      path: {
+        type: "string",
+        description: "Path to the infrastructure directory to analyze",
+      },
+      format: {
+        type: "string",
+        enum: ["markdown", "json"],
+        description: "Output format (default: markdown)",
+      },
+    },
+    required: ["path"],
+  },
+};
+
+/**
+ * Handle explain tool invocation
+ */
+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 infraPath = resolve(path);
+  const result = await discover(infraPath);
+
+  // Group entities by lexicon and kind
+  const byLexicon = new Map<string, { resources: string[]; properties: string[] }>();
+
+  for (const [name, entity] of result.entities) {
+    const lexicon = entity.lexicon ?? "unknown";
+    if (!byLexicon.has(lexicon)) {
+      byLexicon.set(lexicon, { resources: [], properties: [] });
+    }
+    const group = byLexicon.get(lexicon)!;
+    if (entity.kind === "property") {
+      group.properties.push(name);
+    } else {
+      group.resources.push(name);
+    }
+  }
+
+  // Collect dependency info
+  const crossResourceDeps: Array<{ from: string; to: string }> = [];
+  for (const [from, deps] of result.dependencies) {
+    for (const to of deps) {
+      crossResourceDeps.push({ from, to });
+    }
+  }
+
+  const summary = {
+    sourceFiles: result.sourceFiles,
+    totalEntities: result.entities.size,
+    lexicons: Object.fromEntries(
+      Array.from(byLexicon.entries()).map(([lexicon, group]) => [
+        lexicon,
+        {
+          resourceCount: group.resources.length,
+          propertyCount: group.properties.length,
+          resources: group.resources,
+          properties: group.properties,
+        },
+      ]),
+    ),
+    dependencies: crossResourceDeps,
+    errors: result.errors.map((e) => e.message),
+  };
+
+  if (format === "json") {
+    return summary;
+  }
+
+  // Markdown format
+  const lines: string[] = [];
+  lines.push(`# Project Summary`);
+  lines.push("");
+  lines.push(`- **Source files:** ${result.sourceFiles.length}`);
+  lines.push(`- **Total entities:** ${result.entities.size}`);
+  lines.push("");
+
+  for (const [lexicon, group] of byLexicon) {
+    lines.push(`## Lexicon: ${lexicon}`);
+    lines.push("");
+    lines.push(`- Resources: ${group.resources.length}`);
+    lines.push(`- Properties: ${group.properties.length}`);
+    lines.push("");
+
+    if (group.resources.length > 0) {
+      lines.push("### Resources");
+      for (const name of group.resources) {
+        lines.push(`- \`${name}\``);
+      }
+      lines.push("");
+    }
+
+    if (group.properties.length > 0) {
+      lines.push("### Properties");
+      for (const name of group.properties) {
+        lines.push(`- \`${name}\``);
+      }
+      lines.push("");
+    }
+  }
+
+  if (crossResourceDeps.length > 0) {
+    lines.push("## Dependencies");
+    lines.push("");
+    for (const dep of crossResourceDeps) {
+      lines.push(`- \`${dep.from}\` → \`${dep.to}\``);
+    }
+    lines.push("");
+  }
+
+  if (result.errors.length > 0) {
+    lines.push("## Errors");
+    lines.push("");
+    for (const err of result.errors) {
+      lines.push(`- ${err.message}`);
+    }
+    lines.push("");
+  }
+
+  return lines.join("\n");
+}

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

@@ -0,0 +1,107 @@
+import type { LexiconPlugin } from "../../../lexicon";
+
+/**
+ * Scaffold tool definition for MCP
+ */
+export const scaffoldTool = {
+  name: "scaffold",
+  description: "Generate starter code for a common infrastructure pattern",
+  inputSchema: {
+    type: "object" as const,
+    properties: {
+      pattern: {
+        type: "string",
+        description: "Infrastructure pattern to scaffold (e.g. 's3-bucket', 'lambda', 'pipeline')",
+      },
+      lexicon: {
+        type: "string",
+        description: "Lexicon to use for scaffolding (e.g. 'aws', 'gitlab'). Auto-detected if omitted.",
+      },
+    },
+    required: ["pattern"],
+  },
+};
+
+/**
+ * Create a scaffold handler with access to loaded plugins
+ */
+export function createScaffoldHandler(
+  plugins: LexiconPlugin[],
+): (params: Record<string, unknown>) => Promise<unknown> {
+  return async (params) => {
+    const pattern = params.pattern as string;
+    const lexiconName = params.lexicon as string | undefined;
+
+    // Try to find a matching plugin
+    const candidates = lexiconName
+      ? plugins.filter((p) => p.name === lexiconName)
+      : plugins;
+
+    // Search plugin init templates for a pattern match
+    for (const plugin of candidates) {
+      const templates = plugin.initTemplates?.();
+      if (!templates) continue;
+
+      // Match template filenames against the pattern (case-insensitive substring)
+      const lowerPattern = pattern.toLowerCase();
+      const matched: Array<{ filename: string; content: string }> = [];
+
+      for (const [filename, content] of Object.entries(templates)) {
+        if (filename.toLowerCase().includes(lowerPattern)) {
+          matched.push({ filename, content });
+        }
+      }
+
+      if (matched.length > 0) {
+        return {
+          lexicon: plugin.name,
+          pattern,
+          files: matched,
+        };
+      }
+    }
+
+    // Fall back to a generic skeleton
+    const configContent = `/**
+ * Shared configuration for ${pattern}
+ */
+
+// TODO: Import resource types from your lexicon
+// import { ... } from "@intentius/chant-lexicon-<name>";
+
+export const config = {
+  // Add shared configuration here
+};
+`;
+
+    const resourceContent = `/**
+ * ${pattern} resource definition
+ */
+
+// TODO: Import resource types from your lexicon
+// import { ... } from "@intentius/chant-lexicon-<name>";
+// import { config } from "./config";
+
+// export const ${toCamelCase(pattern)} = new ResourceType({
+//   // Add properties here
+// });
+`;
+
+    return {
+      lexicon: lexiconName ?? null,
+      pattern,
+      files: [
+        { filename: "config.ts", content: configContent },
+        { filename: `${pattern}.ts`, content: resourceContent },
+      ],
+      note: "No lexicon-specific template found. Generic skeleton provided — fill in imports and resource types.",
+    };
+  };
+}
+
+function toCamelCase(s: string): string {
+  return s
+    .split(/[-_]/)
+    .map((part, i) => (i === 0 ? part : part.charAt(0).toUpperCase() + part.slice(1)))
+    .join("");
+}

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

@@ -0,0 +1,98 @@
+import type { LexiconPlugin } from "../../../lexicon";
+
+/**
+ * Search tool definition for MCP
+ */
+export const searchTool = {
+  name: "search",
+  description: "Search the resource catalog across loaded lexicons by keyword",
+  inputSchema: {
+    type: "object" as const,
+    properties: {
+      query: {
+        type: "string",
+        description: "Search query — matches against resource type, class name, and kind",
+      },
+      lexicon: {
+        type: "string",
+        description: "Filter results to a specific lexicon (e.g. 'aws', 'gitlab')",
+      },
+      limit: {
+        type: "number",
+        description: "Maximum number of results to return (default: 20)",
+      },
+    },
+    required: ["query"],
+  },
+};
+
+interface CatalogEntry {
+  className: string;
+  resourceType: string;
+  kind?: string;
+}
+
+/**
+ * Create a search handler with access to loaded plugins
+ */
+export function createSearchHandler(
+  plugins: LexiconPlugin[],
+): (params: Record<string, unknown>) => Promise<unknown> {
+  return async (params) => {
+    const query = params.query as string;
+    const lexiconFilter = params.lexicon as string | undefined;
+    const limit = (params.limit as number) ?? 20;
+
+    const lowerQuery = query.toLowerCase();
+    const results: Array<CatalogEntry & { lexicon: string; score: number }> = [];
+
+    const candidates = lexiconFilter
+      ? plugins.filter((p) => p.name === lexiconFilter)
+      : plugins;
+
+    for (const plugin of candidates) {
+      const resources = plugin.mcpResources?.() ?? [];
+      const catalog = resources.find((r) => r.uri === "resource-catalog");
+      if (!catalog) continue;
+
+      let entries: CatalogEntry[];
+      try {
+        const raw = await catalog.handler();
+        entries = JSON.parse(raw);
+      } catch {
+        continue;
+      }
+
+      for (const entry of entries) {
+        const fields = [
+          entry.resourceType?.toLowerCase() ?? "",
+          entry.className?.toLowerCase() ?? "",
+          entry.kind?.toLowerCase() ?? "",
+        ];
+
+        const match = fields.some((f) => f.includes(lowerQuery));
+        if (!match) continue;
+
+        // Score: prefix match on resourceType or className ranks higher
+        const isPrefix = fields.some((f) => f.startsWith(lowerQuery));
+        const score = isPrefix ? 1 : 0;
+
+        results.push({ ...entry, lexicon: plugin.name, score });
+      }
+    }
+
+    // Sort: prefix matches first, then alphabetical by resourceType
+    results.sort((a, b) => {
+      if (a.score !== b.score) return b.score - a.score;
+      return (a.resourceType ?? "").localeCompare(b.resourceType ?? "");
+    });
+
+    const limited = results.slice(0, limit);
+
+    return {
+      query,
+      total: results.length,
+      results: limited.map(({ score: _score, ...entry }) => entry),
+    };
+  };
+}

package/src/codegen/docs-interpolation.test.ts

@@ -12,7 +12,7 @@ describe("expandFileMarkers", () => {
     mkdirSync(join(dir, "sub"), { recursive: true });
     writeFileSync(
       join(dir, "example.ts"),
-      'import * as _ from "./_";\n\nexport const bucket = new _.Bucket({\n  bucketName: "test",\n});\n',
+      'import { Bucket } from "@intentius/chant-lexicon-aws";\n\nexport const bucket = new Bucket({\n  bucketName: "test",\n});\n',
     );
     writeFileSync(
       join(dir, "sub", "nested.ts"),
@@ -27,7 +27,7 @@ describe("expandFileMarkers", () => {
   test("expands full file marker", () => {
     const result = expandFileMarkers("Before\n\n{{file:example.ts}}\n\nAfter", dir);
     expect(result).toContain('```typescript title="example.ts"');
-    expect(result).toContain('import * as _ from "./_";');
+    expect(result).toContain('import { Bucket } from "@intentius/chant-lexicon-aws";');
     expect(result).toContain("```");
     expect(result).toStartWith("Before\n\n");
     expect(result).toEndWith("\n\nAfter");

package/src/codegen/docs.ts

@@ -190,10 +190,11 @@ export function docsPipeline(config: DocsConfig): DocsResult {
   // Generate pages
   const pages = new Map<string, string>();
 
-  pages.set(
-    "index.mdx",
-    generateOverview(config, manifest, resources, properties, serviceGroups, rules),
-  );
+  let overviewContent = generateOverview(config, manifest, resources, properties, serviceGroups, rules);
+  if (config.examplesDir) {
+    overviewContent = expandFileMarkers(overviewContent, config.examplesDir);
+  }
+  pages.set("index.mdx", overviewContent);
   const suppress = new Set(config.suppressPages ?? []);
 
   // Extra pages from lexicon config

package/src/codegen/generate-registry.test.ts

@@ -51,7 +51,7 @@ describe("buildRegistry", () => {
     const entries = buildRegistry(resources, naming, testConfig);
 
     expect(entries["Bucket"]).toBeDefined();
-    expect(entries["Bucket"].attrs).toEqual({ arn: "Arn", domainName: "DomainName" });
+    expect(entries["Bucket"].attrs).toEqual({ Arn: "Arn", DomainName: "DomainName" });
   });
 
   test("omits attrs when empty", () => {
@@ -69,7 +69,7 @@ describe("buildRegistry", () => {
         typeName: "Test::S3::Bucket",
         attributes: [],
         properties: [],
-        propertyTypes: [{ name: "Bucket_Versioning", cfnType: "Versioning" }],
+        propertyTypes: [{ name: "Bucket_Versioning", specType: "Versioning" }],
       },
     ];
     const naming = makeNaming(resources);