feat: project level context with rules using it

[bhirsz]

Summary

Adds project level context to the linter and the first rules built on top of it. This is the foundation discussed in #1677, where the direction was to investigate how robotcode solves this. Implemented self-contained, without depending on the robotcode LSP stack.

Still a draft - more rules are planned on this branch.

Problem

run_project_checks() never parsed anything. It only handed the ConfigManager to each checker, which then had to rglob and parse files on its own. Writing a project rule meant reimplementing discovery, parsing and import resolution every time.

That is why unused-keyword was deprecated and disabled: it defines visit_File, but ProjectChecker has no visiting machinery, so it was effectively dead code.

Project context

A ProjectContext is now built once and passed to ProjectChecker.scan_project:

• Keyword definitions and usages indexed across the project, with embedded arguments, Resource.Keyword prefixes and BDD prefixes.
• Argument specifications parsed with Robot Framework's own UserKeywordArgumentParser, so no library is imported and no user code is executed.
• Keyword visibility resolved through transitive resource imports, so same named keywords in unrelated files are not confused.
• Variables with Robot Framework compatible scoping (command line > file's own *** Variables *** > imported > builtin).
• Imports resolved to real paths via robot.variables.Variables.replace_string, so %{ENV}, nesting and escaping behave exactly like in Robot Framework.

Imports using variables that cannot be resolved are marked UNRESOLVABLE and are never reported. This is the main safety valve against false positives on dynamic paths.

The context is only built when an enabled checker actually uses it, so a run without project rules does not pay for parsing the project.

Configuration

Variables can be provided the same way as in Robot Framework:

robocop check-project --variable RESOURCE_DIR:resources
robocop check-project -v RESOURCE_DIR:resources

or in the configuration file:

[tool.robocop.variables]
RESOURCE_DIR = "resources"

Variable names are no longer normalized, so MY-VAR stays MY-VAR. Previously normalize_config_keys rewrote - to _ recursively, which would have silently corrupted user defined variable names.

New rules

All of them are disabled by default and have to be selected explicitly.

invalid-argument-count (ARG08)

Compares the arguments used in a call with the [Arguments] of the definition.

test.robot:19:5 ARG08 Keyword 'Login' expects 2 arguments but 1 provided, missing ${password}
test.robot:20:5 ARG08 Keyword 'Login' expects 2 arguments but 3 provided
test.robot:21:5 ARG08 Keyword 'With Default' expects from 1 to 2 arguments but 0 provided, missing ${a}

Named arguments are resolved the way Robot Framework does it: name=value is only named when name matches an argument of the keyword or the keyword accepts free named arguments, otherwise it is a positional value.

Skipped to avoid false positives: dynamic keyword names, keywords not found or ambiguous, embedded arguments, @{list} / &{dict} expansion, and template keywords.

unused-keyword (KW04)

Un-deprecated and rewritten. Reports keywords never called anywhere in the project, taking into account setups, teardowns, templates and Run Keyword variants.

Private keywords are only matched against calls from their own file. Calls with a name built from a variable become a pattern, so Login ${type} marks both Login Admin and Login User as used.

unused-resource-import (IMP05)

Reports resource imports whose keywords and variables are never used.

test.robot:3:13 IMP05 Imported resource file 'resources/unused.resource' is not used

Resource imports are transitive in Robot Framework, so an import is checked against the usages of every file that can see it. A resource imported only to re-export its own imports is therefore not reported, and neither is a resource that defines no keywords and no variables.

Skipped to avoid false positives: unresolved imports and files calling keywords by a name built from a variable.

duplicated-variable-in-project (DUP11)

Reports the same variable defined in several files that are visible together through imports.

other.resource:2:1 DUP11 Variable 'browser' is also defined in 'common.resource' (line 2)

Robot Framework does not complain about this, but the value used at runtime depends on the import order, which makes it a common source of hard to debug problems. Names are normalized, so ${my var}, ${MY_VAR} and ${myvar} are the same variable.

unresolved-resource-import (IMP07)

Reports resource imports pointing to files that do not exist.

Backwards compatibility

ProjectChecker.scan_project gained an optional third context argument. Custom checkers written against the old two argument signature are detected by inspecting the signature and are still called without the context.

Signature inspection is used rather than try/except TypeError, so a TypeError raised inside a checker is not silently misinterpreted as an old signature.

Docs

The project checks documentation described a scan_project signature and a source argument that never worked. Rewritten and corrected, which closes #1722.

Follow-up

Planned next, not in this PR yet:

• unused-library-import (Rule Request: Unused resource #1780), limited to standard libraries until library introspection lands
• ambiguous-keyword-name, keyword-not-found
• per-file context caching
• exposing the context to formatters (New formatter suggestion: make keyword call use named parameters #1677)

Test plan

• Cross-checked invalid-argument-count against robot --dryrun on a fixture with valid, invalid, nested and dynamic calls - Robocop reports exactly the same set of errors, no more and no less.
• The previously skipped unused-keyword acceptance tests are enabled again. Expected output gained one keyword defined in a resource file and never called, which is the exact case the old rule could not detect.
• New unit tests for argument specs and call validation, nested run keyword argument association, keyword visibility through imports, --variable parsing and config key normalization.
• Manually verified that an unresolvable import variable produces no diagnostic, and that supplying it via --variable makes the import resolve.
• Full suite: 1969 passed, 77 skipped (was 1883 passed, 79 skipped on main).
• ruff check / ruff format clean; mypy unchanged from baseline (7 pre-existing errors in untouched files).

Closes #1017
Closes #1119
Closes #1780
Closes #1722