@intentius/chant 0.0.22 → 0.1.0

package/src/discovery/collect.test.ts

@@ -54,6 +54,40 @@ describe("collectEntities", () => {
     expect(result.get("entity3")).toBe(entity3);
   });
 
+  test("collects arrays of declarable entities with indexed names", () => {
+    const e0 = createMockEntity("type");
+    const e1 = createMockEntity("type");
+    const e2 = createMockEntity("type");
+
+    const modules = [
+      {
+        file: "test.ts",
+        exports: { myResources: [e0, e1, e2] },
+      },
+    ];
+
+    const result = collectEntities(modules);
+    expect(result.size).toBe(3);
+    expect(result.get("myResources_0")).toBe(e0);
+    expect(result.get("myResources_1")).toBe(e1);
+    expect(result.get("myResources_2")).toBe(e2);
+  });
+
+  test("ignores non-declarable items within arrays", () => {
+    const e0 = createMockEntity("type");
+
+    const modules = [
+      {
+        file: "test.ts",
+        exports: { mixed: [e0, "string", 42, null] },
+      },
+    ];
+
+    const result = collectEntities(modules);
+    expect(result.size).toBe(1);
+    expect(result.get("mixed_0")).toBe(e0);
+  });
+
   test("ignores non-declarable exports", () => {
     const entity = createMockEntity("test");
 

package/src/discovery/collect.ts

@@ -34,6 +34,31 @@ export function collectEntities(
         } else {
           entities.set(name, value);
         }
+      } else if (Array.isArray(value)) {
+        // Arrays of Declarables or CompositeInstances — each element gets an indexed name: exportName_0, ...
+        for (let i = 0; i < value.length; i++) {
+          const item = value[i];
+          if (isDeclarable(item)) {
+            const indexedName = `${name}_${i}`;
+            if (entities.has(indexedName) && entities.get(indexedName) !== item) {
+              throw new DiscoveryError(file, `Duplicate entity name "${indexedName}"`, "resolution");
+            }
+            entities.set(indexedName, item);
+          } else if (isCompositeInstance(item)) {
+            const indexedName = `${name}_${i}`;
+            const expanded = expandComposite(indexedName, item);
+            for (const [expandedName, entity] of expanded) {
+              if (entities.has(expandedName)) {
+                throw new DiscoveryError(
+                  file,
+                  `Duplicate entity name "${expandedName}" from composite expansion of "${indexedName}"`,
+                  "resolution",
+                );
+              }
+              entities.set(expandedName, entity);
+            }
+          }
+        }
       } else if (isCompositeInstance(value)) {
         const expanded = expandComposite(name, value);
         for (const [expandedName, entity] of expanded) {

package/src/lexicon-plugin-helpers.ts

@@ -0,0 +1,130 @@
+/**
+ * Shared helpers for lexicon plugin implementations.
+ *
+ * Eliminates boilerplate across the 8 lexicon plugins by providing
+ * factory functions for common plugin methods: skills loading,
+ * MCP diff tool, and MCP catalog resource.
+ */
+
+import { readFileSync } from "fs";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+import type { SkillDefinition } from "./lexicon";
+import type { McpToolContribution, McpResourceContribution } from "./mcp/types";
+import type { Serializer } from "./serializer";
+
+// ── Skills Loader ─────────────────────────────────────────────────
+
+/**
+ * Metadata for a skill file on disk. Spread into the resulting SkillDefinition
+ * after the file content is read.
+ */
+export type SkillFileSpec = Omit<SkillDefinition, "content"> & {
+  /** Filename relative to the skills directory (e.g. "chant-aws.md") */
+  file: string;
+};
+
+/**
+ * Create a skills loader that reads .md files from a lexicon's skills directory.
+ *
+ * Usage in a plugin:
+ * ```ts
+ * import { createSkillsLoader } from "@intentius/chant/lexicon-plugin-helpers";
+ *
+ * const loadSkills = createSkillsLoader(import.meta.url, [
+ *   { file: "chant-aws.md", name: "chant-aws", description: "..." },
+ * ]);
+ *
+ * // In plugin:
+ * skills() { return loadSkills(); }
+ * ```
+ */
+export function createSkillsLoader(
+  importMetaUrl: string,
+  specs: SkillFileSpec[],
+): () => SkillDefinition[] {
+  return () => {
+    const skillsDir = join(dirname(fileURLToPath(importMetaUrl)), "skills");
+    return specs.map(({ file, ...meta }) => {
+      try {
+        const content = readFileSync(join(skillsDir, file), "utf-8");
+        return { ...meta, content };
+      } catch {
+        return { ...meta, content: "" };
+      }
+    });
+  };
+}
+
+// ── MCP Diff Tool ─────────────────────────────────────────────────
+
+/**
+ * Create an MCP diff tool contribution for a lexicon.
+ *
+ * All lexicons (except Azure) expose an identical "diff" tool that compares
+ * current build output against previous output using the lexicon's serializer.
+ */
+export function createDiffTool(
+  serializer: Serializer,
+  description: string,
+): McpToolContribution {
+  return {
+    name: "diff",
+    description,
+    inputSchema: {
+      type: "object" as const,
+      properties: {
+        path: {
+          type: "string",
+          description: "Path to the infrastructure project directory",
+        },
+      },
+    },
+    async handler(params: Record<string, unknown>): Promise<unknown> {
+      const { diffCommand } = await import("./cli/commands/diff");
+      const result = await diffCommand({
+        path: (params.path as string) ?? ".",
+        serializers: [serializer],
+      });
+      return result;
+    },
+  };
+}
+
+// ── MCP Catalog Resource ──────────────────────────────────────────
+
+/**
+ * Create an MCP resource that serves the lexicon's meta.json as a catalog.
+ *
+ * Most lexicons expose a "resource-catalog" resource with identical structure.
+ *
+ * @param importMetaUrl — The plugin's import.meta.url (used to locate generated JSON)
+ * @param name — Display name (e.g. "AWS Resource Catalog")
+ * @param description — Resource description
+ * @param lexiconJsonFile — Filename of the generated lexicon JSON (e.g. "lexicon-aws.json")
+ */
+export function createCatalogResource(
+  importMetaUrl: string,
+  name: string,
+  description: string,
+  lexiconJsonFile: string,
+): McpResourceContribution {
+  return {
+    uri: "resource-catalog",
+    name,
+    description,
+    mimeType: "application/json",
+    async handler(): Promise<string> {
+      const dir = dirname(fileURLToPath(importMetaUrl));
+      const lexicon = JSON.parse(
+        readFileSync(join(dir, "generated", lexiconJsonFile), "utf-8"),
+      ) as Record<string, { resourceType: string; kind: string }>;
+      const entries = Object.entries(lexicon).map(([className, entry]) => ({
+        className,
+        resourceType: entry.resourceType,
+        kind: entry.kind,
+      }));
+      return JSON.stringify(entries);
+    },
+  };
+}

package/src/toml-emit.ts

@@ -0,0 +1,182 @@
+/**
+ * TOML emitter.
+ *
+ * Converts JavaScript objects to TOML document strings.
+ * Handles scalars, tables, arrays, array of tables, and inline tables.
+ */
+
+import { escapeKey, sortKeys } from "./toml-utils";
+
+export interface EmitTOMLOptions {
+  /** Comment to prepend at the top of the document. */
+  header?: string;
+  /** Key ordering hint: keys matching earlier entries appear first. */
+  keyOrder?: string[];
+}
+
+/**
+ * Emit a JavaScript object as a TOML document string.
+ *
+ * - Top-level scalars, arrays of scalars → bare key-value pairs.
+ * - Nested objects → `[section]` tables.
+ * - Arrays of objects → `[[section]]` array of tables.
+ * - Deeply nested objects → `[parent.child]` dotted sections.
+ */
+export function emitTOML(value: unknown, options?: EmitTOMLOptions): string {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throw new Error("emitTOML expects a plain object at the top level");
+  }
+
+  const lines: string[] = [];
+
+  if (options?.header) {
+    for (const line of options.header.split("\n")) {
+      lines.push(`# ${line}`);
+    }
+    lines.push("");
+  }
+
+  const obj = value as Record<string, unknown>;
+  emitTable(obj, [], lines, options?.keyOrder);
+
+  // Trim trailing blank lines, ensure single trailing newline
+  while (lines.length > 0 && lines[lines.length - 1] === "") {
+    lines.pop();
+  }
+  return lines.join("\n") + "\n";
+}
+
+/**
+ * Emit a TOML table (recursively handles nested tables and array of tables).
+ */
+function emitTable(
+  obj: Record<string, unknown>,
+  path: string[],
+  lines: string[],
+  keyOrder?: string[],
+): void {
+  const keys = sortKeys(Object.keys(obj), keyOrder);
+
+  // First pass: emit all scalar / inline values
+  for (const key of keys) {
+    const val = obj[key];
+    if (val === undefined) continue;
+    if (isTableValue(val)) continue; // handled in second pass
+    if (isArrayOfTables(val)) continue; // handled in second pass
+
+    lines.push(`${escapeKey(key)} = ${emitValue(val)}`);
+  }
+
+  // Second pass: emit nested tables
+  for (const key of keys) {
+    const val = obj[key];
+    if (val === undefined) continue;
+
+    if (isArrayOfTables(val)) {
+      const arr = val as Record<string, unknown>[];
+      for (const item of arr) {
+        lines.push("");
+        const sectionPath = [...path, key];
+        lines.push(`[[${sectionPath.map(escapeKey).join(".")}]]`);
+        emitTable(item, sectionPath, lines, keyOrder);
+      }
+    } else if (isTableValue(val)) {
+      lines.push("");
+      const sectionPath = [...path, key];
+      lines.push(`[${sectionPath.map(escapeKey).join(".")}]`);
+      emitTable(val as Record<string, unknown>, sectionPath, lines, keyOrder);
+    }
+  }
+}
+
+/**
+ * Check if a value should be emitted as a `[table]` section.
+ */
+function isTableValue(val: unknown): val is Record<string, unknown> {
+  return (
+    typeof val === "object" &&
+    val !== null &&
+    !Array.isArray(val) &&
+    !(val instanceof Date)
+  );
+}
+
+/**
+ * Check if a value is an array of tables (`[[section]]`).
+ */
+function isArrayOfTables(val: unknown): boolean {
+  if (!Array.isArray(val) || val.length === 0) return false;
+  return val.every(
+    (item) => typeof item === "object" && item !== null && !Array.isArray(item) && !(item instanceof Date),
+  );
+}
+
+/**
+ * Emit a TOML value (scalar, array of scalars, inline table).
+ */
+function emitValue(val: unknown): string {
+  if (val === null || val === undefined) {
+    return '""'; // TOML has no null — emit empty string
+  }
+
+  if (typeof val === "boolean") {
+    return val ? "true" : "false";
+  }
+
+  if (typeof val === "number") {
+    if (Number.isInteger(val)) return String(val);
+    return String(val);
+  }
+
+  if (typeof val === "string") {
+    return emitString(val);
+  }
+
+  if (val instanceof Date) {
+    return val.toISOString();
+  }
+
+  if (Array.isArray(val)) {
+    if (val.length === 0) return "[]";
+    // Array of scalars → inline array
+    const items = val.map((item) => emitValue(item));
+    const inline = `[${items.join(", ")}]`;
+    if (inline.length <= 80) return inline;
+    // Multi-line array for long content
+    const multiLines = val.map((item) => `  ${emitValue(item)},`);
+    return "[\n" + multiLines.join("\n") + "\n]";
+  }
+
+  // Inline table for non-table contexts (shouldn't normally reach here
+  // because isTableValue is checked first, but handles edge cases)
+  if (typeof val === "object") {
+    const entries = Object.entries(val as Record<string, unknown>);
+    if (entries.length === 0) return "{}";
+    const pairs = entries.map(([k, v]) => `${escapeKey(k)} = ${emitValue(v)}`);
+    return `{ ${pairs.join(", ")} }`;
+  }
+
+  return String(val);
+}
+
+/**
+ * Emit a TOML string with proper quoting.
+ */
+function emitString(val: string): string {
+  // Use basic strings with escaping for most values
+  if (val.includes("\n") || val.includes("\r")) {
+    // Multi-line basic string
+    const escaped = val
+      .replace(/\\/g, "\\\\")
+      .replace(/"""/g, '\\"""');
+    return `"""\n${escaped}"""`;
+  }
+
+  // Regular basic string
+  const escaped = val
+    .replace(/\\/g, "\\\\")
+    .replace(/"/g, '\\"')
+    .replace(/\t/g, "\\t")
+    .replace(/\r/g, "\\r");
+  return `"${escaped}"`;
+}