@intentius/chant 0.0.1

package/src/import/ir-utils.test.ts

@@ -0,0 +1,103 @@
+import { describe, expect, test } from "bun:test";
+import { hasIntrinsicInValue, irUsesIntrinsic, collectDependencies } from "./ir-utils";
+import type { TemplateIR } from "./parser";
+
+describe("hasIntrinsicInValue", () => {
+  test("finds intrinsic at top level", () => {
+    expect(hasIntrinsicInValue({ __intrinsic: "Sub", template: "hello" }, "Sub")).toBe(true);
+  });
+
+  test("finds intrinsic nested in object", () => {
+    const value = { foo: { bar: { __intrinsic: "Ref", name: "x" } } };
+    expect(hasIntrinsicInValue(value, "Ref")).toBe(true);
+  });
+
+  test("finds intrinsic in array", () => {
+    const value = [1, { __intrinsic: "If" }, "hello"];
+    expect(hasIntrinsicInValue(value, "If")).toBe(true);
+  });
+
+  test("returns false for missing intrinsic", () => {
+    const value = { __intrinsic: "Sub", template: "hello" };
+    expect(hasIntrinsicInValue(value, "Ref")).toBe(false);
+  });
+
+  test("returns false for null/undefined", () => {
+    expect(hasIntrinsicInValue(null, "Sub")).toBe(false);
+    expect(hasIntrinsicInValue(undefined, "Sub")).toBe(false);
+  });
+
+  test("returns false for primitives", () => {
+    expect(hasIntrinsicInValue("hello", "Sub")).toBe(false);
+    expect(hasIntrinsicInValue(42, "Sub")).toBe(false);
+  });
+});
+
+describe("irUsesIntrinsic", () => {
+  test("finds intrinsic in resource properties", () => {
+    const ir: TemplateIR = {
+      resources: [
+        { logicalId: "A", type: "T::A", properties: { x: { __intrinsic: "Sub", template: "hi" } } },
+      ],
+      parameters: [],
+    };
+    expect(irUsesIntrinsic(ir, "Sub")).toBe(true);
+    expect(irUsesIntrinsic(ir, "Ref")).toBe(false);
+  });
+
+  test("returns false for empty IR", () => {
+    const ir: TemplateIR = { resources: [], parameters: [] };
+    expect(irUsesIntrinsic(ir, "Sub")).toBe(false);
+  });
+});
+
+describe("collectDependencies", () => {
+  const awsPredicate = (obj: Record<string, unknown>): string | null => {
+    if (obj.__intrinsic === "Ref") {
+      const name = obj.name as string;
+      return name.startsWith("AWS::") ? null : name;
+    }
+    if (obj.__intrinsic === "GetAtt") {
+      return obj.logicalId as string;
+    }
+    return null;
+  };
+
+  test("collects Ref dependencies", () => {
+    const value = { x: { __intrinsic: "Ref", name: "MyBucket" } };
+    const deps = collectDependencies(value, awsPredicate);
+    expect(deps).toEqual(new Set(["MyBucket"]));
+  });
+
+  test("collects GetAtt dependencies", () => {
+    const value = { x: { __intrinsic: "GetAtt", logicalId: "MyBucket", attribute: "Arn" } };
+    const deps = collectDependencies(value, awsPredicate);
+    expect(deps).toEqual(new Set(["MyBucket"]));
+  });
+
+  test("skips AWS:: pseudo-parameters", () => {
+    const value = { x: { __intrinsic: "Ref", name: "AWS::Region" } };
+    const deps = collectDependencies(value, awsPredicate);
+    expect(deps.size).toBe(0);
+  });
+
+  test("collects from nested arrays and objects", () => {
+    const value = {
+      a: [
+        { __intrinsic: "Ref", name: "A" },
+        { nested: { __intrinsic: "GetAtt", logicalId: "B", attribute: "Arn" } },
+      ],
+    };
+    const deps = collectDependencies(value, awsPredicate);
+    expect(deps).toEqual(new Set(["A", "B"]));
+  });
+
+  test("deduplicates", () => {
+    const value = [
+      { __intrinsic: "Ref", name: "A" },
+      { __intrinsic: "Ref", name: "A" },
+    ];
+    const deps = collectDependencies(value, awsPredicate);
+    expect(deps).toEqual(new Set(["A"]));
+  });
+});

