chore: update type / README sync script

## Details

Script to update types & README based off init.lua is using an older
python module that is not compatible with 3.13. Use dedicated parsers
per language and update to latest tree sitter binding.

Author: MeanderingProgrammer

doc/render-markdown.txt

@@ -1,4 +1,4 @@
-*render-markdown.txt*          For 0.10.0         Last change: 2024 October 09
+*render-markdown.txt*          For 0.10.0         Last change: 2024 October 11
 
 ==============================================================================
 Table of Contents                          *render-markdown-table-of-contents*

justfile

@@ -2,6 +2,16 @@ init := "tests/minimal_init.lua"
 
 default: update test health
 
+update:
+  # Updates types.lua & README.md
+  python scripts/update.py
+  # https://pandoc.org/
+  # https://github.com/kdheepak/panvimdoc
+  ../../open-source/panvimdoc/panvimdoc.sh \
+    --project-name render-markdown \
+    --input-file README.md \
+    --vim-version 0.10.0
+
 test:
   just busted "tests"
 
@@ -14,9 +24,15 @@ busted directory:
   nvim --headless --noplugin -u {{init}} \
     -c "PlenaryBustedDirectory {{directory}} { minimal_init = '{{init}}', sequential = true, keep_going = false }"
 
+generate:
+  python scripts/generate.py
+
 health:
   nvim -c "checkhealth render-markdown" -- .
 
+cat-log:
+  cat ~/.local/state/nvim/render-markdown.log
+
 demo: demo-heading demo-list demo-box demo-latex demo-callout
 
 demo-heading:
@@ -48,19 +64,3 @@ demo-callout:
     --name "callout" \
     --height "750" \
     --content ""
-
-update:
-  # Updates types.lua & README.md
-  python -Wignore scripts/update.py
-  # https://pandoc.org/
-  # https://github.com/kdheepak/panvimdoc
-  ../../open-source/panvimdoc/panvimdoc.sh \
-    --project-name render-markdown \
-    --input-file README.md \
-    --vim-version 0.10.0
-
-cat-log:
-  cat ~/.local/state/nvim/render-markdown.log
-
-generate:
-  python scripts/generate.py

scripts/requirements.txt

@@ -1,2 +1,3 @@
-tree_sitter==0.21.3
-tree_sitter_languages==1.10.2
+tree_sitter==0.23.1
+tree-sitter-lua==0.2.0
+tree-sitter-markdown==0.3.2

scripts/update.py

@@ -1,85 +1,87 @@
-from dataclasses import dataclass
+from dataclasses import dataclass, field
+from functools import cached_property
 from pathlib import Path
 
-from tree_sitter_languages import get_language, get_parser
+import tree_sitter_lua
+import tree_sitter_markdown
+from tree_sitter import Language, Parser
 
 
 @dataclass(frozen=True)
 class LuaClass:
     name: str
-    fields: list[str]
+    fields: list[str] = field(default_factory=list)
 
-    def is_it(self, name: str) -> bool:
-        return name in self.name
+    @cached_property
+    def class_name(self) -> str:
+        # ---@class render.md.Init: render.md.Api                               -> Init
+        # ---@class (exact) render.md.UserBufferConfig                          -> UserBufferConfig
+        # ---@class (exact) render.md.UserConfig: render.md.UserBufferConfig    -> UserConfig
+        return self.name.split(":")[0].split()[-1].split(".")[-1]
+
+    @cached_property
+    def is_user(self) -> bool:
+        return self.class_name.startswith("User")
 
     def is_optional(self, field: str) -> bool:
-        optional_fields: list[str] = ["extends", "scope_highlight", "quote_icon"]
-        for optional_field in optional_fields:
-            if optional_field in field:
-                return True
-        return False
+        # ---@field public extends? boolean             -> extends
+        # ---@field public start_row integer            -> start_row
+        # ---@field public attach? fun(buf: integer)    -> attach
+        field_name = field.split()[2].replace("?", "")
+        return field_name in ["extends", "scope_highlight", "quote_icon"]
 
     def validate(self) -> None:
         for field in self.fields:
