feat(analyze): exit code mask configuration for code analysis

Configure which message types should **not** influence the exit code of `robotcode analyze code`, allowing granular control over CI/CD pipeline behavior or pre-commit hooks.

**Configuration File (`robot.toml`)**

```toml
[tool.robotcode-analyze.code]
exit-code-mask = ["error", "warn"]
```

**Command Line Options**

```
robotcode analyze code --exit-code-mask error,warn    # or -xm
robotcode analyze code --extend-exit-code-mask info   # or -xe
```

- `-xm` (or `--exit-code-mask`) overwrites the configuration in `robot.toml`
- `-xe` (or `--extend-exit-code-mask`) extends the configuration in `robot.toml`
- Both options can be specified multiple times or with comma-separated values:

    ```
    robotcode analyze code -xm error -xm warn  # multiple options
    robotcode analyze code -xm error,warn      # comma-separated
    ```

**Behavior**

- Message types in the mask are ignored when determining exit code
- Available types: `error`, `warn`/`warning`, `info`/`information`, `hint`
- Special value `all` ignores all message types (always exit code 0)
- Without configuration, all message types affect the exit code

**Example**

```toml
# In robot.toml - Ignore warnings but let errors affect exit code
[tool.robotcode-analyze.code]
exit-code-mask = ["warn"]
```

```bash
# Using short options
robotcode analyze code -xm error,hint  # Overwrites robot.toml config
robotcode analyze code -xe info -xe hint  # Extends robot.toml config with multiple types
robotcode analyze code -xm all          # Always exit with code 0
```

closes #358

Author: d-biehl

.vscode/launch.json

@@ -78,10 +78,10 @@
 				// "suites",
 				// // "discover", "tests", "--tags"
 				// "."
-				"discover",
-				"--no-diagnostics",
-				"all",
-				".."
+				// "discover",
+				// "--no-diagnostics",
+				// "all",
+				// ".."
 				// "config",
 				// "show",
 				// "discover",
@@ -90,8 +90,8 @@
 				// "-i",
 				// "-v", "CMD_LINE_VAR:cmd_line_var",
 				// "E:\\source\\uvtestprj\\tests\\first.robotrepl"
-				// "analyze",
-				// "code",
+				"analyze",
+				"code",
 				// "--help"
 				// "tests"
 				// "repl-server",

docs/03_reference/cli.md

@@ -2615,6 +2615,38 @@ Examples:
 - `MyVariables`
 - `myvars.subpackage.subpackage`
 
+## tool.robotcode-analyze.code
+
+Type: `CodeConfig | None`
+
+Defines the code analysis configuration.
+
+Examples:
+
+```toml
+[tool.robotcode-analyze.code]
+exit_code_mask = "error|warn"
+```
+
+## tool.robotcode-analyze.code.exit-code-mask
+
+Type: `list[Literal['error', 'warn', 'warning', 'info', 'information', 'hint']] | None`
+
+Specifies the exit code mask for the code analysis.
+This is useful if you want to ignore certain types of diagnostics in the result code.
+
+Examples:
+```toml
+[tool.robotcode-analyze.code]
+exit_code_mask = ["error", "warn"]
+```
+
+## tool.robotcode-analyze.code.extend-exit-code-mask
+
+Type: `list[Literal['error', 'warn', 'warning', 'info', 'information', 'hint']] | None`
+
+Extend the exit code mask setting.
+
 ## tool.robotcode-analyze.exclude-patterns
 
 Type: `list[str] | None`
@@ -2701,6 +2733,31 @@ Examples:
 - `MyVariables`
 - `myvars.subpackage.subpackage`
 
+## tool.robotcode-analyze.extend-code
+
+Type: `CodeConfig | None`
+
+Extend the code analysis configuration.
+
+## tool.robotcode-analyze.extend-code.exit-code-mask
+
+Type: `list[Literal['error', 'warn', 'warning', 'info', 'information', 'hint']] | None`
+
+Specifies the exit code mask for the code analysis.
+This is useful if you want to ignore certain types of diagnostics in the result code.
+
+Examples:
+```toml
+[tool.robotcode-analyze.code]
+exit_code_mask = ["error", "warn"]
+```
+
+## tool.robotcode-analyze.extend-code.extend-exit-code-mask
+
+Type: `list[Literal['error', 'warn', 'warning', 'info', 'information', 'hint']] | None`
+
+Extend the exit code mask setting.
+
 ## tool.robotcode-analyze.extend-exclude-patterns
 
 Type: `list[str] | None`

docs/03_reference/config.md