package/src/import/ir-utils.ts

@@ -0,0 +1,87 @@
+/**
+ * IR intrinsic scanning utilities.
+ *
+ * Generic recursive walkers that scan the import IR value trees for
+ * intrinsic markers and dependency references.
+ */
+
+import type { TemplateIR } from "./parser";
+
+/**
+ * Check if a value tree contains an intrinsic with the given name.
+ * Looks for `{ __intrinsic: name }` objects recursively.
+ */
+export function hasIntrinsicInValue(value: unknown, name: string): boolean {
+  if (value === null || value === undefined) {
+    return false;
+  }
+
+  if (Array.isArray(value)) {
+    return value.some((item) => hasIntrinsicInValue(item, name));
+  }
+
+  if (typeof value === "object") {
+    const obj = value as Record<string, unknown>;
+    if (obj.__intrinsic === name) {
+      return true;
+    }
+    return Object.values(obj).some((v) => hasIntrinsicInValue(v, name));
+  }
+
+  return false;
+}
+
+/**
+ * Check if any resource in the IR uses a given intrinsic.
+ */
+export function irUsesIntrinsic(ir: TemplateIR, name: string): boolean {
+  for (const resource of ir.resources) {
+    if (hasIntrinsicInValue(resource.properties, name)) {
+      return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * Collect dependency references from a value tree.
+ *
+ * @param value - The value tree to scan
+ * @param isDependency - Given an object, returns a logical ID if it represents
+ *   a dependency, or null otherwise. Each lexicon provides its own predicate.
+ */
+export function collectDependencies(
+  value: unknown,
+  isDependency: (obj: Record<string, unknown>) => string | null,
+): Set<string> {
+  const deps = new Set<string>();
+  collectDepsRecursive(value, isDependency, deps);
+  return deps;
+}
+
+function collectDepsRecursive(
+  value: unknown,
+  isDependency: (obj: Record<string, unknown>) => string | null,
+  deps: Set<string>,
+): void {
+  if (value === null || value === undefined) return;
+
+  if (Array.isArray(value)) {
+    for (const item of value) {
+      collectDepsRecursive(item, isDependency, deps);
+    }
+    return;
+  }
+
+  if (typeof value === "object") {
+    const obj = value as Record<string, unknown>;
+    const dep = isDependency(obj);
+    if (dep !== null) {
+      deps.add(dep);
+    } else {
+      for (const v of Object.values(obj)) {
+        collectDepsRecursive(v, isDependency, deps);
+      }
+    }
+  }
+}

package/src/import/parser.ts

@@ -0,0 +1,41 @@
+/**
+ * Intermediate representation of a template parameter
+ */
+export interface ParameterIR {
+  readonly name: string;
+  readonly type: string;
+  readonly description?: string;
+  readonly defaultValue?: unknown;
+  readonly required?: boolean;
+}
+
+/**
+ * Intermediate representation of a template resource
+ */
+export interface ResourceIR {
+  readonly logicalId: string;
+  readonly type: string;
+  readonly properties: Record<string, unknown>;
+  readonly metadata?: Record<string, unknown>;
+}
+
+/**
+ * Intermediate representation of a parsed template
+ */
+export interface TemplateIR {
+  readonly resources: ResourceIR[];
+  readonly parameters: ParameterIR[];
+  readonly metadata?: Record<string, unknown>;
+}
+
+/**
+ * Interface for template parsers that convert external formats to IR
+ */
+export interface TemplateParser {
+  /**
+   * Parse template content into intermediate representation
+   * @param content - Raw template content (JSON, YAML, etc.)
+   * @returns Intermediate representation of the template
+   */
+  parse(content: string): TemplateIR;
+}

package/src/index.ts

@@ -0,0 +1,60 @@
+/**
+ * chant Core
+ *
+ * Lexicon-agnostic declarative specification system
+ */
+
+export * from "./declarable";
+export * from "./composite";
+export * from "./intrinsic";
+export * from "./types";
+export * from "./errors";
+export * from "./attrref";
+export * from "./utils";
+export * from "./builder";
+export * from "./serializer";
+export * from "./lexicon-output";
+export * from "./discovery/files";
+export * from "./discovery/import";
+export * from "./discovery/collect";
+export * from "./discovery/cycles";
+export * from "./sort";
+export * from "./discovery/resolve";
+export * from "./discovery/graph";
+export * from "./discovery/index";
+export * from "./discovery/cache";
+export * from "./build";
+export * from "./detectLexicon";
+export * from "./lint/parser";
+export * from "./lint/rule";
+export * from "./lint/rules";
+export * from "./lint/declarative";
+export * from "./lint/selectors";
+export * from "./lint/named-checks";
+export * from "./lint/post-synth";
+export * from "./lint/rule-loader";
+export * from "./import/parser";
+export * from "./import/generator";
+export * from "./lexicon";
+export * from "./lexicon-integrity";
+export * from "./lexicon-manifest";
+export * from "./lexicon-schema";
+export * from "./config";
+export * from "./validation";
+export * from "./project-validation";
+export { barrel } from "./barrel";
+export * from "./codegen/naming";
+export * from "./codegen/fetch";
+export * from "./codegen/generate";
+export * from "./codegen/package";
+export * from "./codegen/typecheck";
+export * from "./codegen/rollback";
+export * from "./codegen/coverage";
+export * from "./codegen/validate";
+export * from "./codegen/docs";
+export * from "./runtime";
+export * from "./stack-output";
+export * from "./child-project";
+export * from "./lsp/types";
+export * from "./lsp/lexicon-providers";
+export * from "./mcp/types";

package/src/intrinsic-interpolation.test.ts

@@ -0,0 +1,91 @@
+import { describe, expect, test } from "bun:test";
+import { buildInterpolatedString, defaultInterpolationSerializer } from "./intrinsic-interpolation";
+import { AttrRef } from "./attrref";
+import { INTRINSIC_MARKER } from "./intrinsic";
+import { DECLARABLE_MARKER } from "./declarable";
+
+describe("buildInterpolatedString", () => {
+  test("joins parts and values with serializer", () => {
+    const result = buildInterpolatedString(
+      ["Hello ", " world ", "!"],
+      ["foo", "bar"],
+      (v) => `<${v}>`,
+    );
+    expect(result).toBe("Hello <foo> world <bar>!");
+  });
+
+  test("handles no values", () => {
+    const result = buildInterpolatedString(
+      ["just text"],
+      [],
+      () => { throw new Error("should not be called"); },
+    );
+    expect(result).toBe("just text");
+  });
+
+  test("handles empty parts", () => {
+    const result = buildInterpolatedString(
+      ["", ""],
+      ["only"],
+      (v) => String(v),
+    );
+    expect(result).toBe("only");
+  });
+});
+
+describe("defaultInterpolationSerializer", () => {
+  const serialize = defaultInterpolationSerializer(
+    (name, attr) => `\${${name}.${attr}}`,
+    (ref) => `\${${ref}}`,
+  );
+
+  test("serializes AttrRef", () => {
+    const parent = {};
+    const ref = new AttrRef(parent, "Arn");
+    ref._setLogicalName("MyBucket");
+
+    expect(serialize(ref)).toBe("${MyBucket.Arn}");
+  });
+
+  test("throws for AttrRef without logical name", () => {
+    const parent = {};
+    const ref = new AttrRef(parent, "Arn");
+
+    expect(() => serialize(ref)).toThrow("logical name not set");
+  });
+
+  test("serializes Intrinsic with Ref toJSON", () => {
+    const intrinsic = {
+      [INTRINSIC_MARKER]: true as const,
+      toJSON: () => ({ Ref: "AWS::Region" }),
+    };
+
+    expect(serialize(intrinsic)).toBe("${AWS::Region}");
+  });
+
+  test("serializes Intrinsic with non-Ref toJSON as String", () => {
+    const intrinsic = {
+      [INTRINSIC_MARKER]: true as const,
+      toJSON: () => ({ "Fn::Sub": "hello" }),
+      toString: () => "[SubIntrinsic]",
+    };
+
+    expect(serialize(intrinsic)).toBe("[SubIntrinsic]");
+  });
+
+  test("throws for Declarable", () => {
+    const declarable = {
+      [DECLARABLE_MARKER]: true as const,
+      lexicon: "test",
+      entityType: "Bucket",
+    };
+
+    expect(() => serialize(declarable)).toThrow("Cannot embed Declarable");
+  });
+
+  test("serializes primitives via String()", () => {
+    expect(serialize("hello")).toBe("hello");
+    expect(serialize(42)).toBe("42");
+    expect(serialize(true)).toBe("true");
+  });
+});

package/src/intrinsic-interpolation.ts

@@ -0,0 +1,89 @@
+/**
+ * Tagged template interpolation helper.
+ *
+ * Implements the lockstep walk over tagged template literal parts/values,
+ * dispatching on AttrRef / Intrinsic / Declarable / primitive.
+ * Each lexicon provides format-specific serialization strings.
+ */
+
+import { AttrRef } from "./attrref";
+import { INTRINSIC_MARKER } from "./intrinsic";
+import { DECLARABLE_MARKER } from "./declarable";
+
+export type InterpolationValueSerializer = (value: unknown) => string;
+
+/**
+ * Default serialization dispatch for interpolated values.
+ *
+ * Handles: AttrRef → Intrinsic (with Ref special case) → Declarable (throws) → primitive.
+ * Lexicons can wrap/extend this for format-specific behavior.
+ *
+ * @param serializeAttrRef - Format an AttrRef: (logicalName, attribute) → string
+ * @param serializeRef - Format a Ref intrinsic: (refName) → string
+ */
+export function defaultInterpolationSerializer(
+  serializeAttrRef: (logicalName: string, attribute: string) => string,
+  serializeRef: (refName: string) => string,
+): InterpolationValueSerializer {
+  return (value: unknown): string => {
+    // Handle AttrRef
+    if (value instanceof AttrRef) {
+      const logicalName = value.getLogicalName();
+      if (!logicalName) {
+        throw new Error(
+          `Cannot serialize AttrRef for attribute "${value.attribute}": logical name not set`,
+        );
+      }
+      return serializeAttrRef(logicalName, value.attribute);
+    }
+
+    // Handle Intrinsics with toJSON
+    if (
+      typeof value === "object" &&
+      value !== null &&
+      INTRINSIC_MARKER in value &&
+      "toJSON" in value &&
+      typeof value.toJSON === "function"
+    ) {
+      const result = value.toJSON();
+      // If it's a Ref, use the ref serializer
+      if (typeof result === "object" && result !== null && "Ref" in result) {
+        return serializeRef((result as { Ref: string }).Ref);
+      }
+      return String(value);
+    }
+
+    // Handle Declarables — error
+    if (
+      typeof value === "object" &&
+      value !== null &&
+      DECLARABLE_MARKER in value
+    ) {
+      throw new Error(
+        "Cannot embed Declarable directly in Sub template. Use AttrRef instead.",
+      );
+    }
+
+    // Primitive
+    return String(value);
+  };
+}
+
+/**
+ * Walk tagged template literal parts/values in lockstep,
+ * serializing each value via the provided serializer.
+ */
+export function buildInterpolatedString(
+  templateParts: readonly string[],
+  values: readonly unknown[],
+  serializeValue: InterpolationValueSerializer,
+): string {
+  let result = "";
+  for (let i = 0; i < templateParts.length; i++) {
+    result += templateParts[i];
+    if (i < values.length) {
+      result += serializeValue(values[i]);
+    }
+  }
+  return result;
+}

package/src/intrinsic.test.ts

@@ -0,0 +1,69 @@
+import { describe, test, expect } from "bun:test";
+import { INTRINSIC_MARKER, resolveIntrinsicValue, isIntrinsic } from "./intrinsic";
+
+describe("resolveIntrinsicValue", () => {
+  test("returns primitives as-is", () => {
+    expect(resolveIntrinsicValue(42)).toBe(42);
+    expect(resolveIntrinsicValue("hello")).toBe("hello");
+    expect(resolveIntrinsicValue(true)).toBe(true);
+    expect(resolveIntrinsicValue(null)).toBe(null);
+    expect(resolveIntrinsicValue(undefined)).toBe(undefined);
+  });
+
+  test("returns plain objects as-is", () => {
+    const obj = { a: 1 };
+    expect(resolveIntrinsicValue(obj)).toBe(obj);
+  });
+
+  test("calls toJSON on intrinsic objects", () => {
+    const intrinsic = {
+      [INTRINSIC_MARKER]: true as const,
+      toJSON: () => ({ Ref: "MyResource" }),
+    };
+    expect(resolveIntrinsicValue(intrinsic)).toEqual({ Ref: "MyResource" });
+  });
+
+  test("recurses into arrays", () => {
+    const intrinsic = {
+      [INTRINSIC_MARKER]: true as const,
+      toJSON: () => ({ Ref: "A" }),
+    };
+    const result = resolveIntrinsicValue(["hello", intrinsic, 42]);
+    expect(result).toEqual(["hello", { Ref: "A" }, 42]);
+  });
+
+  test("recurses into nested arrays", () => {
+    const intrinsic = {
+      [INTRINSIC_MARKER]: true as const,
+      toJSON: () => "resolved",
+    };
+    const result = resolveIntrinsicValue([[intrinsic], "plain"]);
+    expect(result).toEqual([["resolved"], "plain"]);
+  });
+
+  test("does not call toJSON on non-intrinsic objects with toJSON", () => {
+    const obj = { toJSON: () => "should not be called" };
+    expect(resolveIntrinsicValue(obj)).toBe(obj);
+  });
+
+  test("handles intrinsic without toJSON gracefully", () => {
+    const intrinsic = { [INTRINSIC_MARKER]: true as const };
+    expect(resolveIntrinsicValue(intrinsic)).toBe(intrinsic);
+  });
+});
+
+describe("isIntrinsic", () => {
+  test("returns true for intrinsic objects", () => {
+    const intrinsic = {
+      [INTRINSIC_MARKER]: true as const,
+      toJSON: () => ({}),
+    };
+    expect(isIntrinsic(intrinsic)).toBe(true);
+  });
+
+  test("returns false for plain objects", () => {
+    expect(isIntrinsic({})).toBe(false);
+    expect(isIntrinsic(null)).toBe(false);
+    expect(isIntrinsic("string")).toBe(false);
+  });
+});

package/src/intrinsic.ts

@@ -0,0 +1,43 @@
+/**
+ * Marker symbol for Intrinsic type identification
+ */
+export const INTRINSIC_MARKER = Symbol.for("chant.intrinsic");
+
+/**
+ * Base interface for lexicon-provided intrinsic functions
+ */
+export interface Intrinsic {
+  readonly [INTRINSIC_MARKER]: true;
+  toJSON(): unknown;
+}
+
+/**
+ * Type guard to check if a value is an Intrinsic
+ */
+export function isIntrinsic(value: unknown): value is Intrinsic {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    INTRINSIC_MARKER in value &&
+    (value as Record<symbol, unknown>)[INTRINSIC_MARKER] === true
+  );
+}
+
+/**
+ * Recursively unwrap intrinsic values by calling `toJSON()`.
+ *
+ * - If the value has the INTRINSIC_MARKER and a `toJSON` method, calls it.
+ * - If the value is an array, recurses into each element.
+ * - Otherwise returns the value as-is.
+ */
+export function resolveIntrinsicValue(value: unknown): unknown {
+  if (value !== null && typeof value === "object" && INTRINSIC_MARKER in value) {
+    if ("toJSON" in value && typeof value.toJSON === "function") {
+      return value.toJSON();
+    }
+  }
+  if (Array.isArray(value)) {
+    return value.map(resolveIntrinsicValue);
+  }
+  return value;
+}

package/src/lexicon-integrity.test.ts

@@ -0,0 +1,94 @@
+import { describe, test, expect } from "bun:test";
+import { hashArtifact, computeIntegrity, verifyIntegrity, type ArtifactIntegrity } from "./lexicon-integrity";
+import type { BundleSpec } from "./lexicon";
+
+describe("hashArtifact", () => {
+  test("returns hex string", () => {
+    const hash = hashArtifact("hello world");
+    expect(hash).toMatch(/^[0-9a-f]+$/);
+  });
+
+  test("is deterministic", () => {
+    const a = hashArtifact("test content");
+    const b = hashArtifact("test content");
+    expect(a).toBe(b);
+  });
+
+  test("different inputs produce different hashes", () => {
+    const a = hashArtifact("content-a");
+    const b = hashArtifact("content-b");
+    expect(a).not.toBe(b);
+  });
+});
+
+function makeSpec(overrides?: Partial<BundleSpec>): BundleSpec {
+  return {
+    manifest: { name: "test", version: "1.0.0" },
+    registry: '{"Bucket":{"kind":"resource","resourceType":"TestDom::Storage::Bucket","lexicon":"testdom"}}',
+    typesDTS: "declare class Bucket {}",
+    rules: new Map([["rule1.ts", "export const rule1 = {};"]]),
+    skills: new Map([["skill1.md", "# Skill 1"]]),
+    ...overrides,
+  };
+}
+
+describe("computeIntegrity", () => {
+  test("returns xxhash64 algorithm", () => {
+    const integrity = computeIntegrity(makeSpec());
+    expect(integrity.algorithm).toBe("xxhash64");
+  });
+
+  test("hashes all artifacts", () => {
+    const integrity = computeIntegrity(makeSpec());
+    expect(integrity.artifacts["manifest.json"]).toBeDefined();
+    expect(integrity.artifacts["meta.json"]).toBeDefined();
+    expect(integrity.artifacts["types/index.d.ts"]).toBeDefined();
+    expect(integrity.artifacts["rules/rule1.ts"]).toBeDefined();
+    expect(integrity.artifacts["skills/skill1.md"]).toBeDefined();
+  });
+
+  test("composite hash is deterministic", () => {
+    const a = computeIntegrity(makeSpec());
+    const b = computeIntegrity(makeSpec());
+    expect(a.composite).toBe(b.composite);
+  });
+
+  test("composite changes when any artifact changes", () => {
+    const original = computeIntegrity(makeSpec());
+    const modified = computeIntegrity(makeSpec({ registry: '{"different": true}' }));
+    expect(original.composite).not.toBe(modified.composite);
+  });
+});
+
+describe("verifyIntegrity", () => {
+  test("passes for matching spec", () => {
+    const spec = makeSpec();
+    const integrity = computeIntegrity(spec);
+    const result = verifyIntegrity(spec, integrity);
+    expect(result.ok).toBe(true);
+    expect(result.mismatches).toHaveLength(0);
+  });
+
+  test("detects tampered artifact", () => {
+    const spec = makeSpec();
+    const integrity = computeIntegrity(spec);
+
+    // Tamper with the registry
+    const tampered = makeSpec({ registry: '{"tampered": true}' });
+    const result = verifyIntegrity(tampered, integrity);
+    expect(result.ok).toBe(false);
+    expect(result.mismatches).toContain("meta.json");
+  });
+
+  test("detects extra artifacts", () => {
+    const spec = makeSpec();
+    const integrity = computeIntegrity(spec);
+
+    // Add an extra rule
+    const modified = makeSpec();
+    modified.rules.set("extra.ts", "extra content");
+    const result = verifyIntegrity(modified, integrity);
+    expect(result.ok).toBe(false);
+    expect(result.mismatches).toContain("rules/extra.ts");
+  });
+});