tree-sitter-ucode 0.6.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/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.6.0",
+  "version": "0.6.1",
   "description": "Ucode grammar for tree-sitter",
   "repository": {
     "type": "git",

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/tree-sitter.json

@@ -78,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

@@ -41,7 +41,7 @@ module.exports = grammar({
     ),
 
     _begin: _ => token(seq('/', /\*+/)),
-    _end: _ => 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

package/ucdocs/src/grammar.json

@@ -119,7 +119,7 @@
         "members": [
           {
             "type": "PATTERN",
-            "value": "\\**"
+            "value": "\\*+"
           },
           {
             "type": "STRING",