vigiles 2.5.0 → 3.0.0

package/skills/linter-docs/pylint.md

@@ -0,0 +1,288 @@
+# Pylint — Reference
+
+Shared linter reference for vigiles skills. Used by `strengthen` (find existing rules) and `pr-to-lint-rule` (write custom checkers).
+
+## Check Existing Plugins First
+
+Before writing a custom checker, search these plugins — the pattern may already be covered:
+
+| Plugin                          | Scope                                       | Key messages to know                                                                                                                                |
+| ------------------------------- | ------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `pylint` (core)                 | Convention, Refactor, Warning, Error, Fatal | `C0114` (missing-module-docstring), `R0902` (too-many-instance-attributes), `W0612` (unused-variable), `E1101` (no-member), `W0611` (unused-import) |
+| `pylint-django`                 | Django conventions                          | `E5110` (no-member on Django models), `W5101` (fixme in templates), `C5105` (string-used-as-django-setting)                                         |
+| `pylint-celery`                 | Celery task patterns                        | Detects common Celery anti-patterns (task retry without max_retries, etc.)                                                                          |
+| `pylint-pydantic`               | Pydantic model checking                     | Suppresses false positives from Pydantic's metaclass magic                                                                                          |
+| `pylint-pytest`                 | pytest conventions                          | `W6301` (useless-pytest-mark-decorator), `W6302` (unnecessary-pytest-mark-parametrize)                                                              |
+| `pylint-flask`                  | Flask patterns                              | Suppresses false positives for Flask's app context, request globals                                                                                 |
+| `pylint-sqlalchemy`             | SQLAlchemy ORM                              | Suppresses false `no-member` on SQLAlchemy models                                                                                                   |
+| `pylint-protobuf`               | Protobuf message checking                   | Type-checks protobuf field access, catches typos in field names                                                                                     |
+| `pylint-import-modules`         | Import style enforcement                    | `C6201` (import-modules-only) — enforce `import module` over `from module import name`                                                              |
+| `pylint-secure-coding-standard` | Security patterns                           | Detects insecure patterns: `eval`, `exec`, hardcoded passwords, insecure hash algorithms                                                            |
+
+**Tip:** Many patterns can be handled by Pylint's built-in `bad-names`, `good-names`, `bad-functions`, or the `--disable`/`--enable` system without a custom checker.
+
+**Also consider Ruff.** If the project uses Ruff, it reimplements many Pylint rules (prefixed `PL`) at much higher speed. Check Ruff's rule catalog before writing a Pylint-specific checker.
+
+## Checker Anatomy
+
+Every Pylint checker inherits from `BaseChecker`:
+
+```python
+"""Checker for direct database queries outside the repository layer."""
+
+from astroid import nodes
+from pylint.checkers import BaseChecker
+from pylint.interfaces import HIGH
+
+
+class NoDirectDbQueryChecker(BaseChecker):
+    name = "no-direct-db-query"
+
+    msgs = {
+        "C9001": (
+            "Use %sRepository instead of %s.%s",
+            "no-direct-db-query",
+            "Direct model queries should go through the repository layer.",
+        ),
+    }
+
+    # Optional: add configuration options
+    options = (
+        (
+            "allowed-models",
+            {
+                "default": (),
+                "type": "csv",
+                "metavar": "<models>",
+                "help": "Models that are allowed to be queried directly.",
+            },
+        ),
+    )
+
+    def visit_call(self, node: nodes.Call) -> None:
+        if not isinstance(node.func, nodes.Attribute):
+            return
+        if not isinstance(node.func.expr, nodes.Name):
+            return
+
+        model = node.func.expr.name
+        method = node.func.attrname
+
+        if method in ("objects", "filter", "get", "all", "count", "values"):
+            if model not in self.linter.config.allowed_models:
+                self.add_message(
+                    "no-direct-db-query",
+                    node=node,
+                    args=(model, model, method),
+                    confidence=HIGH,
+                )
+
+
+def register(linter):
+    linter.register_checker(NoDirectDbQueryChecker(linter))
+```
+
+### Key concepts
+
+| Concept       | Purpose             | Notes                                                      |
+| ------------- | ------------------- | ---------------------------------------------------------- |
+| `name`        | Checker identifier  | Must be unique across all checkers                         |
+| `msgs`        | Message dictionary  | Key format: `{C,R,W,E,F}{4 digits}` — category + unique ID |
+| `options`     | Configuration       | Exposed via `pylintrc` or command line                     |
+| `visit_*`     | AST visitor methods | Called for each matching node type                         |
+| `leave_*`     | Post-visit methods  | Called when leaving a node (post-order)                    |
+| `add_message` | Report a violation  | Pass message ID, node, args for formatting                 |
+| `register`    | Plugin entry point  | Module-level function that registers the checker           |
+
+### Message categories
+
+| Prefix | Category   | When to use                                |
+| ------ | ---------- | ------------------------------------------ |
+| `C`    | Convention | Style/naming conventions                   |
+| `R`    | Refactor   | Code that works but should be restructured |
+| `W`    | Warning    | Probable bugs or risky patterns            |
+| `E`    | Error      | Definite bugs or broken code               |
+| `F`    | Fatal      | Pylint can't process the file              |
+
+Choose a unique 4-digit code starting from `9001` to avoid collisions with core Pylint. Check existing codes with `pylint --list-msgs`.
+
+## AST Nodes — Cheat Sheet (astroid)
+
+Pylint uses `astroid` for AST parsing, which adds type inference on top of Python's `ast` module:
+
+| You want to detect         | Node type / visitor                                 | Notes                                         |
+| -------------------------- | --------------------------------------------------- | --------------------------------------------- |
+| Function call `foo()`      | `visit_call` + check `node.func`                    | `node.func` is a `Name` or `Attribute`        |
+| Method call `obj.method()` | `visit_call` + `isinstance(node.func, Attribute)`   | `node.func.attrname` = method name            |
+| Import `import X`          | `visit_import`                                      | `node.names` = list of `(name, alias)` tuples |
+| Import `from X import Y`   | `visit_importfrom`                                  | `node.modname` = module, `node.names` = names |
+| Class definition           | `visit_classdef`                                    | `node.name`, `node.bases`, `node.body`        |
+| Function definition        | `visit_functiondef`                                 | `node.name`, `node.args`, `node.body`         |
+| Assignment `x = ...`       | `visit_assign`                                      | `node.targets`, `node.value`                  |
+| String literal             | `visit_const` + check `isinstance(node.value, str)` |                                               |
+| Decorator `@foo`           | `visit_decorators`                                  | Or check `node.decorators` on function/class  |
+| `raise` statement          | `visit_raise`                                       | `node.exc` = exception expression             |
+| `with` statement           | `visit_with`                                        | `node.items` = context manager list           |
+| `try`/`except`             | `visit_tryexcept`                                   | `node.handlers` = list of except clauses      |
+
+### astroid type inference
+
+astroid can infer types, which is more powerful than plain AST:
+
+```python
+def visit_call(self, node: nodes.Call) -> None:
+    # Infer what the function resolves to
+    try:
+        for inferred in node.func.infer():
+            if isinstance(inferred, nodes.FunctionDef):
+                # We know the actual function being called
+                if inferred.name == "dangerous_function":
+                    self.add_message("no-dangerous-call", node=node)
+    except astroid.InferenceError:
+        pass  # Can't determine — skip
+```
+
+**Caution:** `infer()` can raise `InferenceError` and can return `Uninferable`. Always handle both.
+
+## Testing Checkers
+
+```python
+"""Tests for no_direct_db_query checker."""
+
+import astroid
+import pylint.testutils
+
+from my_checkers.no_direct_db_query import NoDirectDbQueryChecker
+
+
+class TestNoDirectDbQueryChecker(pylint.testutils.UnittestLinter):
+    CHECKER_CLASS = NoDirectDbQueryChecker
+
+    def test_direct_query_flagged(self):
+        node = astroid.extract_node("""
+            User.objects.filter(active=True)  #@
+        """)
+        with self.assertAddsMessages(
+            pylint.testutils.MessageTest(
+                msg_id="no-direct-db-query",
+                node=node,
+                args=("User", "User", "objects"),
+            ),
+        ):
+            self.checker.visit_call(node)
+
+    def test_repository_call_allowed(self):
+        node = astroid.extract_node("""
+            UserRepository.active_users()  #@
+        """)
+        with self.assertNoMessages():
+            self.checker.visit_call(node)
+```
+
+**Testing best practices:**
+
+1. **Use `astroid.extract_node` with `#@` marker.** The marker indicates which node to extract from the code.
+2. **Test with `assertAddsMessages` and `assertNoMessages`.** These are the canonical assertion methods.
+3. **Test configuration options.** If your checker has options, test each combination.
+4. **Test inference edge cases.** Code with dynamic attributes, metaclasses, or `__getattr__` may cause `InferenceError`.
+5. **Run with `pytest` not `unittest`.** Pylint's test utils work with both, but pytest gives better output.
+
+## Registration
+
+### As a Pylint plugin
+
+Add to `pyproject.toml`:
+
+```toml
+[tool.pylint.main]
+load-plugins = ["my_checkers.no_direct_db_query"]
+```
+
+Or `.pylintrc`:
+
+```ini
+[MAIN]
+load-plugins=my_checkers.no_direct_db_query
+```
+
+The module must be importable from `PYTHONPATH`. For a local checker, put it in the project and ensure the path is set.
+
+### vigiles enforce() reference
+
+```typescript
+enforce(
+  "pylint/no-direct-db-query",
+  "Use repository pattern for all DB queries.",
+);
+```
+
+vigiles checks `pylint --help-msg=no-direct-db-query` and verifies the message exists and is enabled.
+
+## Edge Cases and Gotchas
+
+### Symbolic names vs message codes
+
+Pylint messages have both a code (`C0114`) and a symbolic name (`missing-module-docstring`). Both work in vigiles:
+
+```typescript
+enforce("pylint/C0114", "All modules need docstrings.");
+enforce("pylint/missing-module-docstring", "All modules need docstrings.");
+```
+
+Prefer symbolic names — they're readable and stable across Pylint versions.
+
+### astroid inference limitations
+
+astroid can't infer:
+
+- Dynamically constructed classes (`type("Foo", (Base,), {...})`)
+- Heavy metaprogramming (`__init_subclass__`, custom metaclasses)
+- C extensions (some methods on `numpy`, `pandas` are opaque)
+- Runtime-only attributes (`setattr`, `__dict__` manipulation)
+
+If your convention targets heavily dynamic code, expect false negatives. Add a comment explaining the limitation in the checker.
+
+### Plugin vs Ruff
+
+For simple pattern bans, Ruff's built-in rules or `flake8-*` plugins reimplemented in Ruff are 10-100x faster. Use a Pylint custom checker only when you need:
+
+- Type inference (astroid's `infer()`)
+- Cross-function or cross-module analysis
+- Configuration options exposed in `pylintrc`
+- Integration with Django/Flask/SQLAlchemy brain plugins
+
+### Message ID collisions
+
+Core Pylint uses codes `C0001`-`C8999`, `W0001`-`W8999`, etc. Custom checkers should use `9000+` to avoid collisions. Check with:
+
+```bash
+pylint --list-msgs | grep "C90\|W90\|E90"
+```
+
+### Performance
+
+- Pylint is slow on large codebases. Custom checkers add overhead per-file.
+- Avoid `infer()` in hot paths — each call can trigger recursive type resolution.
+- Use `visit_module` + early return to skip files that can't contain violations (e.g., skip test files for production-only rules).
+- Consider `--jobs=N` for parallel execution, but note that custom checkers must be pickle-safe for multiprocessing.
+
+### Monorepo considerations
+
+- Pylint resolves `pylintrc` / `pyproject.toml` from `cwd`, not from the file being linted. In a monorepo, run Pylint per-package.
+- vigiles checks `pylint --help-msg=<name>` from the project `basePath`. If packages have different plugins loaded, run from each package root.
+- Custom checkers must be on `PYTHONPATH`. In a monorepo, use relative `load-plugins` paths or install checkers as a development package.
+
+## Mapping PR Feedback to Checker Strategy
+
+| PR comment pattern                    | Best approach                                                                                  |
+| ------------------------------------- | ---------------------------------------------------------------------------------------------- |
+| "Don't import X directly"             | `pylint/no-name-in-module` or custom checker with `visit_importfrom`                           |
+| "Don't call X()"                      | `pylint/bad-functions` config or custom checker with `visit_call`                              |
+| "Missing docstring"                   | `pylint/missing-function-docstring` (C0116) — already exists                                   |
+| "Function too long"                   | `pylint/too-many-statements` (R0915) — configure threshold                                     |
+| "Too many arguments"                  | `pylint/too-many-arguments` (R0913) — configure `max-args`                                     |
+| "Use logging instead of print"        | Ruff `T201` or custom checker banning `print()`                                                |
+| "Don't use global state"              | Custom checker detecting `global` keyword or module-level mutation                             |
+| "Always type-hint public methods"     | `pylint/missing-function-docstring` doesn't cover this — use `mypy --strict` or custom checker |
+| "Don't catch bare Exception"          | `pylint/broad-exception-caught` (W0718) — already exists                                       |
+| "Don't use mutable default arguments" | `pylint/dangerous-default-value` (W0102) — already exists                                      |

package/skills/linter-docs/rubocop.md

@@ -0,0 +1,277 @@
+# RuboCop — Reference
+
+Shared linter reference for vigiles skills. Used by `strengthen` (find existing rules) and `pr-to-lint-rule` (write custom cops).
+
+## Check Existing Gems First
+
+Before writing a custom cop, search these gems — the pattern may already be covered:
+
+| Gem                   | Scope                                  | Key cops to know                                                                                                                   |
+| --------------------- | -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
+| `rubocop` (core)      | Style, Lint, Metrics, Naming, Security | `Style/FrozenStringLiteralComment`, `Lint/UnusedMethodArgument`, `Metrics/MethodLength`, `Naming/MethodName`, `Security/Eval`      |
+| `rubocop-rails`       | Rails conventions                      | `Rails/HttpPositionalArguments`, `Rails/SkipsModelValidations`, `Rails/Output`, `Rails/HasAndBelongsToMany`, `Rails/DynamicFindBy` |
+| `rubocop-rspec`       | RSpec test patterns                    | `RSpec/ExampleLength`, `RSpec/MultipleExpectations`, `RSpec/NestedGroups`, `RSpec/LetSetup`, `RSpec/MessageSpies`                  |
+| `rubocop-minitest`    | Minitest patterns                      | `Minitest/AssertEmptyLiteral`, `Minitest/RefuteNil`, `Minitest/AssertInDelta`                                                      |
+| `rubocop-performance` | Performance anti-patterns              | `Performance/StringReplacement`, `Performance/Detect`, `Performance/Count`, `Performance/FlatMap`, `Performance/CaseWhenSplat`     |
+| `rubocop-rake`        | Rakefile patterns                      | `Rake/Desc`, `Rake/DuplicateTask`, `Rake/MethodDefinitionInTask`                                                                   |
+| `rubocop-sorbet`      | Sorbet type checking                   | `Sorbet/ForbidSuperclassConstLiteral`, `Sorbet/ValidSigil`, `Sorbet/SignatureBuildOrder`                                           |
+| `rubocop-graphql`     | GraphQL conventions                    | `GraphQL/FieldDescription`, `GraphQL/ObjectDescription`, `GraphQL/ArgumentDescription`                                             |
+| `rubocop-factory_bot` | FactoryBot patterns                    | `FactoryBot/ConsistentParenthesesStyle`, `FactoryBot/CreateList`, `FactoryBot/SyntaxMethods`                                       |
+| `rubocop-capybara`    | Capybara test patterns                 | `Capybara/CurrentPathExpectation`, `Capybara/VisibilityMatcher`, `Capybara/SpecificMatcher`                                        |
+
+**Tip:** Many patterns can be handled by configuring existing cops rather than writing new ones. Check if an existing cop has configurable `AllowedMethods`, `AllowedPatterns`, or `Include`/`Exclude` options first.
+
+## Cop Anatomy
+
+Every RuboCop cop inherits from `RuboCop::Cop::Base`:
+
+```ruby
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module Custom
+      # Disallow direct database queries outside the repository layer.
+      #
+      # @example
+      #   # bad
+      #   User.where(active: true)
+      #
+      #   # good
+      #   UserRepository.active_users
+      class NoDirectDbQuery < Base
+        MSG = 'Use the repository pattern — call `%<model>sRepository` instead of `%<model>s.%<method>s`.'
+
+        RESTRICT_ON_SEND = %i[where find find_by first last all count pluck].freeze
+
+        # @!method ar_model_query?(node)
+        def_node_matcher :ar_model_query?, <<~PATTERN
+          (send (const nil? _) {:where :find :find_by :first :last :all :count :pluck} ...)
+        PATTERN
+
+        def on_send(node)
+          return unless ar_model_query?(node)
+
+          model = node.receiver.short_name
+          add_offense(node, message: format(MSG, model: model, method: node.method_name))
+        end
+      end
+    end
+  end
+end
+```
+
+### Key concepts
+
+| Concept            | Purpose                                       | Notes                                                               |
+| ------------------ | --------------------------------------------- | ------------------------------------------------------------------- |
+| `MSG`              | Error message string                          | Use `format` with `%<name>s` for interpolation                      |
+| `RESTRICT_ON_SEND` | Whitelist of method names                     | Performance optimization — cop only runs on matching `send` nodes   |
+| `def_node_matcher` | AST pattern matcher                           | DSL for matching Ruby AST patterns — replaces manual node traversal |
+| `def_node_search`  | Like `def_node_matcher` but finds all matches | Returns an enumerator of matching nodes                             |
+| `add_offense`      | Report a violation                            | Accepts `node`, optional `message:` and `severity:`                 |
+
+### Cop departments
+
+| Department | When to use                                           |
+| ---------- | ----------------------------------------------------- |
+| `Lint`     | Code that is/will be broken                           |
+| `Style`    | Code that works but violates a convention             |
+| `Metrics`  | Complexity thresholds (method length, ABC size, etc.) |
+| `Naming`   | Naming conventions                                    |
+| `Security` | Security anti-patterns                                |
+| `Custom`   | Your project-specific cops                            |
+
+## Node Pattern DSL — Cheat Sheet
+
+RuboCop's node pattern DSL is the primary way to match AST nodes:
+
+| You want to detect    | Pattern                             | Notes                                         |
+| --------------------- | ----------------------------------- | --------------------------------------------- |
+| Method call `foo`     | `(send nil? :foo ...)`              | `nil?` = no receiver                          |
+| Method call `obj.foo` | `(send _ :foo ...)`                 | `_` = any receiver                            |
+| Method call `Foo.bar` | `(send (const nil? :Foo) :bar ...)` | Constant receiver                             |
+| String literal `"x"`  | `(str "x")`                         |                                               |
+| Symbol `:x`           | `(sym :x)`                          |                                               |
+| Block `foo { }`       | `(block (send nil? :foo) ...)`      |                                               |
+| Class definition      | `(class (const nil? :Name) ...)`    |                                               |
+| `if` conditional      | `(if _ _ _)`                        | Three children: condition, if-body, else-body |
+| Instance variable     | `(ivar :@name)`                     |                                               |
+| Constant assignment   | `(casgn nil? :NAME _)`              |                                               |
+| `require "x"`         | `(send nil? :require (str "x"))`    |                                               |
+
+**Wildcards and captures:**
+
+- `_` — matches any single node
+- `...` — matches any number of nodes (rest)
+- `$_` — capture a node into a variable
+- `nil?` — matches nil (no receiver for top-level calls)
+- `{:foo :bar}` — matches either `:foo` or `:bar`
+- `(send _ {:puts :print :p} ...)` — matches puts/print/p on any receiver
+
+**Pro tip:** Run `ruby-parse -e 'your_code_here'` to see the AST for any Ruby expression. The `parser` gem must be installed.
+
+## Auto-Correct
+
+### `extend AutoCorrector` — opt-in auto-fix
+
+```ruby
+class NoDirectDbQuery < Base
+  extend AutoCorrector
+
+  def on_send(node)
+    return unless ar_model_query?(node)
+
+    add_offense(node) do |corrector|
+      model = node.receiver.short_name
+      corrector.replace(node, "#{model}Repository.#{node.method_name}")
+    end
+  end
+end
+```
+
+Available corrector methods:
+
+| Method                                | What it does                     |
+| ------------------------------------- | -------------------------------- |
+| `corrector.replace(node, text)`       | Replace node with text           |
+| `corrector.insert_before(node, text)` | Insert text before node          |
+| `corrector.insert_after(node, text)`  | Insert text after node           |
+| `corrector.remove(node)`              | Remove node                      |
+| `corrector.wrap(node, before, after)` | Wrap node with before/after text |
+
+Safety rules for auto-correct:
+
+- **Mark unsafe corrections** with `def autocorrect_enabled? = false` or use the cop's `Safe` / `SafeAutoCorrect` metadata in `.rubocop.yml`
+- **Never change runtime behavior.** If the fix might break code, don't auto-correct.
+- RuboCop runs `rubocop -a` (safe only) vs `rubocop -A` (all including unsafe). Default to safe.
+
+## Testing Cops
+
+```ruby
+# frozen_string_literal: true
+
+require "rubocop"
+require "rubocop/rspec/expect_offense"
+
+RSpec.describe RuboCop::Cop::Custom::NoDirectDbQuery, :config do
+  # Tests that valid code produces no offenses
+  it "accepts repository pattern calls" do
+    expect_no_offenses(<<~RUBY)
+      UserRepository.active_users
+    RUBY
+  end
+
+  # Tests that invalid code produces the right offense
+  it "registers offense for direct AR query" do
+    expect_offense(<<~RUBY)
+      User.where(active: true)
+      ^^^^^^^^^^^^^^^^^^^^^^^^ Use the repository pattern — call `UserRepository` instead of `User.where`.
+    RUBY
+  end
+
+  # Tests auto-correction
+  it "auto-corrects to repository call" do
+    expect_offense(<<~RUBY)
+      User.find(1)
+      ^^^^^^^^^^^^ Use the repository pattern — call `UserRepository` instead of `User.find`.
+    RUBY
+
+    expect_correction(<<~RUBY)
+      UserRepository.find(1)
+    RUBY
+  end
+end
+```
+
+**Testing best practices:**
+
+1. **Use `expect_offense` with caret markers.** The carets (`^`) must align with the exact offense location.
+2. **Test edge cases.** Dynamic receivers, safe navigation (`&.`), chained methods, blocks.
+3. **Test configuration.** If your cop respects `AllowedMethods`, test with and without the config.
+4. **Use `:config` shared context** to get a default configuration object.
+
+## Registration
+
+### In `.rubocop.yml`
+
+```yaml
+require:
+  - ./lib/rubocop/cop/custom/no_direct_db_query
+
+Custom/NoDirectDbQuery:
+  Enabled: true
+  Include:
+    - "app/**/*.rb"
+  Exclude:
+    - "app/repositories/**/*.rb"
+```
+
+### vigiles enforce() reference
+
+```typescript
+enforce(
+  "rubocop/Custom/NoDirectDbQuery",
+  "Use repository pattern for all DB queries.",
+);
+```
+
+vigiles checks `rubocop --show-cops Custom/NoDirectDbQuery` and verifies `Enabled: true`.
+
+## Edge Cases and Gotchas
+
+### Safe vs unsafe cops
+
+RuboCop distinguishes `Safe: true` (default) from `Safe: false`. Unsafe cops can produce false positives. When writing a custom cop that can't guarantee correctness (e.g., it doesn't understand metaprogramming), set:
+
+```yaml
+Custom/MyCop:
+  Safe: false
+  SafeAutoCorrect: false
+```
+
+### Metaprogramming blind spots
+
+RuboCop's AST parser doesn't understand:
+
+- `method_missing` / `respond_to_missing?`
+- `define_method` with dynamic names
+- `send` / `public_send` with variable method names
+- ActiveRecord dynamic finders (`find_by_name` generated at runtime)
+
+If your convention targets code that's often generated via metaprogramming, expect false negatives.
+
+### Node matcher vs manual traversal
+
+Use `def_node_matcher` for simple patterns. Switch to manual `node.children`, `node.each_descendant`, etc. when you need:
+
+- Cross-method analysis (e.g., "if method A exists, method B must also exist")
+- State tracking across the file (e.g., counting total occurrences)
+- Complex conditional logic that the pattern DSL can't express
+
+### Performance
+
+- Always use `RESTRICT_ON_SEND` when targeting method calls — it skips the cop entirely for non-matching methods.
+- Avoid `on_send` without `RESTRICT_ON_SEND` on large codebases — it fires for every method call.
+- `def_node_search` iterates descendants and can be slow on deeply nested ASTs. Prefer `def_node_matcher` on specific node types.
+
+### Monorepo considerations
+
+- RuboCop resolves `.rubocop.yml` from the file being linted, walking up directories. Each sub-project can have its own config.
+- vigiles checks `rubocop --show-cops <CopName>` from the project `basePath`. In a monorepo, run from each gem/app root.
+- Custom cops must be `require`-able from the config file's location. Use relative paths or bundle them in a gem.
+
+## Mapping PR Feedback to Cop Strategy
+
+| PR comment pattern                         | Best approach                                                                    |
+| ------------------------------------------ | -------------------------------------------------------------------------------- |
+| "Don't call X directly"                    | Check if an existing cop covers it; otherwise custom cop with `RESTRICT_ON_SEND` |
+| "Use our wrapper for Y"                    | Custom cop — detect raw calls, suggest wrapper                                   |
+| "Method too long"                          | `Metrics/MethodLength` — configure `Max:` threshold                              |
+| "Missing frozen_string_literal"            | `Style/FrozenStringLiteralComment` — already exists                              |
+| "Don't use `puts` in production"           | Custom cop or `Rails/Output` if using Rails                                      |
+| "Always add description to GraphQL fields" | `rubocop-graphql` `GraphQL/FieldDescription`                                     |
+| "Test files too complex"                   | `RSpec/ExampleLength`, `RSpec/NestedGroups` — configure thresholds               |
+| "Naming convention violated"               | `Naming/*` cops — highly configurable                                            |
+| "Security issue: eval"                     | `Security/Eval` — already exists                                                 |
+| "Don't skip validations"                   | `Rails/SkipsModelValidations` — already exists                                   |