Add rails-stats command line executable

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)

README.md

@@ -6,22 +6,62 @@ 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 outside Rails project
+### Run it as a command line tool
 
-You will need a `Rakefile` in the directory where you call `rake` and you will
-need to require `rails_stats`:
+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:
 
-```ruby
-# Rakefile
-require "rails_stats"
+```bash
+$ rails-stats /path/to/app
+$ rails-stats path/to/app
 ```
 
-Then you can call it:
+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
+```
+
+#### 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
+`Rakefile`:
 
 ```bash
-$ rake stats\[/path/to/app/\]
+$ rails-stats /path/to/app
 
-Directory: /path/to/app/
+Directory: /path/to/app
 
 +-----------------------|------------|----------------+
 |                  Name | Total Deps | 1st Level Deps |
@@ -68,7 +108,7 @@ Directory: /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
@@ -78,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 ==
 +----------------------+---------+---------+---------+---------+---------+-----+-------+
@@ -109,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
@@ -151,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 |
@@ -240,7 +267,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
 

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

rails_stats.gemspec

@@ -6,15 +6,16 @@ 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"
   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"]