@codacy/tools-rubocop-1

Table of Contents

• Overview
• Updating patterns
• Updating the RuboCop version
• Development
• Notes for maintainers

Overview

Ruby linter and formatter using RuboCop with 22+ plugin gems. Uses the CLI execution strategy -- spawns rubocop --format json via spawnTool() and parses its JSON output.

Updating patterns

pnpm prefetch
git add src/patterns.json

Pattern IDs use underscore-separated cop names (no prefix): Style_StringLiterals, Lint_Debugger, Metrics_MethodLength, etc.

Updating the RuboCop version

1. Update RUBOCOP_VERSION in src/adapter.ts
2. Review plugin gem compatibility -- some plugins pin specific RuboCop versions
3. Run pnpm prefetch to check for new/removed cops
4. Run pnpm test to verify compatibility
5. If the major version changes, create a new adapter package (rubocop-2/)

Development

pnpm build    # Build with tsup
pnpm test     # Run tests (requires ruby + rubocop in PATH for integration tests)

To install rubocop locally for testing:

gem install rubocop -v 1.91.0
gem install rubocop-performance rubocop-rails rubocop-rspec

Notes for maintainers

• Preset mappings (src/pattern-mappings.json): I18n_GetText_* gates on a new gettext entity (the gettext, gettext_i18n_rails or rubocop-i18n gem) and I18n_RailsI18n_* joins the existing ruby-on-rails key, since Rails I18n ships with Rails and needs no separate entity. All six were default-off and ungated before, which meant init --auto could never enable them — the two cop families are mutually exclusive in practice, so leaving both universal was the worst of both options.

• RuboCop requires Ruby >= 2.7. The adapter uses ensureRuby() for portable Ruby download.

• 22+ plugin gems are installed alongside rubocop, matching the Codacy codacy-rubocop wrapper. The full list is in GEM_PACKAGES in adapter.ts. Plugin gems are installed without version pins (except rubocop itself) to let gem resolve compatible versions.

• Gems are installed in ~/.codacy/runtimes/rubocop-1/gems/ via GEM_HOME/GEM_PATH.

• Output format is JSON with files[].offenses[] structure.

• Pattern IDs: cop_name with / replaced by _ (e.g. Style/StringLiterals → Style_StringLiterals).

• Line/column are 1-based — direct mapping, no conversion needed.

• Multi-line offenses: location.start_line/location.last_line map to Issue.line/Issue.endLine.

• Exit codes: 0 = clean, 1 = offenses found (normal success), 2 = error.

• --force-exclusion ensures config exclusions apply even for explicitly listed files.

• --cache false ensures fresh analysis on every run.

• Pattern filtering is post-hoc: RuboCop runs against all provided files with all cops, then output is filtered by the enabled patterns set.

• Config file detection supports .rubocop.yml, .config/.rubocop.yml, .config/rubocop/config.yml.