Merge branch 'policyfile-support'

https://tickets.opscode.com/browse/CHEF-4984

8 files changed, 1265 insertions, 467 deletions

diff --git a/lib/chef/client.rb b/lib/chef/client.rb
index 390dc247ab..3b50874db9 100644
--- a/lib/chef/client.rb
+++ b/lib/chef/client.rb
@@ -244,7 +244,7 @@ class Chef
     end
 
     def policy_builder
-      @policy_builder ||= Chef::PolicyBuilder.new(node_name, ohai.data, json_attribs, @override_runlist, events)
+      @policy_builder ||= Chef::PolicyBuilder.strategy.new(node_name, ohai.data, json_attribs, @override_runlist, events)
     end
 
 
diff --git a/lib/chef/config.rb b/lib/chef/config.rb
index f5cba9e0ed..da3f3790f6 100644
--- a/lib/chef/config.rb
+++ b/lib/chef/config.rb
@@ -320,6 +320,16 @@ class Chef
     default :enable_reporting, true
     default :enable_reporting_url_fatals, false
 
+    # Policyfile is an experimental feature where a node gets its run list and
+    # cookbook version set from a single document on the server instead of
+    # expanding the run list and having the server compute the cookbook version
+    # set based on environment constraints.
+    #
+    # Because this feature is experimental, it is not recommended for
+    # production use. Developent/release of this feature may not adhere to
+    # semver guidelines.
+    default :use_policyfile, false
+
     # Set these to enable SSL authentication / mutual-authentication
     # with the server
 
diff --git a/lib/chef/policy_builder.rb b/lib/chef/policy_builder.rb
index 37e7f8f3fa..136b2853b0 100644
--- a/lib/chef/policy_builder.rb
+++ b/lib/chef/policy_builder.rb
@@ -1,7 +1,4 @@
 #
-# Author:: Adam Jacob (<adam@opscode.com>)
-# Author:: Tim Hinderliter (<tim@opscode.com>)
-# Author:: Christopher Walters (<cw@opscode.com>)
 # Author:: Daniel DeLeo (<dan@getchef.com>)
 # Copyright:: Copyright 2008-2014 Chef Software, Inc.
 # License:: Apache License, Version 2.0
@@ -19,16 +16,13 @@
 # limitations under the License.
 #
 
-require 'chef/log'
-require 'chef/rest'
-require 'chef/run_context'
-require 'chef/config'
-require 'chef/node'
+require 'chef/policy_builder/expand_node_object'
+require 'chef/policy_builder/policyfile'
 
 class Chef
 
-  # Class that handles fetching policy from server or disk and resolving any
-  # indirection (e.g. expanding run_list).
+  # PolicyBuilder contains classes that handles fetching policy from server or
+  # disk and resolving any indirection (e.g. expanding run_list).
   #
   # INPUTS
   # * event stream object
@@ -41,197 +35,15 @@ class Chef
   # * a new RunStatus (probably doesn't need to be here)
   # * cookbooks sync'd to disk
   # * cookbook_hash is stored in run_context
-  class PolicyBuilder
+  module PolicyBuilder
 
-    attr_reader :events
-    attr_reader :node
-    attr_reader :node_name
-    attr_reader :ohai_data
-    attr_reader :json_attribs
-    attr_reader :override_runlist
-    attr_reader :original_runlist
-    attr_reader :run_context
-    attr_reader :run_list_expansion
-
-    def initialize(node_name, ohai_data, json_attribs, override_runlist, events)
-      @node_name = node_name
-      @ohai_data = ohai_data
-      @json_attribs = json_attribs
-      @override_runlist = override_runlist
-      @events = events
-
-      @node = nil
-      @original_runlist = nil
-      @run_list_expansion = nil
-    end
-
-    def setup_run_context(specific_recipes=nil)
-      if Chef::Config[:solo]
-        Chef::Cookbook::FileVendor.on_create { |manifest| Chef::Cookbook::FileSystemFileVendor.new(manifest, Chef::Config[:cookbook_path]) }
-        cl = Chef::CookbookLoader.new(Chef::Config[:cookbook_path])
-        cl.load_cookbooks
-        cookbook_collection = Chef::CookbookCollection.new(cl)
-        run_context = Chef::RunContext.new(node, cookbook_collection, @events)
-      else
-        Chef::Cookbook::FileVendor.on_create { |manifest| Chef::Cookbook::RemoteFileVendor.new(manifest, api_service) }
-        cookbook_hash = sync_cookbooks
-        cookbook_collection = Chef::CookbookCollection.new(cookbook_hash)
-        run_context = Chef::RunContext.new(node, cookbook_collection, @events)
-      end
-
-      # TODO: this is not the place for this. It should be in Runner or
-      # CookbookCompiler or something.
-      run_context.load(@run_list_expansion)
-      if specific_recipes
-        specific_recipes.each do |recipe_file|
-          run_context.load_recipe_file(recipe_file)
-        end
-      end
-      run_context
-    end
-
-
-    # In client-server operation, loads the node state from the server. In
-    # chef-solo operation, builds a new node object.
-    def load_node
-      events.node_load_start(node_name, Chef::Config)
-      Chef::Log.debug("Building node object for #{node_name}")
-
-      if Chef::Config[:solo]
-        @node = Chef::Node.build(node_name)
-      else
-        @node = Chef::Node.find_or_create(node_name)
-      end
-    rescue Exception => e
-      # TODO: wrap this exception so useful error info can be given to the
-      # user.
-      events.node_load_failed(node_name, e, Chef::Config)
-      raise
-    end
-
-
-    # Applies environment, external JSON attributes, and override run list to
-    # the node, Then expands the run_list.
-    #
-    # === Returns
-    # node<Chef::Node>:: The modified node object. node is modified in place.
-    def build_node
-      # Allow user to override the environment of a node by specifying
-      # a config parameter.
-      if Chef::Config[:environment] && !Chef::Config[:environment].chop.empty?
-        node.chef_environment(Chef::Config[:environment])
-      end
-
-      # consume_external_attrs may add items to the run_list. Save the
-      # expanded run_list, which we will pass to the server later to
-      # determine which versions of cookbooks to use.
-      node.reset_defaults_and_overrides
-      node.consume_external_attrs(ohai_data, @json_attribs)
-
-      setup_run_list_override
-
-      @run_list_expansion = expand_run_list
-
-      # @run_list_expansion is a RunListExpansion.
-      #
-      # Convert @expanded_run_list, which is an
-      # Array of Hashes of the form
-      #   {:name => NAME, :version_constraint => Chef::VersionConstraint },
-      # into @expanded_run_list_with_versions, an
-      # Array of Strings of the form
-      #   "#{NAME}@#{VERSION}"
-      @expanded_run_list_with_versions = @run_list_expansion.recipes.with_version_constraints_strings
-
-      Chef::Log.info("Run List is [#{node.run_list}]")
-      Chef::Log.info("Run List expands to [#{@expanded_run_list_with_versions.join(', ')}]")
-
-
-      events.node_load_completed(node, @expanded_run_list_with_versions, Chef::Config)
-
-      node
-    end
-
-    ########################################
-    # Internal public API
-    ########################################
-
-    def expand_run_list
-      if Chef::Config[:solo]
-        node.expand!('disk')
-      else
-        node.expand!('server')
-      end
-    rescue Exception => e
-      # TODO: wrap/munge exception with useful error output.
-      events.run_list_expand_failed(node, e)
-      raise
-    end
-
-    # Sync_cookbooks eagerly loads all files except files and
-    # templates.  It returns the cookbook_hash -- the return result
-    # from /environments/#{node.chef_environment}/cookbook_versions,
-    # which we will use for our run_context.
-    #
-    # === Returns
-    # Hash:: The hash of cookbooks with download URLs as given by the server
-    def sync_cookbooks
-      Chef::Log.debug("Synchronizing cookbooks")
-
-      begin
-        events.cookbook_resolution_start(@expanded_run_list_with_versions)
-        cookbook_hash = api_service.post("environments/#{node.chef_environment}/cookbook_versions",
-                                       {:run_list => @expanded_run_list_with_versions})
-      rescue Exception => e
-        # TODO: wrap/munge exception to provide helpful error output
-        events.cookbook_resolution_failed(@expanded_run_list_with_versions, e)
-        raise
+    def self.strategy
+      if Chef::Config[:use_policyfile]
+        Policyfile
       else
