idxfence 0.1.0

data/lib/idxfence/checker.rb

@@ -0,0 +1,81 @@
+require_relative "model_parser"
+require_relative "schema_parser"
+require_relative "inflector"
+require_relative "finding"
+
+module Idxfence
+  # Joins the two passes: every uniqueness validation ModelParser found
+  # in app/models/*.rb, resolved to a table name (via
+  # Inflector.table_name_for, unless the model set `self.table_name`
+  # explicitly), against every unique index SchemaParser found in
+  # db/schema.rb for that same table. A validation with no matching
+  # unique index -- one covering exactly its column set (the validated
+  # column plus any `scope:` column(s), unordered) -- is a real gap: the
+  # AR validation can be raced, and only a DB-level unique index closes
+  # it. See DETAILS.md for the full algorithm and its documented
+  # limitations (case-insensitive uniqueness, irregular pluralization,
+  # etc).
+  class Checker
+    def initialize(model_paths:, schema_path:)
+      @model_paths = model_paths
+      @schema_path = schema_path
+    end
+
+    # @return [Array<Finding>, String] findings, and a warning string
+    #   (nil if none) when db/schema.rb was missing/unparseable -- in
+    #   that case findings is always [] since nothing can be
+    #   cross-referenced without it.
+    def call
+      begin
+        schema_tables = SchemaParser.parse(schema_path)
+      rescue SchemaParser::MissingSchemaError => e
+        return [[], "idxfence: warning: #{e.message} -- skipping uniqueness cross-check for #{model_paths.size} model file(s)"]
+      end
+
+      findings = model_paths.flat_map do |model_path|
+        ModelParser.new(path: model_path).call.flat_map do |parsed_model|
+          check_model(parsed_model, schema_tables)
+        end
+      end
+
+      [findings, nil]
+    end
+
+    private
+
+    attr_reader :model_paths, :schema_path
+
+    def check_model(parsed_model, schema_tables)
+      return [] if parsed_model.validations.empty?
+
+      table = parsed_model.table_name_override || Inflector.table_name_for(parsed_model.class_name)
+      unique_indexes = schema_tables[table] || []
+
+      parsed_model.validations.filter_map do |validation|
+        required = ([validation.column] + validation.scope).sort
+        next if unique_indexes.any? { |index_cols| index_cols.sort == required }
+
+        Finding.new(
+          code: "IX001",
+          model: parsed_model.class_name,
+          table: table,
+          column: validation.column,
+          scope: validation.scope,
+          file: parsed_model.file,
+          line: validation.line,
+          message: build_message(parsed_model.class_name, table, validation)
+        )
+      end
+    end
+
+    def build_message(class_name, table, validation)
+      scope_desc = validation.scope.empty? ? "" : " scoped to #{validation.scope.join(', ')}"
+      columns_desc = ([validation.column] + validation.scope).join(", ")
+      "#{class_name} validates uniqueness of :#{validation.column}#{scope_desc} at the application layer only -- " \
+        "db/schema.rb has no unique index on #{table}(#{columns_desc}). Two concurrent requests can both pass " \
+        "the validation's SELECT check before either INSERT commits, producing a genuine duplicate row. Add a " \
+        "matching `add_index :#{table}, [#{[validation.column, *validation.scope].map { |c| ":#{c}" }.join(', ')}], unique: true` " \
+        "migration. See DETAILS.md."
+    end
+  end
+end

data/lib/idxfence/cli.rb

