usernames 0.1.3

data/lib/generators/usernames/templates/availability/username_check_controller.js.tt

@@ -0,0 +1,115 @@
+import { Controller } from "@hotwired/stimulus"
+
+// Live hints and a "is this name free?" check for <%= model_name %>#<%= column %>.
+// Generated by `rails generate usernames:availability`. It's yours: edit it.
+// app/views/usernames/_field.html.erb wires it up:
+//
+//   <div data-controller="username-check"
+//        data-username-check-url-value="/usernames/availability"
+//        data-username-check-param-value="<%= column %>"
+//        data-username-check-rules-value="[…<%= model_name %>.<%= column %>_rules_for_browser…]">
+//     <input data-username-check-target="input" data-action="input->username-check#check">
+//     <p data-username-check-target="hint"></p>
+//     <p data-username-check-target="status"></p>
+//   </div>
+//
+// Everything here is a HINT. The browser only approximates the server's
+// normalisation (Ruby's strip and JavaScript's trim() disagree on NUL, U+FEFF
+// and U+1680), so nothing here blocks submission: no setCustomValidity, no
+// pattern attribute. The model's validations and the unique index decide.
+export default class extends Controller {
+  static targets = ["input", "hint", "status"]
+  static values = {
+    url: String,
+    // The query parameter the endpoint reads: GET /usernames/availability?<%= column %>=…
+    param: { type: String, default: "<%= column %>" },
+    rules: Array,
+    lowercase: { type: Boolean, default: true },
+    delay: { type: Number, default: 300 }
+  }
+
+  connect() {
+    this.patterns = this.rulesValue.map((rule) => ({ ...rule, regexp: this.compile(rule.pattern) }))
+  }
+
+  disconnect() {
+    this.cancel()
+  }
+
+  // On every keystroke: the first rule the name breaks, at once; whether it
+  // is free, once typing pauses.
+  check() {
+    const name = this.normalize(this.inputTarget.value)
+    this.current = name
+    this.cancel()
+
+    const broken = this.firstBrokenRule(name)
+    this.write(this.hasHintTarget && this.hintTarget, broken ? broken.message : "")
+    this.render(null)
+    // Only names that could be registered are worth a request.
+    if (name === "" || broken) return
+
+    this.timer = setTimeout(() => this.ask(name), this.delayValue)
+  }
+
+  async ask(name) {
+    this.request = new AbortController()
+    const url = new URL(this.urlValue, window.location.href)
+    url.searchParams.set(this.paramValue, name)
+
+    try {
+      const response = await fetch(url, {
+        headers: { Accept: "application/json" },
+        signal: this.request.signal,
+        credentials: "same-origin"
+      })
+      if (!response.ok) return // rate-limited or switched off: say nothing rather than guess
+
+      const answer = await response.json()
+      // A slow answer for something typed earlier is not an answer for this.
+      if (name === this.current) this.render(answer)
+    } catch (error) {
+      if (error.name !== "AbortError") throw error
+    }
+  }
+
+  // The server's normalisation, approximately: NFKC, trim,
+  // lowercase (unless case is kept), one leading @ before a letter or digit.
+  normalize(value) {
+    let name = value.normalize("NFKC").trim()
+    if (this.lowercaseValue) name = name.toLowerCase().normalize("NFKC")
+    return name.replace(this.lowercaseValue ? /^@(?=[a-z0-9])/ : /^@(?=[A-Za-z0-9])/, "")
+  }
+
+  // Each pattern matches a name that BREAKS its rule; the first one wins.
+  firstBrokenRule(name) {
+    if (name === "") return null
+    return this.patterns.find(({ regexp }) => regexp && regexp.test(name)) || null
+  }
+
+  // With the u flag a length counts code points, as Ruby does.
+  compile(pattern) {
+    try {
+      return new RegExp(pattern, "u")
+    } catch {
+      try { return new RegExp(pattern) } catch { return null }
+    }
+  }
+
+  render(answer) {
+    if (!this.hasStatusTarget) return
+
+    this.statusTarget.dataset.state = answer ? answer.state : ""
+    this.write(this.statusTarget, answer && answer.message ? answer.message : "")
+  }
+
+  write(element, text) {
+    if (element) element.textContent = text
+  }
+
+  cancel() {
+    clearTimeout(this.timer)
+    if (this.request) this.request.abort()
+    this.request = null
+  }
+}

