@intentius/chant 0.0.1

package/src/codegen/json-patch.test.ts

@@ -0,0 +1,113 @@
+import { describe, test, expect } from "bun:test";
+import { rfc6902Apply } from "./json-patch";
+
+describe("rfc6902Apply", () => {
+  test("add to object", () => {
+    const doc = JSON.stringify({ a: 1 });
+    const patch = JSON.stringify([{ op: "add", path: "/b", value: 2 }]);
+    expect(JSON.parse(rfc6902Apply(doc, patch))).toEqual({ a: 1, b: 2 });
+  });
+
+  test("add to nested object", () => {
+    const doc = JSON.stringify({ a: { b: 1 } });
+    const patch = JSON.stringify([{ op: "add", path: "/a/c", value: 2 }]);
+    expect(JSON.parse(rfc6902Apply(doc, patch))).toEqual({ a: { b: 1, c: 2 } });
+  });
+
+  test("add to array with -", () => {
+    const doc = JSON.stringify({ a: [1, 2] });
+    const patch = JSON.stringify([{ op: "add", path: "/a/-", value: 3 }]);
+    expect(JSON.parse(rfc6902Apply(doc, patch))).toEqual({ a: [1, 2, 3] });
+  });
+
+  test("add to array by index", () => {
+    const doc = JSON.stringify({ a: [1, 3] });
+    const patch = JSON.stringify([{ op: "add", path: "/a/1", value: 2 }]);
+    expect(JSON.parse(rfc6902Apply(doc, patch))).toEqual({ a: [1, 2, 3] });
+  });
+
+  test("add replaces root when path is empty", () => {
+    const doc = JSON.stringify({ a: 1 });
+    const patch = JSON.stringify([{ op: "add", path: "", value: { b: 2 } }]);
+    expect(JSON.parse(rfc6902Apply(doc, patch))).toEqual({ b: 2 });
+  });
+
+  test("remove from object", () => {
+    const doc = JSON.stringify({ a: 1, b: 2 });
+    const patch = JSON.stringify([{ op: "remove", path: "/b" }]);
+    expect(JSON.parse(rfc6902Apply(doc, patch))).toEqual({ a: 1 });
+  });
+
+  test("remove from array", () => {
+    const doc = JSON.stringify({ a: [1, 2, 3] });
+    const patch = JSON.stringify([{ op: "remove", path: "/a/1" }]);
+    expect(JSON.parse(rfc6902Apply(doc, patch))).toEqual({ a: [1, 3] });
+  });
+
+  test("remove root throws", () => {
+    const doc = JSON.stringify({ a: 1 });
+    const patch = JSON.stringify([{ op: "remove", path: "" }]);
+    expect(() => rfc6902Apply(doc, patch)).toThrow("cannot remove root");
+  });
+
+  test("replace in object", () => {
+    const doc = JSON.stringify({ a: 1, b: 2 });
+    const patch = JSON.stringify([{ op: "replace", path: "/a", value: 99 }]);
+    expect(JSON.parse(rfc6902Apply(doc, patch))).toEqual({ a: 99, b: 2 });
+  });
+
+  test("replace in array", () => {
+    const doc = JSON.stringify({ a: [1, 2, 3] });
+    const patch = JSON.stringify([{ op: "replace", path: "/a/1", value: 99 }]);
+    expect(JSON.parse(rfc6902Apply(doc, patch))).toEqual({ a: [1, 99, 3] });
+  });
+
+  test("replace root when path is empty", () => {
+    const doc = JSON.stringify({ a: 1 });
+    const patch = JSON.stringify([{ op: "replace", path: "", value: 42 }]);
+    expect(rfc6902Apply(doc, patch)).toBe("42");
+  });
+
+  test("replace non-existent key throws", () => {
+    const doc = JSON.stringify({ a: 1 });
+    const patch = JSON.stringify([{ op: "replace", path: "/b", value: 2 }]);
+    expect(() => rfc6902Apply(doc, patch)).toThrow('key "b" not found for replace');
+  });
+
+  test("test operation is a no-op", () => {
+    const doc = JSON.stringify({ a: 1 });
+    const patch = JSON.stringify([{ op: "test", path: "/a", value: 1 }]);
+    expect(JSON.parse(rfc6902Apply(doc, patch))).toEqual({ a: 1 });
+  });
+
+  test("multiple operations in sequence", () => {
+    const doc = JSON.stringify({ a: 1 });
+    const patch = JSON.stringify([
+      { op: "add", path: "/b", value: 2 },
+      { op: "replace", path: "/a", value: 10 },
+      { op: "remove", path: "/b" },
+    ]);
+    expect(JSON.parse(rfc6902Apply(doc, patch))).toEqual({ a: 10 });
+  });
+
+  test("unsupported operation throws", () => {
+    const doc = JSON.stringify({ a: 1 });
+    const patch = JSON.stringify([{ op: "unknown", path: "/a" }]);
+    expect(() => rfc6902Apply(doc, patch)).toThrow('unsupported operation "unknown"');
+  });
+
+  test("handles JSON pointer escaping (~0 and ~1)", () => {
+    const doc = JSON.stringify({ "a/b": 1, "c~d": 2 });
+    const patch = JSON.stringify([
+      { op: "replace", path: "/a~1b", value: 10 },
+      { op: "replace", path: "/c~0d", value: 20 },
+    ]);
+    expect(JSON.parse(rfc6902Apply(doc, patch))).toEqual({ "a/b": 10, "c~d": 20 });
+  });
+
+  test("deeply nested add", () => {
+    const doc = JSON.stringify({ a: { b: { c: {} } } });
+    const patch = JSON.stringify([{ op: "add", path: "/a/b/c/d", value: "deep" }]);
+    expect(JSON.parse(rfc6902Apply(doc, patch))).toEqual({ a: { b: { c: { d: "deep" } } } });
+  });
+});

