Implement Polyspace checker

.gitignore

@@ -86,6 +86,7 @@ bin/
 include/
 local/
 pip-selfcheck.json
+pyvenv.cfg
 
 # Spyder project settings
 .spyderproject
@@ -98,3 +99,6 @@ pip-selfcheck.json
 
 # Offline version file
 src/mlx/warnings/__version__.py
+
+# plantuml generation
+src/*.plantuml

README.rst

@@ -286,6 +286,68 @@ input file. When this setting is missing, the default value ``true`` is used.
 .. |--xunit report.xml| replace:: ``--xunit report.xml``
 .. _`--xunit report.xml`: https://robotframework.org/robotframework/latest/RobotFrameworkUserGuide.html#xunit-compatible-result-file
 
+Parse for Polyspace Failures
+----------------------------
+
+The Polyspace checker requires as input a TSV file exported by Polyspace.
+You can find instructions on exporting TSV files in the Polyspace documentation.
+
+Exporting Polyspace Results
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The following commands instruct Polyspace to export the results as a TSV file:
+
+.. code-block:: bash
+
+    polyspace-results-export -key-mode function-scope -format csv -results-dir <resultsFolder> <export_options>
+    # or
+    polyspace-results-export -key-mode function-scope -format csv -host <hostName> -run-id <runID> <export_options> <polyspace_access_options>
+
+The csv format outputs tab-separated values (TSV).
+Each result in the TSV format consists of tab-separated information in columns.
+Starting from Polyspace version R2024a these columns are available:
+ID, Family, Group, Color, New, Check, Information, Function, File, Status, Severity, Comment, Key, Line and Col.
+
+This file is necessary when you enable Polyspace in the configuration file.
+
+Configuration
+^^^^^^^^^^^^^
+
+Polyspace checking can only be used with a configuration file,
+and it cannot be used together with other checkers enabled.
+In this case, only the Polyspace checker will run.
+
+When you enable Polyspace checking in the configuration file,
+the checks consist of a key that represents the "family" column of the TSV file.
+For example, "run-time check" is the family of Code Prover and "defect" is the family of Bug Finder.
+The value of that key is a list, which contains the name of the column to check as a key and
+the value of that column to check together with ``min`` and ``max`` values.
+
+Example Checks
+^^^^^^^^^^^^^^
+
+In case of Code Prover, you might want to check the ``color`` column on ``red`` or ``orange`` issues.
+In case of Bug Finder, you might want to check the ``information`` column on ``impact: high``, ``impact: medium``, or even ``impact: low``.
+Other issues, such as "Global variable", can also be handled.
+You can specify any column and value you want to check in the configuration file.
+
+Default Description Template
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+``Polyspace: $check`` is the default value for the ``cq_description_template`` variable.
+
+Running the mlx-warnings plugin
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The following commands demonstrate how to run the mlx-warnings plugin with the TSV file:
+
+.. code-block:: bash
+
+    # basic Polyspace checker
+    mlx-warnings --config <configuration_file> <tsv_file>
+    # Polyspace checker with code quality export
+    mlx-warnings --code-quality path/to/code_quality.json --config <configuration_file> <tsv_file>
+
 ----------------------------------
 Configuration File to Pass Options
 ----------------------------------
@@ -341,6 +403,20 @@ The values for 'min' and 'max' can be set with environment variables via a
                     "max": 0
                 }
             ]
+        },
+        "polyspace": {
+            "enabled": false,
+            "cq_description_template": "$PRODUCT $family: $check",
+            "exclude": [
+                ".+dummy_function\(\)|dummy_file_name\.c"
+            ]
+            "run-time check": [
+                {
+                    "color": "red",
+                    "min": 0,
+                    "max": 0
+                }
+            ]
         }
     }
 
@@ -419,8 +495,16 @@ If a warning doesn't contain a path, ``"cq_default_path"`` from the `configurati
 If not configured, ``.gitlab-ci.yml`` will be used as a fallback path.
 
 You can customize the description with ``"cq_description_template"``, see `configuration file to pass options`_.
-Its value should be a template for Python's |string.Template|_. The template should contain ``$description`` and has
-access to all environment variables, e.g. ``$HOME``.
+Its value should be a template for Python's |string.Template|_. The template has access to all environment variables,
+e.g. ``$HOME``, and other variables that depend on the checker type:
+
+Polyspace
+  Any field of a Polyspace defect can be included by using the corresponding
+  `column title <Exporting Polyspace Results>`_ in lowercase as the variable name.
+  The default template is ``Polyspace: $check``
+
+Other
+  The template should contain ``$description``, which is the default.
 
 =======================
 Issues and New Features

docs/design.rst

@@ -10,57 +10,166 @@ Software Design
 Class Diagram
 =============
 
+.. uml generated by `pyreverse mlx.warnings --filter ALL -o plantuml`
 .. uml::
 
-    @startuml
-    class WarningsPlugin {
-        #checkerList : WarningsChecker
-        +__init__(sphinx=False, doxygen=False, junit=False, verbose=False)
+    @startuml classes
+    set namespaceSeparator none
+    class "CoverityChecker" as mlx.warnings.regex_checker.CoverityChecker {
+      CLASSIFICATION : str
+      count
+      name : str
+      pattern
+      check(content)
     }
-
-    class WarningsChecker {
-        #min_count = 0
-        #max_count = 0
-        #count = 0
-        #verbose = False
-
-        #{abstract} __init__(name, verbose=False)
-        +set_limits(min_count=0, max_count=0,
-        +{abstract}check(content)
-        +get_count()
+    class "DoxyChecker" as mlx.warnings.regex_checker.DoxyChecker {
+      name : str
+      pattern
     }
-
-    class RegexChecker {
-        #{abstract} __init__(name, regex, verbose=False)
-        +check(content)
+    class "JUnitChecker" as mlx.warnings.junit_checker.JUnitChecker {
+      count
+      name : str
+      _check_testcase(testcase)
+      check(content)
+      prepare_tree(root_input)
     }
-
-    class SphinxChecker {
-        #{static} String name
-        #{static} String regex
-        +__init__(verbose=False)
+    class "PolyspaceChecker" as mlx.warnings.polyspace_checker.PolyspaceChecker {
+      _cq_description_template : Template
+      checkers : list
+      count : int
+      counted_warnings
+      cq_default_path
+      cq_description_template
+      maximum
+      minimum
+      name : str
+      __init__(verbose)
+      check(content)
+      parse_config(config)
+      return_check_limits()
+      return_count()
     }
-
-    class DoxyChecker {
-        #{static} String name
-        #{static} String regex
-        +__init__(verbose=False)
+    class "PolyspaceFamilyChecker" as mlx.warnings.polyspace_checker.PolyspaceFamilyChecker {
+      _cq_description_template
+      check_value
+      code_quality_severity : dict
+      column_name
+      count
+      cq_description_template
+      cq_findings : list
+      family_value
+      __init__(family_value, column_name, check_value)
+      add_code_quality_finding(row)
+      check(content)
+      return_count()
     }
-
-    class JUnitChecker {
-        #{static} String name
-        +__init__(verbose=False)
-        +check(content)
+    class "RegexChecker" as mlx.warnings.regex_checker.RegexChecker {
+      SEVERITY_MAP : dict
+      count
+      name : str
+      pattern : NoneType
+      add_code_quality_finding(match)
+      check(content)
     }
-
-    WarningsPlugin o-- WarningsChecker
-    WarningsChecker <|-- RegexChecker
-    RegexChecker <|-- SphinxChecker
-    RegexChecker <|-- DoxyChecker
-    WarningsChecker <|-- JUnitChecker
-
+    class "RobotChecker" as mlx.warnings.robot_checker.RobotChecker {
+      checkers : list
+      count : int
+      counted_warnings
+      maximum
+      minimum
+      name : str
+      check(content)
+      parse_config(config)
+      return_check_limits()
+      return_count()
+    }
+    class "RobotSuiteChecker" as mlx.warnings.robot_checker.RobotSuiteChecker {
+      check_suite_name : bool
+      is_valid_suite_name : bool
+      name
+      __init__(name, check_suite_name)
+      _check_testcase(testcase)
+      check(content)
+      return_count()
+    }
+    class "SphinxChecker" as mlx.warnings.regex_checker.SphinxChecker {
+      name : str
+      pattern
+      sphinx_deprecation_regex : str
+      sphinx_deprecation_regex_in_match : str
+      include_sphinx_deprecation()
+    }
+    class "WarningsChecker" as mlx.warnings.warnings_checker.WarningsChecker {
+      _counted_warnings : list
+      _cq_description_template : Template
+      _maximum : int
+      _minimum : int
+      count : int
+      counted_warnings
+      cq_default_path : str
+      cq_description_template
+      cq_enabled : bool
+      cq_findings : list
+      exclude_patterns : list
+      include_patterns : list
+      maximum
+      minimum
+      name : str
+      verbose : bool
+      __init__(verbose)
+      _is_excluded(content)
+      _return_error_code()
+      _search_patterns(content, patterns)
+      add_patterns(regexes, pattern_container)
+      {abstract}check(content)
+      parse_config(config)
+      print_when_verbose(message)
+      return_check_limits()
+      return_count()
+    }
+    class "<color:red>WarningsConfigError</color>" as mlx.warnings.exceptions.WarningsConfigError {
+    }
+    class "WarningsPlugin" as mlx.warnings.warnings.WarningsPlugin {
+      _maximum : int
+      _minimum : int
+      activated_checkers : dict
+      count : int
+      cq_enabled : bool
+      printout : bool
+      public_checkers : list
+      verbose : bool
+      __init__(verbose, config_file, cq_enabled)
+      activate_checker(checker)
+      activate_checker_name(name)
+      check(content)
+      check_logfile(file)
+      config_parser(config)
+      configure_maximum(maximum)
+      configure_minimum(minimum)
+      get_checker(name)
+      return_check_limits(name)
+      return_count(name)
+      toggle_printout(printout)
+      write_code_quality_report(out_file)
+      write_counted_warnings(out_file)
+    }
+    class "XMLRunnerChecker" as mlx.warnings.regex_checker.XMLRunnerChecker {
+      name : str
+      pattern
+    }
+    mlx.warnings.junit_checker.JUnitChecker --|> mlx.warnings.warnings_checker.WarningsChecker
+    mlx.warnings.polyspace_checker.PolyspaceChecker --|> mlx.warnings.warnings_checker.WarningsChecker
+    mlx.warnings.polyspace_checker.PolyspaceFamilyChecker --|> mlx.warnings.warnings_checker.WarningsChecker
+    mlx.warnings.regex_checker.CoverityChecker --|> mlx.warnings.regex_checker.RegexChecker
+    mlx.warnings.regex_checker.DoxyChecker --|> mlx.warnings.regex_checker.RegexChecker
+    mlx.warnings.regex_checker.RegexChecker --|> mlx.warnings.warnings_checker.WarningsChecker
+    mlx.warnings.regex_checker.SphinxChecker --|> mlx.warnings.regex_checker.RegexChecker
+    mlx.warnings.regex_checker.XMLRunnerChecker --|> mlx.warnings.regex_checker.RegexChecker
+    mlx.warnings.robot_checker.RobotChecker --|> mlx.warnings.warnings_checker.WarningsChecker
+    mlx.warnings.robot_checker.RobotSuiteChecker --|> mlx.warnings.junit_checker.JUnitChecker
     @enduml
 
+
 String Handling
 ===============
 

src/mlx/warnings/__init__.py

@@ -4,6 +4,8 @@
     'CoverityChecker',
     'DoxyChecker',
     'JUnitChecker',
+    'PolyspaceChecker',
+    'PolyspaceFamilyChecker',
     'RobotChecker',
     'RobotSuiteChecker',
     'SphinxChecker',
@@ -21,5 +23,6 @@
 from .junit_checker import JUnitChecker
 from .regex_checker import CoverityChecker, DoxyChecker, SphinxChecker, XMLRunnerChecker
 from .robot_checker import RobotChecker, RobotSuiteChecker
+from .polyspace_checker import PolyspaceChecker, PolyspaceFamilyChecker
 from .warnings import WarningsPlugin, warnings_wrapper
 from .warnings_checker import WarningsChecker