@intentius/chant 0.0.1

package/src/codegen/naming.ts

@@ -0,0 +1,201 @@
+/**
+ * Collision-free naming strategy for TypeScript class names.
+ *
+ * 5-phase algorithm:
+ * 1. Priority names (backward compatibility)
+ * 2. Priority aliases (additional short names)
+ * 3. Short names (last segment of type)
+ * 4. Collision resolution (service-prefixed)
+ * 5. Property type aliases (globally unique defs)
+ */
+
+/**
+ * Minimal input required by the naming strategy — avoids coupling
+ * to any specific schema parser output format.
+ */
+export interface NamingInput {
+  typeName: string;
+  propertyTypes: Array<{ name: string }>;
+}
+
+/**
+ * Configuration that parameterizes the naming algorithm.
+ * The data tables and name-extraction helpers are provider-specific.
+ */
+export interface NamingConfig {
+  /** Fixed TypeScript class names for backward compatibility. */
+  priorityNames: Record<string, string>;
+  /** Additional TypeScript names beyond the primary priority name. */
+  priorityAliases: Record<string, string[]>;
+  /** Property type aliases that must always be emitted. */
+  priorityPropertyAliases: Record<string, Record<string, string>>;
+  /** Service name abbreviations for collision-resolved names. */
+  serviceAbbreviations: Record<string, string>;
+  /** Extract the short name from a type name (e.g. "Vendor::Service::Resource" → "Resource"). */
+  shortName: (typeName: string) => string;
+  /** Extract the service name from a type name (e.g. "Vendor::Service::Resource" → "Service"). */
+  serviceName: (typeName: string) => string;
+}
+
+export class NamingStrategy {
+  private assigned = new Map<string, string>(); // typeName → primary TS name
+  private _aliases = new Map<string, string[]>(); // typeName → additional TS names
+  private usedNames = new Set<string>();
+  private _propertyAliases = new Map<string, Map<string, string>>(); // typeName → (defName → aliasName)
+
+  constructor(results: NamingInput[], private config: NamingConfig) {
+    const typeNames = results.map((r) => r.typeName);
+
+    const abbreviateService = (service: string): string =>
+      config.serviceAbbreviations[service] ?? service;
+
+    // Phase 1: assign priority names
+    for (const t of typeNames) {
+      const name = config.priorityNames[t];
+      if (name) {
+        this.assigned.set(t, name);
+        this.usedNames.add(name);
+      }
+    }
+
+    // Phase 1b: assign priority aliases
+    for (const t of typeNames) {
+      const extras = config.priorityAliases[t];
+      if (extras) {
+        for (const alias of extras) {
+          if (!this.usedNames.has(alias)) {
+            const existing = this._aliases.get(t) ?? [];
+            existing.push(alias);
+            this._aliases.set(t, existing);
+            this.usedNames.add(alias);
+          }
+        }
+      }
+    }
+
+    // Phase 2: collect short names for non-priority types and detect collisions
+    const shortNameUsers = new Map<string, string[]>(); // shortName → typeNames
+    const nonPriority: string[] = [];
+
+    for (const t of typeNames) {
+      if (this.assigned.has(t)) continue;
+      nonPriority.push(t);
+      const short = config.shortName(t);
+      const users = shortNameUsers.get(short) ?? [];
+      users.push(t);
+      shortNameUsers.set(short, users);
+    }
+
+    // Phase 3: assign non-colliding short names
+    for (const [short, users] of shortNameUsers) {
+      if (users.length === 1 && !this.usedNames.has(short)) {
+        this.assigned.set(users[0], short);
+        this.usedNames.add(short);
+      }
+    }
+
+    // Phase 4: resolve collisions with service prefix
+    for (const t of nonPriority) {
+      if (this.assigned.has(t)) continue;
+      const short = config.shortName(t);
+      const service = abbreviateService(config.serviceName(t));
+      const prefixed = service + short;
+      this.assigned.set(t, prefixed);
+      this.usedNames.add(prefixed);
+    }
+
+    // Phase 5: compute property type aliases
+    // First, force priority property aliases
+    for (const [typeName, aliases] of Object.entries(config.priorityPropertyAliases)) {
+      if (!this.assigned.has(typeName)) continue;
+      for (const [defName, aliasName] of Object.entries(aliases)) {
+        if (!this.usedNames.has(aliasName)) {
+          let ptAliases = this._propertyAliases.get(typeName);
+          if (!ptAliases) {
+            ptAliases = new Map();
+            this._propertyAliases.set(typeName, ptAliases);
+          }
+          ptAliases.set(defName, aliasName);
+          this.usedNames.add(aliasName);
+        }
+      }
+    }
+
+    // Count how many resources define each property type defName
+    const defNameCount = new Map<string, number>();
+    for (const r of results) {
+      const shortName = config.shortName(r.typeName);
+      for (const pt of r.propertyTypes) {
+        const defName = extractDefName(pt.name, shortName);
+        defNameCount.set(defName, (defNameCount.get(defName) ?? 0) + 1);
+      }
+    }
+
+    // For globally unique defNames, create an alias
+    for (const r of results) {
+      const typeName = r.typeName;
+      const tsName = this.assigned.get(typeName);
+      if (!tsName) continue;
+      const shortName = config.shortName(typeName);
+
+      for (const pt of r.propertyTypes) {
+        const defName = extractDefName(pt.name, shortName);
+        if (defNameCount.get(defName) === 1 && !this.usedNames.has(defName)) {
+          let ptAliases = this._propertyAliases.get(typeName);
+          if (!ptAliases) {
+            ptAliases = new Map();
+            this._propertyAliases.set(typeName, ptAliases);
+          }
+          ptAliases.set(defName, defName);
+          this.usedNames.add(defName);
+        }
+      }
+    }
+  }
+
+  /** Primary TypeScript class name for a type. */
+  resolve(typeName: string): string | undefined {
+    return this.assigned.get(typeName);
+  }
+
+  /** Additional TypeScript names for a type. */
+  aliases(typeName: string): string[] {
+    return this._aliases.get(typeName) ?? [];
+  }
+
+  /** All (typeName, tsName) pairs sorted by TS name. */
+  allAssignments(): [string, string][] {
+    const pairs: [string, string][] = [];
+    for (const [t, name] of this.assigned) {
+      pairs.push([t, name]);
+    }
+    for (const [t, extras] of this._aliases) {
+      for (const alias of extras) {
+        pairs.push([t, alias]);
+      }
+    }
+    pairs.sort((a, b) => a[1].localeCompare(b[1]));
+    return pairs;
+  }
+
+  /** Property type aliases for a given type. */
+  propertyTypeAliases(typeName: string): Map<string, string> | undefined {
+    return this._propertyAliases.get(typeName);
+  }
+}
+
+/**
+ * Construct property type name: "Bucket_ServerSideEncryptionByDefault"
+ */
+export function propertyTypeName(parentTSName: string, defName: string): string {
+  return `${parentTSName}_${defName}`;
+}
+
+/**
+ * Extract the raw definition name from a parser-generated name.
+ * "Bucket_ServerSideEncryptionByDefault" → "ServerSideEncryptionByDefault"
+ */
+export function extractDefName(parserName: string, shortName: string): string {
+  const prefix = `${shortName}_`;
+  return parserName.startsWith(prefix) ? parserName.slice(prefix.length) : parserName;
+}

