@intentius/chant 0.0.1

package/src/lexicon-integrity.ts

@@ -0,0 +1,69 @@
+/**
+ * Content hashing and integrity verification for lexicon artifacts.
+ */
+import type { BundleSpec } from "./lexicon";
+
+export interface ArtifactIntegrity {
+  algorithm: "xxhash64";
+  artifacts: Record<string, string>;
+  composite: string;
+}
+
+/**
+ * Hash a single artifact's content using xxhash64.
+ */
+export function hashArtifact(content: string): string {
+  return Bun.hash(content).toString(16);
+}
+
+/**
+ * Compute integrity for all artifacts in a BundleSpec.
+ */
+export function computeIntegrity(spec: BundleSpec): ArtifactIntegrity {
+  const artifacts: Record<string, string> = {};
+
+  // Hash each artifact
+  artifacts["manifest.json"] = hashArtifact(JSON.stringify(spec.manifest, null, 2));
+  artifacts["meta.json"] = hashArtifact(spec.registry);
+  artifacts["types/index.d.ts"] = hashArtifact(spec.typesDTS);
+
+  for (const [name, content] of spec.rules) {
+    artifacts[`rules/${name}`] = hashArtifact(content);
+  }
+  for (const [name, content] of spec.skills) {
+    artifacts[`skills/${name}`] = hashArtifact(content);
+  }
+
+  // Composite hash: sorted key:hash pairs
+  const sorted = Object.entries(artifacts).sort(([a], [b]) => a.localeCompare(b));
+  const compositeInput = sorted.map(([k, v]) => `${k}:${v}`).join("\n");
+  const composite = hashArtifact(compositeInput);
+
+  return { algorithm: "xxhash64", artifacts, composite };
+}
+
+/**
+ * Verify integrity of a BundleSpec against expected hashes.
+ */
+export function verifyIntegrity(
+  spec: BundleSpec,
+  expected: ArtifactIntegrity,
+): { ok: boolean; mismatches: string[] } {
+  const actual = computeIntegrity(spec);
+  const mismatches: string[] = [];
+
+  for (const [key, expectedHash] of Object.entries(expected.artifacts)) {
+    if (actual.artifacts[key] !== expectedHash) {
+      mismatches.push(key);
+    }
+  }
+
+  // Check for artifacts in actual but not in expected
+  for (const key of Object.keys(actual.artifacts)) {
+    if (!(key in expected.artifacts)) {
+      mismatches.push(key);
+    }
+  }
+
+  return { ok: mismatches.length === 0, mismatches };
+}

package/src/lexicon-manifest.test.ts

