Skip to content
chant

Development Setup

Prerequisites

Section titled “Prerequisites”
  • Bun — runtime, package manager, and test runner
  • Git — for version control
  • just — task runner (optional, but recommended)

Clone and Install

Section titled “Clone and Install”
Terminal window
git clone https://github.com/intentius/chant.git
cd chant
bun install

Justfile Commands

Section titled “Justfile Commands”

The project uses just for common tasks. Run just with no arguments to see all available commands:

Terminal window
just              # list all commands
just install      # install all dependencies (including docs)
just build        # type-check the project (bun run tsc --noEmit)
just test         # run all tests
just lint         # run eslint on packages/
just check        # run build + lint + test
just docs         # start the docs dev server
just bench        # run performance benchmarks
just smoke        # build and run the Docker smoke test
just docs-build   # build the unified documentation site

Run Tests

Section titled “Run Tests”
Terminal window
bun test                    # all tests
bun test packages/core/     # core package only
bun test lexicons/aws/      # AWS lexicon only
bun test lexicons/k8s/      # K8s lexicon only

Kubernetes roundtrip tests

Section titled “Kubernetes roundtrip tests”

The K8s lexicon has additional integration tests that run against real manifests from kubernetes/examples:

Terminal window
cd lexicons/k8s


# Parse-only roundtrip (parse → generate)
just import-samples --skip-clone --verbose


# Full roundtrip (parse → generate → import → serialize → compare)
just full-roundtrip --skip-clone --verbose


# k3d cluster validation (requires k3d + kubectl + Docker)
just k3d-validate --verbose

Test Patterns

Section titled “Test Patterns”
  • Unit tests live next to source files or in __tests__/ directories
  • The packages/test-utils/ directory (@intentius/chant-test-utils) provides shared test fixtures, assertions, and the example test harness

Example Tests

Section titled “Example Tests”

Example tests are centralized — each lexicon has a single examples.test.ts that auto-discovers all its examples. Example directories contain only source code (no .test.ts files), so users who copy examples get clean projects.

Per-lexicon examples live at lexicons/<name>/examples/<example>/src/ and are tested by lexicons/<name>/examples/examples.test.ts.

Cross-lexicon examples (e.g. AWS + K8s, GitLab + AWS) live at examples/<name>/src/ and are tested by examples/examples.test.ts.

Both use the shared harness from @intentius/chant-test-utils/example-harness:

import { describeAllExamples } from "@intentius/chant-test-utils/example-harness";
import { mySerializer } from "@intentius/chant-lexicon-my-lexicon";


describeAllExamples({
  lexicon: "my-lexicon",
  serializer: mySerializer,
  outputKey: "my-lexicon",
  examplesDir: import.meta.dir,
}, {
  // Per-example overrides (optional)
  "docs-snippets": { skipLint: true },
  "my-example": {
    checks: (output) => { expect(output).toContain("expected"); },
  },
});

Adding a new example: create a subdirectory with src/ and a package.json — the centralized examples.test.ts auto-discovers it with no test file changes needed. Add an override entry only if you need custom assertions or to skip lint/build.

Type Checking

Section titled “Type Checking”
Terminal window
bun run tsc --noEmit

Project Layout

Section titled “Project Layout”
chant/
├── packages/
│   ├── core/           @intentius/chant — type system, pipeline, CLI, and codegen infrastructure
│   │   └── src/
│   │       ├── runtime.ts              createResource/createProperty factories
│   │       ├── codegen/
│   │       │   ├── naming.ts           NamingStrategy (collision-free class names)
│   │       │   ├── generate.ts         generatePipeline (schema → artifacts)
│   │       │   ├── package.ts          packagePipeline (artifacts → BundleSpec)
│   │       │   └── fetch.ts            fetchWithCache, extractFromZip
│   │       └── lsp/
│   │           └── lexicon-providers.ts LexiconIndex, completions, hover
│   └── test-utils/     shared test fixtures and assertions
├── lexicons/
│   ├── aws/            @intentius/chant-lexicon-aws — AWS CloudFormation lexicon
│   ├── gitlab/         @intentius/chant-lexicon-gitlab — GitLab CI/CD lexicon
│   └── k8s/            @intentius/chant-lexicon-k8s — Kubernetes lexicon
├── docs/               Astro Starlight documentation site
└── package.json

Core codegen infrastructure

Section titled “Core codegen infrastructure”

The packages/core/src/codegen/ directory contains reusable infrastructure for lexicon code generation pipelines. Lexicons supply provider-specific callbacks and data tables; core handles orchestration, logging, warning collection, stats counting, and artifact writing. The AWS lexicon (lexicons/aws/) demonstrates this pattern — its codegen files are thin wrappers around core pipelines.

What’s Next

Section titled “What’s Next”