-            if self.is_it("User"):
-                self.validate_user_field(field)
-            else:
-                self.validate_non_user_field(field)
-
-    def validate_user_field(self, field: str) -> None:
-        # User classes are expected to have optional fields
-        assert "?" in field, f"Field must be optional: {field}"
-
-    def validate_non_user_field(self, field: str) -> None:
-        # Non user classes are expected to have mandatory fields with some exceptions
-        if not self.is_optional(field):
-            assert "?" not in field, f"Field must be mandatory: {field}"
-
-    def to_public_lines(self) -> list[str]:
-        if not self.is_it("User"):
-            return []
-
-        lines: list[str] = []
-        lines.append(self.name.replace("User", ""))
+            # User classes are expected to have optional fields with no exceptions
+            # Internal classes are expected to have mandatory fields with some exceptions
+            optional = self.is_user or self.is_optional(field)
+            message = "optional" if optional else "mandatory"
+            assert ("?" in field) == optional, f"Field must be {message}: {field}"
+
+    def to_internal(self) -> str:
+        lines: list[str] = [self.name.replace("User", "")]
         for field in self.fields:
-            if self.is_it("ConfigOverrides"):
+            if self.class_name == "UserConfigOverrides":
                 lines.append(field.replace("?", ""))
             elif self.is_optional(field):
                 lines.append(field)
             else:
                 lines.append(field.replace("User", "").replace("?", ""))
-        lines.append("")
-        return lines
+        return "\n".join(lines)
 
     def to_str(self) -> str:
-        lines: list[str] = [self.name]
-        lines.extend(self.fields)
-        return "\n".join(lines)
+        return "\n".join([self.name] + self.fields)
 
-    @staticmethod
-    def from_lines(lines: list[str]) -> "LuaClass":
-        return LuaClass(name=lines[0], fields=lines[1:])
+
+INIT_LUA = Path("lua/render-markdown/init.lua")
+TYPES_LUA = Path("lua/render-markdown/types.lua")
+README_MD = Path("README.md")
+HANDLERS_MD = Path("doc/custom-handlers.md")
 
 
 def main() -> None:
-    init_file = Path("lua/render-markdown/init.lua")
-    update_types(init_file, Path("lua/render-markdown/types.lua"))
-    update_readme(init_file, Path("README.md"))
-    update_custom_handlers(init_file, Path("doc/custom-handlers.md"))
+    update_types()
+    update_readme()
+    update_handlers()
 
 
-def update_types(init_file: Path, types_file: Path) -> None:
-    lines: list[str] = ["---@meta", ""]
-    for lua_class in get_classes(init_file):
+def update_types() -> None:
+    classes: list[str] = ["---@meta"]
+    for lua_class in get_classes():
         lua_class.validate()
-        lines.extend(lua_class.to_public_lines())
-    types_file.write_text("\n".join(lines))
+        if lua_class.is_user:
+            classes.append(lua_class.to_internal())
+    TYPES_LUA.write_text("\n\n".join(classes) + "\n")
+
 
+def update_readme() -> None:
 
-def update_readme(init_file: Path, readme_file: Path) -> None:
-    old_config = get_code_block(readme_file, "log_level", 1)
-    new_config = wrap_setup(get_default_config(init_file))
-    text = readme_file.read_text().replace(old_config, new_config)
+    def wrap_setup(value: str) -> str:
+        return f"require('render-markdown').setup({value})\n"
+
+    old_config = get_code_block(README_MD, "log_level", 1)
+    new_config = wrap_setup(get_default_config())
+    text = README_MD.read_text().replace(old_config, new_config)
 
     parameters: list[str] = [
         "heading",
@@ -96,52 +98,41 @@ def update_readme(init_file: Path, readme_file: Path) -> None:
         "indent",
     ]
     for parameter in parameters:
-        old_param = get_code_block(readme_file, f"\n    {parameter} = {{", 2)
+        old_param = get_code_block(README_MD, f"\n    {parameter} = {{", 2)
         new_param = wrap_setup(get_config_for(new_config, parameter))
         text = text.replace(old_param, new_param)
 
-    readme_file.write_text(text)
+    README_MD.write_text(text)
 
 
-def update_custom_handlers(init_file: Path, handler_file: Path) -> None:
-    class_name: str = "render.md.Handler"
-    old = get_code_block(handler_file, class_name, 1)
-    new = [
-        get_class(init_file, "render.md.Mark").to_str(),
-        "",
-        get_class(init_file, class_name).to_str(),
-    ]
-    text = handler_file.read_text().replace(old, "\n".join(new))
-    handler_file.write_text(text)
+def update_handlers() -> None:
+    name_to_lua = {lua.class_name: lua for lua in get_classes()}
+    mark = name_to_lua["Mark"]
+    handler = name_to_lua["Handler"]
 
