brainstem 1.0.0.pre.1 → 1.0.0

data/spec/brainstem/api_docs/formatters/markdown/endpoint_collection_formatter_spec.rb

@@ -0,0 +1,85 @@
+require 'spec_helper'
+require 'brainstem/api_docs/formatters/markdown/endpoint_collection_formatter'
+require 'brainstem/api_docs/endpoint_collection'
+
+module Brainstem
+  module ApiDocs
+    module Formatters
+      module Markdown
+        describe EndpointCollectionFormatter do
+          let(:atlas)               { Object.new }
+          let(:endpoint_collection) { EndpointCollection.new(atlas) }
+          let(:nodoc)               { false }
+
+          subject { described_class.new(endpoint_collection) }
+
+          describe "#call" do
+            it "formats each endpoint" do
+              mock(subject).format_endpoints!
+              stub(subject).format_zero_text!
+              subject.call
+            end
+
+            context "when has content" do
+              before do
+                stub(subject).output { "not empty" }
+              end
+
+              it "does not format zero text" do
+                dont_allow(subject).format_zero_text!
+                subject.call
+              end
+            end
+
+            context "when no content" do
+              it "formats zero text" do
+                stub(subject).format_endpoints!
+                mock(subject).format_zero_text!
+                subject.call
+              end
+            end
+          end
+
+
+          describe "formatting" do
+            describe "#format_endpoints!" do
+              it "joins each documentable endpoint" do
+                mock(subject).all_formatted_endpoints { ["thing 1", "thing 2"] }
+                subject.send(:format_endpoints!)
+                expect(subject.output).to eq "thing 1-----\n\nthing 2"
+              end
+            end
+
+
+            describe "#format_zero_text!" do
+              it "appends the zero text" do
+                subject.send(:format_zero_text!)
+                expect(subject.output).to eq "No endpoints were found."
+              end
+            end
+          end
+
+
+          describe "#all_formatted_endpoints" do
+            it "retrieves all formatted endpoints" do
+              documentable_collection = Object.new
+              mock(documentable_collection).formatted(:markdown) { [] }
+              stub(endpoint_collection).only_documentable { documentable_collection }
+              subject.send(:all_formatted_endpoints)
+            end
+
+            it "rejects blank endpoints" do
+              stub(endpoint_collection).only_documentable
+                .stub!.formatted(:markdown) { [ "thing 1", "", "thing 3" ] }
+
+              expect(subject.send(:all_formatted_endpoints)).to \
+                eq [ "thing 1", "thing 3" ]
+            end
+          end
+        end
+
+
+      end
+    end
+  end
+end

data/spec/brainstem/api_docs/formatters/markdown/endpoint_formatter_spec.rb

