@intentius/chant 0.0.1

package/src/codegen/generate-runtime-index.ts

@@ -0,0 +1,99 @@
+/**
+ * Generic runtime index generator for lexicon packages.
+ *
+ * Produces the `index.ts` file containing factory constructor exports
+ * (`createResource`, `createProperty`) and collision-safe re-exports.
+ */
+
+export interface RuntimeIndexConfig {
+  /** Lexicon identifier: "aws", "terraform", etc. */
+  lexiconName: string;
+  /** Optional re-exports of intrinsic functions. */
+  intrinsicReExports?: {
+    names: string[];
+    from: string;
+  };
+  /** Optional re-exports of pseudo-parameters. */
+  pseudoReExports?: {
+    names: string[];
+    from: string;
+  };
+}
+
+export interface RuntimeIndexEntry {
+  tsName: string;
+  resourceType: string;
+  attrs: Record<string, string>;
+}
+
+export interface RuntimeIndexPropertyEntry {
+  tsName: string;
+  resourceType: string;
+}
+
+/**
+ * Generate the runtime index.ts content with factory constructor exports.
+ *
+ * Phases:
+ * 1. Banner + import createResource/createProperty
+ * 2. Sort and emit resource exports
+ * 3. Sort and emit property exports
+ * 4. Collision-safe re-exports of intrinsics and pseudo-parameters
+ */
+export function generateRuntimeIndex(
+  resources: RuntimeIndexEntry[],
+  properties: RuntimeIndexPropertyEntry[],
+  config: RuntimeIndexConfig,
+): string {
+  const lines: string[] = [];
+  lines.push("// Code generated by chant generate. DO NOT EDIT.");
+  lines.push('import { createResource, createProperty } from "./runtime";');
+  lines.push("");
+
+  // Sort and emit resource exports
+  const sortedResources = [...resources].sort((a, b) => a.tsName.localeCompare(b.tsName));
+  for (const { tsName, resourceType, attrs } of sortedResources) {
+    const attrsStr = JSON.stringify(attrs);
+    lines.push(
+      `export const ${tsName} = createResource(${JSON.stringify(resourceType)}, ${JSON.stringify(config.lexiconName)}, ${attrsStr});`,
+    );
+  }
+
+  lines.push("");
+
+  // Sort and emit property exports
+  const sortedProperties = [...properties].sort((a, b) => a.tsName.localeCompare(b.tsName));
+  for (const { tsName, resourceType } of sortedProperties) {
+    lines.push(
+      `export const ${tsName} = createProperty(${JSON.stringify(resourceType)}, ${JSON.stringify(config.lexiconName)});`,
+    );
+  }
+
+  lines.push("");
+
+  // Collision-safe re-exports
+  const allExportNames = new Set([
+    ...resources.map((e) => e.tsName),
+    ...properties.map((e) => e.tsName),
+  ]);
+
+  lines.push("// Re-exports for convenience");
+
+  if (config.intrinsicReExports) {
+    const safe = config.intrinsicReExports.names.filter((n) => !allExportNames.has(n));
+    if (safe.length > 0) {
+      lines.push(`export { ${safe.join(", ")} } from ${JSON.stringify(config.intrinsicReExports.from)};`);
+    }
+  }
+
+  if (config.pseudoReExports) {
+    const safe = config.pseudoReExports.names.filter((n) => !allExportNames.has(n));
+    if (safe.length > 0) {
+      lines.push(`export { ${safe.join(", ")} } from ${JSON.stringify(config.pseudoReExports.from)};`);
+    }
+  }
+
+  lines.push("");
+
+  return lines.join("\n");
+}

package/src/codegen/generate-typescript.test.ts

