usernames 0.1.3

data/lib/usernames/offensive/lexicon.rb

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+module Usernames
+  module Offensive
+    # One language's bundled data (data/offensive/<locale>.json and its
+    # allowlist), compiled once per process into what rules a and b need.
+    #
+    # Every spelling — terms, variants, exceptions, allowlist entries — is
+    # folded exactly as names are (Offensive.fold), so the data stores
+    # `fuck` once and `fvck`, `phuck` meet it on the name side. Exemptions
+    # are kept both as written and folded: a name's R0 segment `sussex` and
+    # its R1 segment `susseks` are the same word.
+    class Lexicon
+      SEVERE = 4
+
+      # Below this length a severe term must equal a segment: `gc`, `mj`
+      # inside a segment would refuse gcastro and mjordan.
+      SUBSTRING_MINIMUM = 4
+
+      # One spelling of a term, as folded. `whole` means it is matched only
+      # as an entire segment (a short term, or one marked `segment_only`);
+      # `digits`, that it has a digit in it (`2g1c`), so it can only ever sit
+      # inside a part, never inside a segment.
+      Spelling = ::Data.define(:text, :term, :whole, :digits)
+
+      # Spellings by their first SUBSTRING_MINIMUM characters, to find every
+      # one inside a string in a single pass over it. A union Regexp of the
+      # four hundred spellings did the same job twenty times slower.
+      class Index
+        def initialize(spellings)
+          @by_prefix = spellings.group_by { |spelling| spelling.text[0, SUBSTRING_MINIMUM] }.freeze
+        end
+
+        # Whether some spelling occurring in the Whole's text makes the block
+        # answer true; the block gets the spelling and where it starts.
+        def any?(whole)
+          text = whole.text
+          whole.grams.each_with_index.any? do |gram, position|
+            spellings = @by_prefix[gram]
+            spellings&.any? do |spelling|
+              text[position, spelling.text.length] == spelling.text && yield(spelling, position)
+            end
+          end
+        end
+      end
+
+      class << self
+        def for(locale)
+          (@lexicons ||= {})[locale.to_sym] ||= new(locale)
+        end
+      end
+
+      def initialize(locale)
+        @allowlist = both_forms(Data.allowlist(locale))
+        @exceptions = {}
+        @tiers = Hash.new { |tiers, severity| tiers[severity] = {} }
+        @equal = {}
+        severe = []
+        Data.offensive(locale).each { |entry| add(entry, severe) }
+        compile(severe)
+      end
+
+      # Rule a for this language: a whole-segment spelling that IS a unit, or
+      # any severe spelling found in a whole (see #severe_at?).
+      def severe?(name, allowed)
+        name.units.any? { |unit| whole_severe?(unit, allowed) } ||
+          name.wholes.any? do |whole|
+            @index.any?(whole) { |spelling, position| severe_at?(whole, spelling, position, allowed) }
+          end
+      end
+
+      # Rule b: a strong (or, from `minimum` 1, any) spelling that IS one of
+      # the name's segments, or a run of the words its capitals split.
+      def strong?(name, minimum, allowed)
+        table = equal_from(minimum)
+        (name.units + name.joins).any? do |unit|
+          term = table[unit]
+          term && !exempt?(unit, term, allowed)
+        end
+      end
+
+      private
+
+      def add(entry, severe)
+        term = entry.fetch("term")
+        severity = entry.fetch("severity")
+        @exceptions[term] = both_forms(entry.fetch("exceptions", []))
+        [term, *entry.fetch("variants", [])].map { |spelling| Offensive.fold(spelling) }.uniq.each do |text|
+          @tiers[severity][text] ||= term
+          severe << spelling(text, term, entry) if severity >= SEVERE
+        end
+      end
+
+      def spelling(text, term, entry)
+        whole = text.length < SUBSTRING_MINIMUM || entry["segment_only"] == true
+        Spelling.new(text: text, term: term, whole: whole, digits: text.match?(/\d/))
+      end
+
+      # Whole-segment spellings are a table looked up by unit; every severe
+      # spelling of four letters or more goes in the index a whole is scanned with.
+      def compile(severe)
+        @whole_severe = severe.select(&:whole).group_by(&:text).freeze
+        @index = Index.new(severe.select { |spelling| spelling.text.length >= SUBSTRING_MINIMUM })
+        @tiers.default_proc = nil
+        @tiers.each_value(&:freeze)
+        [@tiers, @exceptions].each(&:freeze)
+      end
+
+      # a-1 for the whole-segment spellings: the unit must be the spelling.
+      def whole_severe?(unit, allowed)
+        @whole_severe[unit]&.any? { |spelling| !exempt?(unit, spelling.term, allowed) }
+      end
+
+      # One occurrence of a severe spelling in a whole.
+      #
+      # a-2 when it straddles a separator (`fu_ck`): refused, with no
+      # exemption — such an occurrence lies inside no exempt unit — and
+      # without a-1's whole-segment special cases: a separator in the middle
+      # of `rape` reads as evasion, so `gr_ape` is refused — a documented
+      # trade-off: a real name split exactly there is rarer than the evasion.
+      #
+      # a-1 otherwise: refused unless the unit it sits in — its segment (or
+      # the word of it, between case boundaries), or for a spelling with a
+      # digit its part — is exempt. Whole-segment
+      # spellings are #whole_severe?'s, not matched as substrings.
+      # Spellings under four letters are left out of a-2 as of
+      # a-1 (none ships today); across separators they would refuse innocent
+      # joins of short segments.
+      def severe_at?(whole, spelling, position, allowed)
+        return true if whole.straddles?(spelling.text, position)
+        return false if spelling.whole
+
+        unit = spelling.digits ? whole.part_at(position) : whole.segment_at(position, spelling.text.length)
+        !exempt?(unit, spelling.term, allowed)
+      end
+
+      def exempt?(unit, term, allowed)
+        @allowlist.include?(unit) || allowed.include?(unit) || @exceptions.fetch(term).include?(unit)
+      end
+
+      # { folded spelling => term } over every tier from `minimum` up to
+      # strong. Severe spellings are rule a's, which already caught them.
+      def equal_from(minimum)
+        @equal[minimum] ||= (minimum...SEVERE).each_with_object({}) do |severity, table|
+          @tiers.fetch(severity, {}).each { |text, term| table[text] ||= term }
+        end.freeze
+      end
+
+      def both_forms(words)
+        words.each_with_object(Set.new) do |word, set|
+          set << word << Offensive.fold(word)
+        end.freeze
+      end
+    end
+  end
+end

