Merge pull request #2265 from strictdoc-project/stanislaw/merge_nodes

Code climate: add custom fixit linting check: StrictDoc_CheckDocstringsRule

Author: stanislaw

developer/fixit/check_docstrings.py

@@ -0,0 +1,106 @@
+from typing import Optional
+
+from fixit import LintRule
+from libcst import SimpleString, Expr
+from libcst.metadata import ParentNodeProvider, PositionProvider
+
+RESERVED_STRINGS = ["@relation", "FIXME"]
+
+
+def find_first_significant_char_index(text: str) -> Optional[int]:
+    for i, char in enumerate(text):
+        if char not in {'"', " ", "\t", "#", "\n"}:
+            return i
+    return None
+
+
+def should_check_string(string: str) -> bool:
+    return not any(rs in string for rs in RESERVED_STRINGS)
+
+
+def find_last_significant_char_index(text: str) -> Optional[int]:
+    for i in range(len(text) - 1, -1, -1):
+        if text[i] not in {'"', " ", "\t", "#", "\n"}:
+            return i
+    return None
+
+
+class StrictDoc_CheckDocStringsRule(LintRule):
+    METADATA_DEPENDENCIES = (
+        ParentNodeProvider,
+        PositionProvider,
+    )
+
+    def visit_SimpleString(self, node: "SimpleString") -> Optional[bool]:
+        parent = self.get_metadata(ParentNodeProvider, node)
+
+        if isinstance(parent, Expr):
+            node_strings = node.value.splitlines(keepends=False)
+            if len(node_strings) == 0:
+                return True
+
+            assert node_strings[0].startswith('"""')
+
+            position = self.get_metadata(PositionProvider, node)
+            column = position.start.column
+
+            if node_strings[0] != '"""':
+                node_strings[0] = " " * column + node_strings[0][3:]
+                node_strings.insert(0, '"""')
+
+            if node_strings[-1].strip(" ") != '"""':
+                node_strings[-1] = node_strings[-1][:-3]
+                node_strings.append(" " * column + '"""')
+
+            if (
+                node_strings[2].strip() not in ('"""', "")
+                and "FIXME" not in node_strings[1]
+            ):
+                self.report(
+                    node,
+                    "The first line of a docstring must be separated "
+                    "with an empty line from the rest of the docstring comment.",
+                )
+                return True
+
+            if (should_check_string(node_strings[1])) and not node_strings[
+                1
+            ].endswith("."):
+                node_strings[1] += "."
+
+            first_index = find_first_significant_char_index(node_strings[0])
+            if first_index is not None:
+                if node.value[first_index].islower():
+                    node_strings[0] = (
+                        node_strings[0][:first_index]
+                        + node_strings[0][first_index].upper()
+                        + node_strings[0][first_index + 1 :]
+                    )
+
+            if len(node_strings) > 3 and should_check_string(node_strings[-2]):
+                last_index = find_last_significant_char_index(node_strings[-2])
+                if last_index is not None:
+                    if node_strings[-2].rstrip()[last_index] != ".":
+                        node_strings[-2] = (
+                            node_strings[-2][:last_index]
+                            + node_strings[-2][last_index]
+                            + "."
+                            + node_strings[-2][last_index + 1 :]
+                        )
+
+            patched_value = "\n".join(node_strings)
+
+            if patched_value != node.value:
+                self.report(
+                    node,
+                    (
+                        "The docstring comment's first sentence must start with "
+                        "a capital letter and end with a dot. Additionally, "
+                        "and extended comment that follows the first line must "
+                        "be separated from the first sentence with an empty line. "
+                        "The last sentence must end with a dot."
+                    ),
+                    replacement=SimpleString(patched_value),
+                )
+
+        return True

pyproject.toml

@@ -122,3 +122,13 @@ addopts = "--import-mode=importlib"
 pythonpath = [
   "."
 ]
+
+[tool.fixit]
+enable = [
+    ".developer.fixit.check_docstrings",
+]
+
+# FIXME: Remove disable.
+disable = [
+    "fixit.rules"
+]

requirements.check.txt

@@ -3,6 +3,7 @@ toml
 # Lint
 mypy>=0.910
 ruff>=0.9
+fixit
 
 # Unit tests
 pytest>=6.2.2

strictdoc/backend/excel/import_/excel_sheet_proxy.py

@@ -14,7 +14,9 @@ class ExcelLibType(Enum):
 
 @auto_described
 class ExcelSheetProxy:
-    """This proxy class allows to open either xls(xlrd) or xlsx(openpyxl) with the same interface"""
+    """
+    This proxy class allows to open either xls(xlrd) or xlsx(openpyxl) with the same interface.
+    """
 
     def __init__(self, file: str):
         self.file = file
@@ -35,7 +37,9 @@ def __init__(self, file: str):
 
     @property
     def name(self) -> str:
-        """Returns the name of the first sheet"""
+        """
+        Returns the name of the first sheet.
+        """
         if self.lib == ExcelLibType.OPENPYXL:
             return str(self.sheet.title)
         elif self.lib == ExcelLibType.XLRD:
@@ -44,7 +48,9 @@ def name(self) -> str:
 
     @property
     def ncols(self) -> int:
-        """The number of columns"""
+        """
+        The number of columns.
+        """
         ncols: int = 0
         if self.lib == ExcelLibType.OPENPYXL:
             ncols = self.sheet.max_column
@@ -54,7 +60,9 @@ def ncols(self) -> int:
 
     @property
     def nrows(self) -> int:
-        """The number of rows"""
+        """
+        The number of rows.
+        """
         nrows: int = 0
         if self.lib == ExcelLibType.OPENPYXL:
             nrows = self.sheet.max_row