@@ -0,0 +1,101 @@
+import { describe, test, expect } from "bun:test";
+import { validateManifest } from "./lexicon-schema";
+import { checkVersionCompatibility } from "./lexicon-manifest";
+
+describe("validateManifest", () => {
+  test("parses valid manifest object", () => {
+    const m = validateManifest({
+      name: "testdom",
+      version: "1.0.0",
+      chantVersion: ">=0.1.0",
+      namespace: "TST",
+      intrinsics: [{ name: "Interpolate", outputKey: "Fn::Interpolate", isTag: true }],
+      pseudoParameters: { StackName: "TestDom::StackName" },
+    });
+    expect(m.name).toBe("testdom");
+    expect(m.version).toBe("1.0.0");
+    expect(m.chantVersion).toBe(">=0.1.0");
+    expect(m.namespace).toBe("TST");
+    expect(m.intrinsics).toHaveLength(1);
+    expect(m.pseudoParameters?.StackName).toBe("TestDom::StackName");
+  });
+
+  test("parses valid JSON string", () => {
+    const m = validateManifest(JSON.stringify({ name: "testdom", version: "0.1.0" }));
+    expect(m.name).toBe("testdom");
+    expect(m.version).toBe("0.1.0");
+  });
+
+  test("optional chantVersion", () => {
+    const m = validateManifest({ name: "gcp", version: "2.0.0" });
+    expect(m.chantVersion).toBeUndefined();
+  });
+
+  test("throws on empty data", () => {
+    expect(() => validateManifest(null)).toThrow("empty");
+    expect(() => validateManifest(undefined)).toThrow("empty");
+  });
+
+  test("throws on invalid JSON string", () => {
+    expect(() => validateManifest("{bad json")).toThrow("invalid JSON");
+  });
+
+  test("throws on missing name", () => {
+    expect(() => validateManifest({ version: "1.0.0" })).toThrow("name");
+  });
+
+  test("throws on missing version", () => {
+    expect(() => validateManifest({ name: "testdom" })).toThrow("version");
+  });
+
+  test("throws on non-object", () => {
+    expect(() => validateManifest(42)).toThrow("must be a JSON object");
+    expect(() => validateManifest([])).toThrow("must be a JSON object");
+  });
+});
+
+describe("checkVersionCompatibility", () => {
+  test(">= operator", () => {
+    expect(checkVersionCompatibility(">=0.1.0", "0.1.0")).toBe(true);
+    expect(checkVersionCompatibility(">=0.1.0", "0.2.0")).toBe(true);
+    expect(checkVersionCompatibility(">=0.1.0", "1.0.0")).toBe(true);
+    expect(checkVersionCompatibility(">=0.2.0", "0.1.0")).toBe(false);
+  });
+
+  test("<= operator", () => {
+    expect(checkVersionCompatibility("<=1.0.0", "1.0.0")).toBe(true);
+    expect(checkVersionCompatibility("<=1.0.0", "0.9.0")).toBe(true);
+    expect(checkVersionCompatibility("<=1.0.0", "1.1.0")).toBe(false);
+  });
+
+  test("> operator", () => {
+    expect(checkVersionCompatibility(">0.1.0", "0.2.0")).toBe(true);
+    expect(checkVersionCompatibility(">0.1.0", "0.1.0")).toBe(false);
+  });
+
+  test("< operator", () => {
+    expect(checkVersionCompatibility("<1.0.0", "0.9.0")).toBe(true);
+    expect(checkVersionCompatibility("<1.0.0", "1.0.0")).toBe(false);
+  });
+
+  test("= operator and bare version (exact match)", () => {
+    expect(checkVersionCompatibility("=1.0.0", "1.0.0")).toBe(true);
+    expect(checkVersionCompatibility("=1.0.0", "1.0.1")).toBe(false);
+    expect(checkVersionCompatibility("1.0.0", "1.0.0")).toBe(true);
+    expect(checkVersionCompatibility("1.0.0", "1.0.1")).toBe(false);
+  });
+
+  test("empty range always passes", () => {
+    expect(checkVersionCompatibility("", "1.0.0")).toBe(true);
+    expect(checkVersionCompatibility("  ", "1.0.0")).toBe(true);
+  });
+
+  test("invalid version returns false", () => {
+    expect(checkVersionCompatibility(">=abc", "1.0.0")).toBe(false);
+    expect(checkVersionCompatibility(">=1.0.0", "abc")).toBe(false);
+  });
+
+  test("two-part version", () => {
+    expect(checkVersionCompatibility(">=0.1", "0.1.0")).toBe(true);
+  });
+});

package/src/lexicon-manifest.ts

