tree-sitter-ucode 0.4.0 → 0.5.0

package/tree-sitter.json

@@ -50,10 +50,23 @@
         "markup/queries/textobjects.scm"
       ],
       "injection-regex": "^ucode_markup$"
+    },
+    {
+      "name": "ucdocs",
+      "camelcase": "Ucdocs",
+      "path": "./ucdocs",
+      "file-types": null,
+      "highlights": [
+        "ucdocs/queries/highlights.scm"
+      ],
+      "tags": [
+        "ucdocs/queries/tags.scm"
+      ],
+      "injection-regex": "^ucdocs$"
     }
   ],
   "metadata": {
-    "version": "0.4.0",
+    "version": "0.5.0",
     "license": "MIT",
     "description": "Ucode grammar for tree-sitter",
     "links": {

package/ucdocs/grammar.js

@@ -0,0 +1,284 @@
+/**
+ * @file Ucdocs grammar for tree-sitter
+ * @license MIT
+ */
+
+/// <reference types="tree-sitter-cli/dsl" />
+// @ts-check
+
+module.exports = grammar({
+  name: 'ucdocs',
+
+  extras: _ => [
+    token(choice(
+      // Skip leading stars at the start of each line (e.g. " * " in block comments)
+      seq(/\n/, /[ \t]*/, repeat(seq('*', /[ \t]*/))),
+      /\s/,
+    )),
+  ],
+
+  rules: {
+    document: $ => seq(
+      $._begin,
+      optional(alias($._free_description, $.description)),
+      repeat(choice(
+        $.param_tag,
+        $.returns_tag,
+        $.template_tag,
+        $.typedef_tag,
+        $.type_tag,
+        $.throws_tag,
+        $.deprecated_tag,
+        $.since_tag,
+        $.see_tag,
+        $.example_tag,
+        $.default_tag,
+        $.unknown_tag,
+      )),
+      $._end,
+    ),
+
+    _begin: _ => seq('/', repeat('*')),
+    _end: _ => '/',
+
+    // 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)),
+    )),
+
+    // 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)),
+    )),
+
+    // {@link target text} and similar inline JSDoc tags embedded in description text.
+    inline_tag: $ => seq(
+      '{',
+      $.tag_name,
+      optional(alias($._free_description, $.description)),
+      '}',
+    ),
+
+    // A `{` not immediately followed by `@tagname` is not an inline tag — e.g. an
+    // object literal or arrow-function block in an @example code block. Recursive
+    // so nested braces (object literals inside arrow functions, etc.) stay balanced
+    // instead of erroring out on the first inner `}`.
+    _brace_text: $ => seq(
+      '{',
+      optional(seq(
+        /[^{}@]/,
+        repeat(choice(
+          /[^{}]+/,
+          $._brace_text,
+        )),
+      )),
+      '}',
+    ),
+
+    param_tag: $ => seq(
+      '@param',
+      optional(field('type', choice($.type_expression, $.rest_type_expression))),
+      optional(field('name', choice($.identifier, $.optional_param))),
+      optional(field('description', alias($._typed_description, $.description))),
+    ),
+
+    // [name] or [name=default] — marks the parameter as optional, JSDoc-style.
+    optional_param: $ => seq(
+      '[',
+      field('name', $.param_path),
+      optional(seq('=', field('default', $.default_value))),
+      ']',
+    ),
+
+    // Dotted parameter paths, e.g. opts.precision for nested option fields.
+    param_path: $ => seq(
+      $.identifier,
+      repeat(seq('.', $.identifier)),
+    ),
+
+    default_value: _ => token(choice(
+      /-?\d+(\.\d+)?/,
+      /[a-zA-Z_$][a-zA-Z0-9_$]*/,
+    )),
+
+    returns_tag: $ => seq(
+      choice('@returns', '@return'),
+      optional(field('type', $.type_expression)),
+      optional(field('description', alias($._typed_description, $.description))),
+    ),
+
+    template_tag: $ => seq(
+      '@template',
+      commaSep1(alias($.type_identifier, $.type_param)),
+    ),
+
+    typedef_tag: $ => seq(
+      '@typedef',
+      optional(field('type', $.type_expression)),
+      field('name', $.type_identifier),
+    ),
+
+    type_tag: $ => seq(
+      '@type',
+      field('type', $.type_expression),
+    ),
+
+    throws_tag: $ => seq(
+      choice('@throws', '@throw'),
+      optional(field('type', $.type_expression)),
+      optional(field('description', alias($._typed_description, $.description))),
+    ),
+
+    deprecated_tag: $ => seq(
+      '@deprecated',
+      optional(field('description', alias($._free_description, $.description))),
+    ),
+
+    since_tag: $ => seq(
+      '@since',
+      optional(field('description', alias($._free_description, $.description))),
+    ),
+
+    see_tag: $ => seq(
+      '@see',
+      optional(field('description', alias($._free_description, $.description))),
+    ),
+
+    example_tag: $ => seq(
+      '@example',
+      optional(field('description', alias($._free_description, $.description))),
+    ),
+
+    default_tag: $ => seq(
+      '@default',
+      optional(field('description', alias($._free_description, $.description))),
+    ),
+
+    unknown_tag: $ => seq(
+      $.tag_name,
+      optional(field('description', alias($._free_description, $.description))),
+    ),
+
+    tag_name: _ => /@[a-zA-Z_]+/,
+
+    // ── Type expressions ────────────────────────────────────────────────────
+
+    type_expression: $ => seq('{', $._type, '}'),
+
+    // {..Type} — only valid on @param, signals a rest/variadic parameter.
+    rest_type_expression: $ => seq('{', '...', $._type, '}'),
+
+    _type: $ => choice(
+      $.primitive_type,
+      $.list_type,
+      $.dict_type,
+      $.record_type,
+      $.named_type,
+      $.module_type,
+      $.function_type,
+      $.anon_function_type,
+      $.union_type,
+      $.nullable_type,
+      $.any_type,
+    ),
+
+    primitive_type: _ => choice('int', 'float', 'string', 'boolean', 'null', 'void'),
+
+    any_type: _ => choice('*', 'any'),
+
+    list_type: $ => seq(
+      'list',
+      '<',
+      field('element', $._type),
+      '>',
+    ),
+
+    dict_type: $ => seq(
+      'dict',
+      '<',
+      field('value', $._type),
+      '>',
+    ),
+
+    record_type: $ => seq(
+      '{',
+      commaSep($.record_field),
+      '}',
+    ),
+
+    record_field: $ => seq(
+      field('name', $.identifier),
+      ':',
+      field('type', $._type),
+    ),
+
+    // module:core.ParseConfig — cross-module type reference used by stdlib docs.
+    module_type: $ => seq(
+      'module:',
+      field('path', $.module_path),
+    ),
+
+    module_path: _ => /[a-zA-Z_$][a-zA-Z0-9_$]*(\.[a-zA-Z_$][a-zA-Z0-9_$]*)*/,
+
+    // Covers bare TypeName and generic TypeName<T>, TypeName<T, U>, etc.
+    named_type: $ => seq(
+      field('name', $.type_identifier),
+      optional(seq(
+        '<',
+        field('params', commaSep1($._type)),
+        '>',
+      )),
+    ),
+
+    function_type: $ => seq(
+      '(',
+      field('params', commaSep($.function_param)),
+      ')',
+      '=>',
+      field('return', $._type),
+    ),
+
+    function_param: $ => seq(
+      field('name', $.identifier),
+      ':',
+      field('type', $._type),
+    ),
+
+    // JSDoc anonymous function syntax: function(T, U): V (no parameter names).
+    // Return type is optional to allow bare function(T) declarations.
+    anon_function_type: $ => seq(
+      'function',
+      '(',
+      field('params', commaSep($._type)),
+      ')',
+      optional(seq(':', field('return', $._type))),
+    ),
+
+    // Left-associative so T | U | V parses as (T | U) | V.
+    union_type: $ => prec.left(1, seq($._type, '|', $._type)),
+
+    // ?T is sugar for T | null; higher precedence than union so ?T | U == (?T) | U.
+    nullable_type: $ => prec(2, seq('?', $._type)),
+
+    // PascalCase names: typedef references and type parameters.
+    type_identifier: _ => /[A-Z][a-zA-Z0-9]*/,
+
+    // Lowercase-starting names: parameter names and function param names.
+    identifier: _ => /[a-z_$][a-zA-Z_$0-9]*/,
+
+    _text: _ => token(prec(-1, /[^*{}@\s][^*{}@\n]*/)),
+  },
+});
+
+function commaSep(rule) {
+  return optional(commaSep1(rule));
+}
+
+function commaSep1(rule) {
+  return seq(rule, repeat(seq(',', rule)));
+}