-        events.cookbook_resolution_complete(cookbook_hash)
-      end
-
-      synchronizer = Chef::CookbookSynchronizer.new(cookbook_hash, events)
-      synchronizer.sync_cookbooks
-
-      # register the file cache path in the cookbook path so that CookbookLoader actually picks up the synced cookbooks
-      Chef::Config[:cookbook_path] = File.join(Chef::Config[:file_cache_path], "cookbooks")
-
-      cookbook_hash
-    end
-
-    def setup_run_list_override
-      runlist_override_sanity_check!
-      unless(override_runlist.empty?)
-        @original_runlist = node.run_list.run_list_items.dup
-        node.run_list(*override_runlist)
-        Chef::Log.warn "Run List override has been provided."
-        Chef::Log.warn "Original Run List: [#{original_runlist.join(', ')}]"
-        Chef::Log.warn "Overridden Run List: [#{node.run_list}]"
-      end
-    end
-
-    # Ensures runlist override contains RunListItem instances
-    def runlist_override_sanity_check!
-      # Convert to array and remove whitespace
-      if override_runlist.is_a?(String)
-        @override_runlist = override_runlist.split(',').map { |e| e.strip }
-      end
-      @override_runlist = [override_runlist].flatten.compact
-      override_runlist.map! do |item|
-        if(item.is_a?(Chef::RunList::RunListItem))
-          item
-        else
-          Chef::RunList::RunListItem.new(item)
-        end
+        ExpandNodeObject
       end
     end
 
-    def api_service
-      @api_service ||= Chef::REST.new(config[:chef_server_url])
-    end
-
-    def config
-      Chef::Config
-    end
-
   end
 end