package/src/codegen/package.ts

@@ -0,0 +1,161 @@
+/**
+ * Generic lexicon packaging pipeline.
+ *
+ * Orchestrates: generate → manifest → collect rules → collect skills →
+ * assemble BundleSpec → compute integrity → attach metadata.
+ */
+
+import { readFileSync, readdirSync } from "fs";
+import { join } from "path";
+import type { BundleSpec, LexiconManifest } from "../lexicon";
+import { computeIntegrity } from "../lexicon-integrity";
+import type { GenerateResult } from "./generate";
+
+// ── Types ──────────────────────────────────────────────────────────
+
+export interface PackageOptions {
+  verbose?: boolean;
+  force?: boolean;
+}
+
+export interface PackageResult {
+  spec: BundleSpec;
+  stats: {
+    resources: number;
+    properties: number;
+    enums: number;
+    ruleCount: number;
+    skillCount: number;
+  };
+}
+
+export interface PackagePipelineConfig {
+  /** Run generation and return artifacts. */
+  generate: (opts: { verbose?: boolean; force?: boolean }) => Promise<GenerateResult>;
+  /** Build the lexicon manifest from the generate result. */
+  buildManifest: (genResult: GenerateResult) => LexiconManifest;
+  /** Source directory for collecting rules. */
+  srcDir: string;
+  /** Rule directories relative to srcDir (default: ["lint/rules", "lint/post-synth"]). */
+  ruleDirs?: string[];
+  /** Collect skill definitions. Returns map of filename → content. */
+  collectSkills: () => Map<string, string>;
+  /** Package version for metadata. */
+  version?: string;
+}
+
+// ── Pipeline ───────────────────────────────────────────────────────
+
+/**
+ * Run the packaging pipeline with the supplied config.
+ */
+export async function packagePipeline(
+  config: PackagePipelineConfig,
+  opts: PackageOptions = {},
+): Promise<PackageResult> {
+  const log = opts.verbose
+    ? (msg: string) => console.error(msg)
+    : (_msg: string) => {};
+
+  // Step 1: Run the generation pipeline
+  log("Running generation pipeline...");
+  const result = await config.generate({ verbose: opts.verbose, force: opts.force });
+
+  // Step 2: Build manifest
+  log("Building manifest...");
+  const manifest = config.buildManifest(result);
+
+  // Step 3: Collect rules
+  log("Collecting rules...");
+  const rules = collectRules(config.srcDir, config.ruleDirs);
+
+  // Step 4: Collect skills
+  log("Collecting skills...");
+  const skills = config.collectSkills();
+
+  // Step 5: Assemble BundleSpec
+  const spec: BundleSpec = {
+    manifest,
+    registry: result.lexiconJSON,
+    typesDTS: result.typesDTS,
+    rules,
+    skills,
+  };
+
+  // Step 6: Compute integrity
+  log("Computing integrity...");
+  spec.integrity = computeIntegrity(spec);
+
+  // Step 7: Populate metadata
+  spec.metadata = {
+    generatedAt: new Date().toISOString(),
+    chantVersion: "0.1.0",
+    generatorVersion: config.version ?? "0.0.0",
+    sourceSchemaCount: result.resources,
+  };
+
+  log(`Package assembled: ${rules.size} rules, ${skills.size} skills`);
+
+  return {
+    spec,
+    stats: {
+      resources: result.resources,
+      properties: result.properties,
+      enums: result.enums,
+      ruleCount: rules.size,
+      skillCount: skills.size,
+    },
+  };
+}
+
+// ── Utilities ──────────────────────────────────────────────────────
+
+/**
+ * Collect lint rule source files from a lexicon package.
+ * Auto-discovers .ts files in the specified directories,
+ * skipping test files, barrel files (index.ts), and non-.ts files.
+ */
+export function collectRules(
+  srcDir: string,
+  dirs: string[] = ["lint/rules", "lint/post-synth"],
+): Map<string, string> {
+  const rules = new Map<string, string>();
+
+  for (const dir of dirs) {
+    const fullDir = join(srcDir, dir);
+    let entries: string[];
+    try {
+      entries = readdirSync(fullDir);
+    } catch {
+      continue;
+    }
+
+    for (const entry of entries) {
+      if (!entry.endsWith(".ts")) continue;
+      if (entry.endsWith(".test.ts")) continue;
+      if (entry === "index.ts") continue;
+
+      try {
+        const content = readFileSync(join(fullDir, entry), "utf-8");
+        rules.set(entry, content);
+      } catch {
+        // Skip unreadable files
+      }
+    }
+  }
+
+  return rules;
+}
+
+/**
+ * Collect skills from a plugin's skill definitions.
+ */
+export function collectSkills(
+  skillDefs: Array<{ name: string; content: string }>,
+): Map<string, string> {
+  const skills = new Map<string, string>();
+  for (const s of skillDefs) {
+    skills.set(`${s.name}.md`, s.content);
+  }
+  return skills;
+}

