@intentius/chant 0.0.1

package/src/discovery/resolve.test.ts

@@ -0,0 +1,267 @@
+import { describe, test, expect } from "bun:test";
+import { resolveAttrRefs } from "./resolve";
+import { AttrRef } from "../attrref";
+import type { Declarable } from "../declarable";
+import { DECLARABLE_MARKER } from "../declarable";
+import { LOGICAL_NAME_SYMBOL, getLogicalName } from "../utils";
+
+describe("resolveAttrRefs", () => {
+  test("sets logical names on all entities", () => {
+    const entity1: Declarable = {
+      entityType: "Test1",
+      [DECLARABLE_MARKER]: true,
+    };
+
+    const entity2: Declarable = {
+      entityType: "Test2",
+      [DECLARABLE_MARKER]: true,
+    };
+
+    const entities = new Map<string, Declarable>([
+      ["MyEntity1", entity1],
+      ["MyEntity2", entity2],
+    ]);
+
+    resolveAttrRefs(entities);
+
+    expect(getLogicalName(entity1)).toBe("MyEntity1");
+    expect(getLogicalName(entity2)).toBe("MyEntity2");
+  });
+
+  test("resolves AttrRef with parent in entities collection", () => {
+    const parent: Declarable = {
+      entityType: "Parent",
+      [DECLARABLE_MARKER]: true,
+    };
+
+    const child: Declarable & { ref: AttrRef } = {
+      entityType: "Child",
+      [DECLARABLE_MARKER]: true,
+      ref: new AttrRef(parent, "Arn"),
+    };
+
+    const entities = new Map<string, Declarable>([
+      ["ParentResource", parent],
+      ["ChildResource", child],
+    ]);
+
+    resolveAttrRefs(entities);
+
+    // Verify the AttrRef can now serialize
+    expect(child.ref.toJSON()).toEqual({
+      __attrRef: { entity: "ParentResource", attribute: "Arn" },
+    });
+  });
+
+  test("resolves multiple AttrRefs on same entity", () => {
+    const parent: Declarable = {
+      entityType: "Parent",
+      [DECLARABLE_MARKER]: true,
+    };
+
+    const child: Declarable & { arn: AttrRef; name: AttrRef } = {
+      entityType: "Child",
+      [DECLARABLE_MARKER]: true,
+      arn: new AttrRef(parent, "Arn"),
+      name: new AttrRef(parent, "Name"),
+    };
+
+    const entities = new Map<string, Declarable>([
+      ["ParentResource", parent],
+      ["ChildResource", child],
+    ]);
+
+    resolveAttrRefs(entities);
+
+    expect(child.arn.toJSON()).toEqual({
+      __attrRef: { entity: "ParentResource", attribute: "Arn" },
+    });
+    expect(child.name.toJSON()).toEqual({
+      __attrRef: { entity: "ParentResource", attribute: "Name" },
+    });
+  });
+
+  test("resolves AttrRefs with different parents", () => {
+    const parent1: Declarable = {
+      entityType: "Parent1",
+      [DECLARABLE_MARKER]: true,
+    };
+
+    const parent2: Declarable = {
+      entityType: "Parent2",
+      [DECLARABLE_MARKER]: true,
+    };
+
+    const child: Declarable & { ref1: AttrRef; ref2: AttrRef } = {
+      entityType: "Child",
+      [DECLARABLE_MARKER]: true,
+      ref1: new AttrRef(parent1, "Arn"),
+      ref2: new AttrRef(parent2, "Name"),
+    };
+
+    const entities = new Map<string, Declarable>([
+      ["Parent1Resource", parent1],
+      ["Parent2Resource", parent2],
+      ["ChildResource", child],
+    ]);
+
+    resolveAttrRefs(entities);
+
+    expect(child.ref1.toJSON()).toEqual({
+      __attrRef: { entity: "Parent1Resource", attribute: "Arn" },
+    });
+    expect(child.ref2.toJSON()).toEqual({
+      __attrRef: { entity: "Parent2Resource", attribute: "Name" },
+    });
+  });
+
+  test("throws when AttrRef parent not in entities collection", () => {
+    const parent = {}; // Not a Declarable, not in entities
+
+    const child: Declarable & { ref: AttrRef } = {
+      entityType: "Child",
+      [DECLARABLE_MARKER]: true,
+      ref: new AttrRef(parent, "Arn"),
+    };
+
+    const entities = new Map<string, Declarable>([["ChildResource", child]]);
+
+    expect(() => resolveAttrRefs(entities)).toThrow(
+      'Cannot resolve AttrRef on "ChildResource.ref": parent entity not found in entities collection'
+    );
+  });
+
+  test("handles entities with no AttrRefs", () => {
+    const entity1: Declarable = {
+      entityType: "Test1",
+      [DECLARABLE_MARKER]: true,
+    };
+
+    const entity2: Declarable & { prop: string } = {
+      entityType: "Test2",
+      [DECLARABLE_MARKER]: true,
+      prop: "value",
+    };
+
+    const entities = new Map<string, Declarable>([
+      ["Entity1", entity1],
+      ["Entity2", entity2],
+    ]);
+
+    expect(() => resolveAttrRefs(entities)).not.toThrow();
+
+    expect(getLogicalName(entity1)).toBe("Entity1");
+    expect(getLogicalName(entity2)).toBe("Entity2");
+  });
+
+  test("handles empty entities map", () => {
+    const entities = new Map<string, Declarable>();
+
+    expect(() => resolveAttrRefs(entities)).not.toThrow();
+  });
+
+  test("resolves chain of entities with AttrRefs", () => {
+    const root: Declarable = {
+      entityType: "Root",
+      [DECLARABLE_MARKER]: true,
+    };
+
+    const middle: Declarable & { rootRef: AttrRef } = {
+      entityType: "Middle",
+      [DECLARABLE_MARKER]: true,
+      rootRef: new AttrRef(root, "Id"),
+    };
+
+    const leaf: Declarable & { middleRef: AttrRef } = {
+      entityType: "Leaf",
+      [DECLARABLE_MARKER]: true,
+      middleRef: new AttrRef(middle, "Name"),
+    };
+
+    const entities = new Map<string, Declarable>([
+      ["RootResource", root],
+      ["MiddleResource", middle],
+      ["LeafResource", leaf],
+    ]);
+
+    resolveAttrRefs(entities);
+
+    expect(middle.rootRef.toJSON()).toEqual({
+      __attrRef: { entity: "RootResource", attribute: "Id" },
+    });
+    expect(leaf.middleRef.toJSON()).toEqual({
+      __attrRef: { entity: "MiddleResource", attribute: "Name" },
+    });
+  });
+
+  test("handles entity referencing itself", () => {
+    const entity: Declarable & { selfRef: AttrRef } = {
+      entityType: "SelfReferencing",
+      [DECLARABLE_MARKER]: true,
+      selfRef: null as unknown as AttrRef, // Will be set below
+    };
+
+    entity.selfRef = new AttrRef(entity, "Arn");
+
+    const entities = new Map<string, Declarable>([["MyResource", entity]]);
+
+    resolveAttrRefs(entities);
+
+    expect(entity.selfRef.toJSON()).toEqual({
+      __attrRef: { entity: "MyResource", attribute: "Arn" },
+    });
+  });
+
+  test("preserves logical name symbol on entities", () => {
+    const entity: Declarable = {
+      entityType: "Test",
+      [DECLARABLE_MARKER]: true,
+    };
+
+    const entities = new Map<string, Declarable>([["TestResource", entity]]);
+
+    resolveAttrRefs(entities);
+
+    const entityWithSymbol = entity as unknown as Record<symbol, unknown>;
+    expect(entityWithSymbol[LOGICAL_NAME_SYMBOL]).toBe("TestResource");
+  });
+
+  test("uses export name as logical name", () => {
+    const entity: Declarable = {
+      entityType: "Test",
+      [DECLARABLE_MARKER]: true,
+    };
+
+    const entities = new Map<string, Declarable>([
+      ["MyCustomExportName", entity],
+    ]);
+
+    resolveAttrRefs(entities);
+
+    expect(getLogicalName(entity)).toBe("MyCustomExportName");
+  });
+
+  test("handles complex attribute names in AttrRef", () => {
+    const parent: Declarable = {
+      entityType: "Parent",
+      [DECLARABLE_MARKER]: true,
+    };
+
+    const child: Declarable & { ref: AttrRef } = {
+      entityType: "Child",
+      [DECLARABLE_MARKER]: true,
+      ref: new AttrRef(parent, "Outputs.WebsiteURL"),
+    };
+
+    const entities = new Map<string, Declarable>([
+      ["ParentResource", parent],
+      ["ChildResource", child],
+    ]);
+
+    resolveAttrRefs(entities);
+
+    expect(child.ref.toJSON()).toEqual({
+      __attrRef: { entity: "ParentResource", attribute: "Outputs.WebsiteURL" },
+    });
+  });
+});

