lighthouse-graphql 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: db5eca820107c7975f19338d455cae4a2bfff8b76213035785ed66788ae93978
+  data.tar.gz: 3381c5c9242afae11d45e843d14dcdd7cd90d5b6b593fd69d33e41249745a5a8
+SHA512:
+  metadata.gz: b65cf99a77c8ceeb78656618deb4619d70205bb6bb1dc8b45f16939c34429b4dce17f16fbe554de8978fee381a2aa39d5649a75326fcd6418e10663ef4f5222d
+  data.tar.gz: 47af9818c91027cde136923d4253a1e64cc969e8f8a0aaf7f1fd61332cbd32c982354a528c15cb5467767440439b7df4d8ede19e9d6b9a607531afab743fa7f4

data/CHANGELOG.md

@@ -0,0 +1,47 @@
+# Changelog
+
+All notable changes to `lighthouse-graphql` are documented here. The format is
+based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and this
+project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-09-23
+
+First release on RubyGems. Everything below is what the gem ships with; the library
+had been running inside a private monorepo as a path gem before being extracted.
+
+### Added
+
+- Registry-driven directive dispatch (`Lighthouse::DirectiveRegistry`): adding a
+  directive is "write one class and register it" — no edits to the generator.
+- Directive contracts (`Lighthouse::Contracts::*`) mirroring PHP Lighthouse's
+  interfaces: `FieldResolver`, `FieldMiddleware`, `FieldManipulator`,
+  `ArgManipulator`, `ArgBuilder`.
+- Read directives: `@all`, `@find`, `@first`, `@paginate`, `@count`,
+  `@aggregate`, `@hasMany`, `@hasOne`, `@belongsTo`, `@belongsToMany`,
+  `@field`, `@rename`, `@auth`, `@builder`, `@orderBy`, and the argument
+  filters `@eq`, `@neq`, `@in`, `@notIn`, `@like`, `@where`, plus
+  `@whereConditions` / `@whereHasConditions`.
+- `@method(name:)` — resolve a field by calling a method on the parent object
+  (PHP-parity); removes one-line "call a method" resolvers.
+- Authorization directives `@guard` (require authentication) and `@can`
+  (policy-based authorization, Pundit by default) with configurable
+  `authenticated_user` / `policy_user` / `authorizer` seams — declare auth in
+  the schema instead of in resolvers.
+- `BuilderApplier` / argument builders now re-raise `GraphQL::ExecutionError`
+  instead of swallowing it, so authorization/scoping guards in a builder cannot
+  be silently bypassed.
+- Central naming module (`Lighthouse::Support::Naming`): one rule mapping GraphQL
+  camelCase to Rails snake_case attributes/columns, with `@rename` as the
+  explicit override.
+- Programmatic directive SDL: registered directives contribute their own
+  `directive @name(...) on ...` definitions, so apps need not hand-declare them.
+- Apollo Federation entity binding: `@key`/`@extends`/`@shareable`/
+  `@inaccessible` and `resolve_reference`, with a default model-lookup fallback
+  for direct-model entities and a `ReferenceResolver` registry for custom ones.
+- Config-driven extension seams: `Lighthouse.configure`, `resolver_namespaces`,
+  `on_error`, and `DirectiveRegistry.register` for app-defined directives.
+
+[Unreleased]: https://github.com/Vaz-Innovation/lighthouse-graphql/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/Vaz-Innovation/lighthouse-graphql/releases/tag/v0.1.0

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vaz Innovation
+
+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,134 @@
+# Lighthouse for Ruby (`lighthouse-graphql`)
+
+**SDL-first, directive-driven GraphQL for Ruby on Rails.**
+
+Lighthouse lets you build a GraphQL API for your Rails app primarily through your
+**schema** (SDL) and a set of server-side **directives** — `@all`, `@find`,
+`@paginate`, `@hasMany`, `@belongsTo`, `@whereConditions`, `@orderBy`, `@field`,
+`@auth` and more — instead of hand-writing a resolver for every field. It is a
+Ruby adaptation of the PHP [Lighthouse](https://lighthouse-php.com) library,
+built on top of [graphql-ruby](https://graphql-ruby.org), with first-class
+**Apollo Federation** support so a Rails service can act as a subgraph.
+
+```graphql
+type Query {
+  users: [User!]! @all
+  user(id: ID! @eq): User @find
+}
+
+type User {
+  id: ID!
+  customAttributes: String        # resolves to user.custom_attributes automatically
+  posts: [Post!]! @hasMany        # batched via a Dataloader
+}
+```
+
+That's the whole resolver layer for those fields. No Ruby classes required.
+
+---
+
+## Why Lighthouse?
+
+Writing a resolver class for every field is repetitive. The vast majority of
+GraphQL fields do one of a handful of things: list a model, find one by id,
+paginate, walk a relationship, or read an attribute. Lighthouse — like its PHP
+inspiration — captures those patterns as **directives** you attach in the schema,
+and falls back to a sensible default reader for plain fields. You write Ruby only
+for the genuinely custom parts (`@field(resolver: "...")`), and your schema stays
+the single source of truth.
+
+### Inspirations
+
+- **[Lighthouse (PHP)](https://lighthouse-php.com)** — the directive vocabulary,
+  the SDL-first philosophy, and the arg-resolver / nested-mutation ideas.
+- **[graphql-ruby](https://graphql-ruby.org)** — the execution engine,
+  `Dataloader`, and the connection/pagination types Lighthouse builds on.
+- **[Apollo Federation](https://www.apollographql.com/docs/federation/)** — so a
+  Rails app can be one subgraph in a larger supergraph.
+
+---
+
+## Installation
+
+Add the gem to your `Gemfile`:
+
+```ruby
+gem 'lighthouse-graphql'
+```
+
+It depends on `graphql ~> 2.5` and `activesupport`. For federation you also need
+`apollo-federation` in your app (it is an optional, app-provided dependency).
+
+## Quick start
+
+1. **Put your SDL** in `app/graphql` or any folder (default: `RAILS_ROOT/graphql`),
+   split across as many `.graphql` files as you like:
+
+   ```graphql
+   # graphql/users.graphql
+   type Query {
+     users: [User!]! @paginate
+     user(id: ID! @eq): User @find
+   }
+
+   type User {
+     id: ID!
+     name: String
+     email: String
+     posts: [Post!]! @hasMany
+   }
+   ```
+
+2. **Build the schema** (typically in `app/graphql/your_schema.rb`):
+
+   ```ruby
+   require 'lighthouse-graphql'
+
+   AppSchema = Lighthouse::GraphQL::RbLightHouse.get_schema(
+     sdl_folder: Rails.root.join('graphql').to_s,
+     options: { base_types: { object: BaseObject } } # your graphql-ruby base classes
+   )
+   ```
+
+3. **Execute** it from your controller exactly like any graphql-ruby schema:
+
+   ```ruby
+   AppSchema.execute(params[:query], variables: params[:variables], context: { current_user: current_user })
+   ```
+
+See **[docs/getting-started.md](docs/getting-started.md)** for the full setup,
+including base types and configuration.
+
+---
+
+## Documentation
+
+| Guide | What it covers |
+| --- | --- |
+| [Getting started](docs/getting-started.md) | Install, base types, building & serving the schema |
+| [Directives reference](docs/directives.md) | Every built-in directive, grouped by purpose |
+| [Relationships](docs/relationships.md) | `@hasMany`, `@belongsTo`, `@belongsToMany`, `@hasOne` and batching |
+| [Filtering & ordering](docs/filtering-and-ordering.md) | `@eq`/`@where`/`@in`/`@like`, `@whereConditions`, `@orderBy` |
+| [Authentication & authorization](docs/authorization.md) | `@guard`, `@can` (policy-based, Pundit by default) |
+| [Apollo Federation](docs/federation.md) | `@key`, `resolve_reference`, the `ReferenceResolver` registry |
+| [Custom directives](docs/custom-directives.md) | The contracts, the registry, writing your own directive |
+| [Configuration](docs/configuration.md) | `Lighthouse.configure`, namespaces, error handling |
+| [Best practices](docs/best-practices.md) | Conventions worth adopting |
+
+---
+
+## How it works (one paragraph)
+
+Lighthouse parses your SDL, runs a **manipulation phase** (directives that need to
+reshape the schema — e.g. `@paginate` injecting a Paginator type, `@whereConditions`
+generating input types), builds an executable schema with
+`GraphQL::Schema.from_definition`, then runs a **resolution phase** that attaches
+behavior to fields (directives that resolve data, wrap resolvers, or compose query
+constraints). Every directive is a small class registered with a
+`Lighthouse::DirectiveRegistry`; adding one is "write a class and register it." A
+single `Support::Naming` rule maps GraphQL `camelCase` to Rails `snake_case`, so
+attribute reads "just work" with `@rename` as the explicit override.
+
+## License
+
+MIT. See [LICENSE.txt](LICENSE.txt).

data/docs/authorization.md

@@ -0,0 +1,109 @@
+# Authentication & Authorization
+
+Lighthouse lets you enforce **authentication** and **authorization** declaratively
+in your schema with the `@guard` and `@can` directives — instead of hand-writing
+a resolver whose only job is a policy check. This mirrors PHP Lighthouse's
+`@guard` / `@can*` family, adapted to Ruby and your authorization library (Pundit
+by default).
+
+## Configuration
+
+The library is framework-agnostic: how it reads the current user and how it
+checks an ability are both configurable. The defaults work with a Rails app that
+puts `current_user` / `pundit_user` in the GraphQL context and uses Pundit, so
+**typically no configuration is needed**:
+
+```ruby
+Lighthouse.configure do |config|
+  # The authenticated user (nil if none). Default:
+  config.authenticated_user = ->(ctx) { ctx[:current_user] }
+
+  # The "user" passed to the authorizer. Default: ctx[:pundit_user], falling back
+  # to the authenticated user.
+  config.policy_user = ->(ctx) { ctx[:pundit_user] }
+
+  # How an ability is checked. Default uses Pundit:
+  config.authorizer = ->(user, record, ability) { Pundit.policy!(user, record).public_send("#{ability}?") }
+end
+```
+
+Point `authorizer` at any system (CanCanCan, ActionPolicy, a plain lambda) to use
+something other than Pundit.
+
+## `@guard` — require authentication
+
+Require an authenticated user before a field resolves. Raises `Unauthenticated.`
+otherwise.
+
+```graphql
+type Query {
+  me: User @field(resolver: "Resolvers::CurrentUser") @guard
+}
+```
+
+`@guard` runs **outermost** — before any other directive on the field.
+
+## `@can` — authorize with a policy
+
+Check a policy ability. By default it authorizes the **resolved record**: the
+field resolves first, then `@can` checks the ability against the result (and
+raises if denied). `nil` results pass through; collections are left to scoping.
+
+```graphql
+type Query {
+  # Resolve the (account-scoped) contact, then authorize ContactPolicy#show?
+  contact(id: ID!): Contact
+    @field(resolver: "Resolvers::ContactResolver")
+    @can(ability: "show")
+}
+```
+
+```ruby
+# The resolver is now just a scoped finder — no authorization boilerplate.
+module Resolvers
+  class ContactResolver
+    def self.call(_obj, args, ctx)
+      account = ctx[:current_account]
+      account.contacts.find_by(id: args[:id]) || raise(GraphQL::ExecutionError, 'Contact not found.')
+    end
+  end
+end
+```
+
+With Pundit, `@can(ability: "show")` calls `ContactPolicy.new(pundit_user, contact).show?`.
+
+### Other modes
+
+```graphql
+# Authorize against the parent object (e.g. restrict a field on a type):
+type User {
+  email: String! @can(ability: "view_email", root: true)
+}
+
+# Find a model by an argument and authorize it before resolving:
+type Mutation {
+  archivePost(id: ID!): Post @can(ability: "update", find: "id", model: "Post") @field(resolver: "...")
+}
+```
+
+`@can` is `repeatable`, so you can require multiple abilities.
+
+## Multi-tenancy vs. authorization
+
+Keep the two layers distinct:
+
+- **Tenancy / scoping** (which account's records are visible) belongs in your
+  resolver or an `@builder` — e.g. `account.contacts`. This is application-specific.
+- **Authorization** (may this user perform this action on this record) belongs in
+  `@can` + your policies.
+
+For list fields, filter with a policy **scope** in a builder (e.g. Pundit's
+`policy_scope`) rather than authorizing item-by-item.
+
+## Ordering
+
+When several wrapping directives are on one field, they run in this order:
+
+1. `@guard` / `@auth` (authentication) — outermost
+2. `@can` (authorization of the resolved value)
+3. the field's data resolver (`@field`, `@all`, `@hasMany`, …) — innermost

data/docs/best-practices.md

@@ -0,0 +1,75 @@
+# Best Practices
+
+A few conventions that keep a Lighthouse schema clean and predictable. They build
+on the [GraphQL best practices](https://graphql-rules.com/) and PHP Lighthouse's
+guidance, adapted to Rails.
+
+## Name your primary key `id`
+
+Clients and tooling (and Apollo Federation) assume an `id` field. Keep it `ID!`.
+
+## Let the schema be the source of truth
+
+Reach for a directive before writing a resolver class. Most fields are an `@all`,
+`@find`, `@paginate`, a relationship, or a plain attribute read. Hand-write Ruby
+(`@field`) only for genuinely custom logic. Your `.graphql` files should read like
+documentation of your API.
+
+## Keep the camelCase ↔ snake_case mapping implicit
+
+Expose `camelCase` fields and let the default reader map them to `snake_case`
+attributes. Only use `@rename(attribute:)` when the mapping isn't a plain
+`underscore` — don't sprinkle it everywhere.
+
+## Restrict filterable columns
+
+When using `@whereConditions`, always pass `columns:` (or `columnsEnum:`) to
+constrain what clients can filter on. Open-ended column filtering is a performance
+and security risk:
+
+```graphql
+people(where: _ @whereConditions(columns: ["age", "type"])): [Person!]! @all
+```
+
+The same applies to `@orderBy` — expose a bounded set of sortable columns.
+
+## Enable the Dataloader
+
+Add `use GraphQL::Dataloader` to your schema so relationship directives batch.
+Without it, nested relationships re-introduce N+1 queries.
+
+## Authorize at the field, early
+
+Use `@auth` (and your own authorization directives) on fields that require it.
+Because `@auth` wraps the resolver, the check runs before any data is loaded.
+
+## Mutations: prefer throwable errors
+
+For mutations, raise `GraphQL::ExecutionError` for business failures ("Not
+found", validation messages) rather than returning an `errors` field in the
+payload. Thrown errors surface in the response's top-level `errors` array, which
+is where GraphQL clients' error handling already looks — `onError` callbacks fire,
+and you don't have to thread an `errors` field through every payload and caller.
+
+```ruby
+def resolve(id:)
+  record = Model.find_by(id: id)
+  raise GraphQL::ExecutionError, 'Not found.' unless record
+  # ...
+  { record: record }
+end
+```
+
+## One configuration seam
+
+Keep all Lighthouse wiring — `resolver_namespaces`, custom directive
+registration, federation reference resolvers, `on_error` — in initializers, not
+scattered through the app. This keeps the library a clean dependency and makes the
+app's GraphQL setup easy to find.
+
+## Split your SDL
+
+Lighthouse concatenates every `*.graphql` file under your `sdl_folder`. Organize
+by domain (`users.graphql`, `orders.graphql`, …) and keep a small
+`_directives.graphql` only for directives you declare yourself (built-ins are
+injected automatically).

data/docs/configuration.md

@@ -0,0 +1,70 @@
+# Configuration
+
+Configure Lighthouse from a single initializer. Keeping app-specific wiring here
+means the library holds no app constants — which is what makes it cleanly
+reusable and publishable.
+
+```ruby
+# config/initializers/lighthouse.rb
+require 'lighthouse-graphql'
+
+Lighthouse.configure do |config|
+  config.sdl_folder = Rails.root.join('graphql').to_s
+  config.resolver_namespaces = ['App::Graphql', 'Resolvers']
+  config.on_error = ->(error, _context) { Rails.error.report(error) }
+end
+```
+
+## Options
+
+### `sdl_folder`
+
+Where Lighthouse loads `*.graphql` files from. Defaults to `RAILS_ROOT/graphql`
+in a Rails app, `nil` otherwise (pass SDL explicitly via `SchemaFactory` when not
+on Rails).
+
+### `resolver_namespaces`
+
+An ordered list of namespaces tried when resolving a **class name** referenced by
+a directive argument — `@field(resolver: "ContactPerson")`, `@all(model: "User")`,
+`@builder(class: "ContactsBuilder")`. Fully-qualified names (containing `::`) are
+used as-is. Defaults to `['App::Graphql']`.
+
+```ruby
+config.resolver_namespaces = ['App::Graphql', 'Resolvers']
+# "ContactPerson" tries App::Graphql::ContactPerson, then Resolvers::ContactPerson, then ::ContactPerson
+```
+
+This is the seam that keeps the gem free of your app's namespace.
+
+### `on_error`
+
+A callable `->(error, context) { ... }` invoked when a directive or resolver
+swallows an error (e.g. a malformed filter). The default **raises in test** (so
+failures surface in your suite) and logs otherwise. Point it at your error
+reporter in production:
+
+```ruby
+config.on_error = ->(error, _ctx) { Sentry.capture_exception(error) }
+```
+
+## Extending the registry
+
+Register app-defined directives (see [custom-directives.md](custom-directives.md))
+from the same initializer:
+
+```ruby
+Lighthouse::DirectiveRegistry.register(App::Graphql::Directives::StartsWith)
+```
+
+## Federation reference resolvers
+
+Custom federation entity resolvers are registered with
+`Lighthouse::ReferenceResolver` (see [federation.md](federation.md)), typically in
+`config/initializers/federation.rb` so they re-register on code reload:
+
+```ruby
+Rails.application.config.to_prepare do
+  Lighthouse::ReferenceResolver.register('User') { |ref, _ctx| User.find_by(id: ref['id']) }
+end
+```

data/docs/custom-directives.md

@@ -0,0 +1,129 @@
+# Custom Directives
+
+Adding a directive to Lighthouse is "write one class and register it." There are
+no edits to Lighthouse internals — the generator discovers behavior through a set
+of **contracts** (marker modules) and a **registry**.
+
+## The architecture
+
+Lighthouse builds a schema in two phases, mirroring PHP Lighthouse's
+manipulator/resolver split:
+
+1. **Manipulation phase** (before the schema is built) — directives that need to
+   reshape the SDL/AST run here: `@paginate` injecting a Paginator type,
+   `@whereConditions` generating input and enum types, etc.
+2. **Resolution phase** (after `GraphQL::Schema.from_definition`) — directives
+   attach runtime behavior: resolving data, wrapping a resolver, or composing a
+   query constraint.
+
+A `Lighthouse::DirectiveRegistry` maps directive names to the classes that
+implement them. The generator iterates the registry rather than a hardcoded
+dispatch table.
+
+## The contracts
+
+Include the marker module(s) your directive fulfils:
+
+| Contract | Role | Key method |
+| --- | --- | --- |
+| `Contracts::FieldResolver` | provide a field's resolver | `#define_resolver(type)` (or `#resolve_field`) |
+| `Contracts::FieldMiddleware` | wrap an existing resolver (e.g. `@auth`) | `#wrap_resolver(next)` |
+| `Contracts::FieldManipulator` | reshape the schema for a field | `manipulate_field_definition(...)` |
+| `Contracts::ArgManipulator` | reshape the schema for an argument | `manipulate_argument_definition(...)` |
+| `Contracts::ArgBuilder` | compose a query constraint from an argument | `#handle_builder(relation, value)` |
+
+A directive class also answers two class-level questions: its name and its SDL
+definition.
+
+```ruby
+def self.directive_name = 'upcase'
+def self.definition = 'directive @upcase on FIELD_DEFINITION'
+```
+
+Lighthouse injects that `definition` into the schema automatically, so apps never
+hand-declare your directive.
+
+## Example 1 — an argument filter
+
+Argument-builder directives are the simplest. Suppose you want `@startsWith`:
+
+```ruby
+module App
+  module Graphql
+    module Directives
+      class StartsWith < Lighthouse::GraphQL::Directives::Arguments::Base
+        def self.directive_name = 'startsWith'
+        def self.definition = 'directive @startsWith(key: String) on ARGUMENT_DEFINITION'
+
+        def handle_builder(relation, value)
+          return relation if value.nil?
+
+          relation.where(arel_column(relation).matches("#{value}%"))
+        end
+      end
+    end
+  end
+end
+```
+
+`Arguments::Base` gives you `column` (the `key:` override or snake_cased arg name)
+and `arel_column(relation)`.
+
+## Example 2 — a field resolver
+
+A field-resolver directive attaches a resolver to a field. The simplest path is to
+subclass the base resolver and implement `define_resolver`:
+
+```ruby
+module App
+  module Graphql
+    module Directives
+      class UpcaseDirective < Lighthouse::GraphQL::DirectiveResolvers::BaseDirectiveResolver
+        def self.directive_name = 'upcase'
+        def self.definition = 'directive @upcase on FIELD_DEFINITION'
+
+        def define_resolver(target_type)
+          name = @field_def.name
+          target_type.define_singleton_method("resolve_field_#{name}") do |obj, _args, _ctx|
+            value = obj.public_send(Lighthouse::Support::Naming.attribute(name))
+            value&.upcase
+          end
+        end
+      end
+    end
+  end
+end
+```
+
+## Registering
+
+Register your directive once, from your Lighthouse initializer:
+
+```ruby
+# config/initializers/lighthouse.rb
+Lighthouse::DirectiveRegistry.register(App::Graphql::Directives::StartsWith)
+Lighthouse::DirectiveRegistry.register(App::Graphql::Directives::UpcaseDirective)
+```
+
+It is now usable in your SDL — no other changes:
+
+```graphql
+type Query {
+  users(name: String @startsWith): [User!]! @all
+}
+
+type User {
+  shoutName: String @upcase @rename(attribute: "name")
+}
+```
+
+## Naming helper
+
+Whenever you map a GraphQL name to a database column or model attribute, route
+through `Lighthouse::Support::Naming` so your directive honors the same
+camelCase→snake_case rule as the rest of the library:
+
+```ruby
+Lighthouse::Support::Naming.attribute('customAttributes') # => "custom_attributes"
+Lighthouse::Support::Naming.column('CREATED_AT')          # => "created_at"
+```