package/src/codegen/rollback.test.ts

@@ -0,0 +1,92 @@
+import { describe, test, expect } from "bun:test";
+import { mkdirSync, writeFileSync, rmSync, readFileSync } from "fs";
+import { join } from "path";
+import { tmpdir } from "os";
+import { snapshotArtifacts, saveSnapshot, restoreSnapshot, listSnapshots } from "./rollback";
+
+function makeTempDir(): string {
+  const dir = join(tmpdir(), `chant-rollback-test-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+  mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+describe("rollback", () => {
+  test("snapshot captures generated files with default artifact names", () => {
+    const dir = makeTempDir();
+    const genDir = join(dir, "generated");
+    mkdirSync(genDir, { recursive: true });
+
+    writeFileSync(join(genDir, "lexicon.json"), '{"Bucket":{"kind":"resource"}}');
+    writeFileSync(join(genDir, "index.d.ts"), "declare class Bucket {}");
+    writeFileSync(join(genDir, "index.ts"), "export const Bucket = {};");
+
+    const snapshot = snapshotArtifacts(genDir);
+    expect(snapshot.files["lexicon.json"]).toBeDefined();
+    expect(snapshot.files["index.d.ts"]).toBeDefined();
+    expect(snapshot.files["index.ts"]).toBeDefined();
+    expect(snapshot.hashes["lexicon.json"]).toBeDefined();
+    expect(snapshot.resourceCount).toBe(1);
+
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  test("snapshot uses custom artifact names", () => {
+    const dir = makeTempDir();
+    const genDir = join(dir, "generated");
+    mkdirSync(genDir, { recursive: true });
+
+    writeFileSync(join(genDir, "my-lexicon.json"), '{"Resource":{"kind":"resource"}}');
+    writeFileSync(join(genDir, "types.d.ts"), "declare class Resource {}");
+
+    const snapshot = snapshotArtifacts(genDir, ["my-lexicon.json", "types.d.ts"]);
+    expect(snapshot.files["my-lexicon.json"]).toBeDefined();
+    expect(snapshot.files["types.d.ts"]).toBeDefined();
+    expect(snapshot.resourceCount).toBe(1);
+
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  test("save and list snapshots", () => {
+    const dir = makeTempDir();
+    const snapshotsDir = join(dir, ".snapshots");
+
+    const snapshot = {
+      timestamp: "2025-01-01T00:00:00.000Z",
+      files: { "test.json": "{}" },
+      hashes: { "test.json": "abc123" },
+      resourceCount: 0,
+    };
+
+    saveSnapshot(snapshot, snapshotsDir);
+    const list = listSnapshots(snapshotsDir);
+    expect(list.length).toBe(1);
+    expect(list[0].timestamp).toBe("2025-01-01T00:00:00.000Z");
+
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  test("restore snapshot overwrites generated files", () => {
+    const dir = makeTempDir();
+    const genDir = join(dir, "generated");
+    const snapshotsDir = join(dir, ".snapshots");
+    mkdirSync(genDir, { recursive: true });
+
+    writeFileSync(join(genDir, "lexicon.json"), '{"original":true}');
+
+    const snapshot = snapshotArtifacts(genDir);
+    const snapshotPath = saveSnapshot(snapshot, snapshotsDir);
+
+    writeFileSync(join(genDir, "lexicon.json"), '{"modified":true}');
+    expect(readFileSync(join(genDir, "lexicon.json"), "utf-8")).toBe('{"modified":true}');
+
+    restoreSnapshot(snapshotPath, genDir);
+    expect(readFileSync(join(genDir, "lexicon.json"), "utf-8")).toBe('{"original":true}');
+
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  test("listSnapshots returns empty for nonexistent dir", () => {
+    const list = listSnapshots("/nonexistent/path");
+    expect(list).toHaveLength(0);
+  });
+});

package/src/codegen/rollback.ts

@@ -0,0 +1,115 @@
+/**
+ * Artifact snapshot and restore for generation rollback.
+ */
+import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync } from "fs";
+import { join } from "path";
+import { hashArtifact } from "../lexicon-integrity";
+
+export interface ArtifactSnapshot {
+  timestamp: string;
+  files: Record<string, string>;
+  hashes: Record<string, string>;
+  resourceCount: number;
+}
+
+export interface SnapshotInfo {
+  path: string;
+  timestamp: string;
+  resourceCount: number;
+}
+
+const DEFAULT_ARTIFACT_NAMES = ["lexicon.json", "index.d.ts", "index.ts"];
+
+/**
+ * Snapshot current generated artifacts.
+ *
+ * @param generatedDir - Directory containing generated artifacts
+ * @param artifactNames - List of filenames to snapshot (defaults to generic names)
+ */
+export function snapshotArtifacts(
+  generatedDir: string,
+  artifactNames: string[] = DEFAULT_ARTIFACT_NAMES,
+): ArtifactSnapshot {
+  const files: Record<string, string> = {};
+  const hashes: Record<string, string> = {};
+  let resourceCount = 0;
+
+  for (const entry of artifactNames) {
+    const path = join(generatedDir, entry);
+    if (existsSync(path)) {
+      const content = readFileSync(path, "utf-8");
+      files[entry] = content;
+      hashes[entry] = hashArtifact(content);
+
+      // Count resources in any .json artifact
+      if (entry.endsWith(".json")) {
+        try {
+          const parsed = JSON.parse(content);
+          resourceCount = Object.values(parsed).filter(
+            (e: any) => e && typeof e === "object" && e.kind === "resource"
+          ).length;
+        } catch {}
+      }
+    }
+  }
+
+  return {
+    timestamp: new Date().toISOString(),
+    files,
+    hashes,
+    resourceCount,
+  };
+}
+
+/**
+ * Save a snapshot to the .snapshots directory.
+ */
+export function saveSnapshot(snapshot: ArtifactSnapshot, snapshotsDir: string): string {
+  mkdirSync(snapshotsDir, { recursive: true });
+
+  const filename = `${snapshot.timestamp.replace(/[:.]/g, "-")}.json`;
+  const path = join(snapshotsDir, filename);
+  writeFileSync(path, JSON.stringify(snapshot, null, 2));
+  return path;
+}
+
+/**
+ * Restore a snapshot to the generated directory.
+ */
+export function restoreSnapshot(snapshotPath: string, generatedDir: string): void {
+  const raw = readFileSync(snapshotPath, "utf-8");
+  const snapshot: ArtifactSnapshot = JSON.parse(raw);
+
+  mkdirSync(generatedDir, { recursive: true });
+  for (const [filename, content] of Object.entries(snapshot.files)) {
+    writeFileSync(join(generatedDir, filename), content);
+  }
+}
+
+/**
+ * List available snapshots.
+ */
+export function listSnapshots(snapshotsDir: string): SnapshotInfo[] {
+  if (!existsSync(snapshotsDir)) return [];
+
+  const entries = readdirSync(snapshotsDir)
+    .filter((f) => f.endsWith(".json"))
+    .sort()
+    .reverse();
+
+  const snapshots: SnapshotInfo[] = [];
+  for (const entry of entries) {
+    try {
+      const path = join(snapshotsDir, entry);
+      const raw = readFileSync(path, "utf-8");
+      const data = JSON.parse(raw);
+      snapshots.push({
+        path,
+        timestamp: data.timestamp,
+        resourceCount: data.resourceCount ?? 0,
+      });
+    } catch {}
+  }
+
+  return snapshots;
+}

package/src/codegen/topo-sort.test.ts

@@ -0,0 +1,69 @@
+import { describe, test, expect } from "bun:test";
+import { topoSort } from "./topo-sort";
+
+interface Node {
+  id: string;
+  deps: string[];
+}
+
+describe("topoSort", () => {
+  test("returns empty array for empty input", () => {
+    const result = topoSort<Node>([], (n) => n.id, (n) => n.deps);
+    expect(result).toEqual([]);
+  });
+
+  test("returns single node", () => {
+    const nodes: Node[] = [{ id: "A", deps: [] }];
+    const result = topoSort(nodes, (n) => n.id, (n) => n.deps);
+    expect(result.map((n) => n.id)).toEqual(["A"]);
+  });
+
+  test("sorts dependencies before dependents", () => {
+    const nodes: Node[] = [
+      { id: "C", deps: ["B"] },
+      { id: "A", deps: [] },
+      { id: "B", deps: ["A"] },
+    ];
+    const result = topoSort(nodes, (n) => n.id, (n) => n.deps);
+    const ids = result.map((n) => n.id);
+
+    expect(ids.indexOf("A")).toBeLessThan(ids.indexOf("B"));
+    expect(ids.indexOf("B")).toBeLessThan(ids.indexOf("C"));
+  });
+
+  test("handles diamond dependency", () => {
+    const nodes: Node[] = [
+      { id: "D", deps: ["B", "C"] },
+      { id: "B", deps: ["A"] },
+      { id: "C", deps: ["A"] },
+      { id: "A", deps: [] },
+    ];
+    const result = topoSort(nodes, (n) => n.id, (n) => n.deps);
+    const ids = result.map((n) => n.id);
+
+    expect(ids.indexOf("A")).toBeLessThan(ids.indexOf("B"));
+    expect(ids.indexOf("A")).toBeLessThan(ids.indexOf("C"));
+    expect(ids.indexOf("B")).toBeLessThan(ids.indexOf("D"));
+    expect(ids.indexOf("C")).toBeLessThan(ids.indexOf("D"));
+  });
+
+  test("handles independent nodes", () => {
+    const nodes: Node[] = [
+      { id: "A", deps: [] },
+      { id: "B", deps: [] },
+      { id: "C", deps: [] },
+    ];
+    const result = topoSort(nodes, (n) => n.id, (n) => n.deps);
+    expect(result).toHaveLength(3);
+  });
+
+  test("ignores deps pointing to nodes not in the input", () => {
+    const nodes: Node[] = [
+      { id: "A", deps: ["X"] }, // X not in nodes
+      { id: "B", deps: ["A"] },
+    ];
+    const result = topoSort(nodes, (n) => n.id, (n) => n.deps);
+    const ids = result.map((n) => n.id);
+    expect(ids.indexOf("A")).toBeLessThan(ids.indexOf("B"));
+  });
+});

package/src/codegen/topo-sort.ts

@@ -0,0 +1,46 @@
+/**
+ * Generic DFS-based topological sort.
+ */
+
+/**
+ * Sort nodes in topological order (dependencies first).
+ *
+ * @param nodes - The items to sort.
+ * @param getId - Extract a unique identifier from a node.
+ * @param getEdges - Return the IDs of nodes that `node` depends on.
+ * @returns Sorted array where dependencies appear before dependents.
+ */
+export function topoSort<T>(
+  nodes: T[],
+  getId: (node: T) => string,
+  getEdges: (node: T) => string[],
+): T[] {
+  const result: T[] = [];
+  const added = new Set<string>();
+  const nodeMap = new Map<string, T>();
+
+  for (const node of nodes) {
+    nodeMap.set(getId(node), node);
+  }
+
+  function visit(node: T): void {
+    const id = getId(node);
+    if (added.has(id)) return;
+
+    for (const dep of getEdges(node)) {
+      const depNode = nodeMap.get(dep);
+      if (depNode && !added.has(dep)) {
+        visit(depNode);
+      }
+    }
+
+    result.push(node);
+    added.add(id);
+  }
+
+  for (const node of nodes) {
+    visit(node);
+  }
+
+  return result;
+}