robotframework-robocop 8.7.0__tar.gz → 9.0.0__tar.gz

robotframework_robocop-9.0.0/.gitattributes

@@ -0,0 +1,15 @@
+# Normalize line endings to LF for all text files in the repository.
+# Git auto-detects text vs binary; text files are stored as LF in the repo
+# and checked out as LF on every platform (including Windows), regardless of
+# a contributor's core.autocrlf / core.eol settings.
+* text=auto eol=lf
+
+# Explicitly treat common binary assets as binary so they are never altered.
+*.png binary
+*.jpg binary
+*.jpeg binary
+*.gif binary
+*.ico binary
+*.svg text eol=lf
+*.woff binary
+*.woff2 binary

robotframework_robocop-9.0.0/.github/copilot-instructions.md

@@ -0,0 +1,132 @@
+# Robocop
+
+Robocop is a static code analysis tool (linter) and code formatter for
+[Robot Framework](https://github.com/robotframework/robotframework). It parses `.robot`/`.resource` files using the
+official Robot Framework parsing API and reports linting issues or rewrites files. Requires Python 3.10+ and Robot
+Framework 5.0+.
+
+The package lives under `src/robocop/`. The CLI entry point is `robocop = "robocop.run:main"` (Typer-based), with
+subcommands `check`, `check-project`, `format`, `list`, `docs`, and `migrate`. A separate `robocop-mcp` entry point
+starts an MCP server (`robocop.mcp.server:main`).
+
+## Build, test, and lint
+
+Uses [`uv`](https://docs.astral.sh/uv/) for environment management (`pip install uv` first).
+
+- Run the full test suite: `uv run pytest tests`
+- Run a single test file: `uv run pytest tests/linter/rules/comments/todo_in_comment/test_rule.py`
+- Run a single test: `uv run pytest tests/.../test_rule.py::TestRuleAcceptance::test_rule`
+- Tests run in parallel via `pytest-xdist`; mark documentation/code-example tests with the `docs` pytest marker.
+- Lint: `uv run ruff check` and `uv run ruff format`
+- Type check: `uv run mypy --config-file=pyproject.toml .\src\robocop\` (mypy runs in `strict` mode)
+- Pre-commit runs ruff + mypy: `pre-commit install` then commits are checked automatically.
+
+Cross-version testing (multiple Python + Robot Framework versions) is done with `nox` (sessions defined in
+`noxfile.py`):
+- All combinations: `nox -s tests`
+- Single Python version: `nox -s --python 3.13 tests`
+- Build docs: `uv run nox -s docs` (or `uv run mkdocs serve` for live preview)
+
+Ruff is configured with `select = ["ALL"]` and a curated ignore list in `pyproject.toml`; line length is 120. Respect
+the existing per-file ignores (e.g. `tests/*` skip annotations/asserts, `src/robocop/mcp/*` allows lazy imports).
+
+## Architecture
+
+The two core features are the **linter** (`src/robocop/linter/`) and the **formatter** (`src/robocop/formatter/`). Both
+are driven through `src/robocop/run.py` (the Typer CLI) and share configuration in `src/robocop/config/`.
+
+- **Linter** (`linter/`): `runner.py` orchestrates parsing and checker execution. Rule definitions live in
+  `linter/rules/*.py` and the checkers that visit the code live in `linter/checkers/*.py`, both grouped by category
+  (e.g. `comments.py`, `naming.py`, `spacing.py`, `variables.py`); a checker module imports the rule module of the
+  same name. `linter/rules/` is purely declarative (rules, rule parameters and small helpers) — it never imports
+  checkers. Checkers subclass one of the base classes in `linter/rules/__init__.py`:
+  - `VisitorChecker` — walks the Robot Framework AST (`ModelVisitor`).
+  - `RawFileChecker` — inspects raw file lines (for things parsing can't express).
+  - `ProjectChecker` / `AfterRunChecker` — run once after all files are processed.
+  A checker visits each file once, gathering data, and delegates the decision logic to `check()` methods on the rules.
+  Diagnostics are produced via `linter/diagnostics.py`; auto-fixes via `linter/fix.py`; reports (e.g. SonarQube,
+  summary tables) live in `linter/reports/`.
+- **Formatter** (`formatter/`): each transformer is its own `CamelCase` file under `formatter/formatters/` (e.g.
+  `NormalizeSeparators.py`, `RenameKeywords.py`). `runner.py` applies them; `aligners_core.py` holds shared alignment
+  logic. `disablers.py`/`skip.py` handle opt-out directives.
+- **Config** (`config/`): TOML-based configuration loaded from `pyproject.toml`, `robocop.toml`, or `robot.toml`.
+  `parser.py`/`manager.py`/`schema.py` handle loading and merging; `runtime/resolver.py` resolves per-directory config.
+- **MCP server** (`mcp/`): exposes lint/format over the Model Context Protocol. Optional dependency group `mcp`
+  (`fastmcp`, `pydantic`). The module uses lazy (function-level) imports to isolate the optional dependency.
+- **Version handling**: `version_handling.py` parses and compares Robot Framework versions so rules/tests can be gated
+  by RF version (`ROBOT_VERSION`, `VersionSpecifier`). Many rules behave differently across RF 4/5/6/7.
+
+## Key conventions
+
+### Rule definition
+Each rule is a `Rule` subclass (see `linter/rules/__init__.py`). Required attributes:
+- `name` — kebab-case (e.g. `todo-in-comment`)
+- `rule_id` — category prefix + number (e.g. `COM01` for comments, `SPC22` for spacing)
+- `message` — supports `{placeholder}` substitution
+- `severity` — `RuleSeverity.{ERROR,WARNING,INFO}`
+- `added_in_version` — Robocop version the rule was introduced
+- `parameters` — list of `RuleParam` for configurable options (with `converter`, `desc`, `show_type`)
+
+The **rule docstring is the user-facing documentation** (rendered at https://robocop.dev/stable/rules_list/), so keep
+examples and configuration notes there. Old rule IDs go in `deprecated_names`.
+
+### Formatter definition
+Each formatter is a class that inherits `Formatter` (a `ModelTransformer` subclass) and lives in its own file under
+`formatter/formatters/` whose filename **must match the class name** (e.g. `NormalizeComments.py` →
+`class NormalizeComments`). New formatters must be added to the ordered `FORMATTERS` list in
+`formatter/formatters/__init__.py` — order matters, as formatters run sequentially.
+- Transform the AST with `visit_*` methods (e.g. `visit_Comment`, `visit_Statement`), same as a Robot Framework
+  `ModelTransformer`.
+- Add `ENABLED = False` to keep a formatter out of the default run (only applied when explicitly selected via
+  `--select`).
+- Declare supported skip options in a `HANDLES_SKIP` frozenset and gate behavior through `self.skip`.
+- As with rules, the **class docstring is the user-facing documentation**; mirror it in
+  `docs/formatter/formatters/<name>.md`.
+
+### Rule/formatter tests (acceptance-style)
+Linter rule tests live under `tests/linter/rules/<category>/<rule_name>/` where `<rule_name>` has `-` replaced with `_`
+(e.g. rule `invalid-argument` → `tests/linter/rules/arguments/invalid_argument/`). Each directory contains:
+- empty `__init__.py` (for pytest discovery)
+- `test_rule.py` with a `TestRuleAcceptance(RuleAcceptance)` class (from `tests.linter.utils`)
+- input `.robot` file(s)
+- `expected_output.txt` (and often `expected_extended.txt`)
+
+`RuleAcceptance` infers the rule name from the directory name. Use
+`check_rule(src_files=[...], expected_file=..., output_format=..., test_on_version=...)`. Default output is `simple`;
+also verify `extended` output. Gate version-specific behavior with `test_on_version` (e.g. `">=4"`).
+
+### Configuration model
+Rules and formatters are configured with `--configure <name>.<param>=<value>` (e.g. `line-too-long.line_length=140`);
+selection with `--select`. The same options are expressible in TOML under
+`[tool.robocop.lint]` / `[tool.robocop.format]`.
+
+### Documentation
+Docs are mkdocs (material theme) under `docs/`, partly generated from rule docstrings. When changing behavior, update
+the relevant doc: formatters at `docs/formatter/formatters/<name>.md`, custom-rule docs at
+`docs/linter/custom_rules.md`, rule docs via the docstring.
+
+### Branch, commit and PR naming
+Everything is keyed off a Conventional Commits type. Allowed types (enforced by
+`.github/workflows/pr-title.yml`): `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `build`, `ci`,
+`chore`, `revert`.
+
+Pick the type that matches the change, then use it consistently:
+
+| Artifact | Format | Example |
+| --- | --- | --- |
+| Branch | `<type>/short-description` (kebab-case after the slash) | `feat/add-ignored-sections-param` |
+| Commit | `<type>: description` | `feat: add ignored sections parameter` |
+| PR title | `<type>: description` | `feat: add ignored sections parameter` |
+
+Rules:
+- Description is lowercase, imperative mood, no trailing period.
+- Branch name uses `/` after the type and `-` between words; do not use `_` or spaces. The words after the slash
+  should mirror the commit/PR description, so `feat: add ignored sections param` → `feat/add-ignored-sections-param`.
+- Scopes are optional (`feat(linter): ...`); never required.
+- Breaking changes use `<type>!: description` or a `BREAKING CHANGE:` footer.
+- Keep branch, commits and PR title on the same type so the generated changelog matches the branch.
+
+### Releases
+Versioning/changelog is automated via release-please (`release-please-config.json`, `.release-please-manifest.json`).
+Follow Conventional Commits — PR titles are validated by `.github/workflows/pr-title.yml`. Version lives in
+`src/robocop/__init__.py`.

robotframework_robocop-9.0.0/.github/workflows/megalinter.yml

@@ -0,0 +1,23 @@
+name: MegaLinter
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+
+jobs:
+  megalinter:
+    name: MegaLinter
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 2
+
+      - name: Run MegaLinter
+        id: ml
+        uses: oxsecurity/megalinter/flavors/python@v9.2.0

robotframework_robocop-9.0.0/.github/workflows/publish.yml

@@ -0,0 +1,25 @@
+name: Publish Robocop
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+jobs:
+  pypi:
+    name: Publish to PyPI
+    runs-on: ubuntu-latest
+    environment:
+      name: release
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v3
+      - run: uv build
+      # Check that basic features work and we didn't miss to include crucial files
+      #      - name: Smoke test (wheel) TODO: See in the future
+      #        run: uv run --isolated --no-project -p 3.13 --with dist/*.whl tests/smoke_test.py
+      #      - name: Smoke test (source distribution)
+      #        run: uv run --isolated --no-project -p 3.13 --with dist/*.tar.gz tests/smoke_test.py
+      - run: uv publish --trusted-publishing always

robotframework_robocop-9.0.0/.pre-commit-config.yaml

@@ -0,0 +1,41 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: mixed-line-ending
+        args: ["--fix=lf"]
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.14.8
+    hooks:
+      - id: ruff
+      - id: ruff-format
+
+  - repo: local
+    hooks:
+      - id: update-rules-list
+        name: update docs/rules_list.md
+        entry: python docs/update_rules_list.py
+        language: system
+        pass_filenames: false
+        files: ^(src/robocop/linter/rules/.*\.py|docs/(rules_list_generator|update_rules_list|rules_metadata)\.py)$
+
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.19.1
+    hooks:
+      - id: mypy
+        args: ["--config-file=pyproject.toml", "src/robocop"]
+        pass_filenames: false
+        additional_dependencies:
+          - typer>=0.12.5
+          - jinja2>=3.1.4
+          - rich>=10.11.0
+          - tomli>=2.0.0
+          - tomli-w>=1.0
+          - pathspec>=0.12
+          - platformdirs>=4.3
+          - pytz>=2022.7
+          - types-jinja2
+          - types-pytz
+          - fastmcp>=2.13.0
+          - msgpack-types

robotframework_robocop-9.0.0/.pre-commit-hooks.yaml

@@ -0,0 +1,15 @@
+- id: robocop
+  name: robocop
+  description: "Robot Framework linter"
+  entry: robocop check --force-exclude
+  language: python
+  files: '.*\.(robot|resource)$'
+  minimum_pre_commit_version: "2.9.2"
+
+- id: robocop-format
+  name: robocop-format
+  description: "Robot Framework formatter"
+  entry: robocop format --force-exclude
+  language: python
+  files: '.*\.(robot|resource)$'
+  minimum_pre_commit_version: "2.9.2"

robotframework_robocop-9.0.0/.readthedocs.yml

@@ -0,0 +1,21 @@
+---
+version: 2
+
+mkdocs:
+  configuration: mkdocs.yml
+
+build:
+   os: ubuntu-24.04
+   tools:
+      python: "3.13"
+   jobs:
+      create_environment:
+         - asdf plugin add uv
+         - asdf install uv latest
+         - asdf global uv latest
+         - uv venv
+      install:
+         - uv sync --group doc
+      build:
+         html:
+           - uv run mkdocs build --clean --site-dir $READTHEDOCS_OUTPUT/html --config-file mkdocs.yml

robotframework_robocop-9.0.0/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "9.0.0"
+}

robotframework_robocop-9.0.0/CONTRIBUTING.md

@@ -0,0 +1,190 @@
+# CONTRIBUTING
+
+All contributions are welcome.
+
+Contributing may be anything starting from an idea or bug reported in our issues, discussion on our Slack channel
+[#robocop-linter](https://robotframework.slack.com/archives/C01AWSNKC2H) located in
+[Robot Framework workspace](https://robotframework.slack.com/>) or finally code change directly in the Robocop
+repository.
+
+## Submitting issues
+
+Bugs and enhancements are tracked in the [issue tracker](https://github.com/MarketSquare/robotframework-robocop/issues).
+
+Before submitting a new issue, it is always a good idea to check if the
+same bug or enhancement is already reported. If it is, please add your comments
+to the existing issue instead of creating a new one.
+
+## Code contributions
+
+### Development environment
+
+To set up your local development environment, use install uv first:
+
+```commandline
+pip install uv
+```
+
+You can now run our tests with:
+
+```commandline
+uv run pytest tests
+```
+
+``uv``` will create a local environment for you. You can use it in your IDE for type hinting or to run selected tests
+from the UI.
+
+To test Robocop on multiple Python and Robot versions, you need to create multiple environments and run tests
+through nox. You will need nox:
+
+```commandline
+pip install nox
+```
+
+And multiple Python versions:
+
+```commandline
+uv python install 3.10 3.11 3.12 3.13
+```
+
+To run all nox sessions (defined in ``noxfile.py``), run in the root of the project:
+
+```commandline
+nox -s tests
+```
+
+Running all combinations may take a while. Instead, you can run all major supported Robot versions using
+a selected Python version with:
+
+```commandline
+nox -s --python 3.13 tests
+```
+
+## Coding conventions
+
+Robocop uses ruff as a basic tool for formatting and linting code. Run it using pre-commit to ensure that
+every commit follows our code conventions:
+
+```commandline
+pip install pre-commit
+```
+
+Run from the root of the project:
+
+```commandline
+pre-commit install
+```
+
+You can run tools used in pre-commit manually:
+
+- ruff check (``uv run ruff check``)
+- ruff format (``uv run ruff format``)
+- mypy (``uv run mypy --config-file=pyproject.toml .\src\robocop\``)
+
+
+## Testing
+
+We are using pytest for our test framework. While it would be possible to use Robot Framework, it's easier for us
+to use a different test framework as we can easily mock in unit tests and set up different robot framework versions
+for acceptance testing.
+
+Our tests structure around main features in Robocop:
+
+```text
+tests/
+    formatter/ - formatting tests
+    linter/ - linting tests
+    config/ - config related tests (note that some of the config related tests may be still inside linter/formatter)
+    migrate_config/ - tests for robocop migrate command
+```
+
+Typically, users are contributing in the following areas:
+
+- adding / updating existing rules
+- adding / updating reports
+- adding / updating formatters
+- core functions changes
+
+We will cover how to approach testing for each category.
+
+## Adding / updating existing rules
+
+After you update or add new rule, or even better before you do it, you need to create tests for it under
+``tests/linter/rules/<rule_category>/<rule_name>``. Rule name has replaced ``-`` characters with ``_`` so it's
+recognised by default by pytest.
+
+For example, rule ``invalid-argument`` has tests placed under ``tests/linter/rules/arguments/invalid_argument``
+directory.
+
+Each such directory has at least the following files:
+
+- empty ``__init__.py`` file (for tests discovery)
+- ``test_rule.py`` file that describes tests
+- ``test.robot`` file (name can be different) with Robot Framework code to be linted
+- ``expected_output.txt`` with content of output which Robocop is expected to print
+
+Depending on tested features, you may have multiple robot files with one expected file, or several expected files
+(for example, one for every robot version, if rule behaviour changes over versions).
+
+Example Python file:
+
+```Python
+from tests.linter.utils import RuleAcceptance
+
+
+class TestRuleAcceptance(RuleAcceptance):
+    def test_rule(self):
+        self.check_rule(
+            src_files=["test.robot"], expected_file="expected_output.txt", test_on_version=">=4"
+        )
+
+```
+
+It will select and run only one rule (name will be taken from the directory name) on ``test.robot`` file, compare
+output with ``expected_output.txt``. Tests will only run on versions ``>=4``.
+
+Default output format in Robocop is ``extended`` view. Most tests use ``simple`` view by default (for simplicity).
+It's highly recommended to check how the rule behaves with both views. You can configure to run on different view
+using ``configure``:
+
+```Python
+def test_rule(self):
+    self.check_rule(
+        src_files=["test.robot"], expected_file="expected_output.txt", output_format="extended"
+    )
+```
+
+## Documentation
+
+Robocop uses both dynamically and statically loaded documentation.
+
+For documentation backend we are using mkdocs with the material theme. Documentation source files are stored in ``docs``.
+
+After merging the changes, documentation is rebuilt and deployed at [https://robocop.dev/](https://robocop.dev/). It is advised to build
+documentation locally to check it.
+
+If you are adding or updating new features, you may need to update relevant sections in the documentation. For example,
+if you're changing how external rules works, you may need to update ``docs/linter/custom_rules.md`` document.
+
+If you are adding or updating formatter, you need to add or modify a file at ``docs/formatter/formatters/<formatter_name>.md``.
+
+If you are adding or updating a rule, you need to update the rule docstring and check how the rule documentation
+generates at [https://robocop.dev/stable/rules_list/](https://robocop.dev/stable/rules_list/).
+
+The rules list is also committed as ``docs/rules_list.md`` (a materialized copy of the generated page, so tools that
+read the raw repository sources, such as Context7, get the complete, up-to-date rule reference). Regenerate it after
+changing any rule with:
+
+```bash
+uv run python docs/update_rules_list.py
+```
+
+A pre-commit hook regenerates the file, and a CI job verifies it stays up to date.
+
+### Build documentation locally
+
+If you have a Robocop development environment ready (with uv installed), run:
+
+```bash
+uv run mkdocs serve
+```