brainstem 1.0.0.pre.1 → 1.0.0

data/lib/brainstem/dsl/field.rb

@@ -5,16 +5,19 @@ module Brainstem
     class Field
       include Brainstem::Concerns::Lookup
 
-      attr_reader :name, :type, :description, :conditionals, :options
+      attr_reader :name, :type, :conditionals, :options
 
-      def initialize(name, type, description, options)
+      def initialize(name, type, options)
         @name = name.to_s
         @type = type
-        @description = description
         @conditionals = [options[:if]].flatten.compact
         @options = options
       end
 
+      def description
+        options[:info].presence
+      end
+
       def conditional?
         conditionals.length > 0
       end

data/lib/brainstem/dsl/fields_block.rb

@@ -2,9 +2,8 @@ module Brainstem
   module Concerns
     module PresenterDSL
       class FieldsBlock < BaseBlock
-        def field(name, type, *args)
-          description, options = parse_args(args)
-          configuration[name] = DSL::Field.new(name, type, description, smart_merge(block_options, options))
+        def field(name, type, options = {})
+          configuration[name] = DSL::Field.new(name, type, smart_merge(block_options, format_options(options)))
         end
 
         def fields(name, &block)

data/lib/brainstem/help_text.txt

@@ -0,0 +1,8 @@
+
+Usage: EXECUTABLE_NAME [command [options]]
+
+Commonly used commands are:
+
+    generate:      generates API documentation.
+
+See EXECUTABLE_NAME COMMAND --help for more information on a specific command.

data/lib/brainstem/presenter.rb

@@ -1,7 +1,9 @@
 require 'date'
+require 'set' # For possible brainstem keys
 require 'brainstem/time_classes'
 require 'brainstem/preloader'
 require 'brainstem/concerns/presenter_dsl'
+require 'active_support/core_ext/hash/except'
 
 module Brainstem
   # @abstract Subclass and override {#present} to implement a presenter.
@@ -24,6 +26,20 @@ module Brainstem
       @presents
     end
 
+
+    #
+    # Returns the set of possible brainstem keys for the classes presented.
+    #
+    # If the presenter specifies a key, that will be returned as the only
+    # member of the set.
+    #
+    def self.possible_brainstem_keys
+      @possible_brainstem_keys ||= begin
+        Set.new(presents.map(&presenter_collection.method(:brainstem_key_for!)))
+      end
+    end
+
+
     # Return the second-to-last module in the name of this presenter, which Brainstem considers to be the 'namespace'.
     # E.g., Api::V1::FooPresenter has a namespace of "V1".
     # @return [String] The name of the second-to-last module containing this presenter.
@@ -140,10 +156,9 @@ module Brainstem
 
       apply_default_filters = options.fetch(:apply_default_filters) { true }
 
-      configuration[:filters].each do |filter_name, filter|
+      configuration[:filters].each do |filter_name, filter_options|
         user_value = format_filter_value(user_params[filter_name])
 
-        filter_options = filter[0]
         filter_arg = apply_default_filters && user_value.nil? ? filter_options[:default] : user_value
         filters_hash[filter_name] = filter_arg unless filter_arg.nil?
       end
@@ -175,10 +190,10 @@ module Brainstem
 
       requested_filters = extract_filters(user_params, options)
       requested_filters.each do |filter_name, filter_arg|
-        filter_lambda = configuration[:filters][filter_name][1]
+        filter_lambda = configuration[:filters][filter_name][:value]
 
         args_for_filter_lambda = [filter_arg]
-        args_for_filter_lambda << requested_filters if configuration[:filters][filter_name][0][:include_params]
+        args_for_filter_lambda << requested_filters if configuration[:filters][filter_name][:include_params]
 
         if filter_lambda
           scope = helper_instance.instance_exec(scope, *args_for_filter_lambda, &filter_lambda)
@@ -193,7 +208,7 @@ module Brainstem
     # Given user params, apply a validated sort order to the given scope.
     def apply_ordering_to_scope(scope, user_params)
       sort_name, direction = calculate_sort_name_and_direction(user_params)