data/lib/usernames/offensive/name.rb

@@ -0,0 +1,254 @@
+# frozen_string_literal: true
+
+module Usernames
+  module Offensive
+    # One name, read every way the offensive matcher reads it. Built once per check.
+    #
+    #   forms        R0 (the key) and R1 (the key folded)
+    #   segments     what sits between separators and digit runs, in either form
+    #   digit_parts  what sits between separators only, where a digit keeps it
+    #                from being a segment — the unit a spelling that itself has a
+    #                digit in it (`2g1c`) is read against; segments never hold a
+    #                digit, so without these such a spelling could never match
+    #   wholes       each form with its separators removed (see Whole)
+    #   joins        runs of adjacent words a case boundary split (see below)
+    #
+    # A name stored with its typed case (`case: :preserve`) also splits where
+    # a lowercase letter meets a capital, and before the last capital of a
+    # run that a lowercase letter follows: `ShitheadBob` is the segments
+    # shitheadbob, shithead and bob, `SHITHEADBob` the same, and
+    # `ScunthorpeUnited` is scunthorpeunited, scunthorpe and united. The
+    # capital is the only word boundary such a name has, and the person
+    # typed it. The glued segment stays a segment, and the whole is
+    # unchanged.
+    #
+    # Capitals also cut inside a word as often as between words
+    # (`ShitHeadBob`), so the strong terms, matched by equality, are also
+    # compared with every run of adjacent words of one segment: shithead,
+    # headbob. A run spans at most JOIN_WORDS words. A word a capital does
+    # not end (`XxShitHeadxX` reads Xx, Shit, Headx, X) makes no join that
+    # is a word: a known limit.
+    #
+    # Segments come from BOTH forms: `adm1n` is the segments adm, n as typed
+    # and admin folded, and `shithead1` keeps shithead as typed where folded it
+    # reads shitheadi.
+    class Name
+      attr_reader :key, :forms, :wholes, :segments, :digit_parts, :joins
+
+      # Where a lowercase letter meets a capital (`tB`), and where a run of
+      # capitals gives its last one to the word it starts (`DBo`).
+      CASE_BOUNDARY = /(?<=[a-z])(?=[A-Z])|(?<=[A-Z])(?=[A-Z][a-z])/
+
+      # The most words one join of case-split words spans.
+      JOIN_WORDS = 8
+
+      # `key` is the comparison key; `canonical`, the name as stored, which
+      # differs from it only in case.
+      def initialize(key, canonical = key)
+        @key = key
+        @forms = [key, Offensive.fold(key)].uniq
+        boundaries = case_boundaries(canonical)
+        @wholes = [
+          Whole.new(key, boundaries: boundaries),
+          Whole.new(Reserved.leet(key), folded: true, boundaries: boundaries)
+        ].uniq do |whole|
+          [whole.text, whole.segments]
+        end
+        @segments = @wholes.flat_map(&:segments).uniq
+        @digit_parts = @wholes.flat_map(&:parts).grep(/\d/).uniq
+        @joins = (@wholes.flat_map(&:joins) - @segments).uniq
+      end
+
+      # What a whole-segment rule compares against: every segment, and every
+      # part a digit keeps from being one.
+      def units
+        segments + digit_parts
+      end
+
+      private
+
+      # The positions of the key where `canonical` changes from a lowercase
+      # letter to a capital. Positions carry over: the key is `canonical`
+      # with its ASCII letters lowercased, and the digit fold maps one
+      # character to one.
+      def case_boundaries(canonical)
+        return [].freeze if canonical == key
+
+        positions = []
+        canonical.scan(CASE_BOUNDARY) { positions << Regexp.last_match.begin(0) }
+        positions.freeze
+      end
+    end
+
+    # A form with its separators removed (`f.u.c.k` → `fuck`), remembering
+    # for every character which parts (between separators) and which segment
+    # (between separators and digit runs) it came from. One pass over this
+    # text finds every severe spelling for rules a-1 and a-2 at once: an
+    # occurrence that straddles two parts is a-2's evasion, and one inside a
+    # part lies inside exactly one segment (a spelling without digits cannot
+    # cover a digit), which is a-1's unit.
+    #
+    # The folded whole (`folded: true`, built from the digit-folded key) is
+    # rewritten twice: each part and segment on its own, and the joined text
+    # again once the separators are gone — so a rewrite split by a separator
+    # (`p_huck`, `f_vck`, `fuuu_uuck`) still folds. A character a rewrite
+    # makes from two parts (the `f` of `p_huck`) remembers both, so whatever
+    # covers it straddles them, and an exemption never applies there.
+    #
+    # Case boundaries (see Name) cut a segment into words without making
+    # them parts: an occurrence across one (`ScunThorpe`) is still inside
+    # one segment, the glued one, and is judged by it. One that lies inside
+    # a single word is judged by that word, so `ScunthorpeUnited` is exempt
+    # where `scunthorpeunited` is not.
+    class Whole
+      # What sits between separators.
+      PART = /[^_.-]+/
+
+      attr_reader :text, :parts, :segments, :joins
+
+      def initialize(form, folded: false, boundaries: [])
+        @folded = folded
+        @boundaries = boundaries
+        @text = +""
+        @parts = []
+        @segments = []
+        @joins = []
+        @origins = [] # [first part, last part, segment, word] per character of @text
+        form.scan(PART) { add(Regexp.last_match[0], Regexp.last_match.begin(0)) }
+        rewrite_text if folded
+        @text.freeze
+      end
+
+      # Every substring of Lexicon::SUBSTRING_MINIMUM characters, in order:
+      # what each language's Lexicon::Index looks up, cut once per name.
+      def grams
+        size = Lexicon::SUBSTRING_MINIMUM
+        @grams ||= (0..(text.length - size)).map { |position| text[position, size] }.freeze
+      end
+
+      # Whether `spelling`, found at `position` of the text, straddles a separator.
+      def straddles?(spelling, position)
+        @origins[position][0] != @origins[position + spelling.length - 1][1]
+      end
+
+      def part_at(position)
+        @parts[@origins[position][0]]
+      end
+
+      # The segment that `length` characters from `position` lie in: the word
+      # between case boundaries when they fit in one, the segment otherwise,
+      # or nil on a digit.
+      def segment_at(position, length = 1)
+        _first, _last, segment, word = @origins[position]
+        return @segments[word] if word && word == @origins[position + length - 1][3]
+
+        @segments[segment] if segment
+      end
+
+      private
+
+      # `offset`: where the part starts in the form, to place case boundaries.
+      def add(part, offset)
+        part_index = @parts.size
+        @parts << folded(part)
+        part.scan(/\d+|\D+/) do |run|
+          start = offset + Regexp.last_match.begin(0)
+          if run.getbyte(0).between?(48, 57)
+            run.length.times { @origins << [part_index, part_index, nil, nil] }
+          else
+            add_segment(run, start, part_index)
+          end
+          @text << run
+        end
+      end
+
+      # A run of letters: one segment, and one more for each word in it when
+      # case boundaries cut it.
+      def add_segment(run, start, part_index)
+        segment = @segments.size
+        @segments << folded(run)
+        words = words_in(run, start)
+        if words.one?
+          run.length.times { @origins << [part_index, part_index, segment, nil] }
+        else
+          words.each do |word|
+            @segments << folded(word)
+            index = @segments.size - 1
+            word.length.times { @origins << [part_index, part_index, segment, index] }
+          end
+          add_joins(words)
+        end
+      end
+
+      # Every run of two or more adjacent words short of the whole segment,
+      # each folded as one text: a rewrite can span the boundary (`PHuck`).
+      def add_joins(words)
+        (0...words.size).each do |from|
+          ((from + 2)..[words.size, from + Name::JOIN_WORDS].min).each do |to|
+            @joins << folded(words[from...to].join) unless from.zero? && to == words.size
+          end
+        end
+      end
+
+      # `run` (which starts at `start` in the form) cut at the case boundaries inside it.
+      def words_in(run, start)
+        return [run] if @boundaries.empty?
+
+        cuts = @boundaries.filter_map { |at| at - start if at > start && at < start + run.length }
+        [0, *cuts].zip([*cuts, run.length]).map { |from, to| run[from...to] }
+      end
+
+      def folded(text)
+        @folded ? Offensive.rewrite(text) : text
+      end
+
+      # Offensive.rewrite over the joined text, carrying every character's origins along.
+      def rewrite_text
+        return if Offensive.rewrite(@text) == @text # most names: nothing to rewrite
+
+        characters = @text.chars.zip(@origins)
+        Offensive.rewrites.each { |from, to| characters = replace(characters, from, to) }
+        characters = cut_stretches(characters)
+        @text = characters.map(&:first).join
+        @origins = characters.map(&:last)
+      end
+
+      # `from` → `to` left to right, as String#gsub does; each new character
+      # comes from every part the replaced ones came from.
+      def replace(characters, from, to)
+        result = []
+        index = 0
+        while index < characters.size
+          window = characters[index, from.length]
+          if window.map(&:first).join == from
+            origin = merged(window.map(&:last))
+            to.each_char { |character| result << [character, origin] }
+            index += from.length
+          else
+            result << characters[index]
+            index += 1
+          end
+        end
+        result
+      end
+
+      # A run of three or more of one letter becomes two; the second stands
+      # for the rest of the run, wherever it came from.
+      def cut_stretches(characters)
+        characters.chunk_while { |a, b| a.first == b.first }.flat_map do |run|
+          next run if run.size < 3 || !run.first.first.match?(/[a-z]/)
+
+          [run.first, [run[1].first, merged(run[1..].map(&:last))]]
+        end
+      end
+
+      # A character made from several keeps the first one's segment, and a
+      # word only when they all came from the same one.
+      def merged(origins)
+        words = origins.map(&:last).uniq
+        [origins.map(&:first).min, origins.map { |origin| origin[1] }.max, origins.first[2],
+         words.size == 1 ? words.first : nil]
+      end
+    end
+  end
+end

