huginn_datatable 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 05de880382d0477bad2668f9f64ae7cc9d3bbbc78f71c6e359dfba0ccf9cc43b
+  data.tar.gz: 7d8053d071e2bc52b09463af4a8b6ed7c5b024afd5f9fa5b3f6e39f30cbb5f04
+SHA512:
+  metadata.gz: 20676dc384afff5cb64a1b6289f13207fdc1cde8bc549659ce876408eb435efb9668d2aff5064968bf7cc3d21e71c8e801603ba8737d5c0cc034c9f368788b9e
+  data.tar.gz: 36b11ac27abd80641faa22db4e44feb865881d27f5dd3d8c2b6cb9df1b8dcef10a24b22271021c1e12603481da18a7e17eef4201983586c0c2d2851cf9a86bd6

data/CHANGELOG.md

@@ -0,0 +1,33 @@
+## Changelog
+
+### Unreleased
+
+- Runtime dependency on Pagy declared in the gemspec (`pagy >= 6`) — consumers install it automatically (datatable pagination is not test-only anymore).
+- Supported Rails floor bumped to **7.1** (`>= 7.1, < 9`); Ruby `>= 3.0` without an upper bound (Rails 8 + Ruby 4 supported).
+- Appraisals now cover **Rails 7.1 / 7.2 / 8.0** (was 6.1/7.0/7.1) with generated `gemfiles/*.gemfile`; CI matrix runs every Rails over supported Rubies (3.0 up to 4.0, including Rails 8 on Ruby 4.0).
+- `allowed_paths:` allowlist: associações que filtros/orders/range podem usar.
+  - **Deny-all por padrão** — sem `allowed_paths:`, apenas colunas da própria tabela.
+  - Accepts Rails shapes (Symbol/String/Hash/Array); table names map to the reflection.
+  - Ordenação por associação via subquery escalar correlacionada determinística (`ORDER BY (SELECT … LIMIT 1)`); filtros/range via `pk IN (SELECT DISTINCT pk …)`.
+  - `allowed_paths` also gates `huginn_attributes` association aliases.
+- `huginn_attributes` mapping: public API aliases for datatable fields, hiding the database schema.
+  - Strict by default — fields outside the mapping are silently rejected.
+  - Alias targets accept association names (`company.name`) or table names (`companies.name`).
+  - `huginn_attributes({ ... }, strict: false)` for a translation-only mapping; plain/reflected columns remain the fallback when no mapping is set.
+
+### 0.1.0 — 2026-08-05
+
+- Initial release of the `Huginn` gem.
+- `Huginn::Datatable` concern: two-phase (filter → count/paginate/preload) datatable execution.
+  - `left_joins` for filtering/ordering; values are never string-interpolated.
+  - Lean `COUNT(DISTINCT pk)` via subquery.
+  - `preload` applied *only* to the final paginated subset.
+  - DISTINCT applied only when a joined association multiplies rows.
+- `Huginn::FilterNormalizer`: fluid, tolerant normalization of filter payloads (Parameters / Hash / Array / pairs).
+- `Huginn::Datatable::Validator`: validation + Arel resolution of plain and association-scoped columns.
+- `Huginn::Datatable::Paginator`: enxuto count and pagination (Pagy), `preload` isolation.
+- `Huginn::Searchable`: tolerant full-text search over PostgreSQL.
+  - `:pg_trgm` (similarity OR unaccent+ILIKE), `:unaccent`, `:simple` strategies, runtime degrade when extensions missing.
+  - Default: all `:string`/`:text` columns; overridable via `searchable_columns`.
+  - Association-scoped columns reached through `left_joins`.
+- Railtie auto-includes both concerns into `ActiveRecord::Base` (configurable), mirrors the `muninn` gem layout (version, configuration, Appraisals, CI matrix, `spec/dummy`).

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kayky Marcelo
+
+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,219 @@
+<h1 align="center">Huginn</h1>
+
+<p align="center">
+  <em>Performant, elegant ActiveRecord datatables and tolerant search.</em><br>
+  Huginn is the raven of Odin that represents thought and remembrance — the mate of Muninn.
+</p>
+
+<p align="center">
+  🇺🇸 English · <a href="./README.pt-BR.md">🇧🇷 Português</a>
+</p>
+
+Huginn is a lightweight query layer for Rails that turns a raw datatable request into a **lean count, a paginated subset and one preload** — instead of a massive JOIN materialized in memory. It also ships a PostgreSQL fuzzy-search builder (`pg_trgm` similarity with `unaccent` and `ILIKE` fallback) that is tolerant to typos and accents.
+
+## Highlights
+
+- **Two-phase execution** — association filters/orders/range become reflection-secured subqueries, then a lean count and `preload` **only on the paginated subset**.
+- **Lean counts** — `COUNT(DISTINCT pk)` through a stripped relation; no JOIN materialization.
+- **SQL injection safe ordering/filtering** — every column reference is resolved through Arel reflection, never string-interpolated.
+- **Accent/typo tolerant search** — `pg_trgm` similarity OR `unaccent+ILIKE`, with a configurable fallback chain.
+- **Rails conventions** — works with `ActionController::Parameters`, Railtie auto-includes both concerns (toggleable), zero boilerplate.
+
+## Development
+
+The root `Gemfile` keeps only the tooling (rspec, appraisal, pry) — each supported Rails series lives in its own Appraisal. Use these to run the suite:
+
+```
+bundle install
+bundle exec appraisal install        # generates gemfiles/*.gemfile + resolves
+bundle exec appraisal rspec          # runs the full matrix (Rails 7.1/7.2/8.0)
+bundle exec appraisal rails-8.0 rspec   # or a single series
+bundle exec rake matrix              # alias for the full matrix
+```
+
+A bare `bundle exec rspec` needs an active environment: `export BUNDLE_GEMFILE=gemfiles/rails_8.0.gemfile`.
+
+## Supported versions
+
+| Component | Range |
+|---|---|
+| Ruby | `>= 3.0` (no upper bound — Rails 8 + Ruby 4 supported) |
+| Rails | `>= 7.1, < 9` |
+| Pagy | `>= 6` (runtime dependency, installed automatically) |
+| PostgreSQL | pg_trgm / unaccent / ILIKE search; degrades gracefully without them |
+
+The suite is verified against **Rails 7.1, 7.2 and 8.0** across supported Rubies via [Appraisal](https://github.com/thoughtbot/appraisal). Run the full matrix locally:
+
+```
+bundle exec appraisal install
+bundle exec appraisal rspec
+```
+
+The `gemfiles/*.gemfile` are generated by Appraisal (committed); their `.lock` files are not — each CI cell resolves for its own Ruby/Rails pair.
+
+## Installation
+
+```ruby
+gem "huginn"
+```
+
+## Configuration
+
+```ruby
+# config/initializers/huginn.rb
+Huginn.configure do |config|
+  # :pg_trgm  (recommended) — trigram similarity OR unaccent+ILIKE
+  # :unaccent               — unaccent + ILIKE only
+  # :simple                 — plain LIKE
+  config.search_strategy = :pg_trgm
+
+  config.fuzzy_threshold = 0.3   # similarity() cutoff used by :pg_trgm
+  config.pagy_items = 10         # default page size
+  config.pagy_max_items = 500    # hard cap for per_page
+end
+```
+
+## Railtie (automatic include)
+
+By default the Railtie includes `Huginn::Datatable` and `Huginn::Searchable` into every `ActiveRecord::Base` model. You do **not** need `include` statements unless you opt in selectively:
+
+```ruby
+Huginn.configure { |c| c.auto_include_datatable = false; c.auto_include_searchable = false }
+```
+
+## Usage — datatable
+
+```ruby
+class Plano < ApplicationRecord
+  # Datatable + Searchable are auto-included via Railtie
+end
+```
+
+```ruby
+result = Plano.datatable(
+  params,
+  allowed_paths: [:grupo, { operadora: [:pessoa] }], # associations filters/orders may use
+  includes: [{ operadora: { pessoa: [:endereco, :contatos] } }] # preloaded on the page only
+)
+
+result[:total_count] # Integer (lean COUNT DISTINCT pk)
+result[:data]        # ActiveRecord::Relation (paged + preloaded)
+```
+
+Supported params:
+
+| Key | Behavior |
+|---|---|
+| `page`, `per_page` | Pagination (clamped to `pagy_max_items`) |
+| `search` | Delegates to `Huginn::Searchable.search` |
+| `filters` | Hash / Array of hashes / pairs -> exact or `IN` conditions (`"col" => "null"` → `IS NULL`) |
+| `range_data` | `{ "created_at" => ["2024-01-01", "2024-12-31"] }` — date or numeric ranges |
+| `orders` | `[{ "pessoa.nome" => "desc" }]` — plain or association-scoped columns |
+
+### Scoped ordering / filtering
+
+Any `column` **or** `association.column` reference is validated and mapped to its real reflected table:
+
+```ruby
+Plano.datatable({ orders: [{ "operadora.pessoa.nome" => "asc" }] }, allowed_paths: [{ operadora: :pessoa }])
+```
+
+> Association filters/range and ordering use reflection-resolved subqueries (see the "allowlist of associations" section below). The main relation stays singular and the count is `COUNT(DISTINCT pk)`.
+
+## Association allowlist (`allowed_paths`)
+
+To protect the schema and keep the query lean, the `datatable` does not materialize `left_joins` to filter/order by associations. Instead:
+
+- **Filters/ranges** over association columns become `pk IN (SELECT DISTINCT pk …)` subqueries — the main relation is never multiplied;
+- **Ordering** by an association column uses a *correlated scalar subquery* (`ORDER BY (SELECT … ORDER BY col ASC LIMIT 1)`), which is deterministic even for `has_many` (smallest value);
+- **Only authorized associations** may be referenced. Pass `allowed_paths:` with the associations the caller may use in the query:
+
+```ruby
+result = Plano.datatable(
+  params,
+  allowed_paths: [:grupo, { operadora: :pessoa }],  # associations filters/orders may use
+  includes:      [{ operadora: { pessoa: [:endereco, :contatos] } }] # preload only the page
+)
+```
+
+- **Deny-all by default**: without `allowed_paths:`, no association is authorized for filtering/ordering — only columns of the table itself.
+- `allowed_paths:` accepts the same shapes Rails knows (`:symbol`, `"string"`, nested Hash, mixed Array). Table names (`"companies"`) are recognized as the matching association (`:company`).
+- `includes:` stays independent of `allowed_paths:` — it only controls the **preload** of the paginated page.
+
+## Field aliases & schema protection
+
+Public APIs should not expose the database schema. Declare a mapping of **public names** to real columns/tables with `huginn_attributes`:
+
+```ruby
+class User < ApplicationRecord
+  # Public API name -> real column/table (association name or table name)
+  huginn_attributes(
+    name:         "users.name",
+    email:        "users.email",
+    created_at:   "users.created_at",
+    company_name: "companies.name"   # association column, resolved via subquery
+  )
+end
+```
+
+- Callers then filter/order/range only by the aliases: `{ filters: { company_name: "Acme Corp" } }`, `{ orders: [{ company_name: "asc" }] }`.
+- **Strict by default**: fields outside the mapping are silently rejected (they never reach SQL and are never answered). The schema stays hidden from API consumers.
+- Scoped aliases (`companies.name`) resolve through the association **only if it is authorized in `allowed_paths:`** (the same allowlist applies to aliases).
+- Without `huginn_attributes`, the model **falls back** to plain/reflected columns (`name`, `company.name`).
+- Without `allowed_paths:`, association-scoped aliases are **denied**; only plain columns are usable.
+- `huginn_attributes({ ... }, strict: false)` keeps alias translation but also accepts raw columns.
+
+## Usage — search
+
+```ruby
+# Default: searches every :string / :text column of the model.
+Person.search("kayky")            # typo/accent tolerant, case-insensitive
+
+# Override which columns (including through associations) are searched:
+class Person < ApplicationRecord
+  searchable_columns :name, company: [:name, :cnpj]
+end
+
+Person.search("globex")                            # matches company.name via a left_join
+Person.search("kayky", distinct: false)            # disable the implicit DISTINCT
+```
+
+`Huginn::Datatable` reuses `Huginn::Searchable.search` automatically when the model responds to `search`.
+
+## Query efficiency
+
+```
+phase 1  build the relation          subqueries (pk IN … / ORDER BY (SELECT …)) + search + filters + order   (no data in memory)
+phase 2  count                       SELECT COUNT(DISTINCT "<pk column>") ... (subquery, pk-indexed)
+          paginate                   offset / limit
+          preload                    SELECT ... WHERE id IN (subset)        (2nd lightweight query)
+```
+
+For a `Plano` datatable with deep `includes:`, this is exactly **2 extra queries** on the small page instead of one enormous JOIN.
+
+## Architecture
+
+```
+lib/huginn.rb                       entry, Huginn.configure, Huginn.instrument
+lib/huginn/configuration.rb         search_strategy, fuzzy_threshold, pagy_*
+lib/huginn/railtie.rb               auto-includes concerns into ActiveRecord
+lib/huginn/datatable.rb             Huginn::Datatable (aggregator)
+lib/huginn/datatable/datatable.rb   the datatable Concern
+lib/huginn/datatable/validator.rb   column/association validation + Arel resolution
+lib/huginn/datatable/association_path.rb   resolution of association chains + correlated subqueries
+lib/huginn/datatable/allowed_paths.rb      `allowed_paths:` allowlist expansion/authorization
+lib/huginn/datatable/filter_normalizer.rb  functional param normalization
+lib/huginn/datatable/paginator.rb    lean count, pagination, isolated preload
+lib/huginn/searchable.rb            Huginn::Searchable (aggregator)
+lib/huginn/searchable/searchable.rb the search Concern + DSL
+lib/huginn/searchable/query.rb      tolerant search builder (joins + OR)
+lib/huginn/searchable/fuzzy.rb      pg_trgm / unaccent / simple predicates
+```
+
+## Instrumentation
+
+`Huginn.instrument` wraps `ActiveSupport::Notifications` events under the `huginn` namespace (e.g. `datatable.call.huginn`). Subscribe with `ActiveSupport::Notifications.subscribe(/\.huginn/)`.
+
+## License
+
+MIT

data/README.pt-BR.md

@@ -0,0 +1,219 @@
+<h1 align="center">Huginn</h1>
+
+<p align="center">
+  <em>Datatables ActiveRecord performantes e busca tolerante a erros.</em><br>
+  Huginn é o corvo de Odin que representa o pensamento e a memória — o companheiro de Muninn.
+</p>
+
+<p align="center">
+  <a href="./README.md">🇺🇸 English</a> · 🇧🇷 Português
+</p>
+
+O Huginn é uma camada de consulta leve para Rails que transforma uma requisição de datatable bruta em um **count enxuto, um subconjunto paginado e um único preload** — em vez de um JOIN enorme materializado em memória. Também traz um construtor de busca *fuzzy* para PostgreSQL (similaridade `pg_trgm` com `unaccent` e fallback `ILIKE`) tolerante a erros de digitação e acentuação.
+
+## Destaques
+
+- **Execução em duas fases** — filtros/orders/ranges de associação se tornam subqueries resolvidas por reflexão, e o `preload` é feito **somente no subconjunto paginado**.
+- **Counts enxutos** — `COUNT(DISTINCT pk)` através de uma relation restrita, sem materialização de JOINs.
+- **Ordenação/filtro seguros contra SQL injection** — toda referência de coluna é resolvida via reflexão do Arel, nunca interpolada como string.
+- **Busca tolerante a acentos/typos** — similaridade `pg_trgm` OU `unaccent+ILIKE`, com cadeia de fallback configurável.
+- **Convenções do Rails** — funciona com `ActionController::Parameters`, Railtie inclui ambos os concerns automaticamente (desligável), zero boilerplate.
+
+## Desenvolvimento
+
+O `Gemfile` raiz mantém apenas as ferramentas (rspec, appraisal, pry) — cada série suportada do Rails vive num Appraisal próprio. Para rodar a suíte:
+
+```
+bundle install
+bundle exec appraisal install        # gera os gemfiles/*.gemfile + resolve
+bundle exec appraisal rspec          # roda a matrix completa (Rails 7.1/7.2/8.0)
+bundle exec appraisal rails-8.0 rspec   # ou uma série isolada
+bundle exec rake matrix              # atalho para a matrix completa
+```
+
+Um `bundle exec rspec` isolado precisa de ambiente ativo: `export BUNDLE_GEMFILE=gemfiles/rails_8.0.gemfile`.
+
+## Versões suportadas
+
+| Componente | Escopo |
+|---|---|
+| Ruby | `>= 3.0` (sem teto — Rails 8 + Ruby 4 suportados) |
+| Rails | `>= 7.1, < 9` |
+| Pagy | `>= 6` (dependência runtime, instalada automaticamente) |
+| PostgreSQL | busca pg_trgm / unaccent / ILIKE; degrada sem eles na ausência |
+
+A suíte é verificada contra **Rails 7.1, 7.2 e 8.0** em várias Rubies suportadas via [Appraisal](https://github.com/thoughtbot/appraisal). Rode a matrix completa localmente:
+
+```
+bundle exec appraisal install
+bundle exec appraisal rspec
+```
+
+Os `gemfiles/*.gemfile` são gerados pelo Appraisal (commitados); os arquivos `.lock` deles **não** são — cada célula da CI resolve pelo seu par Ruby/Rails.
+
+## Instalação
+
+```ruby
+gem "huginn"
+```
+
+## Configuração
+
+```ruby
+# config/initializers/huginn.rb
+Huginn.configure do |config|
+  # :pg_trgm  (recomendado) — similaridade trigram OU unaccent+ILIKE
+  # :unaccent               — somente unaccent + ILIKE
+  # :simple                 — LIKE simples
+  config.search_strategy = :pg_trgm
+
+  config.fuzzy_threshold = 0.3   # cutoff de similarity() usado por :pg_trgm
+  config.pagy_items = 10         # tamanho de página padrão
+  config.pagy_max_items = 500    # teto máximo de per_page
+end
+```
+
+## Railtie (include automático)
+
+Por padrão, o Railtie inclui `Huginn::Datatable` e `Huginn::Searchable` em toda `ActiveRecord::Base`. Você **não** precisa de `include`, a menos que opte seletivamente:
+
+```ruby
+Huginn.configure { |c| c.auto_include_datatable = false; c.auto_include_searchable = false }
+```
+
+## Uso — datatable
+
+```ruby
+class Plano < ApplicationRecord
+  # Datatable + Searchable são incluídos automaticamente via Railtie
+end
+```
+
+```ruby
+result = Plano.datatable(
+  params,
+  allowed_paths: [:grupo, { operadora: [:pessoa] }], # associações que filtros/orders podem usar
+  includes: [{ operadora: { pessoa: [:endereco, :contatos] } }] # preload somente na página
+)
+
+result[:total_count] # Integer (count enxuto COUNT DISTINCT pk)
+result[:data]        # ActiveRecord::Relation (paginada + preloaded)
+```
+
+Parâmetros suportados:
+
+| Parâmetro | Comportamento |
+|---|---|
+| `page`, `per_page` | Paginação (limitada a `pagy_max_items`) |
+| `search` | Delega para `Huginn::Searchable.search` |
+| `filters` | Hash / Array de hashes / pares -> condições exatas ou `IN` (`"col" => "null"` → `IS NULL`) |
+| `range_data` | `{ "created_at" => ["2024-01-01", "2024-12-31"] }` — ranges de datas ou numéricos |
+| `orders` | `[{ "pessoa.nome" => "desc" }]` — colunas simples ou de associação |
+
+### Ordenação/filtro com associação
+
+Qualquer referência `column` **ou** `associacao.column` é validada e mapeada para a tabela refletida real:
+
+```ruby
+Plano.datatable({ orders: [{ "operadora.pessoa.nome" => "asc" }] }, allowed_paths: [{ operadora: :pessoa }])
+```
+
+> Filtros/ranges e order de associação usam subqueries resolvidas por reflexão (veja a seção "Allowlist de associações" abaixo). A relation principal permanece única e o count é `COUNT(DISTINCT pk)`.
+
+## Allowlist de associações (`allowed_paths`)
+
+Para proteger o schema e manter a consulta enxuta, o `datatable` não materializa `left_joins` para filtrar/ordenar por associações. Em vez disso:
+
+- **Filtros/ranges** de colunas de associação viram subqueries `pk IN (SELECT DISTINCT pk …)` — a relation principal nunca é multiplicada;
+- **Ordenação** por coluna de associação usa uma *subquery escalar correlacionada* (`ORDER BY (SELECT … ORDER BY col ASC LIMIT 1)`), determinística mesmo para `has_many` (menor valor);
+- **Apenas as associações autorizadas** podem ser referenciadas. Passe `allowed_paths:` com as associações que o chamador pode usar na query:
+
+```ruby
+result = Plano.datatable(
+  params,
+  allowed_paths: [:grupo, { operadora: :pessoa }],  # associações que filtros/orders podem usar
+  includes:      [{ operadora: { pessoa: [:endereco, :contatos] } }] # preload somente da página
+)
+```
+
+- **Deny-all por padrão**: sem `allowed_paths:`, nenhuma associação é autorizada para filtro/ordem — apenas colunas da própria tabela.
+- `allowed_paths:` aceita os mesmos formatos do Rails (`:symbol`, `"string"`, Hash aninhado, Array misto). Nomes de tabela (`"companies"`) são reconhecidos como a associação correspondente (`:company`).
+- `includes:` continua independente do `allowed_paths:`: ele só controla o **preload** dos dados na página paginada.
+
+## Aliases de campos & proteção do schema
+
+APIs públicas não deveriam expor o schema do banco. Declare um mapeamento de **nomes públicos** para colunas/tabelas reais com `huginn_attributes`:
+
+```ruby
+class User < ApplicationRecord
+  # Nome de API pública -> coluna/tabela real (nome da associação ou nome da tabela)
+  huginn_attributes(
+    name:         "users.name",
+    email:        "users.email",
+    created_at:   "users.created_at",
+    company_name: "companies.name"   # coluna de associação, resolvida via subquery
+  )
+end
+```
+
+- Os chamadores filtram/ordenam/rangeiam apenas pelos aliases: `{ filters: { company_name: "Acme Corp" } }`, `{ orders: [{ company_name: "asc" }] }`.
+- **Estrito por padrão**: campos fora do mapeamento são silenciosamente rejeitados (nunca chegam ao SQL e nunca são respondidos). O schema permanece oculto para consumidores da API.
+- Aliases de associação (`companies.name`) resolvem pela associação **somente se ela estiver autorizada em `allowed_paths:`** (a mesma allowlist se aplica aos aliases).
+- Sem `huginn_attributes`, o modelo **cai de volta** para colunas simples/refletidas (`name`, `company.name`).
+- Sem `allowed_paths:`, aliases de associação são **negados**; apenas colunas simples podem ser usadas.
+- `huginn_attributes({ ... }, strict: false)` mantém a tradução de aliases, mas também aceita colunas cruas.
+
+## Uso — search
+
+```ruby
+# Padrão: busca em toda coluna :string / :text do modelo.
+Person.search("kayky")            # tolerante a typos e acentos, sem distinção de caixa
+
+# Sobrescreva quais colunas pesquisar (inclusive através de associações):
+class Person < ApplicationRecord
+  searchable_columns :name, company: [:name, :cnpj]
+end
+
+Person.search("globex")                            # encontra company.name via left_join
+Person.search("kayky", distinct: false)            # desativa o DISTINCT implícito
+```
+
+`Huginn::Datatable` reutiliza `Huginn::Searchable.search` automaticamente quando o modelo responde a `search`.
+
+## Eficiência da query
+
+```
+fase 1  construir a relation      subqueries (pk IN … / ORDER BY (SELECT …)) + search + filters + order   (sem dados em memória)
+fase 2  count                     SELECT COUNT(DISTINCT "<pk>") ... (subquery, indexada por pk)
+        paginate                  offset / limit
+        preload                   SELECT ... WHERE id IN (subset)        (2ª query leve)
+```
+
+Para um datatable de `Plano` com `includes:` profundos, isso são exatamente **2 queries extras** na página pequena em vez de um JOIN enorme.
+
+## Arquitetura
+
+```
+lib/huginn.rb                       entry, Huginn.configure, Huginn.instrument
+lib/huginn/configuration.rb         search_strategy, fuzzy_threshold, pagy_*
+lib/huginn/railtie.rb               auto-inclui os concerns no ActiveRecord
+lib/huginn/datatable.rb             Huginn::Datatable (agregador)
+lib/huginn/datatable/datatable.rb   o Concern do datatable
+lib/huginn/datatable/validator.rb   validação de coluna/associação + resolução Arel
+lib/huginn/datatable/association_path.rb   resolução de cadeias de associação + subqueries
+lib/huginn/datatable/allowed_paths.rb      expansão/autorização da allowlist `allowed_paths:`
+lib/huginn/datatable/filter_normalizer.rb  normalização funcional de params
+lib/huginn/datatable/paginator.rb  count enxuto, paginação, preload isolado
+lib/huginn/searchable.rb            Huginn::Searchable (agregador)
+lib/huginn/searchable/searchable.rb o Concern do search + DSL
+lib/huginn/searchable/query.rb      construtor de busca tolerante (joins + OR)
+lib/huginn/searchable/fuzzy.rb      predicados pg_trgm / unaccent / simple
+```
+
+## Instrumentação
+
+`Huginn.instrument` envolve eventos de `ActiveSupport::Notifications` no namespace `huginn` (ex.: `datatable.call.huginn`). Assine com `ActiveSupport::Notifications.subscribe(/\.huginn/)`.
+
+## Licença
+
+MIT

data/lib/huginn/configuration.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Huginn
+  class Configuration
+    attr_accessor :fuzzy_threshold, :pagy_items, :pagy_max_items
+    attr_writer :search_strategy, :auto_include_datatable, :auto_include_searchable
+
+    def initialize
+      @fuzzy_threshold = 0.3
+      @pagy_items = 10
+      @pagy_max_items = 500
+      @search_strategy = :pg_trgm
+      @auto_include_datatable = true
+      @auto_include_searchable = true
+    end
+
+    # :pg_trgm  -> similarity(trgm) OR unaccent+ILIKE (recommended)
+    # :unaccent -> unaccent + ILIKE only
+    # :simple   -> plain LIKE
+    def search_strategy
+      @search_strategy.to_sym
+    end
+
+    def auto_include_datatable?
+      @auto_include_datatable
+    end
+
+    def auto_include_searchable?
+      @auto_include_searchable
+    end
+  end
+end

data/lib/huginn/datatable/allowed_paths.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+module Huginn
+  module Datatable
+    # Expands the `allowed_paths:` allowlist into its canonical association
+    # chains and answers whether a given chain is authorized.
+    #
+    # Accepts the same shapes Rails knows: a Symbol, a String, a Hash of
+    # nested associations, or an Array mixing those — e.g.
+    #
+    #   allowed_paths: [:company, { company: :people }, "products"]
+    #
+    # Every path is canonicalized through the reflection so that table names
+    # and public aliases map to the association name the querier actually
+    # walks.
+    class AllowedPaths
+      def self.call(model, spec)
+        new(model, spec)
+      end
+
+      def initialize(model, spec)
+        @model = model
+        @allowed = expand(spec)
+      end
+
+      def allow(reference_or_spec)
+        self.class.call(@model, reference_or_spec)
+      end
+
+      # Authorizes an association chain produced by a huginn_attributes alias
+      # (canonicalized), even when the raw allowlist does not mention it.
+      def include_path(path)
+        @allowed << canonicalize_path(path)
+      end
+
+      # Canonical association-name path for a Validator/association Path.
+      def include?(path)
+        return false if path.blank?
+
+        canonical = canonicalize_path(path)
+        @allowed.include?(canonical)
+      end
+
+      def any?
+        @allowed.any?
+      end
+
+      def to_a
+        @allowed.dup
+      end
+
+      private
+
+      attr_reader :model
+
+      def expand(spec)
+        paths = case spec
+        when nil then []
+        when Hash then expand_hash(spec)
+        else Array(spec).flat_map { |node| expand_hash(node) }
+        end
+        paths.map { |path| canonicalize_path(path) }.uniq
+      end
+
+      def expand_hash(node, prefix = [])
+        case node
+        when Symbol, String
+          chain = [*prefix, node.to_s]
+          [*top_level_paths(chain), chain]
+        when Array
+          node.flat_map { |child| expand_hash(child, prefix) }
+        when Hash
+          node.flat_map do |assoc, child|
+            current = [*prefix, assoc.to_s]
+            [current] + expand_hash(child, current)
+          end
+        else
+          []
+        end
+      end
+
+      # A bare association in the allowlist also authorizes the "table_name
+      # of that association" reference used by scoped columns, e.g. allowing
+      # `:company` also allows `companies.name` columns.
+      def top_level_paths(chain)
+        first = chain.first
+        assoc = model.reflect_on_association(first.to_sym)
+        return [] unless assoc && chain.size == 1
+
+        [[assoc.klass.table_name]]
+      end
+
+      # Normalizes a path of names (association/table/alias) into the
+      # canonical list of reflection names the datatable can walk.
+      def canonicalize_path(names)
+        klass = model
+        paths = []
+
+        names.each_with_index do |segment, index|
+          reflection = klass.reflect_on_association(segment.to_sym)
+          reflection ||= index.zero? ? table_reflection(klass, segment) : nil
+
+          if reflection
+            paths << reflection.name.to_s
+            klass = reflection.klass
+          elsif index.zero? && (table_klass = klass_for_table(segment))
+            paths << table_klass.table_name
+            klass = table_klass
+          else
+            paths << segment.to_s
+          end
+        end
+
+        paths
+      end
+
+      def table_reflection(klass, name)
+        klass.reflect_on_all_associations.find { |ref| ref.klass == klass_for_table(name) }
+      end
+
+      def klass_for_table(name)
+        table = name.singularize.camelize.constantize
+        table < ActiveRecord::Base ? table : nil
+      rescue NameError
+        nil
+      end
+    end
+  end
+end