Contributing

Architecture

src/
  extension.ts          # thin activation: register providers from the registry
  core/                 # language-agnostic engine (knows nothing about HCL)
    types.ts            # LanguageModule / Formatter / FormatOptions contracts
    registry.ts         # the list of supported languages
    formatting/         # provider wiring + formatted-string -> minimal edits
  languages/<lang>/     # one self-contained folder per language
    manifest.ts         # static metadata (id, extensions, grammar, config path)
    index.ts            # the LanguageModule (exposes createFormatter())
    lexer.ts            # tokenizer (from Stage 2)
    formatter.ts        # language-specific passes (from Stage 3)

Dependencies flow one way: languages/ → core/, never the reverse. No vscode types leak into core/types.ts or language formatters, so the formatting logic is pure and unit-testable without the editor host.

Adding a new language

1. Create src/languages/<lang>/ with manifest.ts (id, extensions, aliases, grammar scopeName + path, language-configuration path), index.ts (the LanguageModule), plus its lexer.ts / formatter.ts.
2. Add a syntaxes/<lang>.tmLanguage.json grammar and a language-configuration/<lang>.language-configuration.json.
3. Append the module to the array in src/core/registry.ts.
4. Run npm run sync-contributes to regenerate package.json contributes.languages / contributes.grammars from the registry.

The core/ engine is never modified to add a language.

Adding a new color theme

1. Drop the theme JSON into themes/ (the shipped JSONs are the “unified + neutral” look — all chrome surfaces share the editor background). Include editorBracketHighlight.foreground1..6 (we set all six to the palette’s op color so bracket-pair colorization stays calm) and editorBracketHighlight.unexpectedBracket.foreground.
2. Add one entry to src/themes/manifest.ts (id, picker label, file).
3. Add the matching palette subset to src/themes/palettes.ts (bg, bgSide, bgBar, line, dim, accent) — it powers the style-variant overlay (src/themes/variants.ts).
4. Run npm run sync-contributes to regenerate contributes.themes.

Scripts

npm run compile          # esbuild bundle -> dist/extension.js
npm run watch            # rebuild on change
npm run typecheck        # tsc --noEmit
npm run lint             # eslint
npm test                 # unit tests (node:test)
npm run test:grammar     # TextMate scope tests
npm run sync-contributes # regenerate package.json contributes from the registry
npm run sweep -- DIR     # diff every HCL file under DIR against terraform fmt
npm run build:vsix       # vsce package --no-dependencies