@@ -0,0 +1,64 @@
+require "optparse"
+
+module Idxfence
+  module CLI
+    module_function
+
+    def run(argv, out: $stdout, err: $stderr)
+      command, *rest = argv
+
+      case command
+      when "check"
+        check(rest, out: out, err: err)
+      else
+        err.puts usage
+        2
+      end
+    end
+
+    def usage
+      "usage: idxfence check <rails-project-dir> [<rails-project-dir> ...] [--json]\n" \
+        "       (each <rails-project-dir> must contain app/models/ and db/schema.rb)"
+    end
+
+    def check(argv, out:, err:)
+      options = { json: false }
+
+      parser = OptionParser.new do |opts|
+        opts.banner = usage
+        opts.on("--json", "emit JSON instead of text") { options[:json] = true }
+      end
+
+      begin
+        parser.parse!(argv)
+      rescue OptionParser::ParseError => e
+        err.puts "idxfence: #{e.message}"
+        return 2
+      end
+
+      if argv.empty?
+        err.puts usage
+        return 2
+      end
+
+      all_findings = []
+      warnings = []
+
+      argv.each do |project_dir|
+        findings, warning = Idxfence.check(project_dir: project_dir)
+        all_findings.concat(findings)
+        warnings << warning if warning
+      end
+
+      warning_text = warnings.empty? ? nil : warnings.join("\n")
+
+      if options[:json]
+        out.puts Render.json(all_findings, warning: warning_text)
+      else
+        out.puts Render.text(all_findings, warning: warning_text)
+      end
+
+      all_findings.empty? ? 0 : 1
+    end
+  end
+end

data/lib/idxfence/finding.rb

@@ -0,0 +1,26 @@
+module Idxfence
+  # A single ActiveRecord `uniqueness: true` validation (application-layer
+  # only) with no matching database-level unique index to back it up --
+  # meaning two concurrent requests can both pass the validation's
+  # `SELECT ... WHERE` check before either one's `INSERT` commits, landing
+  # a genuine duplicate row despite the validation "working." See
+  # DETAILS.md for the exact race and why only a DB-level unique index
+  # closes it.
+  #
+  # code:    "IX001" every finding uses this single code (one rule: an AR
+  #          uniqueness validation with no matching DB unique index)
+  # model:   the model class name, e.g. "User"
+  # table:   the resolved table name the validation's column(s) were
+  #          checked against, e.g. "users"
+  # column:  the column the validation checks, e.g. "email"
+  # scope:   Array<String> of scope column(s), e.g. ["account_id"]; empty
+  #          array for an unscoped validation
+  # file:    path to the model source file
+  # line:    line number of the `validates`/`validates_uniqueness_of` call
+  # message: a human-readable description
+  Finding = Struct.new(:code, :model, :table, :column, :scope, :file, :line, :message, keyword_init: true) do
+    def to_h
+      { code: code, model: model, table: table, column: column, scope: scope, file: file, line: line, message: message }
+    end
+  end
+end

data/lib/idxfence/inflector.rb

@@ -0,0 +1,69 @@
+module Idxfence
+  # A small, deliberately conservative stand-in for ActiveSupport::Inflector
+  # -- just enough of Rails' own table-name-inference convention
+  # (`Model.name.demodulize.underscore.pluralize`) to resolve a model's
+  # default table name without requiring an actual Rails/ActiveSupport
+  # installation. See DETAILS.md's "table-name inference" section for
+  # exactly which pluralization rules are (and are not) implemented, and
+  # why `self.table_name = "..."` is honored as an explicit override
+  # rather than something idxfence tries to out-guess.
+  module Inflector
+    UNCOUNTABLE = %w[series species equipment information news].freeze
+
+    IRREGULAR = {
+      "person" => "people",
+      "man" => "men",
+      "woman" => "women",
+      "child" => "children",
+      "tooth" => "teeth",
+      "foot" => "feet",
+      "mouse" => "mice",
+      "goose" => "geese"
+    }.freeze
+
+    module_function
+
+    # "Admin::UserAccount" -> "UserAccount" (only the last namespace
+    # segment -- matches Rails' default `table_name_prefix`-less
+    # behavior; a project that sets a custom `table_name_prefix` isn't
+    # modeled here, see DETAILS.md).
+    def demodulize(class_name)
+      class_name.to_s.split("::").last.to_s
+    end
+
+    # "UserAccount" -> "user_account"
+    def underscore(camel)
+      camel.to_s
+           .gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+           .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+           .downcase
+    end
+
+    # "user_account" -> "user_accounts" (a deliberately small rule set,
+    # not a full English pluralizer -- see DETAILS.md limitations).
+    def pluralize(word)
+      return word if UNCOUNTABLE.include?(word)
+      return IRREGULAR[word] if IRREGULAR.key?(word)
+
+      case word
+      when /(ch|sh|ss|x|z)\z/
+        "#{word}es"
+      when /[^aeiou]y\z/
+        "#{word[0..-2]}ies"
+      when /(fe)\z/
+        "#{word[0..-3]}ves"
+      when /[^f]f\z/
+        "#{word[0..-2]}ves"
+      when /s\z/
+        word
+      else
+        "#{word}s"
+      end
+    end
+
+    # Rails' own default: `Model.name.demodulize.underscore.pluralize`.
+    def table_name_for(class_name)
+      pluralize(underscore(demodulize(class_name)))
+    end
+  end
+end

