usernames 0.1.3

data/lib/usernames/rules.rb

@@ -0,0 +1,257 @@
+# frozen_string_literal: true
+
+require_relative "rules/options"
+
+module Usernames
+  # The rules in force for one check: the configuration merged with one
+  # model's or one validator call's options, validated once and frozen.
+  # Build them with `Usernames.configuration.rules_for(**options)`, which
+  # caches them — every check after the first reuses the compiled regexes.
+  #
+  # The format rules are an ordered list of
+  #
+  #   [reason, test, browser_source]
+  #
+  # where `test` is a Regexp (or a lambda) that MATCHES A NAME THAT FAILS,
+  # and the first failure wins. Server regexes anchor with \A and \z: `^` and
+  # `$` are LINE anchors in Ruby, which is how "validuser\nadmin" gets past
+  # the regex everyone copies from Stack Overflow. `browser_source` is the
+  # same rule as a JavaScript RegExp source (see #for_browser), or nil for a
+  # rule the browser does not hint.
+  class Rules
+    include Options
+
+    # Every code point Ruby's \p{Space} matches (Unicode White_Space), spelled
+    # out for JavaScript, whose \s is a slightly different set (it has U+FEFF
+    # and lacks U+0085).
+    WHITESPACE_SOURCE = '[\t-\r \u0085\u00a0\u1680\u2000-\u200a\u2028\u2029\u202f\u205f\u3000]'
+
+    # A character outside the allowed set that is a non-ASCII letter (or a
+    # combining mark, as in an accent left over from `İ`): the case for the
+    # friendlier :username_unicode message.
+    NON_ASCII_LETTER = /\A(?=[^\x00-\x7F])[\p{L}\p{M}]\z/
+
+    # Endings that read as a file when dots are enabled, on top of
+    # every extension Rails' Mime registry knows: Discourse's
+    # CONFUSING_EXTENSIONS, Gitea's reserved patterns, git, and what a web
+    # server would execute or serve as a secret.
+    FILE_EXTENSIONS = %w[
+      js json css htm html xml jpg jpeg png gif bmp ico tif tiff woff
+      keys gpg rss atom
+      git
+      php asp aspx jsp cgi pl py rb sh exe dll bak env
+    ].freeze
+
+    # Every extension Rails' Mime registry knows when rules are built,
+    # including any the app registered in an initializer. None without
+    # Action Dispatch: then there is no Rails router to confuse. Read when
+    # the rules are compiled: the first check, or the first after a
+    # configuration change.
+    def self.rails_extensions
+      defined?(Mime::EXTENSION_LOOKUP) ? Mime::EXTENSION_LOOKUP.keys.map(&:to_s) : []
+    end
+
+    attr_reader :format_checks
+
+    def initialize(**options)
+      assign(options)
+      @format_checks = build_format_checks
+      # Left unfrozen on purpose: the reserved and offensive matchers keep
+      # what they build from these rules here (see #compiled).
+      @compiled = {}
+      freeze
+    end
+
+    # What a content matcher built from these rules (a reserved set, the
+    # offensive exemptions), built on first use and kept for as long as the
+    # rules are: Configuration#rules_for caches the rules, so every check
+    # after the first reuses it. Two threads may build the same thing once
+    # each; both results are equal, so either may win. :nodoc:
+    def compiled(name)
+      @compiled.fetch(name) { @compiled[name] = yield }
+    end
+
+    # Short enough to read in a console or a failing test: the lists can
+    # hold a thousand words.
+    def inspect
+      "#<#{self.class.name} length=#{length} separators=#{separators.inspect} case=#{@case.inspect} " \
+        "edge_separators=#{edge_separators} first_character=#{first_character.inspect} " \
+        "offensive.severity=#{offensive.severity.inspect}>"
+    end
+
+    def lowercase?
+      @case == :lowercase
+    end
+
+    def normalize(value)
+      Normalizer.call(value, @case)
+    end
+
+    # What two names are compared by. ASCII-only on purpose: it is exactly
+    # what PostgreSQL's lower() does under COLLATE "C", so Ruby and the
+    # database agree.
+    def comparison_key(canonical)
+      canonical.downcase(:ascii)
+    end
+
+    # The first rule `value` breaks, as a Usernames::Failure, or nil. Applied
+    # to the value AS GIVEN — normalise first if that is what you mean.
+    # Structure before content: format, then reserved, then offensive.
+    def failure_for(value)
+      string = readable(value)
+      return failure(:username_characters) unless string
+
+      format_failure(string) || content_failure(string)
+    end
+
+    def format_failure(string)
+      # `===` is Ruby's "does this match": Regexp#=== and Proc#=== both answer it.
+      reason, = format_checks.find { |_reason, test, _source| test === string } # rubocop:disable Style/CaseEquality
+      failure(reason) if reason
+    end
+
+    # Hints for a form, as [{ rule:, pattern:, message: }] in the current
+    # locale. Advisory only: Ruby's strip and JavaScript's trim()
+    # disagree on NUL, U+FEFF and U+1680, so the browser approximates
+    # normalisation and the server stays the only authority. A pattern
+    # MATCHES a name that breaks the rule, and is written in the subset both
+    # engines read the same way — no \A, \z, lookbehind or \p{…}. With a
+    # `record` and `attribute`, the messages are that model's (Failure#message).
+    def for_browser(record = nil, attribute = nil)
+      format_checks.filter_map do |reason, _test, source|
+        { rule: reason, pattern: source, message: failure(reason).message(record, attribute) } if source
+      end
+    end
+
+    # The Failure for a format rule, with the interpolations its message needs.
+    def failure(reason)
+      Failure.new(reason: reason, details: details_for(reason))
+    end
+
+    private
+
+    # Valid UTF-8, or nil when the value's own bytes are broken. The
+    # validator sees values exactly as assigned, and a regex over invalid
+    # bytes raises; such a value has characters that cannot be allowed.
+    def readable(value)
+      string = value.to_s
+      string.encode(Encoding::UTF_8) if string.valid_encoding?
+    rescue EncodingError
+      nil
+    end
+
+    # Reserved words are matched on the comparison key alone; the offensive
+    # matcher also reads the case the name was typed in (Offensive.verdict).
+    def content_failure(string)
+      if (rule = Reserved.verdict(comparison_key(string), self))
+        Failure.new(reason: :username_reserved, rule: rule)
+      elsif (rule = Offensive.verdict(string, self))
+        Failure.new(reason: :username_not_allowed, rule: rule)
+      end
+    end
+
+    def details_for(reason)
+      case reason
+      when :too_short then { count: length.min }
+      when :too_long then { count: length.max }
+      when :username_characters then characters_details
+      when :username_edges then { edge_separators_phrase: Phrase.any_separator(edge_set) }
+      else {}
+      end
+    end
+
+    # `count` (how many separators) picks the sentence: one finishes the list
+    # ("…, numbers and underscores"), more continue it ("…, numbers,
+    # underscores and periods"). With none there is no list to finish, so the
+    # message is a different translation of the same error type — not a
+    # :zero plural, which pluralizers such as rails-i18n's Spanish one ignore.
+    # username_characters_without_separators is that translation: the same
+    # error type, only worded for no separators.
+    def characters_details
+      letters = Phrase.letters(@case)
+      return { message: :username_characters_without_separators, letters: letters } if separators.empty?
+
+      { count: separators.size, letters: letters, separators_phrase: Phrase.separators(separators) }
+    end
+
+    def build_format_checks
+      [
+        [:username_spaces, /\p{Space}/, WHITESPACE_SOURCE],
+        *character_checks,
+        [:too_short, ->(string) { string.length < length.min }, "^[\\s\\S]{0,#{length.min - 1}}$"],
+        [:too_long, ->(string) { string.length > length.max }, "[\\s\\S]{#{length.max + 1}}"],
+        *separator_checks,
+        *first_character_checks,
+        # Rule 7: a name with no letter in it reads as a number, whatever
+        # separators sit between the digits (`231640921`, `123_456`), and a
+        # number is an id, not a person. Separators alone never reach this
+        # rule: edges and runs refuse them first.
+        [:username_digits_only, /\A[^A-Za-z]+\z/, "^[^A-Za-z]+$"],
+        *extension_checks
+      ].freeze
+    end
+
+    # Rule 2. Everything that is not an allowed character fails here —
+    # accents, emoji, invisible and bidi characters alike — with the
+    # friendlier :username_unicode message when every offender is a
+    # non-ASCII letter (`josé`, `иван`). The browser only hints the general
+    # rule; the refinement is the same failure in other words.
+    def character_checks
+      allowed = "#{lowercase? ? 'a-z' : 'A-Za-z'}0-9#{class_of(separators)}"
+      disallowed = /[^#{allowed}]/
+      only_letters = lambda do |string|
+        offenders = string.scan(disallowed)
+        offenders.any? && offenders.all?(NON_ASCII_LETTER)
+      end
+
+      [[:username_unicode, only_letters, nil], [:username_characters, disallowed, "[^#{allowed}]"]]
+    end
+
+    # Rules 4 and 5: no separator at an edge (never a dot, even with
+    # edge_separators — "thanks @javi." ends a sentence), no two in a row of
+    # any kind (`oliver.__-hjj`).
+    def separator_checks
+      checks = []
+      if edge_set.any?
+        edge = class_of(edge_set)
+        checks << [:username_edges, /\A[#{edge}]|[#{edge}]\z/, "^[#{edge}]|[#{edge}]$"]
+      end
+      if separators.any?
+        all = class_of(separators)
+        checks << [:username_consecutive, /[#{all}]{2}/, "[#{all}]{2}"]
+      end
+      checks
+    end
+
+    # Rule 6. With :alphanumeric any letter or digit may come first, and a
+    # separator first is rule 4's business, so there is nothing to check.
+    # With :letter the first character must be a letter even when
+    # edge_separators allows `_javi`: the stricter reading is the one that
+    # matches "must start with a letter".
+    def first_character_checks
+      return [] unless first_character == :letter
+
+      letters = lowercase? ? "a-z" : "A-Za-z"
+      [[:username_first_character, /\A[^#{letters}]/, "^[^#{letters}]"]]
+    end
+
+    # Rule 8, only when dots are allowed: `/@john.json` confuses
+    # routers, CDNs and crawlers. Not a browser hint: the hints stop at rule 7.
+    def extension_checks
+      return [] unless separators.include?(".")
+
+      extensions = (Rules.rails_extensions + FILE_EXTENSIONS).uniq.map { |extension| Regexp.escape(extension) }
+      [[:username_extension, /\.(?:#{extensions.join('|')})\z/i, nil]]
+    end
+
+    def edge_set
+      edge_separators ? separators & ["."] : separators
+    end
+
+    # The body of a character class holding exactly these separators, written
+    # the same way for Ruby and JavaScript (`\.` and `\-` mean themselves in both).
+    def class_of(characters)
+      characters.map { |character| Regexp.escape(character) }.join
+    end
+  end
+end

data/lib/usernames/unique_violation.rb

@@ -0,0 +1,176 @@
+# frozen_string_literal: true
+
+module Usernames
+  # Whether an ActiveRecord::RecordNotUnique came from the username's own
+  # unique index — the one that decides who has a name — or from another one.
+  #
+  # A duplicate email raises exactly the same exception class as a duplicate
+  # username, and so does an app's own unique index that merely mentions the
+  # column (`substr(username, 1, 3)`, `(tenant_id, username)`). Redrawing a
+  # generated name over one of those would loop for nothing, and reporting it
+  # as "username has already been taken" would be a lie that hides a real
+  # error — so the race wrapper asks this first, and anything that is not the
+  # username's identity index propagates untouched.
+  #
+  # Each adapter names the culprit differently:
+  #
+  #   PostgreSQL  the constraint (and its table and schema), from the server's error diagnostics
+  #   MySQL       Duplicate entry 'javi' for key 'users.index_users_on_username'
+  #   SQLite      UNIQUE constraint failed: users.username
+  #               UNIQUE constraint failed: index 'index_users_on_lower_username'
+  #
+  # The identity index is the one the gem names itself, the app's configured
+  # `unique_index`, or any index that passes the comparison contract for the
+  # column (Comparison::IndexContract). SQLite's column form names no index,
+  # so there the column must be the only one named, and the table must have
+  # an identity index on exactly it. When the table has more than one unique
+  # index on that column alone (an app's own NOCASE one, say), the message
+  # could be either's: then it is ours only when `conflict` — one query
+  # under the gem's comparison — finds another row with the name.
+  module UniqueViolation
+    POSTGRESQL_CONSTRAINT = /unique constraint "(?<name>[^"]+)"/
+    MYSQL_KEY = /for key '(?:(?<table>[^'.]+)\.)?(?<name>[^']+)'/
+    SQLITE_COLUMNS = /UNIQUE constraint failed: (?<columns>[^:']+?)\s*\z/
+    SQLITE_INDEX = /UNIQUE constraint failed: index '(?<name>[^']+)'/
+
+    # What a violation is matched against: the table as the model names it
+    # (possibly schema-qualified), its bare name, the column, the configured
+    # index, the case mode, the connection to read indexes back with and the
+    # conflict query. :nodoc:
+    Target = ::Data.define(:table, :bare_table, :column, :index, :mode, :connection, :conflict)
+
+    class << self
+      # UniqueViolation.of?(error, table: "users", column: :username, rules: rules)
+      #
+      # `rules` are the column's Usernames::Rules: its case mode, and
+      # config.unique_index (an index the generator did not create).
+      # `connection` is the model's own, which reads its indexes back (an app
+      # may have several databases); without one, Active Record's default
+      # connection is used. `conflict` answers whether another row has the
+      # record's name under the gem's comparison; without one, an ambiguous
+      # SQLite message is not ours.
+      # rubocop:disable-next Metrics/ParameterLists -- each is one fact about the save, all by keyword
+      def of?(error, table:, column:, rules: Usernames.configuration.rules_for, connection: nil, conflict: nil)
+        target = Target.new(table: table.to_s, bare_table: table.to_s.split(".").last, column: column.to_s,
+                            index: rules.unique_index&.to_s, mode: rules.case, connection: connection,
+                            conflict: conflict)
+        name = postgresql_constraint(error)
+        return postgresql_target?(error, target) && identity?(name, target) if name
+
+        named_in_message?(error.message.to_s, target)
+      end
+
+      private
+
+      # SQLite names the columns, or the index of an expression; MySQL the key.
+      def named_in_message?(message, target)
+        if (match = SQLITE_COLUMNS.match(message))
+          match[:columns].split(",").map(&:strip) == ["#{target.bare_table}.#{target.column}"] &&
+            on_the_column_alone?(target)
+        elsif (match = SQLITE_INDEX.match(message) || MYSQL_KEY.match(message))
+          same_table?(match, target) && identity?(match[:name], target)
+        else
+          false
+        end
+      end
+
+      # The constraint name from PostgreSQL's diagnostics (PG_DIAG_CONSTRAINT_NAME),
+      # or from the message when the error carries no result.
+      def postgresql_constraint(error)
+        field = diagnostic(error, :PG_DIAG_CONSTRAINT_NAME)
+        return field if field
+
+        POSTGRESQL_CONSTRAINT.match(error.message.to_s)&.[](:name)
+      end
+
+      # A violation reported on another table (a trigger writing elsewhere),
+      # or on a same-named table in another schema, is not ours, whatever its
+      # index is called.
+      def postgresql_target?(error, target)
+        table = diagnostic(error, :PG_DIAG_TABLE_NAME)
+        schema = diagnostic(error, :PG_DIAG_SCHEMA_NAME)
+        wanted_schema = target.table.split(".")[-2]
+        (table.nil? || table == target.bare_table) && (schema.nil? || wanted_schema.nil? || schema == wanted_schema)
+      end
+
+      def diagnostic(error, field)
+        result = error.cause.try(:result)
+        return unless result && defined?(::PG) && ::PG.const_defined?(field)
+
+        result.error_field(::PG.const_get(field))
+      end
+
+      # A MySQL key names its table only from 8.0.19 on; SQLite's index form never does.
+      def same_table?(match, target)
+        reported = match[:table] if match.names.include?("table")
+        reported.nil? || reported == target.bare_table
+      end
+
+      def identity?(name, target)
+        return true if known_name?(name, target)
+
+        reading(target) do |connection, contract|
+          found = connection.indexes(target.table).find { |index| index.name == name }
+          found ? contract.satisfied_by?(found) : false
+        end
+      end
+
+      # SQLite's "UNIQUE constraint failed: users.username": some unique
+      # index on exactly that column was violated. It is ours when one such
+      # index is the identity index and either it is the only one or another
+      # row really has the name.
+      def on_the_column_alone?(target)
+        reading(target) do |connection, contract|
+          alone = connection.indexes(target.table).select { |index| alone_on_the_column?(index, target) }
+          next false unless alone.any? { |index| known_name?(index.name, target) || contract.satisfied_by?(index) }
+
+          [alone.size, sqlite_unique_indexes_on(connection, contract, target)].max <= 1 || target.conflict&.call == true
+        end
+      end
+
+      def alone_on_the_column?(index, target)
+        index.unique && Array(index.columns) == [target.column]
+      end
+
+      # Every unique index on the column alone, as SQLite itself lists them:
+      # Active Record leaves out those a UNIQUE column constraint creates.
+      def sqlite_unique_indexes_on(connection, contract, target)
+        return 0 unless contract.adapter == :sqlite
+
+        names = connection.select_values("SELECT name FROM pragma_index_list(#{connection.quote(target.bare_table)}) " \
+                                         "WHERE \"unique\" = 1")
+        names.count do |name|
+          connection.select_values("SELECT name FROM pragma_index_info(#{connection.quote(name)})") == [target.column]
+        end
+      end
+
+      def known_name?(name, target)
+        name == target.index || gem_index_names(target).include?(name)
+      end
+
+      def gem_index_names(target)
+        %i[lowercase preserve].map do |mode|
+          Comparison.index_definition(adapter: :sqlite, table: target.table, column: target.column, mode: mode)[:name]
+        end
+      end
+
+      # Reading indexes back can fail (a permissions quirk, a dropped
+      # connection); then only the names above are recognised, and the error
+      # propagates.
+      def reading(target)
+        with_connection(target) do |connection|
+          yield connection, Comparison::IndexContract.new(connection, table: target.table, column: target.column,
+                                                                      mode: target.mode)
+        end
+      rescue StandardError
+        false
+      end
+
+      def with_connection(target, &)
+        return yield(target.connection) if target.connection
+
+        ActiveRecord::Base.with_connection(&)
+      end
+    end
+  end
+end

data/lib/usernames/validator.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require "active_model"
+
+module ActiveModel
+  module Validations
+    # validates :username, username: true
+    # validates :username, username: { length: 2..15, separators: %w[_ .] }
+    # validates :username, username: { message: "isn't available" }
+    #
+    # The rules only — format, reserved, offensive — with no database: you
+    # keep your own uniqueness validation and index (has_username brings both).
+    #
+    # It validates the value AS SUPPLIED. In lowercase mode `Javi`
+    # fails "can only contain lowercase letters…", because `Javi` is not what
+    # would be stored: validate what you store. Pair it with
+    #
+    #   normalizes :username, with: Usernames.normalizer
+    #
+    # and typed `  @Javi ` becomes `javi` before this ever sees it.
+    #
+    # One error at most, for the first rule that fails, so a form never shows
+    # a stack of complaints about one short string. nil is skipped (presence
+    # is a separate question: `validates :username, presence: true`).
+    class UsernameValidator < EachValidator
+      # Options Active Model itself understands; everything else is a rule.
+      VALIDATION_OPTIONS = %i[message strict if unless on allow_nil allow_blank class].freeze
+
+      # Bad rule options fail when the model is defined, not at the first sign-up.
+      def check_validity!
+        rules
+      end
+
+      def validate_each(record, attribute, value)
+        return if value.nil?
+
+        failure = rules.failure_for(value)
+        return unless failure
+
+        # The details first and `message:` last, so a message passed to the
+        # validator replaces every rule's message.
+        record.errors.add(attribute, failure.reason, **failure.details, **options.slice(:message, :strict))
+      end
+
+      private
+
+      # Resolved on every validation (and cached by the configuration), so a
+      # configuration changed after the model was loaded still applies.
+      def rules
+        Usernames.configuration.rules_for(**options.except(*VALIDATION_OPTIONS))
+      end
+    end
+
+    module HelperMethods
+      # validates_username_of :username, length: 2..15
+      def validates_username_of(*attr_names)
+        validates_with UsernameValidator, _merge_attributes(attr_names)
+      end
+    end
+  end
+end

data/lib/usernames/version.rb

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

data/lib/usernames/words.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Usernames
+  # The generator's default vocabulary, from data/words/: short,
+  # everyday, reviewed words that no adjective + animal pair, with any
+  # digits, turns into something the gem itself would refuse — the test
+  # suite checks every pair. `config.generator.adjectives` / `.nouns` start
+  # from these.
+  module Words
+    ADJECTIVES = Data.adjectives
+    ANIMALS = Data.nouns
+  end
+end

data/lib/usernames.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+require "active_support"
+require "active_model"
+require "i18n"
+
+require_relative "usernames/errors"
+require_relative "usernames/version"
+require_relative "usernames/data"
+
+# Every bundled list, read now: a broken install fails here, naming the file.
+Usernames::Data.load!
+
+require_relative "usernames/normalizer"
+require_relative "usernames/phrase"
+require_relative "usernames/result"
+require_relative "usernames/reserved"
+require_relative "usernames/offensive"
+require_relative "usernames/words"
+require_relative "usernames/generator"
+require_relative "usernames/candidates"
+require_relative "usernames/rules"
+require_relative "usernames/configuration"
+require_relative "usernames/validator"
+require_relative "usernames/comparison"
+require_relative "usernames/unique_violation"
+require_relative "usernames/model"
+require_relative "usernames/engine" if defined?(Rails::Engine)
+
+module Usernames
+  # Deliberately permissive: what may ROUTE is not what may be
+  # REGISTERED. A name grandfathered in under older rules still has a page,
+  # the validator decides what can be registered, and the database decides
+  # what exists. No anchors: Rails refuses them in route constraints.
+  ROUTE = /[A-Za-z0-9._-]+/
+
+  LOCALES = File.expand_path("../config/locales/*.yml", __dir__)
+
+  # Under Rails the engine loads config/locales (before the app's, so the
+  # app's keys win). Without Rails nothing would, and every message would
+  # read "Translation missing".
+  I18n.load_path |= Dir[LOCALES] unless defined?(Rails::Engine)
+
+  class << self
+    attr_writer :configuration
+
+    # Lazily initialized, so every function works without an initializer.
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    # Validates at the end of the block, so a bad value fails on the line
+    # that boots the app, naming itself.
+    def configure
+      yield configuration
+      configuration.validate!
+    end
+
+    # Usernames.check("Ad_min")
+    #   # => #<data Usernames::Result ok?=false, reason=:username_reserved, rule=:impersonation, canonical="ad_min", …>
+    #
+    # Normalises, then applies every rule in order; the first failure wins.
+    # Options override the configuration for this call (`length: 2..15`).
+    def check(value, **)
+      rules = configuration.rules_for(**)
+      canonical = rules.normalize(value)
+      Result.for(canonical, rules.failure_for(canonical))
+    end
+
+    # Eligibility only: whether the name may be registered at all. Says
+    # nothing about whether somebody already has it.
+    def allowed?(value, **)
+      check(value, **).ok?
+    end
+
+    # Usernames.normalize(" @Javi_R ") # => "javi_r"
+    def normalize(value, **)
+      configuration.rules_for(**).normalize(value)
+    end
+
+    # What two names are compared by: Usernames.comparison_key("Javi") # => "javi".
+    # Normalises first, which changes nothing in a name that already is
+    # canonical (normalisation is idempotent), so it accepts any input.
+    def comparison_key(value, **)
+      rules = configuration.rules_for(**)
+      rules.comparison_key(rules.normalize(value))
+    end
+
+    # normalizes :username, with: Usernames.normalizer
+    #
+    # A blank result is stored as nil, so "  " never becomes an empty
+    # username that a unique index would let only one person have. The
+    # options are checked now, when the model is defined; the configuration
+    # is read on every call, so it may still change after that.
+    def normalizer(**options)
+      configuration.rules_for(**options)
+
+      lambda do |value|
+        normalized = normalize(value, **options)
+        normalized unless normalized.empty?
+      end
+    end
+
+    # get "@:username", to: "profiles#show", format: false, constraints: { username: Usernames.route }
+    def route
+      ROUTE
+    end
+
+    # [{ rule:, pattern:, message: }] for live hints in a form.
+    def rules_for_browser(**)
+      configuration.rules_for(**).for_browser
+    end
+
+    # Usernames.generate                          # => "quiet_otter_42"
+    # Usernames.generate(from: "José García")     # => "jose_garcia"
+    #
+    # A name the rules allow. Eligibility only, like check: whether
+    # somebody already has it is for the database to say — has_username's
+    # generate_username takes the whole batch there in one query.
+    # Raises NoFreeNameError when the rules leave nothing to draw
+    # (a word list emptied, a minimum length no shape reaches) rather than
+    # returning nil, which a model would store as a missing username.
+    def generate(from: nil, **)
+      name = Generator.candidates(from: from, rules: configuration.rules_for(**)).first
+      return name if name
+
+      raise NoFreeNameError, "no name these rules allow could be generated; check length, separators and the generator's word lists"
+    end
+
+    # Usernames.candidates_for("Javi R", count: 5)  # => ["javi_r", "javir", "javi_r_42", …]
+    #
+    # Up to 3 × count allowed names, ordered, deduplicated. May be
+    # fewer, never raises for running out.
+    def candidates_for(seed, count:, **)
+      Candidates.for(seed, count: count, rules: configuration.rules_for(**))
+    end
+  end
+end