data/lib/generators/usernames/templates/usernames.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+# Every line below shows the default: uncomment one to change it.
+# The README documents the less common options (first_character,
+# reserve_routes, app_name, offensive.adapters, on_adapter_failure, generator,
+# unique_index). Every option is also accepted per model:
+#   has_username :handle, length: 2..24, case: :preserve
+Usernames.configure do |config|
+  # How long a username may be, in characters.
+  # config.length          = 3..30
+
+  # Which separators a name may contain.
+  # %w[_ .] is Instagram-style (and adds the rule that a name can't end like a
+  # file: .json, .png…) · %w[-] is GitHub- and subdomain-style.
+  # config.separators      = %w[_]
+
+  # true allows _javi_ (a dot is never allowed at an edge).
+  # config.edge_separators = false
+
+  # :preserve keeps the case people type (CoolCat) and still compares without
+  # it (nobody else can be coolcat). Decide before you migrate: the unique
+  # index is built for one mode.
+  # config.case            = :lowercase
+
+  # Reserved names. `+=` adds to the bundled lists; `=` replaces them.
+  # config.reserved  += %w[]               # exact: nobody can be exactly this
+  # config.forbidden += %w[]               # impersonation matching, like admin (ad.min, adm1n, admins)
+  # config.allowed   += %w[]               # exceptions to the reserved checks
+
+  # Offensive words, in severity tiers per language.
+  # config.offensive.severity  = :strong   # :severe · :strong · :mild · :off
+  # config.offensive.languages = %i[en es]
+  # config.offensive.allowed  += %w[]      # exceptions to the offensive-word checks (a whole name or segment)
+end

data/lib/tasks/usernames.rake

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+namespace :usernames do
+  desc "Read-only report on an existing username column: values to normalise, collisions, index and " \
+       "collation (rails usernames:audit, usernames:audit[Member,handle] or usernames:audit[Member,handle,preserve])"
+  task :audit, %i[model column case] => :environment do |_task, args|
+    require "usernames/audit"
+
+    args.with_defaults(model: "User", column: "username")
+    model = args[:model].safe_constantize
+    abort "[usernames] No model named #{args[:model]}. Usage: rails usernames:audit[User,username]" unless model
+    if args[:case] && !%w[lowercase preserve].include?(args[:case])
+      abort "[usernames] The case mode is lowercase or preserve (got #{args[:case]})."
+    end
+
+    # Always exits 0: this is a report, not a gate. Read it, then fix what
+    # it lists in a migration you own. The case mode matters before
+    # has_username is declared (the README runs the audit first): without
+    # it, the configured mode is assumed.
+    Usernames::Audit.new(model, args[:column], mode: args[:case]).report($stdout)
+  end
+
+  desc "Every reserved name in force and where it comes from (or usernames:reserved[Player,handle] " \
+       "for one model's rules)"
+  task :reserved, %i[model column] => :environment do |_task, args|
+    require "usernames/reserved/listing"
+
+    rules = Usernames.configuration.rules_for
+    if args[:model]
+      model = args[:model].safe_constantize
+      abort "[usernames] No model named #{args[:model]}." unless model
+
+      column = model.try(:_usernames)&.[]((args[:column] || "username").to_sym)
+      rules = column.rules if column
+    end
+    Usernames::Reserved::Listing.report($stdout, rules)
+  end
+end

data/lib/usernames/adapters/moderate.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Usernames
+  module Adapters
+    # `config.offensive.adapters = [:moderate]` (the default): ask the
+    # moderate gem's offline wordlist too, when the app has that gem. Without
+    # it this is a no-op, not an error — the default must never make an
+    # app add a dependency.
+    #
+    # Moderate reads text, not handles, so the name is handed over the way a
+    # person would read it: camelCase split and separators as spaces
+    # (`BigBadWolf_x` → "Big Bad Wolf x"), which lets its word-boundary
+    # patterns see words.
+    module Moderate
+      class << self
+        def call(name)
+          return false unless available?
+
+          ::Moderate::Filters::Wordlist.classify(text_for(name)).flagged?
+        end
+
+        def available?
+          defined?(::Moderate::Filters::Wordlist) ? true : false
+        end
+
+        def text_for(name)
+          name.to_s
+            .gsub(/([a-z\d])([A-Z])/, '\1 \2')
+            .gsub(/([A-Z]+)([A-Z][a-z])/, '\1 \2')
+            .tr("_.-", "   ")
+            .squeeze(" ")
+            .strip
+        end
+      end
+    end
+  end
+end

