@intentius/chant 0.0.18 → 0.0.24

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,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/discovery/graph.test.ts

@@ -12,6 +12,7 @@ describe("buildDependencyGraph", () => {
 
   test("returns graph with no dependencies for single entity", () => {
     const entity: Declarable = {
+      lexicon: "test",
       entityType: "test",
       [DECLARABLE_MARKER]: true,
     };
@@ -25,11 +26,13 @@ describe("buildDependencyGraph", () => {
 
   test("returns graph with no dependencies for multiple unrelated entities", () => {
     const entity1: Declarable = {
+      lexicon: "test",
       entityType: "test",
       [DECLARABLE_MARKER]: true,
     };
 
     const entity2: Declarable = {
+      lexicon: "test",
       entityType: "test",
       [DECLARABLE_MARKER]: true,
     };
@@ -47,11 +50,13 @@ describe("buildDependencyGraph", () => {
 
   test("detects dependency from AttrRef", () => {
     const parent: Declarable = {
+      lexicon: "test",
       entityType: "parent",
       [DECLARABLE_MARKER]: true,
     };
 
     const child: Declarable & { ref: AttrRef } = {
+      lexicon: "test",
       entityType: "child",
       [DECLARABLE_MARKER]: true,
       ref: new AttrRef(parent, "someAttr"),
@@ -71,11 +76,13 @@ describe("buildDependencyGraph", () => {
 
   test("detects dependency from direct Declarable reference", () => {
     const entity1: Declarable = {
+      lexicon: "test",
       entityType: "type1",
       [DECLARABLE_MARKER]: true,
     };
 
     const entity2: Declarable & { dependency: Declarable } = {
+      lexicon: "test",
       entityType: "type2",
       [DECLARABLE_MARKER]: true,
       dependency: entity1,
@@ -95,16 +102,19 @@ describe("buildDependencyGraph", () => {
 
   test("detects multiple dependencies from one entity", () => {
     const entity1: Declarable = {
+      lexicon: "test",
       entityType: "type1",
       [DECLARABLE_MARKER]: true,
     };
 
     const entity2: Declarable = {
+      lexicon: "test",
       entityType: "type2",
       [DECLARABLE_MARKER]: true,
     };
 
     const entity3: Declarable & { dep1: Declarable; dep2: Declarable } = {
+      lexicon: "test",
       entityType: "type3",
       [DECLARABLE_MARKER]: true,
       dep1: entity1,
@@ -126,11 +136,13 @@ describe("buildDependencyGraph", () => {
 
   test("detects dependencies in nested objects", () => {
     const entity1: Declarable = {
+      lexicon: "test",
       entityType: "type1",
       [DECLARABLE_MARKER]: true,
     };
 
     const entity2: Declarable & { nested: { deep: Declarable } } = {
+      lexicon: "test",
       entityType: "type2",
       [DECLARABLE_MARKER]: true,
       nested: {
@@ -150,16 +162,19 @@ describe("buildDependencyGraph", () => {
 
   test("detects dependencies in arrays", () => {
     const entity1: Declarable = {
+      lexicon: "test",
       entityType: "type1",
       [DECLARABLE_MARKER]: true,
     };
 
     const entity2: Declarable = {
+      lexicon: "test",
       entityType: "type2",
       [DECLARABLE_MARKER]: true,
     };
 
     const entity3: Declarable & { deps: Declarable[] } = {
+      lexicon: "test",
       entityType: "type3",
       [DECLARABLE_MARKER]: true,
       deps: [entity1, entity2],
@@ -179,16 +194,19 @@ describe("buildDependencyGraph", () => {
 
   test("detects mixed AttrRef and Declarable dependencies", () => {
     const entity1: Declarable = {
+      lexicon: "test",
       entityType: "type1",
       [DECLARABLE_MARKER]: true,
     };
 
     const entity2: Declarable = {
+      lexicon: "test",
       entityType: "type2",
       [DECLARABLE_MARKER]: true,
     };
 
     const entity3: Declarable & { ref: AttrRef; dep: Declarable } = {
+      lexicon: "test",
       entityType: "type3",
       [DECLARABLE_MARKER]: true,
       ref: new AttrRef(entity1, "attr"),
@@ -209,17 +227,20 @@ describe("buildDependencyGraph", () => {
 
   test("handles transitive dependencies correctly", () => {
     const entity1: Declarable = {
+      lexicon: "test",
       entityType: "type1",
       [DECLARABLE_MARKER]: true,
     };
 
     const entity2: Declarable & { dep: Declarable } = {
+      lexicon: "test",
       entityType: "type2",
       [DECLARABLE_MARKER]: true,
       dep: entity1,
     };
 
     const entity3: Declarable & { dep: Declarable } = {
+      lexicon: "test",
       entityType: "type3",
       [DECLARABLE_MARKER]: true,
       dep: entity2,
@@ -241,16 +262,19 @@ describe("buildDependencyGraph", () => {
 
   test("ignores non-entity declarables", () => {
     const entity: Declarable = {
+      lexicon: "test",
       entityType: "test",
       [DECLARABLE_MARKER]: true,
     };
 
     const notInEntities: Declarable = {
+      lexicon: "test",
       entityType: "external",
       [DECLARABLE_MARKER]: true,
     };
 
     const entityWithExternal: Declarable & { dep: Declarable } = {
+      lexicon: "test",
       entityType: "test",
       [DECLARABLE_MARKER]: true,
       dep: notInEntities,
@@ -267,11 +291,13 @@ describe("buildDependencyGraph", () => {
 
   test("ignores AttrRef with parent not in entities", () => {
     const externalParent: Declarable = {
+      lexicon: "test",
       entityType: "external",
       [DECLARABLE_MARKER]: true,
     };
 
     const entity: Declarable & { ref: AttrRef } = {
+      lexicon: "test",
       entityType: "test",
       [DECLARABLE_MARKER]: true,
       ref: new AttrRef(externalParent, "attr"),
@@ -285,11 +311,13 @@ describe("buildDependencyGraph", () => {
 
   test("handles circular references without infinite loop", () => {
     const entity1: Declarable & { other?: Declarable } = {
+      lexicon: "test",
       entityType: "type1",
       [DECLARABLE_MARKER]: true,
     };
 
     const entity2: Declarable & { other: Declarable } = {
+      lexicon: "test",
       entityType: "type2",
       [DECLARABLE_MARKER]: true,
       other: entity1,
@@ -309,6 +337,7 @@ describe("buildDependencyGraph", () => {
 
   test("handles self-reference without infinite loop", () => {
     const entity: Declarable & { self?: Declarable } = {
+      lexicon: "test",
       entityType: "test",
       [DECLARABLE_MARKER]: true,
     };
@@ -329,6 +358,7 @@ describe("buildDependencyGraph", () => {
       bool: boolean;
       nul: null;
     } = {
+      lexicon: "test",
       entityType: "test",
       [DECLARABLE_MARKER]: true,
       str: "value",
@@ -348,6 +378,7 @@ describe("buildDependencyGraph", () => {
     // parent is the resource itself (e.g. bucket.arn, bucket.bucketName).
     // These are not real dependencies — they're just attribute accessors.
     const resource: Declarable & { arn?: AttrRef; bucketName?: AttrRef } = {
+      lexicon: "test",
       entityType: "AWS::S3::Bucket",
       [DECLARABLE_MARKER]: true,
     };
@@ -364,6 +395,7 @@ describe("buildDependencyGraph", () => {
     // A resource has its own AttrRefs (self-pointing) AND a property that
     // references a different entity. Only the cross-resource dep should appear.
     const defaults: Declarable = {
+      lexicon: "test",
       entityType: "AWS::S3::VersioningConfiguration",
       [DECLARABLE_MARKER]: true,
     };
@@ -372,6 +404,7 @@ describe("buildDependencyGraph", () => {
       arn?: AttrRef;
       versioningConfiguration?: Declarable;
     } = {
+      lexicon: "test",
       entityType: "AWS::S3::Bucket",
       [DECLARABLE_MARKER]: true,
     };
@@ -391,6 +424,7 @@ describe("buildDependencyGraph", () => {
 
   test("ignores plain objects without markers", () => {
     const entity: Declarable & { data: { key: string } } = {
+      lexicon: "test",
       entityType: "test",
       [DECLARABLE_MARKER]: true,
       data: { key: "value" },
@@ -404,6 +438,7 @@ describe("buildDependencyGraph", () => {
 
   test("handles AttrRef with garbage collected parent gracefully", () => {
     const entity: Declarable & { ref: AttrRef } = {
+      lexicon: "test",
       entityType: "test",
       [DECLARABLE_MARKER]: true,
       ref: new AttrRef({}, "attr"), // Using plain object that will be GC'd
@@ -418,6 +453,7 @@ describe("buildDependencyGraph", () => {
 
   test("detects dependencies deeply nested in arrays and objects", () => {
     const entity1: Declarable = {
+      lexicon: "test",
       entityType: "type1",
       [DECLARABLE_MARKER]: true,
     };
@@ -425,6 +461,7 @@ describe("buildDependencyGraph", () => {
     const entity2: Declarable & {
       complex: { nested: { array: Array<{ item: Declarable }> } };
     } = {
+      lexicon: "test",
       entityType: "type2",
       [DECLARABLE_MARKER]: true,
       complex: {
@@ -446,17 +483,20 @@ describe("buildDependencyGraph", () => {
 
   test("does not traverse into referenced declarables", () => {
     const entity1: Declarable = {
+      lexicon: "test",
       entityType: "type1",
       [DECLARABLE_MARKER]: true,
     };
 
     const entity2: Declarable & { internal: { data: string } } = {
+      lexicon: "test",
       entityType: "type2",
       [DECLARABLE_MARKER]: true,
       internal: { data: "should not traverse this" },
     };
 
     const entity3: Declarable & { dep: Declarable } = {
+      lexicon: "test",
       entityType: "type3",
       [DECLARABLE_MARKER]: true,
       dep: entity2,

package/src/discovery/import.test.ts

@@ -28,8 +28,8 @@ describe("importModule", () => {
 
       const module = await importModule(filePath);
       expect(module.default).toBeDefined();
-      expect(module.default.name).toBe("test");
-      expect(module.default.value).toBe(123);
+      expect((module.default as any).name).toBe("test");
+      expect((module.default as any).value).toBe(123);
     });
   });
 
@@ -125,7 +125,7 @@ describe("importModule", () => {
 
       const module = await importModule(filePath);
       expect(module.MyClass).toBeDefined();
-      const instance = new module.MyClass(100);
+      const instance = new (module.MyClass as any)(100);
       expect(instance.getValue()).toBe(100);
     });
   });
@@ -142,8 +142,8 @@ describe("importModule", () => {
       const module = await importModule(filePath);
       expect(module.add).toBeInstanceOf(Function);
       expect(module.multiply).toBeInstanceOf(Function);
-      expect(module.add(2, 3)).toBe(5);
-      expect(module.multiply(4, 5)).toBe(20);
+      expect((module.add as Function)(2, 3)).toBe(5);
+      expect((module.multiply as Function)(4, 5)).toBe(20);
     });
   });
 

package/src/discovery/resolve.test.ts

@@ -8,11 +8,13 @@ import { LOGICAL_NAME_SYMBOL, getLogicalName } from "../utils";
 describe("resolveAttrRefs", () => {
   test("sets logical names on all entities", () => {
     const entity1: Declarable = {
+      lexicon: "test",
       entityType: "Test1",
       [DECLARABLE_MARKER]: true,
     };
 
     const entity2: Declarable = {
+      lexicon: "test",
       entityType: "Test2",
       [DECLARABLE_MARKER]: true,
     };
@@ -30,11 +32,13 @@ describe("resolveAttrRefs", () => {
 
   test("resolves AttrRef with parent in entities collection", () => {
     const parent: Declarable = {
+      lexicon: "test",
       entityType: "Parent",
       [DECLARABLE_MARKER]: true,
     };
 
     const child: Declarable & { ref: AttrRef } = {
+      lexicon: "test",
       entityType: "Child",
       [DECLARABLE_MARKER]: true,
       ref: new AttrRef(parent, "Arn"),
@@ -55,11 +59,13 @@ describe("resolveAttrRefs", () => {
 
   test("resolves multiple AttrRefs on same entity", () => {
     const parent: Declarable = {
+      lexicon: "test",
       entityType: "Parent",
       [DECLARABLE_MARKER]: true,
     };
 
     const child: Declarable & { arn: AttrRef; name: AttrRef } = {
+      lexicon: "test",
       entityType: "Child",
       [DECLARABLE_MARKER]: true,
       arn: new AttrRef(parent, "Arn"),
@@ -83,16 +89,19 @@ describe("resolveAttrRefs", () => {
 
   test("resolves AttrRefs with different parents", () => {
     const parent1: Declarable = {
+      lexicon: "test",
       entityType: "Parent1",
       [DECLARABLE_MARKER]: true,
     };
 
     const parent2: Declarable = {
+      lexicon: "test",
       entityType: "Parent2",
       [DECLARABLE_MARKER]: true,
     };
 
     const child: Declarable & { ref1: AttrRef; ref2: AttrRef } = {
+      lexicon: "test",
       entityType: "Child",
       [DECLARABLE_MARKER]: true,
       ref1: new AttrRef(parent1, "Arn"),
@@ -119,6 +128,7 @@ describe("resolveAttrRefs", () => {
     const parent = {}; // Not a Declarable, not in entities
 
     const child: Declarable & { ref: AttrRef } = {
+      lexicon: "test",
       entityType: "Child",
       [DECLARABLE_MARKER]: true,
       ref: new AttrRef(parent, "Arn"),
@@ -133,11 +143,13 @@ describe("resolveAttrRefs", () => {
 
   test("handles entities with no AttrRefs", () => {
     const entity1: Declarable = {
+      lexicon: "test",
       entityType: "Test1",
       [DECLARABLE_MARKER]: true,
     };
 
     const entity2: Declarable & { prop: string } = {
+      lexicon: "test",
       entityType: "Test2",
       [DECLARABLE_MARKER]: true,
       prop: "value",
@@ -162,17 +174,20 @@ describe("resolveAttrRefs", () => {
 
   test("resolves chain of entities with AttrRefs", () => {
     const root: Declarable = {
+      lexicon: "test",
       entityType: "Root",
       [DECLARABLE_MARKER]: true,
     };
 
     const middle: Declarable & { rootRef: AttrRef } = {
+      lexicon: "test",
       entityType: "Middle",
       [DECLARABLE_MARKER]: true,
       rootRef: new AttrRef(root, "Id"),
     };
 
     const leaf: Declarable & { middleRef: AttrRef } = {
+      lexicon: "test",
       entityType: "Leaf",
       [DECLARABLE_MARKER]: true,
       middleRef: new AttrRef(middle, "Name"),
@@ -196,6 +211,7 @@ describe("resolveAttrRefs", () => {
 
   test("handles entity referencing itself", () => {
     const entity: Declarable & { selfRef: AttrRef } = {
+      lexicon: "test",
       entityType: "SelfReferencing",
       [DECLARABLE_MARKER]: true,
       selfRef: null as unknown as AttrRef, // Will be set below
@@ -214,6 +230,7 @@ describe("resolveAttrRefs", () => {
 
   test("preserves logical name symbol on entities", () => {
     const entity: Declarable = {
+      lexicon: "test",
       entityType: "Test",
       [DECLARABLE_MARKER]: true,
     };
@@ -228,6 +245,7 @@ describe("resolveAttrRefs", () => {
 
   test("uses export name as logical name", () => {
     const entity: Declarable = {
+      lexicon: "test",
       entityType: "Test",
       [DECLARABLE_MARKER]: true,
     };
@@ -243,11 +261,13 @@ describe("resolveAttrRefs", () => {
 
   test("handles complex attribute names in AttrRef", () => {
     const parent: Declarable = {
+      lexicon: "test",
       entityType: "Parent",
       [DECLARABLE_MARKER]: true,
     };
 
     const child: Declarable & { ref: AttrRef } = {
+      lexicon: "test",
       entityType: "Child",
       [DECLARABLE_MARKER]: true,
       ref: new AttrRef(parent, "Outputs.WebsiteURL"),

package/src/discovery/resolve.ts

@@ -1,6 +1,6 @@
 import type { Declarable } from "../declarable";
 import { AttrRef } from "../attrref";
-import { LOGICAL_NAME_SYMBOL, getAttributes } from "../utils";
+import { LOGICAL_NAME_SYMBOL, getAttributes, isAttrRefLike } from "../utils";
 
 /**
  * Resolves all AttrRef instances in a collection of entities
@@ -22,7 +22,7 @@ export function resolveAttrRefs(entities: Map<string, Declarable>): void {
     for (const attrName of attributes) {
       const attrRef = (entity as unknown as Record<string, unknown>)[attrName];
 
-      if (attrRef instanceof AttrRef) {
+      if (isAttrRefLike(attrRef)) {
         const parent = attrRef.parent.deref();
 
         if (!parent) {

package/src/index.ts

@@ -59,3 +59,5 @@ export * from "./child-project";
 export * from "./lsp/types";
 export * from "./lsp/lexicon-providers";
 export * from "./mcp/types";
+export * from "./state/index";
+export * from "./spell/index";

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

@@ -193,6 +193,30 @@ export interface LexiconPlugin {
 
   /** Return MCP resource contributions */
   mcpResources?(): McpResourceContribution[];
+
+  // State
+  /** Query deployed resources and return API metadata. Opt-in. */
+  describeResources?(options: {
+    environment: string;
+    buildOutput: string;
+    entityNames: string[];
+  }): Promise<Record<string, ResourceMetadata>>;
+}
+
+/**
+ * Metadata about a deployed resource, returned by describeResources.
+ */
+export interface ResourceMetadata {
+  /** Entity type (e.g. AWS::S3::Bucket, K8s::Apps::Deployment) */
+  type: string;
+  /** Provider-assigned physical ID (ARN, resource ID, pod name) */
+  physicalId?: string;
+  /** Provider-specific status string */
+  status: string;
+  /** ISO timestamp of last update */
+  lastUpdated?: string;
+  /** Cloud-assigned output properties */
+  attributes?: Record<string, unknown>;
 }
 
 /**