strictdoc 0.3.0__tar.gz → 0.4.0__tar.gz

{strictdoc-0.3.0 → strictdoc-0.4.0}/.gitignore

@@ -43,8 +43,6 @@ latest_logs/
 # Files downloaded during tests are stored here.
 downloaded_files/
 
-### StrictDoc's documentation ###
-strictdoc-project.github.io/
 
 ### StrictDoc's developer test ###
 __*.sdoc

{strictdoc-0.3.0 → strictdoc-0.4.0}/PKG-INFO

@@ -1,12 +1,14 @@
-Metadata-Version: 2.3
+Metadata-Version: 2.4
 Name: strictdoc
-Version: 0.3.0
+Version: 0.4.0
 Summary: StrictDoc is open-source software for technical documentation and requirements management.
 Project-URL: Changelog, https://github.com/strictdoc-project/strictdoc/blob/main/CHANGELOG.md
 Project-URL: Homepage, https://strictdoc.readthedocs.io/en/stable/
 Project-URL: Source, https://github.com/strictdoc-project/strictdoc
 Author-email: Stanislav Pankevich <s.pankevich@gmail.com>, Maryna Balioura <mettta@gmail.com>
-License: Apache-2.0
+License-Expression: Apache-2.0
+License-File: LICENSE
+License-File: NOTICE
 Classifier: License :: OSI Approved :: BSD License
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
@@ -32,7 +34,7 @@ Requires-Dist: spdx-tools
 Requires-Dist: textx==3.*,>=3.0.0
 Requires-Dist: toml
 Requires-Dist: tree-sitter
-Requires-Dist: tree-sitter-c
+Requires-Dist: tree-sitter-cpp
 Requires-Dist: tree-sitter-python
 Requires-Dist: uvicorn[standard]>=0.14.0
 Requires-Dist: webdriver-manager

{strictdoc-0.3.0 → strictdoc-0.4.0}/pyproject.toml