@@ -0,0 +1,71 @@
+/**
+ * Lexicon manifest validation and version compatibility checking.
+ */
+
+/**
+ * Check if the current version satisfies a semver range requirement.
+ * Supports: >=X.Y.Z, <=X.Y.Z, >X.Y.Z, <X.Y.Z, =X.Y.Z, X.Y.Z (exact match)
+ */
+export function checkVersionCompatibility(required: string, current: string): boolean {
+  const trimmed = required.trim();
+  if (!trimmed) return true;
+
+  let op: string;
+  let versionStr: string;
+
+  if (trimmed.startsWith(">=")) {
+    op = ">=";
+    versionStr = trimmed.slice(2).trim();
+  } else if (trimmed.startsWith("<=")) {
+    op = "<=";
+    versionStr = trimmed.slice(2).trim();
+  } else if (trimmed.startsWith(">")) {
+    op = ">";
+    versionStr = trimmed.slice(1).trim();
+  } else if (trimmed.startsWith("<")) {
+    op = "<";
+    versionStr = trimmed.slice(1).trim();
+  } else if (trimmed.startsWith("=")) {
+    op = "=";
+    versionStr = trimmed.slice(1).trim();
+  } else {
+    op = "=";
+    versionStr = trimmed;
+  }
+
+  const requiredParts = parseVersion(versionStr);
+  const currentParts = parseVersion(current.trim());
+
+  if (!requiredParts || !currentParts) return false;
+
+  const cmp = compareVersions(currentParts, requiredParts);
+
+  switch (op) {
+    case ">=": return cmp >= 0;
+    case "<=": return cmp <= 0;
+    case ">":  return cmp > 0;
+    case "<":  return cmp < 0;
+    case "=":  return cmp === 0;
+    default:   return false;
+  }
+}
+
+function parseVersion(v: string): [number, number, number] | null {
+  // Strip leading 'v'
+  if (v.startsWith("v")) v = v.slice(1);
+
+  const parts = v.split(".");
+  if (parts.length < 2 || parts.length > 3) return null;
+
+  const nums = parts.map(Number);
+  if (nums.some(isNaN)) return null;
+
+  return [nums[0], nums[1], nums[2] ?? 0];
+}
+
+function compareVersions(a: [number, number, number], b: [number, number, number]): number {
+  for (let i = 0; i < 3; i++) {
+    if (a[i] !== b[i]) return a[i] - b[i];
+  }
+  return 0;
+}

package/src/lexicon-output.test.ts

