tree-sitter-aspx 0.0.0-stage → 0.1.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 M. Reifschneider
+
+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/NOTICE

@@ -0,0 +1,7 @@
+tree-sitter-aspx is an original grammar.
+
+An existing ASPX grammar was evaluated before this one was written.
+Its rules were not copied. No third-party grammar source is included
+in this repository.
+
+See LICENSE for the MIT license text.

package/README.md

@@ -1,3 +1,57 @@
-# Temporary Holding Version
+# tree-sitter-aspx
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![Verify](https://github.com/alfpricot/tree-sitter-aspx/actions/workflows/verify.yml/badge.svg?branch=dev)](https://github.com/alfpricot/tree-sitter-aspx/actions/workflows/verify.yml)
+[![Crates.io](https://img.shields.io/crates/v/tree-sitter-aspx)](https://crates.io/crates/tree-sitter-aspx)
+
+A [tree-sitter](https://tree-sitter.github.io/tree-sitter/) grammar for ASP.NET Web Forms markup: `.aspx` pages, `.ascx` user controls, `.master` master pages, and the directive headers of `.asax`, `.asmx`, and `.ashx` files, with Node and Rust bindings. Classic ASP (`.asp` with VBScript) and Razor (`.cshtml`, `.vbhtml`) are different languages and are out of scope, and code-behind files (`.aspx.cs`, `.aspx.vb`) are ordinary C# or VB.NET that this grammar does not parse.
+
+## Installation
+
+```sh
+npm install tree-sitter-aspx   # Node
+cargo add tree-sitter-aspx     # Rust
+```
+
+### Requirements
+
+- **Node:** the `tree-sitter` package, version `^0.25.0`, is an optional peer dependency. The binding is a Node-API addon with prebuilt copies for Linux and Windows; on any other platform the install compiles it from source and needs a C/C++ toolchain that `node-gyp` can use.
+- **Rust:** 1.85 or newer. The crate depends only on `tree-sitter-language`, so the `tree-sitter` version your own crate uses is the one that parses.
+
+## Usage
+
+The grammar parses directives, server comments, HTML comments, code nuggets, `<script>` and `<style>` elements, and tags with attributes. It does not validate HTML. Void tags (`br`, `img`, `meta`, and the other HTML void elements) do not swallow the following markup. An end tag closes the nearest open element; the names are not required to match. `<script>` and `<style>` bodies are raw text, so `<` inside JavaScript or CSS is not a tag.
+
+The C# and VB.NET inside a page are exposed as `c_sharp_code` and `vb_code` nodes, with injection queries for editors. See [docs/EMBEDDED_CODE.md](docs/EMBEDDED_CODE.md).
+
+### Node
+
+The default export exposes `name`, `language`, and `nodeTypeInfo` (the entries from `src/node-types.json`) on every platform, plus the `HIGHLIGHTS_QUERY` and `INJECTIONS_QUERY` strings.
+
+```js
+import Parser from 'tree-sitter';
+import Aspx from 'tree-sitter-aspx';
+
+const parser = new Parser();
+parser.setLanguage(Aspx);
+const tree = parser.parse('<%@ Page Language="C#" %>');
+console.log(tree.rootNode.toString());
+```
+
+### Rust
+
+```rust
+let mut parser = tree_sitter::Parser::new();
+parser
+    .set_language(&tree_sitter_aspx::LANGUAGE.into())
+    .expect("Error loading ASPX parser");
+```
+
+`LANGUAGE` is a `tree_sitter_language::LanguageFn`. The crate also exports `NODE_TYPES`, `HIGHLIGHTS_QUERY`, and `INJECTIONS_QUERY`.
+
+## How to contribute
+
+Branch from `dev` and open pull requests against it. [CONTRIBUTING.md](CONTRIBUTING.md) covers building the parser, running the checks CI runs, and the pull request rules; [ARCHITECTURE.md](ARCHITECTURE.md) explains how the pieces fit together.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

package/binding.gyp

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

package/bindings/node/binding.cc

@@ -0,0 +1,20 @@
+#include <napi.h>
+
+typedef struct TSLanguage TSLanguage;
+
+extern "C" TSLanguage *tree_sitter_aspx();
+
+// "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, "aspx");
+    auto language = Napi::External<TSLanguage>::New(env, tree_sitter_aspx());
+    language.TypeTag(&LANGUAGE_TYPE_TAG);
+    exports["language"] = language;
+    return exports;
+}
+
+NODE_API_MODULE(tree_sitter_aspx_binding, Init)

package/bindings/node/binding_test.js

@@ -0,0 +1,31 @@
+import assert from 'node:assert';
+import { test } from 'node:test';
+import Parser from 'tree-sitter';
+
+test('can load grammar', async () => {
+  const parser = new Parser();
+  await assert.doesNotReject(async () => {
+    const { default: language } = await import('./index.js');
+    parser.setLanguage(language);
+  });
+});
+
+test('exports node type metadata', async () => {
+  const { default: language } = await import('./index.js');
+  assert(Array.isArray(language.nodeTypeInfo));
+  assert(language.nodeTypeInfo.some((node) => node.type === 'document'));
+});
+
+test('exports the aspx language name', async () => {
+  const { default: language } = await import('./index.js');
+  assert.equal(language.name, 'aspx');
+});
+
+test('parses a page directive without error', async () => {
+  const { default: language } = await import('./index.js');
+  const parser = new Parser();
+  parser.setLanguage(language);
+  const tree = parser.parse('<%@ Page Language="C#" Inherits="Example.Page" %>');
+  assert.equal(tree.rootNode.hasError, false);
+  assert.equal(tree.rootNode.type, 'source_file');
+});

package/bindings/node/index.d.ts

@@ -0,0 +1,57 @@
+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 Aspx from "tree-sitter-aspx";
+ *
+ * const parser = new Parser();
+ * parser.setLanguage(Aspx);
+ */
+declare const binding: {
+  /** The language name. */
+  name: "aspx";
+
+  /**
+   * 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;
+};
+
+export default binding;

package/bindings/node/index.js

@@ -0,0 +1,41 @@
+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-aspx.node`)
+    : (await import('node-gyp-build')).default(root);
+
+try {
+  binding.nodeTypeInfo = JSON.parse(
+    readFileSync(new URL('../../src/node-types.json', import.meta.url), 'utf8'),
+  );
+} catch {
+  // node-types.json is optional metadata; the binding still works without it.
+}
+
+const queries = [
+  ['HIGHLIGHTS_QUERY', `${root}/queries/highlights.scm`],
+  ['INJECTIONS_QUERY', `${root}/queries/injections.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 {
+        // A missing query file leaves the property undefined.
+      }
+      return binding[prop];
+    },
+  });
+}
+
+export default binding;

package/grammar.js

@@ -0,0 +1,296 @@
+/// <reference types="tree-sitter-cli/dsl" />
+// @ts-check
+
+// Lexical precedence above the general tag/attribute names, so `script`,
+// `br`, and `Language` win when they are the same length as the general
+// pattern. Longer names (`scriptmanager`, `break`) still take the general
+// pattern because the lexer prefers the longest match.
+const RESERVED = 1;
+
+/**
+ * @param {string} word
+ */
+function reserved(word) {
+  return token(
+    prec(
+      RESERVED,
+      new RegExp(
+        word
+          .split('')
+          .map((ch) => {
+            const lower = ch.toLowerCase();
+            const upper = ch.toUpperCase();
+            return lower === upper
+              ? ch.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+              : `[${upper}${lower}]`;
+          })
+          .join(''),
+      ),
+    ),
+  );
+}
+
+const VOID_TAGS = [
+  'area',
+  'base',
+  'br',
+  'col',
+  'embed',
+  'hr',
+  'img',
+  'input',
+  'link',
+  'meta',
+  'param',
+  'source',
+  'track',
+  'wbr',
+];
+
+export default grammar({
+  name: 'aspx',
+
+  // A UTF-8 BOM is whitespace as far as the page parser is concerned. UTF-16
+  // files are decoded to UTF-8 before parsing; see tools/corpus-check.mjs.
+  extras: (_) => [/\s/, /\uFEFF/],
+
+  // Reserved names (`col`, `script`, `Language`, `WebHandler`) must not match
+  // a prefix of a longer name (`Columns`, `asp:ScriptManager`). Keywords are
+  // recognized only against this word token, so directive names and tag names
+  // both alias it.
+  word: ($) => $._name,
+
+  externals: ($) => [
+    $._lang_csharp,
+    $._lang_vb,
+    $._lang_other,
+    $._code_csharp,
+    $._code_vb,
+    $.server_comment_text,
+    $._script_csharp,
+    $._script_vb,
+    $.style_text,
+    $.expression_text,
+    $.handler_text,
+  ],
+
+  rules: {
+    // WebHandler / WebService files are a directive plus code, not markup.
+    // The reserved directive name is what selects that alternative. An empty
+    // file is the start rule matching nothing; `document` itself cannot be
+    // empty because tree-sitter rejects a non-start rule that matches "".
+    source_file: ($) => optional(choice($.handler_file, $.document)),
+
+    document: ($) => repeat1($._top),
+
+    handler_file: ($) =>
+      seq(
+        $.handler_directive,
+        repeat(choice($.server_comment, $.script_element, alias($.handler_text, $.handler_code))),
+      ),
+
+    _top: ($) => choice($._content, $.end_tag),
+
+    _content: ($) =>
+      choice(
+        $.directive,
+        $.server_comment,
+        $.html_comment,
+        $._nugget,
+        $.script_element,
+        $.style_element,
+        $.void_element,
+        $.self_closing_element,
+        $.element,
+        $.doctype,
+        $.text,
+      ),
+
+    directive: ($) => seq('<%@', field('name', $.directive_name), repeat($._attribute), '%>'),
+
+    handler_directive: ($) =>
+      seq(
+        '<%@',
+        field('name', alias(choice($.web_handler_name, $.web_service_name), $.directive_name)),
+        repeat($._attribute),
+        '%>',
+      ),
+
+    _name: (_) => /[A-Za-z_][A-Za-z0-9_.:-]*/,
+    directive_name: ($) => $._name,
+    web_handler_name: (_) => choice('WebHandler', 'webhandler', 'WEBHANDLER'),
+    web_service_name: (_) => choice('WebService', 'webservice', 'WEBSERVICE'),
+
+    // `Language` is its own attribute so the value is a language_value node
+    // and the scanner can record C# vs VB for later code tokens.
+    language_attribute: ($) =>
+      seq(
+        field('name', alias($.language_name, $.attribute_name)),
+        '=',
+        choice(
+          seq('"', field('value', $._language_value), '"'),
+          seq("'", field('value', $._language_value), "'"),
+        ),
+      ),
+
+    language_name: (_) => reserved('Language'),
+
+    _language_value: ($) =>
+      alias(choice($._lang_csharp, $._lang_vb, $._lang_other), $.language_value),
+
+    _attribute: ($) => choice($.language_attribute, $.attribute),
+
+    attribute: ($) =>
+      seq(
+        field('name', $.attribute_name),
+        optional(
+          seq(
+            '=',
+            field(
+              'value',
+              choice(
+                $.quoted_attribute_value,
+                alias($.unquoted_attribute_value, $.attribute_value),
+              ),
+            ),
+          ),
+        ),
+      ),
+
+    attribute_name: (_) => /[A-Za-z_:][A-Za-z0-9_.:-]*/,
+
+    quoted_attribute_value: ($) =>
+      choice(
+        seq('"', repeat($._double_quoted_chunk), '"'),
+        seq("'", repeat($._single_quoted_chunk), "'"),
+      ),
+
+    _double_quoted_chunk: ($) =>
+      choice(
+        $._nugget,
+        $.server_comment,
+        alias(/[^"<%]+/, $.attribute_value),
+        alias('%', $.attribute_value),
+        alias('<', $.attribute_value),
+      ),
+
+    _single_quoted_chunk: ($) =>
+      choice(
+        $._nugget,
+        $.server_comment,
+        alias(/[^'<%]+/, $.attribute_value),
+        alias('%', $.attribute_value),
+        alias('<', $.attribute_value),
+      ),
+
+    unquoted_attribute_value: (_) => /[^"'=<>\s`]+/,
+
+    server_comment: ($) => seq('<%--', optional($.server_comment_text), '--%>'),
+
+    // Nuggets inside an HTML comment still execute, so they stay real nodes.
+    html_comment: ($) =>
+      seq(
+        '<!--',
+        repeat(
+          choice(
+            $._nugget,
+            $.server_comment,
+            $.directive,
+            alias(/[^-<>]+/, $.comment_text),
+            alias('-', $.comment_text),
+            alias('<', $.comment_text),
+            alias('>', $.comment_text),
+          ),
+        ),
+        '-->',
+      ),
+
+    _nugget: ($) =>
+      choice(
+        $.encoded_expression,
+        $.output_expression,
+        $.binding_expression,
+        $.expression_builder,
+        $.statement_block,
+      ),
+
+    _embedded_code: ($) =>
+      choice(alias($._code_csharp, $.c_sharp_code), alias($._code_vb, $.vb_code)),
+
+    encoded_expression: ($) => seq('<%:', optional($._embedded_code), '%>'),
+    output_expression: ($) => seq('<%=', optional($._embedded_code), '%>'),
+    binding_expression: ($) => seq('<%#', optional($._embedded_code), '%>'),
+    statement_block: ($) => seq('<%', optional($._embedded_code), '%>'),
+
+    // Expression builders (`<%$ AppSettings:Key %>`) are not C# or VB.
+    expression_builder: ($) =>
+      seq('<%$', optional(alias($.expression_text, $.expression_value)), '%>'),
+
+    script_element: ($) =>
+      seq(
+        alias($.script_start_tag, $.start_tag),
+        optional(choice(alias($._script_csharp, $.c_sharp_code), alias($._script_vb, $.vb_code))),
+        alias($.script_end_tag, $.end_tag),
+      ),
+
+    script_start_tag: ($) =>
+      seq('<', field('name', alias($.script_tag_name, $.tag_name)), repeat($._attribute), '>'),
+
+    script_end_tag: ($) => seq('</', field('name', alias($.script_tag_name, $.tag_name)), '>'),
+
+    script_tag_name: (_) => reserved('script'),
+
+    style_element: ($) =>
+      seq(
+        alias($.style_start_tag, $.start_tag),
+        optional($.style_text),
+        alias($.style_end_tag, $.end_tag),
+      ),
+
+    style_start_tag: ($) =>
+      seq('<', field('name', alias($.style_tag_name, $.tag_name)), repeat($._attribute), '>'),
+
+    style_end_tag: ($) => seq('</', field('name', alias($.style_tag_name, $.tag_name)), '>'),
+
+    style_tag_name: (_) => reserved('style'),
+
+    void_element: ($) =>
+      seq(
+        '<',
+        field('name', alias($.void_tag_name, $.tag_name)),
+        repeat($._attribute),
+        choice('/>', '>'),
+      ),
+
+    void_tag_name: (_) => choice(...VOID_TAGS.map((name) => reserved(name))),
+
+    self_closing_element: ($) => seq('<', field('name', $.tag_name), repeat($._attribute), '/>'),
+
+    element: ($) => seq($.start_tag, repeat($._content), $.end_tag),
+
+    start_tag: ($) => seq('<', field('name', $.tag_name), repeat($._attribute), '>'),
+
+    end_tag: ($) =>
+      seq(
+        '</',
+        field(
+          'name',
+          choice(
+            alias($.script_tag_name, $.tag_name),
+            alias($.style_tag_name, $.tag_name),
+            alias($.void_tag_name, $.tag_name),
+            $.tag_name,
+          ),
+        ),
+        '>',
+      ),
+
+    tag_name: ($) => $._name,
+
+    doctype: ($) => seq($.doctype_token, optional(alias(/[^>]+/, $.doctype_declaration)), '>'),
+
+    doctype_token: (_) => token(prec(RESERVED, /<![Dd][Oo][Cc][Tt][Yy][Pp][Ee]/)),
+
+    text: (_) => /[^<\s][^<]*/,
+  },
+});

package/package.json

@@ -1,6 +1,70 @@
 {
   "name": "tree-sitter-aspx",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.3",
+  "description": "Tree-sitter grammar for ASP.NET Web Forms markup",
+  "main": "bindings/node",
+  "types": "bindings/node",
+  "scripts": {
+    "install": "node-gyp-build",
+    "prestart": "npx --yes --package=tree-sitter-cli@0.27.1 -- tree-sitter build --wasm",
+    "start": "npx --yes --package=tree-sitter-cli@0.27.1 -- tree-sitter playground",
+    "test": "node --test bindings/node/*_test.js",
+    "lint": "oxlint grammar.js tools bindings/node",
+    "format": "oxfmt \"grammar.js\" \"tools/*.mjs\" \"bindings/node/*.js\"",
+    "format:check": "oxfmt --check \"grammar.js\" \"tools/*.mjs\" \"bindings/node/*.js\""
+  },
+  "author": "M. Reifschneider",
+  "license": "MIT",
+  "dependencies": {
+    "node-addon-api": "8.9.2",
+    "node-gyp-build": "4.8.4"
+  },
+  "devDependencies": {
+    "node-gyp": "13.1.0",
+    "oxfmt": "0.74.0",
+    "oxlint": "1.89.0",
+    "tree-sitter": "0.25.1",
+    "tree-sitter-cli": "0.27.1"
+  },
+  "peerDependencies": {
+    "tree-sitter": "^0.25.0"
+  },
+  "peerDependenciesMeta": {
+    "tree-sitter": {
+      "optional": true
+    }
+  },
+  "gypfile": true,
+  "directories": {
+    "test": "test"
+  },
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/alfpricot/tree-sitter-aspx.git"
+  },
+  "bugs": {
+    "url": "https://github.com/alfpricot/tree-sitter-aspx/issues"
+  },
+  "homepage": "https://github.com/alfpricot/tree-sitter-aspx#readme",
+  "keywords": [
+    "parser",
+    "aspx",
+    "aspnet",
+    "tree-sitter"
+  ],
+  "files": [
+    "grammar.js",
+    "binding.gyp",
+    "bindings/node/*",
+    "queries/*",
+    "src/**",
+    "prebuilds/**",
+    "tree-sitter.json",
+    "NOTICE"
+  ],
+  "allowScripts": {
+    "tree-sitter-cli@0.27.1": true,
+    "tree-sitter@0.25.1": true
+  }
+}

package/queries/highlights.scm

@@ -0,0 +1,22 @@
+; Syntax highlighting for ASP.NET Web Forms markup.
+
+(directive_name) @keyword
+(tag_name) @tag
+(attribute_name) @attribute
+(attribute_value) @string
+(language_value) @type
+(doctype_token) @keyword
+(doctype_declaration) @string
+
+(server_comment) @comment
+(server_comment_text) @comment
+(html_comment) @comment
+(comment_text) @comment
+
+(text) @text
+(style_text) @string
+(expression_value) @string
+
+["<%" "<%=" "<%:" "<%#" "<%$" "%>" "<%@" "<%--" "--%>"] @punctuation.special
+["<" ">" "</" "/>"] @punctuation.bracket
+["="] @operator