@intentius/chant 0.0.1

package/src/serializer-walker.test.ts

@@ -0,0 +1,124 @@
+import { describe, test, expect } from "bun:test";
+import { walkValue, type SerializerVisitor } from "./serializer-walker";
+import { DECLARABLE_MARKER, type Declarable } from "./declarable";
+import { INTRINSIC_MARKER } from "./intrinsic";
+import { AttrRef } from "./attrref";
+
+function makeDeclarable(type: string, kind: "resource" | "property" = "resource", props?: Record<string, unknown>): Declarable & { props?: Record<string, unknown> } {
+  const d: Declarable & { props?: Record<string, unknown> } = {
+    lexicon: "test",
+    entityType: type,
+    kind,
+    [DECLARABLE_MARKER]: true as const,
+  };
+  if (props) d.props = props;
+  return d;
+}
+
+const mockVisitor: SerializerVisitor = {
+  attrRef: (name, attr) => ({ __getAtt: [name, attr] }),
+  resourceRef: (name) => ({ __ref: name }),
+  propertyDeclarable: (entity, walk) => {
+    if (!("props" in entity) || typeof entity.props !== "object" || entity.props === null) {
+      return undefined;
+    }
+    const props = entity.props as Record<string, unknown>;
+    const result: Record<string, unknown> = {};
+    for (const [k, v] of Object.entries(props)) {
+      if (v !== undefined) result[k] = walk(v);
+    }
+    return Object.keys(result).length > 0 ? result : undefined;
+  },
+};
+
+describe("walkValue", () => {
+  test("returns null and undefined as-is", () => {
+    const names = new Map<Declarable, string>();
+    expect(walkValue(null, names, mockVisitor)).toBe(null);
+    expect(walkValue(undefined, names, mockVisitor)).toBe(undefined);
+  });
+
+  test("returns primitives as-is", () => {
+    const names = new Map<Declarable, string>();
+    expect(walkValue(42, names, mockVisitor)).toBe(42);
+    expect(walkValue("hello", names, mockVisitor)).toBe("hello");
+    expect(walkValue(true, names, mockVisitor)).toBe(true);
+  });
+
+  test("handles AttrRef", () => {
+    const parent = makeDeclarable("Test::Resource");
+    const ref = new AttrRef(parent, "arn");
+    ref._setLogicalName("MyResource");
+
+    const names = new Map<Declarable, string>([[parent, "MyResource"]]);
+    expect(walkValue(ref, names, mockVisitor)).toEqual({ __getAtt: ["MyResource", "arn"] });
+  });
+
+  test("throws for AttrRef without logical name", () => {
+    const parent = makeDeclarable("Test::Resource");
+    const ref = new AttrRef(parent, "arn");
+
+    const names = new Map<Declarable, string>();
+    expect(() => walkValue(ref, names, mockVisitor)).toThrow("logical name not set");
+  });
+
+  test("handles intrinsic with toJSON", () => {
+    const intrinsic = {
+      [INTRINSIC_MARKER]: true as const,
+      toJSON: () => ({ MyIntrinsic: "value" }),
+    };
+    const names = new Map<Declarable, string>();
+    expect(walkValue(intrinsic, names, mockVisitor)).toEqual({ MyIntrinsic: "value" });
+  });
+
+  test("handles resource Declarable via resourceRef", () => {
+    const resource = makeDeclarable("Test::Bucket");
+    const names = new Map<Declarable, string>([[resource, "MyBucket"]]);
+    expect(walkValue(resource, names, mockVisitor)).toEqual({ __ref: "MyBucket" });
+  });
+
+  test("handles property Declarable via propertyDeclarable", () => {
+    const prop = makeDeclarable("Test::Config", "property", { key: "value" });
+    const names = new Map<Declarable, string>();
+    expect(walkValue(prop, names, mockVisitor)).toEqual({ key: "value" });
+  });
+
+  test("recurses into arrays", () => {
+    const names = new Map<Declarable, string>();
+    expect(walkValue([1, "two", [3]], names, mockVisitor)).toEqual([1, "two", [3]]);
+  });
+
+  test("recurses into objects", () => {
+    const names = new Map<Declarable, string>();
+    expect(walkValue({ a: 1, b: { c: 2 } }, names, mockVisitor)).toEqual({ a: 1, b: { c: 2 } });
+  });
+
+  test("applies transformKey when provided", () => {
+    const visitor: SerializerVisitor = {
+      ...mockVisitor,
+      transformKey: (k) => k.toUpperCase(),
+    };
+    const names = new Map<Declarable, string>();
+    expect(walkValue({ foo: 1, bar: 2 }, names, visitor)).toEqual({ FOO: 1, BAR: 2 });
+  });
+
+  test("complex nested structure", () => {
+    const resource = makeDeclarable("Test::Role");
+    const ref = new AttrRef(resource, "arn");
+    ref._setLogicalName("MyRole");
+
+    const names = new Map<Declarable, string>([[resource, "MyRole"]]);
+    const value = {
+      config: {
+        role: resource,
+        items: [ref, "static"],
+      },
+    };
+    expect(walkValue(value, names, mockVisitor)).toEqual({
+      config: {
+        role: { __ref: "MyRole" },
+        items: [{ __getAtt: ["MyRole", "arn"] }, "static"],
+      },
+    });
+  });
+});