@@ -58,7 +58,7 @@ dependencies = [
 
     # Tree Sitter is used for language/AST-aware parsing of Python, C and other files.
     "tree-sitter",
-    "tree-sitter-c",
+    "tree_sitter_cpp",
     "tree-sitter-python",
 
     # Requirements-to-source traceability. Colored syntax for source files.

{strictdoc-0.3.0 → strictdoc-0.4.0}/strictdoc/__init__.py

@@ -1,6 +1,6 @@
 from strictdoc.core.environment import SDocRuntimeEnvironment
 
-__version__ = "0.3.0"
+__version__ = "0.4.0"
 
 
 environment = SDocRuntimeEnvironment(__file__)

{strictdoc-0.3.0 → strictdoc-0.4.0}/strictdoc/backend/sdoc/grammar/grammar.py

@@ -70,6 +70,7 @@ SDocDocument[noskipws]:
 DocumentConfig[noskipws]:
   ('UID: ' uid = /{REGEX_UID}/ '\n')?
   ('VERSION: ' version = SingleLineString '\n')?
+  ('DATE: ' date = SingleLineString '\n')?
   ('CLASSIFICATION: ' classification = SingleLineString '\n')?
   ('REQ_PREFIX: ' requirement_prefix = SingleLineString '\n')?
   ('ROOT: ' (root = BooleanChoice) '\n')?

{strictdoc-0.3.0 → strictdoc-0.4.0}/strictdoc/backend/sdoc/models/document_config.py

@@ -11,6 +11,7 @@ class DocumentConfig:
         return DocumentConfig(
             parent=document,
             version=None,
+            date=None,
             uid=None,
             classification=None,
             requirement_prefix=None,
@@ -29,6 +30,7 @@ class DocumentConfig:
         *,
         parent,
         version: Optional[str],
+        date: Optional[str],
         uid: Optional[str],
         classification: Optional[str],
         requirement_prefix: Optional[str],
@@ -43,6 +45,7 @@ class DocumentConfig:
     ) -> None:
         self.parent = parent
         self.version: Optional[str] = version
+        self.date: Optional[str] = date
 
         meaningful_uid: Optional[str] = None
         if uid is not None and len(uid) > 0:

{strictdoc-0.3.0 → strictdoc-0.4.0}/strictdoc/backend/sdoc_source_code/caching_reader.py

@@ -1,4 +1,4 @@
-from typing import Union
+from typing import Optional, Union
 
 from strictdoc.backend.sdoc.pickle_cache import PickleCache
 from strictdoc.backend.sdoc_source_code.models.source_file_info import (
@@ -20,7 +20,7 @@ class SourceFileTraceabilityCachingReader:
     @staticmethod
     def read_from_file(
         path_to_file: str, project_config: ProjectConfig
-    ) -> SourceFileTraceabilityInfo:
+    ) -> Optional[SourceFileTraceabilityInfo]:
         unpickled_content = PickleCache.read_from_cache(
             path_to_file, project_config, "source_file"
         )
@@ -34,12 +34,21 @@ class SourceFileTraceabilityCachingReader:
         reader = SourceFileTraceabilityCachingReader._get_reader(
             path_to_file, project_config
         )
-        traceability_info: SourceFileTraceabilityInfo = reader.read_from_file(
-            path_to_file
-        )
-        PickleCache.save_to_cache(
-            traceability_info, path_to_file, project_config, "source_file"
-        )
+        try:
+            if (
+                traceability_info := reader.read_from_file(path_to_file)
+            ) is not None:
+                PickleCache.save_to_cache(
+                    traceability_info,
+                    path_to_file,
+                    project_config,
+                    "source_file",
+                )
+        except UnicodeDecodeError:
+            print(  # noqa: T201
+                f"warning: Skip tracing binary file {path_to_file}."
+            )
+            return None
 
         return traceability_info
 
@@ -54,6 +63,13 @@ class SourceFileTraceabilityCachingReader:
         if project_config.is_activated_source_file_language_parsers():
             if path_to_file.endswith(".py"):
                 return SourceFileTraceabilityReader_Python()
-            if path_to_file.endswith(".c") or path_to_file.endswith(".h"):
+            if (
+                path_to_file.endswith(".c")
+                or path_to_file.endswith(".cc")
+                or path_to_file.endswith(".h")
+                or path_to_file.endswith(".hh")
+                or path_to_file.endswith(".hpp")
+                or path_to_file.endswith(".cpp")
+            ):
                 return SourceFileTraceabilityReader_C()
         return SourceFileTraceabilityReader()

{strictdoc-0.3.0 → strictdoc-0.4.0}/strictdoc/backend/sdoc_source_code/marker_parser.py

@@ -11,8 +11,10 @@ from strictdoc.backend.sdoc_source_code.models.range_marker import (
 from strictdoc.backend.sdoc_source_code.models.requirement_marker import Req
 
 REGEX_REQ = r"[A-Za-z][A-Za-z0-9\\-]+"
-# @relation(REQ-1, scope=function)
-REGEX_MARKER = rf"@relation\(({REGEX_REQ}(?:, {REGEX_REQ})*)\, scope=(file|class|function|line|range_start|range_end)\)"
+# @relation(REQ-1, scope=function) or @relation{REQ-1, scope=function}
+REGEX_MARKER = re.compile(
+    rf"@relation[({{]({REGEX_REQ}(?:, {REGEX_REQ})*), scope=(file|class|function|line|range_start|range_end)[)}}]"
+)
 
 
 class MarkerParser:
@@ -29,7 +31,7 @@ class MarkerParser:
         for input_line_idx_, input_line_ in enumerate(
             input_string.splitlines()
         ):
-            match = re.search(REGEX_MARKER, input_line_)
+            match = REGEX_MARKER.search(input_line_)
             if match is None:
                 continue
 

{strictdoc-0.3.0 → strictdoc-0.4.0}/strictdoc/backend/sdoc_source_code/models/function.py

@@ -13,6 +13,7 @@ class Function:
         self,
         parent: Any,
         name: str,
+        display_name: str,
         line_begin: int,
         line_end: int,
         child_functions: List[Any],
@@ -22,6 +23,8 @@ class Function:
         assert parent is not None
         self.parent = parent
         self.name = name
+        self.display_name = display_name
+
         # Child functions are supported in programming languages that can nest
         # functions, for example, Python.
         self.child_functions: List[Function] = child_functions

{strictdoc-0.3.0 → strictdoc-0.4.0}/strictdoc/backend/sdoc_source_code/models/source_file_info.py

@@ -1,5 +1,5 @@
 # mypy: disable-error-code="no-untyped-def,type-arg,var-annotated"
-from typing import Dict, List, Union
+from typing import Dict, List, Optional, Union
 
 from strictdoc.backend.sdoc_source_code.models.function import Function
 from strictdoc.backend.sdoc_source_code.models.function_range_marker import (
@@ -10,6 +10,7 @@ from strictdoc.backend.sdoc_source_code.models.range_marker import (
     LineMarker,
     RangeMarker,
 )
+from strictdoc.core.source_tree import SourceFile
 from strictdoc.helpers.auto_described import auto_described
 
 
@@ -24,6 +25,7 @@ class SourceFileTraceabilityInfo:
         """
 
         self.g_parts: List = g_parts
+        self.source_file: Optional[SourceFile] = None
         self.functions: List[Function] = []
 
         """

{strictdoc-0.3.0 → strictdoc-0.4.0}/strictdoc/backend/sdoc_source_code/reader.py

@@ -305,12 +305,14 @@ class SourceFileTraceabilityReader:
         drop_textx_meta(source_file_traceability_info)
         return source_file_traceability_info
 
-    def read_from_file(self, file_path) -> SourceFileTraceabilityInfo:
+    def read_from_file(self, file_path: str) -> SourceFileTraceabilityInfo:
         try:
             with open(file_path, encoding="utf-8") as file:
                 sdoc_content = file.read()
                 sdoc = self.read(sdoc_content, file_path=file_path)
                 return sdoc
+        except UnicodeDecodeError:
+            raise
         except NotImplementedError:
             traceback.print_exc()
             sys.exit(1)

{strictdoc-0.3.0 → strictdoc-0.4.0}/strictdoc/backend/sdoc_source_code/reader_c.py

@@ -1,9 +1,9 @@
 # mypy: disable-error-code="no-redef,no-untyped-call,no-untyped-def,type-arg,var-annotated"
 import sys
 import traceback
-from typing import List, Optional, Union
+from typing import List, Optional, Sequence, Union
 
-import tree_sitter_c
+import tree_sitter_cpp
 from tree_sitter import Language, Node, Parser
 
 from strictdoc.backend.sdoc.error_handling import StrictDocSemanticError
@@ -12,6 +12,7 @@ from strictdoc.backend.sdoc_source_code.marker_parser import MarkerParser
 from strictdoc.backend.sdoc_source_code.models.function import Function
 from strictdoc.backend.sdoc_source_code.models.function_range_marker import (
     FunctionRangeMarker,
+    RangeMarkerType,
 )
 from strictdoc.backend.sdoc_source_code.models.range_marker import (
     LineMarker,
@@ -52,7 +53,7 @@ class SourceFileTraceabilityReader_C:
         parse_context = ParseContext(file_path, length)
 
         # Works since Python 3.9 but we also lint this with mypy from Python 3.8.
-        language_arg = tree_sitter_c.language()
+        language_arg = tree_sitter_cpp.language()
         py_language = Language(  # type: ignore[call-arg, unused-ignore]
             language_arg
         )
@@ -82,6 +83,12 @@ class SourceFileTraceabilityReader_C:
                             node_.start_point[1] + 1,
                         )
                         for marker_ in markers:
+                            if not isinstance(marker_, FunctionRangeMarker):
+                                continue
+                            # At the top level, only accept the scope=file markers.
+                            # Everything else will be handled by functions and classes.
+                            if marker_.scope != RangeMarkerType.FILE:
+                                continue
                             if isinstance(marker_, FunctionRangeMarker) and (
                                 function_range_marker_ := marker_
                             ):
@@ -91,15 +98,34 @@ class SourceFileTraceabilityReader_C:
                                 traceability_info.markers.append(
                                     function_range_marker_
                                 )
-            elif node_.type == "declaration":
+
+            elif node_.type in ("declaration", "field_declaration"):
                 function_declarator_node = ts_find_child_node_by_type(
                     node_, "function_declarator"
                 )
+
+                # C++ reference declaration wrap the function declaration one time.
                 if function_declarator_node is None:
-                    continue
+                    # Example: TrkVertex& operator-=(const TrkVertex& c);
+                    reference_declarator_node = ts_find_child_node_by_type(
+                        node_, "reference_declarator"
+                    )
+                    if reference_declarator_node is None:
+                        continue
 
-                function_identifier_node = ts_find_child_node_by_type(
-                    function_declarator_node, "identifier"
+                    function_declarator_node = ts_find_child_node_by_type(
+                        reference_declarator_node, "function_declarator"
+                    )
+                    if function_declarator_node is None:
+                        continue
+
+                # For normal C functions the identifier is "identifier".
+                # For C++, there are:
+                # Class function declarations: bool CanSend(const CanFrame &frame);         # noqa: ERA001
+                # Operators:                   TrkVertex& operator-=(const TrkVertex& c);   # noqa: ERA001
+                # Destructors:                 ~TrkVertex();                                # noqa: ERA001
+                function_identifier_node = self._get_function_name_node(
+                    function_declarator_node,
                 )
                 if function_identifier_node is None:
                     continue
@@ -107,10 +133,25 @@ class SourceFileTraceabilityReader_C:
                 if function_identifier_node.text is None:
                     continue
 
-                function_name: str = function_identifier_node.text.decode(
+                assert function_identifier_node.text is not None, node_.text
+                function_display_name = function_identifier_node.text.decode(
                     "utf8"
                 )
-                assert function_name is not None, function_name
+
+                assert function_declarator_node.text is not None, node_.text
+                function_name: str = function_declarator_node.text.decode(
+                    "utf8"
+                )
+                assert function_name is not None, node_.text
+
+                parent_names = self.get_node_ns(node_)
+                if len(parent_names) > 0:
+                    function_name = (
+                        f"{'::'.join(parent_names)}::{function_name}"
+                    )
+                    function_display_name = (
+                        f"{'::'.join(parent_names)}::{function_display_name}"
+                    )
 
                 function_attributes = {FunctionAttribute.DECLARATION}
                 for specifier_node_ in ts_find_child_nodes_by_type(
@@ -121,13 +162,12 @@ class SourceFileTraceabilityReader_C:
 
                 function_markers: List[FunctionRangeMarker] = []
                 function_comment_node: Optional[Node] = None
-                function_comment_text = None
                 if (
                     node_.prev_sibling is not None
                     and node_.prev_sibling.type == "comment"
                 ):
                     function_comment_node = node_.prev_sibling
-                    assert function_comment_node.text is not None
+                    assert function_comment_node.text is not None, node_.text
                     function_comment_text = function_comment_node.text.decode(
                         "utf8"
                     )
@@ -140,7 +180,7 @@ class SourceFileTraceabilityReader_C:
                         function_last_line,
                         function_comment_node.start_point[0] + 1,
                         function_comment_node.start_point[1] + 1,
-                        entity_name=function_name,
+                        entity_name=function_display_name,
                     )
                     for marker_ in markers:
                         if isinstance(marker_, FunctionRangeMarker) and (
@@ -158,6 +198,7 @@ class SourceFileTraceabilityReader_C:
                 new_function = Function(
                     parent=traceability_info,
                     name=function_name,
+                    display_name=function_display_name,
                     line_begin=function_comment_node.start_point[0] + 1
                     if function_comment_node is not None
                     else node_.range.start_point[0] + 1,
@@ -171,13 +212,47 @@ class SourceFileTraceabilityReader_C:
             elif node_.type == "function_definition":
                 function_name: str = ""
 
-                for child_ in node_.children:
-                    if child_.type == "function_declarator":
-                        assert child_.children[0].type == "identifier"
-                        assert child_.children[0].text
+                function_declarator_node = ts_find_child_node_by_type(
+                    node_, "function_declarator"
+                )
+                # C++ reference declaration wrap the function declaration one time.
+                if function_declarator_node is None:
+                    # Example: Foo& Foo::operator+(const Foo& c) { return *this; }
+                    reference_declarator_node = ts_find_child_node_by_type(
+                        node_, "reference_declarator"
+                    )
+                    if reference_declarator_node is None:
+                        continue
+
+                    function_declarator_node = ts_find_child_node_by_type(
+                        reference_declarator_node, "function_declarator"
+                    )
+                    if function_declarator_node is None:
+                        continue
+
+                assert function_declarator_node is not None, node_.text
+
+                assert function_declarator_node.text is not None, node_.text
+                function_name = function_declarator_node.text.decode("utf8")
 
-                        function_name = child_.children[0].text.decode("utf8")
-                assert function_name is not None, "Function name"
+                identifier_node = self._get_function_name_node(
+                    function_declarator_node
+                )
+                if identifier_node is None:
+                    raise NotImplementedError(function_declarator_node)
+
+                assert identifier_node.text is not None, node_.text
+                function_display_name = identifier_node.text.decode("utf8")
+
+                assert function_name is not None, node_.text
+                parent_names = self.get_node_ns(node_)
+                if len(parent_names) > 0:
+                    function_name = (
+                        f"{'::'.join(parent_names)}::{function_name}"
+                    )
+                    function_display_name = (
+                        f"{'::'.join(parent_names)}::{function_display_name}"
+                    )
 
                 function_markers: List[FunctionRangeMarker] = []
                 function_comment_node: Optional[Node] = None
@@ -187,7 +262,7 @@ class SourceFileTraceabilityReader_C:
                     and node_.prev_sibling.type == "comment"
                 ):
                     function_comment_node = node_.prev_sibling
-                    assert function_comment_node.text is not None
+                    assert function_comment_node.text is not None, node_.text
                     function_comment_text = function_comment_node.text.decode(
                         "utf8"
                     )
@@ -200,7 +275,7 @@ class SourceFileTraceabilityReader_C:
                         function_last_line,
                         function_comment_node.start_point[0] + 1,
                         function_comment_node.start_point[1] + 1,
-                        entity_name=function_name,
+                        entity_name=function_display_name,
                     )
                     for marker_ in markers:
                         if isinstance(marker_, FunctionRangeMarker) and (
@@ -218,6 +293,7 @@ class SourceFileTraceabilityReader_C:
                 new_function = Function(
                     parent=traceability_info,
                     name=function_name,
+                    display_name=function_display_name,
                     line_begin=function_comment_node.start_point[0] + 1
                     if function_comment_node is not None
                     else node_.range.start_point[0] + 1,
@@ -273,12 +349,14 @@ class SourceFileTraceabilityReader_C:
 
         return traceability_info
 
-    def read_from_file(self, file_path):
+    def read_from_file(self, file_path: str) -> SourceFileTraceabilityInfo:
         try:
             with open(file_path, "rb") as file:
                 sdoc_content = file.read()
                 sdoc = self.read(sdoc_content, file_path=file_path)
                 return sdoc
+        except UnicodeDecodeError:
+            raise
         except NotImplementedError:
             traceback.print_exc()
             sys.exit(1)
@@ -287,9 +365,43 @@ class SourceFileTraceabilityReader_C:
             sys.exit(1)
         except Exception as exc:  # pylint: disable=broad-except
             print(  # noqa: T201
-                f"error: SourceFileTraceabilityReader_Python: could not parse file: "
+                f"error: SourceFileTraceabilityReader_C: could not parse file: "
                 f"{file_path}.\n{exc.__class__.__name__}: {exc}"
             )
-            # TODO: when --debug is provided
-            # traceback.print_exc()  # noqa: ERA001
+            traceback.print_exc()
             sys.exit(1)
+
+    @staticmethod
+    def _get_function_name_node(function_declarator_node: Node):
+        assert function_declarator_node.type == "function_declarator"
+        function_identifier_node = ts_find_child_node_by_type(
+            function_declarator_node,
+            node_type=(
+                "identifier",
+                "field_identifier",
+                "operator_name",
+                "destructor_name",
+                "qualified_identifier",
+            ),
+        )
+        return function_identifier_node
+
+    @staticmethod
+    def get_node_ns(node: Node) -> Sequence[str]:
+        """Walk up the tree and find parent classes"""
+        parent_scopes = []
+        cursor: Optional[Node] = node
+        while cursor is not None:
+            if cursor.type == "class_specifier" and len(cursor.children) > 1:
+                second_node_or_none = cursor.children[1]
+                if (
+                    second_node_or_none.type == "type_identifier"
+                    and second_node_or_none.text is not None
+                ):
+                    parent_class_name = second_node_or_none.text.decode("utf8")
+                    parent_scopes.append(parent_class_name)
+
+            cursor = cursor.parent
+
+        parent_scopes.reverse()
+        return parent_scopes

{strictdoc-0.3.0 → strictdoc-0.4.0}/strictdoc/backend/sdoc_source_code/reader_python.py

@@ -64,6 +64,7 @@ class SourceFileTraceabilityReader_Python:
                 function = Function(
                     parent=traceability_info,
                     name="module",
+                    display_name="module",
                     line_begin=node_.start_point[0] + 1,
                     line_end=node_.end_point[0] + 1,
                     child_functions=[],
@@ -187,6 +188,7 @@ class SourceFileTraceabilityReader_Python:
                 new_function = Function(
                     parent=traceability_info,
                     name=function_name,
+                    display_name=function_name,
                     line_begin=node_.range.start_point[0] + 1,
                     line_end=node_.range.end_point[0] + 1,
                     child_functions=[],
@@ -242,12 +244,14 @@ class SourceFileTraceabilityReader_Python:
 
         return traceability_info
 
-    def read_from_file(self, file_path):
+    def read_from_file(self, file_path: str) -> SourceFileTraceabilityInfo:
         try:
             with open(file_path, "rb") as file:
                 sdoc_content = file.read()
                 sdoc = self.read(sdoc_content, file_path=file_path)
                 return sdoc
+        except UnicodeDecodeError:
+            raise
         except NotImplementedError:
             traceback.print_exc()
             sys.exit(1)

{strictdoc-0.3.0 → strictdoc-0.4.0}/strictdoc/backend/sdoc_source_code/tree_sitter_helpers.py

@@ -1,4 +1,4 @@
-from typing import Generator, Optional
+from typing import Generator, Optional, Tuple, Union
 
 from tree_sitter import Node, Tree
 
@@ -18,9 +18,14 @@ def traverse_tree(tree: Tree) -> Generator[Node, None, None]:
             break
 
 
-def ts_find_child_node_by_type(node: Node, node_type: str) -> Optional[Node]:
+def ts_find_child_node_by_type(
+    node: Node, node_type: Union[str, Tuple[str, ...], str]
+) -> Optional[Node]:
+    node_types: Tuple[str, ...] = (
+        node_type if isinstance(node_type, tuple) else (node_type,)
+    )
     for child_ in node.children:
-        if child_.type == node_type:
+        if child_.type in node_types:
             return child_
     return None
 

{strictdoc-0.3.0 → strictdoc-0.4.0}/strictdoc/cli/command_parser_builder.py

@@ -16,6 +16,7 @@ EXPORT_FORMATS = [
     "reqif-sdoc",
     "reqifz-sdoc",
     "sdoc",
+    "doxygen",
     "spdx",
 ]
 EXCEL_PARSERS = ["basic"]

{strictdoc-0.3.0 → strictdoc-0.4.0}/strictdoc/core/actions/export_action.py

@@ -12,6 +12,7 @@ from strictdoc.backend.sdoc.writer import SDWriter
 from strictdoc.core.project_config import ProjectConfig
 from strictdoc.core.traceability_index import TraceabilityIndex
 from strictdoc.core.traceability_index_builder import TraceabilityIndexBuilder
+from strictdoc.export.doxygen.doxygen_generator import DoxygenGenerator
 from strictdoc.export.html.document_type import DocumentType
 from strictdoc.export.html.html_generator import HTMLGenerator
 from strictdoc.export.html.html_templates import HTMLTemplates
@@ -153,6 +154,18 @@ class ExportAction:
         if "sdoc" in self.project_config.export_formats:
             self.export_sdoc()
 
+        if "doxygen" in self.project_config.export_formats:
+            output_doxygen_root = os.path.join(
+                self.project_config.output_dir, "doxygen"
+            )
+            doxygen_generator = DoxygenGenerator(
+                project_config=self.project_config
+            )
+            doxygen_generator.export(
+                traceability_index=self.traceability_index,
+                path_to_output_dir=output_doxygen_root,
+            )
+
         if "spdx" in self.project_config.export_formats:
             output_dot_root = os.path.join(
                 self.project_config.output_dir, "spdx"

{strictdoc-0.3.0 → strictdoc-0.4.0}/strictdoc/core/document_tree.py

@@ -3,6 +3,7 @@ from typing import Dict, List, Optional
 
 from strictdoc.backend.sdoc.models.document import SDocDocument
 from strictdoc.backend.sdoc.models.document_grammar import DocumentGrammar
+from strictdoc.core.source_tree import SourceTree
 
 
 class DocumentTree:
@@ -28,7 +29,7 @@ class DocumentTree:
             map_grammars_by_filenames
         )
 
-        self.source_tree = None  # attached later.
+        self.source_tree: Optional[SourceTree] = None  # attached later.
 
     def __repr__(self):
         return (
@@ -53,5 +54,5 @@ class DocumentTree:
     ) -> Optional[DocumentGrammar]:
         return self.map_grammars_by_filenames.get(filename)
 
-    def attach_source_tree(self, source_tree):
+    def attach_source_tree(self, source_tree: SourceTree):
         self.source_tree = source_tree