package/src/discovery/resolve.ts

@@ -0,0 +1,54 @@
+import type { Declarable } from "../declarable";
+import { AttrRef } from "../attrref";
+import { LOGICAL_NAME_SYMBOL, getAttributes } from "../utils";
+
+/**
+ * Resolves all AttrRef instances in a collection of entities
+ * Sets logical names on entities and resolves parent references in AttrRefs
+ *
+ * @param entities - Map of export name to Declarable entity
+ * @throws {Error} If an AttrRef parent cannot be found in the entities collection
+ */
+export function resolveAttrRefs(entities: Map<string, Declarable>): void {
+  // First pass: Set logical names on all entities
+  for (const [name, entity] of entities.entries()) {
+    (entity as unknown as Record<symbol, unknown>)[LOGICAL_NAME_SYMBOL] = name;
+  }
+
+  // Second pass: Resolve all AttrRef instances
+  for (const [name, entity] of entities.entries()) {
+    const attributes = getAttributes(entity);
+
+    for (const attrName of attributes) {
+      const attrRef = (entity as unknown as Record<string, unknown>)[attrName];
+
+      if (attrRef instanceof AttrRef) {
+        const parent = attrRef.parent.deref();
+
+        if (!parent) {
+          throw new Error(
+            `Cannot resolve AttrRef on "${name}.${attrName}": parent has been garbage collected`
+          );
+        }
+
+        // Find the parent entity in the entities map
+        let parentLogicalName: string | undefined;
+
+        for (const [entityName, entityValue] of entities.entries()) {
+          if (entityValue === parent) {
+            parentLogicalName = entityName;
+            break;
+          }
+        }
+
+        if (!parentLogicalName) {
+          throw new Error(
+            `Cannot resolve AttrRef on "${name}.${attrName}": parent entity not found in entities collection`
+          );
+        }
+
+        attrRef._setLogicalName(parentLogicalName);
+      }
+    }
+  }
+}