package/src/serializer-walker.ts

@@ -0,0 +1,83 @@
+/**
+ * Generic recursive value walker for lexicon serializers.
+ *
+ * Implements the dispatch chain: null → AttrRef → Intrinsic → Declarable → Array → Object,
+ * delegating format-specific behavior to a SerializerVisitor.
+ */
+
+import type { Declarable } from "./declarable";
+import { isPropertyDeclarable } from "./declarable";
+import { INTRINSIC_MARKER } from "./intrinsic";
+import { AttrRef } from "./attrref";
+
+export interface SerializerVisitor {
+  /** Format an attribute reference (e.g. CFN Fn::GetAttr). */
+  attrRef(logicalName: string, attribute: string): unknown;
+  /** Format a resource-level Declarable reference (e.g. CFN Ref). */
+  resourceRef(logicalName: string): unknown;
+  /** Format a property-level Declarable by walking its props. */
+  propertyDeclarable(entity: Declarable, walk: (v: unknown) => unknown): unknown;
+  /** Optional key transformation (e.g. camelCase → PascalCase). */
+  transformKey?(key: string): string;
+}
+
+/**
+ * Recursively walk a value, converting AttrRefs, Intrinsics, Declarables,
+ * arrays, and objects using the provided visitor.
+ */
+export function walkValue(
+  value: unknown,
+  entityNames: Map<Declarable, string>,
+  visitor: SerializerVisitor,
+): unknown {
+  if (value === null || value === undefined) {
+    return value;
+  }
+
+  // Handle AttrRef
+  if (value instanceof AttrRef) {
+    const name = value.getLogicalName();
+    if (!name) {
+      throw new Error(
+        `Cannot serialize AttrRef for attribute "${value.attribute}": logical name not set`
+      );
+    }
+    return visitor.attrRef(name, value.attribute);
+  }
+
+  // Handle Intrinsics
+  if (typeof value === "object" && value !== null && INTRINSIC_MARKER in value) {
+    if ("toJSON" in value && typeof value.toJSON === "function") {
+      return value.toJSON();
+    }
+  }
+
+  // Handle Declarable references
+  if (typeof value === "object" && value !== null && "entityType" in value) {
+    const decl = value as Declarable;
+    if (isPropertyDeclarable(decl)) {
+      return visitor.propertyDeclarable(decl, (v) => walkValue(v, entityNames, visitor));
+    }
+    const name = entityNames.get(decl);
+    if (name) {
+      return visitor.resourceRef(name);
+    }
+  }
+
+  // Handle arrays
+  if (Array.isArray(value)) {
+    return value.map((item) => walkValue(item, entityNames, visitor));
+  }
+
+  // Handle objects
+  if (typeof value === "object") {
+    const result: Record<string, unknown> = {};
+    for (const [key, val] of Object.entries(value)) {
+      const outKey = visitor.transformKey ? visitor.transformKey(key) : key;
+      result[outKey] = walkValue(val, entityNames, visitor);
+    }
+    return result;
+  }
+
+  return value;
+}

