feat(analyze,robot): add configurable load_library_timeout with CLI flag and robot.toml support

Add configurable library/variable load timeout. Sources (precedence):

analyze code: --load-library-timeout / --no-load-library-timeout
VS Code setting: robotcode.analysis.robot.loadLibraryTimeout
robot.toml / pyproject: [tool.robotcode-analyze] load-library-timeout
Env: ROBOTCODE_LOAD_LIBRARY_TIMEOUT
Default: 10
Replaces previous hard-coded timeout, adds validation (>0), clearer docs, and examples.

Signed-off-by: Daniel Biehl <dbiehl@live.de>

Author: d-biehl

docs/03_reference/config.md

@@ -3118,3 +3118,48 @@ option is specified.
 corresponds to the `-x --xunit file` option of _robot_
 
 
+## tool.robotcode-analyze.global-library-search-order
+
+Type: `list[str] | None`
+
+Specifies a global search order for libraries and resources used during static analysis.
+This helps disambiguate keywords with identical names coming from multiple sources.
+RobotCode cannot infer dynamic changes done at runtime via `Set Library Search Order`, so
+define a deterministic order here if needed.
+
+Examples:
+
+```toml
+[tool.robotcode-analyze]
+global_library_search_order = ["MyLib", "BuiltIn", "Collections"]
+```
+
+## tool.robotcode-analyze.load-library-timeout
+
+Type: `int | None`
+
+Specifies the timeout in seconds for loading (importing) libraries and variable files during analysis. Increase this if your libraries perform heavy initialization (network calls, large dependency graphs, model loading, etc.).
+
+Must be > 0 when set. If you omit this key, RobotCode will instead look for the environment variable `ROBOTCODE_LOAD_LIBRARY_TIMEOUT`; otherwise it will use the internal default `10`.
+
+Examples:
+
+```toml
+[tool.robotcode-analyze]
+# Fast fail if libraries normally import in < 2s
+load_library_timeout = 5
+```
+
+```toml
+[tool.robotcode-analyze]
+# Allow heavy bootstrap (e.g. Selenium + large resource trees)
+load_library_timeout = 30
+```
+
+```toml
+[tool.robotcode-analyze]
+# Omit to use default
+# load_library_timeout = 15
+```
+
+

package.json

@@ -1028,6 +1028,14 @@
             "markdownDescription": "Specifies a global [search order](https://robotframework.org/robotframework/latest/RobotFrameworkUserGuide.html#specifying-explicit-priority-between-libraries-and-resources) for libraries and resources. This is usefull when you have libraries containing keywords with the same name. **RobotCode** is unable to analyze the library search order in a file specified with [`Set Library Search Order`](https://robotframework.org/robotframework/latest/libraries/BuiltIn.html#Set%20Library%20Search%20Order), so you can define a global order here. Just make sure to call the `Set Library Search Order` keyword somewhere in your robot file or internally in your library.",
             "scope": "resource"
           },
