route_guard 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c095ab5dfc78ae856774803b38cd9d4cceb6073d623908014e73f2d48752d2db
+  data.tar.gz: edcb632d5f8b621477d8d3f8b612b3c581877308db4807e3e57e8ad835f4bf78
+SHA512:
+  metadata.gz: 2dbdfaf0cb426abccbe8e9258742ae121923e635e1f1b6041ebed0d6085fc86409c888e05686c947ccdb757c871ea547a9675a193d0171cfe1c85b9d94ccc6e0
+  data.tar.gz: dd07ec99fb9ad444cc5851db746f36eb73f66017ae9c276dafca239e78f90d7df6b19717bfaf0a8c22b5b27171d4e4daa5b346263ed44eef8b796fc8fcf4d554

data/.gitignore

@@ -0,0 +1,13 @@
+# Test results and coverage
+/coverage/
+/.rspec_status
+/test.log
+/tmp/
+
+# Bundler
+/.bundle/
+/vendor/bundle/
+
+# Gem builds
+/pkg/
+*.gem

data/Gemfile

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+gemspec

data/Gemfile.lock

@@ -0,0 +1,173 @@
+PATH
+  remote: .
+  specs:
+    route_guard (0.1.0)
+      actionpack (>= 6.1)
+      railties (>= 6.1)
+      rainbow (~> 3.1)
+      thor (~> 1.2)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    actionpack (8.1.3.1)
+      actionview (= 8.1.3.1)
+      activesupport (= 8.1.3.1)
+      nokogiri (>= 1.8.5)
+      rack (>= 2.2.4)
+      rack-session (>= 1.0.1)
+      rack-test (>= 0.6.3)
+      rails-dom-testing (~> 2.2)
+      rails-html-sanitizer (~> 1.6)
+      useragent (~> 0.16)
+    actionview (8.1.3.1)
+      activesupport (= 8.1.3.1)
+      builder (~> 3.1)
+      erubi (~> 1.11)
+      rails-dom-testing (~> 2.2)
+      rails-html-sanitizer (~> 1.6)
+    activesupport (8.1.3.1)
+      base64
+      bigdecimal
+      concurrent-ruby (~> 1.0, >= 1.3.1)
+      connection_pool (>= 2.2.5)
+      drb
+      i18n (>= 1.6, < 2)
+      json
+      logger (>= 1.4.2)
+      minitest (>= 5.1)
+      securerandom (>= 0.3)
+      tzinfo (~> 2.0, >= 2.0.5)
+      uri (>= 0.13.1)
+    base64 (0.3.0)
+    bigdecimal (4.1.2)
+    builder (3.3.0)
+    concurrent-ruby (1.3.8)
+    connection_pool (3.0.2)
+    crass (1.0.7)
+    diff-lcs (1.6.2)
+    docile (1.4.1)
+    drb (2.2.3)
+    erb (6.0.6)
+    erubi (1.13.1)
+    i18n (1.15.2)
+      concurrent-ruby (~> 1.0)
+    io-console (0.8.2)
+    irb (1.18.0)
+      pp (>= 0.6.0)
+      prism (>= 1.3.0)
+      rdoc (>= 4.0.0)
+      reline (>= 0.4.2)
+    json (2.21.2)
+    logger (1.7.0)
+    loofah (2.25.2)
+      crass (~> 1.0.2)
+      nokogiri (>= 1.12.0)
+    minitest (6.0.6)
+      drb (~> 2.0)
+      prism (~> 1.5)
+    nokogiri (1.19.4-aarch64-linux-gnu)
+      racc (~> 1.4)
+    nokogiri (1.19.4-aarch64-linux-musl)
+      racc (~> 1.4)
+    nokogiri (1.19.4-arm-linux-gnu)
+      racc (~> 1.4)
+    nokogiri (1.19.4-arm-linux-musl)
+      racc (~> 1.4)
+    nokogiri (1.19.4-arm64-darwin)
+      racc (~> 1.4)
+    nokogiri (1.19.4-x86_64-darwin)
+      racc (~> 1.4)
+    nokogiri (1.19.4-x86_64-linux-gnu)
+      racc (~> 1.4)
+    nokogiri (1.19.4-x86_64-linux-musl)
+      racc (~> 1.4)
+    pp (0.6.4)
+      prettyprint
+    prettyprint (0.2.0)
+    prism (1.9.0)
+    racc (1.8.1)
+    rack (3.2.6)
+    rack-session (2.1.2)
+      base64 (>= 0.1.0)
+      rack (>= 3.0.0)
+    rack-test (2.2.0)
+      rack (>= 1.3)
+    rackup (2.3.1)
+      rack (>= 3)
+    rails-dom-testing (2.3.0)
+      activesupport (>= 5.0.0)
+      minitest
+      nokogiri (>= 1.6)
+    rails-html-sanitizer (1.7.1)
+      loofah (~> 2.25, >= 2.25.2)
+      nokogiri (>= 1.15.7, != 1.16.7, != 1.16.6, != 1.16.5, != 1.16.4, != 1.16.3, != 1.16.2, != 1.16.1, != 1.16.0.rc1, != 1.16.0)
+    railties (8.1.3.1)
+      actionpack (= 8.1.3.1)
+      activesupport (= 8.1.3.1)
+      irb (~> 1.13)
+      rackup (>= 1.0.0)
+      rake (>= 12.2)
+      thor (~> 1.0, >= 1.2.2)
+      tsort (>= 0.2)
+      zeitwerk (~> 2.6)
+    rainbow (3.1.1)
+    rake (13.4.2)
+    rbs (4.1.2)
+      logger
+      prism (>= 1.6.0)
+      tsort
+    rdoc (8.0.0)
+      erb
+      prism (>= 1.6.0)
+      rbs (>= 4.0.0)
+      tsort
+    reline (0.6.3)
+      io-console (~> 0.5)
+    rspec (3.13.2)
+      rspec-core (~> 3.13.0)
+      rspec-expectations (~> 3.13.0)
+      rspec-mocks (~> 3.13.0)
+    rspec-core (3.13.6)
+      rspec-support (~> 3.13.0)
+    rspec-expectations (3.13.5)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-mocks (3.13.8)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-support (3.13.7)
+    securerandom (0.4.1)
+    simplecov (0.22.0)
+      docile (~> 1.1)
+      simplecov-html (~> 0.11)
+      simplecov_json_formatter (~> 0.1)
+    simplecov-html (0.13.2)
+    simplecov_json_formatter (0.1.4)
+    thor (1.5.0)
+    tsort (0.2.0)
+    tzinfo (2.0.6)
+      concurrent-ruby (~> 1.0)
+    uri (1.1.1)
+    useragent (0.16.11)
+    zeitwerk (2.8.3)
+
+PLATFORMS
+  aarch64-linux-gnu
+  aarch64-linux-musl
+  arm-linux-gnu
+  arm-linux-musl
+  arm64-darwin
+  x86_64-darwin
+  x86_64-linux-gnu
+  x86_64-linux-musl
+
+DEPENDENCIES
+  bundler (~> 2.4)
+  rake (~> 13.0)
+  route_guard!
+  rspec (~> 3.12)
+  simplecov (~> 0.22)
+
+BUNDLED WITH
+   2.5.3