package/ucdocs/queries/highlights.scm

@@ -0,0 +1,25 @@
+(tag_name) @keyword
+(param_tag "@param" @keyword)
+(returns_tag ["@returns" "@return"] @keyword)
+(template_tag "@template" @keyword)
+(typedef_tag "@typedef" @keyword)
+(type_tag "@type" @keyword)
+(throws_tag ["@throws" "@throw"] @keyword)
+(deprecated_tag "@deprecated" @keyword)
+(since_tag "@since" @keyword)
+(see_tag "@see" @keyword)
+(example_tag "@example" @keyword)
+(default_tag "@default" @keyword)
+
+(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
+(default_value) @constant
+(description) @comment
+(inline_tag "{" @punctuation.bracket "}" @punctuation.bracket)
+(inline_tag (tag_name) @keyword)

package/ucdocs/queries/tags.scm

@@ -0,0 +1,22 @@
+(template_tag
+  (type_param) @template.param)
+
+(param_tag
+  type: (_)? @param.type
+  name: (_)? @param.name
+  description: (description)? @param.description)
+
+(returns_tag
+  type: (type_expression) @returns.type
+  description: (description)? @returns.description)
+
+(throws_tag
+  type: (type_expression)? @throws.type
+  description: (description)? @throws.description)
+
+(typedef_tag
+  type: (type_expression)? @typedef.type
+  name: (type_identifier) @typedef.name)
+
+(type_tag
+  type: (type_expression) @type.type)