package/src/codegen/json-patch.ts

@@ -0,0 +1,151 @@
+/**
+ * RFC 6902 JSON Patch implementation.
+ *
+ * Applies a JSON Patch document (array of operations) to a JSON document.
+ * Supports add, remove, replace, and test operations.
+ */
+
+interface RFC6902Op {
+  op: string;
+  path: string;
+  value?: unknown;
+}
+
+/**
+ * Apply an RFC 6902 patch document to a JSON document.
+ * Returns the patched JSON as a string.
+ */
+export function rfc6902Apply(doc: string, patch: string): string {
+  const ops: RFC6902Op[] = JSON.parse(patch);
+  let root: unknown = JSON.parse(doc);
+
+  for (let i = 0; i < ops.length; i++) {
+    const op = ops[i];
+    switch (op.op) {
+      case "add":
+        root = jsonPatchAdd(root, op.path, op.value);
+        break;
+      case "remove":
+        root = jsonPatchRemove(root, op.path);
+        break;
+      case "replace":
+        root = jsonPatchReplace(root, op.path, op.value);
+        break;
+      case "test":
+        // Test operations verify a value — skip for now
+        break;
+      case "move":
+      case "copy":
+        // Not commonly used in cfn-lint patches, skip
+        break;
+      default:
+        throw new Error(`op ${i}: unsupported operation "${op.op}"`);
+    }
+  }
+
+  return JSON.stringify(root);
+}
+
+/**
+ * Parse an RFC 6901 JSON Pointer into tokens.
+ * "" → [], "/a/b" → ["a", "b"]
+ */
+function parsePath(path: string): string[] {
+  if (path === "") return [];
+  const raw = path.slice(1).split("/");
+  return raw.map((t) => t.replaceAll("~1", "/").replaceAll("~0", "~"));
+}
+
+function navigateTo(root: unknown, tokens: string[]): { parent: unknown; lastToken: string } {
+  if (tokens.length === 0) throw new Error("empty path");
+  let current = root;
+  for (let i = 0; i < tokens.length - 1; i++) {
+    current = descend(current, tokens[i]);
+  }
+  return { parent: current, lastToken: tokens[tokens.length - 1] };
+}
+
+function descend(current: unknown, token: string): unknown {
+  if (typeof current === "object" && current !== null && !Array.isArray(current)) {
+    const obj = current as Record<string, unknown>;
+    if (!(token in obj)) throw new Error(`key "${token}" not found`);
+    return obj[token];
+  }
+  if (Array.isArray(current)) {
+    const idx = parseInt(token, 10);
+    if (isNaN(idx) || idx < 0 || idx >= current.length) {
+      throw new Error(`invalid array index "${token}"`);
+    }
+    return current[idx];
+  }
+  throw new Error(`cannot descend into ${typeof current} with token "${token}"`);
+}
+
+function jsonPatchAdd(root: unknown, path: string, value: unknown): unknown {
+  const tokens = parsePath(path);
+  if (tokens.length === 0) return value;
+
+  const { parent, lastToken } = navigateTo(root, tokens);
+
+  if (typeof parent === "object" && parent !== null && !Array.isArray(parent)) {
+    (parent as Record<string, unknown>)[lastToken] = value;
+  } else if (Array.isArray(parent)) {
+    if (lastToken === "-") {
+      parent.push(value);
+    } else {
+      const idx = parseInt(lastToken, 10);
+      if (isNaN(idx) || idx < 0 || idx > parent.length) {
+        throw new Error(`array index ${lastToken} out of bounds`);
+      }
+      parent.splice(idx, 0, value);
+    }
+  } else {
+    throw new Error(`cannot add to ${typeof parent}`);
+  }
+
+  return root;
+}
+
+function jsonPatchRemove(root: unknown, path: string): unknown {
+  const tokens = parsePath(path);
+  if (tokens.length === 0) throw new Error("cannot remove root");
+
+  const { parent, lastToken } = navigateTo(root, tokens);
+
+  if (typeof parent === "object" && parent !== null && !Array.isArray(parent)) {
+    delete (parent as Record<string, unknown>)[lastToken];
+  } else if (Array.isArray(parent)) {
+    const idx = parseInt(lastToken, 10);
+    if (isNaN(idx) || idx < 0 || idx >= parent.length) {
+      throw new Error(`array index ${lastToken} out of bounds`);
+    }
+    parent.splice(idx, 1);
+  } else {
+    throw new Error(`cannot remove from ${typeof parent}`);
+  }
+
+  return root;
+}
+
+function jsonPatchReplace(root: unknown, path: string, value: unknown): unknown {
+  const tokens = parsePath(path);
+  if (tokens.length === 0) return value;
+
+  const { parent, lastToken } = navigateTo(root, tokens);
+
+  if (typeof parent === "object" && parent !== null && !Array.isArray(parent)) {
+    const obj = parent as Record<string, unknown>;
+    if (!(lastToken in obj)) throw new Error(`key "${lastToken}" not found for replace`);
+    obj[lastToken] = value;
+  } else if (Array.isArray(parent)) {
+    const idx = parseInt(lastToken, 10);
+    if (isNaN(idx) || idx < 0 || idx >= parent.length) {
+      throw new Error(`array index ${lastToken} out of bounds`);
+    }
+    parent[idx] = value;
+  } else {
+    throw new Error(`cannot replace in ${typeof parent}`);
+  }
+
+  return root;
+}

