✨ Add TypeScript comment type support (issue #69)

docs/source/components/analyse.rst

@@ -47,7 +47,7 @@ Limitations
 
 **Current Limitations:**
 
-- **Language Support**: C/C++ (``//``, ``/* */``), C# (``//``, ``/* */``, ``///``), Python (``#``), YAML (``#``), Rust (``//``, ``/* */``, ``///``), Go (``//``, ``/* */``) and JSONC (``//``, ``/* */``) comment styles are supported
+- **Language Support**: C/C++ (``//``, ``/* */``), C# (``//``, ``/* */``, ``///``), TypeScript (``//``, ``/* */``), Python (``#``), YAML (``#``), Rust (``//``, ``/* */``, ``///``), Go (``//``, ``/* */``) and JSONC (``//``, ``/* */``) 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

@@ -271,7 +271,7 @@ Specifies the comment syntax style used in the source code files. This determine
 
 **Type:** ``str``
 **Default:** ``"cpp"``
-**Supported values:** ``"cpp"``, ``"python"``, ``"cs"``, ``"yaml"``, ``"rust"``, ``"go"``, ``"jsonc"``
+**Supported values:** ``"cpp"``, ``"python"``, ``"cs"``, ``"ts"``, ``"yaml"``, ``"rust"``, ``"go"``, ``"jsonc"``
 
 .. code-block:: toml
 
@@ -304,6 +304,11 @@ Specifies the comment syntax style used in the source code files. This determine
        ``/* */`` (multi-line),
        ``///`` (XML doc comments)
      - ``.cs``
+   * - TypeScript
+     - ``"ts"``
+     - ``//`` (single-line),
+       ``/* */`` (multi-line)
+     - ``.ts``, ``.tsx``
    * - YAML
      - ``"yaml"``
      - ``#`` (single-line)

docs/source/components/discover.rst

@@ -38,3 +38,13 @@ Usage Examples
    include = []
    exclude = ["tests/**", "setup.py"]
    comment_type = "python"
+
+**TypeScript Project:**
+
+.. code-block:: toml
+
+   [source_discover]
+   src_dir = "./frontend"
+   include = ["**/*.ts", "**/*.tsx"]
+   exclude = ["**/*.test.ts", "**/*.spec.ts"]
+   comment_type = "ts"

docs/source/development/change_log.rst

@@ -3,6 +3,20 @@
 Changelog
 =========
 
+Under development
+-----------------
+
+New and Improved
+................
+
+- ✨ Added TypeScript comment type support for source discovery and analysis.
+
+  TypeScript files can now be processed using ``comment_type = "ts"``.
+  Source discovery supports both ``.ts`` and ``.tsx`` extensions by default.
+
+Fixes
+.....
+
 .. _`release:1.3.0`:
 
 1.3.0

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-typescript>=0.23.2",
   "tree-sitter-yaml>=0.7.1",
   "tree-sitter-rust>=0.23.0",
   "tree-sitter-go>=0.23.0",

src/sphinx_codelinks/analyse/utils.py

@@ -28,6 +28,13 @@
     # @C and C++ Scope Node Types, IMPL_C_2, impl, [FE_C_SUPPORT, FE_CPP]
     CommentType.cpp: {"function_definition", "class_definition"},
     CommentType.cs: {"method_declaration", "class_declaration", "property_declaration"},
+    CommentType.ts: {
+        "function_declaration",
+        "class_declaration",
+        "method_definition",
+        "lexical_declaration",
+        "variable_declaration",
+    },
     # @Rust Scope Node Types, IMPL_RUST_2, impl, [FE_RUST];
     CommentType.rust: {
         "function_item",
@@ -64,6 +71,7 @@
             """
 CPP_QUERY = """(comment) @comment"""
 C_SHARP_QUERY = """(comment) @comment"""
+TYPE_SCRIPT_QUERY = """(comment) @comment"""
 YAML_QUERY = """(comment) @comment"""
 RUST_QUERY = """
     (line_comment) @comment
@@ -120,6 +128,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.ts:
+        import tree_sitter_typescript  # noqa: PLC0415
+
+        parsed_language = Language(tree_sitter_typescript.language_typescript())
+        query = Query(parsed_language, TYPE_SCRIPT_QUERY)
     elif comment_type == CommentType.yaml:
         import tree_sitter_yaml  # noqa: PLC0415
 

src/sphinx_codelinks/source_discover/config.py

@@ -9,6 +9,7 @@
     "cpp": ["c", "ci", "cpp", "cc", "cxx", "h", "hpp", "hxx", "hh", "ihl"],
     "python": ["py"],
     "cs": ["cs"],
+    "ts": ["ts", "tsx"],
     "yaml": ["yml", "yaml"],
     "rust": ["rs"],
     "go": ["go"],
@@ -20,6 +21,7 @@ class CommentType(str, Enum):
     python = "python"
     cpp = "cpp"
     cs = "cs"
+    ts = "ts"
     yaml = "yaml"
     # @Support Rust style comments, IMPL_RUST_1, impl, [FE_RUST];
     rust = "rust"

tests/data/discover_fixtures.json

@@ -75,7 +75,9 @@
     "config": {
       "src_dir": "src",
       "include": [],
-      "exclude": ["**/build/**"],
+      "exclude": [
+        "**/build/**"
+      ],
       "gitignore": false,
       "comment_type": "cpp"
     },
@@ -94,7 +96,9 @@
     },
     "config": {
       "src_dir": "src",
-      "include": ["**/*.cpp"],
+      "include": [
+        "**/*.cpp"
+      ],
       "exclude": [],
       "gitignore": false,
       "comment_type": "cpp"
@@ -115,8 +119,12 @@
     },
     "config": {
       "src_dir": "src",
-      "include": ["**/*.cpp"],
-      "exclude": ["**/test_*.cpp"],
+      "include": [
+        "**/*.cpp"
+      ],
+      "exclude": [
+        "**/test_*.cpp"
+      ],
       "gitignore": false,
       "comment_type": "cpp"
     },
@@ -280,7 +288,9 @@
     "config": {
       "src_dir": "src",
       "include": [],
-      "exclude": ["**/test_*.cpp"],
+      "exclude": [
+        "**/test_*.cpp"
+      ],
       "gitignore": true,
       "comment_type": "cpp"
     },
@@ -386,5 +396,27 @@
     "expected": [
       "src/Program.cs"
     ]
+  },
+  {
+    "name": "typescript_comment_type",
+    "description": "TypeScript comment type discovers .ts and .tsx files",
+    "git_init": false,
+    "files": {
+      "src/main.ts": "// main",
+      "src/component.tsx": "// component",
+      "src/main.cpp": "// not ts",
+      "src/util.py": "# not ts"
+    },
+    "config": {
+      "src_dir": "src",
+      "include": [],
+      "exclude": [],
+      "gitignore": false,
+      "comment_type": "ts"
+    },
+    "expected": [
+      "src/component.tsx",
+      "src/main.ts"
+    ]
   }
 ]

tests/data/typescript/demo.ts

@@ -0,0 +1,17 @@
+// regular comment
+function testA() {
+    // @type,TS_REQ_002,TypeScript one-line test
+    return 1;
+}
+
+/* regular block comment */
+const testB = () => {
+    return 2;
+};
+
+// another comment
+class Demo {
+    methodA() {
+        return 3;
+    }
+}

tests/test_analyse.py

@@ -56,101 +56,119 @@ def test_analyse(src_dir, src_paths, tmp_path, snapshot_marks):
 
 
 @pytest.mark.parametrize(
-    "src_dir, src_paths , oneline_comment_style, result",
+    "case",
     [
-        (
-            TEST_DIR / "data" / "dcdc",
-            [
+        {
+            "src_dir": TEST_DIR / "data" / "dcdc",
+            "src_paths": [
                 TEST_DIR / "data" / "dcdc" / "charge" / "demo_1.cpp",
                 TEST_DIR / "data" / "dcdc" / "charge" / "demo_2.cpp",
                 TEST_DIR / "data" / "dcdc" / "discharge" / "demo_3.cpp",
                 TEST_DIR / "data" / "dcdc" / "supercharge.cpp",
             ],
-            ONELINE_COMMENT_STYLE,
-            {
+            "comment_type": "cpp",
+            "oneline_comment_style": ONELINE_COMMENT_STYLE,
+            "result": {
                 "num_src_files": 4,
                 "num_uncached_files": 4,
                 "num_cached_files": 0,
                 "num_comments": 29,
                 "num_oneline_warnings": 0,
             },
-        ),
-        (
-            TEST_DIR / "data" / "oneline_comment_basic",
-            [
+        },
+        {
+            "src_dir": TEST_DIR / "data" / "oneline_comment_basic",
+            "src_paths": [
                 TEST_DIR / "data" / "oneline_comment_basic" / "basic_oneliners.c",
             ],
-            ONELINE_COMMENT_STYLE,
-            {
+            "comment_type": "cpp",
+            "oneline_comment_style": ONELINE_COMMENT_STYLE,
+            "result": {
                 "num_src_files": 1,
                 "num_uncached_files": 1,
                 "num_cached_files": 0,
                 "num_comments": 14,
                 "num_oneline_warnings": 0,
                 "warnings_path_exists": True,
             },
-        ),
-        (
-            TEST_DIR / "data" / "oneline_comment_default",
-            [
+        },
+        {
+            "src_dir": TEST_DIR / "data" / "oneline_comment_default",
+            "src_paths": [
                 TEST_DIR / "data" / "oneline_comment_default" / "default_oneliners.c",
             ],
-            ONELINE_COMMENT_STYLE_DEFAULT,
-            {
+            "comment_type": "cpp",
+            "oneline_comment_style": ONELINE_COMMENT_STYLE_DEFAULT,
+            "result": {
                 "num_src_files": 1,
                 "num_uncached_files": 1,
                 "num_cached_files": 0,
                 "num_comments": 5,
                 "num_oneline_warnings": 1,
                 "warnings_path_exists": True,
             },
-        ),
-        (
-            TEST_DIR / "data" / "rust",
-            [
+        },
+        {
+            "src_dir": TEST_DIR / "data" / "rust",
+            "src_paths": [
                 TEST_DIR / "data" / "rust" / "demo.rs",
             ],
-            ONELINE_COMMENT_STYLE_DEFAULT,
-            {
+            "comment_type": "rust",
+            "oneline_comment_style": ONELINE_COMMENT_STYLE_DEFAULT,
+            "result": {
                 "num_src_files": 1,
                 "num_uncached_files": 1,
                 "num_cached_files": 0,
                 "num_comments": 6,
                 "num_oneline_warnings": 0,
             },
-        ),
-        (
-            TEST_DIR / "data" / "jsonc",
-            [
+        },
+        {
+            "src_dir": TEST_DIR / "data" / "typescript",
+            "src_paths": [
+                TEST_DIR / "data" / "typescript" / "demo.ts",
+            ],
+            "comment_type": "ts",
+            "oneline_comment_style": ONELINE_COMMENT_STYLE_DEFAULT,
+            "result": {
+                "num_src_files": 1,
+                "num_uncached_files": 1,
+                "num_cached_files": 0,
+                "num_comments": 4,
+                "num_oneline_warnings": 0,
+            },
+        },
+        {
+            "src_dir": TEST_DIR / "data" / "jsonc",
+            "src_paths": [
                 TEST_DIR / "data" / "jsonc" / "demo.jsonc",
             ],
-            ONELINE_COMMENT_STYLE_DEFAULT,
-            {
+            "comment_type": CommentType.jsonc,
+            "oneline_comment_style": ONELINE_COMMENT_STYLE_DEFAULT,
+            "result": {
                 "num_src_files": 1,
                 "num_uncached_files": 1,
                 "num_cached_files": 0,
                 "num_comments": 4,
                 "num_oneline_warnings": 0,
-                "comment_type": CommentType.jsonc,
             },
-        ),
+        },
     ],
 )
-def test_analyse_oneline_needs(
-    tmp_path, src_dir, src_paths, oneline_comment_style, result
-):
+def test_analyse_oneline_needs(tmp_path, case):
     src_analyse_config = SourceAnalyseConfig(
-        src_files=src_paths,
-        src_dir=src_dir,
+        src_files=case["src_paths"],
+        src_dir=case["src_dir"],
         get_need_id_refs=False,
         get_oneline_needs=True,
         get_rst=False,
-        oneline_comment_style=oneline_comment_style,
-        comment_type=result.get("comment_type", CommentType.cpp),
+        oneline_comment_style=case["oneline_comment_style"],
+        comment_type=case["comment_type"],
     )
     src_analyse = SourceAnalyse(src_analyse_config)
     src_analyse.run()
 
+    result = case["result"]
     assert len(src_analyse.src_files) == result["num_src_files"]
     assert len(src_analyse.oneline_warnings) == result["num_oneline_warnings"]