package/src/errors.test.ts

@@ -0,0 +1,138 @@
+import { describe, test, expect } from "bun:test";
+import { DiscoveryError, BuildError, LintError } from "./errors";
+
+describe("DiscoveryError", () => {
+  test("creates error with file, message, and type properties", () => {
+    const error = new DiscoveryError(
+      "/path/to/file.ts",
+      "Failed to import module",
+      "import"
+    );
+
+    expect(error).toBeInstanceOf(Error);
+    expect(error).toBeInstanceOf(DiscoveryError);
+    expect(error.name).toBe("DiscoveryError");
+    expect(error.file).toBe("/path/to/file.ts");
+    expect(error.message).toBe("Failed to import module");
+    expect(error.type).toBe("import");
+  });
+
+  test("supports resolution error type", () => {
+    const error = new DiscoveryError(
+      "/src/index.ts",
+      "Cannot resolve module",
+      "resolution"
+    );
+
+    expect(error.type).toBe("resolution");
+  });
+
+  test("supports circular error type", () => {
+    const error = new DiscoveryError(
+      "/src/circular.ts",
+      "Circular dependency detected",
+      "circular"
+    );
+
+    expect(error.type).toBe("circular");
+  });
+
+  test("serializes to JSON correctly", () => {
+    const error = new DiscoveryError(
+      "/test.ts",
+      "Test error",
+      "import"
+    );
+
+    const json = error.toJSON();
+    expect(json).toEqual({
+      name: "DiscoveryError",
+      file: "/test.ts",
+      message: "Test error",
+      type: "import",
+    });
+  });
+});
+
+describe("BuildError", () => {
+  test("creates error with entityName and message properties", () => {
+    const error = new BuildError("MyEntity", "Failed to build entity");
+
+    expect(error).toBeInstanceOf(Error);
+    expect(error).toBeInstanceOf(BuildError);
+    expect(error.name).toBe("BuildError");
+    expect(error.entityName).toBe("MyEntity");
+    expect(error.message).toBe("Failed to build entity");
+  });
+
+  test("serializes to JSON correctly", () => {
+    const error = new BuildError("TestEntity", "Serialization failed");
+
+    const json = error.toJSON();
+    expect(json).toEqual({
+      name: "BuildError",
+      entityName: "TestEntity",
+      message: "Serialization failed",
+    });
+  });
+
+  test("handles entity names with special characters", () => {
+    const error = new BuildError("My-Entity_v2", "Build failure");
+
+    expect(error.entityName).toBe("My-Entity_v2");
+  });
+});
+
+describe("LintError", () => {
+  test("creates error with file, line, column, ruleId, and message properties", () => {
+    const error = new LintError(
+      "/src/app.ts",
+      42,
+      10,
+      "no-unused-vars",
+      "Variable 'x' is declared but never used"
+    );
+
+    expect(error).toBeInstanceOf(Error);
+    expect(error).toBeInstanceOf(LintError);
+    expect(error.name).toBe("LintError");
+    expect(error.file).toBe("/src/app.ts");
+    expect(error.line).toBe(42);
+    expect(error.column).toBe(10);
+    expect(error.ruleId).toBe("no-unused-vars");
+    expect(error.message).toBe("Variable 'x' is declared but never used");
+  });
+
+  test("handles line 0 and column 0", () => {
+    const error = new LintError(
+      "/test.ts",
+      0,
+      0,
+      "parse-error",
+      "Parse error"
+    );
+
+    expect(error.line).toBe(0);
+    expect(error.column).toBe(0);
+  });
+
+  test("serializes to JSON correctly", () => {
+    const error = new LintError(
+      "/main.ts",
+      15,
+      3,
+      "@typescript-eslint/no-explicit-any",
+      "Unexpected any"
+    );
+
+    const json = error.toJSON();
+    expect(json).toEqual({
+      name: "LintError",
+      file: "/main.ts",
+      line: 15,
+      column: 3,
+      ruleId: "@typescript-eslint/no-explicit-any",
+      message: "Unexpected any",
+    });
+  });
+});

