Support banner option

Author: bogdan

CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## v2.3.2
+
+* Add `banner` option that allow to control JSDoc on top of generated file. [#324](https://github.com/bogdan/repo/issues/324).
+
+``` ruby
+JsRoutes.configure do |c|
+c.banner = -> {
+  commit_hash = `git rev-parse --short HEAD`.strip
+
+  <<~DOC
+  @file Javascript Route helpers of my magic pony app.
+  @author Bogdan Gusiev
+  @license MIT
+  @version #{commit_hash}
+  DOC
+}
+end
+```
+
 ## v2.3.1
 
 * Add timestamp on when routes.js was generated into banner.

Readme.md

@@ -331,6 +331,17 @@ Options to configure JavaScript file generator. These options are only available
 * `optional_definition_params` - make all route paramters in definition optional
   * See [related compatibility issue](#optional-definition-params)
   * Default: `false`
+* `banner` - specify the comment on top of the file.
+  * It is not stripped by minifiers by default and helps to originate the content when debugging the build.
+  * You may want to control how much information from backend is exposed to potential attacker at the cost of your own comfort.
+  * See [JSDoc Guide](https://github.com/shri/JSDoc-Style-Guide/blob/master/README.md#files)
+  * Supports a lazy generation with `Proc`.
+  * Default: A string that generates the following:
+
+```
+File generated by js-routes 2.3.1 on <TIMESTAMP>
+Based on Rails 7.2.0 routes of App
+```
 
 <div id="formatter-options"></div>
 

lib/js_routes/configuration.rb

@@ -3,6 +3,7 @@
 require "pathname"
 require "js_routes/types"
 require 'js_routes/utils'
+require 'js_routes/version'
 
 module JsRoutes
   class Configuration
@@ -39,6 +40,8 @@ class Configuration
     attr_accessor :module_type
     sig { returns(T::Boolean) }
     attr_accessor :optional_definition_params
+    sig { returns(BannerCaller) }
+    attr_accessor :banner
 
     sig {params(attributes: T.nilable(Options)).void }
     def initialize(attributes = nil)
@@ -57,6 +60,7 @@ def initialize(attributes = nil)
       @module_type = T.let('ESM', T.nilable(String))
       @documentation = T.let(true, T::Boolean)
       @optional_definition_params = T.let(false, T::Boolean)
+      @banner = T.let(default_banner, BannerCaller)
 
       return unless attributes
       assign(attributes)
@@ -158,5 +162,17 @@ def verify
         raise "JsRoutes namespace option can only be used if module_type is nil"
       end
     end
+
+    sig { returns(T.proc.returns(String)) }
+    def default_banner
+      -> () {
+        app = application.is_a?(Proc) ? application.call : application
+        <<~TXT
+          File generated by js-routes #{JsRoutes::VERSION} on #{Time.now}
+          Based on Rails #{Rails.version} routes of #{app.class}
+        TXT
+
+      }
+    end
   end
 end

lib/js_routes/instance.rb

@@ -29,9 +29,9 @@ def generate
       if named_routes.empty?
         if application.is_a?(Rails::Application)
           if Rails.version >= "8.0.0"
-            application.reload_routes_unless_loaded
+            T.unsafe(application).reload_routes_unless_loaded
           else
-            application.reload_routes!
+            T.unsafe(application).reload_routes!
           end
         end
       end
@@ -43,7 +43,20 @@ def generate
           raise("Missing key #{key} in JS template")
         end
       end
-      content + routes_export + prevent_types_export
+      banner + content + routes_export + prevent_types_export
+    end
+
+    sig { returns(String) }
+    def banner
+      banner = @configuration.banner
+      banner = banner.call if banner.is_a?(Proc)
+      return "" if banner.blank?
+      [
+        "/**",
+        *banner.split("\n").map { |line| " * #{line}" },
+        " */",
+        "",
+      ].join("\n")
     end
 
     sig { void }
@@ -79,12 +92,11 @@ def js_variables
       prefix = @configuration.prefix
       prefix = prefix.call if prefix.is_a?(Proc)
       {
-        'GEM_VERSION'         => JsRoutes::VERSION,
-        'TIMESTAMP'           => Time.now.to_s,
+        # 'GEM_VERSION'         => JsRoutes::VERSION,
         'ROUTES_OBJECT'       => routes_object,
-        'RAILS_VERSION'       => ::Rails.version,
+        # 'RAILS_VERSION'       => ::Rails.version,
         'DEPRECATED_FALSE_PARAMETER_BEHAVIOR' => Rails.version < '7.0.0',
-        'APP_CLASS'           => application.class.to_s,
+        # 'APP_CLASS'           => application.class.to_s,
         'DEFAULT_URL_OPTIONS' => json(@configuration.default_url_options),
         'PREFIX'              => json(prefix),
         'SPECIAL_OPTIONS_KEY' => json(@configuration.special_options_key),
@@ -187,7 +199,7 @@ def mounted_app_routes(route)
       rails_engine_app = T.unsafe(app_from_route(route))
       if rails_engine_app.is_a?(Class) &&
           rails_engine_app < Rails::Engine && !route.path.anchored
-        rails_engine_app.routes.named_routes.flat_map do |_, engine_route|
+        T.unsafe(rails_engine_app).routes.named_routes.flat_map do |_, engine_route|
           route_helpers_if_match(engine_route, route)
         end
       else
@@ -200,7 +212,7 @@ def app_from_route(route)
       app = route.app
       # Rails Engine can use additional
       # ActionDispatch::Routing::Mapper::Constraints, which contain app
-      if app.is_a?(ActionDispatch::Routing::Mapper::Constraints)
+      if app.is_a?(T.unsafe(ActionDispatch::Routing::Mapper::Constraints))
         app.app
       else
         app

lib/js_routes/middleware.rb

@@ -6,7 +6,7 @@ module JsRoutes
   # whenever routes.rb is modified
   #
   # Inspired by
-  # https://github.com/fnando/i18n-js/blob/main/lib/i18n/js/middleware.rb
+  # https://github.com/fnando/i18n-js/blob/v3/lib/i18n/js/middleware.rb
   class Middleware
     include JsRoutes::Types
     include RackApp

lib/js_routes/types.rb

@@ -16,11 +16,20 @@ module Types
     Literal = T.type_alias { T.any(String, Symbol) }
     JourneyRoute = T.type_alias{ActionDispatch::Journey::Route}
     RouteSpec = T.type_alias {T.untyped}
-    Application = T.type_alias { T.any(T::Class[Rails::Engine], Rails::Application) }
-    ApplicationCaller = T.type_alias { T.any(Application, T.proc.returns(Application)) }
+    Application = T.type_alias do
+      T.any(T::Class[Rails::Engine], Rails::Application)
+    end
+    ApplicationCaller = T.type_alias do
+      T.any(Application, T.proc.returns(Application))
+    end
+    BannerCaller = T.type_alias do
+      T.any(String, NilClass, T.proc.returns(T.any(String, NilClass)))
+    end
     Clusivity = T.type_alias { T.any(Regexp, T::Array[Regexp]) }
     FileName = T.type_alias { T.any(String, Pathname, NilClass) }
-    ConfigurationBlock = T.type_alias { T.proc.params(arg0: JsRoutes::Configuration).void }
+    ConfigurationBlock = T.type_alias do
+      T.proc.params(arg0: JsRoutes::Configuration).void
+    end
     Prefix = T.type_alias do
       T.any(T.proc.returns(String), String, NilClass)
     end

lib/js_routes/version.rb

@@ -1,4 +1,6 @@
 # typed: strict
+require 'sorbet-runtime'
+
 module JsRoutes
-  VERSION = "2.3.1"
+  VERSION = T.let("2.3.1", String)
 end

lib/routes.d.ts

@@ -1,7 +1,3 @@
-/**
- * File generated by js-routes RubyVariables.GEM_VERSION on RubyVariables.TIMESTAMP
- * Based on Rails RubyVariables.RAILS_VERSION routes of RubyVariables.APP_CLASS
- */
 declare type Optional<T> = {
     [P in keyof T]?: T[P] | null;
 };

lib/routes.js

@@ -1,7 +1,3 @@
-/**
- * File generated by js-routes RubyVariables.GEM_VERSION on RubyVariables.TIMESTAMP
- * Based on Rails RubyVariables.RAILS_VERSION routes of RubyVariables.APP_CLASS
- */
 // eslint-disable-next-line
 RubyVariables.WRAPPER(
 // eslint-disable-next-line

lib/routes.ts

@@ -1,8 +1,3 @@
-/**
- * File generated by js-routes RubyVariables.GEM_VERSION on RubyVariables.TIMESTAMP
- * Based on Rails RubyVariables.RAILS_VERSION routes of RubyVariables.APP_CLASS
- */
-
 type Optional<T> = { [P in keyof T]?: T[P] | null };
 type Collection<T> = Record<string, T>;