@intentius/chant 0.0.1

package/src/builder.test.ts

@@ -0,0 +1,312 @@
+import { describe, test, expect } from "bun:test";
+import { Builder } from "./builder";
+import type { Declarable } from "./declarable";
+import { DECLARABLE_MARKER } from "./declarable";
+
+// Test implementation of Declarable for testing
+interface TestResource extends Declarable {
+  name: string;
+  type: string;
+  description?: string;
+}
+
+// Simple builder implementation
+class SimpleResourceBuilder extends Builder<TestResource> {
+  private name?: string;
+  private type?: string;
+  private description?: string;
+
+  withName(name: string): this {
+    this.name = name;
+    return this;
+  }
+
+  withType(type: string): this {
+    this.type = type;
+    return this;
+  }
+
+  withDescription(description: string): this {
+    this.description = description;
+    return this;
+  }
+
+  build(): TestResource {
+    if (!this.name || !this.type) {
+      throw new Error("Name and type are required");
+    }
+    return {
+      entityType: "TestResource",
+      [DECLARABLE_MARKER]: true,
+      name: this.name,
+      type: this.type,
+      description: this.description,
+    };
+  }
+}
+
+// Complex builder with validation
+class ValidatedResourceBuilder extends Builder<TestResource> {
+  private name?: string;
+  private type?: string;
+
+  withName(name: string): this {
+    if (!name || name.trim() === "") {
+      throw new Error("Name cannot be empty");
+    }
+    this.name = name;
+    return this;
+  }
+
+  withType(type: string): this {
+    const validTypes = ["A", "B", "C"];
+    if (!validTypes.includes(type)) {
+      throw new Error(`Type must be one of: ${validTypes.join(", ")}`);
+    }
+    this.type = type;
+    return this;
+  }
+
+  build(): TestResource {
+    if (!this.name || !this.type) {
+      throw new Error("Name and type are required");
+    }
+    return {
+      entityType: "TestResource",
+      [DECLARABLE_MARKER]: true,
+      name: this.name,
+      type: this.type,
+    };
+  }
+}
+
+// Builder with default values
+class DefaultsResourceBuilder extends Builder<TestResource> {
+  private name = "default-name";
+  private type = "default-type";
+  private description = "default-description";
+
+  withName(name: string): this {
+    this.name = name;
+    return this;
+  }
+
+  withType(type: string): this {
+    this.type = type;
+    return this;
+  }
+
+  withDescription(description: string): this {
+    this.description = description;
+    return this;
+  }
+
+  build(): TestResource {
+    return {
+      entityType: "TestResource",
+      [DECLARABLE_MARKER]: true,
+      name: this.name,
+      type: this.type,
+      description: this.description,
+    };
+  }
+}
+
+describe("Builder", () => {
+  describe("fluent API", () => {
+    test("allows chaining multiple method calls", () => {
+      const builder = new SimpleResourceBuilder()
+        .withName("test-resource")
+        .withType("test-type")
+        .withDescription("test-description");
+
+      const resource = builder.build();
+      expect(resource.name).toBe("test-resource");
+      expect(resource.type).toBe("test-type");
+      expect(resource.description).toBe("test-description");
+    });
+
+    test("returns 'this' for chaining", () => {
+      const builder = new SimpleResourceBuilder();
+      const result1 = builder.withName("test");
+      const result2 = result1.withType("type");
+
+      expect(result1).toBe(builder);
+      expect(result2).toBe(builder);
+    });
+
+    test("allows arbitrary method call order", () => {
+      const resource1 = new SimpleResourceBuilder()
+        .withName("test")
+        .withType("type")
+        .build();
+
+      const resource2 = new SimpleResourceBuilder()
+        .withType("type")
+        .withName("test")
+        .build();
+
+      expect(resource1.name).toBe(resource2.name);
+      expect(resource1.type).toBe(resource2.type);
+    });
+  });
+
+  describe("build method", () => {
+    test("returns a valid Declarable entity", () => {
+      const resource = new SimpleResourceBuilder()
+        .withName("test")
+        .withType("type")
+        .build();
+
+      expect(resource.entityType).toBe("TestResource");
+      expect(resource[DECLARABLE_MARKER]).toBe(true);
+      expect(resource.name).toBe("test");
+      expect(resource.type).toBe("type");
+    });
+
+    test("throws when required properties are missing", () => {
+      const builder = new SimpleResourceBuilder().withName("test");
+
+      expect(() => builder.build()).toThrow("Name and type are required");
+    });
+
+    test("includes optional properties when set", () => {
+      const resource = new SimpleResourceBuilder()
+        .withName("test")
+        .withType("type")
+        .withDescription("A test resource")
+        .build();
+
+      expect(resource.description).toBe("A test resource");
+    });
+
+    test("omits optional properties when not set", () => {
+      const resource = new SimpleResourceBuilder()
+        .withName("test")
+        .withType("type")
+        .build();
+
+      expect(resource.description).toBeUndefined();
+    });
+  });
+
+  describe("extension patterns", () => {
+    test("supports custom validation in setter methods", () => {
+      const builder = new ValidatedResourceBuilder();
+
+      expect(() => builder.withName("")).toThrow("Name cannot be empty");
+      expect(() => builder.withName("   ")).toThrow("Name cannot be empty");
+      expect(() => builder.withType("Invalid")).toThrow(
+        "Type must be one of: A, B, C"
+      );
+    });
+
+    test("allows valid values through validation", () => {
+      const resource = new ValidatedResourceBuilder()
+        .withName("valid-name")
+        .withType("A")
+        .build();
+
+      expect(resource.name).toBe("valid-name");
+      expect(resource.type).toBe("A");
+    });
+
+    test("supports builders with default values", () => {
+      const resource = new DefaultsResourceBuilder().build();
+
+      expect(resource.name).toBe("default-name");
+      expect(resource.type).toBe("default-type");
+      expect(resource.description).toBe("default-description");
+    });
+
+    test("allows overriding default values", () => {
+      const resource = new DefaultsResourceBuilder()
+        .withName("custom-name")
+        .build();
+
+      expect(resource.name).toBe("custom-name");
+      expect(resource.type).toBe("default-type");
+      expect(resource.description).toBe("default-description");
+    });
+  });
+
+  describe("reusability", () => {
+    test("builder can be reused to create multiple instances", () => {
+      const builder = new DefaultsResourceBuilder();
+
+      const resource1 = builder.build();
+      const resource2 = builder.build();
+
+      // Should create separate instances
+      expect(resource1).not.toBe(resource2);
+      // But with same values
+      expect(resource1.name).toBe(resource2.name);
+      expect(resource1.type).toBe(resource2.type);
+    });
+
+    test("modifying builder after build affects next build", () => {
+      const builder = new SimpleResourceBuilder()
+        .withName("initial")
+        .withType("type");
+
+      const resource1 = builder.build();
+      expect(resource1.name).toBe("initial");
+
+      builder.withName("modified");
+      const resource2 = builder.build();
+      expect(resource2.name).toBe("modified");
+    });
+  });
+
+  describe("type safety", () => {
+    test("build method returns correct type", () => {
+      const builder = new SimpleResourceBuilder()
+        .withName("test")
+        .withType("type");
+
+      const resource = builder.build();
+
+      // TypeScript should recognize this as TestResource
+      expect(resource.entityType).toBe("TestResource");
+      expect(resource.name).toBe("test");
+      expect(resource.type).toBe("type");
+    });
+
+    test("fluent methods maintain builder type", () => {
+      const builder = new SimpleResourceBuilder();
+
+      // Each method should return the same builder type
+      const step1 = builder.withName("test");
+      const step2 = step1.withType("type");
+      const step3 = step2.withDescription("desc");
+
+      expect(step1).toBeInstanceOf(SimpleResourceBuilder);
+      expect(step2).toBeInstanceOf(SimpleResourceBuilder);
+      expect(step3).toBeInstanceOf(SimpleResourceBuilder);
+    });
+  });
+
+  describe("error handling", () => {
+    test("preserves validation errors", () => {
+      const builder = new ValidatedResourceBuilder();
+
+      try {
+        builder.withType("Invalid");
+      } catch (error) {
+        expect(error).toBeInstanceOf(Error);
+        expect((error as Error).message).toBe("Type must be one of: A, B, C");
+      }
+    });
+
+    test("preserves build errors", () => {
+      const builder = new SimpleResourceBuilder();
+
+      try {
+        builder.build();
+      } catch (error) {
+        expect(error).toBeInstanceOf(Error);
+        expect((error as Error).message).toBe("Name and type are required");
+      }
+    });
+  });
+});

