diff --git a/.cursorrules b/.cursorrules index 8f5e1e8..49e7dbc 100644 --- a/.cursorrules +++ b/.cursorrules @@ -19,6 +19,10 @@ Critical Rules: 6. Use the shared logging library. No raw `echo` for status messages. Use `log_info`, `log_warn`, `log_error`, `log_debug`, and `die` from `lib/log.sh`. +7. Never suppress failing checks. When a lint, format, security, or test + check fails, fix the underlying issue. Never comment out code, add + suppression annotations, disable rules, or mark CI jobs as + allowed-to-fail to bypass a failing check. Quick Reference: diff --git a/.opencode/agents.yaml b/.opencode/agents.yaml index 9139b88..6cfa2f0 100644 --- a/.opencode/agents.yaml +++ b/.opencode/agents.yaml @@ -24,6 +24,10 @@ agents: 6. Use the shared logging library. No raw `echo` for status messages. Use `log_info`, `log_warn`, `log_error`, `log_debug`, and `die` from `lib/log.sh`. + 7. Never suppress failing checks. When a lint, format, security, or test + check fails, fix the underlying issue. Never comment out code, add + suppression annotations, disable rules, or mark CI jobs as + allowed-to-fail to bypass a failing check. Quick Reference: diff --git a/AGENTS.md b/AGENTS.md index b071133..5237e60 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -11,6 +11,7 @@ See DEVELOPMENT.md for the complete reference. 4. **Respect `.editorconfig`.** Never override formatting rules (indent style, line endings, trailing whitespace) without explicit instruction. 5. **Write idempotent scripts.** Every script must be safe to re-run. Check before acting: `command -v tool || install_tool`, `mkdir -p`, guard file writes with existence checks. 6. **Use the shared logging library.** No raw `echo` for status messages. Use `log_info`, `log_warn`, `log_error`, `log_debug`, and `die` from `lib/log.sh`. +7. **Never suppress failing checks.** When a lint, format, security, or test check fails, fix the underlying issue. Never comment out code, add suppression annotations, disable rules, or mark CI jobs as allowed-to-fail to bypass a failing check. ## Quick Reference diff --git a/CLAUDE.md b/CLAUDE.md index e140bf6..0ee5d72 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -11,6 +11,7 @@ See DEVELOPMENT.md for the complete reference. 4. **Respect `.editorconfig`.** Never override formatting rules (indent style, line endings, trailing whitespace) without explicit instruction. 5. **Write idempotent scripts.** Every script must be safe to re-run. Check before acting: `command -v tool || install_tool`, `mkdir -p`, guard file writes with existence checks. 6. **Use the shared logging library.** No raw `echo` for status messages. Use `log_info`, `log_warn`, `log_error`, `log_debug`, and `die` from `lib/log.sh`. +7. **Never suppress failing checks.** When a lint, format, security, or test check fails, fix the underlying issue. Never comment out code, add suppression annotations, disable rules, or mark CI jobs as allowed-to-fail to bypass a failing check. ## Quick Reference diff --git a/content/_index.md b/content/_index.md index 15b11ce..418a646 100644 --- a/content/_index.md +++ b/content/_index.md @@ -70,6 +70,9 @@ the retrofit guide at: https://devrail.dev/docs/getting-started/retrofit/ 4. Respect `.editorconfig` formatting rules. 5. Write idempotent scripts. Check before acting. 6. Read DEVELOPMENT.md in the repo for full standards reference. +7. Never suppress failing checks. Fix the root cause, don't comment + out code, add suppression annotations, or mark CI jobs as + allowed-to-fail. ## Available Make Targets - `make lint` — run all linters @@ -84,7 +87,7 @@ the retrofit guide at: https://devrail.dev/docs/getting-started/retrofit/ ## Language Detection Languages are declared in `.devrail.yml`. The Makefile reads this file to determine which tools to run. Supported languages: -python, bash, terraform, ansible, ruby, go, javascript +python, bash, terraform, ansible, ruby, go, javascript, rust See https://devrail.dev/docs/standards/ for per-language tool details. ``` @@ -110,7 +113,7 @@ Run `make check` and get consistent results everywhere -- your laptop, CI, or an {{% /blocks/feature %}} {{% blocks/feature icon="fa-cube" title="One Container" %}} -The `dev-toolchain` container includes linters, formatters, security scanners, and test runners for Python, Bash, Terraform, Ansible, Ruby, Go, and JavaScript/TypeScript. Pin a version and forget about tool management. +The `dev-toolchain` container includes linters, formatters, security scanners, and test runners for Python, Bash, Terraform, Ansible, Ruby, Go, JavaScript/TypeScript, and Rust. Pin a version and forget about tool management. [Learn About the Container](/docs/container/) {{% /blocks/feature %}} diff --git a/content/blog/2026-03-02-introducing-devrail.md b/content/blog/2026-03-02-introducing-devrail.md index 7b7143f..840dd47 100644 --- a/content/blog/2026-03-02-introducing-devrail.md +++ b/content/blog/2026-03-02-introducing-devrail.md @@ -51,14 +51,14 @@ Already have a project? The [retrofit guide](/docs/getting-started/retrofit/) wa ## What's in the Container -The `dev-toolchain` container includes tools for seven language ecosystems. Each language has opinionated defaults documented in the [standards reference](/docs/standards/). +The `dev-toolchain` container includes tools for eight language ecosystems. Each language has opinionated defaults documented in the [standards reference](/docs/standards/). -| Concern | Python | Bash | Terraform | Ansible | Ruby | Go | JS/TS | -|---|---|---|---|---|---|---|---| -| Linter | ruff | shellcheck | tflint | ansible-lint | rubocop | golangci-lint | eslint | -| Formatter | ruff | shfmt | terraform fmt | -- | rubocop | gofumpt | prettier | -| Security | bandit | -- | tfsec | -- | brakeman | govulncheck | npm audit | -| Tests | pytest | bats | terratest | molecule | rspec | go test | vitest | +| Concern | Python | Bash | Terraform | Ansible | Ruby | Go | JS/TS | Rust | +|---|---|---|---|---|---|---|---|---| +| Linter | ruff | shellcheck | tflint | ansible-lint | rubocop | golangci-lint | eslint | clippy | +| Formatter | ruff | shfmt | terraform fmt | -- | rubocop | gofumpt | prettier | rustfmt | +| Security | bandit | -- | tfsec | -- | brakeman | govulncheck | npm audit | cargo-audit | +| Tests | pytest | bats | terratest | molecule | rspec | go test | vitest | cargo test | Universal tools -- trivy, gitleaks, and git-cliff -- run for every project regardless of language. @@ -76,7 +76,7 @@ See the [agent setup guide](/docs/getting-started/agents/) for detailed configur ## Current Status -DevRail is in **beta**. The core contract -- Makefile, container, `.devrail.yml` -- is stable and used in production projects. Language support for all seven ecosystems ships in the `v1` container image. Standards, tool versions, and defaults may still change based on real-world usage. +DevRail is in **beta**. The core contract -- Makefile, container, `.devrail.yml` -- is stable and used in production projects. Language support for all eight ecosystems ships in the `v1` container image. Standards, tool versions, and defaults may still change based on real-world usage. What works today: new projects from templates, retrofitting existing repos, CI integration, agent instruction files, and `make fix` auto-remediation. What's still evolving: additional language ecosystems and edge cases we haven't hit yet. diff --git a/content/docs/standards/_index.md b/content/docs/standards/_index.md index 60b9378..daeb0e8 100644 --- a/content/docs/standards/_index.md +++ b/content/docs/standards/_index.md @@ -2,7 +2,7 @@ title: "Standards" linkTitle: "Standards" weight: 20 -description: "Per-language tooling standards for Python, Bash, Terraform, Ansible, Ruby, Go, JavaScript/TypeScript, and universal security tools." +description: "Per-language tooling standards for Python, Bash, Terraform, Ansible, Ruby, Go, JavaScript/TypeScript, Rust, and universal security tools." --- 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 The following table shows the default tool for each concern per language. These tools are pre-installed in the `dev-toolchain` container. -| Concern | Python | Bash | Terraform | Ansible | Ruby | Go | JavaScript | -|---|---|---|---|---|---|---|---| -| Linter | ruff | shellcheck | tflint | ansible-lint | rubocop, reek | golangci-lint | eslint | -| Formatter | ruff format | shfmt | terraform fmt | -- | rubocop | gofumpt | prettier | -| Security | bandit, semgrep | -- | tfsec, checkov | -- | brakeman, bundler-audit | govulncheck | npm audit | -| Tests | pytest | bats | terratest | molecule | rspec | go test | vitest | -| Type Check | mypy | -- | -- | -- | sorbet | -- | tsc | -| Docs | -- | -- | terraform-docs | -- | -- | -- | -- | -| Universal | trivy, gitleaks, git-cliff | trivy, gitleaks, git-cliff | trivy, gitleaks, git-cliff | trivy, gitleaks, git-cliff | trivy, gitleaks, git-cliff | trivy, gitleaks, git-cliff | trivy, gitleaks, git-cliff | +| Concern | Python | Bash | Terraform | Ansible | Ruby | Go | JavaScript | Rust | +|---|---|---|---|---|---|---|---|---| +| Linter | ruff | shellcheck | tflint | ansible-lint | rubocop, reek | golangci-lint | eslint | clippy | +| Formatter | ruff format | shfmt | terraform fmt | -- | rubocop | gofumpt | prettier | rustfmt | +| Security | bandit, semgrep | -- | tfsec, checkov | -- | brakeman, bundler-audit | govulncheck | npm audit | cargo-audit, cargo-deny | +| Tests | pytest | bats | terratest | molecule | rspec | go test | vitest | cargo test | +| Type Check | mypy | -- | -- | -- | sorbet | -- | tsc | -- | +| Docs | -- | -- | terraform-docs | -- | -- | -- | -- | -- | +| Universal | trivy, gitleaks, git-cliff | trivy, gitleaks, git-cliff | trivy, gitleaks, git-cliff | trivy, gitleaks, git-cliff | trivy, gitleaks, git-cliff | trivy, gitleaks, git-cliff | trivy, gitleaks, git-cliff | trivy, gitleaks, git-cliff | A `--` entry means the concern does not apply to that language. Universal tools run for all projects regardless of declared languages. @@ -29,11 +29,11 @@ Each Makefile target runs the relevant tools for all languages declared in `.dev | Target | What It Runs | |---|---| -| `make lint` | ruff check, shellcheck, tflint, ansible-lint, mypy, rubocop, reek, golangci-lint, eslint, tsc | -| `make format` | ruff format --check, shfmt -d, terraform fmt -check, rubocop --check, gofumpt -d, prettier --check | -| `make fix` | ruff format, shfmt -w, terraform fmt, rubocop -a, gofumpt -w, prettier --write | -| `make test` | pytest, bats, terratest, molecule, rspec, go test, vitest | -| `make security` | bandit, semgrep, tfsec, checkov, brakeman, bundler-audit, govulncheck, npm audit | +| `make lint` | ruff check, shellcheck, tflint, ansible-lint, mypy, rubocop, reek, golangci-lint, eslint, tsc, clippy | +| `make format` | ruff format --check, shfmt -d, terraform fmt -check, rubocop --check, gofumpt -d, prettier --check, cargo fmt --check | +| `make fix` | ruff format, shfmt -w, terraform fmt, rubocop -a, gofumpt -w, prettier --write, cargo fmt | +| `make test` | pytest, bats, terratest, molecule, rspec, go test, vitest, cargo test | +| `make security` | bandit, semgrep, tfsec, checkov, brakeman, bundler-audit, govulncheck, npm audit, cargo-audit, cargo-deny | | `make scan` | trivy, gitleaks (universal -- all projects) | | `make docs` | terraform-docs | | `make changelog` | git-cliff (generate CHANGELOG.md from conventional commits) | @@ -49,6 +49,7 @@ Each Makefile target runs the relevant tools for all languages declared in `.dev - [Ruby Standards](/docs/standards/ruby/) -- rubocop, brakeman, bundler-audit, rspec, reek, sorbet - [Go Standards](/docs/standards/go/) -- golangci-lint, gofumpt, govulncheck, go test - [JavaScript Standards](/docs/standards/javascript/) -- eslint, prettier, npm audit, vitest, tsc +- [Rust Standards](/docs/standards/rust/) -- clippy, rustfmt, cargo-audit, cargo-deny, cargo test - [Universal Security](/docs/standards/universal/) -- trivy, gitleaks, git-cliff ## Consistent Page Structure diff --git a/content/docs/standards/rust.md b/content/docs/standards/rust.md new file mode 100644 index 0000000..9d20755 --- /dev/null +++ b/content/docs/standards/rust.md @@ -0,0 +1,129 @@ +--- +title: "Rust" +linkTitle: "Rust" +weight: 35 +description: "Rust tooling standards: clippy, rustfmt, cargo-audit, cargo-deny, and cargo test." +--- + +Rust projects use clippy for linting, rustfmt for formatting, cargo-audit and cargo-deny for security scanning, and cargo test for testing. + +## Tools + +| Category | Tool | Purpose | +|---|---|---| +| Linter | clippy | Official Rust linter (rustup component) | +| Formatter | rustfmt | Official Rust formatter (rustup component) | +| Security (vulns) | cargo-audit | Scans Cargo.lock for known vulnerabilities | +| Security (policy) | cargo-deny | Enforces dependency policies (licenses, bans, sources) | +| Tests | cargo test | Built-in Rust test runner | + +All tools are pre-installed in the dev-toolchain container. Do not install them on the host. + +## Configuration + +### clippy + +Config file: `clippy.toml` at repository root. + +```toml +# clippy.toml -- DevRail Rust clippy configuration +# See: https://doc.rust-lang.org/clippy/lint_configuration.html +too-many-arguments-threshold = 7 +``` + +Clippy is invoked with `-D warnings` to treat all warnings as errors. Additional lint groups can be enabled via `#![warn(clippy::pedantic)]` in `lib.rs` or `main.rs`. + +### rustfmt + +Config file: `rustfmt.toml` at repository root. + +```toml +# rustfmt.toml -- DevRail Rust formatter configuration +edition = "2021" +max_width = 100 +use_field_init_shorthand = true +use_try_shorthand = true +``` + +### cargo-audit + +No config file required. Scans `Cargo.lock` for known vulnerabilities in crate dependencies using the RustSec Advisory Database. + +### cargo-deny + +Config file: `deny.toml` at repository root. + +```toml +# deny.toml -- DevRail cargo-deny configuration +# See: https://embarkstudios.github.io/cargo-deny/ + +[advisories] +vulnerability = "deny" +unmaintained = "warn" +yanked = "warn" + +[licenses] +unlicensed = "deny" +allow = [ + "MIT", + "Apache-2.0", + "BSD-2-Clause", + "BSD-3-Clause", + "ISC", + "Unicode-3.0", + "Unicode-DFS-2016", +] + +[bans] +multiple-versions = "warn" + +[sources] +unknown-registry = "deny" +unknown-git = "warn" +``` + +## Makefile Targets + +| Target | Command | Description | +|---|---|---| +| `make lint` | `cargo clippy --all-targets --all-features -- -D warnings` | Lint all Rust files | +| `make format` | `cargo fmt --all -- --check` | Check formatting | +| `make fix` | `cargo fmt --all` | Apply formatting fixes | +| `make security` | `cargo audit` | Dependency vulnerability scanning (if `Cargo.lock` exists) | +| `make security` | `cargo deny check` | Dependency policy checking (if `deny.toml` exists) | +| `make test` | `cargo test --all-targets` | Run test suite (if `*.rs` files and `Cargo.toml` exist) | + +## Pre-Commit Hooks + +### Local Hooks (run on every commit, under 30 seconds) + +Formatting and linting with cargo via pre-commit-cargo: + +```yaml +# .pre-commit-config.yaml -- Rust hooks +repos: + - repo: https://github.com/AndrejOrsula/pre-commit-cargo + rev: v0.4.0 + hooks: + - id: cargo-fmt + args: ["--all", "--", "--check"] + - id: cargo-clippy + args: ["--all-targets", "--all-features", "--workspace", "--", "-D", "warnings"] +``` + +### CI-Only (too slow for local hooks) + +- `cargo audit` -- dependency vulnerability scanning +- `cargo deny check` -- dependency policy enforcement +- `cargo test --all-targets` -- full test suite + +## Notes + +- **Clippy is the single linting tool.** It is the official Rust linter, bundled as a rustup component. It subsumes many standalone lint tools. +- **rustfmt is the single formatting tool.** It is the official Rust formatter, also bundled as a rustup component. There is no "strict superset" -- rustfmt is the standard. +- **The entire Rust toolchain is included in the container.** Clippy and rustfmt are tightly coupled to the compiler version. The full toolchain (rustup + cargo + rustc + stdlib) is COPY'd from the builder stage. +- **`Cargo.lock` presence gates vulnerability scanning.** If no `Cargo.lock` file exists, `cargo audit` is skipped because there are no pinned dependencies to scan. +- **`deny.toml` presence gates policy checking.** If no `deny.toml` file exists, `cargo deny` is skipped. +- **`cargo test --all-targets` runs all test types.** This includes unit tests, integration tests, doc tests, and examples. It gates on the presence of `*.rs` files and `Cargo.toml`. +- **All tools are pre-installed in the dev-toolchain container.** Do not install them on the host. +- For cross-cutting coding practices and git workflow standards that apply to all languages, see [Coding Practices](/docs/standards/practices/).