package/src/serializer.ts

@@ -0,0 +1,42 @@
+import type { Declarable } from "./declarable";
+import type { LexiconOutput } from "./lexicon-output";
+
+/**
+ * Result of serialization that may include additional files (e.g. nested stack templates).
+ */
+export interface SerializerResult {
+  /** Primary template content */
+  primary: string;
+  /** Additional files keyed by filename (e.g. "network.template.json" → content) */
+  files?: Record<string, string>;
+}
+
+/**
+ * Serializer interface for chant specifications
+ */
+export interface Serializer {
+  /**
+   * Name of the lexicon
+   */
+  name: string;
+
+  /**
+   * Prefix used for rules in this lexicon
+   */
+  rulePrefix: string;
+
+  /**
+   * Serializes the entities to a string representation
+   * @param entities - Map of entity name to Declarable entity
+   * @param outputs - Optional array of LexiconOutputs produced by this lexicon
+   */
+  serialize(entities: Map<string, Declarable>, outputs?: LexiconOutput[]): string | SerializerResult;
+
+  /**
+   * Serialize a cross-lexicon reference to a foreign output.
+   * Called when this lexicon consumes an output produced by another lexicon.
+   * @param output - The LexiconOutput being referenced
+   * @returns Lexicon-specific reference representation
+   */
+  serializeCrossRef?(output: LexiconOutput): unknown;
+}

package/src/sort.test.ts