data/README.md

@@ -0,0 +1,57 @@
+# RouteGuard
+
+RouteGuard is a production-ready static analysis tool for Rails routing. It inspects your Rails routes to catch issues Rails itself doesn't report—like shadowing, duplicates, unreachable catch-alls, and duplicate resource blocks.
+
+## Core Features
+
+*   **Duplicate Route Detection**: Detects routes sharing the same HTTP verb and path pattern.
+*   **Route Shadowing**: Flags routes that can never be matched because an earlier route matches first (e.g. `/users/:id` shadowing `/users/new`).
+*   **Unreachable Routes**: Detects routes defined after catch-all wildcard routes (e.g. `match "*path"`).
+*   **Duplicate Named Helpers**: Identifies duplicate helper names (e.g., duplicate `auth_path` helpers pointing to different paths).
+*   **Duplicate Resources**: Warns when identical resources are declared multiple times in the same namespace scope.
+*   **Route Statistics**: Computes REST resources count, nested scopes, and wildcards.
+*   **Health Score**: Measures a 0-100 maintainability score based on issues and path nesting levels.
+
+---
+
+## Quick Start
+
+### Installation
+
+Add this gem to your group `:development, :test` block:
+
+```ruby
+group :development, :test do
+  gem "route_guard", path: "path/to/route_guard"
+end
+```
+
+Run `bundle install`.
+
+### Run RouteGuard
+
+Run check from the terminal:
+
+```bash
+bundle exec route_guard check
+```
+
+Or execute via Rake tasks:
+
+```bash
+bundle exec rails route_guard
+bundle exec rails routes:doctor
+```
+
+---
+
+## Documentation
+
+For detailed configurations, options, and workflows, please see:
+
+*   [Usage & Integration Guide](docs/usage.md)
+*   [Publishing Guide](docs/publishing.md)
+
+## License
+
+MIT License.