@@ -23,6 +23,19 @@
           "description": "Defines the cache configuration.",
           "title": "Cache"
         },
+        "code": {
+          "anyOf": [
+            {
+              "$ref": "#/definitions/CodeConfig"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Defines the code analysis configuration.\n\nExamples:\n\n```toml\n[tool.robotcode-analyze.code]\nexit_code_mask = \"error|warn\"\n```\n",
+          "title": "Code"
+        },
         "exclude-patterns": {
           "default": null,
           "description": "Specifies glob patterns for excluding files and folders from analysing by the language server.",
@@ -48,6 +61,19 @@
           "description": "Extend the cache configuration.",
           "title": "Extend cache"
         },
+        "extend-code": {
+          "anyOf": [
+            {
+              "$ref": "#/definitions/CodeConfig"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Extend the code analysis configuration.",
+          "title": "Extend code"
+        },
         "extend-exclude-patterns": {
           "default": null,
           "description": "Extend the exclude patterns.",
@@ -203,6 +229,54 @@
       "title": "CacheConfig",
       "type": "object"
     },
+    "CodeConfig": {
+      "additionalProperties": false,
+      "description": "robotcode-analyze code configuration.",
+      "properties": {
+        "exit-code-mask": {
+          "default": null,
+          "description": "Specifies the exit code mask for the code analysis.\nThis is useful if you want to ignore certain types of diagnostics in the result code.\n\nExamples:\n```toml\n[tool.robotcode-analyze.code]\nexit_code_mask = [\"error\", \"warn\"]\n```\n",
+          "items": {
+            "enum": [
+              "error",
+              "warn",
+              "warning",
+              "info",
+              "information",
+              "hint"
+            ],
+            "type": "string"
+          },
+          "title": "Exit code mask",
+          "type": [
+            "array",
+            "null"
+          ]
+        },
+        "extend-exit-code-mask": {
+          "default": null,
+          "description": "Extend the exit code mask setting.",
+          "items": {
+            "enum": [
+              "error",
+              "warn",
+              "warning",
+              "info",
+              "information",
+              "hint"
+            ],
+            "type": "string"
+          },
+          "title": "Extend exit code mask",
+          "type": [
+            "array",
+            "null"
+          ]
+        }
+      },
+      "title": "CodeConfig",
+      "type": "object"
+    },
     "Condition": {
       "additionalProperties": false,
       "description": "Condition to evaluate.",

etc/robot.toml.json

@@ -17,7 +17,7 @@
 from robotcode.robot.config.utils import get_config_files
 
 from ..__version__ import __version__
-from ..config import AnalyzeConfig, ModifiersConfig
+from ..config import AnalyzeConfig, ExitCodeMask, ModifiersConfig
 from .code_analyzer import CodeAnalyzer, DocumentDiagnosticReport, FolderDiagnosticReport
 
 SEVERITY_COLORS = {
@@ -37,7 +37,8 @@ class ReturnCode(Flag):
 
 
 class Statistic:
-    def __init__(self) -> None:
+    def __init__(self, exit_code_mask: ExitCodeMask) -> None:
+        self.exit_code_mask = exit_code_mask
         self._folders: Set[WorkspaceFolder] = set()
         self._files: Set[TextDocument] = set()
         self._diagnostics: List[Union[DocumentDiagnosticReport, FolderDiagnosticReport]] = []
@@ -86,17 +87,33 @@ def __str__(self) -> str:
 
     def calculate_return_code(self) -> ReturnCode:
         return_code = ReturnCode.SUCCESS
-        if self.errors > 0:
+        if self.errors > 0 and not self.exit_code_mask & ExitCodeMask.ERROR:
             return_code |= ReturnCode.ERRORS
-        if self.warnings > 0:
+        if self.warnings > 0 and not self.exit_code_mask & ExitCodeMask.WARN:
             return_code |= ReturnCode.WARNINGS
-        if self.infos > 0:
+        if self.infos > 0 and not self.exit_code_mask & ExitCodeMask.INFO:
             return_code |= ReturnCode.INFOS
-        if self.hints > 0:
+        if self.hints > 0 and not self.exit_code_mask & ExitCodeMask.HINT:
             return_code |= ReturnCode.HINTS
         return return_code
 
 
+def _parse_exit_code_mask(ctx: click.Context, param: click.Option, value: Tuple[str, ...]) -> ExitCodeMask:
+    try:
+        return ExitCodeMask.parse(value)
+    except KeyError as e:
+        raise click.BadParameter(str(e)) from e
+
+
+def _split_comma(ctx: click.Context, param: click.Option, value: Optional[List[str]]) -> List[str]:
+    if value is None:
+        return []
+    result: List[str] = []
+    for item in value:
+        result.extend([x.strip() for x in item.split(",") if x.strip()])
+    return result
+
+
 @click.command(
     add_help_option=True,
 )
@@ -181,6 +198,24 @@ def calculate_return_code(self) -> ReturnCode:
     multiple=True,
     help="Specifies the diagnostics codes to treat as hint.",
 )
+@click.option(
+    "--exit-code-mask",
+    "-xm",
+    multiple=True,
+    callback=_parse_exit_code_mask,
+    metavar="[" + "|".join(member.name.lower() for member in ExitCodeMask if member.name is not None) + "|all]",
+    help="Specifies which diagnostic severities should not affect the exit code. "
+    "For example, with 'warn' in the mask, warnings won't cause a non-zero exit code.",
+)
+@click.option(
+    "--extend-exit-code-mask",
+    "-xe",
+    multiple=True,
+    callback=_parse_exit_code_mask,
+    metavar="[" + "|".join(member.name.lower() for member in ExitCodeMask if member.name is not None) + "|all]",
+    help="Extend the exit code mask with the specified values. This appends to the default mask, defined in the config"
+    " file.",
+)
 @click.argument(
     "paths", nargs=-1, type=click.Path(exists=True, dir_okay=True, file_okay=True, readable=True, path_type=Path)
 )
@@ -196,6 +231,8 @@ def code(
     modifiers_warning: Tuple[str, ...],
     modifiers_information: Tuple[str, ...],
     modifiers_hint: Tuple[str, ...],
+    exit_code_mask: ExitCodeMask,
+    extend_exit_code_mask: ExitCodeMask,
     paths: Tuple[Path],
 ) -> None:
     """\
@@ -291,7 +328,14 @@ def code(
                 analyzer_config.modifiers.hint = []
             analyzer_config.modifiers.hint.extend(modifiers_hint)
 
-        statistics = Statistic()
+        default_mask = (
+            exit_code_mask
+            if exit_code_mask != ExitCodeMask.NONE
+            else ExitCodeMask.parse(analyzer_config.code.exit_code_mask if analyzer_config.code is not None else None)
+        )
+        mask = default_mask | extend_exit_code_mask
+
+        statistics = Statistic(mask)
         for e in CodeAnalyzer(
             app=app,
             analysis_config=analyzer_config.to_workspace_analysis_config(),

packages/analyze/src/robotcode/analyze/code/cli.py

@@ -83,7 +83,7 @@ def run(
     ) -> Iterable[Union[DocumentDiagnosticReport, FolderDiagnosticReport]]:
         for folder in self.workspace.workspace_folders:
             self.app.verbose(f"Initialize folder {folder.uri.to_path()}")
-            initialize_result = self.diagnostics.initialize_folder(folder)
+            initialize_result = self.diagnostics.analyze_folder(folder)
             if initialize_result is not None:
                 diagnostics: List[Diagnostic] = []
                 for item in initialize_result:

packages/analyze/src/robotcode/analyze/code/code_analyzer.py

@@ -14,13 +14,13 @@ class DiagnosticHandlers:
     @event
     def document_analyzers(sender, document: TextDocument) -> Optional[List[Diagnostic]]: ...
     @event
-    def folder_initializers(sender, folder: WorkspaceFolder) -> Optional[List[Diagnostic]]: ...
+    def folder_analyzers(sender, folder: WorkspaceFolder) -> Optional[List[Diagnostic]]: ...
 
     @event
     def collectors(sender, document: TextDocument) -> Optional[List[Diagnostic]]: ...
 
-    def initialize_folder(self, folder: WorkspaceFolder) -> List[Union[List[Diagnostic], BaseException, None]]:
-        return self.folder_initializers(
+    def analyze_folder(self, folder: WorkspaceFolder) -> List[Union[List[Diagnostic], BaseException, None]]:
+        return self.folder_analyzers(
             self,
             folder,
             return_exceptions=True,

packages/analyze/src/robotcode/analyze/code/diagnostics_context.py

@@ -47,7 +47,7 @@ def __init__(self, diagnostics_context: DiagnosticsContext) -> None:
         )
 
         self.diagnostics_context.workspace.documents.on_read_document_text.add(self.on_read_document_text)
-        self.diagnostics_context.diagnostics.folder_initializers.add(self.analyze_folder)
+        self.diagnostics_context.diagnostics.folder_analyzers.add(self.analyze_folder)
         self.diagnostics_context.diagnostics.document_analyzers.add(self.analyze_document)
 
     def _update_python_path(self) -> None: