fix(makefile): rails make check honours .bundle/config + bundle exec + db:test:prepare (#30) (#32)

Three coordinated fixes so that running `make check` against a Rails 7+
project actually mirrors what its CI does. Each gap is small on its own;
together they're the difference between "consumer copies the Makefile and
gets a CI-equivalent local check" and "consumer hits three errors in
sequence and gives up." Closes #30.

Gap A — DOCKER_RUN now passes -e BUNDLE_APP_CONFIG=/workspace/.bundle when
HAS_RUBY is detected. The container exports BUNDLE_APP_CONFIG=/usr/local/bundle
by default (so its bundled tools resolve), which silently overrode the
project's .bundle/config (e.g. `BUNDLE_PATH: vendor/bundle`). Now the
project's config wins for Ruby projects. Required moving the LANGUAGES /
HAS_<LANG> filter computation above DOCKER_RUN so the new env flag could
key off HAS_RUBY at make-time.

Gap B — _test Ruby branch detects Rails (config/application.rb + Gemfile)
and runs `bundle exec rails db:test:prepare` before `rspec`. On
DB-unreachable failures the loader emits a structured error event with a
clear hint ("ensure your test database is reachable") rather than letting
200+ specs fail with cryptic errors. Non-Rails Ruby projects continue to
call rspec directly. Postgres-as-consumer-responsibility documented in
STABILITY.md.

Gap C — _lint/_format/_fix/_test/_security wrap rubocop/reek/brakeman/
bundler-audit/rspec with `bundle exec` ONLY when the tool is pinned in
Gemfile.lock. Implemented via a Make function:

    RUBY_EXEC_FOR = $(if $(and $(wildcard Gemfile.lock),$(shell grep ...)),bundle exec ,)

Per-tool detection avoids breaking projects with a Gemfile but no
project-pinned rubocop (which would otherwise fail "could not find
rubocop in any of the sources"). Falls back to the container's bundled
tool when the project does not pin it.

Tested:
- tests/smoke-rails.sh: extended with a 4th check that creates a project
  .bundle/config with `BUNDLE_PATH: vendor/bundle` and verifies the
  container's `bundle config get path` resolves to it. All 4 checks pass.
- make _check on dev-toolchain itself: pass (no-op for non-Ruby self-check).

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: matthew-on-git

CHANGELOG.md

@@ -7,6 +7,37 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Fixed
+
+- Rails projects can now run a CI-equivalent `make check` against their actual
+  Gemfile-pinned tools, test database, and `.bundle/config` (#30):
+  - **Gap A — `BUNDLE_APP_CONFIG` override.** `DOCKER_RUN` now passes
+    `-e BUNDLE_APP_CONFIG=/workspace/.bundle` when `HAS_RUBY` is detected, so
+    the project's `.bundle/config` (e.g. `BUNDLE_PATH: vendor/bundle`) wins
+    over the container's `/usr/local/bundle` default. Previously, projects
+    with a sandboxed bundle silently lost their config and bundler couldn't
+    find their gems.
+  - **Gap B — `_test` runs `bundle exec rails db:test:prepare` before rspec.**
+    Detected by `config/application.rb` + `Gemfile` presence. On DB-unreachable
+    failures the loader emits a structured `error` event with a clear hint
+    ("ensure your test database is reachable, e.g. start postgres before
+    make test") rather than letting 200+ specs fail with cryptic errors.
+    Non-Rails Ruby projects continue to call `rspec` directly.
+  - **Gap C — `bundle exec` wrapping for project-pinned tools.** `_lint`,
+    `_format`, `_fix`, `_test`, `_security` now use `bundle exec <tool>`
+    when the tool is present in the project's `Gemfile.lock`. Falls back to
+    the container's tool when the project does not pin it. Eliminates lint
+    diffs caused by version drift between the container's rubocop/reek/
+    brakeman/bundler-audit/rspec and the project's pinned versions.
+- `STABILITY.md` documents the new "you provide a reachable Postgres for
+  Rails projects with DB-touching specs" expectation.
+
+### Added
+
+- `tests/smoke-rails.sh` — fourth assertion: with a project-local
+  `.bundle/config` declaring `BUNDLE_PATH: vendor/bundle`, the container
+  honours it (validates Gap A's fix end-to-end).
+
 ## [1.9.1] - 2026-04-29
 
 ### Fixed

Makefile

@@ -33,18 +33,18 @@ DEVRAIL_ENV_FLAGS := $(shell yq -r '.env // {} | to_entries | .[] | "-e " + .key
 # Non-existent paths are filtered out at runtime.
 RUBY_PATHS         ?= app lib spec config bin
 
-DOCKER_RUN := docker run --rm \
-	-v "$$(pwd):/workspace" \
-	-w /workspace \
-	-e DEVRAIL_FAIL_FAST=$(DEVRAIL_FAIL_FAST) \
-	-e DEVRAIL_LOG_FORMAT=$(DEVRAIL_LOG_FORMAT) \
-	$(DEVRAIL_ENV_FLAGS) \
-	$(DEVRAIL_IMAGE):$(DEVRAIL_TAG)
-
-.DEFAULT_GOAL := help
+# Prefer `bundle exec <tool>` ONLY when the project pins that specific tool
+# in its Gemfile.lock. Otherwise fall back to the container's bundled tool.
+# This gives projects with project-pinned versions consistency with CI without
+# breaking projects that just declare `languages: [ruby]` and rely on the
+# container's defaults. Issue #30 Gap C.
+# Usage in recipes: $(call RUBY_EXEC_FOR,rubocop)rubocop $$ruby_paths
+RUBY_EXEC_FOR = $(if $(and $(wildcard Gemfile.lock),$(shell grep -m1 -E "^[[:space:]]+$(1)[[:space:]]" Gemfile.lock 2>/dev/null)),bundle exec ,)
 
 # ---------------------------------------------------------------------------
 # .devrail.yml language detection (runs inside container where yq is available)
+# Computed before DOCKER_RUN so HAS_<LANG> can influence container env (e.g.
+# BUNDLE_APP_CONFIG override for Ruby projects — issue #30).
 # ---------------------------------------------------------------------------
 LANGUAGES      := $(shell yq '.languages[]' $(DEVRAIL_CONFIG) 2>/dev/null)
 HAS_PYTHON     := $(filter python,$(LANGUAGES))
@@ -58,6 +58,23 @@ HAS_RUST       := $(filter rust,$(LANGUAGES))
 HAS_SWIFT      := $(filter swift,$(LANGUAGES))
 HAS_KOTLIN     := $(filter kotlin,$(LANGUAGES))
 
+# When HAS_RUBY, override the container's default BUNDLE_APP_CONFIG so the
+# project's `.bundle/config` (e.g. `BUNDLE_PATH: vendor/bundle`) wins. Without
+# this, the container's own `/usr/local/bundle` config silently overrides the
+# project's, and bundler can't find project-installed gems (issue #30 Gap A).
+RUBY_DOCKER_ENV := $(if $(HAS_RUBY),-e BUNDLE_APP_CONFIG=/workspace/.bundle,)
+
+DOCKER_RUN := docker run --rm \
+	-v "$$(pwd):/workspace" \
+	-w /workspace \
+	-e DEVRAIL_FAIL_FAST=$(DEVRAIL_FAIL_FAST) \
+	-e DEVRAIL_LOG_FORMAT=$(DEVRAIL_LOG_FORMAT) \
+	$(DEVRAIL_ENV_FLAGS) \
+	$(RUBY_DOCKER_ENV) \
+	$(DEVRAIL_IMAGE):$(DEVRAIL_TAG)
+
+.DEFAULT_GOAL := help
+
 # ---------------------------------------------------------------------------
 # .PHONY declarations
 # ---------------------------------------------------------------------------
@@ -240,7 +257,7 @@ _lint: _check-config
 		for p in $(RUBY_PATHS); do [ -d "$$p" ] && ruby_paths="$$ruby_paths $$p"; done; \
 		ruby_paths=$${ruby_paths# }; \
 		if [ -n "$$ruby_paths" ]; then \
-			rubocop $$ruby_paths || { overall_exit=1; failed_languages="$${failed_languages}\"ruby:rubocop\","; }; \
+			$(call RUBY_EXEC_FOR,rubocop)rubocop $$ruby_paths || { overall_exit=1; failed_languages="$${failed_languages}\"ruby:rubocop\","; }; \
 		else \
 			echo '{"level":"info","msg":"skipping ruby rubocop lint: none of RUBY_PATHS exist (override with RUBY_PATHS=...)","language":"ruby"}' >&2; \
 		fi; \
@@ -251,7 +268,7 @@ _lint: _check-config
 			exit $$overall_exit; \
 		fi; \
 		if [ -n "$$ruby_paths" ]; then \
-			reek $$ruby_paths || { overall_exit=1; failed_languages="$${failed_languages}\"ruby:reek\","; }; \
+			$(call RUBY_EXEC_FOR,reek)reek $$ruby_paths || { overall_exit=1; failed_languages="$${failed_languages}\"ruby:reek\","; }; \
 		fi; \
 		if [ "$(DEVRAIL_FAIL_FAST)" = "1" ] && [ $$overall_exit -ne 0 ]; then \
 			end_time=$$(date +%s%3N); \
@@ -431,7 +448,7 @@ _format: _check-config
 		for p in $(RUBY_PATHS); do [ -d "$$p" ] && ruby_paths="$$ruby_paths $$p"; done; \
 		ruby_paths=$${ruby_paths# }; \
 		if [ -n "$$ruby_paths" ]; then \
-			rubocop --check --fail-level error $$ruby_paths || { overall_exit=1; failed_languages="$${failed_languages}\"ruby\","; }; \
+			$(call RUBY_EXEC_FOR,rubocop)rubocop --check --fail-level error $$ruby_paths || { overall_exit=1; failed_languages="$${failed_languages}\"ruby\","; }; \
 		else \
 			echo '{"level":"info","msg":"skipping ruby format: none of RUBY_PATHS exist (override with RUBY_PATHS=...)","language":"ruby"}' >&2; \
 		fi; \
@@ -581,7 +598,7 @@ _fix: _check-config
 		for p in $(RUBY_PATHS); do [ -d "$$p" ] && ruby_paths="$$ruby_paths $$p"; done; \
 		ruby_paths=$${ruby_paths# }; \
 		if [ -n "$$ruby_paths" ]; then \
-			rubocop -a $$ruby_paths || { overall_exit=1; failed_languages="$${failed_languages}\"ruby\","; }; \
+			$(call RUBY_EXEC_FOR,rubocop)rubocop -a $$ruby_paths || { overall_exit=1; failed_languages="$${failed_languages}\"ruby\","; }; \
 		else \
 			echo '{"level":"info","msg":"skipping ruby fix: none of RUBY_PATHS exist (override with RUBY_PATHS=...)","language":"ruby"}' >&2; \
 		fi; \
@@ -746,7 +763,18 @@ _test: _check-config
 	if [ -n "$(HAS_RUBY)" ]; then \
 		if [ -d "spec" ]; then \
 			ran_languages="$${ran_languages}\"ruby\","; \
-			rspec || { overall_exit=1; failed_languages="$${failed_languages}\"ruby\","; }; \
+			if [ -f "config/application.rb" ] && [ -f "Gemfile" ]; then \
+				echo '{"level":"info","msg":"detected Rails app — running db:test:prepare before rspec","language":"ruby"}' >&2; \
+				if ! bundle exec rails db:test:prepare 2>/tmp/_devrail_rails_db_err; then \
+					cat /tmp/_devrail_rails_db_err >&2; \
+					echo '{"level":"error","msg":"db:test:prepare failed — ensure your test database is reachable (e.g. start postgres before make test)","language":"ruby"}' >&2; \
+					overall_exit=1; failed_languages="$${failed_languages}\"ruby:db-prepare\","; \
+				else \
+					$(call RUBY_EXEC_FOR,rspec)rspec || { overall_exit=1; failed_languages="$${failed_languages}\"ruby\","; }; \
+				fi; \
+			else \
+				$(call RUBY_EXEC_FOR,rspec)rspec || { overall_exit=1; failed_languages="$${failed_languages}\"ruby\","; }; \
+			fi; \
 		else \
 			skipped_languages="$${skipped_languages}\"ruby\","; \
 			echo '{"level":"info","msg":"skipping ruby tests: no spec/ directory found","language":"ruby"}' >&2; \
@@ -898,7 +926,7 @@ _security: _check-config
 	if [ -n "$(HAS_RUBY)" ]; then \
 		ran_languages="$${ran_languages}\"ruby\","; \
 		if [ -f "config/application.rb" ]; then \
-			brakeman -q || { overall_exit=1; failed_languages="$${failed_languages}\"ruby:brakeman\","; }; \
+			$(call RUBY_EXEC_FOR,brakeman)brakeman -q || { overall_exit=1; failed_languages="$${failed_languages}\"ruby:brakeman\","; }; \
 		else \
 			echo '{"level":"info","msg":"skipping brakeman: not a Rails application","language":"ruby"}' >&2; \
 		fi; \
@@ -909,7 +937,7 @@ _security: _check-config
 			exit $$overall_exit; \
 		fi; \
 		if [ -f "Gemfile.lock" ]; then \
-			bundler-audit check || { overall_exit=1; failed_languages="$${failed_languages}\"ruby:bundler-audit\","; }; \
+			$(call RUBY_EXEC_FOR,bundler-audit)bundler-audit check || { overall_exit=1; failed_languages="$${failed_languages}\"ruby:bundler-audit\","; }; \
 		else \
 			echo '{"level":"info","msg":"skipping bundler-audit: no Gemfile.lock found","language":"ruby"}' >&2; \
 		fi; \

STABILITY.md

@@ -32,6 +32,13 @@ DevRail has reached **v1.0** across all repositories. The core standards, toolch
 | **Pre-commit hooks** | Stable | Conventional commit hook and per-language hooks configured in template repos. |
 | **Documentation site** | Stable | [devrail.dev](https://devrail.dev) is live with full standards coverage. |
 
+## Consumer responsibilities
+
+These are services/data the dev-toolchain container does **not** provide; consumers must provide them when relevant:
+
+- **Database service** (Postgres, MySQL, etc.) — required for Rails projects whose specs touch the test database. The container runs `bundle exec rails db:test:prepare` before `rspec` (when `config/application.rb` + `Gemfile` are present), which needs a reachable database. Typical local pattern: `docker-compose up -d postgres` before `make test`. Typical CI pattern: a `services:` block.
+- **Project bundle install** — the container ships its own gems for `rubocop`/`reek`/etc. as defaults, but for Gemfile-pinned versions it expects the project's bundle to already be installed (`bundle install`) so `bundle exec <tool>` can find them.
+
 ## Versioning
 
 All DevRail repos follow [Semantic Versioning](https://semver.org/). The container image uses a floating major tag (`:v1`) that always points to the latest `v1.x.x` release. Pin to a specific tag (e.g., `:v1.4.0`) if you need exact reproducibility.

tests/smoke-rails.sh

@@ -154,4 +154,29 @@ fi
 
 echo "==> bundle install + psych load: PASS (completed in ${bundle_elapsed}s)"
 
+# --- 4) Project .bundle/config wins when DOCKER_RUN sets the override ------
+# Issue #30 Gap A: container's default BUNDLE_APP_CONFIG=/usr/local/bundle
+# silently overrides project-local .bundle/config. The Makefile's DOCKER_RUN
+# now passes -e BUNDLE_APP_CONFIG=/workspace/.bundle for Ruby projects so the
+# project's own config wins.
+echo "==> Verifying .bundle/config override (issue #30 Gap A)"
+mkdir -p "$FIXTURE/.bundle"
+cat >"$FIXTURE/.bundle/config" <<'BUNDLE_CFG'
+---
+BUNDLE_PATH: "vendor/bundle"
+BUNDLE_CFG
+
+bundle_path_seen=$(docker run --rm \
+  -v "$FIXTURE:/workspace" \
+  -w /workspace \
+  -e BUNDLE_APP_CONFIG=/workspace/.bundle \
+  "$IMAGE" \
+  bundle config get path 2>/dev/null | grep -oE '"[^"]+"' | head -1 | tr -d '"' || echo "")
+
+if [ "$bundle_path_seen" != "vendor/bundle" ]; then
+  echo "FAIL: project .bundle/config ignored — bundle path resolved to '$bundle_path_seen', expected 'vendor/bundle'" >&2
+  exit 1
+fi
+echo "==> .bundle/config override: PASS (BUNDLE_PATH = $bundle_path_seen)"
+
 echo "==> All Rails smoke checks passed"