robotframework-plugins 2026.11.0.dev1__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (195) hide show
  1. robotframework_plugins/__init__.py +14 -0
  2. robotframework_plugins/_assets/catalog.json +143 -0
  3. robotframework_plugins/_assets/plugins/rf-agentskills/.claude-plugin/plugin.json +25 -0
  4. robotframework_plugins/_assets/plugins/rf-agentskills/CHANGELOG.md +198 -0
  5. robotframework_plugins/_assets/plugins/rf-agentskills/README.md +27 -0
  6. robotframework_plugins/_assets/plugins/rf-agentskills/catalog.yaml +25 -0
  7. robotframework_plugins/_assets/plugins/rf-api/.claude-plugin/plugin.json +25 -0
  8. robotframework_plugins/_assets/plugins/rf-api/CHANGELOG.md +9 -0
  9. robotframework_plugins/_assets/plugins/rf-api/README.md +27 -0
  10. robotframework_plugins/_assets/plugins/rf-api/catalog.yaml +27 -0
  11. robotframework_plugins/_assets/plugins/rf-api/skills/rf-requests/SKILL.md +110 -0
  12. robotframework_plugins/_assets/plugins/rf-api/skills/rf-requests/assets/examples/authentication-patterns.robot +39 -0
  13. robotframework_plugins/_assets/plugins/rf-api/skills/rf-requests/assets/examples/basic-crud.robot +46 -0
  14. robotframework_plugins/_assets/plugins/rf-api/skills/rf-requests/assets/examples/file-upload.robot +28 -0
  15. robotframework_plugins/_assets/plugins/rf-api/skills/rf-requests/assets/examples/session-handling.robot +48 -0
  16. robotframework_plugins/_assets/plugins/rf-api/skills/rf-requests/references/authentication.md +58 -0
  17. robotframework_plugins/_assets/plugins/rf-api/skills/rf-requests/references/install.md +10 -0
  18. robotframework_plugins/_assets/plugins/rf-api/skills/rf-requests/references/request-options.md +90 -0
  19. robotframework_plugins/_assets/plugins/rf-api/skills/rf-requests/references/response-validation.md +64 -0
  20. robotframework_plugins/_assets/plugins/rf-api/skills/rf-requests/references/troubleshooting.md +64 -0
  21. robotframework_plugins/_assets/plugins/rf-api/skills/rf-restinstance/SKILL.md +119 -0
  22. robotframework_plugins/_assets/plugins/rf-api/skills/rf-restinstance/assets/examples/basic-rest.robot +51 -0
  23. robotframework_plugins/_assets/plugins/rf-api/skills/rf-restinstance/assets/examples/schema-validation.robot +38 -0
  24. robotframework_plugins/_assets/plugins/rf-api/skills/rf-restinstance/assets/examples/schemas/user.json +10 -0
  25. robotframework_plugins/_assets/plugins/rf-api/skills/rf-restinstance/references/authentication.md +61 -0
  26. robotframework_plugins/_assets/plugins/rf-api/skills/rf-restinstance/references/install.md +11 -0
  27. robotframework_plugins/_assets/plugins/rf-api/skills/rf-restinstance/references/json-handling.md +89 -0
  28. robotframework_plugins/_assets/plugins/rf-api/skills/rf-restinstance/references/migrate-from-requests.md +15 -0
  29. robotframework_plugins/_assets/plugins/rf-api/skills/rf-restinstance/references/schema-validation.md +85 -0
  30. robotframework_plugins/_assets/plugins/rf-api/skills/rf-restinstance/references/troubleshooting.md +68 -0
  31. robotframework_plugins/_assets/plugins/rf-core/.claude-plugin/plugin.json +19 -0
  32. robotframework_plugins/_assets/plugins/rf-core/CHANGELOG.md +11 -0
  33. robotframework_plugins/_assets/plugins/rf-core/README.md +38 -0
  34. robotframework_plugins/_assets/plugins/rf-core/agents/rf-debug-expert.md +104 -0
  35. robotframework_plugins/_assets/plugins/rf-core/agents/rf-migration-guide.md +73 -0
  36. robotframework_plugins/_assets/plugins/rf-core/agents/rf-test-architect.md +98 -0
  37. robotframework_plugins/_assets/plugins/rf-core/catalog.yaml +19 -0
  38. robotframework_plugins/_assets/plugins/rf-core/hooks/README.md +435 -0
  39. robotframework_plugins/_assets/plugins/rf-core/hooks/hooks.json +70 -0
  40. robotframework_plugins/_assets/plugins/rf-core/scripts/_hook_input.mjs +101 -0
  41. robotframework_plugins/_assets/plugins/rf-core/scripts/_pending_errors.mjs +65 -0
  42. robotframework_plugins/_assets/plugins/rf-core/scripts/_python_env.mjs +181 -0
  43. robotframework_plugins/_assets/plugins/rf-core/scripts/check_rf_environment.mjs +181 -0
  44. robotframework_plugins/_assets/plugins/rf-core/scripts/maybe_inject_rf_context.mjs +74 -0
  45. robotframework_plugins/_assets/plugins/rf-core/scripts/maybe_remind_robot_tests.mjs +108 -0
  46. robotframework_plugins/_assets/plugins/rf-core/scripts/report_pending_errors.mjs +72 -0
  47. robotframework_plugins/_assets/plugins/rf-core/scripts/rf_error_hints.mjs +126 -0
  48. robotframework_plugins/_assets/plugins/rf-core/scripts/validate_robot.mjs +509 -0
  49. robotframework_plugins/_assets/plugins/rf-core/scripts/validate_robot_project.mjs +103 -0
  50. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/SKILL.md +313 -0
  51. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/resources/api.resource +30 -0
  52. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/resources/calc.resource +23 -0
  53. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/resources/embedded.resource +20 -0
  54. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/resources/keywords.resource +26 -0
  55. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/resources/login.resource +10 -0
  56. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/tests/01__keyword_driven.robot +15 -0
  57. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/tests/02__data_driven.robot +10 -0
  58. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/tests/03__templates.robot +17 -0
  59. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/tests/04__bdd.robot +10 -0
  60. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/tests/05__embedded.robot +13 -0
  61. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/tests/__init__.robot +6 -0
  62. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/tests/api/__init__.robot +7 -0
  63. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/tests/api/users.robot +18 -0
  64. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/tests/env.robot +15 -0
  65. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/variables/common.py +11 -0
  66. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/variables/dev.yaml +3 -0
  67. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/variables/staging.yaml +3 -0
  68. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/references/arguments.md +139 -0
  69. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/references/control-structures.md +175 -0
  70. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/references/embedded-arguments.md +135 -0
  71. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/references/migration.md +90 -0
  72. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/references/resources-and-variable-files.md +127 -0
  73. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/references/styles.md +92 -0
  74. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/references/suites-and-init.md +96 -0
  75. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/references/tags-and-selection.md +104 -0
  76. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/references/templates.md +124 -0
  77. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/references/variables-and-scopes.md +129 -0
  78. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/scripts/rf_conventions.py +883 -0
  79. robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/SKILL.md +216 -0
  80. robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/assets/examples/ExampleLibrary.py +61 -0
  81. robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/assets/examples/ResultListener.py +60 -0
  82. robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/assets/examples/converters.py +48 -0
  83. robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/assets/examples/converters.robot +20 -0
  84. robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/assets/examples/example_library.robot +31 -0
  85. robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/assets/examples/listener.robot +12 -0
  86. robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/references/api-variants.md +291 -0
  87. robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/references/communication.md +248 -0
  88. robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/references/conversion.md +347 -0
  89. robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/references/listeners.md +150 -0
  90. robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/references/packaging-and-docs.md +155 -0
  91. robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/scripts/check_library.py +842 -0
  92. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/SKILL.md +159 -0
  93. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/assets/examples/github-actions-robot.yml +32 -0
  94. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/assets/examples/gitignore.txt +22 -0
  95. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/assets/examples/pyproject.poetry.toml +28 -0
  96. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/assets/examples/pyproject.uv.toml +20 -0
  97. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/assets/examples/requirements.txt +9 -0
  98. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/assets/examples/robot.toml +16 -0
  99. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/assets/examples/smoke.robot +22 -0
  100. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/references/ci.md +61 -0
  101. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/references/cli-tools.md +33 -0
  102. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/references/libraries.md +47 -0
  103. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/references/poetry.md +77 -0
  104. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/references/project-layout.md +86 -0
  105. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/references/troubleshooting.md +73 -0
  106. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/references/uv.md +108 -0
  107. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/references/venv-pip.md +71 -0
  108. robotframework_plugins/_assets/plugins/rf-core/variants/codex/agents/rf-debug-expert.toml +103 -0
  109. robotframework_plugins/_assets/plugins/rf-core/variants/codex/agents/rf-migration-guide.toml +72 -0
  110. robotframework_plugins/_assets/plugins/rf-core/variants/codex/agents/rf-test-architect.toml +97 -0
  111. robotframework_plugins/_assets/plugins/rf-core/variants/opencode/agents/rf-debug-expert.md +107 -0
  112. robotframework_plugins/_assets/plugins/rf-core/variants/opencode/agents/rf-migration-guide.md +76 -0
  113. robotframework_plugins/_assets/plugins/rf-core/variants/opencode/agents/rf-test-architect.md +101 -0
  114. robotframework_plugins/_assets/plugins/rf-core/variants/opencode/plugins/rf-core.js +93 -0
  115. robotframework_plugins/_assets/plugins/rf-desktop/.claude-plugin/plugin.json +24 -0
  116. robotframework_plugins/_assets/plugins/rf-desktop/CHANGELOG.md +9 -0
  117. robotframework_plugins/_assets/plugins/rf-desktop/README.md +26 -0
  118. robotframework_plugins/_assets/plugins/rf-desktop/catalog.yaml +23 -0
  119. robotframework_plugins/_assets/plugins/rf-desktop/skills/rf-platynui/SKILL.md +266 -0
  120. robotframework_plugins/_assets/plugins/rf-desktop/skills/rf-platynui/assets/examples/calculator.robot +45 -0
  121. robotframework_plugins/_assets/plugins/rf-desktop/skills/rf-platynui/assets/examples/mock-deterministic.robot +33 -0
  122. robotframework_plugins/_assets/plugins/rf-desktop/skills/rf-platynui/references/cli-and-inspector.md +82 -0
  123. robotframework_plugins/_assets/plugins/rf-desktop/skills/rf-platynui/references/install.md +14 -0
  124. robotframework_plugins/_assets/plugins/rf-desktop/skills/rf-platynui/references/keywords-reference.md +102 -0
  125. robotframework_plugins/_assets/plugins/rf-desktop/skills/rf-platynui/references/locators-and-queries.md +95 -0
  126. robotframework_plugins/_assets/plugins/rf-desktop/skills/rf-platynui/references/platform-setup.md +65 -0
  127. robotframework_plugins/_assets/plugins/rf-desktop/skills/rf-platynui/references/status-and-migration.md +41 -0
  128. robotframework_plugins/_assets/plugins/rf-mobile/.claude-plugin/plugin.json +24 -0
  129. robotframework_plugins/_assets/plugins/rf-mobile/CHANGELOG.md +9 -0
  130. robotframework_plugins/_assets/plugins/rf-mobile/README.md +26 -0
  131. robotframework_plugins/_assets/plugins/rf-mobile/catalog.yaml +23 -0
  132. robotframework_plugins/_assets/plugins/rf-mobile/skills/rf-appium/SKILL.md +134 -0
  133. robotframework_plugins/_assets/plugins/rf-mobile/skills/rf-appium/assets/examples/android-basic.robot +60 -0
  134. robotframework_plugins/_assets/plugins/rf-mobile/skills/rf-appium/assets/examples/gestures-example.robot +59 -0
  135. robotframework_plugins/_assets/plugins/rf-mobile/skills/rf-appium/assets/examples/hybrid-app.robot +54 -0
  136. robotframework_plugins/_assets/plugins/rf-mobile/skills/rf-appium/assets/examples/ios-basic.robot +48 -0
  137. robotframework_plugins/_assets/plugins/rf-mobile/skills/rf-appium/references/capabilities.md +117 -0
  138. robotframework_plugins/_assets/plugins/rf-mobile/skills/rf-appium/references/gestures-touch.md +84 -0
  139. robotframework_plugins/_assets/plugins/rf-mobile/skills/rf-appium/references/install.md +21 -0
  140. robotframework_plugins/_assets/plugins/rf-mobile/skills/rf-appium/references/locators-mobile.md +74 -0
  141. robotframework_plugins/_assets/plugins/rf-mobile/skills/rf-appium/references/platform-specific.md +105 -0
  142. robotframework_plugins/_assets/plugins/rf-mobile/skills/rf-appium/references/troubleshooting.md +70 -0
  143. robotframework_plugins/_assets/plugins/rf-web/.claude-plugin/plugin.json +25 -0
  144. robotframework_plugins/_assets/plugins/rf-web/CHANGELOG.md +9 -0
  145. robotframework_plugins/_assets/plugins/rf-web/README.md +27 -0
  146. robotframework_plugins/_assets/plugins/rf-web/catalog.yaml +27 -0
  147. robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/SKILL.md +132 -0
  148. robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/assets/examples/authentication-flow.robot +34 -0
  149. robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/assets/examples/basic-web-test.robot +29 -0
  150. robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/assets/examples/form-handling.robot +49 -0
  151. robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/assets/examples/iframe-shadow-dom.robot +31 -0
  152. robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/references/assertion-engine.md +79 -0
  153. robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/references/authentication-storage.md +86 -0
  154. robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/references/browser-context-page.md +110 -0
  155. robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/references/downloads-uploads.md +51 -0
  156. robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/references/iframes-shadow-dom.md +67 -0
  157. robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/references/install.md +67 -0
  158. robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/references/locators.md +83 -0
  159. robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/references/migrate-from-selenium.md +22 -0
  160. robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/references/troubleshooting.md +100 -0
  161. robotframework_plugins/_assets/plugins/rf-web/skills/rf-selenium/SKILL.md +123 -0
  162. robotframework_plugins/_assets/plugins/rf-web/skills/rf-selenium/assets/examples/basic-web-test.robot +64 -0
  163. robotframework_plugins/_assets/plugins/rf-web/skills/rf-selenium/assets/examples/multi-window.robot +55 -0
  164. robotframework_plugins/_assets/plugins/rf-web/skills/rf-selenium/assets/examples/wait-patterns.robot +53 -0
  165. robotframework_plugins/_assets/plugins/rf-web/skills/rf-selenium/references/browser-setup.md +103 -0
  166. robotframework_plugins/_assets/plugins/rf-web/skills/rf-selenium/references/frames-windows.md +84 -0
  167. robotframework_plugins/_assets/plugins/rf-web/skills/rf-selenium/references/install.md +12 -0
  168. robotframework_plugins/_assets/plugins/rf-web/skills/rf-selenium/references/javascript-execution.md +65 -0
  169. robotframework_plugins/_assets/plugins/rf-web/skills/rf-selenium/references/locators.md +86 -0
  170. robotframework_plugins/_assets/plugins/rf-web/skills/rf-selenium/references/troubleshooting.md +122 -0
  171. robotframework_plugins/_assets/plugins/rf-web/skills/rf-selenium/references/waiting-strategies.md +84 -0
  172. robotframework_plugins/_assets.py +120 -0
  173. robotframework_plugins/_catalog.py +123 -0
  174. robotframework_plugins/_snapshot.py +230 -0
  175. robotframework_plugins/adapters/__init__.py +53 -0
  176. robotframework_plugins/adapters/_base.py +400 -0
  177. robotframework_plugins/adapters/claude_code.py +312 -0
  178. robotframework_plugins/adapters/claude_desktop.py +129 -0
  179. robotframework_plugins/adapters/codex.py +276 -0
  180. robotframework_plugins/adapters/copilot.py +87 -0
  181. robotframework_plugins/adapters/cursor.py +295 -0
  182. robotframework_plugins/adapters/goose.py +240 -0
  183. robotframework_plugins/adapters/opencode.py +170 -0
  184. robotframework_plugins/bundle.py +85 -0
  185. robotframework_plugins/cli.py +1311 -0
  186. robotframework_plugins/detect.py +121 -0
  187. robotframework_plugins/manifest.py +338 -0
  188. robotframework_plugins/py.typed +0 -0
  189. robotframework_plugins/skillzip.py +39 -0
  190. robotframework_plugins/transforms.py +725 -0
  191. robotframework_plugins-2026.11.0.dev1.dist-info/METADATA +178 -0
  192. robotframework_plugins-2026.11.0.dev1.dist-info/RECORD +195 -0
  193. robotframework_plugins-2026.11.0.dev1.dist-info/WHEEL +4 -0
  194. robotframework_plugins-2026.11.0.dev1.dist-info/entry_points.txt +2 -0
  195. robotframework_plugins-2026.11.0.dev1.dist-info/licenses/LICENSE +201 -0