@@ -0,0 +1,261 @@
+require 'spec_helper'
+require 'brainstem/api_docs/formatters/markdown/endpoint_formatter'
+require 'brainstem/api_docs/endpoint'
+
+module Brainstem
+  module ApiDocs
+    module Formatters
+      module Markdown
+        describe EndpointFormatter do
+          let(:controller)    { Object.new }
+          let(:atlas)         { Object.new }
+          let(:endpoint)      { Endpoint.new(atlas, {controller: controller }.merge(endpoint_args)) }
+          let(:endpoint_args) { {} }
+          let(:nodoc)         { false }
+
+          subject { described_class.new(endpoint) }
+
+          describe "#call" do
+            before do
+              stub(endpoint).nodoc? { nodoc }
+            end
+
+            context "when it is nodoc" do
+              let(:nodoc) { true }
+
+              before do
+                any_instance_of(described_class) do |instance|
+                  dont_allow(instance).format_title!
+                  dont_allow(instance).format_description!
+                  dont_allow(instance).format_endpoint!
+                  dont_allow(instance).format_params!
+                  dont_allow(instance).format_presents!
+                end
+              end
+
+              it "returns an empty output" do
+                expect(subject.call).to eq ""
+              end
+            end
+
+            context "when it is not nodoc" do
+              it "formats title, description, endpoint, params, and presents" do
+                any_instance_of(described_class) do |instance|
+                  mock(instance).format_title!
+                  mock(instance).format_description!
+                  mock(instance).format_endpoint!
+                  mock(instance).format_params!
+                  mock(instance).format_presents!
+                end
+
+                subject.call
+              end
+            end
+          end
+
+          describe "formatting" do
+            let(:lorem)           { "lorem ipsum dolor sit amet" }
+            let(:default_config)  { {} }
+            let(:show_config)     { {} }
+
+            let(:configuration)   { {
+              :_default => default_config,
+              :show => show_config,
+            } }
+
+            let(:endpoint_args) { { action: :show } }
+
+            before do
+              stub(controller).configuration { configuration }
+            end
+
+            describe "#format_title!" do
+              it "prints it as an h4" do
+                stub(endpoint).title { lorem }
+                mock(subject).md_h4(lorem) { lorem }
+                subject.send(:format_title!)
+                expect(subject.output).to eq lorem
+              end
+            end
+
+
+            describe "#format_description!" do
+              context "when present" do
+                before do
+                  stub(endpoint).description { lorem }
+                end
+
+                it "prints it as a p" do
+                  mock(subject).md_p(lorem) { lorem }
+                  subject.send(:format_description!)
+                  expect(subject.output).to eq lorem
+                end
+              end
+
+              context "when absent" do
+                before do
+                  stub(endpoint).description { "" }
+                end
+
+                it "prints nothing" do
+                  dont_allow(subject).md_p
+                  subject.send(:format_description!)
+                  expect(subject.output).to eq ""
+                end
+
+              end
+            end
+
+
+            describe "#format_endpoint!" do
+              let(:endpoint_args) { { http_methods: %w(get post), path: "/widgets(.:format)" } }
+
+              it "formats it as code, subbing the appropriate format" do
+                mock(subject).md_code("GET / POST /widgets.json") { lorem }
+                subject.send(:format_endpoint!)
+                expect(subject.output).to eq lorem
+              end
+
+              it "includes the joined HTTP methods" do
+                subject.send(:format_endpoint!)
+                expect(subject.output).to include "GET / POST"
+              end
+
+              it "includes the path" do
+                subject.send(:format_endpoint!)
+                expect(subject.output).to include "/widgets"
+              end
+            end
+
+
+            describe "#format_params!" do
+              before do
+                subject.send(:format_params!)
+              end
+
+
+              context "with valid params" do
+                let(:show_config) { {
+                  valid_params: {
+                    only: { info: "which ids to include", nodoc: nodoc },
+                    sprocket_id: { info: "the id of the sprocket", root: "widget", nodoc: nodoc },
+                    sprocket_child: { recursive: true, legacy: false, info: "it does the thing", root: "widget" },
+                  }
+                } }
+
+                context "when nodoc" do
+                  let(:nodoc) { true }
+
+                  it "removes them from the list" do
+                    expect(subject.output).to include "`widget`"
+                    expect(subject.output).to include "`sprocket_child`"
+                    expect(subject.output).not_to include "`sprocket_id`"
+                    expect(subject.output).not_to include "`only`"
+                  end
+                end
+
+                context "when not nodoc" do
+                  it "outputs a header" do
+                    expect(subject.output).to include "Valid Parameters"
+                  end
+
+                  it "spits each root item out as a list item" do
+                    expect(subject.output.scan(/\n-/).count).to eq 2
+                  end
+
+                  it "makes the key an inline code block" do
+                    expect(subject.output).to include "`sprocket_id`"
+                  end
+
+                  context "for non-root params" do
+                    it "outputs sub params under a list item" do
+                      expect(subject.output).to include "- `widget`\n    - `sprocket_id` - the id of the sprocket\n    - `sprocket_child`"
+                    end
+                  end
+
+                  it "includes the info on a hash key" do
+                    expect(subject.output).to include "`sprocket_child` - it does the thing"
+                  end
+
+                  it "includes the recursivity if specified" do
+                    expect(subject.output).to include "Recursive: true"
+                  end
+
+                  it "includes the legacy status if specified" do
+                    expect(subject.output).to include "Legacy: false"
+                  end
+                end
+              end
+
+
+              context "with only default params" do
+                let(:default_config) { {
+                  valid_params: {
+                    sprocket_name: {
+                      info: "the name of the sprocket",
+                      nodoc: nodoc
+                    }
+                  }
+                } }
+
+                context "when nodoc" do
+                  let(:nodoc) { true }
+
+                  it "shows no parameters" do
+                    expect(subject.output).to eq ""
+                  end
+                end
+
+                context "when not nodoc" do
+                  it "falls back to the default" do
+                    expect(subject.output).to include "`sprocket_name` - the name of the sprocket"
+                  end
+                end
+              end
+
+              context "with no valid params" do
+                it "outputs nothing" do
+                  expect(subject.output).to eq ""
+                end
+              end
+
+            end
+
+
+            describe "#format_presents!" do
+              let(:presenter) { Object.new }
+
+              before do
+                stub(endpoint).presenter_title { "Sprocket Widget" }
+                stub(endpoint).relative_presenter_path_from_controller(:markdown) { "../../sprocket_widget.markdown" }
+              end
+
+              context "when present" do
+                before do
+                  stub(endpoint).presenter { presenter }
+                end
+
+                it "outputs a header" do
+                  subject.send(:format_presents!)
+                  expect(subject.output).to include "Data Model"
+                end
+
+                it "displays a link" do
+                  subject.send(:format_presents!)
+                  expect(subject.output).to include "[Sprocket Widget](../../sprocket_widget.markdown)"
+                end
+              end
+
+              context "when not present" do
+                it "does not output anything" do
+                  subject.send(:format_presents!)
+                  expect(subject.output).not_to include "Data Model"
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/spec/brainstem/api_docs/formatters/markdown/helper_spec.rb

