usernames 0.1.3 → 0.2.0

data/app/controllers/usernames/availability_controller.rb

@@ -0,0 +1,177 @@
+# frozen_string_literal: true
+
+module Usernames
+  # GET /usernames/availability?username=javi&target=user
+  #   => { "state": "free" | "taken" | "invalid", "message": "…" }
+  #
+  # The endpoint behind `f.username_field`. The engine draws its route
+  # (config.availability.path); `target` is an alias from
+  # config.availability.targets, and any other value is a 404.
+  #
+  # An availability endpoint tells anyone which names exist — that is its
+  # job — so it comes with guard rails:
+  #
+  # * Rails' own rate_limit (config.availability.rate_limit), counted in
+  #   config.availability.rate_limit_store (Rails.cache by default), read
+  #   once when this class loads. A store that cannot count — the NullStore,
+  #   Rails' default in development and test, or a backend that is down —
+  #   makes the limiter count nothing, so outside development and test the
+  #   endpoint answers 503, with a log line, until it can. A MemoryStore
+  #   works, but per process: each worker counts on its own, so it logs a
+  #   warning once.
+  # * Taken, reserved and not-allowed names all answer "taken", with one
+  #   message: no list, matched word or reason is ever sent to the browser.
+  # * Never cached (no-store), whatever the answer, and advisory only: the
+  #   model's validations and the unique index decide at save time.
+  #
+  # It inherits config.availability.parent_controller (your
+  # ApplicationController by default), so that controller's locale and
+  # authentication callbacks apply. Copy it into your app to change it:
+  # `rails generate usernames:availability --copy`.
+  class AvailabilityController < Usernames.configuration.availability.parent_class
+    # Raised by the counter when the rate limit store cannot count.
+    class CounterUnavailable < StandardError; end
+
+    # The store Rails' rate_limit writes to, wrapped so that a count that
+    # did not happen is noticed: Rails' limiter lets a request through when
+    # increment returns nil, which is exactly what a NullStore, or a cache
+    # whose backend is down, returns.
+    class Counter
+      attr_reader :store
+
+      def initialize(store)
+        @store = store
+        @warned = Concurrent::AtomicBoolean.new(false)
+      end
+
+      def increment(name, amount = 1, **)
+        count = begin
+          store.increment(name, amount, **)
+        rescue StandardError => e
+          failure = e
+          nil
+        end
+        return count if count.is_a?(Integer)
+
+        unavailable!(failure)
+      end
+
+      def null?
+        store.is_a?(ActiveSupport::Cache::NullStore)
+      end
+
+      def memory?
+        store.is_a?(ActiveSupport::Cache::MemoryStore)
+      end
+
+      # Why nothing was counted, for the log.
+      def problem(failure = nil)
+        if null? then "the rate limit store is the NullStore, where Rails' rate_limit counts nothing"
+        elsif failure then "the rate limit store failed to count (#{failure.class}: #{failure.message})"
+        else "the rate limit store's increment returned nothing, so Rails' rate_limit counts nothing"
+        end
+      end
+
+      private
+
+      # In development and test an unlimited check is the useful one: log
+      # once and let it through. Anywhere else, refuse.
+      def unavailable!(failure)
+        raise CounterUnavailable, problem(failure) unless Rails.env.local?
+
+        if @warned.make_true
+          Rails.logger.warn "[usernames] The availability check isn't rate limited here: #{problem(failure)}. " \
+                            "Outside development and test it answers 503 until the store can count."
+        end
+        0
+      end
+    end
+
+    # Captured once: the very object the limiter writes to.
+    RATE_LIMIT = Counter.new(Usernames.configuration.availability.rate_limit_store || Rails.cache)
+
+    MEMORY_STORE_WARNED = Concurrent::AtomicBoolean.new(false)
+
+    # Format failures are shown as they are (the browser hints them anyway);
+    # reserved and not-allowed names are reported as taken (see above).
+    FORMAT_FAILURES = Rules.format_reasons
+
+    # Far beyond any username: what is longer is cut here, before the
+    # normaliser sees it, and still breaks the length rule.
+    LONGEST = 1024
+
+    # Before everything else, the limiter included: an answer about who
+    # exists is never cached, and neither is a 404, a 429 or a 503.
+    prepend_before_action :no_store
+
+    # A counter of its own: an unnamed limiter the parent declares would key
+    # on this controller's path too, and the two would share one count and
+    # one expiry — a parent's shorter window resetting this one, a longer
+    # one spending it twice. Rails 8 takes a name for that; Rails 7.2 keys
+    # only on `by`, so there the name goes into it.
+    OWN_COUNTER =
+      if instance_method(:rate_limiting).parameters.any? { |_kind, name| name == :name }
+        { name: "usernames/availability" }
+      else
+        { by: -> { "usernames/availability:#{request.remote_ip}" } }
+      end
+
+    rate_limit(**Usernames.configuration.availability.rate_limit, **OWN_COUNTER, store: RATE_LIMIT,
+                                                                                 with: -> { head :too_many_requests })
+
+    before_action :warn_about_a_memory_store
+    # After the limiter, so guessing aliases is rate limited too.
+    before_action :find_the_target
+
+    rescue_from CounterUnavailable do |error|
+      Rails.logger.error "[usernames] The availability check is off (503): #{error.message}. " \
+                         "Use a shared store that counts: Solid Cache, Redis or Memcached."
+      head :service_unavailable
+    end
+
+    def show
+      render json: answer_for(typed)
+    end
+
+    private
+
+    def find_the_target
+      @model, @column = Targets.find(params[:target])
+      head :not_found unless @model
+    end
+
+    def typed
+      value = params[:username]
+      value.is_a?(String) ? value[0, LONGEST] : ""
+    end
+
+    # Every message in the model's own words: a translation under
+    # activerecord.errors.models.<model>.attributes.<column> wins here as on
+    # the form.
+    def answer_for(value)
+      result = @model.public_send(:"check_#{@column}", value)
+
+      if result.canonical.empty?
+        { state: "invalid", message: message(:blank) }
+      elsif FORMAT_FAILURES.include?(result.reason)
+        { state: "invalid", message: result.message }
+      elsif result.ok? && @model.public_send(:"#{@column}_available?", result.canonical)
+        { state: "free", message: Locale.t(:usernames, :available) }
+      else
+        { state: "taken", message: message(:taken) }
+      end
+    end
+
+    def message(type)
+      @model.new.errors.generate_message(@column, type)
+    end
+
+    def warn_about_a_memory_store
+      return unless RATE_LIMIT.memory? && MEMORY_STORE_WARNED.make_true
+
+      Rails.logger.warn "[usernames] The availability check's rate limit uses a MemoryStore, which each " \
+                        "process counts on its own. Use a shared store (Solid Cache, Redis, Memcached) for one " \
+                        "limit per client."
+    end
+  end
+end

