tree-sitter-batch 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 WharfLab
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,150 @@
+# tree-sitter-batch
+
+Windows Batch/CMD grammar for [tree-sitter](https://github.com/tree-sitter/tree-sitter).
+
+Parses `.bat` and `.cmd` files into a concrete syntax tree for syntax highlighting, code navigation, and analysis.
+
+## Features
+
+- **Control flow** — `IF`/`ELSE` (EXIST, DEFINED, ERRORLEVEL, comparison with NOT), `FOR` (/D /R /L /F), `GOTO`, `CALL`
+- **Variables** — `SET` (plain, `/A` arithmetic, `/P` prompt), `%VAR%`, `!VAR!`, `%%i`, `%~dp0`, `%VAR:old=new%`
+- **Operators** — pipes `|`, redirects `>` `>>` `2>` `2>&1`, conditional `&&` `||`
+- **Structure** — labels `:name`, comments `REM` `::`, parenthesized blocks, `@ECHO OFF`
+- **Scope** — `SETLOCAL`/`ENDLOCAL` with `ENABLEDELAYEDEXPANSION`
+- **Case-insensitive** — all keywords match regardless of casing
+
+## Example
+
+```batch
+@echo off
+REM Build script
+setlocal enabledelayedexpansion
+
+set "PROJECT=MyApp"
+set /a VERSION=1
+
+if not exist "dist" (
+  mkdir dist
+)
+
+for %%f in (src\*.txt) do (
+  copy "%%f" "dist\"
+)
+
+if %ERRORLEVEL% == 0 (
+  echo Build successful
+) else (
+  echo Build failed
+  exit /b 1
+)
+
+exit /b 0
+```
+
+Parsed tree:
+
+```
+(program
+  (echo_off)
+  (comment)
+  (setlocal_stmt)
+  (variable_assignment)
+  (variable_assignment)
+  (if_stmt
+    (string)
+    (parenthesized
+      (cmd (command_name) (argument_list (argument_value)))))
+  (for_stmt
+    (for_variable)
+    (for_set)
+    (parenthesized
+      (cmd (command_name) (argument_list (string) (string)))))
+  (if_stmt
+    (variable_reference)
+    (comparison_op)
+    (integer)
+    (parenthesized
+      (cmd (command_name) (argument_list (argument_value) (argument_value))))
+    (else_clause
+      (parenthesized
+        (cmd (command_name) (argument_list (argument_value) (argument_value)))
+        (exit_stmt (integer)))))
+  (exit_stmt (integer)))
+```
+
+## Installation
+
+### npm
+
+```sh
+npm install tree-sitter-batch
+```
+
+### Cargo
+
+```sh
+cargo add tree-sitter-batch
+```
+
+### PyPI
+
+```sh
+pip install tree-sitter-batch
+```
+
+### Go
+
+```go
+import tree_sitter_batch "github.com/wharflab/tree-sitter-batch/bindings/go"
+```
+
+## Usage
+
+### Node.js
+
+```javascript
+import Parser from "tree-sitter";
+import Batch from "tree-sitter-batch";
+
+const parser = new Parser();
+parser.setLanguage(Batch);
+
+const tree = parser.parse(`@echo off\necho Hello World\n`);
+console.log(tree.rootNode.toString());
+```
+
+### Rust
+
+```rust
+let mut parser = tree_sitter::Parser::new();
+let language = tree_sitter_batch::LANGUAGE;
+parser.set_language(&language.into()).unwrap();
+
+let tree = parser.parse("@echo off\necho Hello\n", None).unwrap();
+println!("{}", tree.root_node().to_sexp());
+```
+
+### Python
+
+```python
+from tree_sitter import Language, Parser
+import tree_sitter_batch
+
+parser = Parser(Language(tree_sitter_batch.language()))
+tree = parser.parse(b"@echo off\necho Hello\n")
+print(tree.root_node.sexp())
+```
+
+## Syntax Highlighting
+
+The grammar ships with a `queries/highlights.scm` file for use in editors that support tree-sitter highlighting (Neovim, Helix, Zed, etc.).
+
+## References
+
+- Grammar informed by [Blinter](https://github.com/tboy1337/Blinter) batch file linter (159 rules)
+- [SS64 CMD reference](https://ss64.com/nt/)
+- [Microsoft CMD documentation](https://learn.microsoft.com/en-us/windows-server/administration/windows-commands/windows-commands)
+
+## License
+
+[MIT](LICENSE)

package/binding.gyp

@@ -0,0 +1,35 @@
+{
+  "targets": [
+    {
+      "target_name": "tree_sitter_batch_binding",
+      "dependencies": [
+        "<!(node -p \"require('node-addon-api').targets\"):node_addon_api_except",
+      ],
+      "include_dirs": [
+        "src",
+      ],
+      "sources": [
+        "bindings/node/binding.cc",
+        "src/parser.c",
+      ],
+      "variables": {
+        "has_scanner": "<!(node -p \"fs.existsSync('src/scanner.c')\")"
+      },
+      "conditions": [
+        ["has_scanner=='true'", {
+          "sources+": ["src/scanner.c"],
+        }],
+        ["OS!='win'", {
+          "cflags_c": [
+            "-std=c11",
+          ],
+        }, { # OS == "win"
+          "cflags_c": [
+            "/std:c11",
+            "/utf-8",
+          ],
+        }],
+      ],
+    }
+  ]
+}

package/bindings/node/binding.cc

@@ -0,0 +1,19 @@
+#include <napi.h>
+
+typedef struct TSLanguage TSLanguage;
+
+extern "C" TSLanguage *tree_sitter_batch();
+
+// "tree-sitter", "language" hashed with BLAKE2
+const napi_type_tag LANGUAGE_TYPE_TAG = {
+    0x8AF2E5212AD58ABF, 0xD5006CAD83ABBA16
+};
+
+Napi::Object Init(Napi::Env env, Napi::Object exports) {
+    auto language = Napi::External<TSLanguage>::New(env, tree_sitter_batch());
+    language.TypeTag(&LANGUAGE_TYPE_TAG);
+    exports["language"] = language;
+    return exports;
+}
+
+NODE_API_MODULE(tree_sitter_batch_binding, Init)

package/bindings/node/index.d.ts

@@ -0,0 +1,60 @@
+type BaseNode = {
+  type: string;
+  named: boolean;
+};
+
+type ChildNode = {
+  multiple: boolean;
+  required: boolean;
+  types: BaseNode[];
+};
+
+type NodeInfo =
+  | (BaseNode & {
+      subtypes: BaseNode[];
+    })
+  | (BaseNode & {
+      fields: { [name: string]: ChildNode };
+      children: ChildNode[];
+    });
+
+/**
+ * The tree-sitter language object for this grammar.
+ *
+ * @see {@linkcode https://tree-sitter.github.io/node-tree-sitter/interfaces/Parser.Language.html Parser.Language}
+ *
+ * @example
+ * import Parser from "tree-sitter";
+ * import Batch from "tree-sitter-batch";
+ *
+ * const parser = new Parser();
+ * parser.setLanguage(Batch);
+ */
+declare const binding: {
+  /**
+   * The inner language object.
+   * @private
+   */
+  language: unknown;
+
+  /**
+   * The content of the `node-types.json` file for this grammar.
+   *
+   * @see {@linkplain https://tree-sitter.github.io/tree-sitter/using-parsers/6-static-node-types Static Node Types}
+   */
+  nodeTypeInfo: NodeInfo[];
+
+  /** The syntax highlighting query for this grammar. */
+  HIGHLIGHTS_QUERY?: string;
+
+  /** The language injection query for this grammar. */
+  INJECTIONS_QUERY?: string;
+
+  /** The local variable query for this grammar. */
+  LOCALS_QUERY?: string;
+
+  /** The symbol tagging query for this grammar. */
+  TAGS_QUERY?: string;
+};
+
+export default binding;

package/bindings/node/index.js

@@ -0,0 +1,37 @@
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
+const root = fileURLToPath(new URL("../..", import.meta.url));
+
+const binding = typeof process.versions.bun === "string"
+  // Support `bun build --compile` by being statically analyzable enough to find the .node file at build-time
+  ? await import(`${root}/prebuilds/${process.platform}-${process.arch}/tree-sitter-batch.node`)
+  : (await import("node-gyp-build")).default(root);
+
+try {
+  const nodeTypes = await import(`${root}/src/node-types.json`, { with: { type: "json" } });
+  binding.nodeTypeInfo = nodeTypes.default;
+} catch { }
+
+const queries = [
+  ["HIGHLIGHTS_QUERY", `${root}/queries/highlights.scm`],
+  ["INJECTIONS_QUERY", `${root}/queries/injections.scm`],
+  ["LOCALS_QUERY", `${root}/queries/locals.scm`],
+  ["TAGS_QUERY", `${root}/queries/tags.scm`],
+];
+
+for (const [prop, path] of queries) {
+  Object.defineProperty(binding, prop, {
+    configurable: true,
+    enumerable: true,
+    get() {
+      delete binding[prop];
+      try {
+        binding[prop] = readFileSync(path, "utf8");
+      } catch { }
+      return binding[prop];
+    }
+  });
+}
+
+export default binding;

package/grammar.js

@@ -0,0 +1,116 @@
+const ci = (word) => new RegExp(word.split('').map((c) => /[a-zA-Z]/.test(c) ? `[${c.toLowerCase()}${c.toUpperCase()}]` : c).join(''));
+const kw = (word) => token(prec(10, ci(word)));
+
+export default grammar({
+  name: 'batch',
+  extras: () => [/[ \t]/],
+  rules: {
+    program: ($) => repeat(choice(seq($._stmt, /\r?\n/), /\r?\n/)),
+    _stmt: ($) => choice(
+      $.echo_off, $.comment, $.label, $.variable_assignment,
+      $.if_stmt, $.goto_stmt, $.call_stmt, $.exit_stmt,
+      $.setlocal_stmt, $.endlocal_stmt, $.for_stmt,
+      $.redirect_stmt, $.pipe_stmt, $.cond_exec,
+      $.parenthesized, $.cmd,
+    ),
+    echo_off: () => prec(10, seq('@', kw('echo'), choice(kw('off'), kw('on')))),
+    comment: () => token(prec(10, choice(
+      seq(optional('@'), /[rR][eE][mM]/, optional(seq(/[ \t]/, /[^\r\n]*/))),
+      seq('::', /[^\r\n]*/),
+    ))),
+    label: () => token(seq(':', /[a-zA-Z_][a-zA-Z0-9_-]*/)),
+    variable_assignment: () => prec(8, seq(
+      optional('@'), kw('set'),
+      optional(seq(/[ \t]+/, /\/[aApP]/)), /[ \t]+/,
+      choice(
+        seq('"', /[a-zA-Z_][a-zA-Z0-9_]*/, '=', optional(/[^"\r\n]*/), '"'),
+        seq(/[a-zA-Z_][a-zA-Z0-9_]*/, '=', optional(/[^\r\n]*/)),
+      ),
+    )),
+    if_stmt: ($) => prec.right(8, seq(
+      optional('@'), kw('if'),
+      optional(kw('not')),
+      choice(
+        seq(kw('exist'), choice($.string, $.variable_reference)),
+        seq(kw('defined'), /[a-zA-Z_][a-zA-Z0-9_]*/),
+        seq(kw('errorlevel'), $.integer),
+        seq(
+          choice($.string, $.variable_reference, $.integer),
+          $.comparison_op,
+          choice($.string, $.variable_reference, $.integer),
+        ),
+      ),
+      choice(
+        // Parenthesized form: supports else clause
+        seq($.parenthesized, optional($.else_clause)),
+        // Inline command form: no else (ambiguous)
+        $.cmd,
+      ),
+    )),
+    else_clause: ($) => prec.right(8, seq(
+      kw('else'),
+      choice($.parenthesized, $.cmd),
+    )),
+    comparison_op: () => token(prec(10, choice('==', ci('equ'), ci('neq'), ci('lss'), ci('leq'), ci('gtr'), ci('geq')))),
+    goto_stmt: () => prec(8, seq(
+      optional('@'), kw('goto'),
+      choice(token(prec(10, ci(':eof'))), token(seq(optional(':'), /[a-zA-Z_][a-zA-Z0-9_-]*/))),
+    )),
+    call_stmt: ($) => prec(8, seq(
+      optional('@'), kw('call'),
+      choice(token(seq(':', /[a-zA-Z_][a-zA-Z0-9_-]*/)), $.command_name),
+      optional($.argument_list),
+    )),
+    exit_stmt: ($) => prec(8, seq(
+      optional('@'), kw('exit'),
+      optional(choice(
+        seq(kw('/b'), choice($.integer, $.variable_reference)),
+        kw('/b'),
+        $.integer,
+      )),
+    )),
+    setlocal_stmt: () => prec(8, seq(
+      optional('@'), kw('setlocal'),
+      optional(choice(kw('enabledelayedexpansion'), kw('disabledelayedexpansion'), kw('enableextensions'), kw('disableextensions'))),
+    )),
+    endlocal_stmt: () => prec(8, seq(optional('@'), kw('endlocal'))),
+    for_stmt: ($) => prec(8, seq(
+      optional('@'), kw('for'),
+      optional($.for_options), $.for_variable,
+      kw('in'), '(', optional($.for_set), ')', kw('do'),
+      choice($.parenthesized, $.cmd),
+    )),
+    for_options: () => token(prec(10, choice(ci('/d'), seq(ci('/r'), optional(seq(/[ \t]+/, /[^\s]+/))), ci('/l'), seq(ci('/f'), optional(seq(/[ \t]+/, '"', /[^"]*/, '"')))))),
+    for_variable: () => token(seq('%%', optional('~'), /[a-zA-Z]/)),
+    for_set: () => /[^)\r\n]+/,
+    parenthesized: ($) => seq('(', repeat(choice(seq($._stmt, /\r?\n/), /\r?\n/)), ')'),
+    redirect_stmt: ($) => prec.right(4, seq(choice($.cmd, $.parenthesized), $.redirection)),
+    redirection: ($) => prec.right(seq(
+      optional(/[0-2]/), $.redirect_op, $.redirect_target,
+      optional(seq(optional(/[0-2]/), $.redirect_op, $.redirect_target)),
+    )),
+    redirect_op: () => token(choice('2>&1', '>&1', '2>>', '2>', '>>', '>', '<')),
+    redirect_target: () => token(choice(ci('nul'), ci('con'), /[^\s|&><\r\n]+/)),
+    pipe_stmt: ($) => prec.left(3, seq(choice($.cmd, $.parenthesized), '|', choice($.cmd, $.parenthesized))),
+    cond_exec: ($) => choice(
+      prec.left(2, seq(choice($.cmd, $.parenthesized), '&&', choice($.cmd, $.parenthesized))),
+      prec.left(1, seq(choice($.cmd, $.parenthesized), '||', choice($.cmd, $.parenthesized))),
+    ),
+    variable_reference: () => token(choice(
+      seq('%', /[a-zA-Z_][a-zA-Z0-9_]*/, '%'),
+      seq('%~', /[a-zA-Z]*/, /[0-9]/),
+      seq('%', /[0-9]/),
+      seq('%%', optional('~'), /[a-zA-Z]/),
+      seq('!', /[a-zA-Z_][a-zA-Z0-9_]*/, '!'),
+      seq('%', /[a-zA-Z_][a-zA-Z0-9_]*/, ':', /[^%]+/, '%'),
+    )),
+    string: () => token(seq('"', /[^"\r\n]*/, '"')),
+    cmd: ($) => prec.right(5, seq(optional('@'), $.command_name, optional($.argument_list))),
+    command_name: () => /[a-zA-Z_][a-zA-Z0-9_.-]*/,
+    argument_list: ($) => prec.right(repeat1($._arg)),
+    _arg: ($) => choice($.string, $.variable_reference, $.command_option, $.argument_value),
+    command_option: () => token(seq('/', /[a-zA-Z_?][a-zA-Z0-9_:]*/)),
+    argument_value: () => /[^\s|&><"\r\n%!][^\s|&><"\r\n]*/,
+    integer: () => /[0-9]+/,
+  },
+});

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "tree-sitter-batch",
+  "version": "0.1.0",
+  "description": "A Windows Batch/CMD grammar for tree-sitter",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/wharflab/tree-sitter-batch.git"
+  },
+  "license": "MIT",
+  "main": "bindings/node",
+  "types": "bindings/node",
+  "keywords": [
+    "incremental",
+    "parsing",
+    "tree-sitter",
+    "batch",
+    "cmd",
+    "bat"
+  ],
+  "files": [
+    "grammar.js",
+    "tree-sitter.json",
+    "binding.gyp",
+    "prebuilds/**",
+    "bindings/node/*",
+    "!bindings/node/*_test.js",
+    "queries/*",
+    "src/**",
+    "*.wasm"
+  ],
+  "dependencies": {
+    "node-addon-api": "^8.5.0",
+    "node-gyp-build": "^4.8.4"
+  },
+  "devDependencies": {
+    "eslint": "^9.15.0",
+    "eslint-config-treesitter": "^1.0.2",
+    "prebuildify": "^6.0.1",
+    "tree-sitter-cli": "^0.26.6"
+  },
+  "peerDependencies": {
+    "tree-sitter": "^0.25.0"
+  },
+  "peerDependenciesMeta": {
+    "tree-sitter": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "install": "node-gyp-build",
+    "prestart": "tree-sitter build --wasm",
+    "start": "tree-sitter playground",
+    "lint": "eslint grammar.js",
+    "test": "node --test bindings/node/*_test.js"
+  }
+}

package/queries/highlights.scm

@@ -0,0 +1,51 @@
+; Echo off/on
+(echo_off) @keyword
+
+; Comments
+(comment) @comment
+
+; Labels
+(label) @label
+
+; Variable assignment
+(variable_assignment) @variable
+
+; IF/FOR/GOTO/CALL statements
+(if_stmt) @keyword
+(for_stmt) @keyword
+(goto_stmt) @keyword
+(call_stmt) @keyword
+(setlocal_stmt) @keyword
+(endlocal_stmt) @keyword
+(exit_stmt) @keyword
+
+; Operators
+(comparison_op) @operator
+(redirect_op) @operator
+
+; Commands
+(command_name) @function
+
+; Variables
+(variable_reference) @variable
+
+; FOR loop variables
+(for_variable) @variable.parameter
+
+; FOR options
+(for_options) @constant
+
+; Strings
+(string) @string
+
+; Numbers
+(integer) @number
+
+; Command options/flags
+(command_option) @constant
+
+; Argument values
+(argument_value) @string
+
+; Redirect targets
+(redirect_target) @string.special