graphiti 2.0.0.beta.5 → 2.0.0.beta.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cdd882c646fa88d0ac6522b7725ad6132b7ad890043822f5e2a2ce8af3f0fc4c
-  data.tar.gz: 687c64e9c5e6d2931a09bde9f5595b965e36f1a090d863fa17b9edf11559533f
+  metadata.gz: e108e5f71103c3fb7f38f5328a890ff131b264201c583509081cfd3106a7b255
+  data.tar.gz: 18edd07b0ab429ec89309ec94164a2324a21bbbfbd6dd37f6e49bb6f9707f1c9
 SHA512:
-  metadata.gz: 1907226aa19ad065b0affe66f5ea22bb7149fd11aef92d225d7b433a5c67111bde2d7ef5911e633c5ea9059559ff903654c21f835099b5e15e72fdf7ab59cc9b
-  data.tar.gz: 91fd8e83a1452d29ffb45076b94a9eeb316c4e508a2f6565c5e079e6c54a184eede79da45ecb9d25f340f395551d907e10eb152e05666387792c434ed5fb4361
+  metadata.gz: f2affdd800c2966ef15c5d1765b9d1acc48a032c3ee143b9283d69b9545290e227454d77559e25c94b4cd7b0131d0cdc2addbb031a4177155d8085086d818b3b
+  data.tar.gz: 79c294b775b8be269194cae7e61cf179a16ec8dd01e8b0b24e7a141d3333683bfbd54032e4c07623f6d2dc3fbe3ce6c721884658da89cbe24bfd9dac935f8e07

data/.github/workflows/ci.yml

@@ -41,25 +41,30 @@ jobs:
           - { ruby: "3.2", gemfile: Gemfile, appraisal: false }
           - { ruby: "3.3", gemfile: Gemfile, appraisal: false }
           - { ruby: "3.4", gemfile: Gemfile, appraisal: false }
+          - { ruby: "4.0", gemfile: Gemfile, appraisal: false }
           - { ruby: ruby-head, gemfile: Gemfile, appraisal: false }
 
           # Rails 7.1 - the floor
           - { ruby: "3.2", gemfile: gemfiles/rails_7_1.gemfile, appraisal: true }
           - { ruby: "3.4", gemfile: gemfiles/rails_7_1.gemfile, appraisal: true }
+          - { ruby: "4.0", gemfile: gemfiles/rails_7_1.gemfile, appraisal: true }
 
           # Rails 7.2
           - { ruby: "3.2", gemfile: gemfiles/rails_7_2.gemfile, appraisal: true }
           - { ruby: "3.4", gemfile: gemfiles/rails_7_2.gemfile, appraisal: true }
+          - { ruby: "4.0", gemfile: gemfiles/rails_7_2.gemfile, appraisal: true }
           - { ruby: ruby-head, gemfile: gemfiles/rails_7_2.gemfile, appraisal: true }
 
           # Rails 8.0
           - { ruby: "3.2", gemfile: gemfiles/rails_8_0.gemfile, appraisal: true }
           - { ruby: "3.4", gemfile: gemfiles/rails_8_0.gemfile, appraisal: true }
+          - { ruby: "4.0", gemfile: gemfiles/rails_8_0.gemfile, appraisal: true }
           - { ruby: ruby-head, gemfile: gemfiles/rails_8_0.gemfile, appraisal: true }
 
           # Rails 8.1
           - { ruby: "3.2", gemfile: gemfiles/rails_8_1.gemfile, appraisal: true }
           - { ruby: "3.4", gemfile: gemfiles/rails_8_1.gemfile, appraisal: true }
+          - { ruby: "4.0", gemfile: gemfiles/rails_8_1.gemfile, appraisal: true }
           - { ruby: ruby-head, gemfile: gemfiles/rails_8_1.gemfile, appraisal: true }
 
     continue-on-error: ${{ matrix.ruby == 'ruby-head' }}

data/CHANGELOG.md

@@ -1,5 +1,20 @@
 graphiti changelog
 