-      order = configuration[:sort_orders][sort_name]
+      order = configuration[:sort_orders].fetch(sort_name, {})[:value]
 
       ordered_scope = case order
         when Proc
@@ -391,10 +406,16 @@ module Brainstem
       end
     end
 
+
+    def self.presenter_collection
+      Brainstem.presenter_collection(namespace)
+    end
+
+
     # @api protected
     # Find the global presenter collection for our namespace.
     def presenter_collection
-      Brainstem.presenter_collection(self.class.namespace)
+      self.class.presenter_collection
     end
 
     # @api protected

data/lib/brainstem/presenter_validator.rb

@@ -1,5 +1,8 @@
-# Brainstem::PresenterValidator is a helper class that performs validity checks on a given presenter class.
+require 'active_model'
 
+#
+# Brainstem::PresenterValidator is a helper class that performs validity checks on a given presenter class.
+#
 module Brainstem
   class PresenterValidator
     include ActiveModel::Validations
@@ -93,4 +96,4 @@ module Brainstem
       end
     end
   end
-end
+end

data/lib/brainstem/time_classes.rb

@@ -11,4 +11,4 @@ module Brainstem
     rescue LoadError
     end
   end
-end
+end

data/lib/brainstem/version.rb

@@ -1,3 +1,3 @@
 module Brainstem
-  VERSION = "1.0.0.pre.1"
+  VERSION = "1.0.0"
 end

data/spec/brainstem/api_docs/abstract_collection_spec.rb

@@ -0,0 +1,156 @@
+require 'spec_helper'
+require 'brainstem/api_docs/abstract_collection'
+
+module Brainstem
+  module ApiDocs
+    describe AbstractCollection do
+      let(:atlas)    { Object.new }
+      let(:member)   { Object.new }
+      let(:member_2) { Object.new }
+      let(:members)  { [ member, member_2 ] }
+
+      subject { described_class.new(atlas) }
+
+      describe "#last" do
+        it "retrieves the last member" do
+          subject << members
+          expect(subject.last).to eq member_2
+        end
+      end
+
+
+      describe "#<<" do
+        it "adds a member to the collection" do
+          subject << member
+          expect(subject.count).to eq 1
+        end
+
+        it "adds multiple members to the collection" do
+          subject << members
+          expect(subject.count).to eq 2
+        end
+      end
+
+
+      describe "#each" do
+        it "iterates over each member" do
+          subject << members
+          expect { |block| subject.each(&block) }.to yield_successive_args(*members)
+        end
+      end
+
+
+      describe "iteration" do
+        before do
+          subject << member
+        end
+
+
+        describe "#filenames" do
+          it "maps all its members" do
+            stub(member).formatted_as(:markdown, {}) { "blah" }
+            mock(member).suggested_filename(:markdown) { "member.markdown" }
+            expect(subject.filenames(:markdown)).to eq [ "member.markdown" ]
+          end
+        end
+
+
+        describe "#each_filename" do
+          it "maps all its controllers and yields each in turn" do
+            stub(member).formatted_as(:markdown, {}) { "blah" }
+            mock(member).suggested_filename(:markdown) { "member.markdown" }
+            expect { |block| subject.each_filename(:markdown, &block) }.to \
+              yield_with_args("member.markdown")
+          end
+        end
+
+
+        describe "#formatted" do
+          it "maps all its members" do
+            mock(member).formatted_as(:markdown, {}) { "blah" }
+            expect(subject.formatted(:markdown)).to eq [ "blah" ]
+          end
+
+          it "passes options on to the formatter" do
+            mock(member).formatted_as(:markdown, blah: true) { "blah" }
+            subject.formatted(:markdown, blah: true)
+          end
+
+          it "rejects empty" do
+            mock(member).formatted_as(:markdown, {}) { "" }
+            expect(subject.formatted(:markdown)).to eq []
+          end
+        end
+
+
+        describe "#formatted_with_filename" do
+          it "maps all its members and filenames" do
+            mock(member).formatted_as(:markdown, {}) { "blah" }
+            mock(member).suggested_filename(:markdown) { "member.markdown" }
+
+            expect(subject.formatted_with_filename(:markdown)).to eq [ [ "blah", "member.markdown" ] ]
+          end
+
+          it "passes options on to the formatter" do
+            mock(member).formatted_as(:markdown, blah: true) { "blah" }
+            stub(member).suggested_filename(:markdown) { "member.markdown" }
+
+            subject.formatted_with_filename(:markdown, blah: true)
+          end
+
+          it "rejects empty" do
+            mock(member).formatted_as(:markdown, {}) { "" }
+            stub(member).suggested_filename(:markdown) { "member.markdown" }
+            expect(subject.formatted_with_filename(:markdown)).to eq []
+          end
+        end
+
+
+        describe "#each_formatted" do
+          it "maps all its controllers and yields each in turn" do
+            mock(member).formatted_as(:markdown, {}) { "blah" }
+            expect { |block| subject.each_formatted(:markdown, &block) }.to \
+              yield_with_args("blah")
+          end
+
+          it "passes options on to the formatter" do
+            mock(member).formatted_as(:markdown, blah: true) { "blah" }
+
+            subject.each_formatted(:markdown, blah: true) {|_, _| nil }
+          end
+        end
+
+
+        describe "#each_formatted_with_filename" do
+          it "maps all its controllers and filenames and yields each in turn" do
+            mock(member).formatted_as(:markdown, {}) { "blah" }
+            mock(member).suggested_filename(:markdown) { "member.markdown" }
+
+            expect { |block| subject.each_formatted_with_filename(:markdown, &block) }.to \
+              yield_with_args("blah", "member.markdown")
+          end
+
+          it "passes options on to the formatter" do
+            mock(member).formatted_as(:markdown, blah: true) { "blah" }
+            stub(member).suggested_filename(:markdown) { "member.markdown" }
+
+            subject.each_formatted_with_filename(:markdown, blah: true) {|_, _| nil }
+          end
+        end
+      end
+
+
+      describe ".with_members" do
+        subject { described_class.with_members(atlas, member) }
+
+        it "creates a new instance with passed members" do
+          expect(subject).to be_a described_class
+          expect(subject.send(:members)).to eq [ member ]
+        end
+
+      end
+
+      it_behaves_like "atlas taker"
+    end
+  end
+end