@@ -0,0 +1,290 @@
+import { describe, test, expect } from "bun:test";
+import { topologicalSort } from "./sort";
+import { BuildError } from "./errors";
+
+describe("topologicalSort", () => {
+  test("returns empty array for empty dependencies", () => {
+    const dependencies = {};
+    const result = topologicalSort(dependencies);
+    expect(result).toEqual([]);
+  });
+
+  test("returns single node with no dependencies", () => {
+    const dependencies = {
+      A: [],
+    };
+    const result = topologicalSort(dependencies);
+    expect(result).toEqual(["A"]);
+  });
+
+  test("sorts linear dependency chain", () => {
+    const dependencies = {
+      A: [],
+      B: ["A"],
+      C: ["B"],
+      D: ["C"],
+    };
+    const result = topologicalSort(dependencies);
+    expect(result).toEqual(["A", "B", "C", "D"]);
+  });
+
+  test("sorts diamond dependency pattern", () => {
+    const dependencies = {
+      A: [],
+      B: ["A"],
+      C: ["A"],
+      D: ["B", "C"],
+    };
+    const result = topologicalSort(dependencies);
+
+    // A must come first, D must come last
+    expect(result[0]).toBe("A");
+    expect(result[3]).toBe("D");
+
+    // B and C must come before D but after A
+    const bIndex = result.indexOf("B");
+    const cIndex = result.indexOf("C");
+    const dIndex = result.indexOf("D");
+    expect(bIndex).toBeLessThan(dIndex);
+    expect(cIndex).toBeLessThan(dIndex);
+  });
+
+  test("sorts multiple independent nodes", () => {
+    const dependencies = {
+      A: [],
+      B: [],
+      C: [],
+    };
+    const result = topologicalSort(dependencies);
+    expect(result).toHaveLength(3);
+    expect(result).toContain("A");
+    expect(result).toContain("B");
+    expect(result).toContain("C");
+  });
+
+  test("sorts complex graph with multiple levels", () => {
+    const dependencies = {
+      A: [],
+      B: [],
+      C: ["A"],
+      D: ["A", "B"],
+      E: ["C", "D"],
+    };
+    const result = topologicalSort(dependencies);
+
+    // A and B must come before C, D, E
+    const aIndex = result.indexOf("A");
+    const bIndex = result.indexOf("B");
+    const cIndex = result.indexOf("C");
+    const dIndex = result.indexOf("D");
+    const eIndex = result.indexOf("E");
+
+    expect(aIndex).toBeLessThan(cIndex);
+    expect(aIndex).toBeLessThan(dIndex);
+    expect(aIndex).toBeLessThan(eIndex);
+    expect(bIndex).toBeLessThan(dIndex);
+    expect(bIndex).toBeLessThan(eIndex);
+    expect(cIndex).toBeLessThan(eIndex);
+    expect(dIndex).toBeLessThan(eIndex);
+  });
+
+  test("handles node with multiple dependencies", () => {
+    const dependencies = {
+      A: [],
+      B: [],
+      C: [],
+      D: ["A", "B", "C"],
+    };
+    const result = topologicalSort(dependencies);
+
+    // A, B, C must all come before D
+    const dIndex = result.indexOf("D");
+    expect(result.indexOf("A")).toBeLessThan(dIndex);
+    expect(result.indexOf("B")).toBeLessThan(dIndex);
+    expect(result.indexOf("C")).toBeLessThan(dIndex);
+  });
+
+  test("throws BuildError for self-loop", () => {
+    const dependencies = {
+      A: ["A"],
+    };
+
+    expect(() => topologicalSort(dependencies)).toThrow(BuildError);
+    expect(() => topologicalSort(dependencies)).toThrow(/Circular dependency detected/);
+  });
+
+  test("throws BuildError for two-node cycle", () => {
+    const dependencies = {
+      A: ["B"],
+      B: ["A"],
+    };
+
+    expect(() => topologicalSort(dependencies)).toThrow(BuildError);
+    expect(() => topologicalSort(dependencies)).toThrow(/Circular dependency detected/);
+  });
+
+  test("throws BuildError for three-node cycle", () => {
+    const dependencies = {
+      A: ["B"],
+      B: ["C"],
+      C: ["A"],
+    };
+
+    expect(() => topologicalSort(dependencies)).toThrow(BuildError);
+    expect(() => topologicalSort(dependencies)).toThrow(/Circular dependency detected/);
+  });
+
+  test("throws BuildError for cycle in complex graph", () => {
+    const dependencies = {
+      A: [],
+      B: ["A"],
+      C: ["B"],
+      D: ["C"],
+      E: ["D", "B"],
+      F: ["E"],
+      G: ["F", "C"],
+      // Create cycle: G -> C -> B, but also E -> B
+      H: ["G"],
+      I: ["H", "A"],
+      J: ["I"],
+      // Add the cycle
+      K: ["J"],
+      L: ["K"],
+      M: ["L", "K"],
+    };
+
+    // Add actual cycle
+    dependencies.B = ["M"];
+
+    expect(() => topologicalSort(dependencies)).toThrow(BuildError);
+  });
+
+  test("BuildError contains entity name from cycle", () => {
+    const dependencies = {
+      A: ["B"],
+      B: ["C"],
+      C: ["A"],
+    };
+
+    try {
+      topologicalSort(dependencies);
+      expect(true).toBe(false); // Should not reach here
+    } catch (error) {
+      expect(error).toBeInstanceOf(BuildError);
+      if (error instanceof BuildError) {
+        // Entity name should be one of the nodes in the cycle
+        expect(["A", "B", "C"]).toContain(error.entityName);
+      }
+    }
+  });
+
+  test("BuildError message includes cycle path", () => {
+    const dependencies = {
+      A: ["B"],
+      B: ["C"],
+      C: ["A"],
+    };
+
+    try {
+      topologicalSort(dependencies);
+      expect(true).toBe(false); // Should not reach here
+    } catch (error) {
+      expect(error).toBeInstanceOf(BuildError);
+      if (error instanceof BuildError) {
+        expect(error.message).toContain("Circular dependency detected");
+        expect(error.message).toContain("->");
+      }
+    }
+  });
+
+  test("sorts disconnected components", () => {
+    const dependencies = {
+      A: [],
+      B: ["A"],
+      C: [],
+      D: ["C"],
+    };
+    const result = topologicalSort(dependencies);
+
+    // Check ordering within each component
+    const aIndex = result.indexOf("A");
+    const bIndex = result.indexOf("B");
+    const cIndex = result.indexOf("C");
+    const dIndex = result.indexOf("D");
+
+    expect(aIndex).toBeLessThan(bIndex);
+    expect(cIndex).toBeLessThan(dIndex);
+    expect(result).toHaveLength(4);
+  });
+
+  test("handles nodes with empty dependency arrays", () => {
+    const dependencies = {
+      A: [],
+      B: [],
+      C: ["A", "B"],
+    };
+    const result = topologicalSort(dependencies);
+
+    const cIndex = result.indexOf("C");
+    expect(result.indexOf("A")).toBeLessThan(cIndex);
+    expect(result.indexOf("B")).toBeLessThan(cIndex);
+  });
+
+  test("preserves all nodes in result", () => {
+    const dependencies = {
+      A: [],
+      B: ["A"],
+      C: ["A"],
+      D: ["B", "C"],
+      E: [],
+      F: ["E"],
+    };
+    const result = topologicalSort(dependencies);
+
+    expect(result).toHaveLength(6);
+    expect(new Set(result).size).toBe(6); // No duplicates
+    expect(result).toContain("A");
+    expect(result).toContain("B");
+    expect(result).toContain("C");
+    expect(result).toContain("D");
+    expect(result).toContain("E");
+    expect(result).toContain("F");
+  });
+
+  test("handles dependencies on non-existent nodes", () => {
+    const dependencies = {
+      A: ["B"], // B doesn't exist as a key
+      C: [],
+    };
+
+    // Should handle gracefully - B is referenced but not defined
+    const result = topologicalSort(dependencies);
+    expect(result).toContain("A");
+    expect(result).toContain("C");
+  });
+
+  test("handles realistic CloudFormation-style resource dependencies", () => {
+    const dependencies = {
+      MyVPC: [],
+      MySubnet: ["MyVPC"],
+      MySecurityGroup: ["MyVPC"],
+      MyInstance: ["MySubnet", "MySecurityGroup"],
+      MyEIP: ["MyInstance"],
+    };
+    const result = topologicalSort(dependencies);
+
+    // VPC must be first
+    expect(result[0]).toBe("MyVPC");
+
+    // EIP must be last
+    expect(result[result.length - 1]).toBe("MyEIP");
+
+    // Subnet and SecurityGroup must come before Instance
+    const subnetIndex = result.indexOf("MySubnet");
+    const sgIndex = result.indexOf("MySecurityGroup");
+    const instanceIndex = result.indexOf("MyInstance");
+
+    expect(subnetIndex).toBeLessThan(instanceIndex);
+    expect(sgIndex).toBeLessThan(instanceIndex);
+  });
+});