data/lib/usernames/offensive.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+require_relative "offensive/name"
+require_relative "offensive/lexicon"
+require_relative "offensive/hate"
+require_relative "adapters/moderate"
+
+module Usernames
+  # Offensive words: bundled terms in severity tiers per language,
+  # hate-number rules and optional adapters (`moderate`, any callable).
+  #
+  # The whole design is a fight between two failure modes. Match too
+  # little and `f.u.c.k` or `sh1thead_bob` gets through; match substrings
+  # naively and Scunthorpe, Penistone, `grape` and `therapist` cannot sign
+  # up. So each tier is matched as narrowly as its words allow:
+  #
+  #   a-1  severe (tier 4): inside any segment that is not exempt; short
+  #        terms and `segment_only` ones must BE the segment (grape, Shōta)
+  #   a-2  severe, across separators: in the name with separators removed,
+  #        but only where the word straddles them (`fu_ck`, `gr_ape`)
+  #   b    strong (tier 3; tiers 1–2 too under :mild): a whole segment
+  #   c    hate numbers and tokens (Offensive::Hate)
+  #   d    adapters
+  #
+  # Exemptions (the bundled allowlist, config.offensive.allowed, a term's own
+  # exceptions) are whole SEGMENTS, never the joined name: otherwise
+  # `scunt_horpe` would join into the exempt `scunthorpe`. They lift a–b
+  # only; hate rules and adapters are authoritative.
+  module Offensive
+    # Which tiers rule b looks at, per severity mode (nil: rule b is off).
+    EQUAL_FROM = { severe: nil, strong: 3, mild: 1 }.freeze
+
+    # A letter repeated three times or more: a stretched spelling (`fuuuuuck`).
+    STRETCH = /([a-z])\1{2,}/
+
+    class << self
+      # The kind of match — :severe, :strong, :hate_number or :adapter — or nil
+      # when the name is fine. `canonical` is a name as stored that passed
+      # every format rule and is not reserved: the words are matched on its
+      # comparison key, split also where its case changes (see Name), and
+      # adapters get it as it is; `rules` is the
+      # Usernames::Rules in force (rules.offensive carries severity, languages,
+      # allowed and adapters; rules.on_adapter_failure what a raising adapter means).
+      #
+      # `:off` turns off everything the gem bundles, hate rules included;
+      # adapters run in every mode, because an app that configured one asked
+      # for it explicitly.
+      def verdict(canonical, rules)
+        severity = rules.offensive.severity
+        unless severity == :off
+          name = Name.new(rules.comparison_key(canonical), canonical)
+          rule = lexical(name, rules, severity) || Hate.verdict(name, rules)
+          return rule if rule
+        end
+
+        adapter_verdict(canonical, rules)
+      end
+
+      # A name's folded form (R1): the digit folds (`sh1t` → `shit`), then
+      # #rewrite. Terms are folded the same way when they are loaded, so
+      # `phuck` in the data and `fuck` typed meet.
+      def fold(string)
+        rewrite(Reserved.leet(string))
+      end
+
+      # The rewrites of data/offensive/leet.yml in order — `vv`→`w`, `v`→`u`,
+      # `ph`→`f`, `x`→`ks` — then every run of three or more of one letter cut
+      # to two (`fuuuuuck` → `fuuck`). Not doubles: `ass` and `book` stay.
+      def rewrite(string)
+        rewritten = rewrites.reduce(string) do |text, (from, to)|
+          text.include?(from) ? text.gsub(from, to) : text
+        end
+        rewritten.gsub(STRETCH, '\1\1')
+      end
+
+      # [[from, to], …]: the offensive-only rewrites of data/offensive/leet.yml, in order.
+      def rewrites
+        @rewrites ||= Data.leet.fetch("offensive_only").to_a.freeze
+      end
+
+      private
+
+      # Rules a and b over every enabled language: any language's rejection
+      # rejects, and a severe verdict outranks a strong one.
+      def lexical(name, rules, severity)
+        allowed = allowed_for(rules)
+        # A name the app allowed in so many words is exempt as a whole. The
+        # whole name is matched exactly, so joining segments still cannot
+        # manufacture an exemption.
+        return if allowed.include?(name.key)
+
+        lexicons = rules.offensive.languages.map { |locale| Lexicon.for(locale) }
+        return :severe if lexicons.any? { |lexicon| lexicon.severe?(name, allowed) }
+
+        minimum = EQUAL_FROM.fetch(severity)
+        :strong if minimum && lexicons.any? { |lexicon| lexicon.strong?(name, minimum, allowed) }
+      end
+
+      # config.offensive.allowed, as typed and folded (an entry `sussex` must
+      # exempt the folded segment `susseks` too).
+      def allowed_for(rules)
+        rules.compiled(:offensive_allowed) do
+          rules.offensive.allowed.each_with_object(Set.new) do |word, set|
+            key = word.strip.downcase(:ascii)
+            set << key << fold(key)
+          end.freeze
+        end
+      end
+
+      def adapter_verdict(canonical, rules)
+        :adapter if rules.offensive.adapters.any? { |adapter| flagged?(adapter, canonical, rules) }
+      end
+
+      # A raising adapter (a network blip, a bug) follows on_adapter_failure:
+      # :allow (the default: an optional adapter fails open) skips
+      # it, :reject refuses the name. Either way it is logged, so a broken
+      # adapter is not silently a no-op forever.
+      # Adapters receive the name as stored, typed case and all: a capital is
+      # a word boundary a text classifier can use (see Adapters::Moderate).
+      def flagged?(adapter, canonical, rules)
+        callable = adapter == :moderate ? Adapters::Moderate : adapter
+        callable.call(canonical) ? true : false
+      rescue StandardError => e
+        reject = rules.on_adapter_failure == :reject
+        log("[usernames] offensive adapter #{adapter.inspect} raised #{e.class}: #{e.message} " \
+            "(#{reject ? 'name rejected' : 'skipped'}, on_adapter_failure: #{rules.on_adapter_failure.inspect})")
+        reject
+      end
+
+      def log(message)
+        logger = ::Rails.logger if defined?(::Rails) && ::Rails.respond_to?(:logger)
+        logger ? logger.warn(message) : warn(message)
+      end
+    end
+  end
+end