@@ -0,0 +1,146 @@
+import { describe, test, expect } from "bun:test";
+import {
+  writeResourceClass,
+  writePropertyClass,
+  writeConstructor,
+  writeEnumType,
+  resolveConstructorType,
+} from "./generate-typescript";
+
+describe("writeResourceClass", () => {
+  test("generates class with constructor and attributes", () => {
+    const lines: string[] = [];
+    writeResourceClass(
+      lines,
+      "Bucket",
+      [{ name: "BucketName", type: "string", required: true }],
+      [{ name: "Arn", type: "string" }],
+    );
+    const output = lines.join("\n");
+    expect(output).toContain("export declare class Bucket {");
+    expect(output).toContain("bucketName: string;");
+    expect(output).toContain("readonly arn: string;");
+    expect(output).toContain("}");
+  });
+
+  test("applies remap to attribute types", () => {
+    const lines: string[] = [];
+    const remap = new Map([["CustomType", "BucketConfig"]]);
+    writeResourceClass(
+      lines,
+      "Bucket",
+      [],
+      [{ name: "Config", type: "CustomType" }],
+      remap,
+    );
+    const output = lines.join("\n");
+    expect(output).toContain("readonly config: BucketConfig;");
+  });
+});
+
+describe("writePropertyClass", () => {
+  test("generates class with constructor only", () => {
+    const lines: string[] = [];
+    writePropertyClass(
+      lines,
+      "BucketConfig",
+      [{ name: "Enabled", type: "boolean", required: false }],
+    );
+    const output = lines.join("\n");
+    expect(output).toContain("export declare class BucketConfig {");
+    expect(output).toContain("enabled?: boolean;");
+    expect(output).toContain("}");
+  });
+});
+
+describe("writeConstructor", () => {
+  test("empty props produces Record<string, unknown> constructor", () => {
+    const lines: string[] = [];
+    writeConstructor(lines, [], undefined);
+    expect(lines.join("\n")).toContain("constructor(props: Record<string, unknown>);");
+  });
+
+  test("sorts required before optional", () => {
+    const lines: string[] = [];
+    writeConstructor(
+      lines,
+      [
+        { name: "Optional", type: "string", required: false },
+        { name: "Required", type: "string", required: true },
+      ],
+      undefined,
+    );
+    const output = lines.join("\n");
+    const reqIdx = output.indexOf("required:");
+    const optIdx = output.indexOf("optional?:");
+    expect(reqIdx).toBeLessThan(optIdx);
+  });
+
+  test("includes description as JSDoc", () => {
+    const lines: string[] = [];
+    writeConstructor(
+      lines,
+      [{ name: "Name", type: "string", required: true, description: "The bucket name" }],
+      undefined,
+    );
+    const output = lines.join("\n");
+    expect(output).toContain("/** The bucket name */");
+  });
+});
+
+describe("writeEnumType", () => {
+  test("writes single-line for short enum", () => {
+    const lines: string[] = [];
+    writeEnumType(lines, "Status", ["active", "inactive"]);
+    const output = lines.join("\n");
+    expect(output).toContain('export type Status = "active" | "inactive";');
+  });
+
+  test("writes multi-line for long enum", () => {
+    const lines: string[] = [];
+    writeEnumType(lines, "VeryLongTypeName", [
+      "value-one-is-very-long",
+      "value-two-is-very-long",
+      "value-three-is-very-long",
+      "value-four-is-very-long",
+    ]);
+    const output = lines.join("\n");
+    expect(output).toContain("export type VeryLongTypeName =");
+    expect(output).toContain('  | "value-one-is-very-long"');
+  });
+
+  test("sorts values alphabetically", () => {
+    const lines: string[] = [];
+    writeEnumType(lines, "Order", ["z", "a", "m"]);
+    const output = lines.join("\n");
+    expect(output).toContain('"a" | "m" | "z"');
+  });
+});
+
+describe("resolveConstructorType", () => {
+  test("passes through primitives", () => {
+    expect(resolveConstructorType("string", undefined)).toBe("string");
+    expect(resolveConstructorType("number", undefined)).toBe("number");
+    expect(resolveConstructorType("boolean", undefined)).toBe("boolean");
+    expect(resolveConstructorType("any", undefined)).toBe("any");
+  });
+
+  test("normalizes Record<string, any>", () => {
+    expect(resolveConstructorType("Record<string, any>", undefined)).toBe("Record<string, unknown>");
+  });
+
+  test("handles array types recursively", () => {
+    const remap = new Map([["Foo", "Bar"]]);
+    expect(resolveConstructorType("Foo[]", remap)).toBe("Bar[]");
+    expect(resolveConstructorType("string[]", undefined)).toBe("string[]");
+  });
+
+  test("applies remap", () => {
+    const remap = new Map([["InternalName", "PublicName"]]);
+    expect(resolveConstructorType("InternalName", remap)).toBe("PublicName");
+  });
+
+  test("returns type as-is when no remap match", () => {
+    expect(resolveConstructorType("UnknownType", new Map())).toBe("UnknownType");
+  });
+});