data/config/importmap.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+# Drawn into the app's importmap by the engine (importmap-rails only).
+# `import "usernames"` registers the username-check Stimulus controller on the
+# app's own Stimulus application; "usernames/username-check" is the controller
+# alone, for an app that registers it itself.
+pin "usernames", to: "usernames/index.js"
+pin "usernames/username-check", to: "usernames/username_check_controller.js"

data/config/locales/usernames.en.yml

@@ -48,9 +48,13 @@ en:
         one: "is too long (maximum is 1 character)"
         other: "is too long (maximum is %{count} characters)"
   usernames:
-    # What the generated availability check says, in its live region, when
-    # a name is free to take.
+    # What the availability check says, in its live region, when a name is
+    # free to take…
     available: "is available"
+    availability:
+      # …and when it could not ask (offline, rate limited, switched off).
+      # The form still submits; the model decides.
+      error: "couldn't be checked just now"
     # The pieces the phrases above are built from.
     letters:
       lowercase: "lowercase letters"

data/config/locales/usernames.es.yml

@@ -32,6 +32,8 @@ es:
         other: "es demasiado largo (%{count} caracteres máximo)"
   usernames:
     available: "está disponible"
+    availability:
+      error: "no se pudo comprobar ahora"
     letters:
       lowercase: "letras minúsculas"
       any_case: "letras"

