Style Guide
Everything you need to know before changing the DML interpreter or the dml-go library. Read the rules for all repositories first, then the section for the repository you are editing.
Rules for every change
- Do not add comments of any kind to any file: no
//,/* */,#, doc comments,TODOorFIXMEmarkers, section dividers or commented-out code. This includes.dmlfiles, the grammar and CI configuration. Express intent through names and structure, and explain a change in the pull request instead. - Leave existing comments untouched unless the change is about them.
- Follow the structure of the repository you are editing. Do not move, rename or restructure existing code in a change that is about something else.
- Treat every
.dmlfile as untrusted input. - Never commit secrets, keys or
.envfiles. - Ask before cutting a release, force-pushing or deleting data.
DML
The interpreter and command line tool. It is written in Kotlin 1.9 for the JVM 17, built with Gradle into a shadow jar (DML-all.jar), and uses an ANTLR 4.13 grammar, snakeyaml and kotlinx-serialization.
Commands
| Command | What it does |
|---|---|
./gradlew test | Runs the test suite |
./gradlew build | Builds and tests the project |
./gradlew shadowJar | Builds build/libs/DML-all.jar |
java -jar build/libs/DML-all.jar -r dml file.dml | Runs a DML file with the freshly built jar |
Structure
src/main/antlr/DML.g4 grammar
src/main/kotlin/Main.kt DMLInterpreter.kt
src/main/kotlin/cli/ Cli.kt, argument handling
src/main/kotlin/interpreter/ DMLExecutor.kt, SymbolTable.kt
src/test/kotlin/ JUnit 5, one class per concern, @TempDir for files
src/test/resources/ .dml fixtures used by tests
.circleci/config.yml test, build, release
Code style
- Classes are PascalCase and functions are camelCase. One concern per file.
- Tests use JUnit 5, one class per concern, and
@TempDirfor files. A test name states the scenario and the expected result. - Every interpreter, import or CLI change ships with a security test in
src/test/kotlin.
Security
The interpreter runs untrusted .dml input, so these rules are not negotiable.
- Never weaken the sandbox root, the import stack, the recursion limit, the file-size limit, the timeouts or the regex safeguards.
- Resolve every import path against the sandbox root after normalisation. Reject traversal, symlink escapes and absolute paths outside the root.
- Bound everything: recursion depth, import depth, file size, execution time and regex complexity. Fail with a clear error and never hang.
- Escape values on every output path (YAML, JSON, XML, environment interpolation). Error messages never include file contents or environment values.
- Never execute,
evalor shell out on data that comes from a.dmlfile. - A release publishes the jar together with its SHA-256 and updates the Homebrew formula in the same step. Keep plugin versions pinned.
dml-go
The Go library and command line tool that loads, parses, validates and caches .dml configuration files. The module is github.com/tree-software-company/dml-go and targets Go 1.21.
Commands
| Command | What it does |
|---|---|
go build -o bin/dml ./cmd/dml | Builds the command line tool |
go test ./... | Runs all tests |
gofmt -l . | Lists files that are not formatted |
go vet ./... | Reports suspicious code |
Structure
cmd/dml/main.go CLI entry only
dml/ public package: parser, config, env, error, lint
dml/*_test.go tests next to the code they cover
internal/ jar download and verification
examples/ testdata/ runnable examples and fixtures
Code style
- Standard Go style:
gofmtand tabs. - Exported names are documented by clear naming, not by comments.
- Wrap errors with
%w. - Tests are
_test.gofiles only, placed next to the code they cover.
Security
- Never skip or weaken the SHA-256 verification of the downloaded DML jar.
- The jar is downloaded only from a pinned version URL and verified against a pinned SHA-256 before use. Bump the version and the hash together.
- The download connection is also TLS-pinned by SPKI hash for each host in
internal/pins.go, and redirects must stay on HTTPS. Update the pins when GitHub changes its CA or CDN host.DML_LIVE_PIN_TEST=1 go test ./internal -run Livedetects stale pins. - Error messages and logs never contain environment variable values or file contents. Interpolation of environment values is explicit and allow-listed.
- Treat every
.dmlinput as untrusted: bound sizes and depth, and reject path traversal when resolving files. - Keep
testdata/.env.exampleto placeholders only. Do not commit.DS_Store. - Run
go vetandgovulncheck ./...before a release, and keepgo.sumcommitted.
Workflow
- Work for a minor version happens on a
release/x.ybranch, which is merged intomainwith a pull request. - DML releases are tagged
x.y.z, for example0.8.2. dml-go releases are taggedvX.Y.Z, for examplev0.10.0. - When dml-go moves to a new DML jar, update the pinned version and its SHA-256 in the same change.