+    old = get_code_block(HANDLERS_MD, mark.name, 1)
+    new = "\n".join([mark.to_str(), "", handler.to_str(), ""])
+    text = HANDLERS_MD.read_text().replace(old, new)
+    HANDLERS_MD.write_text(text)
 
-def get_class(init_file: Path, name: str) -> LuaClass:
-    lua_classes = get_classes(init_file)
-    results = [lua_class for lua_class in lua_classes if name in lua_class.name]
-    assert len(results) == 1
-    return results[0]
 
-
-def get_classes(init_file: Path) -> list[LuaClass]:
-    # Group comments into class + fields
+def get_classes() -> list[LuaClass]:
     lua_classes: list[LuaClass] = []
-    current: list[str] = []
-    for comment in get_comments(init_file):
-        comment_type: str = comment.split()[0].split("@")[-1]
-        if comment_type == "class":
-            if len(current) > 0:
-                lua_classes.append(LuaClass.from_lines(current))
-            current = [comment]
-        elif comment_type == "field":
-            current.append(comment)
-    lua_classes.append(LuaClass.from_lines(current))
+    for comment in get_comments():
+        # ---@class render.md.Init: render.md.Api       -> class
+        # ---@field public enabled? boolean             -> field
+        # ---@alias render.md.code.Width 'full'|'block' -> alias
+        # ---@type render.md.Config                     -> type
+        # ---@param opts? render.md.UserConfig          -> param
+        # -- Inlined with 'image' elements              -> --
+        annotation = comment.split()[0].split("@")[-1]
+        if annotation == "class":
+            lua_classes.append(LuaClass(comment))
+        elif annotation == "field":
+            lua_classes[-1].fields.append(comment)
     return lua_classes
 
 
-def wrap_setup(value: str) -> str:
-    return f"require('render-markdown').setup({value})"
-
-
 def get_config_for(config: str, parameter: str) -> str:
     lines: list[str] = config.splitlines()
     start: int = lines.index(f"    {parameter} = {{")
@@ -153,22 +144,24 @@ def get_config_for(config: str, parameter: str) -> str:
     return "\n".join(["{"] + lines[start : end + 1] + ["}"])
 
 
-def get_comments(file: Path) -> list[str]:
+def get_comments() -> list[str]:
     query = "(comment) @comment"
-    return ts_query(file, query, "comment")
+    return ts_query(INIT_LUA, query, "comment")
 
 
-def get_default_config(file: Path) -> str:
+def get_default_config() -> str:
     query = """
-        (variable_assignment(
-            (variable_list(
-                variable field: (identifier) @name
-                (#eq? @name "default_config")
-            ))
-            (expression_list value: (table)) @value
-        ))
+        (assignment_statement
+            (variable_list
+                name: (dot_index_expression
+                    field: (identifier) @name
+                    (#eq? @name "default_config")
+                )
+            )
+            (expression_list value: (table_constructor)) @value
+        )
     """
-    default_configs = ts_query(file, query, "value")
+    default_configs = ts_query(INIT_LUA, query, "value")
     assert len(default_configs) == 1
     return default_configs[0]
 
@@ -182,21 +175,19 @@ def get_code_block(file: Path, content: str, n: int) -> str:
 
 
 def ts_query(file: Path, query: str, target: str) -> list[str]:
-    ts_language: str = {
-        ".lua": "lua",
-        ".md": "markdown",
+    tree_sitter = {
+        ".lua": tree_sitter_lua,
+        ".md": tree_sitter_markdown,
     }[file.suffix]
-    parser = get_parser(ts_language)
-    tree = parser.parse(file.read_text().encode())
 
-    ts_query = get_language(ts_language).query(query)
-    captures = ts_query.captures(tree.root_node)
+    language = Language(tree_sitter.language())
+    tree = Parser(language).parse(file.read_text().encode())
+    captures = language.query(query).captures(tree.root_node)
 
-    values: list[str] = []
-    for node, capture in captures:
-        if capture == target:
-            values.append(node.text.decode())
-    return values
+    nodes = captures[target]
+    nodes.sort(key=lambda node: node.start_byte)
+    texts = [node.text for node in nodes]
+    return [text.decode() for text in texts if text is not None]
 
 
 if __name__ == "__main__":