@@ -0,0 +1,100 @@
+require 'spec_helper'
+require 'brainstem/api_docs/formatters/markdown/helper'
+
+module Brainstem
+  module ApiDocs
+    module Formatters
+      module Markdown
+        describe "Helper" do
+          let(:klass) { Class.new { include Helper } }
+
+          let(:lipsum) { "Lorem ipsum dolor sit amet, nulla primis tritani id qui. Eam elitr prodesset in, ne nec nibh elit impedit. Inani rationibus mnesarchum ei vix, at has eligendi scripserit. Vel vidit semper ea. Id ullum scaevola adversarium eum, vide brute mucius ut has." }
+          let(:lipsum_split_80) { [
+            "Lorem ipsum dolor sit amet, nulla primis tritani id qui. Eam elitr prodesset in,",
+            "ne nec nibh elit impedit. Inani rationibus mnesarchum ei vix, at has eligendi",
+            "scripserit. Vel vidit semper ea. Id ullum scaevola adversarium eum, vide brute",
+            "mucius ut has."
+          ] }
+
+          subject { klass.new }
+
+          1.upto(5) do |num|
+            describe "#md_h#{num}" do
+              it "renders text with #{num} # and two newlines" do
+                expect(subject.send("md_h#{num}", "title")).to eq "#{"#" * num} title\n\n"
+              end
+            end
+          end
+
+          describe "#md_hr" do
+            it "renders five dashes and two newlines" do
+              expect(subject.md_hr).to eq "-----\n\n"
+            end
+          end
+
+
+          describe "#md_p" do
+            it "appends two newlines" do
+              expect(subject.md_p(lipsum)).to eq(lipsum + "\n\n")
+            end
+          end
+
+
+          describe "#md_strong" do
+            it "wraps the text in asterisk pairs" do
+              expect(subject.md_strong("Popeye")).to eq "**Popeye**"
+            end
+          end
+
+
+          describe "#md_code" do
+            it "renders the code between backtick blocks" do
+              expect(subject.md_code('var my_var = 1;')).to eq "```\nvar my_var = 1;\n```\n\n"
+            end
+
+            it "allows specifying a language" do
+              expect(subject.md_code('puts "Hi!"', 'ruby')).to eq %Q{```ruby\nputs "Hi!"\n```\n\n}
+            end
+          end
+
+
+          describe "#md_inline_code" do
+            it "renders the code between single backticks" do
+              expect(subject.md_inline_code('my_var')).to eq "`my_var`"
+            end
+          end
+
+
+          describe "#md_ul" do
+            it "evaluates the block given to it in the instance's context" do
+              mock(subject).md_h1('hello') { }
+              subject.md_ul { md_h1("hello") }
+            end
+
+            it "appends two newlines to the end of the list" do
+              expect(subject.md_ul { nil }).to eq "\n\n"
+            end
+          end
+
+
+          describe "#md_li" do
+            it "renders the text after a dash-space with a newline" do
+              expect(subject.md_li("text")).to eq "- text\n"
+            end
+
+            it "allows specifying the indent" do
+              expect(subject.md_li("text", 1)).to eq "    - text\n"
+            end
+          end
+
+
+          describe "#md_a" do
+            it "renders the text in a bracket and includes a link in parens" do
+              expect(subject.md_a("text", "link.md")).to eq "[text](link.md)"
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/spec/brainstem/api_docs/formatters/markdown/presenter_formatter_spec.rb