package/src/codegen/generate-typescript.ts

@@ -0,0 +1,161 @@
+/**
+ * Generic TypeScript declaration (.d.ts) generation utilities.
+ *
+ * Provides functions for writing resource classes, property classes,
+ * constructors, and enum types. Lexicon-specific generators use these
+ * building blocks with their own orchestration logic.
+ */
+
+// ── Minimal input interfaces ────────────────────────────────────────
+
+export interface DtsProperty {
+  name: string;
+  type: string;
+  required: boolean;
+  description?: string;
+}
+
+export interface DtsAttribute {
+  name: string;
+  type: string;
+}
+
+export interface DtsPropertyType {
+  name: string;
+  properties: DtsProperty[];
+}
+
+export interface DtsResource {
+  typeName: string;
+  properties: DtsProperty[];
+  attributes: DtsAttribute[];
+}
+
+// ── Writers ─────────────────────────────────────────────────────────
+
+/**
+ * Write a resource class declaration with constructor and readonly attributes.
+ */
+export function writeResourceClass(
+  lines: string[],
+  tsName: string,
+  properties: DtsProperty[],
+  attributes: DtsAttribute[],
+  remap?: Map<string, string>,
+): void {
+  lines.push("");
+  lines.push(`export declare class ${tsName} {`);
+  writeConstructor(lines, properties, remap);
+
+  // Attributes as readonly properties (sorted)
+  const attrs = [...attributes].sort((a, b) => a.name.localeCompare(b.name));
+  for (const a of attrs) {
+    const attrType = resolveConstructorType(a.type, remap);
+    lines.push(`  readonly ${toCamelCase(a.name)}: ${attrType};`);
+  }
+
+  lines.push("}");
+}
+
+/**
+ * Write a property class declaration with constructor.
+ */
+export function writePropertyClass(
+  lines: string[],
+  tsName: string,
+  properties: DtsProperty[],
+  remap?: Map<string, string>,
+): void {
+  lines.push("");
+  lines.push(`export declare class ${tsName} {`);
+  writeConstructor(lines, properties, remap);
+  lines.push("}");
+}
+
+/**
+ * Write a constructor with typed props parameter.
+ */
+export function writeConstructor(
+  lines: string[],
+  props: DtsProperty[],
+  remap: Map<string, string> | undefined,
+): void {
+  if (props.length === 0) {
+    lines.push("  constructor(props: Record<string, unknown>);");
+    return;
+  }
+
+  // Sort: required first, then optional, each group alphabetically
+  const sorted = [...props].sort((a, b) => {
+    if (a.required !== b.required) return a.required ? -1 : 1;
+    return a.name.localeCompare(b.name);
+  });
+
+  lines.push("  constructor(props: {");
+  for (const p of sorted) {
+    const optional = p.required ? "" : "?";
+    const tsType = resolveConstructorType(p.type, remap);
+    if (p.description) {
+      lines.push(`    /** ${p.description} */`);
+    }
+    lines.push(`    ${toCamelCase(p.name)}${optional}: ${tsType};`);
+  }
+  lines.push("  });");
+}
+
+/**
+ * Write an enum union type.
+ */
+export function writeEnumType(lines: string[], tsName: string, values: string[]): void {
+  const sorted = [...values].sort();
+  const quoted = sorted.map((v) => JSON.stringify(v));
+
+  const singleLine = `\nexport type ${tsName} = ${quoted.join(" | ")};`;
+  if (singleLine.length <= 100) {
+    lines.push(singleLine);
+  } else {
+    lines.push("");
+    lines.push(`export type ${tsName} =`);
+    for (let i = 0; i < quoted.length; i++) {
+      const suffix = i < quoted.length - 1 ? "" : ";";
+      lines.push(`  | ${quoted[i]}${suffix}`);
+    }
+  }
+}
+
+/**
+ * Resolve a type string through the remap table, handling arrays and
+ * common type normalization.
+ */
+export function resolveConstructorType(tsType: string, remap: Map<string, string> | undefined): string {
+  // Handle array types
+  if (tsType.endsWith("[]")) {
+    const inner = tsType.slice(0, -2);
+    return resolveConstructorType(inner, remap) + "[]";
+  }
+
+  // Primitive and pass-through types
+  switch (tsType) {
+    case "string":
+    case "number":
+    case "boolean":
+    case "any":
+      return tsType;
+    case "Record<string, any>":
+      return "Record<string, unknown>";
+    case "Record<string, unknown>":
+      return tsType;
+  }
+
+  // Remap parser property type names to resolved names
+  if (remap) {
+    const resolved = remap.get(tsType);
+    if (resolved) return resolved;
+  }
+
+  return tsType;
+}
+
+function toCamelCase(name: string): string {
+  return name.charAt(0).toLowerCase() + name.slice(1);
+}