@@ -0,0 +1,182 @@
+import { describe, test, expect } from "bun:test";
+import { LexiconOutput, output, isLexiconOutput } from "./lexicon-output";
+import { AttrRef } from "./attrref";
+import { INTRINSIC_MARKER } from "./intrinsic";
+import { DECLARABLE_MARKER } from "./declarable";
+import { collectLexiconOutputs } from "./build";
+import type { Declarable } from "./declarable";
+
+// Mock entity with lexicon field
+class MockResource {
+  readonly [DECLARABLE_MARKER] = true as const;
+  readonly lexicon = "testdom";
+  readonly entityType = "TestDom::Storage::Bucket";
+  readonly arn: AttrRef;
+  readonly props: Record<string, unknown>;
+
+  constructor() {
+    this.arn = new AttrRef(this, "Arn");
+    this.props = {};
+  }
+}
+
+describe("LexiconOutput", () => {
+  test("implements Intrinsic marker", () => {
+    const bucket = new MockResource();
+    const lexiconOutput = new LexiconOutput(bucket.arn, "DataBucketArn");
+
+    expect(lexiconOutput[INTRINSIC_MARKER]).toBe(true);
+  });
+
+  test("extracts sourceLexicon from parent entity", () => {
+    const bucket = new MockResource();
+    const lexiconOutput = new LexiconOutput(bucket.arn, "DataBucketArn");
+
+    expect(lexiconOutput.sourceLexicon).toBe("testdom");
+  });
+
+  test("extracts sourceAttribute from AttrRef", () => {
+    const bucket = new MockResource();
+    const lexiconOutput = new LexiconOutput(bucket.arn, "DataBucketArn");
+
+    expect(lexiconOutput.sourceAttribute).toBe("Arn");
+  });
+
+  test("stores outputName", () => {
+    const bucket = new MockResource();
+    const lexiconOutput = new LexiconOutput(bucket.arn, "DataBucketArn");
+
+    expect(lexiconOutput.outputName).toBe("DataBucketArn");
+  });
+
+  test("sourceEntity starts empty and can be set internally", () => {
+    const bucket = new MockResource();
+    const lexiconOutput = new LexiconOutput(bucket.arn, "DataBucketArn");
+
+    expect(lexiconOutput.sourceEntity).toBe("");
+    lexiconOutput._setSourceEntity("dataBucket");
+    expect(lexiconOutput.sourceEntity).toBe("dataBucket");
+  });
+
+  test("toJSON serializes to chant::output marker", () => {
+    const bucket = new MockResource();
+    const lexiconOutput = new LexiconOutput(bucket.arn, "DataBucketArn");
+
+    expect(lexiconOutput.toJSON()).toEqual({ "chant::output": "DataBucketArn" });
+  });
+
+  test("throws when parent has no lexicon field", () => {
+    const noLexiconParent = {};
+    const ref = new AttrRef(noLexiconParent, "Arn");
+
+    expect(() => new LexiconOutput(ref, "Test")).toThrow("no lexicon field");
+  });
+});
+
+describe("LexiconOutput.auto", () => {
+  test("creates output with auto-generated name from entity and attribute", () => {
+    const bucket = new MockResource();
+    const result = LexiconOutput.auto(bucket.arn, "dataBucket");
+
+    expect(result).toBeInstanceOf(LexiconOutput);
+    expect(result.outputName).toBe("dataBucket_Arn");
+    expect(result.sourceLexicon).toBe("testdom");
+    expect(result.sourceEntity).toBe("dataBucket");
+    expect(result.sourceAttribute).toBe("Arn");
+  });
+
+  test("auto-generated name follows {entityName}_{attribute} pattern", () => {
+    const bucket = new MockResource();
+    const endpointRef = new AttrRef(bucket, "Endpoint");
+    const result = LexiconOutput.auto(endpointRef, "myBucket");
+
+    expect(result.outputName).toBe("myBucket_Endpoint");
+  });
+
+  test("sets sourceEntity immediately", () => {
+    const bucket = new MockResource();
+    const result = LexiconOutput.auto(bucket.arn, "logsBucket");
+
+    // sourceEntity should be set right away, not empty
+    expect(result.sourceEntity).toBe("logsBucket");
+  });
+});
+
+describe("output() helper", () => {
+  test("creates LexiconOutput from AttrRef and name", () => {
+    const bucket = new MockResource();
+    const result = output(bucket.arn, "DataBucketArn");
+
+    expect(result).toBeInstanceOf(LexiconOutput);
+    expect(result.sourceLexicon).toBe("testdom");
+    expect(result.sourceAttribute).toBe("Arn");
+    expect(result.outputName).toBe("DataBucketArn");
+  });
+});
+
+describe("isLexiconOutput", () => {
+  test("returns true for LexiconOutput instances", () => {
+    const bucket = new MockResource();
+    const lexiconOutput = new LexiconOutput(bucket.arn, "DataBucketArn");
+
+    expect(isLexiconOutput(lexiconOutput)).toBe(true);
+  });
+
+  test("returns false for non-LexiconOutput values", () => {
+    expect(isLexiconOutput(null)).toBe(false);
+    expect(isLexiconOutput(undefined)).toBe(false);
+    expect(isLexiconOutput("string")).toBe(false);
+    expect(isLexiconOutput(42)).toBe(false);
+    expect(isLexiconOutput({})).toBe(false);
+  });
+
+  test("returns false for AttrRef", () => {
+    const parent = { lexicon: "testdom" };
+    const ref = new AttrRef(parent, "Arn");
+
+    expect(isLexiconOutput(ref)).toBe(false);
+  });
+});
+
+describe("collectLexiconOutputs", () => {
+  test("collects LexiconOutputs from entity props", () => {
+    const bucket = new MockResource();
+    const lexiconOutput = output(bucket.arn, "DataBucketArn");
+    bucket.props.outputRef = lexiconOutput;
+
+    const entities = new Map<string, Declarable>();
+    entities.set("dataBucket", bucket as unknown as Declarable);
+
+    const collected = collectLexiconOutputs(entities);
+
+    expect(collected).toHaveLength(1);
+    expect(collected[0].outputName).toBe("DataBucketArn");
+    expect(collected[0].sourceEntity).toBe("dataBucket");
+  });
+
+  test("returns empty array when no LexiconOutputs found", () => {
+    const entities = new Map<string, Declarable>();
+    entities.set("bucket", {
+      lexicon: "testdom",
+      entityType: "TestDom::Storage::Bucket",
+      [DECLARABLE_MARKER]: true,
+    } as Declarable);
+
+    const collected = collectLexiconOutputs(entities);
+    expect(collected).toHaveLength(0);
+  });
+
+  test("collects LexiconOutputs from nested props", () => {
+    const bucket = new MockResource();
+    const lexiconOutput = output(bucket.arn, "BucketArn");
+    bucket.props.nested = { deep: { ref: lexiconOutput } };
+
+    const entities = new Map<string, Declarable>();
+    entities.set("dataBucket", bucket as unknown as Declarable);
+
+    const collected = collectLexiconOutputs(entities);
+
+    expect(collected).toHaveLength(1);
+    expect(collected[0].outputName).toBe("BucketArn");
+  });
+});