data/lib/usernames/audit/output.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Usernames
+  class Audit
+    # How the audit writes: a section per subject, ✓ for what is fine, ✗ for
+    # a problem (counted), · for a note, and at most EXAMPLES rows per finding.
+    module Output
+      private
+
+      def list(rows, clean, found, &)
+        return ok(clean) if rows.empty?
+
+        problem("#{format(found, rows.size)}:")
+        rows.first(EXAMPLES).each { |row| line "      #{yield(*row)}" }
+        more(rows)
+      end
+
+      def more(rows)
+        line "      … and #{rows.size - EXAMPLES} more" if rows.size > EXAMPLES
+      end
+
+      def finish
+        line ""
+        if @problems.zero?
+          line "Nothing to fix: the database enforces the same uniqueness the gem checks."
+        else
+          line "#{@problems} #{@problems == 1 ? 'thing' : 'things'} to fix. See the README, \"Adopting an existing column\"."
+        end
+        @problems
+      end
+
+      def section(title)
+        line ""
+        line title
+      end
+
+      def ok(message)
+        line "  ✓ #{message}"
+      end
+
+      def problem(message)
+        @problems += 1
+        line "  ✗ #{message}"
+      end
+
+      def line(text)
+        @io.puts(text)
+      end
+    end
+  end
+end

data/lib/usernames/audit/values.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Usernames
+  class Audit
+    # What one pass over the stored values finds. Collision groups are keyed
+    # by comparison_key(normalize(stored)), over non-nil values only: an
+    # absent username is not an identity, and never collides.
+    class Values
+      attr_reader :noncanonical, :failing, :total
+
+      def initialize(rules)
+        @rules = rules
+        @noncanonical = []
+        @groups = Hash.new { |hash, key| hash[key] = [] }
+        @failing = []
+        @total = 0
+      end
+
+      def <<((id, value))
+        @total += 1
+        canonical = @rules.normalize(value)
+        @noncanonical << [id, value, canonical] unless canonical == value
+        @groups[@rules.comparison_key(canonical)] << [id, value]
+        failure = canonical.empty? ? :blank : @rules.failure_for(canonical)&.reason
+        @failing << [id, value, failure] if failure
+        self
+      end
+
+      def collisions
+        @groups.select { |_key, rows| rows.size > 1 }.to_a
+      end
+    end
+  end
+end

data/lib/usernames/audit.rb

