tree-sitter-ucode 0.5.0 → 0.6.1

package/README.md

@@ -2,17 +2,24 @@
 
 Tree-sitter grammar for [ucode](https://github.com/jow-/ucode), the ECMAScript-like scripting language used in OpenWrt.
 
-Two grammars are provided:
+Three grammars are provided:
 
-| Grammar | Scope | File types |
-|---------|-------|------------|
-| `ucode` | `source.uc` | `.uc`, `.ucode`, `.ut` |
-| `ucode_markup` | `source.ucode.markup` | `.uc`, `.ucode`, `.ut`, `.uc.tmpl` (template files — detected by content) |
+| Grammar | Scope | File types | Purpose |
+|---------|-------|------------|---------|
+| `ucode` | `source.uc` | `.uc`, `.ucode`, `.ut` | Plain ucode source files |
+| `ucode_markup` | `source.ucode.markup` | `.uc`, `.ucode`, `.ut` (template files — detected by content) | Ucode template files mixing raw text and code tags |
+| `ucdocs` | — | injected | JSDoc-style `/** */` doc comment blocks |
+
+`ucode` and `ucode_markup` share file extensions. Template files are distinguished from plain
+code files by content: any file containing a tag opener (`{%`, `{{`, or `{#`) at the start
+of a line (with optional leading whitespace) is automatically parsed by `ucode_markup`. Plain
+code files fall back to `ucode`. See [File-type detection](#file-type-detection) below.
 
-Both grammars share the same file extensions. Template files are distinguished from plain
-code files by content: any file whose first tag opener (`{%`, `{{`, or `{#`) appears at
-the start of a line is automatically parsed by `ucode_markup`. Plain code files fall back
-to `ucode`. See [File-type detection](#file-type-detection) below.
+`ucdocs` is not a standalone file grammar — it is automatically injected by the `ucode` and
+`ucode_markup` grammars into every `/** */` doc comment block. Tools that load grammars
+directly from `tree-sitter.json` (including the tree-sitter CLI) handle this automatically.
+Editor plugins may require registering the `ucdocs` grammar separately — see the editor
+sections below.
 
 ## Ucode vs JavaScript
 
@@ -29,6 +36,34 @@ Ucode is an ECMAScript subset with OpenWrt-specific extensions. Key differences:
 | Regex flags | `g`, `i`, `s` only | Full set |
 | Module system | Static `import`/`export` only; no `from` on re-exports | Full ES modules |
 
+## Doc comment grammar (ucdocs)
+
+`/** */` blocks are parsed by the `ucdocs` grammar and injected into the host parse tree.
+The grammar understands the following tags:
+
+| Tag | Syntax |
+|-----|--------|
+| `@param` | `@param {Type} name description` |
+| `@returns` / `@return` | `@returns {Type} description` |
+| `@throws` / `@throw` | `@throws {Type} description` |
+| `@type` | `@type {Type}` |
+| `@typedef` | `@typedef {Type} TypeName` |
+| `@template` | `@template T, U` |
+| `@function` | `@function module:path#member` |
+| `@module` | `@module name` |
+| `@deprecated` | `@deprecated description` |
+| `@since` | `@since version` |
+| `@see` | `@see reference` |
+| `@example` | `@example code` |
+| `@default` | `@default value` |
+
+Type expressions support: primitives (`int`, `float`, `string`, `boolean`, `null`, `void`,
+`function`), `*`/`any`, `list<T>`, `dict<T>`, record types (`{field: T}`), named types
+(`TypeName`, `TypeName<T, U>`), cross-module refs (`module:path.To.Type`), named function
+types `(name: T) => U`, anonymous function types `function(T): U`, union `T | U`, nullable
+`?T`, and array postfix `T[]`. Inline `{@link ...}` tags and optional params `[name=default]`
+are also supported.
+
 ## Requirements
 
 - [tree-sitter CLI](https://github.com/tree-sitter/tree-sitter) ≥ 0.24
@@ -38,10 +73,10 @@ Ucode is an ECMAScript subset with OpenWrt-specific extensions. Key differences:
 
 ```sh
 npm install
-npm run build        # generate + compile Node.js bindings
+npm run build        # generate + compile Node.js bindings (ucode and ucode_markup only)
 ```
 
-To regenerate parsers after editing a grammar file:
+To regenerate parsers after editing a grammar file (run from the repo root):
 
 ```sh
 # ucode grammar
@@ -49,27 +84,33 @@ npx tree-sitter generate
 
 # ucode_markup grammar (generated from grammar.js — do not edit markup/grammar.js directly)
 node scripts/generate-markup-grammar.js
-cd markup && npx tree-sitter generate
+npx tree-sitter generate markup/grammar.js --output markup/src
+
+# ucdocs grammar (not included in npm run build — must be regenerated manually)
+npx tree-sitter generate ucdocs/grammar.js --output ucdocs/src
 ```
 
 ## Test
 
 ```sh
-npm test             # runs tree-sitter test for ucode and ucode_markup
+npm test             # builds and tests all three grammars (ucode, ucode_markup, ucdocs)
 ```
 
-To filter by corpus file name:
+To filter by corpus file name (run from the repo root):
 
 ```sh
 npx tree-sitter test --file-name control_flow
-cd markup && npx tree-sitter test --file-name markup
+(cd markup && npx tree-sitter test --file-name markup)
+(cd ucdocs && npx tree-sitter test --file-name tags)
+(cd ucdocs && npx tree-sitter test --file-name types)
 ```
 
 ## File-type detection
 
-Both grammars claim the same file extensions. Tools that respect `content-regex` in
+Both `ucode` and `ucode_markup` claim the same file extensions. Tools that respect `content-regex` in
 `tree-sitter.json` (including the tree-sitter CLI ≥ 0.24) automatically route
-template files to `ucode_markup` when a tag opener appears at the start of a line.
+template files to `ucode_markup` when a tag opener (`{%`, `{{`, or `{#`) appears at
+the start of a line (with optional leading whitespace).
 Editors that manage their own filetype dispatch (Neovim, Helix) need an explicit
 rule — see the editor sections below.
 
@@ -102,11 +143,15 @@ grammar       = "ucode_markup"
 
 [[grammar]]
 name   = "ucode"
-source = { git = "https://github.com/m00qek/tree-sitter-ucode", rev = "v0.5.0" }
+source = { git = "https://github.com/m00qek/tree-sitter-ucode", rev = "v0.6.0" }
 
 [[grammar]]
 name   = "ucode_markup"
-source = { git = "https://github.com/m00qek/tree-sitter-ucode", rev = "v0.5.0", subpath = "markup" }
+source = { git = "https://github.com/m00qek/tree-sitter-ucode", rev = "v0.6.0", subpath = "markup" }
+
+[[grammar]]
+name   = "ucdocs"
+source = { git = "https://github.com/m00qek/tree-sitter-ucode", rev = "v0.6.0", subpath = "ucdocs" }
 ```
 
 Helix does not support content-based filetype detection for shared extensions. For

package/markup/queries/injections.scm

@@ -38,3 +38,9 @@
 (for_alt_statement open: (_) increment: (_) @injection.content (#set! injection.language "ucode"))
 
 (for_in_alt_statement open: (_) right: (_) @injection.content (#set! injection.language "ucode"))
+
+; Inject ucdocs into JSDoc block comments (/** ... */).
+; The [^*/] guard excludes /*** section dividers (≥3 stars) and /**/ (empty, non-JSDoc).
+((comment) @injection.content
+  (#match? @injection.content "^/\\*\\*[^*/]")
+  (#set! injection.language "ucdocs"))

package/markup/src/parser.c

@@ -134501,8 +134501,8 @@ TS_PUBLIC const TSLanguage *tree_sitter_ucode_markup(void) {
     .max_reserved_word_set_size = 28,
     .metadata = {
       .major_version = 0,
-      .minor_version = 5,
-      .patch_version = 0,
+      .minor_version = 6,
+      .patch_version = 1,
     },
   };
   return &language;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tree-sitter-ucode",
-  "version": "0.5.0",
+  "version": "0.6.1",
   "description": "Ucode grammar for tree-sitter",
   "repository": {
     "type": "git",

package/queries/injections.scm

@@ -0,0 +1,5 @@
+; Inject ucdocs into JSDoc block comments (/** ... */).
+; The [^*/] guard excludes /*** section dividers (≥3 stars) and /**/ (empty, non-JSDoc).
+((comment) @injection.content
+  (#match? @injection.content "^/\\*\\*[^*/]")
+  (#set! injection.language "ucdocs"))

package/src/parser.c

@@ -113826,8 +113826,8 @@ TS_PUBLIC const TSLanguage *tree_sitter_ucode(void) {
     .max_reserved_word_set_size = 28,
     .metadata = {
       .major_version = 0,
-      .minor_version = 5,
-      .patch_version = 0,
+      .minor_version = 6,
+      .patch_version = 1,
     },
   };
   return &language;

package/src/scanner_impl.h

@@ -400,9 +400,7 @@ static bool scan_automatic_semicolon(TSLexer *lexer) {
 }
 
 static bool scan_ternary_qmark(TSLexer *lexer) {
-    while (lexer->lookahead != '\r' && lexer->lookahead != '\n' &&
-           lexer->lookahead != 0x2028 && lexer->lookahead != 0x2029 &&
-           iswspace(lexer->lookahead))
+    while (iswspace(lexer->lookahead))
         skip(lexer);
 
     if (lexer->lookahead != '?') return false;

package/tree-sitter.json

@@ -14,9 +14,21 @@
       "locals": [
         "queries/locals.scm"
       ],
+      "injections": [
+        "queries/injections.scm"
+      ],
       "tags": [
         "queries/tags.scm"
       ],
+      "folds": [
+        "queries/folds.scm"
+      ],
+      "indents": [
+        "queries/indents.scm"
+      ],
+      "textobjects": [
+        "queries/textobjects.scm"
+      ],
       "injection-regex": "^ucode$"
     },
     {
@@ -66,7 +78,7 @@
     }
   ],
   "metadata": {
-    "version": "0.5.0",
+    "version": "0.6.1",
     "license": "MIT",
     "description": "Ucode grammar for tree-sitter",
     "links": {

package/ucdocs/grammar.js

@@ -33,28 +33,24 @@ module.exports = grammar({
         $.see_tag,
         $.example_tag,
         $.default_tag,
+        $.function_tag,
+        $.module_tag,
         $.unknown_tag,
       )),
       $._end,
     ),
 
-    _begin: _ => seq('/', repeat('*')),
-    _end: _ => '/',
+    _begin: _ => token(seq('/', /\*+/)),
+    _end: _ => token(seq(/\*+/, '/')),
 
     // Used after a type_expression/rest_type_expression has already claimed `{` at
     // this position (param_tag, returns_tag, throws_tag) — excludes _brace_text so
     // it never competes with a legitimate {type} for the leading `{`.
-    _typed_description: $ => prec.right(seq(
-      choice($._text, $.inline_tag),
-      repeat(choice($._text, $.inline_tag)),
-    )),
+    _typed_description: $ => repeat1(choice($._text, $.inline_tag)),
 
     // Used wherever no type_expression can appear at the same position, so a bare
     // `{` can only be an inline tag or arbitrary brace-text (e.g. @example code).
-    _free_description: $ => prec.right(seq(
-      choice($._text, $.inline_tag, $._brace_text),
-      repeat(choice($._text, $.inline_tag, $._brace_text)),
-    )),
+    _free_description: $ => repeat1(choice($._text, $.inline_tag, $._brace_text)),
 
     // {@link target text} and similar inline JSDoc tags embedded in description text.
     inline_tag: $ => seq(
@@ -159,6 +155,29 @@ module.exports = grammar({
       optional(field('description', alias($._free_description, $.description))),
     ),
 
+    // @function module:X.Y#Z — identifies the qualified name of the documented function.
+    function_tag: $ => seq(
+      '@function',
+      optional(field('namepath', $.namepath)),
+    ),
+
+    // @module name — identifies the module this file documents.
+    module_tag: $ => seq(
+      '@module',
+      field('name', $.member_name),
+    ),
+
+    // module:X.Y#Z — a namepath referencing a specific member within a module.
+    // The #member suffix distinguishes instance methods from the module path itself.
+    namepath: $ => seq(
+      'module:',
+      field('path', $.module_path),
+      optional(seq('#', field('member', $.member_name))),
+    ),
+
+    // Member names cover lowercase (error), uppercase (ERR), and underscored (ulog_open).
+    member_name: _ => /[a-zA-Z_$][a-zA-Z0-9_$]*/,
+
     unknown_tag: $ => seq(
       $.tag_name,
       optional(field('description', alias($._free_description, $.description))),
@@ -185,9 +204,11 @@ module.exports = grammar({
       $.union_type,
       $.nullable_type,
       $.any_type,
+      $.parenthesized_type,
+      $.array_type,
     ),
 
-    primitive_type: _ => choice('int', 'float', 'string', 'boolean', 'null', 'void'),
+    primitive_type: _ => choice('int', 'float', 'string', 'boolean', 'null', 'void', 'function'),
 
     any_type: _ => choice('*', 'any'),
 
@@ -259,6 +280,14 @@ module.exports = grammar({
       optional(seq(':', field('return', $._type))),
     ),
 
+    // Explicit grouping: (T|U) to override default union associativity or
+    // for clarity in complex expressions like ?(T|U).
+    parenthesized_type: $ => seq('(', $._type, ')'),
+
+    // T[] postfix array notation.  Precedence 3 > nullable (2) > union (1)
+    // so ?T[] == ?(T[]) and T[]|U[] == (T[])|(U[]).
+    array_type: $ => prec(3, seq($._type, '[]')),
+
     // Left-associative so T | U | V parses as (T | U) | V.
     union_type: $ => prec.left(1, seq($._type, '|', $._type)),
 
@@ -271,7 +300,7 @@ module.exports = grammar({
     // Lowercase-starting names: parameter names and function param names.
     identifier: _ => /[a-z_$][a-zA-Z_$0-9]*/,
 
-    _text: _ => token(prec(-1, /[^*{}@\s][^*{}@\n]*/)),
+    _text: _ => token(prec(-1, /[^*{}@\s][^*{}@\n\r]*/)),
   },
 });
 

package/ucdocs/queries/highlights.scm

@@ -1,4 +1,7 @@
+; ── Tag keywords ──────────────────────────────────────────────────────────────
+
 (tag_name) @keyword
+
 (param_tag "@param" @keyword)
 (returns_tag ["@returns" "@return"] @keyword)
 (template_tag "@template" @keyword)
@@ -10,16 +13,72 @@
 (see_tag "@see" @keyword)
 (example_tag "@example" @keyword)
 (default_tag "@default" @keyword)
+(function_tag "@function" @keyword)
+(module_tag "@module" @keyword)
+
+; ── Names ──────────────────────────────────────────────────────────────────
 
 (type_param) @type.parameter
 (type_identifier) @type
 (primitive_type) @type.builtin
 (any_type) @type.builtin
-(module_type "module:" @module)
-(module_path) @module
 
 (identifier) @variable.parameter
+(record_field name: (identifier) @variable.member)
+(member_name) @variable.member
+
 (default_value) @constant
-(description) @comment
+
+; ── Module paths ────────────────────────────────────────────────────────────
+
+(module_type "module:" @module)
+(module_type path: (module_path) @module)
+(namepath "module:" @module)
+(namepath path: (module_path) @module)
+
+; ── Operators ───────────────────────────────────────────────────────────────
+
+(union_type "|" @operator)
+(nullable_type "?" @operator)
+(function_type "=>" @operator)
+(optional_param "=" @operator)
+
+; ── Punctuation: brackets ────────────────────────────────────────────────────
+
+(type_expression "{" @punctuation.bracket "}" @punctuation.bracket)
+(rest_type_expression "{" @punctuation.bracket "}" @punctuation.bracket)
+(record_type "{" @punctuation.bracket "}" @punctuation.bracket)
+(parenthesized_type "(" @punctuation.bracket ")" @punctuation.bracket)
+(function_type "(" @punctuation.bracket ")" @punctuation.bracket)
+(anon_function_type "(" @punctuation.bracket ")" @punctuation.bracket)
+(named_type "<" @punctuation.bracket ">" @punctuation.bracket)
+(list_type "<" @punctuation.bracket ">" @punctuation.bracket)
+(dict_type "<" @punctuation.bracket ">" @punctuation.bracket)
+(optional_param "[" @punctuation.bracket "]" @punctuation.bracket)
+(array_type "[]" @punctuation.bracket)
 (inline_tag "{" @punctuation.bracket "}" @punctuation.bracket)
-(inline_tag (tag_name) @keyword)
+
+; ── Punctuation: delimiters ──────────────────────────────────────────────────
+
+(record_type "," @punctuation.delimiter)
+(record_field ":" @punctuation.delimiter)
+(function_param ":" @punctuation.delimiter)
+(anon_function_type ":" @punctuation.delimiter)
+(namepath "#" @punctuation.delimiter)
+
+; ── Punctuation: special ─────────────────────────────────────────────────────
+
+(rest_type_expression "..." @punctuation.special)
+
+; ── Descriptions ─────────────────────────────────────────────────────────────
+
+(description) @comment
+
+; @spell only on prose-bearing tags; @example descriptions contain code.
+(document          (description) @spell)
+(param_tag         description: (description) @spell)
+(returns_tag       description: (description) @spell)
+(throws_tag        description: (description) @spell)
+(deprecated_tag    description: (description) @spell)
+(since_tag         description: (description) @spell)
+(see_tag           description: (description) @spell)