package/src/errors.ts

@@ -0,0 +1,86 @@
+/**
+ * Error types for chant discovery, build, and lint failures
+ */
+
+export type DiscoveryErrorType = "import" | "resolution" | "circular";
+
+/**
+ * Error during file discovery or module import
+ */
+export class DiscoveryError extends Error {
+  readonly file: string;
+  readonly type: DiscoveryErrorType;
+
+  constructor(file: string, message: string, type: DiscoveryErrorType) {
+    super(message);
+    this.name = "DiscoveryError";
+    this.file = file;
+    this.type = type;
+  }
+
+  toJSON() {
+    return {
+      name: this.name,
+      file: this.file,
+      message: this.message,
+      type: this.type,
+    };
+  }
+}
+
+/**
+ * Error during build/serialization
+ */
+export class BuildError extends Error {
+  readonly entityName: string;
+
+  constructor(entityName: string, message: string) {
+    super(message);
+    this.name = "BuildError";
+    this.entityName = entityName;
+  }
+
+  toJSON() {
+    return {
+      name: this.name,
+      entityName: this.entityName,
+      message: this.message,
+    };
+  }
+}
+
+/**
+ * Error from lint rule violation
+ */
+export class LintError extends Error {
+  readonly file: string;
+  readonly line: number;
+  readonly column: number;
+  readonly ruleId: string;
+
+  constructor(
+    file: string,
+    line: number,
+    column: number,
+    ruleId: string,
+    message: string
+  ) {
+    super(message);
+    this.name = "LintError";
+    this.file = file;
+    this.line = line;
+    this.column = column;
+    this.ruleId = ruleId;
+  }
+
+  toJSON() {
+    return {
+      name: this.name,
+      file: this.file,
+      line: this.line,
+      column: this.column,
+      ruleId: this.ruleId,
+      message: this.message,
+    };
+  }
+}

package/src/import/base-parser.test.ts