package/src/codegen/json-schema.test.ts

@@ -0,0 +1,196 @@
+import { describe, expect, test } from "bun:test";
+import {
+  resolvePropertyType,
+  resolveRef,
+  extractConstraints,
+  constraintsIsEmpty,
+  isEnumDefinition,
+  primaryType,
+  type JsonSchemaDocument,
+  type JsonSchemaProperty,
+} from "./json-schema";
+
+describe("primaryType", () => {
+  test("returns 'any' for undefined", () => {
+    expect(primaryType(undefined)).toBe("any");
+  });
+
+  test("returns string type directly", () => {
+    expect(primaryType("string")).toBe("string");
+    expect(primaryType("integer")).toBe("integer");
+  });
+
+  test("returns first non-null from array", () => {
+    expect(primaryType(["null", "string"])).toBe("string");
+    expect(primaryType(["number", "null"])).toBe("number");
+  });
+
+  test("returns first element if all are null", () => {
+    expect(primaryType(["null"])).toBe("null");
+  });
+
+  test("returns 'any' for empty array", () => {
+    expect(primaryType([])).toBe("any");
+  });
+});
+
+describe("resolvePropertyType", () => {
+  const emptySchema: JsonSchemaDocument = {};
+  const defName = (name: string) => `Test_${name}`;
+
+  test("returns 'any' for undefined prop", () => {
+    expect(resolvePropertyType(undefined, emptySchema, defName)).toBe("any");
+  });
+
+  test("resolves string type", () => {
+    expect(resolvePropertyType({ type: "string" }, emptySchema, defName)).toBe("string");
+  });
+
+  test("resolves integer/number types to 'number'", () => {
+    expect(resolvePropertyType({ type: "integer" }, emptySchema, defName)).toBe("number");
+    expect(resolvePropertyType({ type: "number" }, emptySchema, defName)).toBe("number");
+  });
+
+  test("resolves boolean type", () => {
+    expect(resolvePropertyType({ type: "boolean" }, emptySchema, defName)).toBe("boolean");
+  });
+
+  test("resolves array with items", () => {
+    const prop: JsonSchemaProperty = { type: "array", items: { type: "string" } };
+    expect(resolvePropertyType(prop, emptySchema, defName)).toBe("string[]");
+  });
+
+  test("resolves array without items", () => {
+    expect(resolvePropertyType({ type: "array" }, emptySchema, defName)).toBe("any[]");
+  });
+
+  test("resolves object type", () => {
+    expect(resolvePropertyType({ type: "object" }, emptySchema, defName)).toBe("Record<string, any>");
+  });
+
+  test("resolves $ref to object definition", () => {
+    const schema: JsonSchemaDocument = {
+      definitions: { Foo: { properties: { bar: { type: "string" } } } },
+    };
+    expect(resolvePropertyType({ $ref: "#/definitions/Foo" }, schema, defName)).toBe("Test_Foo");
+  });
+
+  test("resolves $ref to enum definition using resolveDefName", () => {
+    const schema: JsonSchemaDocument = {
+      definitions: { Status: { enum: ["a", "b"] } },
+    };
+    expect(resolvePropertyType({ $ref: "#/definitions/Status" }, schema, defName)).toBe("Test_Status");
+  });
+
+  test("resolves $ref to enum definition as 'string' when resolveDefName is null", () => {
+    const schema: JsonSchemaDocument = {
+      definitions: { Status: { enum: ["a", "b"] } },
+    };
+    expect(resolvePropertyType({ $ref: "#/definitions/Status" }, schema, null)).toBe("string");
+  });
+
+  test("resolves inline string enum to union type", () => {
+    const prop: JsonSchemaProperty = { type: "string", enum: ["c", "a", "b"] };
+    expect(resolvePropertyType(prop, emptySchema, defName)).toBe('"a" | "b" | "c"');
+  });
+
+  test("resolves oneOf to 'any'", () => {
+    const prop: JsonSchemaProperty = { oneOf: [{ type: "string" }, { type: "number" }] };
+    expect(resolvePropertyType(prop, emptySchema, defName)).toBe("any");
+  });
+
+  test("resolves anyOf to 'any'", () => {
+    const prop: JsonSchemaProperty = { anyOf: [{ type: "string" }] };
+    expect(resolvePropertyType(prop, emptySchema, defName)).toBe("any");
+  });
+
+  test("resolves $ref with null resolveDefName to 'any' for objects", () => {
+    const schema: JsonSchemaDocument = {
+      definitions: { Foo: { properties: { bar: { type: "string" } } } },
+    };
+    expect(resolvePropertyType({ $ref: "#/definitions/Foo" }, schema, null)).toBe("any");
+  });
+});
+
+describe("resolveRef", () => {
+  const defName = (name: string) => `Test_${name}`;
+
+  test("returns 'any' for non-definitions ref", () => {
+    expect(resolveRef("#/other/Foo", {}, defName)).toBe("any");
+  });
+
+  test("returns 'any' for missing definition", () => {
+    expect(resolveRef("#/definitions/Missing", {}, defName)).toBe("any");
+  });
+
+  test("resolves primitive definition", () => {
+    const schema: JsonSchemaDocument = {
+      definitions: { Count: { type: "integer" } },
+    };
+    expect(resolveRef("#/definitions/Count", schema, defName)).toBe("number");
+  });
+});
+
+describe("extractConstraints", () => {
+  test("extracts all constraint fields", () => {
+    const c = extractConstraints({
+      pattern: "^[a-z]+$",
+      minLength: 1,
+      maxLength: 100,
+      minimum: 0,
+      maximum: 999,
+      format: "email",
+      const: "fixed",
+      default: "hello",
+      enum: ["a", "b"],
+    });
+    expect(c.pattern).toBe("^[a-z]+$");
+    expect(c.minLength).toBe(1);
+    expect(c.maxLength).toBe(100);
+    expect(c.minimum).toBe(0);
+    expect(c.maximum).toBe(999);
+    expect(c.format).toBe("email");
+    expect(c.const).toBe("fixed");
+    expect(c.default).toBe("hello");
+    expect(c.enum).toEqual(["a", "b"]);
+  });
+
+  test("returns empty object for no constraints", () => {
+    const c = extractConstraints({});
+    expect(c).toEqual({});
+  });
+});
+
+describe("constraintsIsEmpty", () => {
+  test("returns true for empty constraints", () => {
+    expect(constraintsIsEmpty({})).toBe(true);
+  });
+
+  test("returns false when any field is set", () => {
+    expect(constraintsIsEmpty({ pattern: "x" })).toBe(false);
+    expect(constraintsIsEmpty({ minLength: 0 })).toBe(false);
+    expect(constraintsIsEmpty({ enum: ["a"] })).toBe(false);
+  });
+
+  test("returns true for empty enum array", () => {
+    expect(constraintsIsEmpty({ enum: [] })).toBe(true);
+  });
+});
+
+describe("isEnumDefinition", () => {
+  test("returns true for enum without properties", () => {
+    expect(isEnumDefinition({ enum: ["a", "b"] })).toBe(true);
+  });
+
+  test("returns false for enum with properties", () => {
+    expect(isEnumDefinition({ enum: ["a"], properties: { x: { type: "string" } } })).toBe(false);
+  });
+
+  test("returns false for no enum", () => {
+    expect(isEnumDefinition({ properties: { x: { type: "string" } } })).toBe(false);
+  });
+
+  test("returns false for empty enum", () => {
+    expect(isEnumDefinition({ enum: [] })).toBe(false);
+  });
+});

