Skip to content

CLAUDE.md

Latest commit

 

History

History
163 lines (111 loc) · 6.38 KB

CLAUDE.md

File metadata and controls

163 lines (111 loc) · 6.38 KB
Raw

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Prerequisites & Setup

Tools managed by mise (see mise.toml): Node (from .nvmrc), go 1.25, Python 3.11, Java corretto-20, .NET 6.0, Terraform 1.7.5.

Additional tools not managed by mise (install manually):

# macOS
brew install maven rsync

# Enable corepack for pnpm (pinned via package.json)
corepack enable

Then:

pnpm install

See CONTRIBUTING.md for full details including Docker-based development and language-specific setup.

Build & Development

pnpm build            # Build all packages (tsc + jsii)
pnpm watch            # Watch mode for development
pnpm package          # Build + create distributable packages (requires mvn, rsync)

Testing

pnpm test                          # Run all unit tests (via nx run-many)
pnpm test:update                   # Update snapshots
pnpm nx test @cdktn/commons        # Run one package's tests
pnpm nx test @cdktn/commons --watch # Iterative dev loop: reruns on file change

# Some unit tests require dist packages to be built first (they auto-skip if missing):
pnpm package
pnpm test

# Integration tests (always require pnpm package first)
pnpm package
pnpm integration                              # All integration tests
pnpm integration:single typescript/synth-app  # Single test
pnpm integration:update                       # Update integration snapshots

On Linux with limited tmpfs: TMPDIR=/var/tmp pnpm test

pnpm nx test <pkg> --watch is the recommended dev loop — Nx builds the ^build chain once, then jest's watch UI reruns affected tests on each save.

When adding or changing tests, run the test-audit skill (.claude/skills/test-audit/SKILL.md) over them: it gates each test on the contract it protects and the tier that should own it, and flags duplicated or implementation-coupled tests.

Running CLI locally

# After pnpm watch, use the local CLI directly:
./packages/cdktn-cli/bundle/bin/cdktn <command>

# Or link globally:
pnpm run link-packages
cdktn --version  # Should show 0.0.0

Language-specific testing

pnpm integration:typescript
pnpm integration:python
pnpm integration:go
pnpm integration:csharp
pnpm integration:java

Package Architecture

This is a JSII monorepo (Lerna + pnpm workspaces) that compiles TypeScript to Python, Go, Java, and C#.

Core Packages

Package Purpose
packages/cdktn Core library — constructs (TerraformStack, TerraformResource, etc.). Uses JSII.
packages/cdktn-cli CLI entry point — thin wrapper around cli-core, uses esbuild (transpile only, no type checking; tsc runs as pre-commit hook)
packages/@cdktn/cli-core CLI implementation — commands, project management, Terraform execution
packages/@cdktn/provider-generator Generates TypeScript bindings from Terraform provider schemas
packages/@cdktn/provider-schema Fetches and parses Terraform provider schemas
packages/@cdktn/hcl2cdk Converts HCL to CDK code (cdktn convert)
packages/@cdktn/hcl2json WASM-based HCL parser (Go compiled to WASM)
packages/@cdktn/commons Shared utilities across packages

Key Flows

Synthesis: App → TerraformStack → synthesize() → cdktf.out/stacks/<name>/cdk.tf.json

Provider Generation: Provider schema JSON → provider-generator → TypeScript classes → JSII → Python/Go/Java/C#

HCL Conversion: HCL files → hcl2json (WASM) → JSON AST → hcl2cdk → CDK code

JSII Considerations

  • Core cdktn library uses JSII for multi-language support
  • Changes to public APIs affect all language bindings
  • Run pnpm package to generate all language distributions in dist/
  • JSII metadata lives in .jsii files

Feature Flags

Feature flags in packages/cdktn/src/features.ts enable breaking behavior changes behind opt-in flags. New projects get flags enabled via cdktf.json. Add new flags to FUTURE_FLAGS map.

Project Principles

Priority order: YAGNI > KISS > UX Consistency > Test Coverage. Small PRs reviewable in <30 minutes preferred.

Commit Style

Use conventional commits:

  • feat(cli): / feat(lib): / feat(provider-generator):
  • fix(cli): / fix(lib):
  • refactor(lib): / perf(cli): / test(lib): / revert(lib):
  • chore: for docs, CI, non-code changes

Allowed types: feat, fix, chore, refactor, revert, test, perf

Allowed scopes: cli, lib, hcl2cdk, hcl2json, provider-generator, examples, tests, tools, docs, readme, release, deps, gha

The PR title is what gets linted (.github/workflows/pr-lint.yml); the scope is optional.

CI Labels

PR labels control which CI jobs run:

  • ci/skip-integration, ci/skip-provider-integration, ci/skip-unit, ci/skip-examples — skip test suites
  • ci/unit-only — skip integration/provider-integration/examples

Debugging

CDKTF_LOG_LEVEL=debug cdktn synth  # Verbose CDKTN output
JSII_DEBUG=1 pnpm build            # JSII debug output

Notable changes

CDKTN Rename

This project was renamed from cdktf to cdktn. Key constraints:

  • Package names change (@cdktf/* → @cdktn/*, cdktf → cdktn, cdktf-cli → cdktn-cli)
  • Internal symbols and logical IDs remain unchanged (Symbol.for("cdktf/*"), __cdktf_*)
  • Legacy config/env keys still supported (cdktf.json, CDKTF_*)
  • Prebuilt providers require cdktn as peer dependency (major bump)