Merge pull request #37 from useblocks/36-yaml-support

Implement YAML support

Author: patdhlk

docs/source/components/analyse.rst

@@ -47,7 +47,7 @@ Limitations
 
 **Current Limitations:**
 
-- **Language Support**: Only C/C++ (``//``, ``/* */``) and Python (``#``) comment styles are supported
+- **Language Support**: C/C++ (``//``, ``/* */``), C# (``//``, ``/* */``, ``///``), Python (``#``) and YAML (``#``) comment styles are supported
 - **Single Comment Style**: Each analysis run processes only one comment style at a time
 
 Extraction Examples

docs/source/components/configuration.rst

@@ -267,7 +267,7 @@ Specifies the comment syntax style used in the source code files. This determine
 
 **Type:** ``str``
 **Default:** ``"cpp"``
-**Supported values:** ``"cpp"``, ``"python"``
+**Supported values:** ``"cpp"``, ``"python"``, ``"cs"``, ``"yaml"``
 
 .. code-block:: toml
 
@@ -288,12 +288,22 @@ Specifies the comment syntax style used in the source code files. This determine
      - ``"cpp"``
      - ``//`` (single-line),
        ``/* */`` (multi-line)
-     - ``c``, ``h``, ``.cpp``, and ``.hpp``
+     - ``.c``, ``.ci``, ``.h``, ``.cpp``, ``.cc``, ``.cxx``, ``.hpp``, ``.hh``, ``.hxx`` and ``.ihl``
    * - Python
      - ``"python"``
      - ``#`` (single-line),
        ``""" """`` (docstrings)
      - ``.py``
+   * - C#
+     - ``"cs"``
+     - ``//`` (single-line),
+       ``/* */`` (multi-line),
+       ``///`` (XML doc comments)
+     - ``.cs``
+   * - YAML
+     - ``"yaml"``
+     - ``#`` (single-line)
+     - ``.yaml``, ``.yml``
 
 .. note:: Future versions may support additional programming languages. Currently, only C/C++ and Python comment styles are supported.
 

pyproject.toml

@@ -28,6 +28,7 @@ dependencies = [
   # https://github.com/tree-sitter/py-tree-sitter/issues/386#issuecomment-3101430799
   "tree-sitter~=0.25.1",
   "tree-sitter-c-sharp>=0.23.1",
+  "tree-sitter-yaml>=0.7.1",
 ]
 
 [build-system]

src/sphinx_codelinks/analyse/utils.py

@@ -17,6 +17,7 @@
     CommentType.python: {"function_definition", "class_definition"},
     CommentType.cpp: {"function_definition", "class_definition"},
     CommentType.cs: {"method_declaration", "class_declaration", "property_declaration"},
+    CommentType.yaml: {"block_mapping_pair", "block_sequence_item", "document"},
 }
 
 # initialize logger
@@ -43,6 +44,7 @@
             """
 CPP_QUERY = """(comment) @comment"""
 C_SHARP_QUERY = """(comment) @comment"""
+YAML_QUERY = """(comment) @comment"""
 
 
 def is_text_file(filepath: Path, sample_size: int = 2048) -> bool:
@@ -76,6 +78,11 @@ def init_tree_sitter(comment_type: CommentType) -> tuple[Parser, Query]:
 
         parsed_language = Language(tree_sitter_c_sharp.language())
         query = Query(parsed_language, C_SHARP_QUERY)
+    elif comment_type == CommentType.yaml:
+        import tree_sitter_yaml  # noqa: PLC0415
+
+        parsed_language = Language(tree_sitter_yaml.language())
+        query = Query(parsed_language, YAML_QUERY)
     else:
         raise ValueError(f"Unsupported comment style: {comment_type}")
     parser = Parser(parsed_language)
@@ -133,10 +140,96 @@ def find_next_scope(
     return None
 
 
+def _find_yaml_structure_in_block_node(
+    block_node: TreeSitterNode,
+) -> TreeSitterNode | None:
+    """Find YAML structure elements within a block_node."""
+    for grandchild in block_node.named_children:
+        if grandchild.type == "block_mapping":
+            for ggchild in grandchild.named_children:
+                if ggchild.type == "block_mapping_pair":
+                    return ggchild
+        elif grandchild.type == "block_sequence":
+            for ggchild in grandchild.named_children:
+                if ggchild.type == "block_sequence_item":
+                    return ggchild
+    return None
+
+
+def find_yaml_next_structure(node: TreeSitterNode) -> TreeSitterNode | None:
+    """Find the next YAML structure element after the comment node."""
+    current = node.next_named_sibling
+    while current:
+        if current.type in {
+            "block_mapping_pair",
+            "block_sequence_item",
+            "flow_mapping",
+            "flow_sequence",
+        }:
+            return current
+        if current.type == "document":
+            for child in current.named_children:
+                if child.type == "block_node":
+                    result = _find_yaml_structure_in_block_node(child)
+                    if result:
+                        return result
+        if current.type == "block_node":
+            result = _find_yaml_structure_in_block_node(current)
+            if result:
+                return result
+        current = current.next_named_sibling
+    return None
+
+
+def find_yaml_prev_sibling_on_same_row(node: TreeSitterNode) -> TreeSitterNode | None:
+    """Find a previous named sibling that is on the same row as the comment."""
+    comment_row = node.start_point.row
+    current = node.prev_named_sibling
+
+    while current:
+        # Check if this sibling ends on the same row as the comment starts
+        # This indicates it's an inline comment
+        if current.end_point.row == comment_row:
+            return current
+        # If we find a sibling that ends before the comment row, we can stop
+        # as we won't find any siblings on the same row going backwards
+        if current.end_point.row < comment_row:
+            break
+        current = current.prev_named_sibling
+
+    return None
+
+
+def find_yaml_associated_structure(node: TreeSitterNode) -> TreeSitterNode | None:
+    """Find the YAML structure (key-value pair, list item, etc.) associated with a comment."""
+    # First, check if this is an inline comment by looking for a previous sibling on the same row
+    prev_sibling_same_row = find_yaml_prev_sibling_on_same_row(node)
+    if prev_sibling_same_row:
+        return prev_sibling_same_row
+
+    # If no previous sibling on same row, try to find the next named sibling (structure after the comment)
+    structure = find_yaml_next_structure(node)
+    if structure:
+        return structure
+
+    # If no next sibling found, traverse up to find parent structure
+    parent = node.parent
+    while parent:
+        if parent.type in {"block_mapping_pair", "block_sequence_item"}:
+            return parent
+        parent = parent.parent
+
+    return None
+
+
 def find_associated_scope(
     node: TreeSitterNode, comment_type: CommentType = CommentType.cpp
 ) -> TreeSitterNode | None:
     """Find the associated scope of a comment."""
+    if comment_type == CommentType.yaml:
+        # YAML uses different structure association logic
+        return find_yaml_associated_structure(node)
+
     if node.type == CommentCategory.docstring:
         # Only for python's docstring
         return find_enclosing_scope(node, comment_type)

src/sphinx_codelinks/source_discover/config.py

@@ -9,13 +9,15 @@
     "cpp": ["c", "ci", "cpp", "cc", "cxx", "h", "hpp", "hxx", "hh", "ihl"],
     "python": ["py"],
     "cs": ["cs"],
+    "yaml": ["yml", "yaml"],
 }
 
 
 class CommentType(str, Enum):
     python = "python"
     cpp = "cpp"
     cs = "cs"
+    yaml = "yaml"
 
 
 class SourceDiscoverSectionConfigType(TypedDict, total=False):