data/lib/idxfence/model_parser.rb

@@ -0,0 +1,219 @@
+require "ripper"
+
+module Idxfence
+  # Parses one Ruby source file with Ripper (structural boundaries --
+  # class start/end -- come from the s-expression, never from `do`/`end`
+  # counting; a narrower regex pass then runs only over the *text* of a
+  # class body already located structurally, the same hybrid technique
+  # this workspace's mailstall/jobclash/lockstall packages use) looking
+  # for a Rails model class (superclass `ApplicationRecord` or
+  # `ActiveRecord::Base`) and, within its own body:
+  #
+  #   - an explicit `self.table_name = "..."` override, if present
+  #   - every `validates :col[, :col2, ...], uniqueness: true` (or
+  #     `uniqueness: { scope: ..., ... }`) and
+  #     `validates_uniqueness_of :col[, :col2, ...][, scope: ...]`
+  #     declaration, one UniquenessValidation per column named.
+  #
+  # This is deliberately one file's worth of information -- resolving it
+  # against a database-level unique index requires a second pass over
+  # db/schema.rb, done separately by Idxfence::SchemaParser and joined by
+  # Idxfence::Checker. See DETAILS.md's "two passes" section.
+  class ModelParser
+    MODEL_SUPERCLASS = /\A(?:ApplicationRecord|ActiveRecord::Base)\z/.freeze
+
+    UniquenessValidation = Struct.new(:column, :scope, :line, keyword_init: true)
+    ParsedModel = Struct.new(:class_name, :table_name_override, :validations, :file, keyword_init: true)
+
+    # One `validates`/`validates_uniqueness_of` statement's leading list
+    # of bare `:symbol` column arguments, e.g. the `:email, :username` in
+    # `validates :email, :username, uniqueness: true`.
+    LEADING_COLUMNS = /\A\s*(?:validates(?:_uniqueness_of)?)\s+((?::\w+\s*,\s*)*:\w+)/.freeze
+
+    SCOPE_SYMBOL = /scope:\s*:(\w+)/.freeze
+    SCOPE_ARRAY = /scope:\s*\[([^\]]*)\]/.freeze
+    SCOPE_PCT_I = /scope:\s*%i\[([^\]]*)\]/.freeze
+
+    SELF_TABLE_NAME = /self\.table_name\s*=\s*["']([^"']+)["']/.freeze
+
+    def initialize(path:)
+      @path = path
+    end
+
+    def call
+      source = File.read(path)
+      sexp = Ripper.sexp(source)
+      return [] unless sexp
+
+      lines = source.lines
+      models = []
+
+      each_class_node(sexp) do |class_name, class_node|
+        next unless model_class?(class_node)
+
+        start_line = min_line(class_node)
+        end_line = max_line(class_node)
+        next unless start_line && end_line
+
+        body_source = lines[(start_line - 1)...end_line].join
+
+        models << ParsedModel.new(
+          class_name: class_name,
+          table_name_override: (m = body_source.match(SELF_TABLE_NAME)) && m[1],
+          validations: uniqueness_validations(body_source, lines, start_line),
+          file: path
+        )
+      end
+
+      models
+    end
+
+    private
+
+    attr_reader :path
+
+    # Walks the class body's own source text statement-by-statement,
+    # buffering lines from a `validates`/`validates_uniqueness_of` call
+    # until its parens/braces balance (so an options hash wrapped across
+    # multiple lines, e.g. `uniqueness: { scope: ..., \n case_sensitive:
+    # false }`, is still read as one statement), then extracts every
+    # uniqueness-checked column out of that buffered statement.
+    def uniqueness_validations(body_source, all_lines, class_start_line)
+      validations = []
+      buffer = nil
+      buffer_start_line = nil
+      depth = 0
+      body_line_count = 0
+
+      body_source.each_line.with_index do |line, idx|
+        body_line_count = idx + 1
+        absolute_line = class_start_line + idx
+
+        if buffer.nil?
+          next unless line =~ /\bvalidates(?:_uniqueness_of)?\b/
+
+          buffer = +""
+          buffer_start_line = absolute_line
+        end
+
+        buffer << line
+        depth += line.count("{") + line.count("(") + line.count("[")
+        depth -= line.count("}") + line.count(")") + line.count("]")
+
+        next if depth > 0
+
+        validations.concat(parse_statement(buffer, buffer_start_line))
+        buffer = nil
+        buffer_start_line = nil
+      end
+
+      # Ripper.sexp's leaf position tracking only covers tokens that
+      # carry their own content (identifiers, literals, keywords) --
+      # a class body whose captured span ends on a line containing only
+      # closing punctuation (`}`, `end`) is not reflected in that span,
+      # so a statement buffer still open here (an options hash whose
+      # closing `}` fell on such a line) is finished by reading straight
+      # past the class node's own detected span, from the underlying
+      # file, until it balances or the file runs out.
+      if buffer
+        (class_start_line - 1 + body_line_count...all_lines.length).each do |i|
+          line = all_lines[i]
+          break unless line
+
+          buffer << line
+          depth += line.count("{") + line.count("(") + line.count("[")
+          depth -= line.count("}") + line.count(")") + line.count("]")
+          break if depth <= 0
+        end
+
+        validations.concat(parse_statement(buffer, buffer_start_line))
+      end
+
+      validations
+    end
+
+    def parse_statement(statement, line)
+      return [] unless statement =~ /\buniqueness:/ || statement =~ /\bvalidates_uniqueness_of\b/
+
+      columns_match = statement.match(LEADING_COLUMNS)
+      return [] unless columns_match
+
+      columns = columns_match[1].scan(/:(\w+)/).flatten
+      scope = extract_scope(statement)
+
+      columns.map { |col| UniquenessValidation.new(column: col, scope: scope, line: line) }
+    end
+
+    def extract_scope(statement)
+      if (m = statement.match(SCOPE_PCT_I))
+        return m[1].split(/\s+/).reject(&:empty?)
+      end
+
+      if (m = statement.match(SCOPE_ARRAY))
+        return m[1].scan(/:(\w+)/).flatten
+      end
+
+      if (m = statement.match(SCOPE_SYMBOL))
+        return [m[1]]
+      end
+
+      []
+    end
+
+    def model_class?(class_node)
+      superclass_node = class_node[2]
+      return false unless superclass_node
+
+      name = const_name(superclass_node)
+      !!(name && name.match?(MODEL_SUPERCLASS))
+    end
+
+    def each_class_node(node, &block)
+      return unless node.is_a?(Array)
+
+      if node[0] == :class
+        name = const_name(node[1])
+        block.call(name, node)
+        return
+      end
+
+      node.each { |child| each_class_node(child, &block) }
+    end
+
+    def const_name(node)
+      parts = []
+      collect_const_leaves(node, parts)
+      parts.empty? ? nil : parts.join("::")
+    end
+
+    def collect_const_leaves(node, acc)
+      return unless node.is_a?(Array)
+
+      acc << node[1] if node[0] == :@const && node[1].is_a?(String)
+      node.each { |child| collect_const_leaves(child, acc) }
+    end
+
+    def min_line(node)
+      lines = []
+      collect_lines(node, lines)
+      lines.min
+    end
+
+    def max_line(node)
+      lines = []
+      collect_lines(node, lines)
+      lines.max
+    end
+
+    def collect_lines(node, acc)
+      return unless node.is_a?(Array)
+
+      if node.length == 2 && node.all? { |x| x.is_a?(Integer) }
+        acc << node[0]
+        return
+      end
+
+      node.each { |child| collect_lines(child, acc) }
+    end
+  end
+end