data/config/locales/usernames.pt.yml

@@ -32,6 +32,8 @@ pt:
         other: "é muito longo (máximo: %{count} caracteres)"
   usernames:
     available: "está disponível"
+    availability:
+      error: "não foi possível verificar agora"
     letters:
       lowercase: "letras minúsculas"
       any_case: "letras"

data/lib/generators/usernames/availability_generator.rb

@@ -4,58 +4,119 @@ require "rails/generators/base"
 
 module Usernames
   module Generators
-    # rails generate usernames:availability [--model=User] [--column=username]
+    # rails generate usernames:availability [--copy] [--model=User] [--column=username]
     #
-    # Copies a live "is this name free?" check into the app:
-    # nothing is mounted behind its back, and every file is the app's to edit.
+    # The live "is this name free?" check is built in: the gem's endpoint,
+    # its route and its Stimulus controller, used by `f.username_field`. On
+    # its own this generator says so, and — when it finds the files a 0.1
+    # install copied into the app — what to do with them.
     #
-    #   app/controllers/usernames/availability_controller.rb   GET /usernames/availability?<column>=…
+    # --copy writes a set of your own to change, which replaces the gem's:
+    #
+    #   app/controllers/usernames/availability_controller.rb   the endpoint (the gem's class, overridden)
     #   app/javascript/controllers/username_check_controller.js
     #   app/views/usernames/_field.html.erb                     <%= render "usernames/field", form: form %>
+    #   config/routes.rb                                         usernames_availability, at the top
     class AvailabilityGenerator < Rails::Generators::Base
       source_root File.expand_path("templates/availability", __dir__)
 
-      desc "Copy a rate-limited availability endpoint, a Stimulus controller and a form partial into your app."
+      desc "Explain the built-in availability check, or copy it into your app (--copy) to customise it."
 
+      class_option :copy, type: :boolean, default: false, desc: "Copy the endpoint, the JavaScript and a partial"
       class_option :model, type: :string, default: "User", desc: "The model with has_username"
       class_option :column, type: :string, default: "username", desc: "Its username column"
 
-      def create_controller
-        template "availability_controller.rb.tt", "app/controllers/usernames/availability_controller.rb"
+      GEM = File.expand_path("../../..", __dir__)
+      CONTROLLER = "app/controllers/usernames/availability_controller.rb"
+      JAVASCRIPT = "app/javascript/controllers/username_check_controller.js"
+      PARTIAL = "app/views/usernames/_field.html.erb"
+      ROUTES = "config/routes.rb"
+
+      # Read before anything is written, so --copy's own files are not mistaken for 0.1's.
+      def look_for_copied_files
+        @found = [CONTROLLER, JAVASCRIPT, PARTIAL].select { |path| File.exist?(File.join(destination_root, path)) }
+        @found << ROUTES if routes.include?("usernames/availability#show")
+      end
+
+      def copy_the_endpoint
+        return unless options[:copy]
+
+        create_file CONTROLLER, copied("#", File.read(File.join(GEM, CONTROLLER), encoding: "UTF-8"))
       end
 
-      # Thor injects a line only once, so a re-run leaves routes.rb alone.
-      def add_route
-        route %(get "usernames/availability", to: "usernames/availability#show", as: :usernames_availability)
+      def copy_the_javascript
+        return unless options[:copy]
+
+        source = File.join(GEM, "app/assets/javascripts/usernames/username_check_controller.js")
+        create_file JAVASCRIPT, copied("//", File.read(source, encoding: "UTF-8"))
       end
 
-      def create_stimulus_controller
-        template "username_check_controller.js.tt", "app/javascript/controllers/username_check_controller.js"
+      def copy_the_partial
+        template "_field.html.erb.tt", PARTIAL if options[:copy]
       end
 
-      def create_partial
-        template "_field.html.erb.tt", "app/views/usernames/_field.html.erb"
+      # Above every other route, so a catch-all can't shadow it; the engine
+      # then draws none. Thor injects a line only once.
+      def draw_the_route
+        route "usernames_availability" if options[:copy]
       end
 
       def display_post_install_message