diff --git a/lib/chef/policy_builder/expand_node_object.rb b/lib/chef/policy_builder/expand_node_object.rb
new file mode 100644
index 0000000000..ea01533a92
--- /dev/null
+++ b/lib/chef/policy_builder/expand_node_object.rb
@@ -0,0 +1,229 @@
+#
+# Author:: Adam Jacob (<adam@opscode.com>)
+# Author:: Tim Hinderliter (<tim@opscode.com>)
+# Author:: Christopher Walters (<cw@opscode.com>)
+# Author:: Daniel DeLeo (<dan@getchef.com>)
+# Copyright:: Copyright 2008-2014 Chef Software, Inc.
+# License:: Apache License, Version 2.0
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+require 'chef/log'
+require 'chef/rest'
+require 'chef/run_context'
+require 'chef/config'
+require 'chef/node'
+
+class Chef
+  module PolicyBuilder
+
+    # ExpandNodeObject is the "classic" policy builder implementation. It
+    # expands the run_list on a node object and then queries the chef-server
+    # to find the correct set of cookbooks, given version constraints of the
+    # node's environment.
+    class ExpandNodeObject
+
+      attr_reader :events
+      attr_reader :node
+      attr_reader :node_name
+      attr_reader :ohai_data
+      attr_reader :json_attribs
+      attr_reader :override_runlist
+      attr_reader :original_runlist
+      attr_reader :run_context
+      attr_reader :run_list_expansion
+
+      def initialize(node_name, ohai_data, json_attribs, override_runlist, events)
+        @node_name = node_name
+        @ohai_data = ohai_data
+        @json_attribs = json_attribs
+        @override_runlist = override_runlist
+        @events = events
+
+        @node = nil
+        @original_runlist = nil
+        @run_list_expansion = nil
+      end
+
+      def setup_run_context(specific_recipes=nil)
+        if Chef::Config[:solo]
+          Chef::Cookbook::FileVendor.on_create { |manifest| Chef::Cookbook::FileSystemFileVendor.new(manifest, Chef::Config[:cookbook_path]) }
+          cl = Chef::CookbookLoader.new(Chef::Config[:cookbook_path])
+          cl.load_cookbooks
+          cookbook_collection = Chef::CookbookCollection.new(cl)
+          run_context = Chef::RunContext.new(node, cookbook_collection, @events)
+        else
+          Chef::Cookbook::FileVendor.on_create { |manifest| Chef::Cookbook::RemoteFileVendor.new(manifest, api_service) }
+          cookbook_hash = sync_cookbooks
+          cookbook_collection = Chef::CookbookCollection.new(cookbook_hash)
+          run_context = Chef::RunContext.new(node, cookbook_collection, @events)
+        end
+
+        # TODO: this is not the place for this. It should be in Runner or
+        # CookbookCompiler or something.
+        run_context.load(@run_list_expansion)
+        if specific_recipes
+          specific_recipes.each do |recipe_file|
+            run_context.load_recipe_file(recipe_file)
+          end
+        end
+        run_context
+      end
+
+
+      # In client-server operation, loads the node state from the server. In
+      # chef-solo operation, builds a new node object.
+      def load_node
+        events.node_load_start(node_name, Chef::Config)
+        Chef::Log.debug("Building node object for #{node_name}")
+
+        if Chef::Config[:solo]
+          @node = Chef::Node.build(node_name)
+        else
+          @node = Chef::Node.find_or_create(node_name)
+        end
+      rescue Exception => e
+        # TODO: wrap this exception so useful error info can be given to the
+        # user.
+        events.node_load_failed(node_name, e, Chef::Config)
+        raise
+      end
+
+
+      # Applies environment, external JSON attributes, and override run list to
+      # the node, Then expands the run_list.
+      #
+      # === Returns
+      # node<Chef::Node>:: The modified node object. node is modified in place.
+      def build_node
+        # Allow user to override the environment of a node by specifying
+        # a config parameter.
+        if Chef::Config[:environment] && !Chef::Config[:environment].chop.empty?
+          node.chef_environment(Chef::Config[:environment])
+        end
+
+        # consume_external_attrs may add items to the run_list. Save the
+        # expanded run_list, which we will pass to the server later to
+        # determine which versions of cookbooks to use.
+        node.reset_defaults_and_overrides
+        node.consume_external_attrs(ohai_data, @json_attribs)
+
+        setup_run_list_override
+
+        @run_list_expansion = expand_run_list
+
+        # @run_list_expansion is a RunListExpansion.
+        #
+        # Convert @expanded_run_list, which is an
+        # Array of Hashes of the form
+        #   {:name => NAME, :version_constraint => Chef::VersionConstraint },
+        # into @expanded_run_list_with_versions, an
+        # Array of Strings of the form
+        #   "#{NAME}@#{VERSION}"
+        @expanded_run_list_with_versions = @run_list_expansion.recipes.with_version_constraints_strings
+
+        Chef::Log.info("Run List is [#{node.run_list}]")
+        Chef::Log.info("Run List expands to [#{@expanded_run_list_with_versions.join(', ')}]")
+
+
+        events.node_load_completed(node, @expanded_run_list_with_versions, Chef::Config)
+
+        node
+      end
+
+      ########################################
+      # Internal public API
+      ########################################
+
+      def expand_run_list
+        if Chef::Config[:solo]
+          node.expand!('disk')
+        else
+          node.expand!('server')
+        end
+      rescue Exception => e
+        # TODO: wrap/munge exception with useful error output.
+        events.run_list_expand_failed(node, e)
+        raise
+      end
+
+      # Sync_cookbooks eagerly loads all files except files and
+      # templates.  It returns the cookbook_hash -- the return result
+      # from /environments/#{node.chef_environment}/cookbook_versions,
+      # which we will use for our run_context.
+      #
+      # === Returns
+      # Hash:: The hash of cookbooks with download URLs as given by the server
+      def sync_cookbooks
+        Chef::Log.debug("Synchronizing cookbooks")
+
+        begin
+          events.cookbook_resolution_start(@expanded_run_list_with_versions)
+          cookbook_hash = api_service.post("environments/#{node.chef_environment}/cookbook_versions",
+                                         {:run_list => @expanded_run_list_with_versions})
+        rescue Exception => e
+          # TODO: wrap/munge exception to provide helpful error output
+          events.cookbook_resolution_failed(@expanded_run_list_with_versions, e)
+          raise
+        else
+          events.cookbook_resolution_complete(cookbook_hash)
+        end
+
+        synchronizer = Chef::CookbookSynchronizer.new(cookbook_hash, events)
+        synchronizer.sync_cookbooks
+
+        # register the file cache path in the cookbook path so that CookbookLoader actually picks up the synced cookbooks
+        Chef::Config[:cookbook_path] = File.join(Chef::Config[:file_cache_path], "cookbooks")
+
+        cookbook_hash
+      end
+
+      def setup_run_list_override
+        runlist_override_sanity_check!
+        unless(override_runlist.empty?)
+          @original_runlist = node.run_list.run_list_items.dup
+          node.run_list(*override_runlist)
+          Chef::Log.warn "Run List override has been provided."
+          Chef::Log.warn "Original Run List: [#{original_runlist.join(', ')}]"
+          Chef::Log.warn "Overridden Run List: [#{node.run_list}]"
+        end
+      end
+
+      # Ensures runlist override contains RunListItem instances
+      def runlist_override_sanity_check!
+        # Convert to array and remove whitespace
+        if override_runlist.is_a?(String)
+          @override_runlist = override_runlist.split(',').map { |e| e.strip }
+        end
+        @override_runlist = [override_runlist].flatten.compact
+        override_runlist.map! do |item|
+          if(item.is_a?(Chef::RunList::RunListItem))
+            item
+          else
+            Chef::RunList::RunListItem.new(item)
+          end
+        end
+      end
+
+      def api_service
+        @api_service ||= Chef::REST.new(config[:chef_server_url])
+      end
+
+      def config
+        Chef::Config
+      end
+
+    end
+  end
+end
diff --git a/lib/chef/policy_builder/policyfile.rb b/lib/chef/policy_builder/policyfile.rb
new file mode 100644
index 0000000000..3c89f810fa
--- /dev/null
+++ b/lib/chef/policy_builder/policyfile.rb
@@ -0,0 +1,329 @@
+#
+# Author:: Adam Jacob (<adam@opscode.com>)
+# Author:: Tim Hinderliter (<tim@opscode.com>)
+# Author:: Christopher Walters (<cw@opscode.com>)
+# Author:: Daniel DeLeo (<dan@getchef.com>)
+# Copyright:: Copyright 2008-2014 Chef Software, Inc.
+# License:: Apache License, Version 2.0
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+require 'chef/log'
+require 'chef/rest'
+require 'chef/run_context'
+require 'chef/config'
+require 'chef/node'
+
+class Chef
+  module PolicyBuilder
+
+    # Policyfile is an experimental policy builder implementation that gets run
+    # list and cookbook version information from a single document.
+    #
+    # == WARNING
+    # This implementation is experimental. It may be changed in incompatible
+    # ways in minor or even patch releases, or even abandoned altogether. If
+    # using this with other tools, you may be forced to upgrade those tools in
+    # lockstep with chef-client because of incompatible behavior changes.
+    #
+    # == Unsupported Options:
+    # * override_runlist:: This could potentially be integrated into the
+    # policyfile, or replaced with a similar feature that has different
+    # semantics.
+    # * specific_recipes:: put more design thought into this use case.
+    # * run_list in json_attribs:: would be ignored anyway, so it raises an error.
+    # * chef-solo:: not currently supported. Need more design thought around
+    # how this should work.
+    class Policyfile
+
+      class UnsupportedFeature < StandardError; end
+
+      class PolicyfileError < StandardError; end
+
+      RunListExpansionIsh = Struct.new(:recipes)
+
+      attr_reader :events
+      attr_reader :node
+      attr_reader :node_name
+      attr_reader :ohai_data
+      attr_reader :json_attribs
+      attr_reader :run_context
+
+      def initialize(node_name, ohai_data, json_attribs, override_runlist, events)
+        @node_name = node_name
+        @ohai_data = ohai_data
+        @json_attribs = json_attribs
+        @events = events
+
+        @node = nil
+
+        Chef::Log.warn("Using experimental Policyfile feature")
+
+        if Chef::Config[:solo]
+          raise UnsupportedFeature, "Policyfile does not support chef-solo at this time."
+        end
+
+        if override_runlist
+          raise UnsupportedFeature, "Policyfile does not support override run lists at this time"
+        end
+
+        if json_attribs && json_attribs.key?("run_list")
+          raise UnsupportedFeature, "Policyfile does not support setting the run_list in json data at this time"
+        end
+
+        if Chef::Config[:environment] && !Chef::Config[:environment].chop.empty?
+          raise UnsupportedFeature, "Policyfile does not work with Chef Environments"
+        end
+      end
+
+      ## API Compat ##
+      # Methods related to unsupported features
+
+      # Override run_list is not supported.
+      def original_runlist
+        nil
+      end
+
+      # Override run_list is not supported.
+      def override_runlist
+        nil
+      end
+
+      # Policyfile gives you the run_list already expanded, no expansion is
+      # performed here.
+      def run_list_expansion
+        nil
+      end
+
+      ## PolicyBuilder API ##
+
+      # Loads the node state from the server.
+      def load_node
+        events.node_load_start(node_name, Chef::Config)
+        Chef::Log.debug("Building node object for #{node_name}")
+
+        @node = Chef::Node.find_or_create(node_name)
+        validate_policyfile
+        node
+      rescue Exception => e
+        events.node_load_failed(node_name, e, Chef::Config)
+        raise
+      end
+
+      # Applies environment, external JSON attributes, and override run list to
+      # the node, Then expands the run_list.
+      #
+      # === Returns
+      # node<Chef::Node>:: The modified node object. node is modified in place.
+      def build_node
+        # consume_external_attrs may add items to the run_list. Save the
+        # expanded run_list, which we will pass to the server later to
+        # determine which versions of cookbooks to use.
+        node.reset_defaults_and_overrides
+
+        node.consume_external_attrs(ohai_data, json_attribs)
+
+        apply_policyfile_attributes
+
+        Chef::Log.info("Run List is [#{run_list}]")
+        Chef::Log.info("Run List expands to [#{run_list_with_versions_for_display.join(', ')}]")
+
+
+        events.node_load_completed(node, run_list_with_versions_for_display, Chef::Config)
+
+        node
+      rescue Exception => e
+        events.node_load_failed(node_name, e, Chef::Config)
+        raise
+      end
+
+      def setup_run_context(specific_recipes=nil)
+        # TODO: This file vendor stuff is duplicated and initializing it with a
+        # block traps a reference to this object in a global context which will
+        # prevent it from getting GC'd. Simplify it.
+        Chef::Cookbook::FileVendor.on_create { |manifest| Chef::Cookbook::RemoteFileVendor.new(manifest, api_service) }
+        sync_cookbooks
+        cookbook_collection = Chef::CookbookCollection.new(cookbooks_to_sync)
+        run_context = Chef::RunContext.new(node, cookbook_collection, events)
+
+        run_context.load(run_list_expansion_ish)
+
+        run_context
+      end
+
+      ## Internal Public API ##
+
+      def sync_cookbooks
+        Chef::Log.debug("Synchronizing cookbooks")
+        synchronizer = Chef::CookbookSynchronizer.new(cookbooks_to_sync, events)
+        synchronizer.sync_cookbooks
+
+        # register the file cache path in the cookbook path so that CookbookLoader actually picks up the synced cookbooks
+        Chef::Config[:cookbook_path] = File.join(Chef::Config[:file_cache_path], "cookbooks")
+
+        cookbooks_to_sync
+      end
+
+
+      def run_list_with_versions_for_display
+        run_list.map do |recipe_spec|
+          cookbook, recipe = parse_recipe_spec(recipe_spec)
+          lock_data = cookbook_lock_for(cookbook)
+          display = "#{cookbook}::#{recipe}@#{lock_data["version"]} (#{lock_data["identifier"][0...7]})"
+          display
+        end
+      end
+
+      def run_list_expansion_ish
+        recipes = run_list.map do |recipe_spec|
+          cookbook, recipe = parse_recipe_spec(recipe_spec)
+          "#{cookbook}::#{recipe}"
+        end
+        RunListExpansionIsh.new(recipes)
+      end
+
+      def apply_policyfile_attributes
+        node.run_list(run_list)
+        node.automatic_attrs[:roles] = []
+        node.automatic_attrs[:recipes] = run_list_expansion_ish.recipes
+        node.attributes.role_default = policy["default_attributes"]
+        node.attributes.role_override = policy["override_attributes"]
+      end
+
+      def parse_recipe_spec(recipe_spec)
+        rmatch = recipe_spec.match(/recipe\[([^:]+)::([^:]+)\]/)
+        if rmatch.nil?
+          raise PolicyfileError, "invalid recipe specification #{recipe_spec} in Policyfile from #{policyfile_location}"
+        else
+          [rmatch[1], rmatch[2]]
+        end
+      end
+
+      def cookbook_lock_for(cookbook_name)
+        cookbook_locks[cookbook_name]
+      end
+
+      def run_list
+        policy["run_list"]
+      end
+
+      def policy
+        @policy ||= http_api.get(policyfile_location)
+      rescue Net::HTTPServerException => e
+        raise ConfigurationError, "Error loading policyfile from `#{policyfile_location}': #{e.class} - #{e.message}"
+      end
+
+      def policyfile_location
+        "data/policyfiles/#{deployment_group}"
+      end
+
+      # Do some mimimal validation of the policyfile we fetched from the
+      # server. Compatibility mode relies on using data bags to store policy
+      # files; therefore no real validation will be performed server-side and
+      # we need to make additional checks to ensure the data will be formatted
+      # correctly.
+      def validate_policyfile
+        errors = []
+        unless run_list
+          errors << "Policyfile is missing run_list element"
+        end
+        unless policy.key?("cookbook_locks")
+          errors << "Policyfile is missing cookbook_locks element"
+        end
+        if run_list.kind_of?(Array)
+          run_list_errors = run_list.select do |maybe_recipe_spec|
+            validate_recipe_spec(maybe_recipe_spec)
+          end
+          errors += run_list_errors
+        else
+          errors << "Policyfile run_list is malformed, must be an array of `recipe[cb_name::recipe_name]` items: #{policy["run_list"]}"
+        end
+
+        unless errors.empty?
+          raise PolicyfileError, "Policyfile fetched from #{policyfile_location} was invalid:\n#{errors.join("\n")}"
+        end
+      end
+
+      def validate_recipe_spec(recipe_spec)
+        parse_recipe_spec(recipe_spec)
+        nil
+      rescue PolicyfileError => e
+        e.message
+      end
+
+      class ConfigurationError < StandardError; end
+
+      def deployment_group
+        Chef::Config[:deployment_group] or
+          raise ConfigurationError, "Setting `deployment_group` is not configured."
+      end
+
+      # Builds a 'cookbook_hash' map of the form
+      #   "COOKBOOK_NAME" => "IDENTIFIER"
+      #
+      # This can be passed to a Chef::CookbookSynchronizer object to
+      # synchronize the cookbooks.
+      #
+      # TODO: Currently this makes N API calls to the server to get the
+      # cookbook objects. With server support (bulk API or the like), this
+      # should be reduced to a single call.
+      def cookbooks_to_sync
+        @cookbook_to_sync ||= begin
+          events.cookbook_resolution_start(run_list_with_versions_for_display)
+
+          cookbook_versions_by_name = cookbook_locks.inject({}) do |cb_map, (name, lock_data)|
+            cb_map[name] = manifest_for(name, lock_data)
+            cb_map
+          end
+          events.cookbook_resolution_complete(cookbook_versions_by_name)
+
+          cookbook_versions_by_name
+        end
+      rescue Exception => e
+        # TODO: wrap/munge exception to provide helpful error output
+        events.cookbook_resolution_failed(run_list_with_versions_for_display, e)
+        raise
+      end
+
+      # Fetches the CookbookVersion object for the given name and identifer
+      # specified in the lock_data.
+      # TODO: This only implements Chef 11 compatibility mode, which means that
+      # cookbooks are fetched by the "dotted_decimal_identifier": a
+      # representation of a SHA1 in the traditional x.y.z version format.
+      def manifest_for(cookbook_name, lock_data)
+        xyz_version = lock_data["dotted_decimal_identifier"]
+        http_api.get("cookbooks/#{cookbook_name}/#{xyz_version}")
+      rescue Exception => e
+        message = "Error loading cookbook #{cookbook_name} at version #{xyz_version}: #{e.class} - #{e.message}"
+        err = Chef::Exceptions::CookbookNotFound.new(message)
+        err.set_backtrace(e.backtrace)
+        raise err
+      end
+
+      def cookbook_locks
+        policy["cookbook_locks"]
+      end
+
+      def http_api
+        @api_service ||= Chef::REST.new(config[:chef_server_url])
+      end
+
+      def config
+        Chef::Config
+      end
+
+    end
+  end
+end
+
diff --git a/spec/unit/policy_builder/expand_node_object_spec.rb b/spec/unit/policy_builder/expand_node_object_spec.rb
new file mode 100644
index 0000000000..b452f98c80
--- /dev/null
+++ b/spec/unit/policy_builder/expand_node_object_spec.rb
@@ -0,0 +1,295 @@
+#
+# Author:: Daniel DeLeo (<dan@getchef.com>)
+# Copyright:: Copyright 2014 Chef Software, Inc.
+# License:: Apache License, Version 2.0
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+require 'spec_helper'
+require 'chef/policy_builder'
+
+describe Chef::PolicyBuilder::ExpandNodeObject do
+
+  let(:node_name) { "joe_node" }
+  let(:ohai_data) { {"platform" => "ubuntu", "platform_version" => "13.04", "fqdn" => "joenode.example.com"} }
+  let(:json_attribs) { {"run_list" => []} }
+  let(:override_runlist) { "recipe[foo::default]" }
+  let(:events) { Chef::EventDispatch::Dispatcher.new }
+  let(:policy_builder) { Chef::PolicyBuilder::ExpandNodeObject.new(node_name, ohai_data, json_attribs, override_runlist, events) }
+
+  # All methods that Chef::Client calls on this class.
+  describe "Public API" do
+    it "implements a node method" do
+      expect(policy_builder).to respond_to(:node)
+    end
+
+    it "implements a load_node method" do
+      expect(policy_builder).to respond_to(:load_node)
+    end
+
+    it "implements  a build_node method" do
+      expect(policy_builder).to respond_to(:build_node)
+    end
+
+    it "implements a setup_run_context method that accepts a list of recipe files to run" do
+      expect(policy_builder).to respond_to(:setup_run_context)
+      expect(policy_builder.method(:setup_run_context).arity).to eq(-1) #optional argument
+    end
+
+    it "implements a run_context method" do
+      expect(policy_builder).to respond_to(:run_context)
+    end
+
+    describe "loading the node" do
+
+      context "on chef-solo" do
+
+        before do
+          Chef::Config[:solo] = true
+        end
+
+        it "creates a new in-memory node object with the given name" do
+          policy_builder.load_node
+          policy_builder.node.name.should == node_name
+        end
+
+      end
+
+      context "on chef-client" do
+
+        let(:node) { Chef::Node.new.tap { |n| n.name(node_name) } }
+
+        it "loads or creates a node on the server" do
+          Chef::Node.should_receive(:find_or_create).with(node_name).and_return(node)
+          policy_builder.load_node
+          policy_builder.node.should == node
+        end
+
+      end
+    end
+
+    describe "building the node" do
+
+      # XXX: Chef::Client just needs to be able to call this, it doesn't depend on the return value.
+      it "builds the node and returns the updated node object" do
+        pending
+      end
+
+    end
+
+  end
+
+  # Implementation specific tests
+
+  describe "when first created" do
+
+    it "has a node_name" do
+      expect(policy_builder.node_name).to eq(node_name)
+    end
+
+    it "has ohai data" do
+      expect(policy_builder.ohai_data).to eq(ohai_data)
+    end
+
+    it "has a set of attributes from command line option" do
+      expect(policy_builder.json_attribs).to eq(json_attribs)
+    end
+
+    it "has an override_runlist" do
+      expect(policy_builder.override_runlist).to eq(override_runlist)
+    end
+
+  end
+
+  describe "building the node" do
+
+    let(:configured_environment) { nil }
+    let(:json_attribs) { nil }
+
+    let(:override_runlist) { nil }
+    let(:primary_runlist) { ["recipe[primary::default]"] }
+
+    let(:original_default_attrs) { {"default_key" => "default_value"} }
+    let(:original_override_attrs) { {"override_key" => "override_value"} }
+
+    let(:node) do
+      node = Chef::Node.new
+      node.name(node_name)
+      node.default_attrs = original_default_attrs
+      node.override_attrs = original_override_attrs
+      node.run_list(primary_runlist)
+      node
+    end
+
+    before do
+      Chef::Config[:environment] = configured_environment
+      Chef::Node.should_receive(:find_or_create).with(node_name).and_return(node)
+      policy_builder.load_node
+      policy_builder.build_node
+    end
+
+    it "sanity checks test setup" do
+      expect(node.run_list).to eq(primary_runlist)
+    end
+
+    it "clears existing default and override attributes from the node" do
+      expect(node["default_key"]).to be_nil
+      expect(node["override_key"]).to be_nil
+    end
+
+    it "applies ohai data to the node" do
+      expect(node["fqdn"]).to eq(ohai_data["fqdn"])
+    end
+
+    describe "when the given run list is not in expanded form" do
+
+      # NOTE: for chef-client, the behavior is always to expand the run list,
+      # but this operation is a no-op when none of the run list items are
+      # roles. Because of the amount of mocking required to make this work in
+      # tests, this test is isolated from the others.
+
+      let(:primary_runlist) { ["role[some_role]"] }
+      let(:expansion) do
+        recipe_list = Chef::RunList::VersionedRecipeList.new
+        recipe_list.add_recipe("recipe[from_role::default", "1.0.2")
+        double("RunListExpansion", :recipes => recipe_list)
+      end
+
+      let(:node) do
+        node = Chef::Node.new
+        node.name(node_name)
+        node.default_attrs = original_default_attrs
+        node.override_attrs = original_override_attrs
+        node.run_list(primary_runlist)
+
+        node.should_receive(:expand!).with("server") do
+          node.run_list("recipe[from_role::default]")
+          expansion
+        end
+
+        node
+      end
+
+      it "expands run list items via the server API" do
+        expect(node.run_list).to eq(["recipe[from_role::default]"])
+      end
+
+    end
+
+    context "when JSON attributes are given on the command line" do
+
+      let(:json_attribs) { {"run_list" => ["recipe[json_attribs::default]"], "json_attribs_key" => "json_attribs_value"  } }
+
+      it "sets the run list according to the given JSON" do
+        expect(node.run_list).to eq(["recipe[json_attribs::default]"])
+      end
+
+      it "sets node attributes according to the given JSON" do
+        expect(node["json_attribs_key"]).to eq("json_attribs_value")
+      end
+
+    end
+
+    context "when an override_runlist is given" do
+
+      let(:override_runlist) { "recipe[foo::default]" }
+
+      it "sets the override run_list on the node" do
+        expect(node.run_list).to eq([override_runlist])
+        expect(policy_builder.original_runlist).to eq(primary_runlist)
+      end
+
+    end
+
+    context "when no environment is specified" do
+
+      it "does not set the environment" do
+        expect(node.chef_environment).to eq("_default")
+      end
+
+    end
+
+    context "when a custom environment is configured" do
+
+      let(:configured_environment) { environment.name }
+
+      let(:environment) do
+        environment = Chef::Environment.new.tap {|e| e.name("prod") }
+        Chef::Environment.should_receive(:load).with("prod").and_return(environment)
+        environment
+      end
+
+      it "sets the environment as configured" do
+        expect(node.chef_environment).to eq(environment.name)
+      end
+    end
+
+  end
+
+  describe "configuring the run_context" do
+    let(:json_attribs) { nil }
+    let(:override_runlist) { nil }
+
+    let(:node) do
+      node = Chef::Node.new
+      node.name(node_name)
+      node.run_list("recipe[first::default]", "recipe[second::default]")
+      node
+    end
+
+    let(:chef_http) { double("Chef::REST") }
+
+    let(:cookbook_resolve_url) { "environments/#{node.chef_environment}/cookbook_versions" }
+    let(:cookbook_resolve_post_data) { {:run_list=>["first::default", "second::default"]} }
+
+    # cookbook_hash is just a hash, but since we're passing it between mock
+    # objects, we get a little better test strictness by using a double (which
+    # will have object equality rather than semantic equality #== semantics).
+    let(:cookbook_hash) { double("cookbook hash", :each => nil) }
+
+    let(:cookbook_synchronizer) { double("CookbookSynchronizer") }
+
+    before do
+      Chef::Node.should_receive(:find_or_create).with(node_name).and_return(node)
+
+      policy_builder.stub(:api_service).and_return(chef_http)
+
+      policy_builder.load_node
+      policy_builder.build_node
+
+      run_list_expansion = policy_builder.run_list_expansion
+
+      chef_http.should_receive(:post).with(cookbook_resolve_url, cookbook_resolve_post_data).and_return(cookbook_hash)
+      Chef::CookbookSynchronizer.should_receive(:new).with(cookbook_hash, events).and_return(cookbook_synchronizer)
+      cookbook_synchronizer.should_receive(:sync_cookbooks)
+
+      Chef::RunContext.any_instance.should_receive(:load).with(run_list_expansion)
+
+      policy_builder.setup_run_context
+    end
+
+    it "configures FileVendor to fetch files remotely" do
+      manifest = double("cookbook manifest")
+      Chef::Cookbook::RemoteFileVendor.should_receive(:new).with(manifest, chef_http)
+      Chef::Cookbook::FileVendor.create_from_manifest(manifest)
+    end
+
+    it "triggers cookbook compilation in the run_context" do
+      # Test condition already covered by `Chef::RunContext.any_instance.should_receive(:load).with(run_list_expansion)`
+    end
+
+  end
+
+end
+
diff --git a/spec/unit/policy_builder/policyfile_spec.rb b/spec/unit/policy_builder/policyfile_spec.rb
new file mode 100644
index 0000000000..7e83dce804
--- /dev/null
+++ b/spec/unit/policy_builder/policyfile_spec.rb
@@ -0,0 +1,391 @@
+#
+# Author:: Daniel DeLeo (<dan@getchef.com>)
+# Copyright:: Copyright 2014 Chef Software, Inc.
+# License:: Apache License, Version 2.0
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+require 'spec_helper'
+require 'chef/policy_builder'
+
+describe Chef::PolicyBuilder::Policyfile do
+
+  let(:node_name) { "joe_node" }
+  let(:ohai_data) { {"platform" => "ubuntu", "platform_version" => "13.04", "fqdn" => "joenode.example.com"} }
+  let(:json_attribs) { {"custom_attr" => "custom_attr_value"} }
+  let(:override_runlist) { nil }
+  let(:events) { Chef::EventDispatch::Dispatcher.new }
+  let(:policy_builder) { Chef::PolicyBuilder::Policyfile.new(node_name, ohai_data, json_attribs, override_runlist, events) }
+
+  # Convert a SHA1 (160 bit) hex string into an x.y.z version number where the
+  # maximum value is smaller than a postgres BIGINT (signed 64bit, so 63 usable
+  # bits). This requires enterprise Chef or open source server 11.1.0+ (currently not released)
+  #
+  # The SHA1 is devided as follows:
+  # * "major": first 14 chars (56 bits)
+  # * "minor": next 14 chars (56 bits)
+  # * "patch": last 12 chars (48 bits)
+  def id_to_dotted(sha1_id)
+    major = sha1_id[0...14]
+    minor = sha1_id[14...28]
+    patch = sha1_id[28..40]
+    decimal_integers =[major, minor, patch].map {|hex| hex.to_i(16) }
+    decimal_integers.join(".")
+  end
+
+
+  let(:example1_lock_data) do
+    # based on https://github.com/danielsdeleo/chef-workflow2-prototype/blob/master/skeletons/basic_policy/Policyfile.lock.json
+    {
+      "identifier" => "168d2102fb11c9617cd8a981166c8adc30a6e915",
+      "version" => "2.3.5",
+      # NOTE: for compatibility mode we include the dotted id in the policyfile to enhance discoverability.
+      "dotted_decimal_identifier" => id_to_dotted("168d2102fb11c9617cd8a981166c8adc30a6e915"),
+      "source" => { "path" => "./cookbooks/demo" },
+      "scm_identifier"=> {
+        "vcs"=> "git",
+        "rev_id"=> "9d5b09026470c322c3cb5ca8a4157c4d2f16cef3",
+        "remote"=> nil
+      }
+    }
+  end
+
+  let(:example2_lock_data) do
+    {
+      "identifier" => "feab40e1fca77c7360ccca1481bb8ba5f919ce3a",
+      "version" => "4.2.0",
+      # NOTE: for compatibility mode we include the dotted id in the policyfile to enhance discoverability.
+      "dotted_decimal_identifier" => id_to_dotted("feab40e1fca77c7360ccca1481bb8ba5f919ce3a"),
+      "source" => { "api" => "https://community.getchef.com/api/v1/cookbooks/example2" }
+    }
+  end
+
+  let(:policyfile_default_attributes) { {"policyfile_default_attr" => "policyfile_default_value"} }
+  let(:policyfile_override_attributes) { {"policyfile_override_attr" => "policyfile_override_value"} }
+
+  let(:policyfile_run_list) { ["recipe[example1::default]", "recipe[example2::server]"] }
+
+  let(:parsed_policyfile_json) do
+    {
+      "run_list" => policyfile_run_list,
+
+      "cookbook_locks" => {
+        "example1" => example1_lock_data,
+        "example2" => example2_lock_data
+      },
+
+      "default_attributes" => policyfile_default_attributes,
+      "override_attributes" => policyfile_override_attributes
+    }
+  end
+
+  let(:err_namespace) { Chef::PolicyBuilder::Policyfile }
+
+  it "configures a Chef HTTP API client" do
+    http = double("Chef::REST")
+    server_url = "https://api.opscode.com/organizations/example"
+    Chef::Config[:chef_server_url] = server_url
+    Chef::REST.should_receive(:new).with(server_url).and_return(http)
+    expect(policy_builder.http_api).to eq(http)
+  end
+
+  describe "reporting unsupported features" do
+
+    def initialize_pb
+      Chef::PolicyBuilder::Policyfile.new(node_name, ohai_data, json_attribs, override_runlist, events)
+    end
+
+    context "chef-solo" do
+      before { Chef::Config[:solo] = true }
+
+      it "errors on create" do
+        expect { initialize_pb }.to raise_error(err_namespace::UnsupportedFeature)
+      end
+    end
+
+    context "when given an override run_list" do
+      let(:override_runlist) { "recipe[foo],recipe[bar]" }
+
+      it "errors on create" do
+        expect { initialize_pb }.to raise_error(err_namespace::UnsupportedFeature)
+      end
+    end
+
+    context "when json_attribs contains a run_list" do
+      let(:json_attribs) { {"run_list" => []} }
+
+      it "errors on create" do
+        expect { initialize_pb }.to raise_error(err_namespace::UnsupportedFeature)
+      end
+    end
+
+    context "when an environment is configured" do
+      before { Chef::Config[:environment] = "blurch" }
+
+      it "errors when an environment is configured" do
+        expect { initialize_pb }.to raise_error(err_namespace::UnsupportedFeature)
+      end
+    end
+
+  end
+
+  describe "when using compatibility mode" do
+
+    let(:http_api) { double("Chef::REST") }
+
+    let(:configured_environment) { nil }
+
+    let(:override_runlist) { nil }
+    let(:primary_runlist) { nil }
+
+    let(:original_default_attrs) { {"default_key" => "default_value"} }
+    let(:original_override_attrs) { {"override_key" => "override_value"} }
+
+    let(:node) do
+      node = Chef::Node.new
+      node.name(node_name)
+      node.default_attrs = original_default_attrs
+      node.override_attrs = original_override_attrs
+      node.run_list(primary_runlist) if primary_runlist
+      node
+    end
+
+    before do
+      # TODO: agree on this name and logic.
+      Chef::Config[:deployment_group] = "example-policy-stage"
+      policy_builder.stub(:http_api).and_return(http_api)
+    end
+
+    context "when the deployment group cannot be loaded" do
+      let(:error404) { Net::HTTPServerException.new("404 message", :body) }
+
+      before do
+        Chef::Node.should_receive(:find_or_create).with(node_name).and_return(node)
+        http_api.should_receive(:get).
+          with("data/policyfiles/example-policy-stage").
+          and_raise(error404)
+      end
+
+      it "raises an error" do
+        expect { policy_builder.load_node }.to raise_error(err_namespace::ConfigurationError)
+      end
+
+      it "sends error message to the event system" do
+        events.should_receive(:node_load_failed).with(node_name, an_instance_of(err_namespace::ConfigurationError), Chef::Config)
+        expect { policy_builder.load_node }.to raise_error(err_namespace::ConfigurationError)
+      end
+
+    end
+
+    describe "when the deployment_group is not configured" do
+      before do
+        Chef::Config[:deployment_group] = nil
+        Chef::Node.should_receive(:find_or_create).with(node_name).and_return(node)
+      end
+
+      it "errors while loading the node" do
+        expect { policy_builder.load_node }.to raise_error(err_namespace::ConfigurationError)
+      end
+
+
+      it "passes error information to the event system" do
+        # TODO: also make sure something acceptable happens with the error formatters
+        err_class = err_namespace::ConfigurationError
+        events.should_receive(:node_load_failed).with(node_name, an_instance_of(err_class), Chef::Config)
+        expect { policy_builder.load_node }.to raise_error(err_class)
+      end
+    end
+
+    context "and a deployment_group is configured" do
+      before do
+        http_api.should_receive(:get).with("data/policyfiles/example-policy-stage").and_return(parsed_policyfile_json)
+      end
+
+      it "fetches the policy file from a data bag item" do
+        expect(policy_builder.policy).to eq(parsed_policyfile_json)
+      end
+
+      it "extracts the run_list from the policyfile" do
+        expect(policy_builder.run_list).to eq(policyfile_run_list)
+      end
+
+      it "extracts the cookbooks and versions for display from the policyfile" do
+        expected = [
+          "example1::default@2.3.5 (168d210)",
+          "example2::server@4.2.0 (feab40e)"
+        ]
+
+        expect(policy_builder.run_list_with_versions_for_display).to eq(expected)
+      end
+
+      it "generates a RunListExpansion-alike object for feeding to the CookbookCompiler" do
+        expect(policy_builder.run_list_expansion_ish).to respond_to(:recipes)
+        expect(policy_builder.run_list_expansion_ish.recipes).to eq(["example1::default", "example2::server"])
+      end
+
+
+      describe "validating the Policyfile.lock" do
+
+        it "errors if the policyfile json contains any non-recipe items" do
+          parsed_policyfile_json["run_list"] = ["role[foo]"]
+          expect { policy_builder.validate_policyfile }.to raise_error(err_namespace::PolicyfileError)
+        end
+
+        it "errors if the policyfile json contains non-fully qualified recipe items" do
+          parsed_policyfile_json["run_list"] = ["recipe[foo]"]
+          expect { policy_builder.validate_policyfile }.to raise_error(err_namespace::PolicyfileError)
+        end
+
+        it "errors if the policyfile doesn't have a run_list key" do
+          parsed_policyfile_json.delete("run_list")
+          expect { policy_builder.validate_policyfile }.to raise_error(err_namespace::PolicyfileError)
+        end
+
+        it "error if the policyfile doesn't have a cookbook_locks key" do
+          parsed_policyfile_json.delete("cookbook_locks")
+          expect { policy_builder.validate_policyfile }.to raise_error(err_namespace::PolicyfileError)
+        end
+
+        it "accepts a valid policyfile" do
+          policy_builder.validate_policyfile
+        end
+
+      end
+
+      describe "building the node object" do
+
+        before do
+          Chef::Node.should_receive(:find_or_create).with(node_name).and_return(node)
+
+          policy_builder.load_node
+          policy_builder.build_node
+        end
+
+        it "resets default and override data" do
+          expect(node["default_key"]).to be_nil
+          expect(node["override_key"]).to be_nil
+        end
+
+        it "applies ohai data" do
+          expect(ohai_data).to_not be_empty # ensure test is testing something
+          ohai_data.each do |key, value|
+            expect(node.automatic_attrs[key]).to eq(value)
+          end
+        end
+
+        it "applies attributes from json file" do
+          expect(node["custom_attr"]).to eq("custom_attr_value")
+        end
+
+        it "applies attributes from the policyfile" do
+          expect(node["policyfile_default_attr"]).to eq("policyfile_default_value")
+          expect(node["policyfile_override_attr"]).to eq("policyfile_override_value")
+        end
+
+        it "sets the policyfile's run_list on the node object" do
+          expect(node.run_list).to eq(policyfile_run_list)
+        end
+
+        it "creates node.automatic_attrs[:roles]" do
+          expect(node.automatic_attrs[:roles]).to eq([])
+        end
+
+        it "create node.automatic_attrs[:recipes]" do
+          expect(node.automatic_attrs[:recipes]).to eq(["example1::default", "example2::server"])
+        end
+
+      end
+
+
+      describe "fetching the desired cookbook set" do
+
+        let(:example1_cookbook_object) { double("Chef::CookbookVersion for example1 cookbook") }
+        let(:example2_cookbook_object) { double("Chef::CookbookVersion for example2 cookbook") }
+
+        let(:expected_cookbook_hash) do
+          { "example1" => example1_cookbook_object, "example2" => example2_cookbook_object }
+        end
+
+        let(:example1_xyz_version) { example1_lock_data["dotted_decimal_identifier"] }
+        let(:example2_xyz_version) { example2_lock_data["dotted_decimal_identifier"] }
+
+        let(:cookbook_synchronizer) { double("Chef::CookbookSynchronizer") }
+
+        context "and a cookbook is missing" do
+
+          let(:error404) { Net::HTTPServerException.new("404 message", :body) }
+
+          before do
+            Chef::Node.should_receive(:find_or_create).with(node_name).and_return(node)
+
+            # Remove references to example2 cookbook because we're iterating
+            # over a Hash data structure and on ruby 1.8.7 iteration order will
+            # not be stable.
+            parsed_policyfile_json["cookbook_locks"].delete("example2")
+            parsed_policyfile_json["run_list"].delete("recipe[example2::server]")
+
+            policy_builder.load_node
+            policy_builder.build_node
+
+            http_api.should_receive(:get).with("cookbooks/example1/#{example1_xyz_version}").
+              and_raise(error404)
+          end
+
+          it "raises an error indicating which cookbook is missing" do
+            expect { policy_builder.cookbooks_to_sync }.to raise_error(Chef::Exceptions::CookbookNotFound)
+          end
+
+        end
+
+        context "and the cookbooks can be fetched" do
+          before do
+            Chef::Node.should_receive(:find_or_create).with(node_name).and_return(node)
+
+            policy_builder.load_node
+            policy_builder.build_node
+
+            http_api.should_receive(:get).with("cookbooks/example1/#{example1_xyz_version}").
+              and_return(example1_cookbook_object)
+            http_api.should_receive(:get).with("cookbooks/example2/#{example2_xyz_version}").
+              and_return(example2_cookbook_object)
+
+            Chef::CookbookSynchronizer.stub(:new).
+              with(expected_cookbook_hash, events).
+              and_return(cookbook_synchronizer)
+          end
+
+          it "builds a Hash of the form 'cookbook_name' => Chef::CookbookVersion" do
+            expect(policy_builder.cookbooks_to_sync).to eq(expected_cookbook_hash)
+          end
+
+          it "syncs the desired cookbooks via CookbookSynchronizer" do
+            cookbook_synchronizer.should_receive(:sync_cookbooks)
+            policy_builder.sync_cookbooks
+          end
+
+          it "builds a run context" do
+            cookbook_synchronizer.should_receive(:sync_cookbooks)
+            Chef::RunContext.any_instance.should_receive(:load).with(policy_builder.run_list_expansion_ish)
+            run_context = policy_builder.setup_run_context
+            expect(run_context.node).to eq(node)
+            expect(run_context.cookbook_collection.keys).to match_array(["example1", "example2"])
+          end
+
+        end
+      end
+    end
+
+  end
+
+end
diff --git a/spec/unit/policy_builder_spec.rb b/spec/unit/policy_builder_spec.rb
index 4b95c079b7..506911452c 100644
--- a/spec/unit/policy_builder_spec.rb
+++ b/spec/unit/policy_builder_spec.rb
@@ -21,274 +21,6 @@ require 'chef/policy_builder'
 
 describe Chef::PolicyBuilder do
 
