robotframework-lint-lsp 1.0.0__tar.gz

robotframework_lint_lsp-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Abdulwahab Isam
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

robotframework_lint_lsp-1.0.0/PKG-INFO

@@ -0,0 +1,127 @@
+Metadata-Version: 2.4
+Name: robotframework-lint-lsp
+Version: 1.0.0
+Summary: Robot Framework lint for coding agents: robocop rules, an LSP server and an auto-fix hook
+Author: Abdulwahab Isam
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/ai94iq/robotframework-lint-lsp
+Project-URL: Documentation, https://github.com/ai94iq/robotframework-lint-lsp/blob/main/docs/agents.md
+Project-URL: Issues, https://github.com/ai94iq/robotframework-lint-lsp/issues
+Keywords: robotframework,robocop,lint,lsp,claude-code
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Framework :: Robot Framework
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: robotframework==7.5.1
+Requires-Dist: robotframework-robocop==9.4.0
+Requires-Dist: pygls==2.1.1
+Provides-Extra: dev
+Requires-Dist: pytest==9.2.0; extra == "dev"
+Dynamic: license-file
+
+# robotframework-lint-lsp
+
+Extra [Robocop](https://github.com/MarketSquare/robotframework-robocop) rules
+for Robot Framework 7.5. When Robocop and the Robot Framework docs disagree,
+these rules follow Robot Framework.
+
+## Install
+
+```bash
+python -m venv .venv
+.venv/Scripts/python -m pip install -e ".[dev]"   # Windows
+.venv/bin/python -m pip install -e ".[dev]"       # Linux, macOS
+```
+
+Pinned: robotframework 7.5.1, robotframework-robocop 9.4.0, pytest 9.2.0.
+
+## Run
+
+```bash
+robocop check --custom-rules robotframework_lint path/to/tests
+```
+
+The installed package registers the `robotframework_lint` Robocop plugin, so
+the rules load by plugin name, no path needed. Run only these rules with
+`--select RFL001 --select RFL002`.
+
+## Rules
+
+| ID | Name | Source |
+|---|---|---|
+| RFL001 | for-in-zip-without-mode | [RF 7.0 release notes](https://github.com/robotframework/robotframework/blob/master/doc/releasenotes/rf-7.0.rst) |
+| RFL002 | deprecated-standard-library (Telnet) | [RF 7.5 release notes](https://github.com/robotframework/robotframework/blob/master/doc/releasenotes/rf-7.5.rst) |
+| RFL003 | deprecated-tag-pattern (`XORY`, `&`) | [RF 7.5 release notes](https://github.com/robotframework/robotframework/blob/master/doc/releasenotes/rf-7.5.rst) |
+| RFL004 | deprecated-translation (French `Unités de test`, Finnish `Tagit`) | [RF 7.5 release notes](https://github.com/robotframework/robotframework/blob/master/doc/releasenotes/rf-7.5.rst) |
+| RFL005 | doc-tags-without-empty-row (`Tags:` in keyword docs) | [RF 7.5 release notes](https://github.com/robotframework/robotframework/blob/master/doc/releasenotes/rf-7.5.rst) |
+| RFL006 | deprecated-argument-name (`list_=`, `time_=`) | [RF 7.5 release notes](https://github.com/robotframework/robotframework/blob/master/doc/releasenotes/rf-7.5.rst) |
+
+RFL003 asks Robot Framework's own `TagPatterns` whether a pattern is deprecated,
+so it reports exactly what RF 7.5.1 warns about. That includes all-caps tags
+holding an operator word, such as `-DONOTX` or `-ORANGE`: RF reads them as
+`DO NOT X` and `OR ANGE`. Write such tags in lower case.
+
+RFL004 reads the deprecated terms from Robot Framework's own language
+definitions. It reports a term only when RF parsed it as a header or setting,
+that is, when the file's language is French or Finnish (`language: fr` or
+`language: fi` in the file, or `--language`).
+
+## LSP server (Claude Code and other agents)
+
+`robotframework-lint-lsp` is a stdio language server. It lints the open
+buffer in process with the robocop defaults plus these rules, on open, save
+and change (debounced 0.4 s). Output is kept small for AI agents:
+
+- one line per finding: `RULEID message`, at most 120 characters
+- at most 20 findings per file (`maxDiagnostics`), then one `overflow` line
+  that says how many more were cut
+- at most 50 symbols or references per answer
+- warnings and errors only by default (`minSeverity`: info, warning, error)
+- identical findings on one line reported once; no related information
+
+- a finding robocop can fix ends with `fix all: <command>`; fixable Info
+  rules are raised to warning
+
+Settings go in `initializationOptions`: `maxDiagnostics`, `minSeverity`,
+`select`, `ignore`, `groupFindings` (default off). For Claude Code, copy
+`.lsp.json` from this repo into your plugin; it maps `.robot` and
+`.resource` to `robotframework`.
+
+The plugin also ships a PostToolUse hook, `robotframework-lint-autofix`
+(`hooks/hooks.json`): after each Edit or Write of a `.robot` or `.resource`
+file it applies robocop's safe fixes, so the agent only sees what is left.
+
+Setup for Claude Code, opencode, Crush, Codex and GLM:
+[docs/agents.md](docs/agents.md). Measured results (cost, turns and issues
+left, with and without the LSP, per model):
+[docs/benchmarks.html](docs/benchmarks.html)
+and [docs/benchmarks](docs/benchmarks).
+
+The server also answers code navigation for user keywords:
+
+- document symbols: tests, keywords and variables in a file
+- definition and references: matched the way Robot matches names, so
+  `say_hello` finds `Say Hello`
+- workspace symbols: find a keyword by name, exact matches first, then
+  prefix, then substring
+- hover: the keyword signature and the first doc line, at most 200 characters
+
+On start it indexes every `.robot` and `.resource` file under the workspace
+root, up to 2000 files. It skips `.git`, `.venv`, `node_modules` and
+`results`. Open files are indexed again on every change. Library keywords
+such as `Log` and keywords with embedded arguments aren't indexed.
+
+## Tests
+
+```bash
+python -m pytest
+```
+
+## License
+
+MIT

robotframework_lint_lsp-1.0.0/README.md

@@ -0,0 +1,101 @@
+# robotframework-lint-lsp
+
+Extra [Robocop](https://github.com/MarketSquare/robotframework-robocop) rules
+for Robot Framework 7.5. When Robocop and the Robot Framework docs disagree,
+these rules follow Robot Framework.
+
+## Install
+
+```bash
+python -m venv .venv
+.venv/Scripts/python -m pip install -e ".[dev]"   # Windows
+.venv/bin/python -m pip install -e ".[dev]"       # Linux, macOS
+```
+
+Pinned: robotframework 7.5.1, robotframework-robocop 9.4.0, pytest 9.2.0.
+
+## Run
+
+```bash
+robocop check --custom-rules robotframework_lint path/to/tests
+```
+
+The installed package registers the `robotframework_lint` Robocop plugin, so
+the rules load by plugin name, no path needed. Run only these rules with
+`--select RFL001 --select RFL002`.
+
+## Rules
+
+| ID | Name | Source |
+|---|---|---|
+| RFL001 | for-in-zip-without-mode | [RF 7.0 release notes](https://github.com/robotframework/robotframework/blob/master/doc/releasenotes/rf-7.0.rst) |
+| RFL002 | deprecated-standard-library (Telnet) | [RF 7.5 release notes](https://github.com/robotframework/robotframework/blob/master/doc/releasenotes/rf-7.5.rst) |
+| RFL003 | deprecated-tag-pattern (`XORY`, `&`) | [RF 7.5 release notes](https://github.com/robotframework/robotframework/blob/master/doc/releasenotes/rf-7.5.rst) |
+| RFL004 | deprecated-translation (French `Unités de test`, Finnish `Tagit`) | [RF 7.5 release notes](https://github.com/robotframework/robotframework/blob/master/doc/releasenotes/rf-7.5.rst) |
+| RFL005 | doc-tags-without-empty-row (`Tags:` in keyword docs) | [RF 7.5 release notes](https://github.com/robotframework/robotframework/blob/master/doc/releasenotes/rf-7.5.rst) |
+| RFL006 | deprecated-argument-name (`list_=`, `time_=`) | [RF 7.5 release notes](https://github.com/robotframework/robotframework/blob/master/doc/releasenotes/rf-7.5.rst) |
+
+RFL003 asks Robot Framework's own `TagPatterns` whether a pattern is deprecated,
+so it reports exactly what RF 7.5.1 warns about. That includes all-caps tags
+holding an operator word, such as `-DONOTX` or `-ORANGE`: RF reads them as
+`DO NOT X` and `OR ANGE`. Write such tags in lower case.
+
+RFL004 reads the deprecated terms from Robot Framework's own language
+definitions. It reports a term only when RF parsed it as a header or setting,
+that is, when the file's language is French or Finnish (`language: fr` or
+`language: fi` in the file, or `--language`).
+
+## LSP server (Claude Code and other agents)
+
+`robotframework-lint-lsp` is a stdio language server. It lints the open
+buffer in process with the robocop defaults plus these rules, on open, save
+and change (debounced 0.4 s). Output is kept small for AI agents:
+
+- one line per finding: `RULEID message`, at most 120 characters
+- at most 20 findings per file (`maxDiagnostics`), then one `overflow` line
+  that says how many more were cut
+- at most 50 symbols or references per answer
+- warnings and errors only by default (`minSeverity`: info, warning, error)
+- identical findings on one line reported once; no related information
+
+- a finding robocop can fix ends with `fix all: <command>`; fixable Info
+  rules are raised to warning
+
+Settings go in `initializationOptions`: `maxDiagnostics`, `minSeverity`,
+`select`, `ignore`, `groupFindings` (default off). For Claude Code, copy
+`.lsp.json` from this repo into your plugin; it maps `.robot` and
+`.resource` to `robotframework`.
+
+The plugin also ships a PostToolUse hook, `robotframework-lint-autofix`
+(`hooks/hooks.json`): after each Edit or Write of a `.robot` or `.resource`
+file it applies robocop's safe fixes, so the agent only sees what is left.
+
+Setup for Claude Code, opencode, Crush, Codex and GLM:
+[docs/agents.md](docs/agents.md). Measured results (cost, turns and issues
+left, with and without the LSP, per model):
+[docs/benchmarks.html](docs/benchmarks.html)
+and [docs/benchmarks](docs/benchmarks).
+
+The server also answers code navigation for user keywords:
+
+- document symbols: tests, keywords and variables in a file
+- definition and references: matched the way Robot matches names, so
+  `say_hello` finds `Say Hello`
+- workspace symbols: find a keyword by name, exact matches first, then
+  prefix, then substring
+- hover: the keyword signature and the first doc line, at most 200 characters
+
+On start it indexes every `.robot` and `.resource` file under the workspace
+root, up to 2000 files. It skips `.git`, `.venv`, `node_modules` and
+`results`. Open files are indexed again on every change. Library keywords
+such as `Log` and keywords with embedded arguments aren't indexed.
+
+## Tests
+
+```bash
+python -m pytest
+```
+
+## License
+
+MIT

robotframework_lint_lsp-1.0.0/pyproject.toml

@@ -0,0 +1,50 @@
+[build-system]
+requires = ["setuptools>=69,<85"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "robotframework-lint-lsp"
+version = "1.0.0"
+description = "Robot Framework lint for coding agents: robocop rules, an LSP server and an auto-fix hook"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [{ name = "Abdulwahab Isam" }]
+keywords = ["robotframework", "robocop", "lint", "lsp", "claude-code"]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Framework :: Robot Framework",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Topic :: Software Development :: Quality Assurance",
+    "Topic :: Software Development :: Testing",
+]
+dependencies = [
+    "robotframework==7.5.1",
+    "robotframework-robocop==9.4.0",
+    "pygls==2.1.1",
+]
+
+[project.urls]
+Homepage = "https://github.com/ai94iq/robotframework-lint-lsp"
+Documentation = "https://github.com/ai94iq/robotframework-lint-lsp/blob/main/docs/agents.md"
+Issues = "https://github.com/ai94iq/robotframework-lint-lsp/issues"
+
+[project.optional-dependencies]
+dev = ["pytest==9.2.0"]
+
+[project.scripts]
+robotframework-lint-lsp = "robotframework_lint.lsp:main"
+robotframework-lint-autofix = "robotframework_lint.autofix:main"
+
+[project.entry-points."robocop.plugins"]
+robotframework_lint = "robotframework_lint.rules"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.robocop.lint]
+custom_rules = ["src/robotframework_lint/rules"]

robotframework_lint_lsp-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

robotframework_lint_lsp-1.0.0/src/robotframework_lint/__init__.py

@@ -0,0 +1,3 @@
+"""Robocop rule pack for Robot Framework."""
+
+__version__ = "0.1.0"

robotframework_lint_lsp-1.0.0/src/robotframework_lint/autofix.py

@@ -0,0 +1,63 @@
+"""PostToolUse hook: apply safe robocop fixes to a Robot file right after an agent edits it.
+
+A/B runs showed agents read "fix all: <command>" hints but never ran them, so the
+fixable findings stayed. Fixing here costs the agent no turns. Silent by design:
+the LSP push reports whatever is left.
+"""
+
+from __future__ import annotations
+
+import json
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+
+from .hints import FIX_COMMANDS
+
+ROBOT_SUFFIXES = {".robot", ".resource"}
+# Two robocop runs must finish inside the hook's 120 s budget.
+TIMEOUT_S = 50
+
+
+def fix_file(path: Path) -> None:
+    # -I: the hook runs inside the edited repo, which must not shadow robocop with its own module.
+    robocop = [sys.executable, "-I", "-m", "robocop"]
+    check_rules = [rule for rule, cmd in FIX_COMMANDS.items() if cmd.startswith("robocop check")]
+    selects = [arg for rule in check_rules for arg in ("--select", rule)]
+    original = path.read_text(encoding="utf-8", newline="")
+    # A temp copy keeps robocop from reading the repo's config, which can name Python rule files.
+    with tempfile.TemporaryDirectory() as tmp:
+        copy = Path(tmp) / f"buffer{path.suffix}"
+        copy.write_text(original, encoding="utf-8", newline="")
+        # TMPDIR can sit under a folder with its own robocop config; an explicit empty one wins.
+        config = Path(tmp) / "robocop.toml"
+        config.write_text("", encoding="utf-8")
+        # Argument lists, never a shell: the path comes from the hook payload.
+        for args in (["format", "--select", "ReplaceWithVAR", "--silent"], ["check", "--fix", *selects]):
+            subprocess.run([*robocop, *args, "--config", str(config), "--root", tmp, "--", str(copy)], cwd=tmp,
+                           capture_output=True, timeout=TIMEOUT_S, check=False)
+        fixed = copy.read_text(encoding="utf-8")  # robocop writes the OS line ending
+    if "\r\n" in original:
+        fixed = fixed.replace("\n", "\r\n")
+    # The agent may have written again while robocop ran; never overwrite the newer text.
+    if fixed != original and path.read_text(encoding="utf-8", newline="") == original:
+        path.write_text(fixed, encoding="utf-8", newline="")
+
+
+def main() -> int:
+    try:
+        payload = json.loads(sys.stdin.read())
+        path = Path(payload["tool_input"]["file_path"])
+    except (ValueError, KeyError, TypeError):
+        return 0
+    if path.suffix.lower() in ROBOT_SUFFIXES and path.is_file():
+        try:
+            fix_file(path)
+        except (OSError, ValueError, subprocess.TimeoutExpired):
+            pass  # a failed fix must never block the agent's edit
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

robotframework_lint_lsp-1.0.0/src/robotframework_lint/hints.py

@@ -0,0 +1,24 @@
+"""One-line fix hints for the findings agents most often left unfixed.
+
+Robocop has no auto-fix for these, and agents without a hint spent extra
+edit rounds guessing the modern form or left the finding in place.
+"""
+
+# One shell command fixes every finding of the rule in the file (checked on robocop 9.4.0).
+FIX_COMMANDS = {
+    "DEPR05": "robocop format --select ReplaceWithVAR <file>",
+    "DEPR06": "robocop format --select ReplaceWithVAR <file>",
+    **{rule: f"robocop check --fix --select {rule} <file>"
+       for rule in ("DEPR03", "DEPR04", "DEPR07", "DEPR08", "DEPR09", "DEPR10", "DEPR11",
+                    "MISC04", "MISC09", "VAR01")},
+}
+
+FIX_HINTS = {
+    "MISC09": "use inline IF: IF    cond    Keyword    ELSE    Keyword",
+    "SPC03": "use exactly 2 empty lines between sections",
+    "VAR02": "drop the assignment or use the variable",
+    "VAR05": "pass the value as an argument or RETURN it",
+    "VAR06": "pass the value as an argument or RETURN it",
+    "VAR10": "spell the variable the same way everywhere",
+    "MISC04": "use one assignment style in the file",
+}

robotframework_lint_lsp-1.0.0/src/robotframework_lint/lsp.py

@@ -0,0 +1,237 @@
+"""Minimal LSP server: robocop defaults plus our rules, token-cheap diagnostics.
+
+Token controls: one short line per finding ("RULEID message", capped length),
+a per-file cap, a severity floor, dedup of identical findings, and no related
+information, code descriptions or data payloads.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import tempfile
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from lsprotocol import types
+from pygls.lsp.server import LanguageServer
+
+from .hints import FIX_COMMANDS, FIX_HINTS
+from .lsp_navigation import register as register_navigation
+from .lsp_navigation import scan_workspace
+from .navigation import WorkspaceIndex
+
+RULES_DIR = Path(__file__).parent / "rules"
+MAX_MESSAGE = 120
+MAX_LINT_BYTES = 1_000_000
+DEBOUNCE_SECONDS = 0.4
+SEVERITY_ORDER = {"info": 0, "warning": 1, "error": 2}
+LSP_SEVERITY = {
+    "info": types.DiagnosticSeverity.Information,
+    "warning": types.DiagnosticSeverity.Warning,
+    "error": types.DiagnosticSeverity.Error,
+}
+MAX_GROUP_LINES = 6
+
+
+@dataclass
+class Settings:
+    max_diagnostics: int = 20
+    min_severity: str = "warning"
+    select: list[str] = field(default_factory=list)
+    ignore: list[str] = field(default_factory=list)
+    group: bool = False  # v4 A/B: grouped findings left more DEPR05/06 unfixed
+
+    @classmethod
+    def from_options(cls, options: object) -> Settings:
+        opts = options if isinstance(options, dict) else {}
+        severity = str(opts.get("minSeverity", "warning")).lower()
+        if severity not in SEVERITY_ORDER:
+            severity = "warning"
+        cap = opts.get("maxDiagnostics", 20)
+        cap = cap if isinstance(cap, int) and cap > 0 else 20
+        group = opts.get("groupFindings", False) is True
+        return cls(cap, severity, _str_list(opts.get("select")), _str_list(opts.get("ignore")), group)
+
+
+def _str_list(value: object) -> list[str]:
+    return [str(v) for v in value] if isinstance(value, list) else []
+
+
+def _severity_name(robocop_severity: object) -> str:
+    letter = getattr(robocop_severity, "value", "W")
+    return {"I": "info", "W": "warning", "E": "error"}.get(letter, "warning")
+
+
+def _run_robocop(text: str, suffix: str, settings: Settings) -> list:
+    from robocop.config.manager import ConfigManager
+    from robocop.config.schema import RawConfig, RawLinterConfig
+    from robocop.linter.rules import RuleSeverity
+    from robocop.linter.runner import RobocopLinter
+    from robocop.source_file import SourceFile
+
+    with tempfile.TemporaryDirectory() as tmp:
+        path = Path(tmp) / f"buffer{suffix}"
+        path.write_text(text, encoding="utf-8")
+        linter_config = RawLinterConfig(
+            select=settings.select or None,
+            ignore=settings.ignore or None,
+            threshold=RuleSeverity("I"),  # floor applied after promotion in lint_text
+            custom_rules=[str(RULES_DIR)],
+            return_result=True,
+        )
+        config = RawConfig(sources=[str(path)], linter=linter_config, silent=True)
+        # A robocop or pyproject file above the temp dir must not pick rules or rule files.
+        manager = ConfigManager(sources=[str(path)], root=Path(tmp), ignore_file_config=True,
+                                overwrite_config=config)
+        linter = RobocopLinter(manager)
+        return list(linter.run_check(SourceFile(path=path, config=manager.default_config)))
+
+
+def lint_text(text: str, settings: Settings, suffix: str = ".robot") -> list[types.Diagnostic]:
+    """Lint a buffer and return capped, filtered, deduplicated LSP diagnostics."""
+    floor = SEVERITY_ORDER[settings.min_severity]
+    seen: set[tuple[int, str, str]] = set()
+    groups: dict[str, list[tuple]] = {}
+    found = sorted(_run_robocop(text, suffix, settings), key=lambda d: (d.range.start.line, d.range.start.character))
+    for diag in found:
+        rule_id = diag.rule.rule_id
+        severity = _severity_name(diag.severity)
+        # Promote only Info rules one command fixes; each promoted finding costs agents an edit turn.
+        if severity == "info" and rule_id in FIX_COMMANDS:
+            severity = "warning"
+        if SEVERITY_ORDER[severity] < floor:
+            continue
+        line = max(diag.range.start.line - 1, 0)
+        key = (line, rule_id, diag.message)
+        if key in seen:
+            continue
+        seen.add(key)
+        group_key = rule_id if settings.group else f"{rule_id}:{len(seen)}"
+        groups.setdefault(group_key, []).append((diag, rule_id, line, severity))
+    result = [_group_to_lsp(members) for members in groups.values()]
+    result.sort(key=lambda d: (d.range.start.line, d.range.start.character))
+    if len(result) <= settings.max_diagnostics:
+        return result
+    return result[: settings.max_diagnostics] + [_overflow(len(result) - settings.max_diagnostics, settings)]
+
+
+def _overflow(hidden: int, settings: Settings) -> types.Diagnostic:
+    # Without it an agent can't tell a clean tail from a truncated one.
+    return types.Diagnostic(
+        range=types.Range(types.Position(0, 0), types.Position(0, 0)),
+        message=f"overflow {hidden} more findings not shown (maxDiagnostics {settings.max_diagnostics})",
+        severity=types.DiagnosticSeverity.Information,
+        code="overflow",
+        source="rflint",
+    )
+
+
+def _group_to_lsp(members: list[tuple]) -> types.Diagnostic:
+    """One diagnostic per rule, anchored at its first finding, with the worst severity."""
+    diag, rule_id, line, _ = members[0]
+    severity = max((m[3] for m in members), key=SEVERITY_ORDER.__getitem__)
+    count = ""
+    if len(members) > 1:
+        lines = [str(m[2] + 1) for m in members[:MAX_GROUP_LINES]]
+        more = ",..." if len(members) > MAX_GROUP_LINES else ""
+        count = f"x{len(members)} (lines {','.join(lines)}{more}) "
+    return _to_lsp(diag, rule_id, line, severity, count)
+
+
+def _to_lsp(diag, rule_id: str, line: int, severity: str, count: str = "") -> types.Diagnostic:
+    start_col = max(diag.range.start.character - 1, 0)
+    end_line = max(diag.range.end.line - 1, line)
+    end_col = max(diag.range.end.character - 1, 0)
+    command = FIX_COMMANDS.get(rule_id)
+    hint = f"fix all: {command}" if command else FIX_HINTS.get(rule_id)
+    suffix = f"; {hint}" if hint else ""
+    base = f"{rule_id} {count}{diag.message}"
+    room = MAX_MESSAGE - len(suffix)
+    if len(base) > room:
+        base = base[: room - 3] + "..."
+    message = base + suffix
+    return types.Diagnostic(
+        range=types.Range(types.Position(line, start_col), types.Position(end_line, end_col)),
+        message=message,
+        severity=LSP_SEVERITY[severity],
+        code=rule_id,
+        source="rflint",
+    )
+
+
+class RflintServer(LanguageServer):
+    def __init__(self) -> None:
+        super().__init__("robotframework-lint-lsp", "0.1.0")
+        self.settings = Settings()
+        self.pending: dict[str, asyncio.Task] = {}
+        self.index = WorkspaceIndex()
+
+    def publish(self, uri: str) -> None:
+        doc = self.workspace.get_text_document(uri)
+        suffix = ".resource" if uri.endswith(".resource") else ".robot"
+        if len(doc.source) > MAX_LINT_BYTES:  # a generated blob would hold the event loop
+            self.text_document_publish_diagnostics(
+                types.PublishDiagnosticsParams(uri=uri, version=doc.version, diagnostics=[]))
+            return
+        try:
+            self.index.update(uri, doc.source)
+            diagnostics = lint_text(doc.source, self.settings, suffix)
+            for diag in diagnostics:  # robocop columns are code points
+                diag.range = self.workspace.position_codec.range_to_client_units(doc.lines, diag.range)
+        except Exception as exc:  # parse errors must not kill the server
+            self.window_log_message(types.LogMessageParams(types.MessageType.Warning, f"rflint: {exc}"[:200]))
+            diagnostics = []
+        self.text_document_publish_diagnostics(
+            types.PublishDiagnosticsParams(uri=uri, version=doc.version, diagnostics=diagnostics)
+        )
+
+
+server = RflintServer()
+register_navigation(server)
+
+
+@server.feature(types.INITIALIZE)
+def on_initialize(ls: RflintServer, params: types.InitializeParams) -> None:
+    ls.settings = Settings.from_options(params.initialization_options)
+    scan_workspace(ls.index, params.root_uri)
+
+
+@server.feature(types.TEXT_DOCUMENT_DID_OPEN)
+def on_open(ls: RflintServer, params: types.DidOpenTextDocumentParams) -> None:
+    ls.publish(params.text_document.uri)
+
+
+@server.feature(types.TEXT_DOCUMENT_DID_SAVE)
+def on_save(ls: RflintServer, params: types.DidSaveTextDocumentParams) -> None:
+    ls.publish(params.text_document.uri)
+
+
+@server.feature(types.TEXT_DOCUMENT_DID_CHANGE)
+async def on_change(ls: RflintServer, params: types.DidChangeTextDocumentParams) -> None:
+    uri = params.text_document.uri
+    previous = ls.pending.pop(uri, None)
+    if previous:
+        previous.cancel()
+
+    async def later() -> None:
+        await asyncio.sleep(DEBOUNCE_SECONDS)
+        ls.pending.pop(uri, None)
+        ls.publish(uri)
+
+    ls.pending[uri] = asyncio.ensure_future(later())
+
+
+@server.feature(types.TEXT_DOCUMENT_DID_CLOSE)
+def on_close(ls: RflintServer, params: types.DidCloseTextDocumentParams) -> None:
+    pending = ls.pending.pop(params.text_document.uri, None)
+    if pending:
+        pending.cancel()  # a late publish would bring back diagnostics for a closed file
+    ls.text_document_publish_diagnostics(types.PublishDiagnosticsParams(uri=params.text_document.uri, diagnostics=[]))
+
+
+def main() -> None:
+    server.start_io()
+
+
+if __name__ == "__main__":
+    main()