+          "robotcode.analysis.robot.loadLibraryTimeout": {
+            "type": ["number", "null"],
+            "default": null,
+            "minimum": 1,
+            "maximum": 3600,
+            "markdownDescription": "Specifies the timeout in seconds for loading libraries and variable files during analysis. Use this when libraries initialize slowly (network calls, heavy imports, large models).\n\n**Must be > 0 when set.**\n\n**Warning:** Defining a value here overrides both the configuration file value and the environment variable.\n\nIf you change this setting, you may need to run the command `RobotCode: Clear Cache and Restart Language Servers`.",
+            "scope": "resource"
+          },
           "robotcode.analysis.diagnosticModifiers.ignore": {
             "type": "array",
             "default": [],
@@ -2051,6 +2059,7 @@
         "userDescription": "Gets informations about the Robot Framework Environment .",
         "canBeReferencedInPrompt": true,
         "tags": [
+
           "robot",
           "robotframework",
           "robotcode"

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

@@ -114,6 +114,15 @@ def _split_comma(ctx: click.Context, param: click.Option, value: Optional[List[s
     return result
 
 
+def _validate_load_library_timeout(ctx: click.Context, param: click.Option, value: Optional[int]) -> Optional[int]:
+    """Validate --load-library-timeout (>0) or pass through None."""
+    if value is None:
+        return None
+    if value <= 0:
+        raise click.BadParameter("must be > 0")
+    return value
+
+
 @click.command(
     add_help_option=True,
 )
@@ -216,6 +225,18 @@ def _split_comma(ctx: click.Context, param: click.Option, value: Optional[List[s
     help="Extend the exit code mask with the specified values. This appends to the default mask, defined in the config"
     " file.",
 )
+@click.option(
+    "--load-library-timeout",
+    type=int,
+    callback=_validate_load_library_timeout,
+    metavar="SECONDS",
+    show_envvar=True,
+    envvar="ROBOTCODE_LOAD_LIBRARY_TIMEOUT",
+    help=(
+        "Timeout (in seconds) for loading libraries and variable files during analysis. "
+        "Must be > 0. Overrides config file and environment variable when set."
+    ),
+)
 @click.argument(
     "paths", nargs=-1, type=click.Path(exists=True, dir_okay=True, file_okay=True, readable=True, path_type=Path)
 )
@@ -234,6 +255,7 @@ def code(
     exit_code_mask: ExitCodeMask,
     extend_exit_code_mask: ExitCodeMask,
     paths: Tuple[Path],
+    load_library_timeout: Optional[int],
 ) -> None:
     """\
         Performs static code analysis to identify potential issues in the specified *PATHS*. The analysis detects syntax
@@ -335,6 +357,12 @@ def code(
         )
         mask = default_mask | extend_exit_code_mask
 
+        if load_library_timeout is not None:
+            analyzer_config.load_library_timeout = load_library_timeout
+
+        app.verbose(f"Using analyzer_config: {analyzer_config}")
+        app.verbose(f"Using exit code mask: {mask}")
+
         statistics = Statistic(mask)
         for e in CodeAnalyzer(
             app=app,

packages/analyze/src/robotcode/analyze/config.py

@@ -318,6 +318,37 @@ class AnalyzeConfig(BaseOptions):
         description="Extend the global library search order setting."
     )
 
+    load_library_timeout: Optional[int] = field(
+        description="""\
+            Specifies the timeout in seconds for loading (importing) libraries and variable files during
+            analysis. Increase this if your libraries perform heavy initialization (network calls, large
+            dependency graphs, model loading, etc.).
+
+            Must be > 0 when set. If you omit this key, RobotCode will instead look for the environment
+            variable `ROBOTCODE_LOAD_LIBRARY_TIMEOUT`; otherwise it will use the internal default `10`.
+
+            Examples:
+
+            ```toml
+            [tool.robotcode-analyze]
+            # Fast fail if libraries normally import in < 2s
+            load_library_timeout = 5
+            ```
+
+            ```toml
+            [tool.robotcode-analyze]
+            # Allow heavy bootstrap (e.g. Selenium + large resource trees)
+            load_library_timeout = 30
+            ```
+
+            ```toml
+            [tool.robotcode-analyze]
+            # Omit to use default
+            # load_library_timeout = 15
+            ```
+        """,
+    )
+
     def to_workspace_analysis_config(self) -> WorkspaceAnalysisConfig:
         return WorkspaceAnalysisConfig(
             exclude_patterns=self.exclude_patterns or [],
@@ -331,7 +362,10 @@ def to_workspace_analysis_config(self) -> WorkspaceAnalysisConfig:
                 if self.cache is not None
                 else WorkspaceCacheConfig()
             ),
-            robot=AnalysisRobotConfig(global_library_search_order=self.global_library_search_order or []),
+            robot=AnalysisRobotConfig(
+                global_library_search_order=self.global_library_search_order or [],
+                load_library_timeout=self.load_library_timeout,
+            ),
             modifiers=(
                 AnalysisDiagnosticModifiersConfig(
                     ignore=self.modifiers.ignore or [],

packages/robot/src/robotcode/robot/diagnostics/document_cache_helper.py

@@ -532,6 +532,11 @@ def create_imports_manager(self, root_uri: Uri) -> ImportsManager:
             self.analysis_config.cache.ignore_arguments_for_library + cache_config.ignore_arguments_for_library,
             self.analysis_config.robot.global_library_search_order + analysis_config.global_library_search_order,
             cache_base_path,
+            load_library_timeout=(
+                analysis_config.load_library_timeout
+                if analysis_config.load_library_timeout is not None
+                else self.analysis_config.robot.load_library_timeout
+            ),
         )
 
         result.libraries_changed.add(self._on_libraries_changed)

packages/robot/src/robotcode/robot/diagnostics/imports_manager.py

@@ -96,7 +96,8 @@
 REST_EXTENSIONS = (".rst", ".rest")
 
 
-LOAD_LIBRARY_TIMEOUT: int = int(os.environ.get("ROBOTCODE_LOAD_LIBRARY_TIMEOUT", 10))
+DEFAULT_LOAD_LIBRARY_TIMEOUT: int = 10
+ENV_LOAD_LIBRARY_TIMEOUT_VAR = "ROBOTCODE_LOAD_LIBRARY_TIMEOUT"
 COMPLETE_LIBRARY_IMPORT_TIMEOUT = COMPLETE_RESOURCE_IMPORT_TIMEOUT = COMPLETE_VARIABLES_IMPORT_TIMEOUT = 5
 
 
@@ -514,6 +515,7 @@ def __init__(
         ignore_arguments_for_library: List[str],
         global_library_search_order: List[str],
         cache_base_path: Optional[Path],
+        load_library_timeout: Optional[int] = None,
     ) -> None:
         super().__init__()
 
@@ -590,6 +592,45 @@ def __init__(
 
         self._diagnostics: List[Diagnostic] = []
 
+        # precedence: explicit config (arg) > environment variable > default
+        if load_library_timeout is None:
+            env_value = os.environ.get(ENV_LOAD_LIBRARY_TIMEOUT_VAR)
+            if env_value is not None:
+                try:
+                    load_library_timeout = int(env_value)
+                except ValueError:
+                    self._logger.warning(
+                        lambda: (
+                            "Invalid value for "
+                            f"{ENV_LOAD_LIBRARY_TIMEOUT_VAR}={env_value!r}, using default "
+                            f"{DEFAULT_LOAD_LIBRARY_TIMEOUT}"
+                        ),
+                        context_name="imports",
+                    )
+                    load_library_timeout = DEFAULT_LOAD_LIBRARY_TIMEOUT
+            else:
+                load_library_timeout = DEFAULT_LOAD_LIBRARY_TIMEOUT
+
+        # enforce sane lower bound
+        if load_library_timeout <= 0:
+            self._logger.warning(
+                lambda: (
+                    "Configured load_library_timeout "
+                    f"{load_library_timeout} is not > 0, fallback to {DEFAULT_LOAD_LIBRARY_TIMEOUT}"
+                ),
+                context_name="imports",
+            )
+            load_library_timeout = DEFAULT_LOAD_LIBRARY_TIMEOUT
+
+        self.load_library_timeout = load_library_timeout
+
+        self._logger.critical(lambda: f"Using LoadLibrary timeout of {self.load_library_timeout} seconds")
+
+        self._logger.trace(
+            lambda: f"Using load_library_timeout={self.load_library_timeout} (config/env/default)",
+            context_name="imports",
+        )
+
     def __del__(self) -> None:
         try:
             if self._executor is not None:
@@ -1266,12 +1307,12 @@ def _get_library_libdoc(
                     base_dir,
                     self.get_resolvable_command_line_variables(),
                     variables,
-                ).result(LOAD_LIBRARY_TIMEOUT)
+                ).result(self.load_library_timeout)
 
             except TimeoutError as e:
                 raise RuntimeError(
                     f"Loading library {name!r} with args {args!r} (working_dir={working_dir!r}, base_dir={base_dir!r}) "
-                    f"timed out after {LOAD_LIBRARY_TIMEOUT} seconds. "
+                    f"timed out after {self.load_library_timeout} seconds. "
                     "The library may be slow or blocked during import. "
                     "If required, increase the timeout by setting the ROBOTCODE_LOAD_LIBRARY_TIMEOUT "
                     "environment variable."
@@ -1444,13 +1485,13 @@ def _get_variables_libdoc(
                     base_dir,
                     self.get_resolvable_command_line_variables() if resolve_command_line_vars else None,
                     variables,
-                ).result(LOAD_LIBRARY_TIMEOUT)
+                ).result(self.load_library_timeout)
 
             except TimeoutError as e:
                 raise RuntimeError(
                     f"Loading variables {name!r} with args {args!r} (working_dir={working_dir!r}, "
                     f"base_dir={base_dir!r}) "
-                    f"timed out after {LOAD_LIBRARY_TIMEOUT} seconds. "
+                    f"timed out after {self.load_library_timeout} seconds. "
                     "The variables may be slow or blocked during import. "
                     "If required, increase the timeout by setting the ROBOTCODE_LOAD_LIBRARY_TIMEOUT "
                     "environment variable."

packages/robot/src/robotcode/robot/diagnostics/workspace_config.py

@@ -55,6 +55,9 @@ class CacheConfig(ConfigBase):
 @dataclass
 class AnalysisRobotConfig(ConfigBase):
     global_library_search_order: List[str] = field(default_factory=list)
+    # Timeout in seconds for loading libraries and variable files during analysis. If None, fallback to env var
+    # ROBOTCODE_LOAD_LIBRARY_TIMEOUT or default (10).
+    load_library_timeout: Optional[int] = None
 
 
 @config_section("robotcode.analysis.diagnosticModifiers")