nlpp-grammar

nlpp-grammar

Tree-sitter grammar for NL++ — a pseudocode language for expressing software architecture and implementation intent to AI coding agents.

NL++ files use the .nlpp extension and language ID nlpp. The language lets you sketch structure, dependencies, and intent in a form that is both human-readable and toolable: syntax highlighting, autocomplete, import inlining, and symbol resolution, all feeding into a structured prompt ready for a coding agent.

---

Quick example

service OrderService {
    uses PaymentGateway

    method auto place_order(Order order) {
        uses PaymentGateway.charge
        /?
          Must be idempotent. Kick off fulfilment on success.
        ?/
    }

    ???
}

For the full language reference see nlpp-spec-v1.0.md.

---

What this repo contains

Path	Purpose
grammar.js	Tree-sitter grammar definition
src/	Generated C parser (output of tree-sitter generate)
queries/highlights.scm	Syntax highlighting capture groups (tree-sitter)
nlpp.tmLanguage.json	TextMate grammar — highlighting for editors/tools that don't run tree-sitter
bindings/node/	Node entry point — locates the WASM and queries (no parsing, no dependencies)
tree-sitter-nlpp.wasm	Compiled grammar; the artifact JS consumers actually load
test/	Corpus tests (tree-sitter test)
nlpp-spec-v1.0.md	Full NL++ language specification
CONTRIBUTING.md	Build system details, local install, and release workflow

---

Building

Requires the tree-sitter CLI.

npm install
tree-sitter generate     # regenerate src/ from grammar.js
tree-sitter build --wasm # compile the WASM grammar

npm run build runs generate + build in one step.

---

Testing

tree-sitter test       # corpus tests in test/corpus/
npm test               # Node.js binding tests

---

Syntax highlighting

Capture groups defined in queries/highlights.scm:

Capture	Tokens
@comment.line	// line comments
@comment.block	/* */ block comments
@keyword	define, uses, field, inherits, implements, custom block keywords
@keyword.import	import
@keyword.function	function, method, getter, setter
@keyword.type	object keywords (layer, module, service, component, class, interface, enum, type), auto
@keyword.modifier	public, private, override
@string	quoted strings ("…")
@string.special	prose delimiters /? ?/, prose text, ??? fill-in markers, hint text
@constant	define names
@type.definition	object and custom block names
@function	function / method / getter / setter names
@variable.member	field names
@type	type annotations (fields, parameters, return types)
@variable.parameter	parameter names
@variable	uses targets

TextMate grammar

nlpp.tmLanguage.json (the nlpp-grammar/textmate export) is a second grammar for NL++, in TextMate/regex form. tree-sitter is precise but not everywhere — this grammar covers the places it can't run:

• Editors, for highlight-on-open before a tree-sitter language server has started. VS Code registers it via contributes.grammars.
• The web, via Shiki and other TextMate-based highlighters, which consume it natively — the WASM is no help to them.

Being regex-based it is approximate where the tree-sitter grammar relies on a GLR conflict (the type-vs-name boundary and custom-block keywords); everything lexical, including recursive [ … ] template arguments, it gets exactly right. It is a hand-maintained duplicate of grammar.js, kept honest by a parity test (npm run test:parity) that asserts the two highlighters agree token by token. See CONTRIBUTING.md before editing either grammar.

---

Contributing / releasing

See CONTRIBUTING.md for local development setup, prebuild instructions, and the npm release workflow.