@@ -0,0 +1,230 @@
+# frozen_string_literal: true
+
+require_relative "audit/values"
+require_relative "audit/output"
+
+module Usernames
+  # `rails usernames:audit[User,username]`: what stands between an
+  # existing column and the gem's guarantees. Read-only — it never writes a
+  # row, an index or a setting.
+  #
+  # Rails' `normalizes` does not touch rows already in the database, so a
+  # stored `JAVI` next to a new `javi` would be two identities, and a unique
+  # index cannot be added over values that collide once normalised. The
+  # audit lists exactly that, plus whether the column's type, collation and
+  # indexes give the comparison contract (Usernames::Comparison), and which
+  # stored names today's rules would refuse — those keep working (only a
+  # change is validated); they are listed so nobody is surprised.
+  #
+  # Fixing what it finds is the app's own migration, under a username-write
+  # freeze (README, "Adopting an existing column"): the gem deliberately
+  # renames nobody.
+  class Audit
+    include Output
+
+    # Rows shown per finding; the counts are always complete.
+    EXAMPLES = 20
+    BATCH = 10_000
+
+    # The types the comparison contract covers; citext is excluded.
+    POSTGRESQL_TYPES = /\A(text|character varying(\(\d+\))?)\z/
+    MODES = %i[lowercase preserve].freeze
+
+    attr_reader :model, :column, :rules, :mode
+
+    # `mode` audits as that case mode: the README's adoption workflow runs the
+    # audit BEFORE has_username is declared, when the model cannot say which
+    # mode its index will be built for.
+    def initialize(model, column = :username, mode: nil)
+      @model = model.is_a?(String) ? model.constantize : model
+      @column = column.to_sym
+      @definition = @model._usernames[@column] if @model.respond_to?(:_usernames)
+      @mode_given = !mode.to_s.empty?
+      @mode = @mode_given ? mode.to_sym : Comparison.mode_for(@model, @column)
+      raise ArgumentError, "mode must be lowercase or preserve (got #{mode.inspect})" unless MODES.include?(@mode)
+
+      @rules = @definition ? @definition.rules : Usernames.configuration.rules_for(case: @mode)
+      @problems = 0
+    end
+
+    # Writes the report to `io` and returns the number of problems found
+    # (values failing today's rules are a note, not a problem).
+    def report(io = $stdout)
+      @io = io
+      line "usernames:audit #{model.name}##{column} (#{model.table_name}.#{column}, #{mode} mode, " \
+           "#{connection.adapter_name}) — read-only"
+      undeclared_note
+      return finish unless column_section
+
+      index_section
+      values_section
+      finish
+    end
+
+    private
+
+    def connection
+      model.lease_connection
+    end
+
+    def adapter
+      Comparison.adapter(connection)
+    end
+
+    # Without the declaration the audit cannot know the column's own rules
+    # (length, separators…) or, unless told, its case mode.
+    def undeclared_note
+      return if @definition
+
+      other = (MODES - [mode]).first
+      mode_hint = @mode_given ? "" : " (the configured one; for #{other}: usernames:audit[#{model.name},#{column},#{other}])"
+      line "  · #{model.name} doesn't declare has_username :#{column} yet: checked against the configured rules, " \
+           "in #{mode} mode#{mode_hint}"
+    end
+
+    # --- the column (the criteria per adapter) ------------------------------------------------
+
+    def column_section
+      section "Column"
+      definition = model.columns_hash[column.to_s]
+      if definition
+        type_and_collation(definition)
+      else
+        problem("there is no column #{model.table_name}.#{column} (rails generate usernames:install adds it)")
+      end
+      definition
+    end
+
+    def type_and_collation(definition)
+      collation = contract.column_collation
+      case adapter
+      when :postgresql then postgresql_column(definition.sql_type, collation)
+      when :mysql then expect_collation(definition.sql_type, collation, "utf8mb4_bin")
+      else sqlite_column(definition.sql_type, collation)
+      end
+    end
+
+    def postgresql_column(type, collation)
+      if type == "citext"
+        return problem("citext is incompatible: its case-insensitivity follows the database locale; " \
+                       "use a string column with collation \"C\"")
+      end
+
+      problem("#{type} is not text or character varying") unless POSTGRESQL_TYPES.match?(type)
+      if !column_collation_ok?(:postgresql, collation)
+        problem(%(#{type}, collation #{collation.inspect}: equality and lower() follow it; set collation: "C"))
+        problem(%(collation #{collation.inspect} is nondeterministic: it can ignore case or punctuation)) unless
+          deterministic?(collation)
+      elsif mode == :preserve
+        # lower(column COLLATE "C"): the explicit collation wins, so the
+        # column's own one only decides ORDER BY.
+        ok %(#{type}, collation #{collation.inspect} (compared through COLLATE "C"))
+      else
+        ok %(#{type}, collation #{collation.inspect})
+      end
+    end
+
+    def expect_collation(type, collation, expected)
+      return ok("#{type}, collation #{expected}") if column_collation_ok?(:mysql, collation)
+
+      problem("#{type}, collation #{collation.inspect}: set collation: #{expected.inspect}, a byte-wise comparison")
+    end
+
+    # SQLite's default BINARY is the contract; NOCASE (or any custom one) is not.
+    def sqlite_column(type, collation)
+      return ok("#{type}, default BINARY collation") if column_collation_ok?(:sqlite, collation)
+
+      problem("#{type}, COLLATE #{collation}: the contract is SQLite's default BINARY")
+    end
+
+    # The index verifier's own rule and its reading of the column's
+    # collation (Comparison::IndexContract), so the column check here and
+    # the index verdict below can never disagree.
+    def column_collation_ok?(adapter, collation)
+      Comparison::IndexContract.column_collation_ok?(adapter, mode, collation)
+    end
+
+    def deterministic?(collation)
+      value = connection.select_value(
+        "SELECT collisdeterministic FROM pg_collation WHERE collname = #{connection.quote(collation)}"
+      )
+      value.nil? || ActiveModel::Type::Boolean.new.cast(value)
+    rescue ActiveRecord::StatementInvalid
+      true # before PostgreSQL 12 every collation is deterministic, and the column does not exist
+    end
+
+    # --- indexes --------------------------------------------------------------------------------------
+
+    # Every index that involves the column, each with why it does not
+    # enforce the comparison contract (Comparison::IndexContract) — a
+    # partial, composite or NOCASE unique index is not uniqueness.
+    def index_section
+      section "Index"
+      matching = listed_indexes.find { |_index, reason| reason.nil? }&.first
+      return ok("#{matching.name} matches the #{mode} mode") if matching
+
+      problem("no unique index matches the #{mode} mode, so the database does not enforce uniqueness yet: " \
+              "#{add_index_line}")
+    end
+
+    def add_index_line
+      expected = contract.definition
+      "add_index #{Comparison.ruby_name(model.table_name)}, #{expected[:column].inspect}, unique: true, " \
+        "name: #{expected[:name].inspect}"
+    end
+
+    def contract
+      @contract ||= Comparison::IndexContract.new(connection, table: model.table_name, column: column, mode: mode)
+    end
+
+    # [[index, reason], …] for every index that involves the column, each
+    # printed with why it falls short (reason nil: it enforces the contract).
+    def listed_indexes
+      verdicts = connection.indexes(model.table_name).select { |index| contract.mentions?(index) }
+        .map { |index| [index, contract.violation(index)] }
+      verdicts.each { |index, reason| line "  · #{describe(index)}#{" — #{reason}" if reason}" }
+    end
+
+    def describe(index)
+      "#{index.name} (#{index.unique ? 'unique' : 'not unique'} on #{Array(index.columns).join(', ')})"
+    end
+    # --- stored values ----------------------------------------------------------------------------------
+
+    def values_section
+      values = Values.new(rules)
+      each_value { |id, value| values << [id, value] }
+      section "Stored values (#{values.total} with a #{column})"
+      noncanonical(values.noncanonical)
+      collisions(values.collisions)
+      notes(values.failing)
+    end
+
+    def noncanonical(rows)
+      list(rows, "every stored #{column} is already in its normalised form",
+           "%d differ from their normalised form (rewrite them in your own migration)") do |id, value, canonical|
+        "##{id} #{value.inspect} → #{canonical.empty? ? 'nil' : canonical.inspect}"
+      end
+    end
+
+    def collisions(groups)
+      list(groups, "no two stored names collide once normalised",
+           "groups that collide once normalised: %d (the unique index cannot be added over them)") do |key, rows|
+        "#{key.inspect}: #{rows.map { |id, value| "##{id} #{value.inspect}" }.join(', ')}"
+      end
+    end
+
+    def each_value(&)
+      model.unscoped.where.not(column => nil).in_batches(of: BATCH) do |batch|
+        batch.pluck(model.primary_key, column).each(&)
+      end
+    end
+
+    def notes(failing)
+      return ok("every stored #{column} passes today's rules") if failing.empty?
+
+      line "  · #{failing.size} fail today's rules — they keep working; only a change is validated:"
+      failing.first(EXAMPLES).each { |id, value, reason| line "      ##{id} #{value.inspect}: #{reason}" }
+      more(failing)
+    end
+  end
+end

data/lib/usernames/candidates.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Usernames
+  # Suggestions for a sign-up form: `Usernames.candidates_for("Javi R", count: 5)`.
+  #
+  # Up to 3 × count allowed names, best first: the seed itself, first name +
+  # last initial, the seed with a few random digits, then default shapes.
+  # Three times as many as asked for because the caller still subtracts
+  # the taken ones (one query) and should usually have `count` left.
+  module Candidates
+    class << self
+      def for(seed, count:, rules:)
+        unless count.is_a?(Integer) && count.positive?
+          raise ArgumentError, "count must be a positive whole number (got #{count.inspect})"
+        end
+
+        limit = 3 * count
+        names = []
+        seeded(seed, count, rules).each { |draw| add(names, draw, limit, rules) }
+        # Default shapes for the rest, within a bounded number of draws: a
+        # tight rule set may allow few of them, and this must still end.
+        [limit * 2, Generator::DRAWS].max.times do |index|
+          break if names.size >= limit
+
+          add(names, Generator.shape(index + 1, rules), limit, rules)
+        end
+        names
+      end
+
+      private
+
+      # The cleaned seed; first name + last initial, with each configured
+      # separator and with none (`javi_r`, `javir`); then the seed with two
+      # and three random digits, `count` of them in turn.
+      def seeded(seed, count, rules)
+        return [] if seed.nil?
+
+        base = Generator.clean(seed, rules)
+        return [] if base.empty?
+
+        max = rules.length.max
+        [Generator.fit(base, max, rules), *initials(Generator.words(seed, rules), rules)] +
+          Array.new(count) { |index| Generator.with_digits(base, index.even? ? 10..99 : 100..999, rules) }
+      end
+
+      def initials(words, rules)
+        return [] if words.size < 2
+
+        initial = words.last[0]
+        (rules.separators + [""]).filter_map do |separator|
+          first = Generator.fit(words.first, rules.length.max - separator.length - initial.length, rules)
+          "#{first}#{separator}#{initial}" if first
+        end
+      end
+
+      def add(names, draw, limit, rules)
+        return if draw.nil? || names.size >= limit
+
+        name = rules.normalize(draw)
+        names << name unless name.empty? || names.include?(name) || rules.failure_for(name)
+      end
+    end
+  end
+end