package/src/lexicon-output.ts

@@ -0,0 +1,82 @@
+import { INTRINSIC_MARKER, type Intrinsic } from "./intrinsic";
+import { AttrRef } from "./attrref";
+
+/**
+ * Represents a cross-lexicon output that bridges a producing lexicon (e.g. AWS)
+ * with any consuming lexicon (e.g. GitHub, Cloudflare).
+ *
+ * Implements Intrinsic so it can be used as Value<string> anywhere.
+ */
+export class LexiconOutput implements Intrinsic {
+  readonly [INTRINSIC_MARKER] = true as const;
+  readonly sourceLexicon: string;
+  readonly sourceEntity: string;
+  readonly sourceAttribute: string;
+  readonly outputName: string;
+  /** @internal WeakRef to the source entity object for identity-based matching */
+  readonly _sourceParent: WeakRef<object>;
+
+  constructor(ref: AttrRef, name: string) {
+    const parent = ref.parent.deref();
+    if (!parent) {
+      throw new Error("Cannot create LexiconOutput: parent entity has been garbage collected");
+    }
+
+    if (!("lexicon" in parent) || typeof (parent as Record<string, unknown>).lexicon !== "string") {
+      throw new Error("Cannot create LexiconOutput: parent entity has no lexicon field");
+    }
+
+    this.sourceLexicon = (parent as Record<string, unknown>).lexicon as string;
+    this.sourceEntity = "";
+    this.sourceAttribute = ref.attribute;
+    this.outputName = name;
+    this._sourceParent = ref.parent;
+  }
+
+  /**
+   * Set the source entity logical name.
+   * Called during build when entity names are resolved.
+   * @internal
+   */
+  _setSourceEntity(name: string): void {
+    (this as { sourceEntity: string }).sourceEntity = name;
+  }
+
+  /**
+   * Create a LexiconOutput with an auto-generated name from entity name and attribute.
+   * Used during cross-lexicon ref auto-detection.
+   *
+   * @param ref - The AttrRef pointing to the source entity
+   * @param entityName - The logical name of the source entity
+   * @returns A LexiconOutput with name `{entityName}_{attribute}`
+   */
+  static auto(ref: AttrRef, entityName: string): LexiconOutput {
+    const name = `${entityName}_${ref.attribute}`;
+    const output = new LexiconOutput(ref, name);
+    output._setSourceEntity(entityName);
+    return output;
+  }
+
+  toJSON(): { "chant::output": string } {
+    return { "chant::output": this.outputName };
+  }
+}
+
+/**
+ * Create a LexiconOutput from an AttrRef and a user-provided output name.
+ *
+ * Usage:
+ * ```ts
+ * const bucketArn = output(dataBucket.arn, "DataBucketArn");
+ * ```
+ */
+export function output(ref: AttrRef, name: string): LexiconOutput {
+  return new LexiconOutput(ref, name);
+}
+
+/**
+ * Type guard to check if a value is a LexiconOutput
+ */
+export function isLexiconOutput(value: unknown): value is LexiconOutput {
+  return value instanceof LexiconOutput;
+}