package/src/builder.ts

@@ -0,0 +1,56 @@
+import type { Declarable } from "./declarable";
+
+/**
+ * Base class for builder pattern implementations
+ *
+ * Provides a fluent API for constructing Declarable entities.
+ * Subclasses should implement the build() method to return
+ * a fully constructed Declarable entity.
+ *
+ * @example
+ * ```ts
+ * class ResourceBuilder extends Builder<MyResource> {
+ *   private name?: string;
+ *   private type?: string;
+ *
+ *   withName(name: string): this {
+ *     this.name = name;
+ *     return this;
+ *   }
+ *
+ *   withType(type: string): this {
+ *     this.type = type;
+ *     return this;
+ *   }
+ *
+ *   build(): MyResource {
+ *     if (!this.name || !this.type) {
+ *       throw new Error("Name and type are required");
+ *     }
+ *     return {
+ *       entityType: "MyResource",
+ *       [DECLARABLE_MARKER]: true,
+ *       name: this.name,
+ *       type: this.type,
+ *     };
+ *   }
+ * }
+ *
+ * const resource = new ResourceBuilder()
+ *   .withName("myResource")
+ *   .withType("custom")
+ *   .build();
+ * ```
+ */
+export abstract class Builder<T extends Declarable> {
+  /**
+   * Builds and returns the final Declarable entity
+   *
+   * Subclasses must implement this method to construct
+   * and return the entity with all configured properties.
+   *
+   * @returns The constructed Declarable entity
+   * @throws Error if required properties are not set
+   */
+  abstract build(): T;
+}

