route_guard 0.1.0

data/lib/route_guard/rules/statistics.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module RouteGuard
+  module Rules
+    class Statistics < Base
+      def analyze(routes, report)
+        return [] if routes.empty?
+
+        # Calculate metrics
+        total_routes = routes.length
+
+        # REST Resources: count unique controller resource names or use RouteTracker if available
+        resource_calls = RouteTracker.resource_calls
+        rest_resources = if resource_calls.any?
+                           resource_calls.map { |c| c[:args].first }.uniq.size
+                         else
+                           # Fallback: estimate from controller count
+                           routes.map(&:controller).compact.uniq.size
+                         end
+
+        # Namespaces: count of unique directories in controller names
+        namespaces = routes.map(&:controller).compact
+                           .select { |c| c.include?("/") }
+                           .map { |c| c.split("/")[0...-1].join("/") }
+                           .uniq.size
+
+        # Scopes: count of unique non-parameter, non-wildcard first-level path prefixes
+        prefixes = routes.map { |r| r.path.split("/")[1] }
+                         .compact
+                         .reject { |p| p.start_with?(":") || p.start_with?("*") }
+                         .uniq
+        scopes = prefixes.size
+
+        # Wildcards: routes containing '*'
+        wildcards = routes.select { |r| r.path.include?("*") }.size
+
+        # Nesting depth: count of dynamic parameters (:id, etc.) in route path
+        depths = routes.map { |r| r.path.scan(/:\w+/).size }
+        max_depth = depths.max || 0
+        avg_depth = (depths.sum.to_f / total_routes).round(2)
+
+        # Most common controller
+        controller_counts = Hash.new(0)
+        routes.each { |r| controller_counts[r.controller] += 1 if r.controller }
+        most_common_controller = nil
+        most_common_count = 0
+        if controller_counts.any?
+          raw_controller, most_common_count = controller_counts.max_by { |_, count| count }
+          most_common_controller = camelize_controller(raw_controller)
+        end
+
+        # Store in report stats (will be updated with issues later)
+        report.stats = {
+          total_routes: total_routes,
+          rest_resources: rest_resources,
+          namespaces: namespaces,
+          scopes: scopes,
+          wildcards: wildcards,
+          duplicate_paths: 0, # Will be set by analyzer after running all rules
+          shadowed_routes: 0, # Will be set by analyzer
+          average_nesting_depth: avg_depth,
+          maximum_nesting_depth: max_depth,
+          most_common_controller: most_common_controller,
+          most_common_count: most_common_count
+        }
+
+        [] # Statistics rule does not generate issues itself
+      end
+
+      private
+
+      def camelize_controller(name)
+        return nil unless name
+        name.to_s.split("/").map { |part| part.split("_").map(&:capitalize).join }.join("::") + "Controller"
+      end
+    end
+  end
+end
+

data/lib/route_guard/rules/unreachable_routes.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require_relative "base"
+require_relative "../models/issue"
+
+module RouteGuard
+  module Rules
+    class UnreachableRoutes < Base
+      def analyze(routes, report)
+        issues = []
+        catch_alls = []
+
+        routes.each do |route|
+          matching_catch_all = catch_alls.find do |ca|
+            verb_matches?(ca.verb, route.verb)
+          end
+
+          if matching_catch_all
+            issues << Models::Issue.new(
+              rule_name: :unreachable_routes,
+              severity: :error,
+              message: "Unreachable Route: #{route} is unreachable because it comes after catch-all wildcard #{matching_catch_all}.",
+              route: route,
+              related_routes: [matching_catch_all]
+            )
+          elsif catch_all_wildcard?(route)
+            catch_alls << route
+          end
+        end
+
+        issues
+      end
+
+      private
+
+      def catch_all_wildcard?(route)
+        path = route.path
+        path == "/*path" || path == "*path" || path.match?(/\A\/?\*[a-zA-Z_]+\z/)
+      end
+    end
+  end
+end

data/lib/route_guard/rules/unused_routes.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require_relative "base"
+require_relative "../models/issue"
+
+module RouteGuard
+  module Rules
+    class UnusedRoutes < Base
+      def analyze(routes, report)
+        issues = []
+        return issues unless defined?(Rails)
+
+        routes.each do |route|
+          next if route.controller.nil? || route.action.nil?
+          next if route.internal?
+
+          controller_class_name = camelize_controller(route.controller)
+
+          begin
+            klass = if controller_class_name.respond_to?(:safe_constantize)
+                      controller_class_name.safe_constantize
+                    else
+                      Object.const_get(controller_class_name) rescue nil
+                    end
+
+            if klass
+              if klass.respond_to?(:action_methods)
+                unless klass.action_methods.include?(route.action.to_s)
+                  issues << Models::Issue.new(
+                    rule_name: :unused_routes,
+                    severity: :warning,
+                    message: "Unused Route: Action '#{route.action}' is missing in #{controller_class_name}.",
+                    route: route
+                  )
+                end
+              end
+            else
+              issues << Models::Issue.new(
+                rule_name: :unused_routes,
+                severity: :warning,
+                message: "Unused Route: Controller #{controller_class_name} does not exist.",
+                route: route
+              )
+            end
+          rescue NameError, LoadError
+            issues << Models::Issue.new(
+              rule_name: :unused_routes,
+              severity: :warning,
+              message: "Unused Route: Controller #{controller_class_name} could not be loaded.",
+              route: route
+            )
+          end
+        end
+
+        issues
+      end
+
+      private
+
+      def camelize_controller(name)
+        return nil unless name
+        name.to_s.split("/").map { |part| part.split("_").map(&:capitalize).join }.join("::") + "Controller"
+      end
+    end
+  end
+end