package/src/codegen/generate.ts

@@ -0,0 +1,206 @@
+/**
+ * Generic generation pipeline orchestration.
+ *
+ * Provides the step sequencing, logging, warning collection, stats counting,
+ * and artifact writing pattern. Individual steps (fetch, parse, etc.) are
+ * supplied by the lexicon via callbacks.
+ */
+
+import { writeFileSync, mkdirSync, existsSync } from "fs";
+import { join } from "path";
+import type { NamingStrategy } from "./naming";
+
+// ── Types ──────────────────────────────────────────────────────────
+
+export interface GenerateOptions {
+  force?: boolean;
+  verbose?: boolean;
+  dryRun?: boolean;
+  schemaSource?: Map<string, Buffer>;
+}
+
+export interface GenerateResult {
+  lexiconJSON: string;
+  typesDTS: string;
+  indexTS: string;
+  resources: number;
+  properties: number;
+  enums: number;
+  warnings: Array<{ file: string; error: string }>;
+}
+
+/**
+ * A parsed result with enough structure for the pipeline to count stats.
+ * Lexicons extend this with their own fields.
+ */
+export interface ParsedResult {
+  propertyTypes: Array<{ name: string }>;
+  enums: Array<unknown>;
+}
+
+export interface AugmentResult<T> {
+  schemas: Map<string, Buffer>;
+  extraResults?: T[];
+  warnings?: Array<{ file: string; error: string }>;
+}
+
+export interface GeneratePipelineConfig<T extends ParsedResult> {
+  /** Fetch or provide raw schema data. */
+  fetchSchemas: (opts: { force?: boolean }) => Promise<Map<string, Buffer>>;
+
+  /** Parse a single schema buffer into a result. Returns null to skip. */
+  parseSchema: (typeName: string, data: Buffer) => T | null;
+
+  /** Create a naming strategy from the parsed results. */
+  createNaming: (results: T[]) => NamingStrategy;
+
+  /** Generate lexicon JSON from results + naming. */
+  generateRegistry: (results: T[], naming: NamingStrategy) => string;
+
+  /** Generate TypeScript declarations. */
+  generateTypes: (results: T[], naming: NamingStrategy) => string;
+
+  /** Generate runtime index with factory exports. */
+  generateRuntimeIndex: (results: T[], naming: NamingStrategy) => string;
+
+  /** Optional pre-parse hook (patches, overlays, extra resources, etc.). */
+  augmentSchemas?: (
+    schemas: Map<string, Buffer>,
+    opts: GenerateOptions,
+    log: (msg: string) => void,
+  ) => Promise<AugmentResult<T>>;
+
+  /** Optional post-parse hook (add synthetic resources, fallbacks, etc.). */
+  augmentResults?: (
+    results: T[],
+    opts: GenerateOptions,
+    log: (msg: string) => void,
+  ) => { results: T[]; warnings?: Array<{ file: string; error: string }> };
+}
+
+// ── Pipeline ───────────────────────────────────────────────────────
+
+/**
+ * Run a generation pipeline with the supplied config callbacks.
+ */
+export async function generatePipeline<T extends ParsedResult>(
+  config: GeneratePipelineConfig<T>,
+  opts: GenerateOptions = {},
+): Promise<GenerateResult> {
+  const log = opts.verbose
+    ? (msg: string) => console.error(msg)
+    : (_msg: string) => {};
+
+  const warnings: Array<{ file: string; error: string }> = [];
+
+  // Step 1: Fetch schemas (or use provided source)
+  let schemas: Map<string, Buffer>;
+  if (opts.schemaSource) {
+    schemas = opts.schemaSource;
+    log(`Using provided schema source with ${schemas.size} schemas`);
+  } else {
+    log("Fetching schemas...");
+    schemas = await config.fetchSchemas({ force: opts.force });
+    log(`Fetched ${schemas.size} schemas`);
+  }
+
+  // Step 2: Augment schemas (patches, overlays, etc.)
+  let extraResults: T[] = [];
+  if (config.augmentSchemas && !opts.schemaSource) {
+    const augment = await config.augmentSchemas(schemas, opts, log);
+    schemas = augment.schemas;
+    if (augment.extraResults) extraResults = augment.extraResults;
+    if (augment.warnings) warnings.push(...augment.warnings);
+  }
+
+  // Step 3: Parse each schema
+  log("Parsing schemas...");
+  const results: T[] = [];
+  for (const [typeName, data] of schemas) {
+    try {
+      const result = config.parseSchema(typeName, data);
+      if (result) results.push(result);
+    } catch (err) {
+      warnings.push({
+        file: typeName,
+        error: err instanceof Error ? err.message : String(err),
+      });
+    }
+  }
+  results.push(...extraResults);
+  log(`Parsed ${results.length} schemas`);
+
+  // Step 4: Augment results (fallbacks, synthetic resources, etc.)
+  if (config.augmentResults) {
+    const augment = config.augmentResults(results, opts, log);
+    // augmentResults may mutate results in-place or return new ones
+    if (augment.warnings) warnings.push(...augment.warnings);
+  }
+
+  // Step 5: Naming strategy
+  const naming = config.createNaming(results);
+
+  // Step 6: Generate artifacts
+  log("Generating lexicon JSON...");
+  const lexiconJSON = config.generateRegistry(results, naming);
+
+  log("Generating TypeScript declarations...");
+  const typesDTS = config.generateTypes(results, naming);
+
+  log("Generating runtime index...");
+  const indexTS = config.generateRuntimeIndex(results, naming);
+
+  // Count stats
+  let resourceCount = 0;
+  let propertyCount = 0;
+  let enumCount = 0;
+  for (const r of results) {
+    resourceCount++;
+    propertyCount += r.propertyTypes.length;
+    enumCount += r.enums.length;
+  }
+
+  return {
+    lexiconJSON,
+    typesDTS,
+    indexTS,
+    resources: resourceCount,
+    properties: propertyCount,
+    enums: enumCount,
+    warnings,
+  };
+}
+
+// ── Artifact writing ───────────────────────────────────────────────
+
+export interface WriteConfig {
+  /** Base directory of the lexicon package. */
+  baseDir: string;
+  /** Subdirectory for generated files (default: "src/generated"). */
+  generatedSubdir?: string;
+  /** Map of filename → content to write. */
+  files: Record<string, string>;
+  /** Optional snapshot function called before overwriting. */
+  snapshot?: (generatedDir: string) => void;
+}
+
+/**
+ * Write generated artifacts to disk with optional auto-snapshot.
+ */
+export function writeGeneratedArtifacts(config: WriteConfig): void {
+  const generatedDir = join(config.baseDir, config.generatedSubdir ?? "src/generated");
+  mkdirSync(generatedDir, { recursive: true });
+
+  // Auto-snapshot before overwriting
+  if (config.snapshot) {
+    try {
+      config.snapshot(generatedDir);
+    } catch {
+      // Best effort — don't fail generation if snapshot fails
+    }
+  }
+
+  for (const [filename, content] of Object.entries(config.files)) {
+    writeFileSync(join(generatedDir, filename), content);
+  }
+}