package/src/child-project.ts

@@ -0,0 +1,44 @@
+/**
+ * Child Project — represents a nested project directory that gets built
+ * independently and referenced from a parent as a single deployment unit.
+ *
+ * Lexicons create ChildProjectInstance via their own factory (e.g. `nestedStack()`).
+ * The core build pipeline detects these and recursively builds children.
+ */
+
+import { DECLARABLE_MARKER, type Declarable } from "./declarable";
+import type { BuildResult } from "./build";
+
+/**
+ * Marker symbol for child project identification.
+ */
+export const CHILD_PROJECT_MARKER = Symbol.for("chant.childProject");
+
+/**
+ * A child project instance — a Declarable representing a separately-built
+ * project directory referenced from a parent.
+ */
+export interface ChildProjectInstance extends Declarable {
+  readonly [CHILD_PROJECT_MARKER]: true;
+  readonly [DECLARABLE_MARKER]: true;
+  readonly lexicon: string;
+  readonly entityType: string;
+  readonly kind: "resource";
+  readonly projectPath: string;
+  readonly logicalName: string;
+  readonly outputs: Record<string, unknown>;
+  readonly options: Record<string, unknown>;
+  buildResult?: BuildResult;
+}
+
+/**
+ * Type guard for ChildProjectInstance.
+ */
+export function isChildProject(value: unknown): value is ChildProjectInstance {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    CHILD_PROJECT_MARKER in value &&
+    (value as Record<symbol, unknown>)[CHILD_PROJECT_MARKER] === true
+  );
+}

package/src/cli/commands/__fixtures__/init-lexicon-output/README.md