@@ -0,0 +1,67 @@
+import { describe, expect, test } from "bun:test";
+import { BaseValueParser } from "./base-parser";
+
+/**
+ * Mock parser that recognizes {"UPPER": value} as an intrinsic.
+ */
+class MockParser extends BaseValueParser {
+  protected dispatchIntrinsic(
+    key: string,
+    value: unknown,
+    _obj: Record<string, unknown>,
+  ): unknown | null {
+    if (key === "UPPER") {
+      return { __intrinsic: "UPPER", value: this.parseValue(value) };
+    }
+    return null;
+  }
+}
+
+describe("BaseValueParser", () => {
+  const parser = new MockParser();
+
+  test("returns null/undefined as-is", () => {
+    expect(parser.parseValue(null)).toBeNull();
+    expect(parser.parseValue(undefined)).toBeUndefined();
+  });
+
+  test("returns primitives as-is", () => {
+    expect(parser.parseValue("hello")).toBe("hello");
+    expect(parser.parseValue(42)).toBe(42);
+    expect(parser.parseValue(true)).toBe(true);
+  });
+
+  test("recurses into arrays", () => {
+    expect(parser.parseValue([1, "two", null])).toEqual([1, "two", null]);
+  });
+
+  test("dispatches single-key intrinsic", () => {
+    expect(parser.parseValue({ UPPER: "hello" })).toEqual({
+      __intrinsic: "UPPER",
+      value: "hello",
+    });
+  });
+
+  test("recurses into intrinsic values", () => {
+    expect(parser.parseValue({ UPPER: { UPPER: "nested" } })).toEqual({
+      __intrinsic: "UPPER",
+      value: { __intrinsic: "UPPER", value: "nested" },
+    });
+  });
+
+  test("falls through for unknown single-key objects", () => {
+    expect(parser.parseValue({ unknown: "value" })).toEqual({ unknown: "value" });
+  });
+
+  test("recurses into multi-key objects", () => {
+    const result = parser.parseValue({ a: 1, b: { UPPER: "x" } });
+    expect(result).toEqual({ a: 1, b: { __intrinsic: "UPPER", value: "x" } });
+  });
+
+  test("recurses arrays inside objects", () => {
+    const result = parser.parseValue({ items: [{ UPPER: "a" }, "plain"] });
+    expect(result).toEqual({
+      items: [{ __intrinsic: "UPPER", value: "a" }, "plain"],
+    });
+  });
+});

package/src/import/base-parser.ts

@@ -0,0 +1,48 @@
+/**
+ * Base class for template value parsers.
+ *
+ * Implements the generic recursive walk: null → array → single-key
+ * intrinsic dispatch → plain object → primitive. Subclasses provide
+ * format-specific intrinsic dispatch.
+ */
+
+export abstract class BaseValueParser {
+  /**
+   * Try to interpret a single-key object as an intrinsic function.
+   * Return the parsed intrinsic value, or null if this key isn't an intrinsic.
+   */
+  protected abstract dispatchIntrinsic(
+    key: string,
+    value: unknown,
+    obj: Record<string, unknown>,
+  ): unknown | null;
+
+  /**
+   * Parse a value recursively: null → array → single-key intrinsic → object → primitive.
+   */
+  parseValue(value: unknown): unknown {
+    if (value === null || value === undefined) return value;
+
+    if (Array.isArray(value)) {
+      return value.map((v) => this.parseValue(v));
+    }
+
+    if (typeof value === "object") {
+      const obj = value as Record<string, unknown>;
+      const keys = Object.keys(obj);
+
+      if (keys.length === 1) {
+        const result = this.dispatchIntrinsic(keys[0], obj[keys[0]], obj);
+        if (result !== null) return result;
+      }
+
+      const parsed: Record<string, unknown> = {};
+      for (const [k, v] of Object.entries(obj)) {
+        parsed[k] = this.parseValue(v);
+      }
+      return parsed;
+    }
+
+    return value;
+  }
+}

package/src/import/generator.ts

@@ -0,0 +1,21 @@
+import type { TemplateIR } from "./parser";
+
+/**
+ * Represents a generated TypeScript file
+ */
+export interface GeneratedFile {
+  readonly path: string;
+  readonly content: string;
+}
+
+/**
+ * Interface for TypeScript code generators that convert IR to TypeScript
+ */
+export interface TypeScriptGenerator {
+  /**
+   * Generate TypeScript files from intermediate representation
+   * @param ir - Intermediate representation of the template
+   * @returns Array of generated TypeScript files
+   */
+  generate(ir: TemplateIR): GeneratedFile[];
+}