+# [2.0.0-beta.6](https://github.com/graphiti-api/graphiti/compare/v2.0.0-beta.5...v2.0.0-beta.6) (2026-08-09)
+
+
+### Bug Fixes
+
+* reject invalid page parameters ([#537](https://github.com/graphiti-api/graphiti/issues/537)) ([bb3698b](https://github.com/graphiti-api/graphiti/commit/bb3698b52911c658c5d023ad8fd55b5106195001)), closes [#347](https://github.com/graphiti-api/graphiti/issues/347)
+* treat empty polymorphic configuration as unset ([#538](https://github.com/graphiti-api/graphiti/issues/538)) ([5c17899](https://github.com/graphiti-api/graphiti/commit/5c1789993fbb4638d4443cf014b8bef358addb80)), closes [#199](https://github.com/graphiti-api/graphiti/issues/199)
+
+
+### Features
+
+* Add graphiti:audit task to audit resources for issues ([84436ea](https://github.com/graphiti-api/graphiti/commit/84436eab7c7d0713ec6f355b62ba8b06913ee31a))
+* raise MissingRelationshipMethod when rendering reads an association the model does not define ([1c41cee](https://github.com/graphiti-api/graphiti/commit/1c41cee787b4f747d2906b2230f8fb926e3d887d))
+* rename always_include_resource_ids to resource_ids, with a belongs_to_resource_ids_by_default setting ([8b11151](https://github.com/graphiti-api/graphiti/commit/8b111516822f6fc6e3675b59941688791cb34e74))
+
 # [2.0.0-beta.5](https://github.com/graphiti-api/graphiti/compare/v2.0.0-beta.4...v2.0.0-beta.5) (2026-08-07)
 
 

data/docs/concepts/relationships.md

@@ -70,10 +70,20 @@ has_many :positions,
   writable: true,
   link: self.autolink, # default true
   single: false, # only allow this sideload when one employee
-  always_include_resource_ids: true # default: true for belongs_to, false otherwise
+  resource_ids: false
 ```
 
-`belongs_to` renders resource linkage by default, so a client can see which record a relationship points at without following the link:
+`resource_ids` is the one whose default depends on the relationship type:
+
+| type | renders resource ids by default |
+|---|---|
+| `belongs_to` | yes, when its foreign key already holds the related id |
+| `has_one` | no |
+| `has_many` | no |
+| `many_to_many` | no |
+| `polymorphic_belongs_to` | no |
+
+`belongs_to` renders them so a client can see which record a relationship points at without following the link:
 
 ```json
 "employee": {
@@ -82,19 +92,109 @@ has_many :positions,
 }
 ```
 
-That costs nothing, because the id is already on the parent as its foreign key. A `has_many` would have to run a query per record to answer the same question, so it stays off unless you ask for it.
+That costs nothing, because the id is already on the parent as its foreign key.
+
+No other relationship type has a free source for its ids. A collection accepts `resource_ids: true`, but that reads the association on every render of every parent record, whether or not the request wants the relationship. That is the N+1 from [#167](https://github.com/graphiti-api/graphiti/issues/167#issuecomment-686866646) on every response. Leave collections off and let clients `?include=` them.
 
-A `belongs_to` falls back to loading the association when the foreign key cannot answer for it: a `params` block or `base_scope` can filter out the record the key points at, a polymorphic target takes its type from the record rather than the relationship, and a remote resource has no local key to read. Turning linkage on for those, or for a `has_many`, brings back the 1+N described in [#167](https://github.com/graphiti-api/graphiti/issues/167#issuecomment-686866646).
+Not every `belongs_to` can use its foreign key. A `scope` or `params` block or a `base_scope` can filter out the record the key points at, a polymorphic target's type varies per record while rendered ids carry one type for the whole relationship, a remote resource has no local key to read, and a custom `primary_key` points the relationship at some other column. Those load the association instead, so they stay off by default too.
 
-Set the default for every relationship on a resource, whatever its type:
+<details>
+<summary>Which `belongs_to` declarations render resource ids, and which do not</summary>
+
+```ruby
+# yes. employee_id is the employee's id, so the payload already has it
+belongs_to :employee
+
+# no. nothing renders at all, ids included
+belongs_to :employee, readable: false
+
+# no. employee_id holds a name, not the related id
+belongs_to :employee, primary_key: :first_name
+
+# no. the base scope can exclude the employee the key points at, and
+# graphiti cannot know whether it does without running it
+belongs_to :employee, base_scope: -> { Employee.all }
+
+# no. a remote resource has no local foreign key to read
+belongs_to :employee, remote: "http://foo.com/employees"
+
+# no. the record's own class decides its type, so the key gives an id
+# with no type to pair it with
+belongs_to :employee, resource: CreditCardResource
+
+# no. the scope can exclude the employee the key points at, and graphiti
+# cannot know whether it does without running it
+belongs_to :employee do
+  scope { |ids| {type: :employees, conditions: {id: ids}} }
+end
+
+# no. same, a params filter can exclude the employee the key points at
+belongs_to :employee do
+  params { |hash, positions| hash[:filter][:active] = true }
+end
+
+# no. credit_card_type is local, but rendered ids carry one type for the
+# whole relationship and this one's varies per record
+polymorphic_belongs_to :credit_card do
+  group_by(:credit_card_type) do
+    on(:Visa).belongs_to :visa, resource: VisaResource
+  end
+end
+```
+
+Watch for the `scope`, `params` and `base_scope` cases. Nothing about those declarations looks like it concerns resource ids, so adding a scope block to filter a relationship also stops its ids from rendering.
+
+If you keep a `schema.json`, the schema check catches that. A relationship that renders resource ids is marked `linkage: true`, and one that stops rendering them is reported as a breaking change. Gaining them is additive and passes.
+
+To render ids anyway, opt in on the relationship and accept the query:
+
+```ruby
+belongs_to :employee, resource_ids: true do
+  scope { |ids| {type: :employees, conditions: {id: ids}} }
+end
+```
+
+Know what that buys for the `scope`, `params` and `base_scope` cases. Rendering reads the association off the model, which does not apply the block, so if the block narrows what sideloading returns, the ids will disagree with it. Opting in there says you know the two agree. A `primary_key`, polymorphic or remote relationship does resolve to the right id this way.
+
+</details>
+
+### belongs_to_resource_ids_by_default {#belongs-to-resource-ids}
+
+To change how far a `belongs_to` goes, across a whole API, set it on the resource everything inherits from:
 
 ```ruby
 class ApplicationResource < Graphiti::Resource
-  self.always_include_resource_ids_by_default = false
+  self.belongs_to_resource_ids_by_default = :foreign_key
 end
 ```
 
-Subclasses inherit it, and a relationship passing `always_include_resource_ids` explicitly still wins.
+| | |
+|---|---|
+| `:foreign_key` | Default. Render resource ids wherever the foreign key already holds the related id, and never run an extra query. |
+| `:always` | Render them for every `belongs_to`, loading the association when the foreign key cannot answer. A query per record, per relationship, on every render. |
+| `:never` | Render none. This is the 1.x payload. |
+
+Subclasses inherit it, and a relationship passing `resource_ids` explicitly still wins.
+
+All three describe requests that do not include the relationship. A relationship the request does include renders its ids whatever this is set to, `:never` included, because the records are already loaded and sitting in `included`.
+
+Before flipping the setting, [`bin/rake graphiti:audit`](/topics/debugging#graphiti-audit) reports how every relationship renders resource ids today and which would start loading the association.
+
+#### What a client sees {#relationship-payload-shapes}
+
+A client never has to work out which rule applied. The relationship object says what it knows:
+
+```json
+"employee": { "data": { "type": "employees", "id": "1" } }   // here is the id
+"employee": { "links": { "related": "..." } }                 // fetch it yourself
+"employee": { "meta": { "included": false } }                 // neither
+```
+
+The last shape appears only when a relationship has no ids **and** no link, which usually means `link: false`. It is not a general "was this sideloaded" flag. Relationships are autolinked by default, so the link shape is the one you normally see.
+
+The setting covers `belongs_to` and `polymorphic_belongs_to`, and no collection, deliberately. An API-wide `:always` on collections would be the N+1 from [#167](https://github.com/graphiti-api/graphiti/issues/167#issuecomment-686866646) applied everywhere at once.
+
+`:always` renders ids by loading the association, so a relationship naming a method the model does not have raises on every render once you set it.
 
 ### Conditional Relationships {#conditional-relationships}
 
@@ -221,7 +321,7 @@ Defaults to these common options:
 has_many :positions,
   foreign_key: :employee_id,
   primary_key: :id,
-  always_include_resource_ids: false,
+  resource_ids: false,
   resource: PositionResource
 ```
 
@@ -265,7 +365,7 @@ Defaults to these common options:
 belongs_to :employee,
   foreign_key: :employee_id,
   primary_key: :id,
-  always_include_resource_ids: false,
+  resource_ids: true,
   resource: EmployeeResource
 ```
 

data/docs/topics/debugging.md

@@ -172,6 +172,32 @@ Which add Debugger output as well.
 The `PATH` should not contain the domain unless you want to hit a live
 API instead of a test server.
 
+#### graphiti:audit {#graphiti-audit}
+
+> `bin/rake graphiti:audit`
+
+Audits every relationship declared across your resources. It reports anything that will raise at request time, relationships that load an association just to render resource ids, and `belongs_to` relationships that render no ids unless included. A checklist at the end shows what was checked:
+
+```
+ERROR will raise when the relationship is included: the model has no association method
+
+  EmployeeResource
+    has_many :positions  Employee has no #positions method
+
+  fix: define it, point the relationship at the real association with `as:`, or remove the relationship
+
+checks
+
+  ✓ all relationships inspectable
+  ✗ 1 association method missing
+  ✓ all readable guards defined
+  ✓ all sideload filters declared
+
+graphiti: 12 resources, 40 relationships, 1 error.
+```
+
+The task exits nonzero when there are errors, so it can hold the line in CI. Run it before and after flipping [belongs_to_resource_ids_by_default](/concepts/relationships#belongs-to-resource-ids) to see exactly what the setting changes.
+
 #### graphiti:benchmark {#graphiti-benchmark}
 
 > `bin/rake graphiti:benchmark[PATH,NUM_REQUESTS]`

data/docs/upgrading.md

@@ -128,9 +128,9 @@ It has to be a request spec. Exceptions are rendered in Rack middleware, which c
 Nothing to do here. These change what a client receives or when a callback runs, and none of them warns you, because none of them is a rename.
 
 <details>
-<summary>A `belongs_to` renders resource linkage in every payload, where 1.x sent only a link</summary>
+<summary>A `belongs_to` renders resource ids when its foreign key already holds them, where 1.x sent only a link</summary>
 
-A `belongs_to` now includes resource linkage in the payload by default, where 1.x sent only a link:
+A `belongs_to` now renders resource ids in the payload by default, where 1.x sent only a link:
 
 ```json
 "employee": { "data": { "type": "employees", "id": "1" }, "links": { "related": "..." } }
@@ -138,27 +138,29 @@ A `belongs_to` now includes resource linkage in the payload by default, where 1.
 
 The id comes from the foreign key already on the parent, so this costs no extra queries, and clients can resolve the relationship against data they already hold instead of following the link. `has_many` is unchanged, since answering there means a query per record.
 
-Not every `belongs_to` qualifies. A `scope` or `params` block, a `base_scope`, a polymorphic or remote target or a custom `primary_key` all mean the foreign key is not the related id, and those keep loading the association, so they stay opt-in as in 1.x.
+Not every `belongs_to` qualifies. A remote target or a custom `primary_key` mean the foreign key is not the related id, a polymorphic target means one rendered type cannot cover every record, and a `scope` or `params` block or a `base_scope` mean the key might not survive the filter. Rendering ids for those means loading the association, so they stay opt-in as in 1.x and render nothing until you ask.
 
-Relationships are marked `linkage: true` in `schema.json`, and the schema check reports a relationship that stops including it.
+Run [`bin/rake graphiti:audit`](/topics/debugging#graphiti-audit) to see where your API stands: it lists every relationship that renders no ids, and why.
 
 To go back to the old payload for one relationship:
 
 ```ruby
-belongs_to :employee, always_include_resource_ids: false
+belongs_to :employee, resource_ids: false
 ```
 
-Or for the whole API, on the resource everything inherits from. The same setting with `true` is the 2.0 replacement for the `Sideload::BelongsTo` monkey patch that [#167](https://github.com/graphiti-api/graphiti/issues/167) has been recommending, and it now covers every relationship type rather than only `belongs_to`:
+Or for the whole API, on the resource everything inherits from:
 
 ```ruby
 class ApplicationResource < Graphiti::Resource
   self.abstract_class = true
 
-  self.always_include_resource_ids_by_default = false
+  self.belongs_to_resource_ids_by_default = :never
 end
 ```
 
-How linkage is configured, and when a `belongs_to` cannot use its foreign key, is covered in [Customizing Relationships](/concepts/relationships#customizing-relationships).
+If you carry the `Sideload::BelongsTo` monkey patch from [#167](https://github.com/graphiti-api/graphiti/issues/167), delete it and set nothing. The default now covers the safe cases on its own. To force ids onto the rest the way the patch did, set `self.belongs_to_resource_ids_by_default = :always`, at a query per record for each one.
+
+The three settings, and when a `belongs_to` cannot use its foreign key, are covered in [Customizing Relationships](/concepts/relationships#belongs-to-resource-ids).
 
 </details>
 
@@ -224,6 +226,7 @@ Every name below still works, warns, and will be removed in the next major. They
 | `context_namespace` | `current_action` |
 | `Graphiti::Rails::DEPRECATOR` | `Graphiti::DEPRECATOR` (the old name still resolves) |
 | `require "graphiti_errors"`, `require "graphiti/responders"` | remove / no longer needed |
+| `always_include_resource_ids: true` on a relationship | `resource_ids: true` |
 
 `RSpec.describe PostResource, type: :resource` still picks up the resource-testing context automatically. That has not changed.
 
@@ -234,6 +237,9 @@ Every name below still works, warns, and will be removed in the next major. They
 | `include GraphitiErrors` | `register_exception` is available on every controller |
 | `GraphitiErrors::ExceptionHandler` | subclass `Graphiti::Rails::ExceptionHandler` |
 | `GraphitiErrors.enable!` / `.disable!` | `handle_request_exceptions` |
+| `self.always_include_resource_ids_by_default` | `self.belongs_to_resource_ids_by_default`, which takes `:foreign_key`, `:always` or `:never` |
+
+`always_include_resource_ids_by_default` only ever shipped in `2.0.0.beta.4`, so it is gone rather than deprecated and raises `NoMethodError` at class-definition time. It applied to every relationship type, and only a `belongs_to` can render resource ids without loading an association, so the replacement covers `belongs_to` alone. `= false` becomes `:never`. There is no equivalent of `= true`, because arming every collection API-wide is the behavior it was removed for. Use `:always` for `belongs_to`.
 
 ## Without Rails {#without-rails}
 

data/graphiti.gemspec

@@ -24,7 +24,7 @@ Gem::Specification.new do |spec|
   spec.add_dependency "rescue_registry", "~> 1.0"
   spec.add_dependency "concurrent-ruby", ">= 1.2", "< 2.0"
   spec.add_dependency "activesupport", ">= 7.1"
-  # Bundled (no longer default) as of Ruby 3.5; graphiti uses OpenStruct in lib/
+  # Bundled (no longer default) as of Ruby 4.0; graphiti uses OpenStruct in lib/
   spec.add_dependency "ostruct", ">= 0.5"
 
   spec.add_development_dependency "faraday", "~> 0.15"

data/lib/graphiti/audit/report.rb

@@ -0,0 +1,226 @@
+module Graphiti
+  class Audit
+    class Report
+      ANSI = {red: 31, green: 32, yellow: 33, blue: 34, magenta: 35, cyan: 36, bold: 1, dim: 2}.freeze
+
+      ISSUE_HEADINGS = {
+        broken_relationship: "raised while being inspected",
+        missing_association_method: "will raise when the relationship is included: the model has no association method",
+        missing_guard_method: "will raise whenever the resource renders: the readable guard is not defined",
+        missing_sideload_filter: "will raise when the relationship is included: the related resource is missing the filter"
+      }.freeze
+
+      CHECKLIST = {
+        broken_relationship: ["all relationships inspectable", "relationship", "raised while being inspected"],
+        missing_association_method: ["all association methods defined", "association method", "missing"],
+        missing_guard_method: ["all readable guards defined", "readable guard", "missing"],
+        missing_sideload_filter: ["all sideload filters declared", "sideload filter", "missing"],
+        loads_on_every_render: ["all id-rendering loads preloaded", "relationship", "loading ids without preloading"]
+      }.freeze
+
+      Cell = Struct.new(:raw, :painted) do
+        def pad_to(width)
+          painted + " " * (width - raw.length)
+        end
+      end
+
+      def initialize(rows, color: $stdout.tty?)
+        @rows = rows
+        @color = color
+      end
+
+      def to_s
+        return "graphiti: no relationships found.\n" if @rows.empty?
+
+        (body + [summary]).join("\n")
+      end
+
+      private
+
+      def body
+        [""] + issue_sections + loading_section + would_load_section + checks_section
+      end
+
+      def issue_sections
+        row_finding_pairs = @rows.flat_map do |row|
+          row.findings.map { |finding| [row, finding] }
+        end
+
+        row_finding_pairs
+          .group_by { |_, finding| finding.check }
+          .sort_by { |check, _| ISSUE_HEADINGS.keys.index(check) || ISSUE_HEADINGS.size }
+          .flat_map { |check, group| issue_section(check, group) }
+      end
+
+      def issue_section(check, group)
+        findings = group.map(&:last)
+        label = findings.first.error? ? "ERROR" : "WARNING"
+        color = findings.first.error? ? :red : :yellow
+        fixes = findings.filter_map(&:remedy).uniq
+
+        section_heading(label, color, ISSUE_HEADINGS.fetch(check, check.to_s.tr("_", " "))) +
+          lines_grouped_by_resource(group.map { |row, finding| [row, finding.message] }) +
+          (fixes.size == 1 ? [fix_line(fixes.first), ""] : [])
+      end
+
+      def loading_section
+        rows = @rows.select { |row| loads_without_preload?(row) }
+        return [] if rows.empty?
+
+        section_heading("WARNING", :yellow, "rendering resource ids by loading an association the base_scope does not preload") +
+          lines_grouped_by_resource(rows.map { |row| [row, nil] }) +
+          ["  #{paint("That is a query per record rendered.", :dim)}",
+            fix_line("preload the association in base_scope, or drop `resource_ids`"),
+            "  #{paint("See www.graphiti.dev/concepts/relationships#customizing-relationships", :dim)}",
+            ""]
+      end
+
+      def loads_without_preload?(row)
+        row.resource_ids_source == :load && row.preloaded == false
+      end
+
+      def would_load_section
+        rows = @rows.select(&:would_start_loading?)
+        return [] if rows.empty?
+
+        verb = rows.size == 1 ? "renders" : "render"
+
+        section_heading("FYI", :blue, "#{count(rows.size, "belongs_to relationship")} #{verb} no resource ids") +
+          lines_grouped_by_resource(rows.map { |row| [row, nil] }) +
+          ["  #{paint("Nothing to fix. A request that includes the relationship still gets its ids.", :dim)}",
+            "",
+            "  #{paint("To render ids on every response, opt in:", :dim)}",
+            ""] +
+          opt_in_lines +
+          ["",
+            "  #{paint("Either would load the association on every render. That potential performance cost is why ids are opt-in.", :dim)}",
+            "  #{paint("Preloading the association in base_scope keeps that load cheap.", :dim)}",
+            "  #{paint("See www.graphiti.dev/concepts/relationships#belongs-to-resource-ids", :dim)}",
+            ""]
+      end
+
+      def checks_section
+        failure_counts = @rows.flat_map(&:findings).map(&:check).tally
+        loading = @rows.count { |row| loads_without_preload?(row) }
+        failure_counts[:loads_on_every_render] = loading if loading > 0
+
+        no_loads = @rows.none? { |row| row.resource_ids_source == :load }
+
+        lines = CHECKLIST.filter_map do |check, (passed, failure_noun, failure_suffix)|
+          if (failures = failure_counts[check])
+            "  #{paint("✗", :red)} #{count(failures, failure_noun)} #{failure_suffix}"
+          elsif check == :loads_on_every_render && no_loads
+            nil
+          else
+            "  #{paint("✓", :green)} #{passed}"
+          end
+        end
+
+        [paint("checks", :bold), ""] + lines + [""]
+      end
+
+      def section_heading(label, color, heading)
+        ["#{paint(label, color, :bold)} #{paint(heading, :bold)}", ""]
+      end
+
+      def fix_line(text)
+        "  #{paint("fix:", :green)} #{text}"
+      end
+
+      def lines_grouped_by_resource(pairs)
+        width = pairs.map { |row, _| declaration_cell(row).raw.length }.max
+
+        pairs.group_by { |row, _| row.resource }.sort_by { |resource, _| resource }.flat_map do |resource, group|
+          ["  #{paint(resource, :bold)}"] +
+            group.sort_by { |row, _| row.relationship.to_s }.map { |row, note|
+              declaration = declaration_cell(row)
+              note ? "    #{declaration.pad_to(width)}  #{note}" : "    #{declaration.painted}"
+            } +
+            [""]
+        end
+      end
+
+      def opt_in_lines
+        options = [
+          [[["resource_ids: ", :cyan], ["true", :yellow]], "on one relationship"],
+          [[["self.belongs_to_resource_ids_by_default = ", nil], [":always", :cyan]], "across the whole API"]
+        ]
+
+        rows = options.map do |parts, scope|
+          [cell(parts), cell([[scope, :dim]])]
+        end
+
+        aligned(rows, "    ")
+      end
+
+      def declaration_cell(row)
+        cell(declaration_parts(row))
+      end
+
+      def declaration_parts(row)
+        parts = [[row.type.to_s, :blue], [" ", nil], [":#{row.relationship}", :cyan]]
+
+        row.options.each do |key, value|
+          parts << [", ", nil] << ["#{key}: ", :cyan] << option_part(value)
+        end
+
+        parts
+      end
+
+      def option_part(value)
+        case value
+        when "..." then ["{ ... }", :dim]
+        when true, false then [value.inspect, :yellow]
+        when Symbol then [value.inspect, :cyan]
+        when String then [value.inspect, :green]
+        else [value.inspect, nil]
+        end
+      end
+
+      def cell(parts)
+        Cell.new(
+          parts.map { |text, _| text }.join,
+          parts.map { |text, style| paint(text, style) }.join
+        )
+      end
+
+      def aligned(rows, indent)
+        widths = rows.transpose.map { |column| column.map { |cell| cell.raw.length }.max }
+
+        rows.map do |cells|
+          line = cells.each_with_index.map { |cell, index|
+            index == cells.size - 1 ? cell.painted : cell.pad_to(widths[index])
+          }.join("  ")
+          indent + line
+        end
+      end
+
+      def summary
+        errors = @rows.count(&:error?)
+        loading = @rows.count { |row| loads_without_preload?(row) }
+        no_ids = @rows.count(&:would_start_loading?)
+
+        counts = [
+          count(@rows.group_by(&:resource).size, "resource"),
+          count(@rows.size, "relationship"),
+          paint(count(errors, "error"), errors > 0 ? :red : nil)
+        ]
+        counts << paint("#{loading} loading ids without preloading", :yellow) if loading > 0
+        counts << "#{no_ids} without resource ids" if no_ids > 0
+
+        "graphiti: #{counts.join(", ")}."
+      end
+
+      def count(number, noun)
+        "#{number} #{noun}#{"s" unless number == 1}"
+      end
+
+      def paint(text, *styles)
+        styles = styles.compact
+        return text unless @color && styles.any?
+
+        "\e[#{styles.map { |style| ANSI.fetch(style) }.join(";")}m#{text}\e[0m"
+      end
+    end
+  end
+end

data/lib/graphiti/audit.rb

@@ -0,0 +1,231 @@
+module Graphiti
+  # Resources register themselves as they load, so eager load before auditing.
+  class Audit
+    Finding = Struct.new(:severity, :check, :message, :remedy, keyword_init: true) do
+      def error?
+        severity == :error
+      end
+    end
+
+    Row = Struct.new(
+      :resource,
+      :relationship,
+      :type,
+      :target,
+      :resource_ids_source,
+      :resource_ids_source_if_always,
+      :resource_ids_default,
+      :resource_ids_blocker,
+      :preloaded,
+      :options,
+      :findings,
+      keyword_init: true
+    ) do
+      def would_start_loading?
+        return false if resource_ids_default == :never
+
+        resource_ids_source != :load && resource_ids_source_if_always == :load
+      end
+
+      def severity
+        return :error if findings.any?(&:error?)
+        findings.empty? ? :ok : :warning
+      end
+
+      def error?
+        severity == :error
+      end
+    end
+
+    def self.run(resources = nil)
+      new(resources).run
+    end
+
+    def self.findings(resources = nil)
+      run(resources).flat_map(&:findings)
+    end
+
+    def initialize(resources = nil)
+      @resources = resources || Graphiti.resources.reject(&:abstract_class?)
+    end
+
+    def run
+      @resources.sort_by { |resource| resource.name.to_s }.flat_map { |resource| rows_for(resource) }
+    end
+
+    private
+
+    def rows_for(resource_class)
+      model = inferred_model(resource_class)
+
+      resource_class.sideloads.map do |name, sideload|
+        row_for(resource_class, name, sideload, model)
+      end
+    end
+
+    def row_for(resource_class, name, sideload, model)
+      source = resource_ids_source(sideload)
+
+      Row.new(
+        resource: resource_class.name,
+        relationship: name,
+        type: sideload.type,
+        target: target_name(sideload),
+        resource_ids_source: source,
+        resource_ids_source_if_always: resource_ids_source_if_always(resource_class, sideload),
+        resource_ids_default: resource_class.belongs_to_resource_ids_by_default,
+        resource_ids_blocker: sideload.resource_ids_blocker,
+        preloaded: source == :load ? association_preloaded?(resource_class, sideload) : nil,
+        options: declaration_options(sideload),
+        findings: [
+          missing_association_method(sideload, model),
+          missing_guard_method(resource_class, sideload),
+          missing_sideload_filter(sideload)
+        ].compact
+      )
+    rescue => error
+      Row.new(
+        resource: resource_class.name,
+        relationship: name,
+        type: sideload.type,
+        resource_ids_source: :none,
+        options: {},
+        findings: [
+          Finding.new(
+            severity: :error,
+            check: :broken_relationship,
+            message: "#{error.class}: #{error.message.strip.lines.first.to_s.strip}"
+          )
+        ]
+      )
+    end
+
+    def declaration_options(sideload)
+      options = sideload.non_default_options
+      options[:base_scope] = "..." if sideload.customized_base_scope?
+      options[:scope] = "..." if sideload.class.scope_proc
+      options[:params] = "..." if sideload.class.params_proc
+      options
+    end
+
+    def resource_ids_source(sideload)
+      return :none unless sideload.render_resource_ids?
+
+      sideload.resource_ids_blocker.nil? ? :key : :load
+    end
+
+    def resource_ids_source_if_always(resource_class, sideload)
+      original = resource_class.belongs_to_resource_ids_by_default
+      resource_class.belongs_to_resource_ids_by_default = :always
+      resource_ids_source(sideload)
+    ensure
+      resource_class.belongs_to_resource_ids_by_default = original
+    end
+
+    def target_name(sideload)
+      if sideload.type == :polymorphic_belongs_to
+        children = sideload.children.values.filter_map { |child| short_name(child) }
+        return children.empty? ? nil : children.join(", ")
+      end
+
+      sideload.resource.class.name
+    rescue
+      nil
+    end
+
+    def short_name(sideload)
+      sideload.resource.class.name&.split("::")&.last
+    rescue
+      nil
+    end
+
+    def inferred_model(resource_class)
+      model = resource_class.model
+      model.is_a?(Class) ? model : nil
+    rescue Errors::ModelNotFound
+      nil
+    end
+
+    def missing_association_method(sideload, model)
+      return unless model
+      return if sideload.type == :polymorphic_belongs_to
+      return if model.method_defined?(sideload.association_name)
+      return if model.private_method_defined?(sideload.association_name)
+
+      Finding.new(
+        severity: :error,
+        check: :missing_association_method,
+        message: "#{model.name} has no ##{sideload.association_name} method",
+        remedy: "define it, point the relationship at the real association with `as:`, or remove the relationship"
+      )
+    end
+
+    def missing_guard_method(resource_class, sideload)
+      guard = sideload.readable_guard_name
+      return unless guard
+      return if defines?(resource_class, guard)
+      return if defines?(sideload.resource.class, guard)
+
+      Finding.new(
+        severity: :error,
+        check: :missing_guard_method,
+        message: "##{guard} is defined on neither #{resource_class.name} nor its related resource",
+        remedy: "define the guard on either resource"
+      )
+    end
+
+    def defines?(resource_class, method_name)
+      resource_class.method_defined?(method_name) ||
+        resource_class.private_method_defined?(method_name)
+    end
+
+    def missing_sideload_filter(sideload)
+      return if builds_its_own_query?(sideload)
+
+      key = sideload_filter_key(sideload)
+      return unless key
+
+      related = sideload.resource.class
+      return if related.filters.key?(key)
+
+      Finding.new(
+        severity: :error,
+        check: :missing_sideload_filter,
+        message: "#{related.name} is missing `filter #{key.inspect}`",
+        remedy: "declare the filter on the related resource"
+      )
+    end
+
+    def builds_its_own_query?(sideload)
+      sideload.class.params_proc || sideload.class.scope_proc
+    end
+
+    def sideload_filter_key(sideload)
+      case sideload.type
+      when :has_many, :has_one then sideload.foreign_key
+      when :many_to_many then sideload.true_foreign_key
+      when :belongs_to then sideload.primary_key
+      end
+    end
+
+    def association_preloaded?(resource_class, sideload)
+      scope = resource_class.new.base_scope
+      return nil unless scope.respond_to?(:includes_values)
+
+      preloads = [scope.includes_values, scope.preload_values, scope.eager_load_values]
+      association_names(preloads).include?(sideload.association_name.to_sym)
+    rescue
+      nil
+    end
+
+    def association_names(preload_values)
+      Array(preload_values).flat_map do |value|
+        case value
+        when Hash then value.keys.map(&:to_sym)
+        when Array then association_names(value)
+        else [value.to_sym]
+        end
+      end
+    end
+  end
+end

data/lib/graphiti/errors.rb

@@ -689,6 +689,53 @@ module Graphiti
       end
     end
 
+    class InvalidBelongsToResourceIds < Base
+      def initialize(resource_class, value)
+        @resource_class = resource_class
+        @value = value
+      end
+
+      def message
+        <<~MSG
+          #{@resource_class.name}: belongs_to_resource_ids_by_default must be one of :foreign_key, :always, or :never. Got #{@value.inspect}.
+
+            :foreign_key - render resource ids wherever the foreign key already holds the related id (default)
+            :always      - render them for every belongs_to, loading the association when the foreign key cannot answer
+            :never       - render none
+
+          To render resource ids for a collection, ask for it one relationship at a time with `resource_ids: true`.
+        MSG
+      end
+    end
+
+    class MissingRelationshipMethod < Base
+      def initialize(resource_class, sideload, model)
+        @resource_class = resource_class
+        @sideload = sideload
+        @model = model
+      end
+
+      def message
+        <<~MSG
+          #{@resource_class.name}: relationship #{@sideload.name.inspect} is declared, but #{@model.class.name} has no ##{@sideload.association_name} method.
+
+          Rendering the relationship reads the association off the model. Define ##{@sideload.association_name} on #{@model.class.name}, point the relationship at the real association with `as:`, or remove the relationship.
+          #{resource_ids_note}
+        MSG
+      end
+
+      private
+
+      def resource_ids_note
+        return "" unless @sideload.render_resource_ids?
+
+        <<~MSG
+
+          resource_ids is set on this relationship, so every render reads the association, not just requests that include it. See www.graphiti.dev/concepts/relationships#customizing-relationships.
+        MSG
+      end
+    end
+
     class MissingDependentFilter < Base
       def initialize(resource, filters)
         @resource = resource

data/lib/graphiti/request_validators/validator.rb

@@ -11,10 +11,12 @@ module Graphiti
       end
 
       def validate
+        validate_page
+
         # Right now, all requests - even reads - go through the validator
         # In the future these should have their own validation logic, but
         # for now we can just bypass
-        return true unless @params.has_key?(:data)
+        return errors.blank? unless @params.has_key?(:data)
 
         resource = @root_resource
         if @params[:data].has_key?(:type)
@@ -47,6 +49,13 @@ module Graphiti
 
       private
 
+      def validate_page
+        page = @params[:page]
+        return if page.nil? || page.respond_to?(:each_pair)
+
+        @errors.add(:page, :invalid, message: "must be an object")
+      end
+
       def process_relationships(resource, relationships, payload_path)
         relationships.each_key do |name|
           unless resource.class.sideload(name.to_sym)

data/lib/graphiti/resource/configuration.rb

@@ -6,6 +6,16 @@ module Graphiti
       DEFAULT_MAX_PAGE_SIZE = 1_000
 
       module Overrides
+        BELONGS_TO_RESOURCE_IDS_VALUES = [:foreign_key, :always, :never].freeze
+
+        def belongs_to_resource_ids_by_default=(val)
+          unless BELONGS_TO_RESOURCE_IDS_VALUES.include?(val)
+            raise Errors::InvalidBelongsToResourceIds.new(self, val)
+          end
+
+          super
+        end
+
         def serializer=(val)
           if val
             if super(Class.new(val))
@@ -21,6 +31,10 @@ module Graphiti
           send(:prepend, Polymorphism)
         end
 
+        def polymorphic?
+          polymorphic.present?
+        end
+
         def type=(val)
           val = val&.to_sym
           if (val = super)
@@ -90,7 +104,7 @@ module Graphiti
           :attributes_schema_by_default,
           :relationships_readable_by_default,
           :relationships_writable_by_default,
-          :always_include_resource_ids_by_default,
+          :belongs_to_resource_ids_by_default,
           :filters_accept_nil_by_default,
           :filters_deny_empty_by_default,
           :graphql_entrypoint,
@@ -116,6 +130,7 @@ module Graphiti
           default(klass, :attributes_schema_by_default, true)
           default(klass, :relationships_readable_by_default, true)
           default(klass, :relationships_writable_by_default, true)
+          default(klass, :belongs_to_resource_ids_by_default, :foreign_key)
           default(klass, :filters_accept_nil_by_default, false)
           default(klass, :filters_deny_empty_by_default, false)
 

data/lib/graphiti/resource/polymorphism.rb

@@ -8,6 +8,8 @@ module Graphiti
       end
 
       def serializer_for(model)
+        return super unless self.class.polymorphic?
+
         if polymorphic_child?
           serializer
         else
@@ -17,10 +19,14 @@ module Graphiti
       end
 
       def associate_all(*args)
+        return super unless self.class.polymorphic?
+
         _associate(:associate_all, *args)
       end
 
       def associate(*args)
+        return super unless self.class.polymorphic?
+
         _associate(:associate, *args)
       end
 
@@ -34,6 +40,8 @@ module Graphiti
 
       module ClassMethods
         def inherited(klass)
+          return super unless polymorphic?
+
           klass.type = nil
           klass.model = klass.infer_model
           klass.endpoint = klass.infer_endpoint
@@ -42,6 +50,8 @@ module Graphiti
         end
 
         def sideload(name)
+          return super unless polymorphic?
+
           if (split_on = name.to_s.split(/^on__/)).length > 1
             on_type, name = split_on[1].split("--").map(&:to_sym)
           end

data/lib/graphiti/schema.rb

@@ -251,7 +251,7 @@ module Graphiti
             schema[:guard] = true
           end
 
-          if config.always_include_resource_ids?
+          if config.render_resource_ids?
             schema[:linkage] = true
           end
 

data/lib/graphiti/sideload/belongs_to.rb

@@ -3,40 +3,33 @@ class Graphiti::Sideload::BelongsTo < Graphiti::Sideload
     :belongs_to
   end
 
-  def default_include_resource_ids?
-    linkage_from_foreign_key?
+  def default_render_resource_ids?
+    case parent_resource_class&.belongs_to_resource_ids_by_default
+    when :always then renderable_at_all?
+    when :never then false
+    else resource_ids_from_foreign_key?
+    end
+  end
+
+  def renderable_at_all?
+    readable_guarded? || readable?
   end
 
-  # The parent already carries the foreign key, and for a plain belongs_to
-  # that key *is* the related id, so linkage costs nothing. Anything that can
-  # change which record the relationship resolves to, or what type it carries,
-  # has to load the association instead:
-  #
-  #   - a scope/params block or a base_scope can filter out the record the
-  #     foreign key points at, so the key would claim a relationship the API
-  #     would not actually return
-  #   - a polymorphic target takes its type from the record, not from the
-  #     relationship, so the key alone cannot say what type the id has
-  #   - a remote resource has no local foreign key to read
-  #   - a custom primary_key points the relationship at some other column, so
-  #     the key holds that column's value rather than the related id
-  def linkage_from_foreign_key?
-    # Ask before resolving #resource: an unreadable relationship renders
-    # nothing, and its resource class may not even be inferrable.
-    return false unless readable?
-    return false unless foreign_key_is_related_id?
-    return false if polymorphic_child?
-    return false if self.class.scope_proc || self.class.params_proc
-    return false if @base_scope
-    return false if remote?
-    return false if resource.class.polymorphic.present?
+  def resource_ids_blocker
+    return :unreadable unless renderable_at_all?
+    return :custom_primary_key unless foreign_key_is_related_id?
+    return :polymorphic_child if polymorphic_child?
+    return :scope_block if self.class.scope_proc
+    return :params_block if self.class.params_proc
+    return :base_scope if @base_scope
+    return :remote if remote?
+    return :polymorphic_resource if resource.class.polymorphic.present?
 
-    true
+    nil
   end
 
-  # The foreign key can stand in for the related id only when the two hold the
-  # same value. base_filter matches the key against primary_key, so pointing
-  # that at another column means the key holds that column instead.
+  # base_filter matches the foreign key against primary_key, so a custom
+  # primary_key means the key holds that column's value, not the related id.
   def foreign_key_is_related_id?
     primary_key == :id
   end

data/lib/graphiti/sideload.rb

@@ -20,6 +20,7 @@ module Graphiti
     def initialize(name, opts)
       @name = name
       validate_options!(opts)
+      translate_deprecated_options!(opts)
       @parent_resource_class = opts[:parent_resource]
       @resource_class_name = opts[:resource]
       @primary_key = opts[:primary_key]
@@ -42,7 +43,7 @@ module Graphiti
       @group_name = opts[:group_name]
       @polymorphic_child = opts[:polymorphic_child]
       @parent = opts[:parent]
-      @always_include_resource_ids = opts[:always_include_resource_ids]
+      @render_resource_ids = opts[:resource_ids]
 
       if polymorphic_child?
         parent.resource.polymorphic << resource_class
@@ -110,6 +111,31 @@ module Graphiti
       dynamic_flag?(@readable) || dynamic_flag?(@writable)
     end
 
+    def readable_guarded?
+      dynamic_flag?(@readable)
+    end
+
+    def readable_guard_name
+      @readable.to_sym if @readable.is_a?(Symbol) || @readable.is_a?(String)
+    end
+
+    def non_default_options
+      options = {}
+      options[:as] = association_name if @as
+      options[:primary_key] = primary_key unless primary_key == :id
+      options[:single] = true if single?
+      options[:remote] = @remote if remote?
+      options[:link] = @link unless @link.nil?
+      options[:readable] = @readable unless @readable.nil? || @readable == true
+      options[:writable] = @writable unless @writable.nil? || @writable == true
+      options[:resource_ids] = @render_resource_ids unless @render_resource_ids.nil?
+      options
+    end
+
+    def customized_base_scope?
+      !!@base_scope
+    end
+
     def single?
       !!@single
     end
@@ -122,24 +148,21 @@ module Graphiti
       !!@polymorphic_as
     end
 
-    # False everywhere but a plain belongs_to - see
-    # Sideload::BelongsTo#linkage_from_foreign_key?.
-    def linkage_from_foreign_key?
-      false
+    def resource_ids_from_foreign_key?
+      resource_ids_blocker.nil?
     end
 
-    # nil at either of the first two levels means "not specified" rather
-    # than "false".
-    def always_include_resource_ids?
-      return !!@always_include_resource_ids unless @always_include_resource_ids.nil?
+    def resource_ids_blocker
+      :no_foreign_key_on_parent
+    end
 
-      configured = parent_resource_class&.always_include_resource_ids_by_default
-      return !!configured unless configured.nil?
+    def render_resource_ids?
+      return !!@render_resource_ids unless @render_resource_ids.nil?
 
-      default_include_resource_ids?
+      default_render_resource_ids?
     end
 
-    def default_include_resource_ids?
+    def default_render_resource_ids?
       false
     end
 
@@ -434,6 +457,18 @@ module Graphiti
       false
     end
 
+    def translate_deprecated_options!(opts)
+      return unless opts.key?(:always_include_resource_ids)
+
+      Graphiti::DEPRECATOR.deprecation_warning(
+        :always_include_resource_ids,
+        "Use :resource_ids instead (#{opts[:parent_resource]&.name}##{@name})"
+      )
+
+      value = opts.delete(:always_include_resource_ids)
+      opts[:resource_ids] = value unless opts.key?(:resource_ids)
+    end
+
     def validate_options!(opts)
       if opts[:remote]
         if opts[:resource]

data/lib/graphiti/util/serializer_relationships.rb

@@ -68,9 +68,9 @@ module Graphiti
           # sideload can resolve it to something the foreign key alone would
           # not predict, so the loaded records win. Only the un-included case
           # is worth short-circuiting.
-          if sideload_ref.linkage_from_foreign_key? &&
+          if sideload_ref.resource_ids_from_foreign_key? &&
               !self_ref.send(:included_anywhere?, @proxy.query.include_hash, sideload_ref.name)
-            linkage always: sideload_ref.always_include_resource_ids? do
+            linkage always: sideload_ref.render_resource_ids? do
               foreign_key = @object.public_send(sideload_ref.foreign_key)
 
               unless foreign_key.nil?
@@ -81,7 +81,7 @@ module Graphiti
               end
             end
           else
-            linkage always: sideload_ref.always_include_resource_ids?
+            linkage always: sideload_ref.render_resource_ids?
           end
 
           if link_ref
@@ -107,8 +107,31 @@ module Graphiti
 
       def data_proc
         sideload_ref = @sideload
+        resource_class_ref = @resource_class
         ->(_) {
-          if (records = @object.public_send(sideload_ref.association_name))
+          begin
+            records = @object.public_send(sideload_ref.association_name)
+          rescue NoMethodError => error
+            # #receiver raises ArgumentError when the error was built by hand
+            # rather than raised by a failed call, and a hand-built one can
+            # still carry a matching #name.
+            receiver = begin
+              error.receiver
+            rescue ArgumentError
+              nil
+            end
+
+            raise unless error.name == sideload_ref.association_name &&
+              receiver.equal?(@object)
+
+            # A private method exists, so "has no such method" would be a lie.
+            raise if @object.respond_to?(sideload_ref.association_name, true)
+
+            raise Errors::MissingRelationshipMethod
+              .new(resource_class_ref, sideload_ref, @object)
+          end
+
+          if records
             if records.respond_to?(:to_ary)
               records.each { |r| sideload_ref.resource.decorate_record(r) }
             else

data/lib/graphiti/version.rb

@@ -1,3 +1,3 @@
 module Graphiti
-  VERSION = "2.0.0.beta.5"
+  VERSION = "2.0.0.beta.6"
 end

data/lib/graphiti.rb

@@ -166,6 +166,8 @@ require "graphiti/configuration"
 require "graphiti/context"
 require "graphiti/errors"
 require "graphiti/types"
+require "graphiti/audit"
+require "graphiti/audit/report"
 require "graphiti/schema"
 require "graphiti/schema_diff"
 require "graphiti/adapters/abstract"

data/lib/tasks/graphiti.rake

@@ -16,6 +16,15 @@ namespace :graphiti do
     Graphiti::Debugger.flush if debug
   end
 
+  desc "Audit every relationship: what will raise, what loads to render ids, which render no ids, and which checks passed."
+  task audit: [:environment] do
+    helpers.setup_rails!
+    rows = Graphiti::Audit.run
+    puts Graphiti::Audit::Report.new(rows).to_s
+
+    exit 1 if rows.any?(&:error?)
+  end
+
   desc "Execute benchmark without web server."
   task :benchmark, [:path, :requests] => [:environment] do |_, args|
     helpers.setup_rails!

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: graphiti
 version: !ruby/object:Gem::Version
-  version: 2.0.0.beta.5
+  version: 2.0.0.beta.6
 platform: ruby
 authors:
 - Lee Richmond
@@ -335,6 +335,8 @@ files:
 - lib/graphiti/adapters/graphiti_api.rb
 - lib/graphiti/adapters/null.rb
 - lib/graphiti/adapters/persistence/associations.rb
+- lib/graphiti/audit.rb
+- lib/graphiti/audit/report.rb
 - lib/graphiti/cli.rb
 - lib/graphiti/configuration.rb
 - lib/graphiti/context.rb