tree-sitter-glsl-spec 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Tin Švagelj
+
+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,106 @@
+# tree-sitter-glsl
+
+A [specification](https://github.com/KhronosGroup/GLSL)-compliant GLSL and ESSL
+parser for [tree-sitter](https://tree-sitter.github.io/) covering the full GLSL
+4.60 core grammar, all current Khronos extensions, and common real-world macro
+patterns.
+
+## Features
+
+- Full GLSL 4.60 and ESSL 3.20 grammar
+- All Khronos extension keywords, types, built-in functions, and variables
+- Structured preprocessor parsing (`#define`, `#if`/`#ifdef`/`#elif`/`#else`)
+- Macro expansion support for real-world shaders (`COMPAT_PRECISION`, `MYTYPE(args)`)
+- Multilingual header support (`#ifdef __cplusplus` language injection)
+- Extension-defined grammar rules (`demote`, `terminateInvocation`)
+
+## Queries
+
+| File | Purpose |
+|------|---------|
+| `highlights.scm` | Syntax highlighting with built-in function/variable/constant recognition |
+| `injections.scm` | Language injection for `#ifdef __cplusplus` / `__STDC__` guards |
+| `locals.scm` | Scope-aware local variable tracking |
+| `tags.scm` | Symbol indexing for code navigation |
+|-|-|
+| `version-tags.scm` | `#version`-dependent construct validation |
+| `constructor-heuristics.scm` | Opt-in heuristic for capitalized constructor calls |
+
+`version-tags.scm` and `constructor-heuristics.scm` are custom selectors,
+that might be useful in some cases, but you likely don't need them.
+
+## Usage
+
+### Node.js
+
+```javascript
+const Parser = require('tree-sitter');
+const GLSL = require('tree-sitter-glsl-spec');
+
+const parser = new Parser();
+parser.setLanguage(GLSL);
+const tree = parser.parse('void main() { gl_FragColor = vec4(1.0); }');
+```
+
+### Rust
+
+```rust
+let mut parser = tree_sitter::Parser::new();
+parser.set_language(&tree_sitter_glsl_spec::LANGUAGE.into()).unwrap();
+let tree = parser.parse("void main() { gl_FragColor = vec4(1.0); }", None).unwrap();
+```
+
+### Python
+
+```python
+import tree_sitter_glsl_spec as glsl
+from tree_sitter import Parser
+
+parser = Parser(glsl.language())
+tree = parser.parse(b"void main() { gl_FragColor = vec4(1.0); }")
+```
+
+## Development
+
+```bash
+npm install                                   # Install dependencies
+npx tree-sitter generate                      # Regenerate parser from grammar.js
+npx tree-sitter test                          # Run corpus tests
+npx eslint                                    # Lint
+npx tsc --noEmit                              # Type check
+node scripts/audit_node_types.js --coverage   # Grammar coverage analysis
+```
+
+The specification is included as a [git submodule](https://github.com/KhronosGroup/GLSL).
+Run `git submodule update --init` to fetch it for spec-scraping scripts.
+
+## References
+
+- Specification Document: [Khronos - The OpenGL Shading Language, Version 4.60](https://registry.khronos.org/OpenGL/specs/gl/GLSLangSpec.4.60.pdf)
+- Specification Repository (BNF): [GitHub - KhronosGroup/GLSL](https://github.com/KhronosGroup/GLSL)
+
+## Background
+
+This project began as a fork of [tree-sitter-glsl](https://github.com/tree-sitter-grammars/tree-sitter-glsl)
+by Stephan Seitz, which inherited its grammar from
+[tree-sitter-c](https://github.com/tree-sitter/tree-sitter-c). After running into
+too many quirks from the C grammar inheritance, I rewrote the grammar from scratch
+against the GLSL 4.60 specification.
+
+### Why not inherit from tree-sitter-c?
+
+GLSL's syntax is C-like but substantially simpler. A dedicated grammar provides:
+
+- **Fewer ambiguities** — 1 GLR conflict (without macros) vs C's 16. No pointers,
+  no K&R functions, no multi-word types, no `sizeof`/`typeof`, no casts.
+- **Flat expression trees** — identifiers and literals appear directly in the tree
+  without the `unary_expression > postfix_expression > primary_expression` wrapper
+  chain that a C-inherited grammar produces.
+- **GLSL-native nodes** — layout qualifiers with `name:`/`value:` fields, precision
+  qualifiers, interface blocks, `demote`/`terminateInvocation` extension statements.
+- **Specification fidelity** — every BNF production from the spec exists as a
+  (hidden or visible) rule, documented with the original grammar notation.
+
+## License
+
+This project is licensed under the [MIT](./LICENSE) license.

package/binding.gyp

@@ -0,0 +1,21 @@
+{
+  "targets": [
+    {
+      "target_name": "tree_sitter_glsl_binding",
+      "dependencies": [
+        "<!(node -p \"require('node-addon-api').targets\"):node_addon_api_except",
+      ],
+      "include_dirs": [
+        "src",
+      ],
+      "sources": [
+        "bindings/node/binding.cc",
+        "src/parser.c",
+        # NOTE: if your language has an external scanner, add it here.
+      ],
+      "cflags_c": [
+        "-std=c11",
+      ],
+    }
+  ]
+}

package/bindings/node/binding.cc

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

package/bindings/node/binding_test.js

@@ -0,0 +1,11 @@
+import assert from "node:assert";
+import { test } from "node:test";
+import Parser from "tree-sitter";
+
+test("can load grammar", () => {
+  const parser = new Parser();
+  assert.doesNotReject(async () => {
+    const { default: language } = await import("./index.js");
+    parser.setLanguage(language);
+  });
+});

package/bindings/node/index.d.ts

@@ -0,0 +1,91 @@
+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 Glsl from "tree-sitter-glsl-spec";
+ *
+ * const parser = new Parser();
+ * parser.setLanguage(Glsl);
+ */
+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[];
+
+  /**
+   * Syntax highlighting query. Maps GLSL nodes to highlight capture names
+   * (`@keyword`, `@function`, `@type`, `@operator`, `@variable`, etc.).
+   * Includes built-in function/variable/constant recognition.
+   */
+  HIGHLIGHTS_QUERY?: string;
+
+  /**
+   * Language injection query. Identifies `#ifdef __cplusplus` / `#ifdef __STDC__`
+   * guard blocks and marks their foreign-language content for injection
+   * (`cpp` or `c`).
+   *
+   * Requires `OPT.MULTILINGUAL` to be enabled in grammar.js before the C
+   * sources are generated.
+   */
+  INJECTIONS_QUERY?: string;
+
+  /**
+   * Local variable tracking query. Defines scopes (functions, blocks, loops)
+   * and tracks identifier definitions and references within them.
+   */
+  LOCALS_QUERY?: string;
+
+  /**
+   * Tags query for code navigation. Captures function definitions, type
+   * definitions, variable declarations, function calls, and type references.
+   */
+  TAGS_QUERY?: string;
+
+  /**
+   * Version tags query. Captures GLSL constructs whose availability depends
+   * on a minimum `#version` (e.g., `uint` requires 130, `double` requires 400).
+   * Intended for post-parse validation, not syntax highlighting.
+   */
+  VERSION_TAGS_QUERY?: string;
+
+  /**
+   * Constructor heuristic query. Identifies function calls where the callee
+   * is a user-defined type name (capitalized identifier), which are likely
+   * struct constructors. Opt-in — not included in default highlighting.
+   */
+  CONSTRUCTOR_HEURISTICS_QUERY?: string;
+};
+
+export default binding;

package/bindings/node/index.js

@@ -0,0 +1,39 @@
+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-glsl.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`],
+  ["VERSION_TAGS_QUERY", `${root}/queries/version-tags.scm`],
+  ["CONSTRUCTOR_HEURISTICS_QUERY", `${root}/queries/constructor-heuristics.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;