data/Rakefile

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec) do |t|
+  t.rspec_opts = "--format documentation"
+end
+
+task default: :spec

data/bin/route_guard

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative "../lib/route_guard"
+
+begin
+  RouteGuard::CLI.start(ARGV)
+rescue SystemExit => e
+  # Propagate CLI exits
+  exit(e.status)
+rescue => e
+  warn "Error: #{e.message}"
+  exit(1)
+end

data/docs/publishing.md

@@ -0,0 +1,76 @@
+# RouteGuard: Gem Publishing Guide
+
+This guide details how to build, package, and publish the **RouteGuard** gem to the RubyGems community.
+
+---
+
+## 1. Preparing for Release
+
+Before building and publishing, ensure that:
+
+1.  All tests pass:
+    ```bash
+    bundle exec rspec
+    ```
+2.  Your version in `lib/route_guard/version.rb` is bumped according to Semantic Versioning (SemVer) rules:
+    ```ruby
+    module RouteGuard
+      VERSION = "0.1.0" # Major.Minor.Patch
+    end
+    ```
+3.  The metadata in `route_guard.gemspec` (homepage, authors, email, etc.) is correct.
+
+---
+
+## 2. Building the Gem
+
+To package the gem code into a distributable `.gem` file, run the `gem build` command from the root of the project:
+
+```bash
+gem build route_guard.gemspec
+```
+
+This generates a file named `route_guard-0.1.0.gem` (matching your current version) in the root folder.
+
+---
+
+## 3. Authentication with RubyGems
+
+To publish a gem, you need an account on [RubyGems.org](https://rubygems.org/).
+
+Once registered, sign in via your terminal using:
+
+```bash
+gem signin
+```
+
+Enter your RubyGems email and password when prompted. This securely stores your API key locally in `~/.gem/credentials`.
+
+---
+
+## 4. Publishing to RubyGems
+
+Publish the built gem package using the `gem push` command:
+
+```bash
+gem push route_guard-0.1.0.gem
+```
+
+Once pushed, your gem will be immediately indexable, and developers around the world can install it via:
+
+```bash
+gem install route_guard
+```
+
+---
+
+## 5. Version Control Best Practices
+
+After publishing a release:
+
+1.  **Tag the release** in git:
+    ```bash
+    git tag -a v0.1.0 -m "Release version 0.1.0"
+    git push origin v0.1.0
+    ```
+2.  **Document changes** in a `CHANGELOG.md` file so developers know what changed.

data/docs/usage.md

@@ -0,0 +1,81 @@
+# RouteGuard: Usage Guide
+
+This guide explains how to install, integrate, and run **RouteGuard** in your Rails application.
+
+---
+
+## 1. Installation
+
+Add `route_guard` to your application's `Gemfile`. Since RouteGuard has zero runtime overhead in production, it is highly recommended to group it under `:development` and `:test`:
+
+```ruby
+group :development, :test do
+  gem "route_guard", path: "path/to/route_guard" # During local development
+  # Or once published:
+  # gem "route_guard"
+end
+```
+
+Then execute:
+
+```bash
+bundle install
+```
+
+---
+
+## 2. Command Line Interface (CLI)
+
+You can run RouteGuard directly from your terminal. Since it automatically boot-loads your Rails environment, make sure to execute it from your Rails application root directory:
+
+```bash
+bundle exec route_guard
+```
+
+### Commands
+
+*   `check` (default): Run full inspection rules on routes.
+*   `stats`: Generate key route complexity metrics and statistics.
+*   `doctor`: Run in strict mode (fails on warnings/errors). Perfect for CI pipelines.
+*   `json`: Generate a machine-readable JSON report.
+*   `html`: Generate a premium interactive HTML report dashboard.
+
+### CLI Options
+
+| Option | Type | Description |
+| :--- | :--- | :--- |
+| `--strict` | Boolean | Treat all warnings as errors. |
+| `--format` | String | Output format (`terminal`, `json`, `html`, `ci`). |
+| `--only` | Array | Only run specific inspections (e.g. `duplicate_routes`). |
+| `--except` | Array | Exclude specific inspections from running. |
+| `--fail-on-warning`| Boolean | Exit with status code `1` if warnings are found. |
+| `--output` | String | Path to write the JSON/HTML output. |
+| `--verbose` | Boolean | Display detailed debug information. |
+
+#### Examples
+
+**Generate a self-contained HTML dashboard report:**
+```bash
+bundle exec route_guard html --output=coverage/route_guard_report.html
+```
+
+**Run only duplicate route checking:**
+```bash
+bundle exec route_guard check --only duplicate_routes
+```
+
+**Strict checking in CI, failing on warnings:**
+```bash
+bundle exec route_guard check --fail-on-warning
+```
+
+---
+
+## 3. Rails / Rake Integration
+
+RouteGuard automatically registers Rake tasks when loaded in your Rails application.
+
+### Available Tasks
+
+*   **`bundle exec rails route_guard`** (or `bundle exec rails routes:lint`): Analyzes your routes and prints findings to your terminal.
+*   **`bundle exec rails routes:doctor`**: Runs strict verification. Exits with non-zero code if any issue (warning or error) is detected. Ideal for Git pre-commit hooks or CI steps.

data/lib/route_guard/analyzer.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require_relative "models/report"
+require_relative "rules/duplicate_routes"
+require_relative "rules/shadowed_routes"
+require_relative "rules/unreachable_routes"
+require_relative "rules/duplicate_helpers"
+require_relative "rules/duplicate_resources"
+require_relative "rules/statistics"
+require_relative "rules/complexity"
+require_relative "rules/unused_routes"
+
+module RouteGuard
+  class Analyzer
+    RULE_MAPPING = {
+      duplicate_routes: Rules::DuplicateRoutes,
+      shadowed_routes: Rules::ShadowedRoutes,
+      unreachable_routes: Rules::UnreachableRoutes,
+      duplicate_helpers: Rules::DuplicateHelpers,
+      duplicate_resources: Rules::DuplicateResources,
+      statistics: Rules::Statistics,
+      complexity: Rules::Complexity,
+      unused_routes: Rules::UnusedRoutes
+    }.freeze
+
+    def self.analyze(routes, enabled_rules, options = {})
+      report = Models::Report.new(routes)
+      start_time = Time.now
+
+      # 1. Run Statistics first (if enabled)
+      if enabled_rules.include?(:statistics)
+        stat_rule = Rules::Statistics.new(options)
+        stat_rule.analyze(routes, report)
+      end
+
+      # 2. Run other lint rules
+      issues = []
+      lint_rules = %i[duplicate_routes shadowed_routes unreachable_routes duplicate_helpers duplicate_resources unused_routes]
+      (lint_rules & enabled_rules).each do |rule_sym|
+        rule_class = RULE_MAPPING[rule_sym]
+        next unless rule_class
+
+        rule = rule_class.new(options)
+        rule_issues = rule.analyze(routes, report)
+        issues.concat(rule_issues) if rule_issues.is_a?(Array)
+      end
+
+      # Expose intermediate issues on report for Complexity to analyze
+      report.issues = issues
+
+      # Update stats with issue metrics
+      if report.stats && report.stats.any?
+        report.stats[:duplicate_paths] = issues.count { |i| i.rule_name == :duplicate_routes }
+        report.stats[:shadowed_routes] = issues.count { |i| i.rule_name == :shadowed_routes }
+      end
+
+      # 3. Run Complexity last (if enabled)
+      if enabled_rules.include?(:complexity)
+        comp_rule = Rules::Complexity.new(options)
+        comp_issues = comp_rule.analyze(routes, report)
+        issues.concat(comp_issues) if comp_issues.is_a?(Array)
+      end
+
+      report.issues = issues
+      report.duration = Time.now - start_time
+      report
+    end
+  end
+end

data/lib/route_guard/cli.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+require "thor"
+require_relative "../route_guard"
+
+module RouteGuard
+  class CLI < Thor
+    class_option :strict, type: :boolean, default: false, desc: "Treat warnings as errors"
+    class_option :format, type: :string, default: "terminal", desc: "Output format: terminal, json, html, ci"
+    class_option :only, type: :array, default: [], desc: "Run only specified rules"
+    class_option :except, type: :array, default: [], desc: "Exclude specified rules"
+    class_option :fail_on_warning, type: :boolean, default: false, desc: "Fail if warnings are found"
+    class_option :verbose, type: :boolean, default: false, desc: "Print verbose output"
+    class_option :output, type: :string, desc: "Output file path"
+
+    desc "check", "Analyze Rails routes for issues"
+    def check
+      config = build_config
+      inspector = Inspector.new(config)
+      report = inspector.run
+
+      fmt = (options[:format] || "terminal").to_sym
+      io = if options[:output]
+             File.open(options[:output], "w")
+           else
+             $stdout
+           end
+
+      inspector.format(report, fmt, io)
+      io.close if options[:output]
+
+      exit_status(report, config)
+    end
+
+    default_task :check
+
+    desc "stats", "Calculate routing statistics and metrics"
+    def stats
+      config = build_config
+      config.rules = [:statistics]
+      inspector = Inspector.new(config)
+      report = inspector.run
+
+      fmt = (options[:format] || "terminal").to_sym
+      if fmt == :json
+        inspector.format(report, :json)
+      else
+        inspector.format(report, :terminal)
+      end
+    end
+
+    desc "doctor", "Thoroughly inspect and report on route health"
+    def doctor
+      config = build_config
+      config.strict = true
+      config.fail_on_warning = true
+      inspector = Inspector.new(config)
+      report = inspector.run
+      inspector.format(report, :terminal)
+      exit_status(report, config)
+    end
+
+    desc "json", "Output results in JSON format"
+    def json
+      config = build_config
+      config.formatters = [:json]
+      inspector = Inspector.new(config)
+      report = inspector.run
+      inspector.format(report, :json)
+      exit_status(report, config)
+    end
+
+    desc "html", "Generate a beautiful HTML report"
+    def html
+      config = build_config
+      config.formatters = [:html]
+      inspector = Inspector.new(config)
+      report = inspector.run
+
+      output_file = options[:output] || "route_guard_report.html"
+      File.open(output_file, "w") do |f|
+        inspector.format(report, :html, f)
+      end
+      puts "HTML report generated at #{output_file}"
+      exit_status(report, config)
+    end
+
+    # Disable Thor's exit-on-failure behavior by default to control exit statuses
+    def self.exit_on_failure?
+      true
+    end
+
+    private
+
+    def build_config
+      config = Configuration.new
+      config.strict = options[:strict]
+      config.fail_on_warning = options[:fail_on_warning]
+      config.only = options[:only] || []
+      config.except = options[:except] || []
+      config.verbose = options[:verbose]
+
+      fmt = (options[:format] || "terminal").to_sym
+      config.formatters = [fmt]
+      config
+    end
+
+    def exit_status(report, config = nil)
+      strict = config ? config.strict : options[:strict]
+      fail_on_warning = config ? config.fail_on_warning : options[:fail_on_warning]
+
+      if report.errors.any?
+        exit(1)
+      elsif fail_on_warning && report.warnings.any?
+        exit(1)
+      elsif strict && report.warnings.any?
+        exit(1)
+      else
+        exit(0)
+      end
+    end
+  end
+end

data/lib/route_guard/configuration.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module RouteGuard
+  class Configuration
+    attr_accessor :rules, :formatters, :strict, :fail_on_warning, :only, :except, :verbose
+
+    ALL_RULES = %i[
+      duplicate_routes
+      shadowed_routes
+      unreachable_routes
+      duplicate_helpers
+      duplicate_resources
+      unused_routes
+      statistics
+      complexity
+    ].freeze
+
+    def initialize
+      @rules = ALL_RULES.dup
+      @formatters = [:terminal]
+      @strict = false
+      @fail_on_warning = false
+      @only = []
+      @except = []
+      @verbose = false
+    end
+
+    def enabled_rules
+      active_rules = if only.any?
+                       rules & only.map(&:to_sym)
+                     else
+                       rules
+                     end
+
+      active_rules - except.map(&:to_sym)
+    end
+  end
+end

data/lib/route_guard/formatter/ci.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module RouteGuard
+  module Formatter
+    class Ci
+      def format(report, io = $stdout)
+        report.issues.each do |issue|
+          severity = issue.severity == :error ? "error" : "warning"
+
+          if issue.file && issue.line
+            rel_file = issue.file.sub(/\A#{Regexp.escape(Dir.pwd)}\//, "")
+            io.puts "::#{severity} file=#{rel_file},line=#{issue.line}::[RouteGuard] #{issue.message}"
+          else
+            io.puts "::#{severity}::[RouteGuard] #{issue.message}"
+          end
+        end
+      end
+    end
+  end
+end