@@ -0,0 +1,485 @@
+require 'spec_helper'
+require 'brainstem/api_docs/formatters/markdown/presenter_formatter'
+require 'brainstem/api_docs/presenter'
+
+module Brainstem
+  module ApiDocs
+    module Formatters
+      module Markdown
+        describe PresenterFormatter do
+          let(:presenter_args)       { {} }
+          let(:extra_presenter_args) { {} }
+          let(:presenter)            { Presenter.new(presenter_args.merge(extra_presenter_args)) }
+          let(:nodoc)                { false }
+
+          subject { described_class.new(presenter) }
+
+          describe "#call" do
+            before do
+              stub(presenter).nodoc? { nodoc }
+            end
+
+            context "when nodoc" do
+              let(:nodoc) { true }
+
+              it "returns an empty output" do
+                any_instance_of(described_class) do |instance|
+                  dont_allow(instance).format_title!
+                  dont_allow(instance).format_brainstem_keys!
+                  dont_allow(instance).format_description!
+                  dont_allow(instance).format_fields!
+                  dont_allow(instance).format_filters!
+                  dont_allow(instance).format_sort_orders!
+                  dont_allow(instance).format_associations!
+                end
+
+                expect(subject.call).to eq ""
+              end
+            end
+
+            context "when not nodoc" do
+              it "formats title, brainstem_keys, description, conditionals, fields, filters, sort_orders, and associations" do
+                any_instance_of(described_class) do |instance|
+                  mock(instance).format_title!
+                  mock(instance).format_brainstem_keys!
+                  mock(instance).format_description!
+                  mock(instance).format_fields!
+                  mock(instance).format_filters!
+                  mock(instance).format_sort_orders!
+                  mock(instance).format_associations!
+                end
+
+                subject.call
+              end
+            end
+          end
+
+
+          describe "formatting" do
+            let(:lorem) { "lorem ipsum dolor sit amet" }
+
+            describe "#format_title!" do
+              context "with title" do
+                it "prints it as an h4" do
+                  stub(presenter).title { lorem }
+                  mock(subject).md_h4(lorem) { lorem }
+                  subject.send(:format_title!)
+                  expect(subject.output).to eq lorem
+                end
+              end
+            end
+
+
+            describe "#format_brainstem_keys!" do
+              before do
+                stub(presenter).brainstem_keys { [ "sprockets", "widgets" ] }
+              end
+
+              it "outputs it" do
+                subject.send(:format_brainstem_keys!)
+                expect(subject.output).to include "Top-level key: `sprockets` / `widgets`"
+              end
+            end
+
+
+            describe "#format_description!" do
+              context "when present" do
+                before do
+                  stub(presenter).description { lorem }
+                end
+
+                it "prints it as a p" do
+                  mock(subject).md_p(lorem) { lorem }
+                  subject.send(:format_description!)
+                  expect(subject.output).to eq lorem
+                end
+              end
+
+              context "when absent" do
+                before do
+                  stub(presenter).description { "" }
+                end
+
+                it "prints nothing" do
+                  dont_allow(subject).md_p
+                  subject.send(:format_description!)
+                  expect(subject.output).to eq ""
+                end
+              end
+            end
+
+
+            describe "#format_fields!" do
+              let(:valid_fields) { {} }
+              let(:conditionals) { {} }
+              let(:optional)     { false }
+
+              let(:sprocket_name_long) { OpenStruct.new(
+                name:        :sprocket_name,
+                description: lorem,
+                options:     { via: :name },
+                type:        :string
+              ) }
+
+              let(:sprocket_name_short) { OpenStruct.new(
+                name:    :sprocket_name,
+                type:    :string,
+                options: { }
+              ) }
+
+              before do
+                stub(sprocket_name_long).optional?  { optional }
+                stub(sprocket_name_short).optional? { optional }
+                stub(presenter).conditionals        { conditionals }
+                stub(presenter).valid_fields        { valid_fields }
+                subject.send(:format_fields!)
+              end
+
+              it "outputs a header" do
+                expect(subject.output).to include "Fields"
+              end
+
+              context "with fields present" do
+                context "branch node" do
+                  context "with single branch" do
+                    let(:valid_fields) { { sprockets: { name: sprocket_name_long } } }
+
+                    it "outputs the name of the branch as a list item" do
+                      expect(subject.output.scan(/\n-/).count).to eq 1
+                      expect(subject.output.scan(/\n    -/).count).to eq 1
+                      expect(subject.output.scan(/\n        -/).count).to eq 1
+                    end
+
+                    it "outputs the child nodes as sub-list items" do
+                      expect(subject.output).to \
+                        include("\n- `sprockets`\n    - `sprocket_name`")
+                    end
+                  end
+
+                  context "with sub-branch" do
+                    let(:valid_fields) { { sprockets: { sub_sprocket: { name: sprocket_name_long } } } }
+
+                    it "outputs the name of sub-branches as a sub-list item" do
+                      expect(subject.output.scan(/\n-/).count).to eq 1
+                      expect(subject.output.scan(/\n    -/).count).to eq 1
+                      expect(subject.output.scan(/\n        -/).count).to eq 1
+                      expect(subject.output.scan(/\n            -/).count).to eq 1
+                    end
+
+                    it "outputs the child nodes as sub-list items" do
+                      expect(subject.output).to \
+                        include("\n- `sprockets`\n    - `sub_sprocket`\n        - `sprocket_name`")
+                    end
+                  end
+                end
+
+                context "leaf node" do
+                  let(:valid_fields) { { sprocket_name: sprocket_name_long } }
+
+                  context "if it is not conditional" do
+                    it "outputs each field as a list item" do
+                      expect(subject.output.scan(/\n-/).count).to eq 1
+                    end
+
+                    it "outputs each field's name" do
+                      expect(subject.output).to include "sprocket_name"
+                    end
+
+                    it "outputs each field's type" do
+                      expect(subject.output).to include "`sprocket_name` (`String`)"
+                    end
+
+                    describe "optional" do
+                      context "when true" do
+                        let(:optional) { true }
+
+                        it "says so" do
+                          expect(subject.output).to include "only returned when requested"
+                        end
+
+                      end
+
+                      context "when false" do
+                        it "says nothing" do
+                          expect(subject.output).not_to include "Only returned when requested"
+                        end
+                      end
+                    end
+
+                    describe "description" do
+                      context "when present" do
+                        it "outputs the description" do
+                          expect(subject.output).to include "    - #{lorem}"
+                        end
+                      end
+
+                      context "when absent" do
+                        let(:valid_fields) { { sprocket_name: sprocket_name_short } }
+
+                        it "does not include the description" do
+                          expect(subject.output).not_to include "    -"
+                        end
+                      end
+                    end
+                  end
+
+
+                  context "if it is conditional" do
+                    let(:sprocket_name_long) { OpenStruct.new(
+                      name: :sprocket_name,
+                      description: lorem,
+                      options: { via: :name, if: [:it_is_a_friday] },
+                      type: :string
+                    ) }
+
+                    context "if nodoc" do
+                      let(:conditionals) { {
+                        :it_is_a_friday => OpenStruct.new(
+                          description: nil,
+                          name: :it_is_a_friday,
+                          type: :request,
+                          options: { nodoc: true }
+                        )
+                      } }
+
+                      it "does not include the conditional" do
+                        expect(subject.output).not_to include "visible when"
+                      end
+                    end
+
+                    context "if not nodoc" do
+                      context "if the conditional has a description" do
+                        let(:conditionals) { {
+                          :it_is_a_friday => OpenStruct.new(
+                            description: "it is a friday",
+                            name: :it_is_a_friday,
+                            type: :request,
+                            options: {},
+                          )
+                        } }
+
+                        it "includes the conditional" do
+                          expect(subject.output).to include "\n    - visible when it is a friday"
+                        end
+                      end
+
+                      context "if the condition doesn't have a description" do
+                        let(:conditionals) { {
+                          :it_is_a_friday => OpenStruct.new(
+                            description: nil,
+                            name: :it_is_a_friday,
+                            type: :request,
+                            options: {},
+                          )
+                        } }
+
+                        it "does not include the conditional" do
+                          expect(subject.output).not_to include "visible when"
+                        end
+                      end
+                    end
+                  end
+                end
+              end
+
+              context "with no fields" do
+                it "outputs that no fields were listed" do
+                  subject.send(:format_fields!)
+                  expect(subject.output).to include "No fields were listed"
+                end
+              end
+            end
+
+
+            describe "#format_filters!" do
+              let(:valid_filters) { {} }
+
+              before do
+                stub(presenter).valid_filters { valid_filters }
+                subject.send(:format_filters!)
+              end
+
+              context "when has filters" do
+                let(:valid_filters) {
+                  {
+                    "published" => {
+                      value: Proc.new { nil },
+                      info: "limits to published"
+                    }
+                  }
+                }
+
+                it "outputs a header" do
+                  expect(subject.output).to include "Filters"
+                end
+
+                it "lists them" do
+                  expect(subject.output.scan(/\n-/).count).to eq 1
+                  expect(subject.output).to include "`published`"
+                  expect(subject.output).to include "    - limits to published"
+                end
+              end
+
+              context "when no filters" do
+                it "says nothing" do
+                  expect(subject.output).to_not include "Filters"
+                end
+              end
+            end
+
+
+            describe "format_sort_orders!" do
+              before do
+                stub(presenter).valid_sort_orders { sort_orders }
+                stub(presenter).default_sort_field { "alphabetical" }
+                stub(presenter).default_sort_direction { "asc" }
+              end
+
+              let(:sort_orders) { {
+                "created_at" => {
+                  value: "sprockets.created_at"
+                },
+                "alphabetical" => {
+                  value: "sprockets.name",
+                  info: "it sorts by name"
+                },
+              } }
+
+              before do
+                subject.send(:format_sort_orders!)
+              end
+
+              context "when has sort orders defined" do
+                it "outputs a header" do
+                  expect(subject.output).to include "Sort Orders"
+                end
+
+                it "lists the sort orders with the default first" do
+                  expect(subject.output.scan(/\n-/).count).to eq 2
+                  expect(subject.output).to match /alphabetical.*created_at/m
+                end
+
+                it "outputs the doc string" do
+                  expect(subject.output).to include "    - it sorts by name"
+                end
+
+                context "when it has a default sort order" do
+                  it "inlines the default" do
+                    expect(subject.output).to include "`alphabetical` - **default** (asc)"
+                  end
+                end
+              end
+
+              context "when has no sort orders defined" do
+                let(:sort_orders) { {} }
+
+                it "says nothing" do
+                  expect(subject.output).to_not include "Sort Orders"
+                end
+              end
+            end
+
+
+            describe "format_associations!" do
+              let(:associations) { {} }
+              let(:link) { nil }
+
+              before do
+                stub(presenter).valid_associations { associations }
+                stub(presenter).link_for_association(anything) { link }
+                subject.send(:format_associations!)
+              end
+
+              context "when has associations" do
+                let(:associations) {
+                  {
+                    "widgets" => OpenStruct.new(
+                      name: "widgets",
+                      description: "these are some widgets you might find relevant",
+                      target_class: "Widget"
+                    )
+                  }
+                }
+
+                it "outputs a header" do
+                  expect(subject.output).to include "Associations"
+                end
+
+                context "when has static target class" do
+                  let(:link) { "./path" }
+
+                  it "links them" do
+                    expect(subject.output).to include "[Widget](./path)"
+                  end
+                end
+
+                context "when has polymorphic target class or presenter was not found" do
+                  let(:link) { nil }
+
+                  it "lists them" do
+                    expect(subject.output).to include "`widgets`"
+                  end
+
+                  it "does not render a link" do
+                    expect(subject.output).to_not include "[Widget]"
+                  end
+                end
+
+                describe "description" do
+                  context "when present" do
+                    it "lists it" do
+                      expect(subject.output).to include "these are some widgets"
+                    end
+                  end
+                end
+
+                describe "restrict_to_only" do
+                  context "when present and true" do
+                    let(:associations) {
+                      {
+                        "widgets" => OpenStruct.new(
+                          name: "widgets",
+                          description: "these are some widgets you might find relevant",
+                          options: { restrict_to_only: true }
+                        )
+                      }
+                    }
+
+                    it "lists it" do
+                      expect(subject.output).to include "Restricted to queries using"
+                    end
+
+                    it "adds a period at the end of the description if there is none" do
+                      expect(subject.output).to include "you might find relevant.  Restricted to queries using"
+                    end
+                  end
+
+                  context "when absent or false" do
+                    let(:associations) {
+                      {
+                        "widgets" => OpenStruct.new(
+                          name: "widgets",
+                          options: { restrict_to_only: false }
+                        )
+                      }
+                    }
+
+                    it "doesn't show it" do
+                      expect(subject.output).not_to include "Restricted to queries using"
+                    end
+                  end
+                end
+              end
+
+              context "when no associations" do
+                it "says nothing" do
+                  expect(subject.output).to_not include "Associations"
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end