Skip to content

Commit 0a1f8aa

Browse files
matthew-on-gitclaude
matthew-on-git
and
claude
committed
docs(ruby): add Ruby standards page and update language matrix
Add content/docs/standards/ruby.md with full Ruby tooling docs. Update _index.md language support matrix and target mapping tables. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
1 parent 172af2e commit 0a1f8aa

2 files changed

Lines changed: 173 additions & 14 deletions

File tree

‎content/docs/standards/_index.md‎

Lines changed: 15 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
title: "Standards"
33
linkTitle: "Standards"
44
weight: 20
5-
description: "Per-language tooling standards for Python, Bash, Terraform, Ansible, and universal security tools."
5+
description: "Per-language tooling standards for Python, Bash, Terraform, Ansible, Ruby, and universal security tools."
66
---
77

88
DevRail defines opinionated tooling standards for each supported language ecosystem. Every tool is pre-installed in the dev-toolchain container and invoked through consistent Makefile targets.
@@ -11,15 +11,15 @@ DevRail defines opinionated tooling standards for each supported language ecosys
1111

1212
The following table shows the default tool for each concern per language. These tools are pre-installed in the `dev-toolchain` container.
1313

14-
| Concern | Python | Bash | Terraform | Ansible |
15-
|---|---|---|---|---|
16-
| Linter | ruff | shellcheck | tflint | ansible-lint |
17-
| Formatter | ruff format | shfmt | terraform fmt | -- |
18-
| Security | bandit, semgrep | -- | tfsec, checkov | -- |
19-
| Tests | pytest | bats | terratest | molecule |
20-
| Type Check | mypy | -- | -- | -- |
21-
| Docs | -- | -- | terraform-docs | -- |
22-
| Universal | trivy, gitleaks | trivy, gitleaks | trivy, gitleaks | trivy, gitleaks |
14+
| Concern | Python | Bash | Terraform | Ansible | Ruby |
15+
|---|---|---|---|---|---|
16+
| Linter | ruff | shellcheck | tflint | ansible-lint | rubocop, reek |
17+
| Formatter | ruff format | shfmt | terraform fmt | -- | rubocop |
18+
| Security | bandit, semgrep | -- | tfsec, checkov | -- | brakeman, bundler-audit |
19+
| Tests | pytest | bats | terratest | molecule | rspec |
20+
| Type Check | mypy | -- | -- | -- | sorbet |
21+
| Docs | -- | -- | terraform-docs | -- | -- |
22+
| Universal | trivy, gitleaks | trivy, gitleaks | trivy, gitleaks | trivy, gitleaks | trivy, gitleaks |
2323

2424
A `--` entry means the concern does not apply to that language. Universal tools run for all projects regardless of declared languages.
2525

@@ -29,10 +29,10 @@ Each Makefile target runs the relevant tools for all languages declared in `.dev
2929

3030
| Target | What It Runs |
3131
|---|---|
32-
| `make lint` | ruff check, shellcheck, tflint, ansible-lint, mypy |
33-
| `make format` | ruff format, shfmt, terraform fmt |
34-
| `make test` | pytest, bats, terratest, molecule |
35-
| `make security` | bandit, semgrep, tfsec, checkov |
32+
| `make lint` | ruff check, shellcheck, tflint, ansible-lint, mypy, rubocop, reek |
33+
| `make format` | ruff format, shfmt, terraform fmt, rubocop |
34+
| `make test` | pytest, bats, terratest, molecule, rspec |
35+
| `make security` | bandit, semgrep, tfsec, checkov, brakeman, bundler-audit |
3636
| `make scan` | trivy, gitleaks (universal -- all projects) |
3737
| `make docs` | terraform-docs |
3838
| `make check` | All of the above in sequence |
@@ -43,6 +43,7 @@ Each Makefile target runs the relevant tools for all languages declared in `.dev
4343
- [Bash Standards](/docs/standards/bash/) -- shellcheck, shfmt, bats
4444
- [Terraform Standards](/docs/standards/terraform/) -- tflint, terraform fmt, tfsec, checkov, terratest, terraform-docs
4545
- [Ansible Standards](/docs/standards/ansible/) -- ansible-lint, molecule
46+
- [Ruby Standards](/docs/standards/ruby/) -- rubocop, brakeman, bundler-audit, rspec, reek, sorbet
4647
- [Universal Security](/docs/standards/universal/) -- trivy, gitleaks
4748

4849
## Consistent Page Structure

‎content/docs/standards/ruby.md‎