@@ -63,7 +71,9 @@ def nrows(self) -> int:
         return nrows
 
     def get_cell_value(self, row: int, col: int) -> str:
-        """Returns the value at row/col as string"""
+        """
+        Returns the value at row/col as string.
+        """
         cell_value: str = ""
         if self.lib == ExcelLibType.OPENPYXL:
             cell_value = (
@@ -74,7 +84,9 @@ def get_cell_value(self, row: int, col: int) -> str:
         return cell_value
 
     def row_values(self, row: int) -> List[str]:
-        """Returns a full row as list"""
+        """
+        Returns a full row as list.
+        """
         row_values: List[str] = []
         if self.lib == ExcelLibType.OPENPYXL:
             row_values = [(cell.value or "") for cell in self.sheet[row + 1]]

strictdoc/backend/sdoc_source_code/reader_c.py

@@ -389,7 +389,9 @@ def _get_function_name_node(function_declarator_node: Node):
 
     @staticmethod
     def get_node_ns(node: Node) -> Sequence[str]:
-        """Walk up the tree and find parent classes"""
+        """
+        Walk up the tree and find parent classes.
+        """
         parent_scopes = []
         cursor: Optional[Node] = node
         while cursor is not None:

strictdoc/backend/sdoc_source_code/reader_python.py

@@ -280,7 +280,9 @@ def read_from_file(self, file_path: str) -> SourceFileTraceabilityInfo:
 
     @staticmethod
     def get_node_ns(node: Node) -> Sequence[str]:
-        """Walk up the tree and find parent classes"""
+        """
+        Walk up the tree and find parent classes.
+        """
         parent_scopes = []
         cursor: Optional[Node] = node
         while cursor:

strictdoc/backend/sdoc_source_code/reader_robot.py

@@ -59,19 +59,27 @@ def __init__(
         self.parse_context = parse_context
 
     def visit_Comment(self, node: Comment) -> None:
-        """Create non-function Marker from Comment outside TestCases."""
+        """
+        Create non-function Marker from Comment outside TestCases.
+        """
         self._visit_possibly_marked_node(node)
 
     def visit_Documentation(self, node: Documentation) -> None:
-        """Create non-function Marker from Documentation outside TestCases."""
+        """
+        Create non-function Marker from Documentation outside TestCases.
+        """
         self._visit_possibly_marked_node(node)
 
     def visit_Tags(self, node: Tags) -> None:
-        """Create non-function Marker from Tags outside TestCases."""
+        """
+        Create non-function Marker from Tags outside TestCases.
+        """
         self._visit_possibly_marked_node(node)
 
     def visit_TestCase(self, node: TestCase) -> None:
-        """Create function and non-function Marker from TestCases."""
+        """
+        Create function and non-function Marker from TestCases.
+        """
         trailing_empty_lines = 0
         tc_markers = []
         for stmt in node.body:

strictdoc/backend/sdoc_source_code/test_reports/robot_xml_reader.py

@@ -22,7 +22,9 @@ def __init__(self, project_config: ProjectConfig):
         self.document: Optional[SDocDocument] = None
 
     def visit_suite(self, suite: robot.result.TestSuite) -> None:
-        """Create document for top level suite and sections for nested suites."""
+        """
+        Create document for top level suite and sections for nested suites.
+        """
         assert suite.full_name not in self.suites
 
         if suite.parent is None:
@@ -67,7 +69,9 @@ def visit_suite(self, suite: robot.result.TestSuite) -> None:
         super().visit_suite(suite)
 
     def visit_test(self, test: robot.result.TestCase) -> None:
-        """Create TEST_RESULT node for each test case."""
+        """
+        Create TEST_RESULT node for each test case.
+        """
         assert self.document
         assert test.parent and test.parent.full_name in self.suites, (
             "depth-first traversal expected"

strictdoc/git/project_diff_analyzer.py

@@ -229,7 +229,7 @@ def get_changes_requirements_changed(self) -> Optional[int]:
 
     def get_changes_sections_stats_string(self) -> str:
         """
-        Example: 2 removed, 1 modified, 2 added
+        Example: 2 removed, 1 modified, 2 added.
         """
         change_components = []
         removed = self._change_counters.get(ChangeType.SECTION_REMOVED)
@@ -246,7 +246,7 @@ def get_changes_sections_stats_string(self) -> str:
 
     def get_changes_requirements_stats_string(self) -> str:
         """
-        Example: 2 removed, 1 modified, 2 added
+        Example: 2 removed, 1 modified, 2 added.
         """
         change_components = []
         removed = self._change_counters.get(ChangeType.REQUIREMENT_REMOVED)

tasks.py

@@ -66,6 +66,7 @@ def run_invoke_with_tox(
     environment_type: ToxEnvironment,
     command: str,
     environment: Optional[Dict] = None,
+    pty: bool = False,
 ) -> invoke.runners.Result:
     assert isinstance(environment_type, ToxEnvironment)
     assert isinstance(command, str)
@@ -80,6 +81,7 @@ def run_invoke_with_tox(
                 {command}
         """,
         environment=environment,
+        pty=pty,
     )
 
 
@@ -592,6 +594,27 @@ def lint_mypy(context):
 # # @sdoc[/SDOC-SRS-43]
 
 
+@task(aliases=["lf"])
+def lint_fixit(context, fix=False):
+    if fix:
+        run_invoke_with_tox(
+            context,
+            ToxEnvironment.CHECK,
+            """
+                fixit fix strictdoc/
+            """,
+            pty=True,
+        )
+    else:
+        run_invoke_with_tox(
+            context,
+            ToxEnvironment.CHECK,
+            """
+                fixit lint --diff strictdoc/
+            """,
+        )
+
+
 @task(aliases=["l"])
 def lint(context):
     lint_ruff_format(context)