package/src/codegen/json-schema.ts

@@ -0,0 +1,209 @@
+/**
+ * Generic JSON Schema resolution utilities for lexicon code generation.
+ *
+ * These functions handle the common subset of JSON Schema used by
+ * infrastructure-as-code formats (CloudFormation, Terraform, Azure ARM, etc.).
+ * Lexicon-specific entry points call these with a `resolveDefName` callback
+ * to produce their own naming conventions.
+ */
+
+// --- Schema input interfaces ---
+
+export interface JsonSchemaDocument {
+  definitions?: Record<string, JsonSchemaDefinition>;
+  [key: string]: unknown;
+}
+
+export interface JsonSchemaProperty {
+  type?: string | string[];
+  $ref?: string;
+  items?: JsonSchemaProperty;
+  oneOf?: JsonSchemaProperty[];
+  anyOf?: JsonSchemaProperty[];
+  properties?: Record<string, JsonSchemaProperty>;
+  required?: string[];
+  enum?: string[];
+  pattern?: string;
+  minLength?: number;
+  maxLength?: number;
+  minimum?: number;
+  maximum?: number;
+  format?: string;
+  const?: unknown;
+  default?: unknown;
+  description?: string;
+}
+
+export interface JsonSchemaDefinition extends JsonSchemaProperty {
+  enum?: string[];
+}
+
+// --- Constraint types ---
+
+export interface PropertyConstraints {
+  pattern?: string;
+  minLength?: number;
+  maxLength?: number;
+  minimum?: number;
+  maximum?: number;
+  format?: string;
+  const?: unknown;
+  default?: unknown;
+  enum?: string[];
+}
+
+// --- Functions ---
+
+/**
+ * Get the primary type from a type field that can be string or string[].
+ * Returns first non-"null" type, or "any" if empty.
+ */
+export function primaryType(type: string | string[] | undefined): string {
+  if (!type) return "any";
+  if (typeof type === "string") return type;
+  for (const t of type) {
+    if (t !== "null") return t;
+  }
+  return type.length > 0 ? type[0] : "any";
+}
+
+/**
+ * Resolve a schema property to its TypeScript type string.
+ *
+ * @param prop - The property to resolve
+ * @param schema - The containing schema document (for $ref resolution)
+ * @param resolveDefName - Callback to produce a TypeScript name from a definition.
+ *   Receives (defName: string) and should return the TS type name for that definition.
+ *   When null, $ref to object definitions resolves to "any".
+ */
+export function resolvePropertyType(
+  prop: JsonSchemaProperty | undefined,
+  schema: JsonSchemaDocument,
+  resolveDefName: ((defName: string) => string) | null,
+): string {
+  if (!prop) return "any";
+
+  // Handle oneOf/anyOf → any
+  if ((prop.oneOf && prop.oneOf.length > 0) || (prop.anyOf && prop.anyOf.length > 0)) {
+    return "any";
+  }
+
+  // Handle $ref
+  if (prop.$ref) {
+    return resolveRef(prop.$ref, schema, resolveDefName);
+  }
+
+  // Inline enum → union of string literals
+  if (prop.enum && prop.enum.length > 0) {
+    const sorted = [...prop.enum].sort();
+    return sorted.map((v) => JSON.stringify(v)).join(" | ");
+  }
+
+  const pt = primaryType(prop.type);
+
+  switch (pt) {
+    case "string":
+      return "string";
+    case "integer":
+    case "number":
+      return "number";
+    case "boolean":
+      return "boolean";
+    case "array":
+      if (prop.items) {
+        const itemType = resolvePropertyType(prop.items, schema, resolveDefName);
+        return `${itemType}[]`;
+      }
+      return "any[]";
+    case "object":
+      return "Record<string, any>";
+    default:
+      return "any";
+  }
+}
+
+/**
+ * Resolve a $ref pointer to a TypeScript type name.
+ *
+ * @param ref - The $ref string (e.g. "#/definitions/Foo")
+ * @param schema - The containing schema document
+ * @param resolveDefName - Callback to produce a TS name for object definitions.
+ *   Receives (defName: string). When null, object defs resolve to "any".
+ */
+export function resolveRef(
+  ref: string,
+  schema: JsonSchemaDocument,
+  resolveDefName: ((defName: string) => string) | null,
+): string {
+  const prefix = "#/definitions/";
+  if (!ref.startsWith(prefix)) return "any";
+
+  const defName = ref.slice(prefix.length);
+  const def = schema.definitions?.[defName];
+  if (!def) return "any";
+
+  // String enum → named type (via resolveDefName) or string
+  if (isEnumDefinition(def)) {
+    return resolveDefName ? resolveDefName(defName) : "string";
+  }
+
+  // Object with properties → named type
+  if (def.properties) {
+    return resolveDefName ? resolveDefName(defName) : "any";
+  }
+
+  // Primitive type
+  if (def.type) {
+    const pt = primaryType(def.type);
+    switch (pt) {
+      case "string": return "string";
+      case "integer":
+      case "number": return "number";
+      case "boolean": return "boolean";
+      case "object": return "Record<string, any>";
+    }
+  }
+
+  return "any";
+}
+
+/**
+ * Extract property constraints from a schema property.
+ */
+export function extractConstraints(prop: JsonSchemaProperty): PropertyConstraints {
+  const c: PropertyConstraints = {};
+  if (prop.pattern) c.pattern = prop.pattern;
+  if (prop.minLength !== undefined) c.minLength = prop.minLength;
+  if (prop.maxLength !== undefined) c.maxLength = prop.maxLength;
+  if (prop.minimum !== undefined) c.minimum = prop.minimum;
+  if (prop.maximum !== undefined) c.maximum = prop.maximum;
+  if (prop.format) c.format = prop.format;
+  if (prop.const !== undefined) c.const = prop.const;
+  if (prop.default !== undefined) c.default = prop.default;
+  if (prop.enum && prop.enum.length > 0) c.enum = prop.enum;
+  return c;
+}
+
+/**
+ * Check whether a PropertyConstraints object is empty (all fields undefined/absent).
+ */
+export function constraintsIsEmpty(c: PropertyConstraints): boolean {
+  return (
+    !c.pattern &&
+    c.minLength === undefined &&
+    c.maxLength === undefined &&
+    c.minimum === undefined &&
+    c.maximum === undefined &&
+    !c.format &&
+    c.const === undefined &&
+    c.default === undefined &&
+    (!c.enum || c.enum.length === 0)
+  );
+}
+
+/**
+ * Check whether a schema definition is a pure string enum (no properties).
+ */
+export function isEnumDefinition(def: JsonSchemaDefinition): boolean {
+  return (def.enum != null && def.enum.length > 0) && !def.properties;
+}