Lines changed: 158 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,158 @@
1+
---
2+
title: "Ruby"
3+
linkTitle: "Ruby"
4+
weight: 25
5+
description: "Ruby and Rails tooling standards: rubocop, brakeman, bundler-audit, rspec, reek, and sorbet."
6+
---
7+
8+
Ruby projects use rubocop for linting and formatting, brakeman and bundler-audit for security, rspec for testing, reek for code smell detection, and optionally sorbet for type checking.
9+
10+
## Tools
11+
12+
| Category | Tool | Purpose |
13+
|---|---|---|
14+
| Linter + Formatter | rubocop | Style enforcement and auto-correction |
15+
| Linter (Rails) | rubocop-rails | Rails-specific rubocop rules |
16+
| Linter (RSpec) | rubocop-rspec | RSpec-specific rubocop rules |
17+
| Linter (Perf) | rubocop-performance | Performance-focused rubocop rules |
18+
| Security | brakeman | Static analysis for Rails security vulnerabilities |
19+
| Security | bundler-audit | Checks Gemfile.lock for known vulnerable gems |
20+
| Tests | rspec | Ruby test framework |
21+
| Code Smells | reek | Detects code smells (feature envy, long methods, etc.) |
22+
| Type Check | sorbet | Gradual static type checker for Ruby |
23+
24+
All tools are pre-installed in the dev-toolchain container. Do not install them on the host.
25+
26+
## Configuration
27+
28+
### rubocop
29+
30+
Config file: `.rubocop.yml` at repository root.
31+
32+
```yaml
33+
# .rubocop.yml -- DevRail Ruby style configuration
34+
require:
35+
- rubocop-rails
36+
- rubocop-rspec
37+
- rubocop-performance
38+
39+
AllCops:
40+
TargetRubyVersion: 3.4
41+
NewCops: enable
42+
Exclude:
43+
- "db/schema.rb"
44+
- "bin/**/*"
45+
- "vendor/**/*"
46+
- "node_modules/**/*"
47+
48+
Style/Documentation:
49+
Enabled: false
50+
51+
Metrics/BlockLength:
52+
Exclude:
53+
- "spec/**/*"
54+
- "config/routes.rb"
55+
56+
Layout/LineLength:
57+
Max: 120
58+
```
59+
60+
rubocop handles both linting and formatting. Do not use standardrb or prettier-ruby separately.
61+
62+
### reek
63+
64+
Config file: `.reek.yml` at repository root.
65+
66+
```yaml
67+
# .reek.yml -- code smell detection configuration
68+
exclude_paths:
69+
- vendor
70+
- db/schema.rb
71+
- bin
72+
73+
detectors:
74+
IrresponsibleModule:
75+
enabled: false
76+
UncommunicativeVariableName:
77+
accept:
78+
- e
79+
- i
80+
- k
81+
- v
82+
```
83+
84+
### rspec
85+
86+
Config file: `.rspec` at repository root.
87+
88+
```text
89+
--require spec_helper
90+
--format documentation
91+
--color
92+
```
93+
94+
### sorbet
95+
96+
Config file: `sorbet/config` at repository root.
97+
98+
```text
99+
--dir
100+
.
101+
--ignore=vendor/
102+
--ignore=db/
103+
--ignore=bin/
104+
```
105+
106+
Sorbet uses typed signatures (`# typed: strict`, `# typed: true`, etc.) at the top of each file. Start with `# typed: false` and incrementally adopt stricter levels.
107+
108+
### brakeman
109+
110+
No config file required. Brakeman scans Rails applications for common security vulnerabilities (SQL injection, XSS, mass assignment, etc.). It only runs for Rails projects (detected by the presence of `config/application.rb`).
111+
112+
### bundler-audit
113+
114+
No config file required. Scans `Gemfile.lock` for known vulnerable gem versions. Run `bundler-audit update` periodically to refresh the advisory database.
115+
116+
## Makefile Targets
117+
118+
| Target | Command | Description |
119+
|---|---|---|
120+
| `make lint` | `rubocop .` | Lint all Ruby files |
121+
| `make lint` | `reek .` | Detect code smells |
122+
| `make format` | `rubocop --check --fail-level error .` | Check formatting (no changes) |
123+
| `make security` | `brakeman -q` | Rails security scanning (Rails only) |
124+
| `make security` | `bundler-audit check` | Dependency vulnerability scanning |
125+
| `make test` | `rspec` | Run test suite (if `spec/` exists) |
126+
127+
## Pre-Commit Hooks
128+
129+
### Local Hooks (run on every commit, under 30 seconds)
130+
131+
rubocop runs on every commit to catch style and formatting issues:
132+
133+
```yaml
134+
# .pre-commit-config.yaml -- Ruby hooks
135+
repos:
136+
- repo: https://github.com/rubocop/rubocop
137+
rev: "" # container manages version
138+
hooks:
139+
- id: rubocop
140+
```
141+
142+
### CI-Only (too slow for local hooks)
143+
144+
- `brakeman -q` -- Rails security scanning
145+
- `bundler-audit check` -- dependency vulnerability scanning
146+
- `rspec` -- full test suite
147+
- `reek .` -- code smell detection (when project is large)
148+
- `sorbet` -- type checking (when project adopts typed signatures)
149+
150+
## Notes
151+
152+
- **rubocop is the single tool for both linting and formatting.** Do not use standardrb or prettier-ruby.
153+
- **`rubocop-rails`, `rubocop-rspec`, and `rubocop-performance`** are rubocop extensions loaded via `require:` in `.rubocop.yml`. They are not standalone CLI tools.
154+
- **`brakeman` only runs for Rails applications.** It is skipped if `config/application.rb` is not present.
155+
- **`bundler-audit` only runs if `Gemfile.lock` exists.** It checks for known vulnerabilities in declared gem dependencies.
156+
- **`reek` runs as part of `make lint`.** It detects code smells (feature envy, too-many-instance-variables, data clump, etc.).
157+
- **`sorbet` is optional.** Projects can incrementally adopt it by adding `# typed:` sigils to Ruby files. The `sorbet-runtime` gem provides runtime type annotations.
158+
- **All tools are pre-installed in the dev-toolchain container.** Do not install them on the host.

0 commit comments

Comments
 (0)