vigiles 2.0.0

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                                   |

package/skills/linter-docs/ruff.md

@@ -0,0 +1,187 @@
+# Ruff — Reference
+
+Shared linter reference for vigiles skills. Used by `strengthen` (find existing rules) and `pr-to-lint-rule` (write custom rules).
+
+## Check Existing Rules First
+
+Ruff reimplements 800+ rules from flake8, pylint, isort, pyupgrade, and others. Before writing a custom rule, check if Ruff already covers it:
+
+| Prefix    | Source                    | Key rules                                                                                                                                     |
+| --------- | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
+| `E` / `W` | pycodestyle               | `E501` (line-too-long), `W291` (trailing-whitespace), `E711` (none-comparison)                                                                |
+| `F`       | pyflakes                  | `F401` (unused-import), `F841` (unused-variable), `F811` (redefined-unused-name)                                                              |
+| `I`       | isort                     | `I001` (unsorted-imports), `I002` (missing-required-import)                                                                                   |
+| `N`       | pep8-naming               | `N801` (invalid-class-name), `N802` (invalid-function-name), `N806` (non-lowercase-variable)                                                  |
+| `UP`      | pyupgrade                 | `UP006` (non-pep585-annotation), `UP007` (non-pep604-annotation), `UP035` (deprecated-import)                                                 |
+| `S`       | flake8-bandit             | `S101` (assert), `S105` (hardcoded-password-string), `S301` (suspicious-pickle-usage)                                                         |
+| `B`       | flake8-bugbear            | `B006` (mutable-argument-default), `B007` (unused-loop-control-variable), `B905` (zip-without-explicit-strict)                                |
+| `A`       | flake8-builtins           | `A001` (builtin-variable-shadowing), `A002` (builtin-argument-shadowing)                                                                      |
+| `C4`      | flake8-comprehensions     | `C400` (unnecessary-generator-list), `C401` (unnecessary-generator-set), `C408` (unnecessary-collection-call)                                 |
+| `T20`     | flake8-print              | `T201` (print), `T203` (pprint)                                                                                                               |
+| `SIM`     | flake8-simplify           | `SIM102` (collapsible-if), `SIM108` (if-else-block-instead-of-if-exp), `SIM110` (reimplemented-builtin)                                       |
+| `PL`      | pylint                    | `PLC0414` (useless-import-alias), `PLE1205` (logging-too-many-args), `PLR0913` (too-many-arguments), `PLW0602` (global-variable-not-assigned) |
+| `PTH`     | flake8-use-pathlib        | `PTH100` (os-path-abspath), `PTH118` (os-path-join), `PTH123` (builtin-open)                                                                  |
+| `RUF`     | ruff-specific             | `RUF001` (ambiguous-unicode-character), `RUF005` (collection-literal-concatenation), `RUF013` (implicit-optional)                             |
+| `D`       | pydocstyle                | `D100` (undocumented-public-module), `D103` (undocumented-public-function), `D400` (first-line-should-end-with-period)                        |
+| `ANN`     | flake8-annotations        | `ANN001` (missing-type-function-argument), `ANN201` (missing-return-type-public-function)                                                     |
+| `ARG`     | flake8-unused-arguments   | `ARG001` (unused-function-argument), `ARG002` (unused-method-argument)                                                                        |
+| `ERA`     | eradicate                 | `ERA001` (commented-out-code)                                                                                                                 |
+| `TCH`     | flake8-type-checking      | `TCH001` (typing-only-first-party-import), `TCH002` (typing-only-third-party-import)                                                          |
+| `FBT`     | flake8-boolean-trap       | `FBT001` (boolean-typed-positional-argument), `FBT002` (boolean-default-value-positional-argument)                                            |
+| `ICN`     | flake8-import-conventions | `ICN001` (unconventional-import-alias) — e.g., `import numpy as np`                                                                           |
+| `PIE`     | flake8-pie                | `PIE790` (unnecessary-placeholder), `PIE804` (no-unnecessary-dict-kwargs)                                                                     |
+| `RSE`     | flake8-raise              | `RSE102` (unnecessary-paren-on-raise-exception)                                                                                               |
+| `RET`     | flake8-return             | `RET501` (unnecessary-return-none), `RET504` (unnecessary-assign)                                                                             |
+| `TID`     | flake8-tidy-imports       | `TID252` (relative-imports) — ban relative imports                                                                                            |
+| `PERF`    | perflint                  | `PERF101` (unnecessary-list-cast), `PERF401` (manual-list-comprehension)                                                                      |
+| `FURB`    | refurb                    | `FURB105` (print-empty-string), `FURB118` (reimplemented-operator)                                                                            |
+
+**Tip:** Run `ruff rule <CODE>` to see the full description of any rule. Run `ruff linter` to see all available rule groups.
+
+## Rule Selection
+
+Configure in `pyproject.toml`:
+
+```toml
+[tool.ruff.lint]
+select = [
+  "E", "W",    # pycodestyle
+  "F",         # pyflakes
+  "I",         # isort
+  "B",         # flake8-bugbear
+  "S",         # flake8-bandit
+  "UP",        # pyupgrade
+  "SIM",       # flake8-simplify
+  "T20",       # flake8-print
+  "RUF",       # ruff-specific
+]
+ignore = [
+  "E501",      # line-too-long (handled by formatter)
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = ["S101"]  # allow assert in tests
+"__init__.py" = ["F401"]  # allow unused imports in __init__
+```
+
+Or in `ruff.toml` (same syntax without `[tool.ruff]` prefix):
+
+```toml
+[lint]
+select = ["E", "F", "I", "B"]
+```
+
+### Selecting individual rules vs groups
+
+- `"F"` enables all pyflakes rules
+- `"F401"` enables only `F401`
+- `"ALL"` enables everything (noisy — use `ignore` to subtract)
+- Use `extend-select` to add rules without overriding the default set
+
+## Custom Rules
+
+**Ruff does not support user-defined rules.** If no existing rule covers your pattern:
+
+1. **Configure existing rules** — many rules accept options (e.g., `flake8-import-conventions` lets you set allowed aliases)
+2. **Use `ruff.lint.flake8-import-conventions.aliases`** — for import alias enforcement
+3. **Use `ruff.lint.flake8-tidy-imports.banned-api`** — for banning specific imports/modules
+4. **Use ast-grep** — for arbitrary AST pattern matching, reference via `enforce()` with an ast-grep rule
+5. **Write a Pylint checker** — if you need the full power of a custom rule with AST analysis, use Pylint (Ruff can coexist with Pylint in CI)
+
+```toml
+# Ban specific APIs without a custom rule
+[tool.ruff.lint.flake8-tidy-imports.banned-api]
+"os.system".msg = "Use subprocess.run instead."
+"typing.Dict".msg = "Use dict instead (PEP 585)."
+```
+
+## Auto-Fix
+
+Ruff provides auto-fix for many rules:
+
+```bash
+ruff check --fix              # apply safe fixes only
+ruff check --fix --unsafe-fixes  # include unsafe fixes
+ruff check --fix-only         # only fix, don't report remaining violations
+```
+
+**Safe vs unsafe fixes:**
+
+- **Safe** — guaranteed to not change semantics (e.g., removing unused imports)
+- **Unsafe** — may change semantics (e.g., `UP007` rewriting `Optional[X]` to `X | None` can break runtime type checking)
+
+Check fixability per rule with `ruff rule <CODE>` — it shows whether the rule has a fix and if it's safe.
+
+### vigiles enforce() reference
+
+```typescript
+enforce("ruff/F401", "Remove unused imports.");
+enforce("ruff/T201", "Use logging module instead of print.");
+enforce("ruff/S101", "Don't use assert in production code.");
+```
+
+vigiles checks `ruff rule <CODE>` and verifies the rule exists, then parses `ruff check --show-settings` to confirm it's enabled.
+
+## Edge Cases and Gotchas
+
+### Ruff vs Pylint (PL prefix)
+
+Ruff reimplements many Pylint rules with the `PL` prefix. The mapping is not 1:1 — some Pylint rules have no Ruff equivalent, and Ruff's implementations may differ in edge cases.
+
+| Ruff code | Pylint equivalent                      | Notes         |
+| --------- | -------------------------------------- | ------------- |
+| `PLR0913` | `R0913` (too-many-arguments)           | Same behavior |
+| `PLC0414` | `C0414` (useless-import-alias)         | Same behavior |
+| `PLW0602` | `W0602` (global-variable-not-assigned) | Same behavior |
+| `PLE1205` | `E1205` (logging-too-many-args)        | Same behavior |
+
+If the project uses both Ruff and Pylint, disable Pylint rules that Ruff already covers to avoid duplicate reports.
+
+### Preview rules
+
+Some rules are behind `--preview` flag. These are not stable and may change between versions. Don't use `enforce()` on preview rules unless you pin the Ruff version.
+
+```toml
+[tool.ruff]
+preview = true  # enables preview rules
+```
+
+### Formatter vs linter conflicts
+
+Ruff has both a linter (`ruff check`) and a formatter (`ruff format`). Some linter rules conflict with the formatter:
+
+- `E501` (line-too-long) — the formatter handles line length; disable in the linter
+- `W291`/`W292`/`W293` — whitespace rules handled by formatter
+- `COM812` (missing-trailing-comma) — conflicts with formatter in some cases
+
+The Ruff docs recommend: `ignore = ["E501", "W291", "W292", "W293"]` when using `ruff format`.
+
+### Monorepo config inheritance
+
+Ruff resolves config by walking up from the file being linted. In a monorepo:
+
+- Each package can have its own `pyproject.toml` with `[tool.ruff]`
+- A root config applies to all packages unless overridden
+- Use `extend` to inherit from a shared config: `extend = "../../pyproject.toml"`
+
+vigiles discovers Ruff config at `basePath` only. In a monorepo, run vigiles from each package root.
+
+## Mapping PR Feedback to Rule Strategy
+
+| PR comment pattern            | Best approach                                                      |
+| ----------------------------- | ------------------------------------------------------------------ |
+| "Remove unused imports"       | `ruff/F401` — already exists                                       |
+| "Don't use print()"           | `ruff/T201` — already exists                                       |
+| "Sort your imports"           | `ruff/I001` — already exists                                       |
+| "Use pathlib not os.path"     | `ruff/PTH*` — enable the PTH group                                 |
+| "Don't use assert in prod"    | `ruff/S101` — already exists, ignore in tests via per-file-ignores |
+| "Remove commented-out code"   | `ruff/ERA001` — already exists                                     |
+| "Add type annotations"        | `ruff/ANN*` — enable the ANN group                                 |
+| "Use comprehensions"          | `ruff/C4*` — enable the C4 group                                   |
+| "Don't shadow builtins"       | `ruff/A001` / `A002` — already exists                              |
+| "Simplify this if"            | `ruff/SIM102` / `SIM108` — already exists                          |
+| "Don't use mutable defaults"  | `ruff/B006` — already exists                                       |
+| "Ban specific import"         | `flake8-tidy-imports.banned-api` config — no custom rule needed    |
+| "Naming convention violated"  | `ruff/N*` — enable the N group                                     |
+| "Don't use os.system"         | `flake8-tidy-imports.banned-api` config                            |
+| "Complex pattern not in Ruff" | Write a Pylint checker or use ast-grep                             |