data/lib/usernames/phrase.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Usernames
+  # A piece of an error message that depends on the rules in force and on the
+  # locale: "underscores, periods and dashes", "an underscore or a period",
+  # "lowercase letters".
+  #
+  # Translated when the message is READ, not when the error is added. Active
+  # Model keeps an error's options and builds its message on every read, so a
+  # record validated in English and rendered inside `I18n.with_locale(:es)`
+  # (a mailer, a background job) must not carry an English fragment into a
+  # Spanish sentence. I18n calls any interpolation value that responds to
+  # #call; everything else (errors.details, JSON, inspect) sees the text.
+  class Phrase
+    SEPARATOR_NAMES = { "_" => :underscore, "." => :period, "-" => :dash }.freeze
+    SCOPE = %i[usernames separators].freeze
+
+    class << self
+      # "underscores", "underscores and periods", "underscores, periods and
+      # dashes" — every separator allowed, in the order they were configured.
+      def separators(separators)
+        new { join(separators, form: :plural, connector: :and) }
+      end
+
+      # "an underscore", "an underscore or a period" — any one of them.
+      def any_separator(separators)
+        new { join(separators, form: :singular, connector: :or) }
+      end
+
+      # "lowercase letters" or, when the typed case is kept, "letters".
+      def letters(case_mode)
+        new { I18n.t(case_mode == :lowercase ? :lowercase : :any_case, scope: %i[usernames letters]) }
+      end
+
+      # The list sentence itself, in the current locale. Not to_sentence:
+      # Rails' English connectors carry an Oxford comma, and these sentences
+      # are written without one in all three shipped languages.
+      def join(separators, form:, connector:)
+        words = separators.map { |separator| I18n.t(form, scope: [*SCOPE, SEPARATOR_NAMES.fetch(separator)]) }
+        return words.join if words.size < 2
+
+        connectors = [*SCOPE, :connectors]
+        [words[0..-2].join(I18n.t(:words, scope: connectors)), words.last].join(I18n.t(connector, scope: connectors))
+      end
+    end
+
+    def initialize(&translate)
+      @translate = translate
+    end
+
+    def to_s
+      @translate.call.to_s
+    end
+
+    # What I18n calls while interpolating.
+    def call(*)
+      to_s
+    end
+
+    def as_json(*)
+      to_s
+    end
+
+    def inspect
+      to_s.inspect
+    end
+  end
+end