@@ -0,0 +1,26 @@
+# @intentius/chant-lexicon-fixture
+
+fixture lexicon plugin for [chant](https://github.com/intentius/chant).
+
+## Getting started
+
+```bash
+# Generate types from upstream spec
+just generate
+
+# Validate generated artifacts
+just validate
+
+# Generate documentation
+just docs
+```
+
+## Project structure
+
+- `src/plugin.ts` — LexiconPlugin with all lifecycle methods
+- `src/serializer.ts` — Build output serializer
+- `src/codegen/` — Code generation pipeline
+- `src/spec/` — Upstream schema fetching and parsing
+- `src/lint/rules/` — Lint rules
+- `src/lsp/` — LSP completions and hover
+- `src/generated/` — Generated artifacts (do not edit)

package/src/cli/commands/__fixtures__/init-lexicon-output/docs/astro.config.mjs

@@ -0,0 +1,14 @@
+// @ts-check
+import { defineConfig } from 'astro/config';
+import starlight from '@astrojs/starlight';
+
+export default defineConfig({
+  integrations: [
+    starlight({
+      title: 'Fixture',
+      sidebar: [
+        { label: 'Overview', slug: '' },
+      ],
+    }),
+  ],
+});

package/src/cli/commands/__fixtures__/init-lexicon-output/docs/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "@intentius/chant-lexicon-fixture-docs",
+  "type": "module",
+  "version": "0.0.1",
+  "private": true,
+  "scripts": {
+    "dev": "astro dev",
+    "build": "astro build",
+    "preview": "astro preview"
+  },
+  "dependencies": {
+    "@astrojs/starlight": "^0.37.6",
+    "astro": "^5.6.1",
+    "sharp": "^0.34.2"
+  }
+}

package/src/cli/commands/__fixtures__/init-lexicon-output/docs/src/content/docs/index.mdx

@@ -0,0 +1,8 @@
+---
+title: Overview
+description: Fixture lexicon for chant
+---
+
+Welcome to the Fixture lexicon documentation.
+
+Run `just generate` to populate this site with generated reference pages.

package/src/cli/commands/__fixtures__/init-lexicon-output/docs/src/content.config.ts

@@ -0,0 +1,7 @@
+import { defineCollection } from 'astro:content';
+import { docsLoader } from '@astrojs/starlight/loaders';
+import { docsSchema } from '@astrojs/starlight/schema';
+
+export const collections = {
+  docs: defineCollection({ loader: docsLoader(), schema: docsSchema() }),
+};

package/src/cli/commands/__fixtures__/init-lexicon-output/docs/tsconfig.json

@@ -0,0 +1,10 @@
+{
+  "extends": "astro/tsconfigs/strict",
+  "include": [
+    ".astro/types.d.ts",
+    "**/*"
+  ],
+  "exclude": [
+    "dist"
+  ]
+}

package/src/cli/commands/__fixtures__/init-lexicon-output/justfile

@@ -0,0 +1,26 @@
+# Default recipe - list all available commands
+default:
+    @just --list
+
+# Generate types and metadata from upstream schemas
+generate:
+    bun run src/codegen/generate-cli.ts
+
+# Validate generated artifacts
+validate:
+    bun run src/validate-cli.ts
+
+# Generate docs site, install deps, and start dev server
+docs:
+    bun run src/codegen/docs-cli.ts
+    bun install --cwd docs
+    bun --cwd docs dev
+
+# Build docs site for production
+docs-build:
+    bun run src/codegen/docs-cli.ts
+    bun install --cwd docs
+    bun --cwd docs build
+
+# Package the lexicon (generate + validate)
+package: generate validate

package/src/cli/commands/__fixtures__/init-lexicon-output/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@intentius/chant-lexicon-fixture",
+  "version": "0.0.1",
+  "type": "module",
+  "private": true,
+  "files": [
+    "src/",
+    "dist/"
+  ],
+  "exports": {
+    ".": "./src/index.ts",
+    "./*": "./src/*",
+    "./manifest": "./dist/manifest.json",
+    "./meta": "./dist/meta.json",
+    "./types": "./dist/types/index.d.ts"
+  },
+  "scripts": {
+    "generate": "bun run src/codegen/generate-cli.ts",
+    "validate": "bun run src/validate-cli.ts",
+    "docs": "bun src/codegen/docs-cli.ts",
+    "prepack": "bun run generate && bun run validate"
+  },
+  "dependencies": {
+    "@intentius/chant": "workspace:*"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3"
+  }
+}

package/src/cli/commands/__fixtures__/init-lexicon-output/src/codegen/docs.ts

