From c63c5ba39719f7e388aaaaecc98b56dd6bad0f03 Mon Sep 17 00:00:00 2001 From: Ernesto Tagwerker Date: Sun, 12 Jul 2026 10:07:00 -0400 Subject: [PATCH 1/5] Add rails-stats command line executable Add a standalone `rails-stats` executable so the tool can be run against a directory without setting up a Rakefile. It accepts both absolute and relative paths, defaults to the current directory when none is given, and optionally takes a `json` second argument for JSON output. Co-Authored-By: Claude Opus 4.8 (1M context) --- CHANGELOG.md | 1 + README.md | 23 +++++++++++++++++++++++ bin/rails-stats | 27 +++++++++++++++++++++++++++ 3 files changed, 51 insertions(+) create mode 100755 bin/rails-stats diff --git a/CHANGELOG.md b/CHANGELOG.md index 9c34104..24dd71b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,6 @@ # main ([unreleased](https://github.com/fastruby/rails_stats/compare/v2.1.0...main)) +* [FEATURE: Add a `rails-stats` command line executable that accepts an absolute or relative directory](https://github.com/fastruby/rails_stats/pull/49) * [FEATURE: Support component-based and Packwerk (packs) applications with a per-pack and Core breakdown](https://github.com/fastruby/rails_stats/issues/23) * [BUGFIX: Respect an explicit path argument (e.g. `rake stats[packs/pack1]`) when running inside a booted Rails app](https://github.com/fastruby/rails_stats/issues/23) * [CHORE: Improve the GH Test Workflow](https://github.com/fastruby/rails_stats/pull/35) diff --git a/README.md b/README.md index ca3bdf2..521c284 100644 --- a/README.md +++ b/README.md @@ -6,6 +6,29 @@ There were a few things missing to the included `rake stats` RailsStats mainly adds the ability to be run from outside the project in question. This can be helpful if the app you are interested in can not be booted for some reason. +### Run it as a command line tool + +Once the gem is installed you can point the `rails-stats` executable at any +directory, without setting up a `Rakefile`. It accepts both absolute and +relative paths: + +```bash +$ rails-stats /path/to/app +$ rails-stats path/to/app +``` + +When no path is given it defaults to the current directory: + +```bash +$ rails-stats +``` + +You can also request JSON output by passing `json` as a second argument: + +```bash +$ rails-stats path/to/app json +``` + ### Run it outside Rails project You will need a `Rakefile` in the directory where you call `rake` and you will diff --git a/bin/rails-stats b/bin/rails-stats new file mode 100755 index 0000000..fbad7d0 --- /dev/null +++ b/bin/rails-stats @@ -0,0 +1,27 @@ +#!/usr/bin/env ruby +# frozen_string_literal: true + +# Standalone CLI for running rails_stats against a directory without having to +# set up a Rakefile. Accepts both absolute and relative paths: +# +# rails-stats /path/to/app +# rails-stats path/to/app +# rails-stats # defaults to the current directory +# rails-stats path/to/app json +# +$LOAD_PATH.unshift(File.expand_path("../lib", __dir__)) + +require "rails_stats/all" + +path = ARGV[0] || "." +format = ARGV[1] || "" + +root_directory = File.absolute_path(path) + +unless File.directory?(root_directory) + warn "rails-stats: no such directory - #{path}" + exit 1 +end + +puts "\nDirectory: #{root_directory}\n\n" +RailsStats::CodeStatistics.new(root_directory, format: format).to_s From 73218503f94566e6f3f6d22be49a746169c22951 Mon Sep 17 00:00:00 2001 From: Ernesto Tagwerker Date: Sun, 12 Jul 2026 10:19:24 -0400 Subject: [PATCH 2/5] Declare rails-stats executable explicitly and lead README with it Set spec.bindir/spec.executables explicitly in the gemspec per the RubyGems specification reference, and update the README so the primary usage examples call the rails-stats executable instead of rake stats[...]. Co-Authored-By: Claude Opus 4.8 (1M context) --- README.md | 27 +++++++++++++++------------ rails_stats.gemspec | 3 ++- 2 files changed, 17 insertions(+), 13 deletions(-) diff --git a/README.md b/README.md index 521c284..b145538 100644 --- a/README.md +++ b/README.md @@ -31,18 +31,11 @@ $ rails-stats path/to/app json ### Run it outside Rails project -You will need a `Rakefile` in the directory where you call `rake` and you will -need to require `rails_stats`: - -```ruby -# Rakefile -require "rails_stats" -``` - -Then you can call it: +The quickest way is the `rails-stats` executable, which does not require a +`Rakefile`: ```bash -$ rake stats\[/path/to/app/\] +$ rails-stats /path/to/app Directory: /path/to/app/ @@ -88,10 +81,20 @@ Directory: /path/to/app/ Code LOC: 145 Test LOC: 6 Code to Test Ratio: 1:0.0 Files: 34 ``` +If you would rather go through `rake`, add a `Rakefile` in the directory where +you call `rake` that requires `rails_stats`: + +```ruby +# Rakefile +require "rails_stats" +``` + +Then call `rake stats\[/path/to/app/\]`. + ### Run it on many Rails engines ```bash -$ for dir in /path/to/many/engines/*/; do bundle exec rake stats[$dir]; done +$ for dir in /path/to/many/engines/*/; do rails-stats "$dir"; done ``` ### Component-based and Packwerk (packs) applications @@ -263,7 +266,7 @@ $ bundle exec rake stats[/users/brian/examples/redmine/] If you want to export the details using JSON, you can use this command: ``` -$ rake stats\[test/dummy,json\] +$ rails-stats test/dummy json Directory: /Users/etagwerker/Projects/redmine diff --git a/rails_stats.gemspec b/rails_stats.gemspec index 4e71c0e..766d997 100644 --- a/rails_stats.gemspec +++ b/rails_stats.gemspec @@ -14,7 +14,8 @@ Gem::Specification.new do |spec| spec.license = "MIT" spec.files = `git ls-files -z`.split("\x0") - spec.executables = spec.files.grep(%r{^bin/}) { |f| File.basename(f) } + spec.bindir = "bin" + spec.executables = ["rails-stats"] spec.test_files = spec.files.grep(%r{^(test|spec|features)/}) spec.require_paths = ["lib"] From 48277dfa32d68b930bb25a867c68d69acbf6427f Mon Sep 17 00:00:00 2001 From: Ernesto Tagwerker Date: Sun, 12 Jul 2026 10:20:58 -0400 Subject: [PATCH 3/5] Add Ernesto Tagwerker to gemspec authors Co-Authored-By: Claude Opus 4.8 (1M context) --- rails_stats.gemspec | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/rails_stats.gemspec b/rails_stats.gemspec index 766d997..b8b338f 100644 --- a/rails_stats.gemspec +++ b/rails_stats.gemspec @@ -6,8 +6,8 @@ require 'rails_stats/version' Gem::Specification.new do |spec| spec.name = "rails_stats" spec.version = RailsStats::VERSION - spec.authors = ["Brian Leonard"] - spec.email = ["brian@bleonard.com"] + spec.authors = ["Brian Leonard", "Ernesto Tagwerker"] + spec.email = ["brian@bleonard.com", "ernesto@ombulabs.com"] spec.summary = %q{Analyze a Rails project} spec.description = %q{Point it to a directory and see stuff about the app} spec.homepage = "https://github.com/fastruby/rails_stats" From 83d4da3790e1d7e432a085b43b9c6d29822464d3 Mon Sep 17 00:00:00 2001 From: Ernesto Tagwerker Date: Sun, 12 Jul 2026 10:38:30 -0400 Subject: [PATCH 4/5] Consolidate rake usage into one README subsection Move all rake invocation instructions (Rakefile-in-any-directory and replacing the built-in rake stats inside a Rails app) into a single "Calling it through rake" subsection, and switch every other example to the rails-stats executable. Co-Authored-By: Claude Opus 4.8 (1M context) --- README.md | 59 ++++++++++++++++++++++++++++--------------------------- 1 file changed, 30 insertions(+), 29 deletions(-) diff --git a/README.md b/README.md index b145538..2ebe68b 100644 --- a/README.md +++ b/README.md @@ -29,6 +29,30 @@ You can also request JSON output by passing `json` as a second argument: $ rails-stats path/to/app json ``` +#### Calling it through `rake` + +If you prefer `rake`, there are two ways to reach the same code: + +- **From any directory**, add a `Rakefile` that requires `rails_stats` and call + the task with a path: + + ```ruby + # Rakefile + require "rails_stats" + ``` + + ```bash + $ rake stats\[/path/to/app/\] + ``` + +- **Inside your own Rails app**, add `rails_stats` to your `Gemfile` to + _replace_ the default `rake stats` implementation (you might need to + `require "rails_stats"` in your `Rakefile`), then run: + + ```bash + $ bundle exec rake stats + ``` + ### Run it outside Rails project The quickest way is the `rails-stats` executable, which does not require a @@ -81,16 +105,6 @@ Directory: /path/to/app/ Code LOC: 145 Test LOC: 6 Code to Test Ratio: 1:0.0 Files: 34 ``` -If you would rather go through `rake`, add a `Rakefile` in the directory where -you call `rake` that requires `rails_stats`: - -```ruby -# Rakefile -require "rails_stats" -``` - -Then call `rake stats\[/path/to/app/\]`. - ### Run it on many Rails engines ```bash @@ -104,13 +118,13 @@ RailsStats understands large Rails monoliths that are organized into [packs-rails](https://github.com/rubyatscale/packs-rails)) or [components](https://cbra.info/) (component-based Rails). -When packs or components are detected, `rake stats` automatically prints a +When packs or components are detected, `rails-stats` automatically prints a breakdown per pack/component, a `Core Application` section for everything that lives in the main app, and a `Total (all packs)` section that aggregates the whole monolith: ```bash -$ bundle exec rake stats +$ rails-stats /path/to/monolith == Core Application == +----------------------+---------+---------+---------+---------+---------+-----+-------+ @@ -135,29 +149,16 @@ Packwerk marker) or when it lives directly under a `packs/` or `components/` directory and holds any of the usual code folders (`app`, `lib`, `spec`, `test`). Nested packs (`packs/a/packs/b`) are supported. -You can also scope stats to a single pack, even from inside a booted Rails app: +You can also scope stats to a single pack: ```bash -$ bundle exec rake stats[packs/pack1] +$ rails-stats packs/pack1 ``` The same breakdown is available in JSON under a `"packs"` key: ```bash -$ bundle exec rake stats[.,json] -``` - -### Within your Rails project - -You can also include it within your Rails application to _replace_ the default `rake stats` implementation. - -Just add rails_stats to your Gemfile. -Depending on your setup, you might need to `require rails_stats` in your Rakefile. - -Then you'll be able to just run: - -```bash -$ bundle exec rake stats +$ rails-stats . json ``` ### Things it knows about @@ -177,7 +178,7 @@ Here are some open source Rails projects and their output. ```bash -$ bundle exec rake stats[/users/brian/examples/redmine/] +$ rails-stats /users/brian/examples/redmine/ +-----------------------|------------|----------------+ | Name | Total Deps | 1st Level Deps | From 421c996276bf42e3d8e1f2f1db2255c4f89d2bff Mon Sep 17 00:00:00 2001 From: Ernesto Tagwerker Date: Sun, 12 Jul 2026 10:41:12 -0400 Subject: [PATCH 5/5] Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 2ebe68b..46652b3 100644 --- a/README.md +++ b/README.md @@ -61,7 +61,7 @@ The quickest way is the `rails-stats` executable, which does not require a ```bash $ rails-stats /path/to/app -Directory: /path/to/app/ +Directory: /path/to/app +-----------------------|------------|----------------+ | Name | Total Deps | 1st Level Deps |