data/lib/usernames/reserved/listing.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module Usernames
+  module Reserved
+    # `rails usernames:reserved`: every reserved word in force and where it
+    # comes from, for the day somebody asks why `x` is taken by nobody.
+    #
+    #   admin        impersonation · big-username-blocklist (MIT) — …
+    #   recipe       config.reserved
+    #   pricing      route /pricing
+    #
+    # A word on several lists is shown with the one that decides how it is
+    # matched: impersonation first (it is matched in every spelling), then
+    # your own lists, the bundled exact words and your routes.
+    module Listing
+      class << self
+        # [[word, source], …], sorted by word, without the words
+        # config.allowed lifts (see .allowed).
+        def entries(rules = Usernames.configuration.rules_for)
+          sources = {}
+          impersonation(rules).each { |word, source| sources[word] ||= source }
+          exact(rules).each { |word, source| sources[word] ||= source }
+          routes(rules).each { |word| sources[word] ||= "route /#{word}" }
+          lifted = allowed(rules)
+          sources.except(*lifted).sort
+        end
+
+        # The words config.allowed lifts, sorted.
+        def allowed(rules = Usernames.configuration.rules_for)
+          keys(rules.allowed).sort
+        end
+
+        def report(io = $stdout, rules = Usernames.configuration.rules_for)
+          words = entries(rules)
+          width = words.map { |word, _source| word.length }.max.to_i
+          io.puts "#{words.size} reserved names (impersonation words also refuse their spellings: adm1n, ad.min, admins)"
+          words.each { |word, source| io.puts "  #{word.ljust(width)}  #{source}" }
+          lifted = allowed(rules)
+          io.puts "Lifted by config.allowed: #{lifted.join(' ')}" if lifted.any?
+          words.size
+        end
+
+        private
+
+        def impersonation(rules)
+          bundled = Data.impersonation.to_set
+          keys(rules.forbidden).map do |word|
+            [word, bundled.include?(word) ? bundled_source(word) : "config.forbidden"]
+          end +
+            Reserved.app_names(rules).map { |word| [word, "impersonation · your app's name"] }
+        end
+
+        def exact(rules)
+          bundled = Data.reserved.to_set
+          custom, shipped = keys(rules.reserved).partition { |word| !bundled.include?(word) }
+          custom.map { |word| [word, "config.reserved"] } + shipped.map { |word| [word, bundled_source(word)] }
+        end
+
+        def routes(rules)
+          rules.reserve_routes ? Reserved.routes.to_a : []
+        end
+
+        # "web · gitlab (MIT) — GitLab top-level and project wildcard routes"
+        def bundled_source(word)
+          provenance = Reserved.source_of(word)
+          return "bundled" unless provenance
+
+          origin = [provenance.source, ("(#{provenance.licence})" if provenance.licence)].compact.join(" ")
+          text = [provenance.category, (origin unless origin.empty?)].compact.join(" · ")
+          provenance.reason ? "#{text} — #{provenance.reason}" : text
+        end
+
+        def keys(words)
+          words.map { |word| word.strip.downcase(:ascii) }.uniq
+        end
+      end
+    end
+  end
+end