-  let(:node_name) { "joe_node" }
-  let(:ohai_data) { {"platform" => "ubuntu", "platform_version" => "13.04", "fqdn" => "joenode.example.com"} }
-  let(:json_attribs) { {"run_list" => []} }
-  let(:override_runlist) { "recipe[foo::default]" }
-  let(:events) { Chef::EventDispatch::Dispatcher.new }
-  let(:policy_builder) { Chef::PolicyBuilder.new(node_name, ohai_data, json_attribs, override_runlist, events) }
-
-  # All methods that Chef::Client calls on this class.
-  describe "Public API" do
-    it "implements a node method" do
-      expect(policy_builder).to respond_to(:node)
-    end
-
-    it "implements a load_node method" do
-      expect(policy_builder).to respond_to(:load_node)
-    end
-
-    it "implements  a build_node method" do
-      expect(policy_builder).to respond_to(:build_node)
-    end
-
-    it "implements a setup_run_context method that accepts a list of recipe files to run" do
-      expect(policy_builder).to respond_to(:setup_run_context)
-      expect(policy_builder.method(:setup_run_context).arity).to eq(-1) #optional argument
-    end
-
-    it "implements a run_context method" do
-      expect(policy_builder).to respond_to(:run_context)
-    end
-
-    describe "loading the node" do
-
-      context "on chef-solo" do
-
-        before do
-          Chef::Config[:solo] = true
-        end
-
-        it "creates a new in-memory node object with the given name" do
-          policy_builder.load_node
-          policy_builder.node.name.should == node_name
-        end
-
-      end
-
-      context "on chef-client" do
-
-        let(:node) { Chef::Node.new.tap { |n| n.name(node_name) } }
-
-        it "loads or creates a node on the server" do
-          Chef::Node.should_receive(:find_or_create).with(node_name).and_return(node)
-          policy_builder.load_node
-          policy_builder.node.should == node
-        end
-
-      end
-    end
-
-    describe "building the node" do
-
-      # XXX: Chef::Client just needs to be able to call this, it doesn't depend on the return value.
-      it "builds the node and returns the updated node object" do
-        pending
-      end
-
-    end
-
-  end
-
-  # Implementation specific tests
-
-  describe "when first created" do
-
-    it "has a node_name" do
-      expect(policy_builder.node_name).to eq(node_name)
-    end
-
-    it "has ohai data" do
-      expect(policy_builder.ohai_data).to eq(ohai_data)
-    end
-
-    it "has a set of attributes from command line option" do
-      expect(policy_builder.json_attribs).to eq(json_attribs)
-    end
-
-    it "has an override_runlist" do
-      expect(policy_builder.override_runlist).to eq(override_runlist)
-    end
-
-  end
-
-  describe "building the node" do
-
-    let(:configured_environment) { nil }
-    let(:json_attribs) { nil }
-
-    let(:override_runlist) { nil }
-    let(:primary_runlist) { ["recipe[primary::default]"] }
-
-    let(:original_default_attrs) { {"default_key" => "default_value"} }
-    let(:original_override_attrs) { {"override_key" => "override_value"} }
-
-    let(:node) do
-      node = Chef::Node.new
-      node.name(node_name)
-      node.default_attrs = original_default_attrs
-      node.override_attrs = original_override_attrs
-      node.run_list(primary_runlist)
-      node
-    end
-
-    before do
-      Chef::Config[:environment] = configured_environment
-      Chef::Node.should_receive(:find_or_create).with(node_name).and_return(node)
-      policy_builder.load_node
-      policy_builder.build_node
-    end
-
-    it "sanity checks test setup" do
-      expect(node.run_list).to eq(primary_runlist)
-    end
-
-    it "clears existing default and override attributes from the node" do
-      expect(node["default_key"]).to be_nil
-      expect(node["override_key"]).to be_nil
-    end
-
-    it "applies ohai data to the node" do
-      expect(node["fqdn"]).to eq(ohai_data["fqdn"])
-    end
-
-    describe "when the given run list is not in expanded form" do
-
-      # NOTE: for chef-client, the behavior is always to expand the run list,
-      # but this operation is a no-op when none of the run list items are
-      # roles. Because of the amount of mocking required to make this work in
-      # tests, this test is isolated from the others.
-
-      let(:primary_runlist) { ["role[some_role]"] }
-      let(:expansion) do
-        recipe_list = Chef::RunList::VersionedRecipeList.new
-        recipe_list.add_recipe("recipe[from_role::default", "1.0.2")
-        double("RunListExpansion", :recipes => recipe_list)
-      end
-
-      let(:node) do
-        node = Chef::Node.new
-        node.name(node_name)
-        node.default_attrs = original_default_attrs
-        node.override_attrs = original_override_attrs
-        node.run_list(primary_runlist)
-
-        node.should_receive(:expand!).with("server") do
-          node.run_list("recipe[from_role::default]")
-          expansion
-        end
-
-        node
-      end
-
-      it "expands run list items via the server API" do
-        expect(node.run_list).to eq(["recipe[from_role::default]"])
-      end
-
-    end
-
-    context "when JSON attributes are given on the command line" do
-
-      let(:json_attribs) { {"run_list" => ["recipe[json_attribs::default]"], "json_attribs_key" => "json_attribs_value"  } }
-
-      it "sets the run list according to the given JSON" do
-        expect(node.run_list).to eq(["recipe[json_attribs::default]"])
-      end
-
-      it "sets node attributes according to the given JSON" do
-        expect(node["json_attribs_key"]).to eq("json_attribs_value")
-      end
-
-    end
-
-    context "when an override_runlist is given" do
-
-      let(:override_runlist) { "recipe[foo::default]" }
-
-      it "sets the override run_list on the node" do
-        expect(node.run_list).to eq([override_runlist])
-        expect(policy_builder.original_runlist).to eq(primary_runlist)
-      end
-
-    end
-
-    context "when no environment is specified" do
-
-      it "does not set the environment" do
-        expect(node.chef_environment).to eq("_default")
-      end
-
-    end
-
-    context "when a custom environment is configured" do
-
-      let(:configured_environment) { environment.name }
-
-      let(:environment) do
-        environment = Chef::Environment.new.tap {|e| e.name("prod") }
-        Chef::Environment.should_receive(:load).with("prod").and_return(environment)
-        environment
-      end
-
-      it "sets the environment as configured" do
-        expect(node.chef_environment).to eq(environment.name)
-      end
-    end
-
-  end
-
-  describe "configuring the run_context" do
-    let(:json_attribs) { nil }
-    let(:override_runlist) { nil }
-
-    let(:node) do
-      node = Chef::Node.new
-      node.name(node_name)
-      node.run_list("recipe[first::default]", "recipe[second::default]")
-      node
-    end
-
-    let(:chef_http) { double("Chef::REST") }
-
-    let(:cookbook_resolve_url) { "environments/#{node.chef_environment}/cookbook_versions" }
-    let(:cookbook_resolve_post_data) { {:run_list=>["first::default", "second::default"]} }
-
-    # cookbook_hash is just a hash, but since we're passing it between mock
-    # objects, we get a little better test strictness by using a double (which
-    # will have object equality rather than semantic equality #== semantics).
-    let(:cookbook_hash) { double("cookbook hash", :each => nil) }
-
-    let(:cookbook_synchronizer) { double("CookbookSynchronizer") }
-
-    before do
-      Chef::Node.should_receive(:find_or_create).with(node_name).and_return(node)
-
-      policy_builder.stub(:api_service).and_return(chef_http)
-
-      policy_builder.load_node
-      policy_builder.build_node
-
-      run_list_expansion = policy_builder.run_list_expansion
-
-      chef_http.should_receive(:post).with(cookbook_resolve_url, cookbook_resolve_post_data).and_return(cookbook_hash)
-      Chef::CookbookSynchronizer.should_receive(:new).with(cookbook_hash, events).and_return(cookbook_synchronizer)
-      cookbook_synchronizer.should_receive(:sync_cookbooks)
-
-      Chef::RunContext.any_instance.should_receive(:load).with(run_list_expansion)
-
-      policy_builder.setup_run_context
-    end
-
-    it "configures FileVendor to fetch files remotely" do
-      manifest = double("cookbook manifest")
-      Chef::Cookbook::RemoteFileVendor.should_receive(:new).with(manifest, chef_http)
-      Chef::Cookbook::FileVendor.create_from_manifest(manifest)
-    end
-
-    it "triggers cookbook compilation in the run_context" do
-      # Test condition already covered by `Chef::RunContext.any_instance.should_receive(:load).with(run_list_expansion)`
-    end
-
-  end
+  # TODO: test the strategy method
 
 end