@intentius/chant 0.0.22 → 0.0.24

package/src/discovery/collect.ts

@@ -34,6 +34,18 @@ export function collectEntities(
         } else {
           entities.set(name, value);
         }
+      } else if (Array.isArray(value)) {
+        // Arrays of Declarables — each element gets an indexed name: exportName_0, exportName_1, ...
+        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(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}"`;
+}

package/src/toml-parse.ts

@@ -0,0 +1,370 @@
+/**
+ * TOML parser.
+ *
+ * Handles the TOML subset used by Chant lexicons: tables, arrays of tables,
+ * key-value pairs, inline tables, inline arrays, strings, numbers, booleans.
+ */
+
+import { unescapeString, stripInlineComment } from "./toml-utils";
+
+/**
+ * Parse a TOML document string into a plain object.
+ *
+ * Uses a built-in parser that handles the TOML subset used by Flyway
+ * configuration files.
+ */
+export function parseTOML(content: string): Record<string, unknown> {
+  const result: Record<string, unknown> = {};
+  const lines = content.split("\n");
+  let currentPath: string[] = [];
+  let isArrayOfTables = false;
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i].trim();
+
+    // Skip empty lines and comments
+    if (line === "" || line.startsWith("#")) continue;
+
+    // Array of tables: [[section.path]]
+    const aotMatch = line.match(/^\[\[([^\]]+)\]\]\s*(?:#.*)?$/);
+    if (aotMatch) {
+      currentPath = parseDottedKey(aotMatch[1].trim());
+      isArrayOfTables = true;
+      // Ensure the array exists and add a new entry
+      const arr = ensureArrayAt(result, currentPath);
+      arr.push({});
+      continue;
+    }
+
+    // Table header: [section.path]
+    const tableMatch = line.match(/^\[([^\]]+)\]\s*(?:#.*)?$/);
+    if (tableMatch) {
+      currentPath = parseDottedKey(tableMatch[1].trim());
+      isArrayOfTables = false;
+      ensureTableAt(result, currentPath);
+      continue;
+    }
+
+    // Key-value pair
+    const kvResult = parseKeyValue(line);
+    if (kvResult) {
+      const target = isArrayOfTables
+        ? getLastArrayEntry(result, currentPath)
+        : getTableAt(result, currentPath);
+      if (target) {
+        setNestedValue(target, kvResult.key, kvResult.value);
+      }
+      continue;
+    }
+  }
+
+  return result;
+}
+
+// ── Key-value parsing ─────────────────────────────────────────────
+
+interface KeyValueResult {
+  key: string[];
+  value: unknown;
+}
+
+/**
+ * Parse a key = value line.
+ */
+function parseKeyValue(line: string): KeyValueResult | null {
+  // Find the = sign (not inside quotes)
+  const eqIndex = findEquals(line);
+  if (eqIndex === -1) return null;
+
+  const rawKey = line.slice(0, eqIndex).trim();
+  const rawValue = line.slice(eqIndex + 1).trim();
+
+  const key = parseDottedKey(rawKey);
+  const value = parseTOMLValue(rawValue);
+
+  return { key, value };
+}
+
+/**
+ * Find the index of the first `=` not inside quotes.
+ */
+function findEquals(line: string): number {
+  let inSingleQuote = false;
+  let inDoubleQuote = false;
+
+  for (let i = 0; i < line.length; i++) {
+    const ch = line[i];
+    if (ch === "'" && !inDoubleQuote) {
+      inSingleQuote = !inSingleQuote;
+    } else if (ch === '"' && !inSingleQuote && (i === 0 || line[i - 1] !== "\\")) {
+      inDoubleQuote = !inDoubleQuote;
+    } else if (ch === "=" && !inSingleQuote && !inDoubleQuote) {
+      return i;
+    }
+  }
+  return -1;
+}
+
+/**
+ * Parse a dotted key like `flyway.placeholders.name` into path segments.
+ */
+function parseDottedKey(raw: string): string[] {
+  const parts: string[] = [];
+  let current = "";
+  let inQuote = false;
+  let quoteChar = "";
+
+  for (let i = 0; i < raw.length; i++) {
+    const ch = raw[i];
+    if (inQuote) {
+      if (ch === quoteChar) {
+        inQuote = false;
+      } else {
+        current += ch;
+      }
+    } else if (ch === '"' || ch === "'") {
+      inQuote = true;
+      quoteChar = ch;
+    } else if (ch === ".") {
+      parts.push(current.trim());
+      current = "";
+    } else {
+      current += ch;
+    }
+  }
+  if (current.trim()) parts.push(current.trim());
+  return parts;
+}
+
+// ── Value parsing ─────────────────────────────────────────────────
+
+/**
+ * Parse a TOML value string.
+ */
+function parseTOMLValue(raw: string): unknown {
+  // Strip inline comments (not inside strings)
+  const value = stripInlineComment(raw);
+
+  if (value === "true") return true;
+  if (value === "false") return false;
+
+  // String values
+  if (value.startsWith('"""')) {
+    const end = value.indexOf('"""', 3);
+    return end !== -1 ? value.slice(3, end) : value.slice(3);
+  }
+  if (value.startsWith("'''")) {
+    const end = value.indexOf("'''", 3);
+    return end !== -1 ? value.slice(3, end) : value.slice(3);
+  }
+  if (value.startsWith('"') && value.endsWith('"')) {
+    return unescapeString(value.slice(1, -1));
+  }
+  if (value.startsWith("'") && value.endsWith("'")) {
+    return value.slice(1, -1); // Literal string, no escaping
+  }
+
+  // Array
+  if (value.startsWith("[")) {
+    return parseTOMLArray(value);
+  }
+
+  // Inline table
+  if (value.startsWith("{")) {
+    return parseTOMLInlineTable(value);
+  }
+
+  // Number
+  const num = Number(value);
+  if (!isNaN(num) && value !== "") return num;
+
+  // Bare string / date (return as string)
+  return value;
+}
+
+/**
+ * Parse a TOML inline array.
+ */
+function parseTOMLArray(raw: string): unknown[] {
+  // Remove outer brackets
+  const inner = raw.slice(1, raw.lastIndexOf("]")).trim();
+  if (inner === "") return [];
+
+  const items: unknown[] = [];
+  let current = "";
+  let depth = 0;
+  let inString = false;
+  let stringChar = "";
+
+  for (let i = 0; i < inner.length; i++) {
+    const ch = inner[i];
+    if (inString) {
+      current += ch;
+      if (ch === stringChar && inner[i - 1] !== "\\") {
+        inString = false;
+      }
+    } else if (ch === '"' || ch === "'") {
+      inString = true;
+      stringChar = ch;
+      current += ch;
+    } else if (ch === "[" || ch === "{") {
+      depth++;
+      current += ch;
+    } else if (ch === "]" || ch === "}") {
+      depth--;
+      current += ch;
+    } else if (ch === "," && depth === 0) {
+      const trimmed = current.trim();
+      if (trimmed !== "") items.push(parseTOMLValue(trimmed));
+      current = "";
+    } else {
+      current += ch;
+    }
+  }
+
+  const trimmed = current.trim();
+  if (trimmed !== "") items.push(parseTOMLValue(trimmed));
+
+  return items;
+}
+
+/**
+ * Parse a TOML inline table.
+ */
+function parseTOMLInlineTable(raw: string): Record<string, unknown> {
+  const inner = raw.slice(1, raw.lastIndexOf("}")).trim();
+  if (inner === "") return {};
+
+  const result: Record<string, unknown> = {};
+  let current = "";
+  let depth = 0;
+  let inString = false;
+  let stringChar = "";
+
+  for (let i = 0; i < inner.length; i++) {
+    const ch = inner[i];
+    if (inString) {
+      current += ch;
+      if (ch === stringChar && inner[i - 1] !== "\\") {
+        inString = false;
+      }
+    } else if (ch === '"' || ch === "'") {
+      inString = true;
+      stringChar = ch;
+      current += ch;
+    } else if (ch === "[" || ch === "{") {
+      depth++;
+      current += ch;
+    } else if (ch === "]" || ch === "}") {
+      depth--;
+      current += ch;
+    } else if (ch === "," && depth === 0) {
+      parseInlineTableEntry(current.trim(), result);
+      current = "";
+    } else {
+      current += ch;
+    }
+  }
+
+  if (current.trim()) parseInlineTableEntry(current.trim(), result);
+  return result;
+}
+
+function parseInlineTableEntry(entry: string, target: Record<string, unknown>): void {
+  const kv = parseKeyValue(entry);
+  if (kv) {
+    setNestedValue(target, kv.key, kv.value);
+  }
+}
+
+// ── Object path helpers ───────────────────────────────────────────
+
+function ensureTableAt(root: Record<string, unknown>, path: string[]): Record<string, unknown> {
+  let current = root;
+  for (const segment of path) {
+    if (!(segment in current)) {
+      current[segment] = {};
+    }
+    const next = current[segment];
+    if (Array.isArray(next)) {
+      // Navigate into last array entry
+      current = next[next.length - 1] as Record<string, unknown>;
+    } else if (typeof next === "object" && next !== null) {
+      current = next as Record<string, unknown>;
+    } else {
+      const obj: Record<string, unknown> = {};
+      current[segment] = obj;
+      current = obj;
+    }
+  }
+  return current;
+}
+
+function ensureArrayAt(root: Record<string, unknown>, path: string[]): unknown[] {
+  let current = root;
+  for (let i = 0; i < path.length - 1; i++) {
+    const segment = path[i];
+    if (!(segment in current)) {
+      current[segment] = {};
+    }
+    const next = current[segment];
+    if (Array.isArray(next)) {
+      current = next[next.length - 1] as Record<string, unknown>;
+    } else if (typeof next === "object" && next !== null) {
+      current = next as Record<string, unknown>;
+    }
+  }
+
+  const lastKey = path[path.length - 1];
+  if (!(lastKey in current) || !Array.isArray(current[lastKey])) {
+    current[lastKey] = [];
+  }
+  return current[lastKey] as unknown[];
+}
+
+function getTableAt(root: Record<string, unknown>, path: string[]): Record<string, unknown> {
+  let current = root;
+  for (const segment of path) {
+    const next = current[segment];
+    if (Array.isArray(next)) {
+      current = next[next.length - 1] as Record<string, unknown>;
+    } else if (typeof next === "object" && next !== null) {
+      current = next as Record<string, unknown>;
+    } else {
+      return current;
+    }
+  }
+  return current;
+}
+
+function getLastArrayEntry(root: Record<string, unknown>, path: string[]): Record<string, unknown> | null {
+  let current = root;
+  for (let i = 0; i < path.length - 1; i++) {
+    const next = current[path[i]];
+    if (Array.isArray(next)) {
+      current = next[next.length - 1] as Record<string, unknown>;
+    } else if (typeof next === "object" && next !== null) {
+      current = next as Record<string, unknown>;
+    } else {
+      return null;
+    }
+  }
+
+  const lastKey = path[path.length - 1];
+  const arr = current[lastKey];
+  if (Array.isArray(arr) && arr.length > 0) {
+    return arr[arr.length - 1] as Record<string, unknown>;
+  }
+  return null;
+}
+
+function setNestedValue(target: Record<string, unknown>, key: string[], value: unknown): void {
+  let current = target;
+  for (let i = 0; i < key.length - 1; i++) {
+    if (!(key[i] in current)) {
+      current[key[i]] = {};
+    }
+    current = current[key[i]] as Record<string, unknown>;
+  }
+  current[key[key.length - 1]] = value;
+}