-        say "\n\tThe `usernames` availability check has been successfully installed!", :green
-        say "\nTo complete the setup:"
-        say "  1. Render the field in your sign-up form: <%= render \"usernames/field\", form: form %>"
-        say "  2. If you don't use importmap's eagerLoadControllersFrom, register the Stimulus controller " \
-            "(rails stimulus:manifest:update)."
-        say "  3. Give production a shared cache store (Solid Cache, Redis or Memcached). With the NullStore, " \
-            "Rails' rate_limit counts nothing, so the endpoint answers 503 there until you do."
-        say "\nThe route is declared at the top of config/routes.rb, so a catch-all /:#{column} below it can't shadow it."
-        say "Hints in the browser never block submission: the model and its unique index decide.", :green
+        options[:copy] ? copied_message : built_in_message
+        upgrade_message unless @found.empty? || options[:copy]
       end
 
       private
 
+      def built_in_message
+        say "\n\tThe availability check is built into the usernames gem: nothing to generate.", :green
+        say "\n  <%= f.username_field :#{column} %> <%= f.username_status :#{column} %>   in the form"
+        say %(  import "usernames"                                   in app/javascript/application.js)
+        say %(  config.availability.targets = { #{target_alias.inspect} => "#{model_name}##{column}" }   in the initializer)
+        say "\nTo change how it works, copy it into your app: rails generate usernames:availability --copy"
+      end
+
+      # A 0.1 install copied a controller, a route, a Stimulus controller and
+      # a partial that speak an older protocol. Either mode keeps the pair
+      # consistent; mixing them does not.
+      def upgrade_message
+        say "\nFound files a 0.1 install copied into this app: #{@found.join(', ')}.", :yellow
+        say "They speak the 0.1 protocol, and the app's copies win over the gem's. Pick one:"
+        say "  * Managed (recommended): delete them all — the controller, the usernames/availability route, " \
+            "the Stimulus controller and the partial — and use f.username_field / f.username_status with " \
+            "`import \"usernames\"`. Upgrades then come with the gem."
+        say "  * Customized: keep your pair, and set config.availability.path = nil so the gem draws no route. " \
+            "Don't `import \"usernames\"`: your Stimulus controller is the one registered as username-check."
+      end
+
+      def copied_message
+        say "\n\tThe availability check is now yours to change.", :green
+        say "\n  #{CONTROLLER} replaces the gem's endpoint (same class); `usernames_availability` in config/routes.rb " \
+            "draws its route, above any catch-all, so the gem draws none."
+        say "  #{JAVASCRIPT} is registered by your Stimulus setup as username-check: remove " \
+            "`import \"usernames\"` from app/javascript/application.js, or the gem's would register over it."
+        say %(  Render the field with <%= render "usernames/field", form: form %>.)
+        say "  The endpoint answers for config.availability.targets, as the gem's did: keep " \
+            "{ #{target_alias.inspect} => \"#{model_name}##{column}\" } there."
+        say "Gem upgrades no longer change these files: compare them with the gem's when you upgrade.", :yellow
+      end
+
+      def copied(comment, source)
+        note = "#{comment} Copied from the usernames gem by `rails generate usernames:availability --copy`. " \
+               "It's yours: edit it.\n"
+        source.start_with?("# frozen_string_literal") ? source.sub("\n", "\n\n#{note}") : note + source
+      end
+
+      def routes
+        path = File.join(destination_root, ROUTES)
+        File.exist?(path) ? File.read(path) : ""
+      end
+
       def model_name
         options[:model].camelize
       end
 
-      def singular
+      def target_alias
         model_name.underscore.tr("/", "_")
       end
 

data/lib/generators/usernames/install_generator.rb

@@ -4,6 +4,7 @@ require "rails/generators/base"
 require "rails/generators/active_record"
 require_relative "existing_schema"
 require_relative "install_messages"
+require_relative "javascript_setup"
 
 module Usernames
   module Generators
@@ -20,9 +21,14 @@ module Usernames
     # added. A column that already holds usernames gets the adoption workflow
     # instead of a promise: the index cannot be trusted — or even added —
     # until `rails usernames:audit` comes back clean.
+    #
+    # The initializer publishes that column to the live availability check
+    # (config.availability.targets), and in an importmap + Stimulus app the
+    # generator adds `import "usernames"` to app/javascript/application.js, once.
     class InstallGenerator < Rails::Generators::Base
       include ActiveRecord::Generators::Migration
       include InstallMessages
+      include JavascriptSetup
 
       source_root File.expand_path("templates", __dir__)
 
@@ -65,6 +71,19 @@ module Usernames
         migration_template "add_username.rb.erb", File.join(db_migrate_path, "#{migration_name}.rb")
       end
 
+      # Only where the line can work: importmap (nothing else resolves it),
+      # the entrypoint, and stimulus-rails' controllers/application.js
+      # exporting the `application` it registers on. Never twice, and never
+      # removing anything.
+      def add_the_javascript_import
+        return unless javascript_setup == :ready
+
+        separator = File.read(destination(APPLICATION_JS)).end_with?("\n") ? "" : "\n"
+        # force: Thor would skip text it finds anywhere in the file, even in a
+        # comment; javascript_setup has already said the import is missing.
+        append_to_file APPLICATION_JS, %(#{separator}import "usernames"\n), force: true
+      end
+
       def display_post_install_message
         say "\n\tThe `usernames` gem has been successfully installed!", :green
         warn_about_the_database unless database.reachable?
@@ -74,6 +93,11 @@ module Usernames
 
       private
 
+      # The initializer's line: config.availability.targets = { "user" => "User#handle" }.
+      def target_alias = model_name.underscore.tr("/", "_")
+
+      def target = "#{model_name}##{column}"
+
       # --- what the migration does -----------------------------------------------------------------
 
       # A file name and a constant, whatever the table is called:

data/lib/generators/usernames/install_messages.rb

@@ -12,10 +12,9 @@ module Usernames
         say "\nTo complete the setup:"
         say "  1. Run 'rails db:migrate'#{migration_summary}."
         say "  2. Add `#{macro_line}` to your #{model_name} model."
-        say "  3. Optionally, run 'rails generate usernames:availability' for a live \"is this name free?\" " \
-            "check on your sign-up form."
         say "\nUsernames are unique from the moment the index exists: the database decides, " \
             "with the same comparison the gem uses everywhere."
+        integration_message
       end
 
       # On a populated column no index is a promise — not even one already in
@@ -35,8 +34,48 @@ module Usernames
         say "  4. Add `#{macro_line}` to your #{model_name} model. Existing names that break today's rules " \
             "keep working; only a change is validated."
         say "  See \"Adopting an existing column\" in the README."
+        integration_message
       end
 
+      # Then, in the forms: the field and its status, and the one line of
+      # JavaScript behind them.
+      def integration_message
+        say "\nThen, in any form for a #{model_name}, a username field that checks names as people type:"
+        say "  <%= f.label :#{column} %> <%= f.username_field :#{column} %> <%= f.username_status :#{column} %>"
+        say "  #{JAVASCRIPT_STEPS.fetch(javascript_setup)}"
+        devise_message if defined?(::Devise)
+        say "  In production, the check counts requests in Rails.cache: give it a shared store (Solid Cache, " \
+            "Redis, Memcached). It answers 503 until one counts."
+      end
+
+      # Devise permits only its own attributes: without these lines a sign-up
+      # form says the name is free, and the save drops it.
+      def devise_message
+        say "  Devise drops attributes it doesn't know, so permit :#{column} where people choose or change " \
+            "it (in ApplicationController, before_action ... if: :devise_controller?):"
+        say "    devise_parameter_sanitizer.permit(:sign_up, keys: [:#{column}])"
+        say "    devise_parameter_sanitizer.permit(:account_update, keys: [:#{column}])"
+      end
+
+      JAVASCRIPT_STEPS = {
+        ready: %(Added `import "usernames"` to app/javascript/application.js.),
+        imported: %(app/javascript/application.js already has `import "usernames"`.),
+        no_importmap: "No importmap here: run 'rails generate usernames:javascript' to copy the Stimulus controller " \
+                      "into app/javascript/controllers (then it is yours to keep up to date).",
+        no_entrypoint: %(No app/javascript/application.js: add `import "usernames"` to your importmap entrypoint.),
+        no_stimulus: "No app/javascript/controllers/application.js (stimulus-rails' Stimulus setup): the field " \
+                     "works as a plain input; with stimulus-rails, add `import \"usernames\"` for the live check.",
+        uncertain_source: "Didn't add `import \"usernames\"`: app/javascript/controllers/application.js has " \
+                          "constructs the installer won't guess at (template interpolation or a regular " \
+                          "expression). Add the line yourself if that file exports `application`.",
+        no_application_export: "Didn't add `import \"usernames\"`: app/javascript/controllers/application.js " \
+                               "doesn't export the Stimulus application by the name `application` " \
+                               "(`export { application }`), which it imports, and a missing export would stop " \
+                               "app/javascript/application.js loading at all. Export it under that name and add the " \
+                               "line, or register \"usernames/username-check\" on your application yourself."
+      }.freeze
+      private_constant :JAVASCRIPT_STEPS
+
       def index_doubt
         return "the unique index isn't trustworthy yet (it may not even be addable)" if add_index?
 

data/lib/generators/usernames/javascript_generator.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require "rails/generators/base"
+
+module Usernames
+  module Generators
+    # rails generate usernames:javascript
+    #
+    # For an app that bundles its JavaScript (jsbundling, esbuild, Vite…)
+    # rather than using importmap, where `import "usernames"` has nothing to
+    # resolve it: copies the gem's Stimulus controller to
+    # app/javascript/controllers/username_check_controller.js, where the
+    # bundler and Stimulus' manifest pick it up. From then on the file is
+    # the app's: run this again after a gem upgrade to refresh it.
+    class JavascriptGenerator < Rails::Generators::Base
+      desc "Copy the username-check Stimulus controller into app/javascript/controllers (for jsbundling apps)."
+
+      SOURCE = File.expand_path("../../../app/assets/javascripts/usernames/username_check_controller.js", __dir__)
+      DESTINATION = "app/javascript/controllers/username_check_controller.js"
+
+      def copy_the_controller
+        note = "// Copied from the usernames gem #{Usernames::VERSION} by `rails generate usernames:javascript`. " \
+               "Run it again after upgrading the gem.\n"
+        create_file DESTINATION, note + File.read(SOURCE, encoding: "UTF-8")
+      end
+
+      def display_post_install_message
+        say "\n\t#{DESTINATION} is in place.", :green
+        say "\nRegister it as username-check: `rails stimulus:manifest:update`, or in " \
+            "app/javascript/controllers/index.js:"
+        say %(  import UsernameCheckController from "./username_check_controller"\n) +
+            %(  application.register("username-check", UsernameCheckController))
+        say "Then f.username_field / f.username_status work as with importmap. The file is the app's now: " \
+            "the gem's fields and endpoint change with the gem, so refresh it when you upgrade.", :yellow
+      end
+    end
+  end
+end

data/lib/generators/usernames/javascript_setup.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+module Usernames
+  module Generators
+    # Whether `import "usernames"` can work in the app being installed into,
+    # for `rails generate usernames:install`: importmap (nothing else
+    # resolves the specifier), an app/javascript/application.js entrypoint,
+    # and stimulus-rails' controllers/application.js exporting the
+    # `application` the gem's index.js imports by name. A static import of a
+    # name a module doesn't export fails the whole entrypoint before any of
+    # it runs, so anything short of a plain named export is a no. :nodoc:
+    module JavascriptSetup
+      APPLICATION_JS = "app/javascript/application.js"
+      STIMULUS_APPLICATION = "app/javascript/controllers/application.js"
+      IMPORTED = /^\s*import\s+["']usernames["']/
+
+      # `export const application = …` (or let, var).
+      EXPORTS_A_BINDING = /\bexport\s+(?:const|let|var)\s+application\b/
+
+      # `export { … }`, with an optional `from "…"`: the list, to read.
+      EXPORT_LISTS = /\bexport\s*\{([^}]*)\}/
+
+      # One entry of such a list: `application`, `application as application`,
+      # or `other as application` — whatever is exported under that name.
+      EXPORTED_AS_APPLICATION = /\A(?:application|[\w$]+\s+as\s+application)\z/
+
+      QUOTES = %w[' " `].freeze
+
+      private
+
+      # :ready, :imported, or what is missing for the line to work. Read
+      # once, before the line is added, so the message can say it was.
+      def javascript_setup
+        @javascript_setup ||=
+          if !File.exist?(destination("config/importmap.rb")) then :no_importmap
+          elsif !File.exist?(destination(APPLICATION_JS)) then :no_entrypoint
+          elsif code(APPLICATION_JS, strings: true).match?(IMPORTED) then :imported
+          elsif !File.exist?(destination(STIMULUS_APPLICATION)) then :no_stimulus
+          elsif uncertain?(STIMULUS_APPLICATION) then :uncertain_source
+          elsif !exports_application?(code(STIMULUS_APPLICATION)) then :no_application_export
+          else :ready
+          end
+      end
+
+      def exports_application?(source)
+        source.match?(EXPORTS_A_BINDING) || source.scan(EXPORT_LISTS).flatten.any? do |list|
+          list.split(",").any? { |entry| entry.strip.match?(EXPORTED_AS_APPLICATION) }
+        end
+      end
+
+      # A file read as code, in one pass: each comment becomes one space
+      # (so `export/* c */const` still reads as two words), each string or
+      # template literal `""` (so `"export { application }"` exports
+      # nothing, and the `//` in `"https://…"` starts no comment).
+      # `strings: true` keeps '…' and "…" strings as written, to read an
+      # import's specifier.
+      def code(path, strings: false)
+        scan(path, strings).first
+      end
+
+      # Whether the file has what this reading doesn't follow, and so won't
+      # guess about: a template literal interpolating `${…}` (which may nest
+      # code, comments and more templates) or a `/` that starts no comment —
+      # division, or a regular-expression literal that may hold anything.
+      # stimulus-rails' generated controllers/application.js has neither.
+      def uncertain?(path)
+        scan(path, false).last
+      end
+
+      # [code, uncertain]
+      def scan(path, strings)
+        source = File.read(destination(path), encoding: "UTF-8")
+        code = +""
+        uncertain = false
+        index = 0
+        while index < source.length
+          finish = token_end(source, index)
+          uncertain ||= finish ? interpolates?(source, index, finish) : source[index] == "/"
+          code << (finish ? token(source, index, finish, strings) : source[index])
+          index = finish || (index + 1)
+        end
+        [code, uncertain]
+      end
+
+      def interpolates?(source, start, finish)
+        source[start] == "`" && source[start...finish].include?("${")
+      end
+
+      # Where the comment or literal starting at `index` ends, or nil for
+      # any other character.
+      def token_end(source, index)
+        case source[index, 2]
+        when "//" then source.index("\n", index) || source.length
+        when "/*" then (finish = source.index("*/", index + 2)) ? finish + 2 : source.length
+        else literal_end(source, index) if QUOTES.include?(source[index])
+        end
+      end
+
+      def token(source, start, finish, strings)
+        return " " if source[start] == "/"
+        return source[start...finish] if strings && source[start] != "`"
+
+        '""'
+      end
+
+      # Just past the literal opening at `start`: its closing quote, with
+      # backslash escapes skipped. A '…' or "…" string ends at a line break
+      # at the latest; a template's `${…}` is read as part of it.
+      def literal_end(source, start)
+        quote = source[start]
+        index = start + 1
+        while index < source.length
+          return index + 1 if source[index] == quote
+          return index if source[index] == "\n" && quote != "`"
+
+          index += source[index] == "\\" ? 2 : 1
+        end
+        source.length
+      end
+
+      def destination(path) = File.join(destination_root, path)
+    end
+  end
+end