idxfence 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 794cbdb21b56bd42bd76746144881c689cca74c95f90e943cc338c19970f4b6d
+  data.tar.gz: fe88f00617bb381545c72a74e44c7ee18198d7abc8e43880e5d9f2989bce0cd4
+SHA512:
+  metadata.gz: b7bb81eadf4b7503b41bd7c7865286df53b8eef4225e551f0945330996d0660430dfc3e7d15df1d84bc77675e6a8a365c32e2c793a989b2123159e101f9e23c8
+  data.tar.gz: 03d2ca96d275480e65eb6610d05be5c3ef9c1bf259097e757066ddf916e052b6d91e7add5d9e1da94c1125aeafbf07579f417b0e4886f67a5c561d5b068b22a3

data/DETAILS.md

@@ -0,0 +1,293 @@
+# idxfence — Design Details
+
+## Why this exists
+
+`ActiveRecord::Validations::Uniqueness` gives every model a friendly,
+one-line way to reject a duplicate before it ever touches the database:
+
+```ruby
+class User < ApplicationRecord
+  validates :email, uniqueness: true
+end
+```
+
+It looks like a correctness guarantee. It is not one. `uniqueness: true`
+compiles down to a `SELECT 1 FROM users WHERE email = ? LIMIT 1` run
+**before** the `INSERT`, in the same request, on the same connection. If
+that `SELECT` finds nothing, Rails lets the `INSERT` proceed. Nothing
+about this sequence is atomic:
+
+```
+Request A: SELECT ... WHERE email = 'a@b.com'  -> 0 rows, OK to insert
+Request B: SELECT ... WHERE email = 'a@b.com'  -> 0 rows, OK to insert
+Request A: INSERT INTO users (email) VALUES ('a@b.com')  -> commits
+Request B: INSERT INTO users (email) VALUES ('a@b.com')  -> commits too
+```
+
+Two requests, both individually "validated," landing a genuine duplicate
+row. This isn't a contrived edge case -- it's two form submissions a few
+milliseconds apart (a double-click, a flaky client retry, two browser
+tabs), a background job re-processing the same webhook payload that
+raced a live request, or any modest amount of real concurrent traffic
+hitting a signup/registration endpoint. The Rails Guides' own Active
+Record Validations guide documents this exact race in its section on
+`uniqueness`, and recommends a database-level unique index as the only
+real fix -- the AR validation is explicitly framed there as a UX nicety
+(a friendly in-app error message before ever reaching the DB), not a
+correctness guarantee. Plenty of real, shipped Rails apps have only the
+AR-level check, because it "works" in every manual test and in every
+single-threaded spec run, and the gap simply never surfaces until
+production traffic finds it.
+
+## Why a DB-level unique index is the actual fix
+
+A unique index makes the *second* `INSERT` fail, atomically, at the
+database's own constraint-enforcement layer -- no race window exists
+because uniqueness is now checked as part of the same operation that
+writes the row, not as a separate prior query. The fix is not to remove
+the AR validation (it's still valuable for a fast, friendly in-request
+error message on the common case) -- it's to **also** add the matching
+index and rescue `ActiveRecord::RecordNotUnique` on the rare occasions
+the race actually happens:
+
+```ruby
+add_index :users, :email, unique: true
+```
+
+This is why idxfence doesn't flag "uniqueness: true with no index" as
+"remove the validation" -- it flags it as "add the index," which is
+exactly what Rails' own guide recommends.
+
+## Why this needs two passes over two different files
+
+A single `app/models/user.rb` file only tells you *what the application
+layer checks*. Whether that check is actually backed by a database
+constraint lives in a completely different file, generated by Rails
+itself from actual migrations: `db/schema.rb`. There is no way to answer
+"is this uniqueness validation race-safe?" from the model file alone --
+the same way there's no way to know if a lock is held without also
+looking at what's guarding the resource. idxfence therefore always
+performs two independent passes:
+
+1. **`Idxfence::ModelParser`** parses one `app/models/*.rb` file at a
+   time and extracts every `validates ..., uniqueness: true` /
+   `uniqueness: { ... }` / `validates_uniqueness_of ...` declaration,
+   plus an explicit `self.table_name = "..."` override if present. It
+   knows nothing about the database.
+2. **`Idxfence::SchemaParser`** parses `db/schema.rb` once and extracts,
+   for every `create_table` block, the column set of every *unique*
+   `t.index` inside it. It knows nothing about any model.
+3. **`Idxfence::Checker`** is the only place these two are joined: for
+   each validation, it resolves the table name (see below), looks up
+   that table's unique indexes from the schema pass, and reports a
+   finding only if none of them cover exactly that validation's column
+   set.
+
+This is a deliberately different shape from most of this workspace's
+other Ruby checkers (`mailstall`, `jobclash`, `lockstall`), which all
+answer their question from a single file. idxfence cannot.
+
+## Table-name resolution algorithm
+
+Rails' own default: `Model.name.demodulize.underscore.pluralize`. Given
+a model class found in `app/models/user.rb`:
+
+1. If the class body contains `self.table_name = "some_table"` (a plain
+   string/symbol literal assignment, found by regex over the class
+   body's own source text -- not full Ruby evaluation), that exact
+   string is used, unconditionally, no matter what the class is named.
+   This is checked **first** and short-circuits inference entirely --
+   matching Rails' own behavior, where an explicit `table_name=` always
+   wins.
+2. Otherwise, `Idxfence::Inflector.table_name_for(class_name)`:
+   - **Demodulize**: only the last `::`-separated segment of the class
+     name is used (`Admin::UserAccount` -> `UserAccount`). A project
+     that sets a custom, non-default `table_name_prefix` on a namespace
+     isn't modeled -- see limitations.
+   - **Underscore**: `UserAccount` -> `user_account` (standard
+     CamelCase-to-snake_case).
+   - **Pluralize**: a small, deliberately non-exhaustive rule set --
+     `-y` preceded by a consonant -> `-ies`; `-ch`/`-sh`/`-ss`/`-x`/`-z`
+     -> `+es`; `-fe`/`-f` -> `-ves`; already ending in `-s` -> unchanged;
+     a short table of common irregulars (`person` -> `people`, `child`
+     -> `children`, etc.); otherwise `+s`. This is **not**
+     ActiveSupport::Inflector -- see limitations for exactly what it
+     doesn't handle.
+
+## Scope-column-set matching algorithm
+
+A `validates :email, uniqueness: { scope: :account_id }` validation is
+only actually enforced by an index covering **both** columns together --
+a unique index on `email` alone does *not* prevent two different
+`account_id`s from each having their own duplicate `email`... but it
+also does not prevent the specific race this validation exists to catch
+(two requests for the *same* `account_id` both inserting the same
+`email`), because a single-column unique index on `email` alone would
+incorrectly forbid that email existing under any other account too,
+which isn't even what the validation says it's protecting -- so a
+single-column index is treated as **not a match** for a scoped
+validation, full stop.
+
+Concretely: for a validation on column `C` with scope columns `S`
+(`S` is empty for an unscoped validation), idxfence computes
+`required = ({C} ∪ S).sort` and considers it satisfied only if
+`db/schema.rb` has a unique index on that table whose own column list,
+sorted, equals `required` exactly:
+
+- Same size, same columns -- order doesn't matter (`t.index
+  ["account_id", "email"], unique: true` and `t.index ["email",
+  "account_id"], unique: true` both satisfy `scope: :account_id` on
+  `:email`).
+- A **subset** doesn't count (a unique index on `email` alone does not
+  satisfy `scope: :account_id` on `:email` -- see above).
+- A **superset** doesn't count either (a unique index on
+  `[account_id, email, region]` does not satisfy a validation scoped
+  only to `account_id` -- Rails' own uniqueness validation with `scope:
+  :account_id` only queries `WHERE account_id = ? AND email = ?`, so a
+  three-column unique index enforces a stricter, different invariant
+  than what the validation actually checks; a duplicate `(account_id,
+  email)` pair with two different `region`s would still pass that
+  three-column index but is exactly the race the two-column validation
+  is supposed to prevent).
+
+`scope:` is recognized in all three forms Rails accepts: a bare symbol
+(`scope: :account_id`), an array literal (`scope: [:account_id,
+:region]`), and a `%i[]` literal (`scope: %i[account_id region]`).
+
+`validates :email, :username, uniqueness: true` (multiple columns in one
+statement) is treated as **two independent, single-column** uniqueness
+validations -- this matches Rails' own actual runtime behavior, which
+registers one separate `UniquenessValidator` per attribute listed, each
+checked on its own.
+
+## How it parses (Ripper for structural boundaries, regex within them)
+
+Same hybrid technique this workspace's `mailstall`/`jobclash`/`lockstall`
+packages use: structural boundaries -- class bodies, `create_table`
+blocks -- come from `Ripper.sexp`, never from naive `do`/`end` line
+counting. A narrower regex pass then runs only over the *text* of a
+boundary already located structurally.
+
+- **`ModelParser`**: walks the s-expression for every `class` node,
+  filters to ones whose superclass constant is exactly
+  `ApplicationRecord`/`ActiveRecord::Base` (the same conservative,
+  single-file superclass check `mailstall` uses for controllers -- a
+  model inheriting from a project-specific `ApplicationRecord` subclass
+  chain isn't traced). Within that class's own source-text span, a
+  `validates`/`validates_uniqueness_of` statement is buffered
+  line-by-line, tracking paren/brace/bracket depth, until it balances --
+  so a `uniqueness: { ... }` options hash wrapped across several lines
+  is still read as one statement, not truncated at the first line break.
+  One known Ripper quirk this had to work around: a class node's own
+  detected line span, built purely from the positions Ripper attaches to
+  *content-bearing* tokens (identifiers, literals, keywords), does not
+  extend to a line containing only closing punctuation (a lone `}` or
+  `end`) with nothing else on it -- so a still-open statement buffer at
+  the end of that span is completed by reading straight from the
+  underlying file past the detected span, until its brackets balance or
+  the file runs out, rather than being silently dropped.
+- **`SchemaParser`**: walks the s-expression for every
+  `:method_add_block` node whose call target is the identifier
+  `create_table`, locates that block's own text span the same way, then
+  regex-extracts the table name (`create_table "table_name"`) and every
+  `t.index [...], ..., unique: true` line inside it (a non-unique
+  `t.index` is read but discarded -- it can't enforce anything at the
+  database level).
+
+## Explicitly out of scope / known limitations (v0.1)
+
+- **Not a full English pluralizer.** `Idxfence::Inflector` implements
+  the common regular-plural rules plus a short irregular table, not the
+  complete rule set `ActiveSupport::Inflector` ships (custom
+  `inflections.rb` overrides, uncommon irregulars, uncountable words
+  beyond a small built-in list). A model whose default-inferred table
+  name is wrong for this reason will produce a false negative or false
+  positive against the wrong table -- set `self.table_name` explicitly
+  (already fully honored, and checked first) to sidestep this entirely,
+  or treat an unexpected result as a signal to verify the actual table
+  name by hand.
+- **Case-sensitive column/table matching.** Column names are compared
+  as exact strings; a schema and model that disagree only in case
+  (unusual, but not forbidden by Postgres/MySQL) won't match. This
+  mirrors real-world convention (Rails/DB column and table names are
+  conventionally lowercase snake_case) rather than a deliberate design
+  choice to ignore case.
+- **Does not model `uniqueness: { case_sensitive: false }` at the SQL
+  level.** A `LOWER(email)` functional/expression unique index (a valid,
+  common way to actually enforce case-insensitive uniqueness at the DB
+  layer) is not recognized as satisfying a case-insensitive validation
+  -- idxfence only looks for a plain `t.index [...], unique: true` on
+  the literal column name. A validation declaring `case_sensitive:
+  false` is checked the same as any other uniqueness validation (does a
+  plain unique index exist on this column set), which is a real but
+  separate gap from the one this tool targets -- documented here rather
+  than silently mismatched.
+- **No custom `table_name_prefix`/`table_name_suffix` resolution.** Only
+  `self.table_name = "..."` (an explicit, literal override) and the
+  default demodulized/underscored/pluralized class name are considered;
+  a namespace-wide prefix/suffix convention set elsewhere (e.g. in an
+  initializer or a shared base class) isn't traced across files.
+- **No STI (single-table inheritance) awareness.** A subclass of another
+  AR model (not `ApplicationRecord`/`ActiveRecord::Base` directly) isn't
+  recognized as a model at all by the current superclass check -- an STI
+  subclass's own `validates` declarations (if any) are not scanned. This
+  is the same single-file, no-cross-file-inheritance-graph trade-off
+  `mailstall` documents for controllers.
+- **No autofix, no runtime enforcement.** idxfence only reports; it
+  never writes a migration, and it never runs inside the request path.
+
+## Prior art (checked before building, 2026-09)
+
+**No existing static analyzer checks this specific cross-file
+invariant.** RuboCop-Rails has cops that check validation *syntax*
+(`Rails/UniqueValidationWithoutIndex` was proposed community-side in the
+past but is not present in the current, actively maintained cop list as
+of this writing -- searched 2026-09) but nothing shipped and maintained
+in the current RuboCop-Rails release cross-references `db/schema.rb`
+against `app/models/`. Brakeman is a security scanner focused on
+injection/XSS/mass-assignment classes of bugs, not schema-vs-validation
+consistency. This exact race condition is extremely well-documented
+folklore -- it's in the Rails Guides themselves, in "Rails Antipatterns"
+and multiple widely-read blog posts going back over a decade -- but,
+searched as of this writing, no maintained open-source tool actually
+reads both files and tells you, before you ship, which of your
+`uniqueness: true` validations are silently unguarded. That's the gap
+idxfence fills.
+
+## Package layout
+
+```
+idxfence/
+  lib/idxfence.rb           # top-level require, Idxfence.check entry point
+  lib/idxfence/             # finding, model_parser, schema_parser, checker, cli, render, inflector, version
+  exe/idxfence               # CLI executable
+  spec/                       # RSpec suite + fixture Rails-project directories
+  examples/                   # one project with the genuine gap, fake app/models + db/schema.rb
+  docs/USAGE.md               # full API/CLI reference
+```
+
+## Testing
+
+Fixture-based, zero network/Rails/database dependency: each fixture is a
+tiny fake Rails project directory (`app/models/*.rb` + `db/schema.rb`)
+under `spec/fixtures/projects/`. Covers: an unscoped `uniqueness: true`
+with a matching unique index (not flagged), the same with a non-unique
+index and with no index at all (both flagged), a `scope:` validation
+with a matching composite unique index declared in either column order
+(not flagged), the same scope with only a single-column index or no
+index at all (both flagged -- a single-column index doesn't enforce
+scoped uniqueness), `self.table_name` correctly resolved against its own
+`create_table` block rather than the pluralized default (both a matching
+and a missing-index variant, the latter proving the *custom* table's own
+index state is what's checked, not the default table's), a model with no
+uniqueness validations at all (not flagged, nothing to check),
+`db/schema.rb` missing or failing to parse (a clear warning, not a
+crash, in both the library and CLI), `validates :a, :b, uniqueness: true`
+treated as two independent single-column validations, both
+`validates_uniqueness_of` (with and without `scope:`), a `-y`-ending
+class name pluralized correctly, a `uniqueness: { ... }` options hash
+wrapped across multiple lines, `scope:` as an array literal and as
+`%i[]`, and multiple models checked against one shared schema.rb in a
+single project. The CLI is exercised end-to-end against fixture project
+directories, checking text and `--json` output, multi-project-directory
+invocations, and all exit codes.

data/Gemfile

@@ -0,0 +1,3 @@
+source "https://rubygems.org"
+
+gemspec

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jay Tank
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,95 @@
+# idxfence
+
+[![Gem Version](https://img.shields.io/gem/v/idxfence.svg)](https://rubygems.org/gems/idxfence)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+Flags a Rails ActiveRecord `validates :column, uniqueness: true` (or
+`uniqueness: { scope: ... }`, or `validates_uniqueness_of`) whose column
+set has **no matching database-level unique index** in `db/schema.rb`.
+
+`uniqueness: true` only runs a `SELECT ... WHERE` check at the
+application layer, in the same request, before the `INSERT`. Under real
+concurrency, two requests can both run that `SELECT` and both see "no
+existing row" before either one's `INSERT` commits -- landing a genuine
+duplicate row despite the validation "working" in every manual test and
+every single-threaded spec run. The Rails Guides themselves document
+this exact race and recommend a matching DB-level unique index as the
+only real fix -- the AR validation is a friendly UX nicety, not a
+correctness guarantee. See [DETAILS.md](DETAILS.md) for the exact race,
+the table-name/scope-matching algorithm, and why this genuinely needs
+two passes over two different files.
+
+## Quick start
+
+```bash
+gem install idxfence
+idxfence check /path/to/rails-project
+```
+
+```
+idxfence: 1 finding(s)
+[IX001] app/models/user.rb:2 User#email -> users has no matching unique index: User validates uniqueness of :email at the application layer only -- db/schema.rb has no unique index on users(email). 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 :users, [:email], unique: true` migration. See DETAILS.md.
+```
+
+Each `<rails-project-dir>` argument must contain `app/models/` and
+`db/schema.rb`. Exits `1` if any finding, `0` otherwise -- wire it into
+CI as a pre-merge gate on the whole project.
+
+## As a library
+
+```ruby
+require "idxfence"
+
+findings, warning = Idxfence.check(project_dir: "/path/to/rails-project")
+findings.each { |f| puts "[#{f.code}] #{f.model}##{f.column} -> #{f.table} (#{f.file}:#{f.line})" }
+```
+
+## What it checks (v0.1)
+
+For every `app/models/*.rb` model whose superclass is `ApplicationRecord`
+or `ActiveRecord::Base`:
+
+1. Every `validates :column[, :column2, ...], uniqueness: true` (or
+   `uniqueness: { scope: ..., ... }`), and every
+   `validates_uniqueness_of :column[, ...][, scope: ...]` -- each column
+   named is treated as its own independent validation, matching Rails'
+   own runtime behavior.
+2. The model's table name -- `self.table_name = "..."` if the model sets
+   it explicitly, otherwise Rails' own default
+   (`demodulize.underscore.pluralize`).
+3. Cross-referenced against `db/schema.rb`'s `create_table` block for
+   that table: is there a `t.index [...], unique: true` whose column set
+   (the validated column, plus any `scope:` column(s)) matches exactly,
+   in either order?
+
+No matching unique index -> flagged. A `scope:` validation additionally
+requires the composite index (a single-column index on just the
+validated column does **not** satisfy a scoped validation -- see
+[DETAILS.md](DETAILS.md)).
+
+**Not flagged / explicitly out of scope**:
+
+- A uniqueness validation with a matching unique index already in place
+  -- that's the correct, race-safe setup.
+- A model with no uniqueness validations at all -- nothing to check.
+- `db/schema.rb` missing or unparseable -- a clear warning, not a crash
+  (nothing can be cross-referenced without it).
+
+Class boundaries, `create_table` blocks, and `validates` statements are
+found by parsing with Ruby's own `Ripper` for structure and pattern
+matching within it -- see [DETAILS.md](DETAILS.md) for exactly how, the
+full table-name/scope-matching algorithm, and its honestly documented
+limitations (irregular pluralization, case-sensitivity, functional
+indexes).
+
+## Requirements
+
+Developed and tested against Ruby 3.0.2, matching this workspace's other
+Ruby packages. No known incompatibility with newer 3.x versions. No
+Rails installation or database connection is required to run
+idxfence -- it's a pure static-source check over `app/models/*.rb` and
+`db/schema.rb`.
+
+## License
+
+MIT

data/docs/USAGE.md

@@ -0,0 +1,107 @@
+# idxfence — Usage
+
+## Library API
+
+```ruby
+require "idxfence"
+
+findings, warning = Idxfence.check(project_dir: project_dir)
+```
+
+`project_dir` — path to a Rails project root (the directory containing
+`app/` and `db/`). Model files are globbed from
+`app/models/**/*.rb`, and the schema is read from `db/schema.rb`.
+
+For callers that already have their own explicit file list (e.g. tests
+against fixtures not laid out as a full Rails project):
+
+```ruby
+findings, warning = Idxfence.check_paths(
+  model_paths: Dir.glob("app/models/**/*.rb"),
+  schema_path: "db/schema.rb"
+)
+```
+
+### Return value
+
+A two-element array: `[Array<Idxfence::Finding>, String or nil]`. The
+second element is a warning message (nil if none) — set when
+`db/schema.rb` was missing or failed to parse, in which case findings is
+always `[]` since nothing can be cross-referenced without it.
+
+Each `Finding` has:
+
+- `code` — always `"IX001"` (one rule: an AR uniqueness validation with
+  no matching DB-level unique index)
+- `model` — the model class name, e.g. `"User"`
+- `table` — the resolved table name, e.g. `"users"`
+- `column` — the validated column, e.g. `"email"`
+- `scope` — `Array<String>` of scope column(s) (`[]` for an unscoped
+  validation)
+- `file` — path to the model source file
+- `line` — line number of the `validates`/`validates_uniqueness_of` call
+- `message` — human-readable description with the fix
+- `#to_h` — plain hash of the above eight keys
+
+## CLI
+
+```bash
+idxfence check <rails-project-dir> [<rails-project-dir> ...] [--json]
+```
+
+Each `<rails-project-dir>` must contain `app/models/` and
+`db/schema.rb`. At least one is required. Multiple directories can be
+checked in one invocation (e.g. a monorepo with more than one Rails app).
+
+### Exit codes
+
+- `0` — no findings (a schema warning alone does not change the exit
+  code — check stderr/the warning line if you need to distinguish "clean"
+  from "couldn't check")
+- `1` — one or more findings
+- `2` — usage error (no paths, unknown command, bad flag)
+
+### Example
+
+```bash
+$ idxfence check .
+
+idxfence: 1 finding(s)
+[IX001] app/models/user.rb:2 User#email -> users has no matching unique index: User validates uniqueness of :email at the application layer only -- db/schema.rb has no unique index on users(email). 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 :users, [:email], unique: true` migration. See DETAILS.md.
+```
+
+### `--json`
+
+```bash
+$ idxfence check . --json
+{"findings":[{"code":"IX001","model":"User","table":"users","column":"email","scope":[],"file":"app/models/user.rb","line":2,"message":"..."}],"warning":null}
+```
+
+## What triggers a finding
+
+A model class whose superclass is exactly `ApplicationRecord` or
+`ActiveRecord::Base`, declaring:
+
+1. `validates :column[, :column2, ...], uniqueness: true` or
+   `uniqueness: { scope: ..., ... }` — each named column is its own
+   independent validation.
+2. `validates_uniqueness_of :column[, :column2, ...][, scope: ...]` —
+   same treatment.
+
+...resolved against the model's table (an explicit `self.table_name =
+"..."` if present, otherwise `demodulize.underscore.pluralize` of the
+class name), where `db/schema.rb`'s `create_table` block for that table
+has no `t.index [...], unique: true` whose column set — the validated
+column plus any `scope:` column(s), in either order — matches exactly.
+
+`scope:` is recognized as a bare symbol (`scope: :account_id`), an array
+(`scope: [:account_id, :region]`), or `%i[]` (`scope: %i[account_id
+region]`).
+
+Not flagged: a validation with a matching unique index already in place,
+a model with no uniqueness validations at all. `db/schema.rb` missing or
+unparseable produces a warning, not a crash, and no findings (nothing to
+cross-reference against). See [DETAILS.md](../DETAILS.md) for the full
+table-name and scope-matching algorithm and every documented limitation
+(irregular pluralization, case-sensitivity, functional/expression
+indexes, STI).

data/examples/app/models/membership.rb

@@ -0,0 +1,8 @@
+# Clean, by contrast: this scoped uniqueness validation IS backed by a
+# matching composite unique index in db/schema.rb -- see the
+# `t.index ["account_id", "email"], unique: true` line on the
+# "memberships" table. idxfence does not flag this one.
+class Membership < ApplicationRecord
+  validates :email, uniqueness: { scope: :account_id, case_sensitive: false }
+  belongs_to :account
+end

data/examples/app/models/user.rb

@@ -0,0 +1,11 @@
+# Trips IX001: a completely ordinary-looking Rails model.
+# validates :email, uniqueness: true only runs a SELECT ... WHERE check
+# at the application layer, before the INSERT -- it looks like it
+# guarantees no two users can ever share an email, but db/schema.rb (see
+# db/schema.rb next to this file) has no unique index on users.email at
+# all. Two signups for the same address, a few milliseconds apart, can
+# both pass this validation's SELECT before either INSERT commits.
+class User < ApplicationRecord
+  validates :email, presence: true, uniqueness: true
+  validates :password, length: { minimum: 8 }
+end

data/examples/db/schema.rb

@@ -0,0 +1,26 @@
+# This is what idxfence cross-references app/models/*.rb against. Note:
+#   - "users" has no unique index on email at all -> User's
+#     `uniqueness: true` on :email gets flagged (IX001).
+#   - "memberships" DOES have a matching composite unique index on
+#     [account_id, email] -> Membership's scoped uniqueness validation
+#     is NOT flagged.
+ActiveRecord::Schema[7.1].define(version: 2026_09_01_000000) do
+  create_table "accounts", force: :cascade do |t|
+    t.string "name"
+    t.timestamps
+  end
+
+  create_table "users", force: :cascade do |t|
+    t.string "email"
+    t.string "password_digest"
+    t.timestamps
+  end
+
+  create_table "memberships", force: :cascade do |t|
+    t.bigint "account_id", null: false
+    t.string "email"
+    t.timestamps
+    t.index ["account_id", "email"], name: "index_memberships_on_account_id_and_email", unique: true
+    t.index ["account_id"], name: "index_memberships_on_account_id"
+  end
+end

data/exe/idxfence

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "idxfence"
+require "idxfence/cli"
+
+exit Idxfence::CLI.run(ARGV)

data/idxfence.gemspec

@@ -0,0 +1,39 @@
+require_relative "lib/idxfence/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "idxfence"
+  spec.version       = Idxfence::VERSION
+  spec.authors       = ["Jay"]
+  spec.summary       = "Flags Rails ActiveRecord uniqueness: true validations with no matching DB-level unique index in db/schema.rb."
+  spec.description   = <<~DESC
+    idxfence cross-references every `validates :column, uniqueness: true`
+    / `uniqueness: { scope: ... }` / `validates_uniqueness_of` declaration
+    in app/models/*.rb against db/schema.rb's create_table blocks, and
+    flags any whose column set (including scope columns) has no matching
+    `t.index [...], unique: true`. An ActiveRecord uniqueness validation
+    only performs a SELECT ... WHERE check at the application layer
+    before an INSERT -- under real concurrency, two requests can both
+    pass that check before either commits, landing a genuine duplicate
+    row despite the validation "working." Rails Guides themselves
+    document this exact race and recommend a matching DB-level unique
+    index as the only real fix; plenty of real apps ship with only the
+    AR-level check.
+  DESC
+  spec.homepage      = "https://github.com/jay-tank/idxfence"
+  spec.license       = "MIT"
+  spec.required_ruby_version = ">= 3.0.0"
+
+  spec.metadata["homepage_uri"]    = spec.homepage
+  spec.metadata["source_code_uri"] = spec.homepage
+
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      f.match(%r{\A(?:test|spec|features)/}) || f.match(%r{\A\.github/})
+    end
+  end
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "rspec", "~> 3.13"
+end