package/src/sort.ts

@@ -0,0 +1,58 @@
+import { BuildError } from "./errors";
+import { detectCycles } from "./discovery/cycles";
+
+/**
+ * Performs a topological sort on a dependency graph
+ * @param dependencies - Record where keys are entity names and values are arrays of their dependencies
+ * @returns Array of entity names in topological order (dependencies appear before dependents)
+ * @throws {BuildError} If a cycle is detected in the dependency graph
+ */
+export function topologicalSort(
+  dependencies: Record<string, string[]>
+): string[] {
+  // Check for cycles first
+  const cycles = detectCycles(dependencies);
+  if (cycles.length > 0) {
+    const cycleStr = cycles[0].join(" -> ");
+    throw new BuildError(
+      cycles[0][0],
+      `Circular dependency detected: ${cycleStr}`
+    );
+  }
+
+  const sorted: string[] = [];
+  const visited = new Set<string>();
+  const visiting = new Set<string>();
+
+  /**
+   * DFS helper for topological sort
+   * @param node - Current node being visited
+   */
+  function visit(node: string): void {
+    if (visited.has(node)) {
+      return;
+    }
+
+    visiting.add(node);
+
+    const deps = dependencies[node] || [];
+    for (const dep of deps) {
+      if (!visited.has(dep)) {
+        visit(dep);
+      }
+    }
+
+    visiting.delete(node);
+    visited.add(node);
+    sorted.push(node);
+  }
+
+  // Visit all nodes
+  for (const node of Object.keys(dependencies)) {
+    if (!visited.has(node)) {
+      visit(node);
+    }
+  }
+
+  return sorted;
+}