data/spec/brainstem/api_docs/atlas_spec.rb

@@ -0,0 +1,353 @@
+require 'spec_helper'
+require 'brainstem/api_docs/atlas'
+require 'dummy/rails'
+
+module Brainstem
+  module ApiDocs
+    describe Atlas do
+      let(:introspector) { Object.new }
+
+      subject { Atlas.new(introspector) }
+
+      describe "#initialize" do
+        describe "mapping" do
+          before do
+            stub(introspector).valid? { true }
+          end
+
+          it "parses routes" do
+            any_instance_of(Atlas) do |instance|
+              mock(instance).parse_routes!
+              stub(instance).extract_presenters!
+              stub(instance).validate!
+            end
+
+            subject
+          end
+
+          it "extracts presenters" do
+            any_instance_of(Atlas) do |instance|
+              stub(instance).parse_routes!
+              mock(instance).extract_presenters!
+              stub(instance).validate!
+            end
+
+            subject
+          end
+        end
+
+
+        describe "validation" do
+          before do
+            any_instance_of(Atlas) do |instance|
+              stub(instance).parse_routes!
+              stub(instance).extract_presenters!
+            end
+          end
+
+          describe "when atlas is invalid" do
+            before do
+              stub.any_instance_of(Atlas).valid? { false }
+            end
+
+            it "raises an error" do
+              expect { subject }.to raise_error InvalidAtlasError
+            end
+          end
+
+          describe "when atlas is valid" do
+            before do
+              stub.any_instance_of(Atlas).valid? { true }
+            end
+
+            it "does not raise an error" do
+              expect { subject }.not_to raise_error
+            end
+
+          end
+        end
+      end
+
+      describe "#parse_routes!" do
+        let(:route_1) { {
+          path:            "/endpoint1",
+          http_methods:    ["POST"],
+          controller:      FakeDescendantController,
+          controller_name: "fake_descendant",
+          action:          "create" } }
+
+        let(:route_2) { {
+          path:            "/endpoint2",
+          http_methods:    ["GET"],
+          controller:      FakeDescendantController,
+          controller_name: "fake_descendant",
+          action:          "show" } }
+
+        before do
+          any_instance_of(Atlas) do |instance|
+            stub(instance).extract_presenters!
+            stub(instance).validate!
+          end
+
+          stub(introspector) do |i|
+            i.routes { [ route_1, route_2 ] }
+            i.controllers { [ FakeDescendantController ] }
+            i.presenters { }
+            i.valid? { true }
+          end
+
+        end
+
+        context "when route is valid" do
+          it "constructs an Endpoint" do
+            expect(subject.endpoints.count).to eq 2
+            expect(subject.endpoints).to all(be_an(Endpoint))
+          end
+
+          it "adds the endpoint to the controller" do
+            expect(subject.controllers.first.endpoints.count).to eq 2
+            expect(subject.controllers.first.endpoints).to all(be_an(Endpoint))
+          end
+
+          context "when controller not in controllers list" do
+            let(:route_2) { {
+              path:            "/endpoint2",
+              http_methods:    ["GET"],
+              controller:      TrueClass,
+              controller_name: "true_class",
+              action:          "show" } }
+
+            it "discards the route" do
+              expect(subject.endpoints.count).to eq 1
+            end
+          end
+
+          context "when controller does not match all passed matches" do
+            let(:route_2) { {
+              path:            "/endpoint2",
+              http_methods:    ["GET"],
+              controller:      TrueClass,
+              controller_name: "true_class",
+              action:          "show" } }
+
+            before do
+              stub.any_instance_of(Atlas)
+                .controller_matches { [ Regexp.new('FakeDescendant', 'i') ] }
+            end
+
+            it "discards the route" do
+              expect(subject.endpoints.count).to eq 1
+            end
+          end
+
+          context "when controller does match all passed matches" do
+            before do
+              stub.any_instance_of(Atlas)
+                .controller_matches { [ Regexp.new('FakeDescendant', 'i') ] }
+            end
+
+            it "keeps the route" do
+              expect(subject.endpoints.count).to eq 2
+            end
+          end
+
+          context "when an Endpoint for that route already exists, but with a different HTTP verb" do
+            let(:route_2) { {
+              path:            "/endpoint1",
+              http_methods:    ["PATCH"],
+              controller:      FakeDescendantController,
+              controller_name: "fake_descendant",
+              action:          "create" } }
+
+            it "merges the route" do
+              expect(subject.endpoints.count).to eq 1
+              expect(subject.endpoints.first.http_methods).to eq ["POST", "PATCH"]
+            end
+          end
+        end
+
+
+        context "when a route is invalid" do
+          let(:route_2) { {
+            path: "/endpoint2",
+            http_methods: ["GET"],
+            controller: TrueClass,
+            controller_name: "plainly_erroneous",
+            action: "show" } }
+
+          it "skips that route" do
+            expect(subject.endpoints.count).to eq 1
+            expect(subject.endpoints).to all(be_an(Endpoint))
+          end
+        end
+
+        context "when all routes are invalid" do
+          let(:route_1)   { {
+            path:            "/endpoint1",
+            http_methods:    ["POST"],
+            controller:      TrueClass,
+            controller_name: "true_class",
+            action:          "create" } }
+
+          let(:route_2)   { {
+            path:            "/endpoint2",
+            http_methods:    ["GET"],
+            controller:      TrueClass,
+            controller_name: "true_class",
+            action:          "show" } }
+
+          it "has an empty endpoints" do
+            expect(subject.endpoints.count).to eq 0
+          end
+        end
+      end
+
+
+      describe "#extract_presenters!" do
+        let(:endpoint_1)           { Object.new }
+        let(:endpoint_2)           { Object.new }
+        let(:presenter)            { Object.new }
+        let(:target_class)         { Class.new }
+        let(:presenter_collection) { Object.new }
+
+        before do
+          # This set-up is a bit of a smell.
+          stub(endpoint_1).declared_presented_class { target_class }
+          stub(endpoint_2).declared_presented_class { Class.new }
+
+          stub(target_class).to_s { "TargetClass" }
+
+          any_instance_of(described_class) do |instance|
+            stub(instance).parse_routes!
+            stub(instance).validate!
+
+            stub(instance).valid_presenter_pairs { {
+              "TargetClass" => target_class
+            } }
+
+            stub(instance).presenters { presenter_collection }
+            stub(instance).endpoints { [ endpoint_1, endpoint_2 ] }
+          end
+        end
+
+        it "creates a presenter for each valid presenter pair" do
+          stub(endpoint_1).presenter=(presenter)
+          mock(presenter_collection)
+            .find_or_create_from_presenter_collection("TargetClass", target_class) { presenter }
+
+          subject
+        end
+
+        it "sets the presenter on each endpoint that presents the same" do
+          mock(endpoint_1).presenter=(presenter)
+          dont_allow(endpoint_2).presenter=(presenter)
+
+          stub(presenter_collection)
+            .find_or_create_from_presenter_collection("TargetClass", target_class) { presenter }
+
+          subject
+        end
+      end
+
+
+      describe "#valid?" do
+        before do
+          any_instance_of(Atlas) do |instance|
+            stub(instance) do |i|
+              i.parse_routes!
+              i.extract_presenters!
+              i.validate!
+            end
+          end
+        end
+
+        context "when has at least one endpoint" do
+          before do
+            stub(subject).endpoints { [ Object.new ] }
+          end
+
+          it "is valid" do
+            expect(subject.send(:valid?)).to eq true
+          end
+        end
+
+        context "When has no endpoints" do
+          before do
+            stub(subject).endpoints { [ ] }
+          end
+
+          it "is invalid" do
+            expect(subject.send(:valid?)).to eq false
+          end
+        end
+      end
+
+
+      describe "#allow_route?" do
+        before do
+          any_instance_of(Atlas) do |instance|
+            stub(instance) do |i|
+              i.parse_routes!
+              i.extract_presenters!
+              i.validate!
+            end
+          end
+
+          stub(introspector) do |instance|
+            instance.controllers  { [ FakeDescendantController ] }
+          end
+        end
+
+        context "when controller not in the controllers list" do
+          it "is false" do
+            expect(subject.send(:allow_route?, controller: FakeNonDescendantController)).to eq false
+          end
+        end
+
+        context "when controller in the controllers list" do
+          context "when matches all controller_matches" do
+            before do
+              stub.any_instance_of(Atlas).controller_matches do
+                [ Regexp.new('descendant', 'i') ]
+              end
+            end
+
+            it "is true" do
+              expect(subject.send(:allow_route?, controller: FakeDescendantController)).to eq true
+            end
+          end
+
+          context "when controller does not match all controller_matches" do
+            before do
+              stub.any_instance_of(Atlas).controller_matches do
+                [ Regexp.new('wildly_inaccurate_regexp_match', 'i') ]
+              end
+            end
+
+            it "is false" do
+              expect(subject.send(:allow_route?, controller: FakeDescendantController)).to eq false
+            end
+          end
+        end
+      end
+
+
+      describe "#find_by_class" do
+        before do
+          any_instance_of(Atlas) do |instance|
+            stub(instance) do |i|
+              i.parse_routes!
+              i.extract_presenters!
+              i.validate!
+            end
+          end
+        end
+
+        it "delegates to the resolver" do
+          mock(subject.resolver).find_by_class(nil)
+          subject.find_by_class(nil)
+        end
+      end
+    end
+  end
+end