data/lib/idxfence/render.rb

@@ -0,0 +1,28 @@
+require "json"
+
+module Idxfence
+  module Render
+    module_function
+
+    def text(findings, warning: nil)
+      lines = []
+      lines << "idxfence: #{warning}" if warning
+
+      if findings.empty?
+        lines << "idxfence: no unguarded uniqueness validations found" unless warning
+        return lines.join("\n")
+      end
+
+      lines << "idxfence: #{findings.size} finding(s)"
+      findings.each do |f|
+        scope_desc = f.scope.empty? ? "" : " (scope: #{f.scope.join(', ')})"
+        lines << "[#{f.code}] #{f.file}:#{f.line} #{f.model}##{f.column}#{scope_desc} -> #{f.table} has no matching unique index: #{f.message}"
+      end
+      lines.join("\n")
+    end
+
+    def json(findings, warning: nil)
+      JSON.generate(findings: findings.map(&:to_h), warning: warning)
+    end
+  end
+end

data/lib/idxfence/schema_parser.rb

@@ -0,0 +1,127 @@
+require "ripper"
+
+module Idxfence
+  # Parses `db/schema.rb` (Rails' generated, declarative snapshot of the
+  # database schema) with Ripper looking for each `create_table` block's
+  # boundary structurally, then a narrower regex pass over that block's
+  # own text extracting every `t.index [...], unique: true` line -- the
+  # same hybrid technique Idxfence::ModelParser uses on model files. See
+  # DETAILS.md's "two passes" section for why this has to be a second,
+  # separate pass over a different file rather than something
+  # ModelParser could infer on its own.
+  #
+  # Returns a Hash of table_name => Array<Array<String>>, one entry per
+  # *unique* index found in that table's `create_table` block, each an
+  # array of the index's own column names in the order `t.index` declared
+  # them (order doesn't matter for matching -- Checker compares as sets).
+  # A non-unique `t.index` (no `unique: true`) is not collected at all --
+  # it can't enforce uniqueness at the database level regardless of what
+  # columns it covers.
+  class SchemaParser
+    CREATE_TABLE_IDENT = "create_table".freeze
+    TABLE_NAME_LINE = /create_table\s+["']([^"']+)["']/.freeze
+    INDEX_LINE = /t\.index\s+\[([^\]]*)\](?:[^\n]*?unique:\s*true)?/.freeze
+
+    class MissingSchemaError < StandardError; end
+
+    def self.parse(path)
+      raise MissingSchemaError, "#{path}: no such file" unless File.exist?(path)
+
+      new(path: path).call
+    end
+
+    def initialize(path:)
+      @path = path
+    end
+
+    def call
+      source = File.read(path)
+      sexp = Ripper.sexp(source)
+      raise MissingSchemaError, "#{path}: could not parse (invalid Ruby syntax)" unless sexp
+
+      lines = source.lines
+      tables = Hash.new { |h, k| h[k] = [] }
+
+      each_create_table_block(sexp) do |block_node|
+        start_line = min_line(block_node)
+        end_line = max_line(block_node)
+        next unless start_line && end_line
+
+        block_source = lines[(start_line - 1)...end_line].join
+        table_name = (m = block_source.match(TABLE_NAME_LINE)) && m[1]
+        next unless table_name
+
+        block_source.each_line do |line|
+          next unless line =~ /t\.index\b/
+
+          idx_match = line.match(INDEX_LINE)
+          next unless idx_match
+          next unless line.match?(/unique:\s*true/)
+
+          columns = idx_match[1].scan(/["']([^"']+)["']/).flatten
+          tables[table_name] << columns unless columns.empty?
+        end
+      end
+
+      tables
+    end
+
+    private
+
+    attr_reader :path
+
+    # Yields the block node of every `create_table "...", ... do |t| ...
+    # end` call (a `:method_add_block` s-expression whose call target's
+    # method name is exactly `create_table`).
+    def each_create_table_block(node, &block)
+      return unless node.is_a?(Array)
+
+      if node[0] == :method_add_block && create_table_call?(node[1])
+        block.call(node[2])
+        return
+      end
+
+      node.each { |child| each_create_table_block(child, &block) }
+    end
+
+    def create_table_call?(call_node)
+      ident = find_first_ident(call_node)
+      ident == CREATE_TABLE_IDENT
+    end
+
+    def find_first_ident(node)
+      return nil unless node.is_a?(Array)
+      return node[1] if node[0] == :@ident && node[1].is_a?(String)
+
+      node.each do |child|
+        found = find_first_ident(child)
+        return found if found
+      end
+
+      nil
+    end
+
+    def min_line(node)
+      lines = []
+      collect_lines(node, lines)
+      lines.min
+    end
+
+    def max_line(node)
+      lines = []
+      collect_lines(node, lines)
+      lines.max
+    end
+
+    def collect_lines(node, acc)
+      return unless node.is_a?(Array)
+
+      if node.length == 2 && node.all? { |x| x.is_a?(Integer) }
+        acc << node[0]
+        return
+      end
+
+      node.each { |child| collect_lines(child, acc) }
+    end
+  end
+end