@@ -0,0 +1,25 @@
+import { docsPipeline, writeDocsSite } from "@intentius/chant/codegen/docs";
+
+/**
+ * Generate documentation site for the fixture lexicon.
+ */
+export async function generateDocs(options?: { verbose?: boolean }): Promise<void> {
+  const config = {
+    name: "fixture",
+    displayName: "Fixture",
+    description: "fixture lexicon documentation",
+    distDir: "./dist",
+    outDir: "./docs",
+    // TODO: Implement service grouping for your provider
+    serviceFromType: (type: string) => type.split("::")[1] ?? type,
+    // TODO: Implement resource documentation URLs
+    resourceTypeUrl: (type: string) => `#${type}`,
+  };
+
+  const result = docsPipeline(config);
+  writeDocsSite(config, result);
+
+  if (options?.verbose) {
+    console.error("Documentation generated");
+  }
+}

package/src/cli/commands/__fixtures__/init-lexicon-output/src/codegen/generate-cli.ts

@@ -0,0 +1,8 @@
+#!/usr/bin/env bun
+import { generate, writeGeneratedFiles } from "./generate";
+import { dirname } from "path";
+import { fileURLToPath } from "url";
+
+const pkgDir = dirname(dirname(fileURLToPath(import.meta.url)));
+const result = await generate({ verbose: true });
+writeGeneratedFiles(result, pkgDir);

package/src/cli/commands/__fixtures__/init-lexicon-output/src/codegen/generate.ts

@@ -0,0 +1,74 @@
+import { generatePipeline, writeGeneratedArtifacts } from "@intentius/chant/codegen/generate";
+import type { GenerateResult } from "@intentius/chant/codegen/generate";
+import { dirname } from "path";
+import { fileURLToPath } from "url";
+
+/**
+ * Run the code generation pipeline.
+ *
+ * Each callback has a TODO describing what to implement.
+ */
+export async function generate(options?: { verbose?: boolean }): Promise<GenerateResult> {
+  const result = await generatePipeline({
+    // Must return Map<typeName, Buffer> — each entry is one schema file.
+    // Example: fetch a zip, extract JSON files, key by type name.
+    // See lexicons/aws/src/spec/fetch.ts for a working example.
+    fetchSchemas: async (opts) => {
+      throw new Error("TODO: implement fetchSchemas — download your upstream spec");
+    },
+
+    // Must return a ParsedResult (with propertyTypes[] and enums[] at minimum).
+    // Return null to skip a schema file.
+    // See lexicons/aws/src/spec/parse.ts for a working example.
+    parseSchema: (name, data) => {
+      throw new Error("TODO: implement parseSchema — parse a single schema file");
+    },
+
+    // Must return a NamingStrategy instance.
+    // See lexicons/aws/src/codegen/naming.ts and ./naming.ts for setup.
+    createNaming: (results) => {
+      throw new Error("TODO: implement createNaming — return a NamingStrategy instance");
+    },
+
+    // Must return a string of JSON (the lexicon registry).
+    // Use buildRegistry + serializeRegistry from @intentius/chant/codegen/generate-registry.
+    // See lexicons/aws/src/codegen/generate.ts for a working example.
+    generateRegistry: (results, naming) => {
+      throw new Error("TODO: implement generateRegistry — produce lexicon JSON");
+    },
+
+    // Must return a string of TypeScript declarations (.d.ts content).
+    // See lexicons/aws/src/codegen/generate.ts for a working example.
+    generateTypes: (results, naming) => {
+      throw new Error("TODO: implement generateTypes — produce .d.ts content");
+    },
+
+    // Must return a string of TypeScript (runtime index with factory exports).
+    // Use generateRuntimeIndex from @intentius/chant/codegen/generate-runtime-index.
+    // See lexicons/aws/src/codegen/generate.ts for a working example.
+    generateRuntimeIndex: (results, naming) => {
+      throw new Error("TODO: implement generateRuntimeIndex — produce index.ts content");
+    },
+  });
+
+  if (options?.verbose) {
+    console.error(`Generated ${result.resources} resources, ${result.properties} property types`);
+  }
+
+  return result;
+}
+
+/**
+ * Write generated files to the package directory.
+ */
+export function writeGeneratedFiles(result: GenerateResult, pkgDir?: string): void {
+  const dir = pkgDir ?? dirname(dirname(fileURLToPath(import.meta.url)));
+  writeGeneratedArtifacts({
+    baseDir: dir,
+    files: {
+      "lexicon.json": result.lexiconJSON,
+      "index.d.ts": result.typesDTS,
+      "index.ts": result.indexTS,
+    },
+  });
+}