brainstem 1.0.0.pre.1 → 1.0.0

data/spec/brainstem/dsl/association_spec.rb

@@ -5,8 +5,24 @@ describe Brainstem::DSL::Association do
   let(:name) { :user }
   let(:target_class) { User }
   let(:description) { "This object's user" }
-  let(:options) { { } }
-  let(:association) { Brainstem::DSL::Association.new(name, target_class, description, options) }
+  let(:options) { { info: description } }
+  let(:association) { Brainstem::DSL::Association.new(name, target_class, options) }
+
+  describe 'description' do
+    context 'when `info` is specified in the options' do
+      it 'returns the value specified with the info key' do
+        expect(association.description).to eq(description)
+      end
+    end
+
+    context 'when `info` is not specified in the options' do
+      let(:options) { {} }
+
+      it 'returns nil' do
+        expect(association.description).to be_nil
+      end
+    end
+  end
 
   describe "#run_on" do
     let(:context) { { } }

data/spec/brainstem/dsl/conditional_spec.rb

@@ -2,8 +2,31 @@ require 'spec_helper'
 require 'brainstem/dsl/conditional'
 
 describe Brainstem::DSL::Conditional do
-  let(:conditional) { Brainstem::DSL::Conditional.new(name, type, action, description) }
+  let(:conditional) { Brainstem::DSL::Conditional.new(name, type, action, options) }
   let(:model) { Workspace.first }
+  let(:options) { { info: description } }
+
+  describe 'description' do
+    let(:name) { :title_is_hello }
+    let(:type) { :model }
+    let(:action) { lambda { |model| model.title == 'hello' } }
+
+    context 'when `info` is specified in the options' do
+      let(:description) { 'visible when the title is hello' }
+
+      it 'returns the value specified with the info key' do
+        expect(conditional.description).to eq(description)
+      end
+    end
+
+    context 'when `info` is not specified in the options' do
+      let(:options) { {} }
+
+      it 'returns nil' do
+        expect(conditional.description).to be_nil
+      end
+    end
+  end
 
   describe '.matches?' do
     context 'as a :model conditional' do
@@ -90,4 +113,4 @@ describe Brainstem::DSL::Conditional do
       end
     end
   end
-end
+end

data/spec/brainstem/dsl/configuration_spec.rb

@@ -1 +1 @@
-# This is tested in concerns/inheritable_configuration_spec.rb
+# This is tested in concerns/inheritable_configuration_spec.rb

data/spec/brainstem/dsl/field_spec.rb

@@ -5,10 +5,26 @@ describe Brainstem::DSL::Field do
   let(:name) { :title }
   let(:type) { :string }
   let(:description) { 'the title of this model' }
-  let(:options) { { } }
-  let(:field) { Brainstem::DSL::Field.new(name, type, description, options) }
+  let(:options) { { info: description } }
+  let(:field) { Brainstem::DSL::Field.new(name, type, options) }
   let(:model) { Workspace.first }
 
+  describe 'description' do
+    context 'when `info` is specified in the options' do
+      it 'returns the value specified with the info key' do
+        expect(field.description).to eq(description)
+      end
+    end
+
+    context 'when `info` is not specified in the options' do
+      let(:options) { {} }
+
+      it 'returns nil' do
+        expect(field.description).to be_nil
+      end
+    end
+  end
+
   describe '#method_name' do
     describe 'by default' do
       it 'returns the name' do

data/spec/brainstem/presenter_collection_spec.rb

@@ -615,14 +615,22 @@ describe Brainstem::PresenterCollection do
           WorkspacePresenter.filter(:other_filter_with_default, default: true) { |scope, opt| scope }
 
           provided_params = nil
+
           WorkspacePresenter.filter :filter_with_param, :include_params => true do |scope, option, params|
             provided_params = params
             scope
           end
 
-          @presenter_collection.presenting("workspaces", :params => { :filter_with_param => "arg", :other_filter => 'another_arg' }) { Workspace.where(nil) }
+          @presenter_collection.presenting("workspaces", :params => {
+            :filter_with_param => "arg",
+            :other_filter => 'another_arg'
+          }) { Workspace.where(nil) }
 