data/lib/idxfence/version.rb

@@ -0,0 +1,3 @@
+module Idxfence
+  VERSION = "0.1.0"
+end

data/lib/idxfence.rb

@@ -0,0 +1,40 @@
+require_relative "idxfence/version"
+require_relative "idxfence/finding"
+require_relative "idxfence/inflector"
+require_relative "idxfence/model_parser"
+require_relative "idxfence/schema_parser"
+require_relative "idxfence/checker"
+require_relative "idxfence/render"
+
+module Idxfence
+  class << self
+    # Scans a Rails project root for ActiveRecord `uniqueness: true` /
+    # `uniqueness: { ... }` / `validates_uniqueness_of` validations under
+    # `app/models/**/*.rb` with no matching unique index in
+    # `db/schema.rb`.
+    #
+    # @param project_dir [String] path to a Rails project root (the
+    #   directory containing `app/` and `db/`)
+    # @return [Array(Array<Finding>, String, nil)] findings, and a
+    #   warning string (nil if none) when db/schema.rb was missing or
+    #   unparseable
+    def check(project_dir:)
+      model_paths = Dir.glob(File.join(project_dir, "app", "models", "**", "*.rb"))
+      schema_path = File.join(project_dir, "db", "schema.rb")
+
+      check_paths(model_paths: model_paths, schema_path: schema_path)
+    end
+
+    # Lower-level entry point: an explicit list of model file paths and
+    # one schema.rb path, for callers that already know their own
+    # layout (or for testing against fixtures that aren't laid out as a
+    # full Rails project).
+    #
+    # @param model_paths [Array<String>]
+    # @param schema_path [String]
+    # @return [Array(Array<Finding>, String, nil)]
+    def check_paths(model_paths:, schema_path:)
+      Checker.new(model_paths: model_paths, schema_path: schema_path).call
+    end
+  end
+end