@@ -0,0 +1,883 @@
1
+ #!/usr/bin/env python3
2
+ # /// script
3
+ # requires-python = ">=3.8"
4
+ # dependencies = ["robotframework>=7"]
5
+ # ///
6
+ """Robot Framework project convention detector for the rf-language skill.
7
+
8
+ Scans the ``.robot`` and ``.resource`` files under a project directory with the
9
+ Robot Framework parser (``robot.api``) and prints one JSON object
10
+ (``schema: rf-conventions/1``) describing the conventions new code should
11
+ follow: the Robot Framework version and which version-gated features it
12
+ supports, separator and assignment style, keyword naming, embedded and typed
13
+ arguments, BDD and template usage, tags, legacy constructs (with Robocop rule
14
+ ids), resource and variable-file layout and the web library in use.
15
+
16
+ Run it in the project environment:
17
+ ``uv run python scripts/rf_conventions.py <project-dir>``.
18
+
19
+ The script is read-only: it never writes to the project, never imports the
20
+ project's libraries and never executes project code.
21
+
22
+ Top-level keys (always present; undeterminable values are ``null``):
23
+ ``schema, root, rf, scan, style, keywords, calls, tests, variables, legacy,
24
+ layout, libraries, advice``.
25
+
26
+ ``rf.features`` keys (``{min, available}``; ``available`` is ``null`` when the
27
+ effective version is unknown): return_statement (5.0); test_tags,
28
+ keyword_tags, robot_private (6.0); parseinclude, suite_name_setting,
29
+ json_variable_files, mixed_embedded_args (6.1); var_statement, tag_removal,
30
+ test_full_name (7.0); scope_suites, bdd_embedded_prefix (7.1); group,
31
+ embedded_pattern_flags, template_skip_rows (7.2); typed_arguments (7.3);
32
+ secret_type (7.4).
33
+
34
+ Exit codes: 0 ok (also for a directory without Robot Framework files), 1
35
+ internal error, 2 usage, 3 environment (Robot Framework missing or < 7), 4
36
+ path missing or not a directory. stdout carries only the JSON result;
37
+ diagnostics go to stderr as ``error:`` / ``warning:`` / ``hint:`` lines.
38
+ """
39
+ from __future__ import annotations
40
+
41
+ import argparse
42
+ import json
43
+ import os
44
+ import re
45
+ import sys
46
+ import traceback
47
+ from collections import Counter, defaultdict
48
+ from pathlib import Path
49
+ from typing import Any, Dict, Iterator, List, NoReturn, Optional, Tuple
50
+
51
+ # Robot Framework is optional at import time so that --help and usage errors
52
+ # work under any interpreter; _require_robot() enforces it after parsing.
53
+ try:
54
+ from robot.version import VERSION as _RF_VERSION
55
+ except ImportError: # pragma: no cover - exercised via a bare venv
56
+ _RF_VERSION = None
57
+ try:
58
+ from robot.api import Token, get_init_model, get_model, get_resource_model
59
+ from robot.api.parsing import ModelVisitor
60
+ _RF_IMPORT_ERROR: Exception | None = None
61
+ except ImportError as _exc: # pragma: no cover - exercised via a bare venv or an old RF
62
+ Token = None
63
+ get_model = get_resource_model = get_init_model = None
64
+ ModelVisitor = object
65
+ _RF_IMPORT_ERROR = _exc
66
+
67
+ SCHEMA = "rf-conventions/1"
68
+ MIN_RF_MAJOR = 7
69
+ EXIT_OK, EXIT_INTERNAL, EXIT_USAGE, EXIT_ENV, EXIT_INPUT = 0, 1, 2, 3, 4
70
+ DEFAULT_MAX_FILES = 2000
71
+ DEFAULT_MAX_EXAMPLES = 3
72
+ SCRIPT_PATH = os.path.abspath(__file__)
73
+
74
+ SKIP_DIRS = {
75
+ ".git", ".hg", ".svn", ".venv", "venv", "env", "node_modules", "results", "output",
76
+ "__pycache__", ".robotcode_cache", ".robocop_cache", ".tox", ".nox", ".mypy_cache",
77
+ ".pytest_cache", ".ruff_cache", "pabot_results", "dist", "build", "site-packages",
78
+ }
79
+ RESOURCE_DIR_CANDIDATES = ("resources", "keywords", "res")
80
+ VARIABLE_DIRS = ("variables", "resources/variables", "vars")
81
+ VARFILE_EXT = (".py", ".yaml", ".yml", ".json")
82
+ BDD = re.compile(r"^(given|when|then|and|but)\s", re.I)
83
+ CONTROL_NODES = ("For", "While", "If", "Try")
84
+ # The library skill and its plugin (the skill may not be installed).
85
+ WEB_LIBRARIES = {"Browser": "rf-browser (plugin rf-web)", "SeleniumLibrary": "rf-selenium (plugin rf-web)"}
86
+
87
+ #: Version gate: (feature key, minimum version). Mirrors the SKILL.md table.
88
+ FEATURES: List[Tuple[str, Tuple[int, int]]] = [
89
+ ("return_statement", (5, 0)),
90
+ ("test_tags", (6, 0)),
91
+ ("keyword_tags", (6, 0)),
92
+ ("robot_private", (6, 0)),
93
+ ("parseinclude", (6, 1)),
94
+ ("suite_name_setting", (6, 1)),
95
+ ("json_variable_files", (6, 1)),
96
+ ("mixed_embedded_args", (6, 1)),
97
+ ("var_statement", (7, 0)),
98
+ ("tag_removal", (7, 0)),
99
+ ("test_full_name", (7, 0)),
100
+ ("scope_suites", (7, 1)),
101
+ ("bdd_embedded_prefix", (7, 1)),
102
+ ("group", (7, 2)),
103
+ ("embedded_pattern_flags", (7, 2)),
104
+ ("template_skip_rows", (7, 2)),
105
+ ("typed_arguments", (7, 3)),
106
+ ("secret_type", (7, 4)),
107
+ ]
108
+
109
+ #: Legacy keyword calls: normalized name -> (construct, Robocop 9.x rule id or None).
110
+ LEGACY_KEYWORDS: Dict[str, Tuple[str, Optional[str]]] = {
111
+ "runkeywordif": ("Run Keyword If", "DEPR08"),
112
+ "runkeywordunless": ("Run Keyword Unless", "DEPR08"),
113
+ "setvariable": ("Set Variable", "DEPR05"),
114
+ "settestvariable": ("Set Test Variable", "DEPR05"),
115
+ "setsuitevariable": ("Set Suite Variable", "DEPR05"),
116
+ "setglobalvariable": ("Set Global Variable", "DEPR05"),
117
+ "setlocalvariable": ("Set Local Variable", "DEPR05"),
118
+ "createlist": ("Create List", "DEPR06"),
119
+ "createdictionary": ("Create Dictionary", "DEPR06"),
120
+ "exitforloop": ("Exit For Loop", "DEPR09"),
121
+ "exitforloopif": ("Exit For Loop If", "DEPR09"),
122
+ "continueforloop": ("Continue For Loop", "DEPR09"),
123
+ "continueforloopif": ("Continue For Loop If", "DEPR09"),
124
+ "returnfromkeyword": ("Return From Keyword", "DEPR10"),
125
+ "returnfromkeywordif": ("Return From Keyword If", "DEPR10"),
126
+ # Modern forms exist but Robocop 9.1 does not flag these.
127
+ "catenate": ("Catenate", None),
128
+ "setvariableif": ("Set Variable If", None),
129
+ }
130
+ LEGACY_OTHER = {
131
+ "[Return]": "DEPR11",
132
+ "Force Tags": "DEPR07",
133
+ "Default Tags": None,
134
+ "WITH NAME": "DEPR03",
135
+ "singular section header": "DEPR04",
136
+ }
137
+ SINGULAR_HEADERS = {"setting", "variable", "test case", "task", "keyword", "comment"}
138
+
139
+ INPUT_HINT = (
140
+ "pass the project root (the directory holding tests/ and resources/), for example: "
141
+ "uv run python scripts/rf_conventions.py ."
142
+ )
143
+
144
+
145
+ class RobotEnvironmentError(RuntimeError):
146
+ """Robot Framework is missing or too old in the running interpreter."""
147
+
148
+ def __init__(self, message: str, hints: List[str]) -> None:
149
+ super().__init__(message)
150
+ self.hints = list(hints)
151
+
152
+
153
+ class InputError(RuntimeError):
154
+ """The path to scan does not exist or is not a directory."""
155
+
156
+ def __init__(self, message: str, hint: str = INPUT_HINT) -> None:
157
+ super().__init__(message)
158
+ self.hint = hint
159
+
160
+
161
+ def _fail(code: int, error: str, *hints: str) -> NoReturn:
162
+ print(f"error: {error}", file=sys.stderr)
163
+ for hint in hints:
164
+ print(f"hint: {hint}", file=sys.stderr)
165
+ sys.exit(code)
166
+
167
+
168
+ def _warn(message: str) -> None:
169
+ print(f"warning: {message}", file=sys.stderr)
170
+
171
+
172
+ def _require_robot() -> None:
173
+ """Raise RobotEnvironmentError unless Robot Framework >= 7 is importable."""
174
+ fallback = (
175
+ "not using uv? use the project's interpreter (.venv/bin/python or poetry run python); "
176
+ "see the rf-setup skill"
177
+ )
178
+ try:
179
+ major = int(str(_RF_VERSION).split(".")[0]) if _RF_VERSION else None
180
+ except ValueError:
181
+ major = 0
182
+ if (_RF_IMPORT_ERROR is not None or _RF_VERSION is None) and (major is None or major >= MIN_RF_MAJOR):
183
+ raise RobotEnvironmentError(
184
+ f"Robot Framework is not importable by {sys.executable} ({_RF_IMPORT_ERROR})",
185
+ [
186
+ f"run it through the project environment: uv run python {SCRIPT_PATH} ...",
187
+ "add Robot Framework to the project: uv add robotframework",
188
+ fallback,
189
+ ],
190
+ )
191
+ if major is None or major < MIN_RF_MAJOR:
192
+ raise RobotEnvironmentError(
193
+ f"Robot Framework {_RF_VERSION} found in {sys.executable}; "
194
+ f"robotframework>={MIN_RF_MAJOR} is required",
195
+ [
196
+ f"run it through the project environment: uv run python {SCRIPT_PATH} ...",
197
+ 'upgrade Robot Framework in the project: uv add "robotframework>=7"',
198
+ fallback,
199
+ ],
200
+ )
201
+
202
+
203
+ # ---------------------------------------------------------------------------
204
+ # Helpers
205
+ # ---------------------------------------------------------------------------
206
+
207
+
208
+ def _norm(name: str) -> str:
209
+ return re.sub(r"[\s_]", "", name).lower()
210
+
211
+
212
+ def _vtuple(version: Optional[str]) -> Optional[Tuple[int, int, int]]:
213
+ if not version:
214
+ return None
215
+ m = re.match(r"(\d+)\.(\d+)(?:\.(\d+))?", version)
216
+ if not m:
217
+ return None
218
+ return (int(m.group(1)), int(m.group(2)), int(m.group(3) or 0))
219
+
220
+
221
+ def _embedded_args(name: str) -> List[str]:
222
+ """Contents of every ``${...}`` in ``name`` (brace-balanced)."""
223
+ out: List[str] = []
224
+ i = 0
225
+ while True:
226
+ start = name.find("${", i)
227
+ if start < 0:
228
+ return out
229
+ depth, j = 1, start + 2
230
+ while j < len(name) and depth:
231
+ if name[j] == "\\":
232
+ j += 2
233
+ continue
234
+ if name[j] == "{":
235
+ depth += 1
236
+ elif name[j] == "}":
237
+ depth -= 1
238
+ j += 1
239
+ out.append(name[start + 2:j - 1])
240
+ i = j
241
+
242
+
243
+ def _strip_embedded(name: str) -> str:
244
+ for arg in _embedded_args(name):
245
+ name = name.replace("${" + arg + "}", "${}", 1)
246
+ return name
247
+
248
+
249
+ def _embedded_kind(arg: str) -> Tuple[bool, bool]:
250
+ """(typed, custom pattern) for the content of one embedded argument."""
251
+ m = re.match(r"^[^:]*", arg)
252
+ rest = arg[m.end():] if m else ""
253
+ typed = rest.startswith(": ")
254
+ if typed:
255
+ tm = re.match(r"^: [^:]+", rest)
256
+ rest = rest[tm.end():] if tm else ""
257
+ return typed, rest.startswith(":")
258
+
259
+
260
+ def _read(path: Path) -> str:
261
+ try:
262
+ return path.read_text(encoding="utf-8", errors="replace")
263
+ except OSError:
264
+ return ""
265
+
266
+
267
+ def _dist_version(metadata: Path) -> Optional[str]:
268
+ name = version = None
269
+ for line in _read(metadata).splitlines():
270
+ if line.startswith("Name:"):
271
+ name = line.split(":", 1)[1].strip()
272
+ elif line.startswith("Version:"):
273
+ version = line.split(":", 1)[1].strip()
274
+ elif not line.strip():
275
+ break
276
+ if name and _norm(name.replace("-", "")) == "robotframework":
277
+ return version
278
+ return None
279
+
280
+
281
+ def _project_env_version(root: Path) -> Optional[str]:
282
+ venv = root / ".venv"
283
+ if not venv.is_dir():
284
+ return None
285
+ candidates = sorted(venv.glob("lib/python*/site-packages/robotframework-*.dist-info/METADATA"))
286
+ candidates += sorted(venv.glob("Lib/site-packages/robotframework-*.dist-info/METADATA"))
287
+ for metadata in candidates:
288
+ version = _dist_version(metadata)
289
+ if version:
290
+ return version
291
+ return None
292
+
293
+
294
+ def _locked_version(root: Path) -> Optional[str]:
295
+ for lock in ("uv.lock", "poetry.lock"):
296
+ text = _read(root / lock) if (root / lock).is_file() else ""
297
+ m = re.search(r'name = "robotframework"\s*\nversion = "([^"]+)"', text)
298
+ if m:
299
+ return m.group(1)
300
+ return None
301
+
302
+
303
+ def _declared_version(root: Path) -> Optional[str]:
304
+ for fname in ("pyproject.toml", "requirements.txt", "requirements-dev.txt"):
305
+ path = root / fname
306
+ if not path.is_file():
307
+ continue
308
+ m = re.search(
309
+ r"""(?:^|["'\s])robotframework\s*(?:\[[^\]]*\])?\s*((?:[<>=!~]=?\s*[\w.*]+\s*,?\s*)+)""",
310
+ _read(path),
311
+ re.M,
312
+ )
313
+ if m:
314
+ return m.group(1).strip().rstrip(",").strip()
315
+ return None
316
+
317
+
318
+ def _iter_files(root: Path, max_files: int, state: Dict[str, bool]) -> Iterator[Path]:
319
+ count = 0
320
+ for dirpath, dirs, files in os.walk(root):
321
+ dirs[:] = sorted(d for d in dirs if d not in SKIP_DIRS and not d.startswith("."))
322
+ for fname in sorted(files):
323
+ if fname.endswith((".robot", ".resource")):
324
+ if count >= max_files:
325
+ state["truncated"] = True
326
+ return
327
+ count += 1
328
+ yield Path(dirpath) / fname
329
+
330
+
331
+ # ---------------------------------------------------------------------------
332
+ # Scanner
333
+ # ---------------------------------------------------------------------------
334
+
335
+
336
+ class _Stats:
337
+ def __init__(self, max_examples: int) -> None:
338
+ self.max_examples = max_examples
339
+ self.c: Counter = Counter()
340
+ self.sep: Counter = Counter()
341
+ self.assign: Counter = Counter()
342
+ self.legacy: Counter = Counter()
343
+ self.legacy_ids: Dict[str, Optional[str]] = {}
344
+ self.libs: Counter = Counter()
345
+ self.kw_defs: Dict[str, List[Tuple[str, str]]] = defaultdict(list)
346
+ self.examples: Dict[str, List[str]] = defaultdict(list)
347
+ self.res_dirs: Counter = Counter()
348
+ self.var_imports: Counter = Counter()
349
+ self.tags: Counter = Counter()
350
+ self.parse_errors: List[Dict[str, str]] = []
351
+
352
+ def example(self, key: str, value: str) -> None:
353
+ if len(self.examples[key]) < self.max_examples:
354
+ self.examples[key].append(value)
355
+
356
+ def add_legacy(self, construct: str, rule: Optional[str]) -> None:
357
+ self.legacy[construct] += 1
358
+ self.legacy_ids[construct] = rule
359
+
360
+
361
+ def _values(node: Any) -> List[str]:
362
+ return [t.value for t in node.tokens if t.type == Token.ARGUMENT]
363
+
364
+
365
+ def _make_visitor(stats: _Stats, rel: str, is_resource: bool, pipe_file: bool) -> Any:
366
+ class Visitor(ModelVisitor): # type: ignore[misc,valid-type]
367
+ def __init__(self) -> None:
368
+ self.in_body = False
369
+ self.in_test = False
370
+ self.file_private = False
371
+ self.suite_template = False
372
+
373
+ def generic_visit(self, node: Any) -> None:
374
+ tokens = getattr(node, "tokens", None)
375
+ if tokens is not None and type(node).__name__ not in ("TestCaseName", "KeywordName"):
376
+ prev_data = False
377
+ for tok in tokens:
378
+ if tok.type == Token.EOL:
379
+ prev_data = False
380
+ elif tok.type == Token.SEPARATOR:
381
+ if self.in_body and prev_data and not pipe_file:
382
+ stats.sep["tab" if "\t" in tok.value else str(len(tok.value))] += 1
383
+ else:
384
+ prev_data = True
385
+ if tok.type in (Token.ERROR, Token.FATAL_ERROR):
386
+ stats.c["syntax_errors"] += 1
387
+ super().generic_visit(node)
388
+
389
+ # -- settings -----------------------------------------------------
390
+ def visit_SectionHeader(self, node: Any) -> None:
391
+ data = node.data_tokens
392
+ if data:
393
+ name = data[0].value.strip("* ").lower()
394
+ if name in SINGULAR_HEADERS:
395
+ stats.add_legacy("singular section header", LEGACY_OTHER["singular section header"])
396
+ self.generic_visit(node)
397
+
398
+ def visit_LibraryImport(self, node: Any) -> None:
399
+ if node.name:
400
+ stats.libs[node.name] += 1
401
+ if any(t.value.upper() == "WITH NAME" for t in node.tokens):
402
+ stats.add_legacy("WITH NAME", LEGACY_OTHER["WITH NAME"])
403
+ self.generic_visit(node)
404
+
405
+ def visit_VariablesImport(self, node: Any) -> None:
406
+ suffix = Path(node.name or "").suffix.lower().lstrip(".")
407
+ kind = {"yml": "yaml"}.get(suffix, suffix) or "module"
408
+ stats.var_imports[kind] += 1
409
+ self.generic_visit(node)
410
+
411
+ def visit_TestTags(self, node: Any) -> None:
412
+ setting = node.tokens[0].value if node.tokens else ""
413
+ if _norm(setting).startswith("force"):
414
+ stats.add_legacy("Force Tags", LEGACY_OTHER["Force Tags"])
415
+ stats.c["force_tags"] += 1
416
+ else:
417
+ stats.c["test_tags"] += 1
418
+ self._count_tags(_values(node))
419
+ self.generic_visit(node)
420
+
421
+ def visit_ForceTags(self, node: Any) -> None: # older parsers
422
+ self.visit_TestTags(node)
423
+
424
+ def visit_DefaultTags(self, node: Any) -> None:
425
+ stats.add_legacy("Default Tags", LEGACY_OTHER["Default Tags"])
426
+ stats.c["default_tags"] += 1
427
+ self._count_tags(_values(node))
428
+ self.generic_visit(node)
429
+
430
+ def visit_KeywordTags(self, node: Any) -> None:
431
+ if any(v.lower() == "robot:private" for v in _values(node)):
432
+ self.file_private = True
433
+ self.generic_visit(node)
434
+
435
+ def visit_TestTemplate(self, node: Any) -> None:
436
+ value = (node.value or "").strip()
437
+ if value and value.upper() != "NONE":
438
+ self.suite_template = True
439
+ stats.c["template_suites"] += 1
440
+ self.generic_visit(node)
441
+
442
+ def _count_tags(self, values: List[str]) -> None:
443
+ for value in values:
444
+ if value and not value.startswith("-"):
445
+ stats.tags[_norm(value)] += 1
446
+
447
+ # -- variables ----------------------------------------------------
448
+ def visit_Variable(self, node: Any) -> None:
449
+ name = node.name or ""
450
+ if not name:
451
+ return self.generic_visit(node)
452
+ stats.c["section_variables"] += 1
453
+ inner = name[2:-1] if name.endswith("}") else name[2:]
454
+ base = inner.split(":", 1)[0]
455
+ if ": " in inner:
456
+ stats.c["typed_variables"] += 1
457
+ if base != base.upper():
458
+ stats.c["variables_not_upper"] += 1
459
+ stats.example("variables_not_upper", f"{rel}:{node.lineno} {name}")
460
+ self.generic_visit(node)
461
+
462
+ # -- tests --------------------------------------------------------
463
+ def visit_TestCase(self, node: Any) -> None:
464
+ stats.c["tests"] += 1
465
+ templated = self.suite_template
466
+ for stmt in node.body:
467
+ if type(stmt).__name__ == "Template":
468
+ value = (stmt.value or "").strip()
469
+ if value and value.upper() != "NONE":
470
+ templated = True
471
+ stats.c["templated_tests"] += 1
472
+ else:
473
+ templated = False
474
+ if not templated and self._has_control(node.body):
475
+ stats.c["control_in_untemplated"] += 1
476
+ stats.example("control_in_untemplated", f"{rel}:{node.lineno} {node.name}")
477
+ self.in_body = self.in_test = True
478
+ self.generic_visit(node)
479
+ self.in_body = self.in_test = False
480
+
481
+ def _has_control(self, body: List[Any]) -> bool:
482
+ return any(type(stmt).__name__ in CONTROL_NODES for stmt in body)
483
+
484
+ def visit_Tags(self, node: Any) -> None:
485
+ values = _values(node)
486
+ if self.in_test:
487
+ stats.c["tags_settings"] += 1
488
+ self._count_tags(values)
489
+ elif any(v.lower() == "robot:private" for v in values):
490
+ stats.c["private_tagged"] += 1
491
+ self.generic_visit(node)
492
+
493
+ # -- keywords -----------------------------------------------------
494
+ def visit_Keyword(self, node: Any) -> None:
495
+ name = node.name or ""
496
+ stats.c["keywords"] += 1
497
+ if is_resource:
498
+ stats.kw_defs[_norm(_strip_embedded(name))].append((name, f"{rel}:{node.lineno}"))
499
+ args = _embedded_args(name)
500
+ if args:
501
+ stats.c["embedded"] += 1
502
+ stats.example("embedded", f"{rel}:{node.lineno} {name}")
503
+ kinds = [_embedded_kind(a) for a in args]
504
+ if any(p for _, p in kinds):
505
+ stats.c["embedded_with_pattern"] += 1
506
+ typed = sum(1 for t, _ in kinds if t)
507
+ if typed:
508
+ stats.c["typed_arguments"] += typed
509
+ stats.c["keywords_with_typed"] += 1
510
+ if BDD.match(name):
511
+ stats.c["bdd_prefixed_names"] += 1
512
+ plain = re.sub(r"\$\{\}", "", _strip_embedded(name))
513
+ words = [w for w in plain.split() if w[:1].isalpha()]
514
+ if "_" in plain:
515
+ stats.c["underscore"] += 1
516
+ elif words:
517
+ stats.c["title_case" if all(w[0].isupper() for w in words) else "other_case"] += 1
518
+ before = stats.c["private_tagged"]
519
+ self.in_body = True
520
+ self.generic_visit(node)
521
+ self.in_body = False
522
+ if self.file_private or stats.c["private_tagged"] > before:
523
+ stats.c["private"] += 1
524
+
525
+ def visit_Arguments(self, node: Any) -> None:
526
+ values = _values(node)
527
+ if values:
528
+ stats.c["keywords_with_arguments"] += 1
529
+ typed_here = 0
530
+ for value in values:
531
+ if re.match(r"^[$@&]\{[^}]*: [^}]+\}", value):
532
+ stats.c["typed_arguments"] += 1
533
+ typed_here += 1
534
+ stats.example("typed_arguments", f"{rel}:{node.lineno} {value}")
535
+ elif re.match(r"^[$@&]\{[^}]+\}\s*:\s*\w", value):
536
+ stats.c["invalid_typed_arguments"] += 1
537
+ stats.example("invalid_typed_arguments", f"{rel}:{node.lineno} {value}")
538
+ if typed_here:
539
+ stats.c["keywords_with_typed"] += 1
540
+ self.generic_visit(node)
541
+
542
+ def visit_ReturnSetting(self, node: Any) -> None:
543
+ stats.add_legacy("[Return]", LEGACY_OTHER["[Return]"])
544
+ self.generic_visit(node)
545
+
546
+ # -- statements ---------------------------------------------------
547
+ def visit_Var(self, node: Any) -> None:
548
+ stats.c["var_statements"] += 1
549
+ self.generic_visit(node)
550
+
551
+ def visit_KeywordCall(self, node: Any) -> None:
552
+ keyword = node.keyword or ""
553
+ if BDD.match(keyword):
554
+ stats.c["bdd_steps"] += 1
555
+ key = _norm(keyword)
556
+ if key.startswith("builtin."):
557
+ key = key[len("builtin."):]
558
+ info = LEGACY_KEYWORDS.get(key)
559
+ if info:
560
+ stats.add_legacy(*info)
561
+ for tok in node.get_tokens(Token.ASSIGN):
562
+ value = tok.value.rstrip()
563
+ if value.endswith(" ="):
564
+ stats.assign["name_space_equals"] += 1
565
+ elif value.endswith("="):
566
+ stats.assign["name_equals"] += 1
567
+ else:
568
+ stats.assign["no_equals"] += 1
569
+ self.generic_visit(node)
570
+
571
+ return Visitor()
572
+
573
+
574
+ def _scan_file(path: Path, root: Path, stats: _Stats) -> None:
575
+ rel = path.relative_to(root).as_posix()
576
+ pipe_file = any(line.startswith("| ") for line in _read(path).splitlines())
577
+ if path.name == "__init__.robot":
578
+ model = get_init_model(str(path), data_only=False)
579
+ stats.c["init_files"] += 1
580
+ is_resource = False
581
+ elif path.suffix == ".resource":
582
+ model = get_resource_model(str(path), data_only=False)
583
+ stats.res_dirs[path.parent.relative_to(root).as_posix()] += 1
584
+ is_resource = True
585
+ else:
586
+ model = get_model(str(path), data_only=False)
587
+ is_resource = False
588
+ _make_visitor(stats, rel, is_resource, pipe_file).visit(model)
589
+
590
+
591
+ def _features(effective: Optional[Tuple[int, int, int]]) -> Dict[str, Dict[str, Any]]:
592
+ return {
593
+ key: {"min": f"{mv[0]}.{mv[1]}", "available": (None if effective is None else effective[:2] >= mv)}
594
+ for key, mv in FEATURES
595
+ }
596
+
597
+
598
+ def _advice(data: Dict[str, Any]) -> List[Dict[str, str]]:
599
+ rf = data["rf"]
600
+ eff = _vtuple(rf["effective"])
601
+ kw = data["keywords"]
602
+ advice: List[Dict[str, str]] = []
603
+
604
+ def add(ident: str, text: str) -> None:
605
+ advice.append({"id": ident, "text": text})
606
+
607
+ if eff is not None and eff[:2] < (7, 3) and data["scan"]["files"]:
608
+ add("no-typed-arguments",
609
+ f"Robot Framework {rf['effective']} is older than 7.3: do not write ${{name: type}} in "
610
+ "[Arguments], VAR, FOR or the Variables section (it passes the dry run and fails at run "
611
+ "time); keep arguments untyped and convert explicitly, for example with Convert To Integer.")
612
+ with_args = kw["with_arguments"]
613
+ if eff is not None and eff[:2] >= (7, 3) and with_args and kw["with_typed_arguments"] * 2 < with_args:
614
+ add("use-typed-arguments",
615
+ f"Robot Framework {rf['effective']} supports typed user-keyword arguments; "
616
+ f"{kw['with_typed_arguments']} of {with_args} keywords with arguments use them. "
617
+ "Type new arguments that are not strings, for example ${count: int}.")
618
+ if kw["invalid_typed_arguments"]:
619
+ add("fix-invalid-typed-arguments",
620
+ f"{kw['invalid_typed_arguments']} argument(s) use the invalid form ${{name}}: type; write "
621
+ "${name: type} on RF 7.3+ or drop the type and convert explicitly.")
622
+ if kw["definitions"] and kw["embedded"] * 4 >= kw["definitions"]:
623
+ add("follow-embedded-style",
624
+ f"{kw['embedded']} of {kw['definitions']} keywords use embedded arguments; write new "
625
+ "keywords of the same kind with embedded arguments, quoting adjacent ones or giving "
626
+ "them a pattern.")
627
+ dups = kw["duplicate_names"]["count"]
628
+ if dups:
629
+ add("resolve-duplicate-keywords",
630
+ f"{dups} keyword name(s) are defined in more than one resource file; qualify calls "
631
+ "(resource.Keyword Name), rename one of them, or use Set Library Search Order; check "
632
+ "with robocop check --no-cache -s KW06.")
633
+ legacy = data["legacy"]
634
+ if legacy:
635
+ ids = sorted({item["robocop"] for item in legacy if item["robocop"]})
636
+ total = sum(item["count"] for item in legacy)
637
+ text = f"{total} legacy construct(s) in {len(legacy)} kind(s); replace them with the modern forms"
638
+ if ids:
639
+ text += " and check with: robocop check --no-cache " + " ".join(f"-s {i}" for i in ids)
640
+ add("migrate-legacy", text + ".")
641
+ web = data["libraries"]["web_library"]
642
+ if isinstance(web, str):
643
+ add("web-library",
644
+ f"Web tests use {web}; write new web keywords with {web} (see the {WEB_LIBRARIES[web]} skill).")
645
+ elif isinstance(web, list):
646
+ add("mixed-web-libraries",
647
+ "Both Browser and SeleniumLibrary are imported; keep each suite on one of them and write "
648
+ "new web tests with the one the surrounding files use.")
649
+ return advice[:8]
650
+
651
+
652
+ def run(root: Any = ".", max_files: int = DEFAULT_MAX_FILES,
653
+ max_examples: int = DEFAULT_MAX_EXAMPLES) -> Dict[str, Any]:
654
+ """Scan ``root`` and return the rf-conventions/1 dictionary.
655
+
656
+ Raises :class:`InputError` when ``root`` is missing or not a directory and
657
+ :class:`RobotEnvironmentError` when Robot Framework >= 7 is unavailable.
658
+ """
659
+ _require_robot()
660
+ path = Path(root).expanduser()
661
+ if not path.exists():
662
+ raise InputError(f"path not found: {root}")
663
+ if not path.is_dir():
664
+ raise InputError(f"not a directory: {root}")
665
+ path = path.resolve()
666
+ max_examples = max(0, int(max_examples))
667
+ stats = _Stats(max_examples)
668
+ state = {"truncated": False}
669
+ files = 0
670
+ for fpath in _iter_files(path, max(0, int(max_files)), state):
671
+ files += 1
672
+ try:
673
+ _scan_file(fpath, path, stats)
674
+ except Exception as exc: # parser failure on one file must not abort the scan
675
+ if len(stats.parse_errors) < max_examples:
676
+ stats.parse_errors.append({"file": fpath.relative_to(path).as_posix(),
677
+ "error": str(exc).splitlines()[0][:200] if str(exc) else type(exc).__name__})
678
+ stats.c["parse_failures"] += 1
679
+
680
+ installed = str(_RF_VERSION) if _RF_VERSION else None
681
+ project_env = _project_env_version(path)
682
+ locked = _locked_version(path)
683
+ effective, source = None, None
684
+ for src, value in (("project_env", project_env), ("locked", locked), ("installed", installed)):
685
+ if value and _vtuple(value):
686
+ effective, source = value, src
687
+ break
688
+
689
+ c = stats.c
690
+ dups = [(k, v) for k, v in stats.kw_defs.items() if len({loc.split(":")[0] for _, loc in v}) > 1]
691
+ web = [lib for lib in WEB_LIBRARIES if stats.libs.get(lib)]
692
+ if stats.res_dirs:
693
+ resource_dir: Optional[str] = stats.res_dirs.most_common(1)[0][0]
694
+ else:
695
+ resource_dir = next((d for d in RESOURCE_DIR_CANDIDATES if (path / d).is_dir()), None)
696
+ varfiles = sorted(
697
+ p.relative_to(path).as_posix()
698
+ for d in VARIABLE_DIRS if (path / d).is_dir()
699
+ for p in (path / d).rglob("*")
700
+ if p.is_file() and p.suffix.lower() in VARFILE_EXT and "__pycache__" not in p.parts
701
+ )
702
+ data: Dict[str, Any] = {
703
+ "schema": SCHEMA,
704
+ "root": str(path),
705
+ "rf": {
706
+ "installed": installed,
707
+ "project_env": project_env,
708
+ "locked": locked,
709
+ "declared": _declared_version(path),
710
+ "effective": effective,
711
+ "effective_source": source,
712
+ "features": _features(_vtuple(effective)),
713
+ },
714
+ "scan": {
715
+ "files": files,
716
+ "truncated": state["truncated"],
717
+ "parse_errors": stats.parse_errors,
718
+ "syntax_errors": c["syntax_errors"],
719
+ },
720
+ "style": {
721
+ "separator": {
722
+ "dominant": stats.sep.most_common(1)[0][0] if stats.sep else None,
723
+ "counts": dict(stats.sep.most_common(5)),
724
+ },
725
+ "assignment": {
726
+ "dominant": stats.assign.most_common(1)[0][0] if stats.assign else None,
727
+ "counts": {k: stats.assign.get(k, 0) for k in ("name_equals", "name_space_equals", "no_equals")},
728
+ },
729
+ "keyword_case": {"title_case": c["title_case"], "other": c["other_case"],
730
+ "underscore": c["underscore"]},
731
+ },
732
+ "keywords": {
733
+ "definitions": c["keywords"],
734
+ "with_arguments": c["keywords_with_arguments"],
735
+ "with_typed_arguments": c["keywords_with_typed"],
736
+ "embedded": c["embedded"],
737
+ "embedded_with_pattern": c["embedded_with_pattern"],
738
+ "typed_arguments": c["typed_arguments"],
739
+ "invalid_typed_arguments": c["invalid_typed_arguments"],
740
+ "private": c["private"],
741
+ "bdd_prefixed_names": c["bdd_prefixed_names"],
742
+ "duplicate_names": {
743
+ "count": len(dups),
744
+ "examples": [
745
+ {"name": v[0][0], "defined_in": [loc for _, loc in v][:max_examples]}
746
+ for _, v in dups[:max_examples]
747
+ ],
748
+ },
749
+ "examples": {key: stats.examples.get(key, [])
750
+ for key in ("embedded", "typed_arguments", "invalid_typed_arguments")},
751
+ },
752
+ "calls": {"bdd_steps": c["bdd_steps"], "var_statements": c["var_statements"]},
753
+ "tests": {
754
+ "count": c["tests"],
755
+ "template_suites": c["template_suites"],
756
+ "templated_tests": c["templated_tests"],
757
+ "tag_settings": {"test_tags": c["test_tags"], "force_tags": c["force_tags"],
758
+ "default_tags": c["default_tags"], "tags": c["tags_settings"]},
759
+ "top_tags": [{"tag": t, "count": n} for t, n in stats.tags.most_common(10)],
760
+ "control_in_untemplated": c["control_in_untemplated"],
761
+ "examples": stats.examples.get("control_in_untemplated", []),
762
+ },
763
+ "variables": {
764
+ "section_variables": c["section_variables"],
765
+ "not_uppercase": c["variables_not_upper"],
766
+ "typed": c["typed_variables"],
767
+ "examples": stats.examples.get("variables_not_upper", []),
768
+ },
769
+ "legacy": [{"construct": k, "count": n, "robocop": stats.legacy_ids.get(k)}
770
+ for k, n in sorted(stats.legacy.items(), key=lambda kv: (-kv[1], kv[0]))],
771
+ "layout": {
772
+ "resource_dirs": dict(stats.res_dirs.most_common(5)),
773
+ "resource_dir": resource_dir,
774
+ "variable_files": varfiles[:10],
775
+ "variable_imports": dict(sorted(stats.var_imports.items())),
776
+ "libraries_dir": (path / "libraries").is_dir(),
777
+ "init_files": c["init_files"],
778
+ "robot_toml": (path / "robot.toml").is_file(),
779
+ },
780
+ "libraries": {
781
+ "imports": dict(stats.libs.most_common(10)),
782
+ "web_library": web[0] if len(web) == 1 else (web or None),
783
+ },
784
+ "advice": [],
785
+ }
786
+ data["advice"] = _advice(data)
787
+ return data
788
+
789
+
790
+ # ---------------------------------------------------------------------------
791
+ # CLI
792
+ # ---------------------------------------------------------------------------
793
+
794
+ EPILOG = """\
795
+ examples:
796
+ uv run python scripts/rf_conventions.py .
797
+ uv run python scripts/rf_conventions.py path/to/project --max-examples 5 --pretty
798
+ uv run python scripts/rf_conventions.py . --max-files 500 --json-out results/conventions.json
799
+
800
+ Paths to the script are relative to the rf-language skill directory; PATH is the
801
+ project to scan. Not using uv? Run with the project's interpreter (.venv/bin/python
802
+ or poetry run python); see rf-setup.
803
+ exit codes: 0 ok (also when no .robot/.resource files exist), 1 internal error,
804
+ 2 usage, 3 environment (robotframework>=7 missing), 4 path missing or not a directory.
805
+ """
806
+
807
+
808
+ class _Parser(argparse.ArgumentParser):
809
+ """argparse with ``error:``/``hint:`` stderr lines and exit code 2."""
810
+
811
+ def error(self, message: str) -> NoReturn: # type: ignore[override]
812
+ _fail(EXIT_USAGE, message,
813
+ f"see the options and examples: uv run python {SCRIPT_PATH} --help")
814
+
815
+
816
+ def build_parser() -> argparse.ArgumentParser:
817
+ parser = _Parser(
818
+ description="Detect a Robot Framework project's conventions and print them as JSON on stdout.",
819
+ epilog=EPILOG,
820
+ formatter_class=argparse.RawDescriptionHelpFormatter,
821
+ )
822
+ parser.add_argument("path", nargs="?", default=".", help="Project directory to scan (default: .)")
823
+ parser.add_argument("--max-files", type=int, default=DEFAULT_MAX_FILES,
824
+ help=f"Scan at most N .robot/.resource files (default {DEFAULT_MAX_FILES}; sets scan.truncated)")
825
+ parser.add_argument("--max-examples", type=int, default=DEFAULT_MAX_EXAMPLES,
826
+ help=f"Examples per list (default {DEFAULT_MAX_EXAMPLES}; 0 = none)")
827
+ parser.add_argument("--json-out", metavar="FILE",
828
+ help="Write the JSON result to FILE; stdout gets {written, bytes, mode}")
829
+ parser.add_argument("--pretty", action="store_true", help="Indent the JSON output")
830
+ parser.add_argument("--debug", action="store_true", help="Print a traceback on internal errors")
831
+ return parser
832
+
833
+
834
+ def emit(data: Dict[str, Any], *, pretty: bool, json_out: Optional[str]) -> None:
835
+ text = json.dumps(data, indent=2) if pretty else json.dumps(data, separators=(",", ":"))
836
+ if not json_out:
837
+ print(text)
838
+ return
839
+ os.makedirs(os.path.dirname(os.path.abspath(json_out)), exist_ok=True)
840
+ payload = (text + "\n").encode("utf-8")
841
+ with open(json_out, "wb") as fh:
842
+ fh.write(payload)
843
+ print(json.dumps({"written": json_out, "bytes": len(payload), "mode": "conventions"}))
844
+
845
+
846
+ def _run_cli(args: argparse.Namespace, parser: argparse.ArgumentParser) -> int:
847
+ if args.max_files < 1:
848
+ parser.error("--max-files must be >= 1")
849
+ if args.max_examples < 0:
850
+ parser.error("--max-examples must be >= 0")
851
+ try:
852
+ _require_robot()
853
+ except RobotEnvironmentError as exc:
854
+ _fail(EXIT_ENV, str(exc), *exc.hints)
855
+ try:
856
+ data = run(args.path, max_files=args.max_files, max_examples=args.max_examples)
857
+ except InputError as exc:
858
+ _fail(EXIT_INPUT, str(exc), exc.hint)
859
+ if data["scan"]["files"] == 0:
860
+ _warn(f"no .robot or .resource files found under {data['root']}")
861
+ if data["scan"]["truncated"]:
862
+ _warn(f"scan stopped after {args.max_files} files (scan.truncated); raise --max-files to scan more")
863
+ emit(data, pretty=args.pretty, json_out=args.json_out)
864
+ return EXIT_OK
865
+
866
+
867
+ def main(argv: Optional[List[str]] = None) -> None:
868
+ parser = build_parser()
869
+ args = parser.parse_args(argv)
870
+ try:
871
+ code = _run_cli(args, parser)
872
+ except SystemExit:
873
+ raise
874
+ except Exception as exc:
875
+ if args.debug:
876
+ traceback.print_exc(file=sys.stderr)
877
+ _fail(EXIT_INTERNAL, f"internal: {type(exc).__name__}: {exc}",
878
+ "re-run with --debug for a traceback")
879
+ sys.exit(code)
880
+
881
+
882
+ if __name__ == "__main__":
883
+ main()