-          expect(provided_params).to eq({ "filter_with_param" => "arg", "other_filter" => "another_arg", "other_filter_with_default" => true })
+          expect(provided_params).to eq({
+            "filter_with_param"         => "arg",
+            "other_filter"              => "another_arg",
+            "other_filter_with_default" => true
+          })
         end
       end
     end

data/spec/brainstem/presenter_spec.rb

@@ -68,6 +68,38 @@ describe Brainstem::Presenter do
         }).to raise_error(/Brainstem Presenter#presents now expects a Class instead of a class name/)
       end
     end
+
+
+    describe ".possible_brainstem_keys" do
+      let(:presented_class)       { Class.new }
+      let(:other_presented_class) { Class.new }
+      let(:presenter_class)       { Class.new(Brainstem::Presenter) }
+
+      before do
+        presenter_class.presents      presented_class, other_presented_class
+      end
+
+      context "when has brainstem key" do
+        before do
+          presenter_class.brainstem_key "presented_class"
+        end
+
+        it "returns the set of only its brainstem key" do
+          expect(presenter_class.possible_brainstem_keys.to_a).to eq ["presented_class"]
+        end
+      end
+
+      context "when has no brainstem key" do
+        before do
+          stub(presented_class).table_name       { "t1" }
+          stub(other_presented_class).table_name { "t2" }
+        end
+
+        it "returns the set of keys of its presented classes" do
+          expect(presenter_class.possible_brainstem_keys.to_a.sort).to eq ["t1", "t2"]
+        end
+      end
+    end
   end
 
   describe "#group_present" do

data/spec/brainstem/presenter_validator_spec.rb

@@ -9,29 +9,34 @@ describe Brainstem::PresenterValidator do
       preload :lead_user
 
       conditionals do
-        model :title_is_hello, lambda { |model| model.title == 'hello' }, 'visible when the title is hello'
-        request :user_is_bob, lambda { current_user == 'bob' }, 'visible only to bob'
+        model :title_is_hello, lambda { |model| model.title == 'hello' }, info: 'visible when the title is hello'
+        request :user_is_bob, lambda { current_user == 'bob' }, info: 'visible only to bob'
       end
 
       fields do
         field :title, :string
         field :description, :string
         field :updated_at, :datetime
-        field :secret, :string, 'a secret, via secret_info',
+        field :secret, :string,
+              info: 'a secret, via secret_info',
               via: :secret_info,
               if: [:user_is_bob, :title_is_hello]
 
         with_options if: :user_is_bob do
-          field :bob_title, :string, 'another name for the title, only for Bob',
+          field :bob_title, :string,
+                info: 'another name for the title, only for Bob',
                 via: :title
         end
       end
 
       associations do
-        association :tasks, Task, 'The Tasks in this Workspace',
+        association :tasks, Task,
+                    info: 'The Tasks in this Workspace',
                     restrict_to_only: true
-        association :lead_user, User, 'The user who runs this Workspace'
-        association :subtasks, Task, 'Only Tasks in this Workspace that are subtasks',
+        association :lead_user, User,
+                    info: 'The user who runs this Workspace'
+        association :subtasks, Task,
+                    info: 'Only Tasks in this Workspace that are subtasks',
                     dynamic: lambda { |workspace| workspace.tasks.where('parent_id IS NOT NULL') }
       end
     end

data/spec/dummy/rails.rb

@@ -0,0 +1,49 @@
+# This is a dummy file which is used in the Introspector specs to simulate a
+# loaded rails app.
+silence_warnings do
+  FakeRailsApplication      = Struct.new(:eager_load!, :routes)
+  FakeRailsRoutesObject     = Struct.new(:routes)
+  FakeRailsRoutePathObject  = Struct.new(:spec)
+  FakeRailsRoute            = Struct.new(:name, :path, :defaults, :constraints)
+end
+
+
+class Rails
+  def self.application
+    @application ||= begin
+      route_1 = FakeRailsRoute.new(
+        "fake_descendant",
+        FakeRailsRoutePathObject.new(spec: '/fake_descendant'),
+        { controller: "fake_descendant", action: "show" },
+        { :request_method => /^GET|POST$/ }
+      )
+
+      route_2 = FakeRailsRoute.new(
+        "route_with_no_controller",
+        FakeRailsRoutePathObject.new(spec: '/fake_descendant'),
+        { },
+        { :request_method => /^PATCH$/ }
+      )
+
+      route_3 = FakeRailsRoute.new(
+        "route_with_invalid_controller",
+        FakeRailsRoutePathObject.new(spec: '/fake_descendant'),
+        { controller: "invalid_controller", action: "show" },
+        { :request_method => /^GET$/ }
+      )
+
+      routes = FakeRailsRoutesObject.new([ route_1, route_2, route_3 ])
+
+      FakeRailsApplication.new(true, routes)
+    end
+  end
+end
+
+
+class FakeBasePresenter; end
+class FakeDescendantPresenter < FakeBasePresenter; end
+
+class FakeBaseController; end
+class FakeDescendantController < FakeBaseController; end
+
+class FakeNonDescendantController; end

data/spec/shared/atlas_taker.rb

@@ -0,0 +1,18 @@
+shared_examples "atlas taker" do
+  describe "#initialize" do
+    it "requires an atlas" do
+      expect { described_class.new }.to raise_error ArgumentError
+      expect { described_class.new(atlas) }.not_to raise_error
+    end
+  end
+
+  describe "#find_by_class" do
+    let(:klass) { Class.new }
+
+    it "delegates to the atlas" do
+      mock(atlas).find_by_class(klass)
+      subject.find_by_class(klass)
+    end
+  end
+end
+

data/spec/shared/formattable.rb

@@ -0,0 +1,14 @@
+shared_examples "formattable" do
+  describe "formatting" do
+    let(:formatter) { Object.new }
+    let(:formatters) { { markdown: formatter } }
+    let(:options) { { formatters: formatters } }
+
+    describe "#formatted_as" do
+      it "looks up the formatter and calls that" do
+        mock(formatter).call(subject, { test: true }) { "blah" }
+        expect(subject.formatted_as(:markdown, test: true)).to eq "blah"
+      end
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -12,6 +12,8 @@ require_relative 'spec_helpers/schema'
 require_relative 'spec_helpers/db'
 require_relative 'spec_helpers/rr'
 
+Dir["./spec/shared/**/*.rb"].each {|f| require f}
+
 DatabaseCleaner.strategy = :transaction
 
 RSpec.configure do |config|

data/spec/spec_helpers/db.rb

@@ -44,4 +44,4 @@ Attachments::TaskAttachment.create!(id: 2, subject: Task.first, filename: 'I am
 # Show that the base class is always used as the brainstem_key for attachments as polymorphic association targets
 
 # Use Group / Workspace as the polymorphic target of an association where we do not
-# want the baseclass to be used as the brainstem_key (like line_items0)
+# want the baseclass to be used as the brainstem_key (like line_items0)

data/spec/spec_helpers/presenters.rb

@@ -1,4 +1,4 @@
-class WorkspacePresenter < Brainstem::Presenter
+ class WorkspacePresenter < Brainstem::Presenter
   presents Workspace
 
   helper do
@@ -10,8 +10,8 @@ class WorkspacePresenter < Brainstem::Presenter
   preload :lead_user
 
   conditionals do
-    model   :title_is_hello, lambda { |model| model.title == 'hello' }, 'visible when the title is hello'
-    request :user_is_bob, lambda { current_user == 'bob' }, 'visible only to bob'
+    model   :title_is_hello, lambda { |model| model.title == 'hello' }, info: 'visible when the title is hello'
+    request :user_is_bob, lambda { current_user == 'bob' }, info: 'visible only to bob'
   end
 
   fields do
@@ -32,23 +32,26 @@ class WorkspacePresenter < Brainstem::Presenter
       field :access_level, :integer, dynamic: lambda { 2 }
     end
 
-    field :hello_title, :string, 'the title, when hello',
+    field :hello_title, :string,
+          info: 'the title, when hello',
           dynamic: lambda { 'title is hello' },
           if: :title_is_hello
 
-    field :secret, :string, 'a secret, via secret_info',
+    field :secret, :string,
+          info: 'a secret, via secret_info',
           via: :secret_info,
           if: [:user_is_bob, :title_is_hello]
 
     with_options if: :user_is_bob do
-      field :bob_title, :string, 'another name for the title, only for Bob',
+      field :bob_title, :string,
+            info: 'another name for the title, only for Bob',
             via: :title
     end
   end
 
   associations do
-    association :tasks, Task, 'The Tasks in this Workspace'
-    association :lead_user, User, 'The user who runs this Workspace'
+    association :tasks, Task, info: 'The Tasks in this Workspace'
+    association :lead_user, User, info: 'The user who runs this Workspace'
     # association :subtasks, Task, 'Only Tasks in this Workspace that are subtasks',
     #             dynamic: lambda { |workspace| workspace.tasks.where('parent_id IS NOT NULL') },
     #             brainstem_key: 'sub_tasks'
@@ -63,7 +66,7 @@ class CheesePresenter < Brainstem::Presenter
   end
 
   associations do
-    association :user, User, 'The owner of the cheese'
+    association :user, User, info: 'The owner of the cheese'
   end
 end
 
@@ -75,7 +78,7 @@ class GroupPresenter < Brainstem::Presenter
   end
 
   associations do
-    association :tasks, Task, 'The Tasks in this Group'
+    association :tasks, Task, info: 'The Tasks in this Group'
   end
 end
 
@@ -88,10 +91,12 @@ class TaskPresenter < Brainstem::Presenter
 
   associations do
     association :sub_tasks, Task
-    association :other_tasks, Task, 'another copy of the sub_tasks association',
+    association :other_tasks, Task,
+                info: 'another copy of the sub_tasks association',
                 via: :sub_tasks
     association :workspace, Workspace
-    association :restricted, Task, 'only available on only / show requests',
+    association :restricted, Task,
+                info: 'only available on only / show requests',
                 dynamic: lambda { |task| Task.last },
                 restrict_to_only: true
   end
@@ -105,7 +110,8 @@ class UserPresenter < Brainstem::Presenter
   end
 
   associations do
-    association :odd_workspaces, Workspace, 'only the odd numbered workspaces',
+    association :odd_workspaces, Workspace,
+                info: 'only the odd numbered workspaces',
                 dynamic: lambda { |user| user.workspaces.select { |workspace| workspace.id % 2 == 1 } }
   end
 end
@@ -135,4 +141,4 @@ class AttachmentPresenter < Brainstem::Presenter
   associations do
     association :subject, :polymorphic
   end
-end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: brainstem
 version: !ruby/object:Gem::Version
-  version: 1.0.0.pre.1
+  version: 1.0.0
 platform: ruby
 authors:
 - Mavenlink
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-03-08 00:00:00.000000000 Z
+date: 2017-07-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -168,7 +168,8 @@ description: Brainstem allows you to create rich API presenters that know how to
   sort, and include associations.
 email:
 - opensource@mavenlink.com
-executables: []
+executables:
+- brainstem
 extensions: []
 extra_rdoc_files: []
 files:
@@ -179,12 +180,48 @@ files:
 - LICENSE
 - README.md
 - Rakefile
+- bin/brainstem
 - brainstem.gemspec
+- docs/api_doc_generator.markdown
+- docs/brainstem_executable.markdown
+- docs/docgen.png
+- docs/docgen_ascii.txt
+- docs/executable.png
+- docs/executable_ascii.txt
 - lib/brainstem.rb
+- lib/brainstem/api_docs.rb
+- lib/brainstem/api_docs/abstract_collection.rb
+- lib/brainstem/api_docs/atlas.rb
+- lib/brainstem/api_docs/builder.rb
+- lib/brainstem/api_docs/controller.rb
+- lib/brainstem/api_docs/controller_collection.rb
+- lib/brainstem/api_docs/endpoint.rb
+- lib/brainstem/api_docs/endpoint_collection.rb
+- lib/brainstem/api_docs/exceptions.rb
+- lib/brainstem/api_docs/formatters/abstract_formatter.rb
+- lib/brainstem/api_docs/formatters/markdown/controller_formatter.rb
+- lib/brainstem/api_docs/formatters/markdown/endpoint_collection_formatter.rb
+- lib/brainstem/api_docs/formatters/markdown/endpoint_formatter.rb
+- lib/brainstem/api_docs/formatters/markdown/helper.rb
+- lib/brainstem/api_docs/formatters/markdown/presenter_formatter.rb
+- lib/brainstem/api_docs/introspectors/abstract_introspector.rb
+- lib/brainstem/api_docs/introspectors/rails_introspector.rb
+- lib/brainstem/api_docs/presenter.rb
+- lib/brainstem/api_docs/presenter_collection.rb
+- lib/brainstem/api_docs/resolver.rb
+- lib/brainstem/api_docs/sinks/abstract_sink.rb
+- lib/brainstem/api_docs/sinks/controller_presenter_multifile_sink.rb
+- lib/brainstem/api_docs/sinks/stdout_sink.rb
+- lib/brainstem/cli.rb
+- lib/brainstem/cli/abstract_command.rb
+- lib/brainstem/cli/generate_api_docs_command.rb
+- lib/brainstem/concerns/controller_dsl.rb
 - lib/brainstem/concerns/controller_param_management.rb
 - lib/brainstem/concerns/error_presentation.rb
+- lib/brainstem/concerns/formattable.rb
 - lib/brainstem/concerns/inheritable_configuration.rb
 - lib/brainstem/concerns/lookup.rb
+- lib/brainstem/concerns/optional.rb
 - lib/brainstem/concerns/presenter_dsl.rb
 - lib/brainstem/controller_methods.rb
 - lib/brainstem/dsl/association.rb
@@ -195,6 +232,7 @@ files:
 - lib/brainstem/dsl/configuration.rb
 - lib/brainstem/dsl/field.rb
 - lib/brainstem/dsl/fields_block.rb
+- lib/brainstem/help_text.txt
 - lib/brainstem/preloader.rb
 - lib/brainstem/presenter.rb
 - lib/brainstem/presenter_collection.rb
@@ -207,9 +245,37 @@ files:
 - lib/brainstem/test_helpers.rb
 - lib/brainstem/time_classes.rb
 - lib/brainstem/version.rb
+- spec/brainstem/api_docs/abstract_collection_spec.rb
+- spec/brainstem/api_docs/atlas_spec.rb
+- spec/brainstem/api_docs/builder_spec.rb
+- spec/brainstem/api_docs/controller_collection_spec.rb
+- spec/brainstem/api_docs/controller_spec.rb
+- spec/brainstem/api_docs/endpoint_collection_spec.rb
+- spec/brainstem/api_docs/endpoint_spec.rb
+- spec/brainstem/api_docs/formatters/abstract_formatter_spec.rb
+- spec/brainstem/api_docs/formatters/markdown/controller_formatter_spec.rb
+- spec/brainstem/api_docs/formatters/markdown/endpoint_collection_formatter_spec.rb
+- spec/brainstem/api_docs/formatters/markdown/endpoint_formatter_spec.rb
+- spec/brainstem/api_docs/formatters/markdown/helper_spec.rb
+- spec/brainstem/api_docs/formatters/markdown/presenter_formatter_spec.rb
+- spec/brainstem/api_docs/introspectors/abstract_introspector_spec.rb
+- spec/brainstem/api_docs/introspectors/rails_introspector_spec.rb
+- spec/brainstem/api_docs/presenter_collection_spec.rb
+- spec/brainstem/api_docs/presenter_spec.rb
+- spec/brainstem/api_docs/resolver_spec.rb
+- spec/brainstem/api_docs/sinks/abstract_sink_spec.rb
+- spec/brainstem/api_docs/sinks/controller_presenter_multifile_sink_spec.rb
+- spec/brainstem/api_docs/sinks/stdout_sink_spec.rb
+- spec/brainstem/api_docs_spec.rb
+- spec/brainstem/cli/abstract_command_spec.rb
+- spec/brainstem/cli/generate_api_docs_command_spec.rb
+- spec/brainstem/cli_spec.rb
+- spec/brainstem/concerns/controller_dsl_spec.rb
 - spec/brainstem/concerns/controller_param_management_spec.rb
 - spec/brainstem/concerns/error_presentation_spec.rb
+- spec/brainstem/concerns/formattable_spec.rb
 - spec/brainstem/concerns/inheritable_configuration_spec.rb
+- spec/brainstem/concerns/optional_spec.rb
 - spec/brainstem/concerns/presenter_dsl_spec.rb
 - spec/brainstem/controller_methods_spec.rb
 - spec/brainstem/dsl/association_spec.rb
@@ -223,6 +289,9 @@ files:
 - spec/brainstem/query_strategies/filter_and_search_spec.rb
 - spec/brainstem/query_strategies/filter_or_search_spec.rb
 - spec/brainstem_spec.rb
+- spec/dummy/rails.rb
+- spec/shared/atlas_taker.rb
+- spec/shared/formattable.rb
 - spec/spec_helper.rb
 - spec/spec_helpers/db.rb
 - spec/spec_helpers/presenters.rb
@@ -243,19 +312,47 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">"
+  - - ">="
     - !ruby/object:Gem::Version
-      version: 1.3.1
+      version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.4.8
+rubygems_version: 2.5.2
 signing_key: 
 specification_version: 4
 summary: ActiveRecord presenters with a rich request API
 test_files:
+- spec/brainstem/api_docs/abstract_collection_spec.rb
+- spec/brainstem/api_docs/atlas_spec.rb
+- spec/brainstem/api_docs/builder_spec.rb
+- spec/brainstem/api_docs/controller_collection_spec.rb
+- spec/brainstem/api_docs/controller_spec.rb
+- spec/brainstem/api_docs/endpoint_collection_spec.rb
+- spec/brainstem/api_docs/endpoint_spec.rb
+- spec/brainstem/api_docs/formatters/abstract_formatter_spec.rb
+- spec/brainstem/api_docs/formatters/markdown/controller_formatter_spec.rb
+- spec/brainstem/api_docs/formatters/markdown/endpoint_collection_formatter_spec.rb
+- spec/brainstem/api_docs/formatters/markdown/endpoint_formatter_spec.rb
+- spec/brainstem/api_docs/formatters/markdown/helper_spec.rb
+- spec/brainstem/api_docs/formatters/markdown/presenter_formatter_spec.rb
+- spec/brainstem/api_docs/introspectors/abstract_introspector_spec.rb
+- spec/brainstem/api_docs/introspectors/rails_introspector_spec.rb
+- spec/brainstem/api_docs/presenter_collection_spec.rb
+- spec/brainstem/api_docs/presenter_spec.rb
+- spec/brainstem/api_docs/resolver_spec.rb
+- spec/brainstem/api_docs/sinks/abstract_sink_spec.rb
+- spec/brainstem/api_docs/sinks/controller_presenter_multifile_sink_spec.rb
+- spec/brainstem/api_docs/sinks/stdout_sink_spec.rb
+- spec/brainstem/api_docs_spec.rb
+- spec/brainstem/cli/abstract_command_spec.rb
+- spec/brainstem/cli/generate_api_docs_command_spec.rb
+- spec/brainstem/cli_spec.rb
+- spec/brainstem/concerns/controller_dsl_spec.rb
 - spec/brainstem/concerns/controller_param_management_spec.rb
 - spec/brainstem/concerns/error_presentation_spec.rb
+- spec/brainstem/concerns/formattable_spec.rb
 - spec/brainstem/concerns/inheritable_configuration_spec.rb
+- spec/brainstem/concerns/optional_spec.rb
 - spec/brainstem/concerns/presenter_dsl_spec.rb
 - spec/brainstem/controller_methods_spec.rb
 - spec/brainstem/dsl/association_spec.rb
@@ -269,6 +366,9 @@ test_files:
 - spec/brainstem/query_strategies/filter_and_search_spec.rb
 - spec/brainstem/query_strategies/filter_or_search_spec.rb
 - spec/brainstem_spec.rb
+- spec/dummy/rails.rb
+- spec/shared/atlas_taker.rb
+- spec/shared/formattable.rb
 - spec/spec_helper.rb
 - spec/spec_helpers/db.rb
 - spec/spec_helpers/presenters.rb