data/lib/route_guard/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module RouteGuard
+  VERSION = "0.1.0"
+end

data/lib/route_guard.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require_relative "route_guard/version"
+require_relative "route_guard/configuration"
+require_relative "route_guard/models/route"
+require_relative "route_guard/models/issue"
+require_relative "route_guard/models/report"
+require_relative "route_guard/route_tracker"
+require_relative "route_guard/route_loader"
+require_relative "route_guard/analyzer"
+require_relative "route_guard/inspector"
+require_relative "route_guard/cli"
+
+require_relative "route_guard/railtie" if defined?(Rails::Railtie)

data/lib/tasks/route_guard.rake

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+namespace :routes do
+  desc "Lint Rails routes and detect shadowing, duplicates, etc."
+  task lint: :environment do
+    require "route_guard"
+    config = RouteGuard::Configuration.new
+    inspector = RouteGuard::Inspector.new(config)
+    report = inspector.run
+    inspector.format(report, :terminal)
+
+    exit(1) if report.errors.any?
+  end
+
+  desc "Run RouteGuard doctor mode on Rails routes"
+  task doctor: :environment do
+    require "route_guard"
+    config = RouteGuard::Configuration.new
+    config.strict = true
+    config.fail_on_warning = true
+    inspector = RouteGuard::Inspector.new(config)
+    report = inspector.run
+    inspector.format(report, :terminal)
+
+    exit(1) if report.errors.any? || report.warnings.any?
+  end
+end
+
+desc "Lint Rails routes using RouteGuard"
+task route_guard: ["routes:lint"]

metadata

@@ -0,0 +1,195 @@
+--- !ruby/object:Gem::Specification
+name: route_guard
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Amritesh Tiwari
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-08-04 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rainbow
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.1'
+- !ruby/object:Gem::Dependency
+  name: thor
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+- !ruby/object:Gem::Dependency
+  name: actionpack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.1'
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.1'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.4'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.4'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
+description: Analyze Rails routes for shadowing, duplicates, unreachable routes, and
+  maintainability metrics.
+email:
+- t.amritesh801@gmail.com
+executables:
+- route_guard
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- Gemfile
+- Gemfile.lock
+- README.md
+- Rakefile
+- bin/route_guard
+- docs/publishing.md
+- docs/usage.md
+- lib/route_guard.rb
+- lib/route_guard/analyzer.rb
+- lib/route_guard/cli.rb
+- lib/route_guard/configuration.rb
+- lib/route_guard/formatter/ci.rb
+- lib/route_guard/formatter/html.rb
+- lib/route_guard/formatter/json.rb
+- lib/route_guard/formatter/terminal.rb
+- lib/route_guard/inspector.rb
+- lib/route_guard/models/issue.rb
+- lib/route_guard/models/report.rb
+- lib/route_guard/models/route.rb
+- lib/route_guard/railtie.rb
+- lib/route_guard/route_loader.rb
+- lib/route_guard/route_tracker.rb
+- lib/route_guard/rules/base.rb
+- lib/route_guard/rules/complexity.rb
+- lib/route_guard/rules/duplicate_helpers.rb
+- lib/route_guard/rules/duplicate_resources.rb
+- lib/route_guard/rules/duplicate_routes.rb
+- lib/route_guard/rules/shadowed_routes.rb
+- lib/route_guard/rules/statistics.rb
+- lib/route_guard/rules/unreachable_routes.rb
+- lib/route_guard/rules/unused_routes.rb
+- lib/route_guard/version.rb
+- lib/tasks/route_guard.rake
+homepage: https://github.com/amriteshtiwari/RouteGuard
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/amriteshtiwari/RouteGuard
+  source_code_uri: https://github.com/amriteshtiwari/RouteGuard
+  changelog_uri: https://github.com/amriteshtiwari/RouteGuard/blob/main/CHANGELOG.md
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.3
+signing_key:
+specification_version: 4
+summary: A production-ready static analysis tool for Rails routes.
+test_files: []