1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
|
# dsk-cli
DSL Development Kit (DSK) – a CLI that helps you design, build, test, and ship Tree-sitter based Domain-Specific Languages (DSLs) with a convention-over-configuration workflow.
## Why this is helpful
- **Lower barrier to entry**: Generate a working Tree-sitter `grammar.js` from examples via an interactive flow.
- **No boilerplate**: One command builds both a C static library and a Node.js addon package.
- **Fast iteration**: Built-in watch mode (`dsk dev`) and testing (`dsk test`).
- **Editor-ready**: Generate Tree-sitter highlight queries and editor scaffolds (Neovim, Emacs, VS Code).
- **Consistent outputs**: Standardized project layout and generated artifacts under `generated/` and `dist/`.
## Prerequisites
- macOS or Linux
- [Bun](https://bun.sh) (to run `dsk`)
- [tree-sitter CLI](https://tree-sitter.github.io/tree-sitter/creating-parsers#installation) (`npm i -g tree-sitter-cli` or `brew install tree-sitter`)
- C toolchain: clang/gcc and `ar` (macOS: `xcode-select --install`, Ubuntu: `build-essential`)
- For the generated JS addon builds: Python 3 and make are typically required by node-gyp (the template depends on `node-gyp`)
## Install (for developing this CLI)
```bash
bun install
bunx tsc
bun link # optional: exposes `dsk` on your PATH during development
```
## Quickstart (creating a DSL)
```bash
# 1) Scaffold a new DSL project interactively
dsk new my-lang --interactive
# 2) Move into the project directory
cd my-lang
# 3) Build (generates parser, C lib, and JS addon)
dsk build
# 4) Run tests (expects corpus in `corpus/` or queries)
dsk test -v
# 5) Iterate with watch mode
dsk dev --debounce 150
# 6) Generate editor highlighting scaffolds
dsk highlight
# 7) Package outputs for distribution
dsk package
```
## Command reference
### `dsk new <name> [--interactive]`
Creates a new DSL project. With `--interactive`, it asks for examples and infers common token patterns, then generates a starter `grammar.js` and project structure using templates.
### `dsk build` [--verbose] [--skip-c] [--skip-js]
Builds your DSL:
- Runs `tree-sitter generate`
- Builds a C static library and header under `generated/c/`
- Creates a Node.js addon package under `generated/js/` (compiles via node-gyp)
Outputs:
- `generated/c/include/<dsl>.h`
- `generated/c/lib/lib<dsl>.a`
- `generated/js/` (package.json, binding.gyp, compiled addon, copied `src/`)
### `dsk test` [-u|--update] [-f|--filter <regex>] [--cwd <dir>] [-v|--verbose] [patterns...]
Thin wrapper around `tree-sitter test` that streams output directly.
- `--update`: updates expected output snapshots
- `--filter <regex>`: only run tests whose description matches
- `--cwd <dir>`: run tests in a different directory
- `--verbose`: pass through verbose output
Examples:
```bash
dsk test
dsk test -v -f numbers
dsk test -u corpus/examples.txt
```
### `dsk dev` [--debounce <ms>] [--quiet] [-v|--verbose]
Watches `grammar.js` and on changes runs `dsk build` then `dsk test`.
- `--debounce <ms>`: delay rebuild after changes (default: 150)
- `--quiet`: suppress non-error logs
- `--verbose`: pass to `dsk build` (more detailed build logs)
### `dsk highlight`
Generates highlighting assets and editor scaffolds:
- `generated/editors/tree-sitter/highlights.scm`
- `generated/editors/neovim/setup-instructions.md`
- `generated/editors/emacs/<lang>-mode.el`
- `generated/editors/vscode/syntaxes/<lang>.tmLanguage.json`
- `generated/editors/vscode/language-configuration.json`
### `dsk package`
Packages build outputs into `dist/`:
- Archives `generated/c/` as `dist/c-artifacts.tar.gz`
- Packs the JS addon under `generated/js/` via `bun pack` (falls back to `npm pack`)
### `dsk self:package`
Builds and packages the `dsk` CLI itself into a tarball under `release/`.
```bash
dsk self:package
# → release/dsk-cli-<version>.tgz
```
## Project structure (generated DSL project)
- `grammar.js`: Tree-sitter grammar
- `src/`: generated parser sources after `tree-sitter generate`
- `corpus/`: test cases for `tree-sitter test`
- `generated/`: build outputs (C and JS targets)
- `generated/editors/`: highlight queries and editor scaffolds
- `dist/`: packaged artifacts
## Notes about the JS addon template
- Depends on `node-addon-api` and `node-gyp` (declared in template `package.json`)
- `binding.gyp` includes Node-API headers and defines `NAPI_VERSION=8`
- Builds via `npm install` or `bun install` in `generated/js/` (auto-detected)
## Troubleshooting
- `tree-sitter` not found: install with `npm i -g tree-sitter-cli` or `brew install tree-sitter`
- C compiler not found: macOS `xcode-select --install`; Linux install `build-essential`
- node-gyp build issues: ensure Python 3 and make are available; re-run `dsk build -v`
---
This project was created using `bun init` in bun v1.1.29. [Bun](https://bun.sh) is a fast all-in-one JavaScript runtime.
|