package/src/stack-output.ts

@@ -0,0 +1,82 @@
+/**
+ * Stack Output — marks a value for cross-stack export.
+ *
+ * When a child project declares `stackOutput(ref)`, the serializer emits
+ * it into the template's Outputs section. The parent can then reference
+ * it via `nestedStack().outputs.name`.
+ */
+
+import { DECLARABLE_MARKER, type Declarable } from "./declarable";
+import type { AttrRef } from "./attrref";
+
+/**
+ * Marker symbol for stack output identification.
+ */
+export const STACK_OUTPUT_MARKER = Symbol.for("chant.stackOutput");
+
+/**
+ * A stack output declaration — wraps an AttrRef into a Declarable
+ * that serializers emit as a template Output.
+ */
+export interface StackOutput extends Declarable {
+  readonly [STACK_OUTPUT_MARKER]: true;
+  readonly [DECLARABLE_MARKER]: true;
+  readonly lexicon: string;
+  readonly entityType: string;
+  readonly kind: "output";
+  readonly sourceRef: AttrRef;
+  readonly description?: string;
+}
+
+/**
+ * Type guard for StackOutput.
+ */
+export function isStackOutput(value: unknown): value is StackOutput {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    STACK_OUTPUT_MARKER in value &&
+    (value as Record<symbol, unknown>)[STACK_OUTPUT_MARKER] === true
+  );
+}
+
+/**
+ * Create a stack output that exports an attribute reference for cross-stack use.
+ *
+ * @param ref - The AttrRef to export (e.g. `vpc.vpcId`)
+ * @param options - Optional description for the output
+ * @returns A StackOutput Declarable
+ *
+ * @example
+ * ```ts
+ * import { stackOutput } from "@intentius/chant";
+ * import * as _ from "./_";
+ *
+ * export const vpcId = stackOutput(_.$.vpc.vpcId);
+ * export const subnetId = stackOutput(_.$.subnet.subnetId, {
+ *   description: "Primary subnet ID",
+ * });
+ * ```
+ */
+export function stackOutput(
+  ref: AttrRef,
+  options?: { description?: string },
+): StackOutput {
+  // Derive lexicon from the AttrRef's parent entity
+  const parent = ref.parent.deref();
+  const lexicon = parent && typeof (parent as any).lexicon === "string"
+    ? (parent as any).lexicon
+    : "unknown";
+
+  const output: StackOutput = {
+    [STACK_OUTPUT_MARKER]: true,
+    [DECLARABLE_MARKER]: true,
+    lexicon,
+    entityType: "chant:output",
+    kind: "output",
+    sourceRef: ref,
+    description: options?.description,
+  };
+
+  return output;
+}