(#7012) Split plumbing into Puppet::Interface

This splits out the plumbing into the Puppet::Interface namespace, and uses
Puppet::Faces for all the public-facing code.

The fault line is "what you care about if you are using or writing a face",
which is public, against "what you care about to enable either of those two",
which is the plumbing.

25 files changed, 259 insertions, 270 deletions

diff --git a/lib/puppet/faces.rb b/lib/puppet/faces.rb
index 07a745480..947eecf24 100644
--- a/lib/puppet/faces.rb
+++ b/lib/puppet/faces.rb
@@ -1,106 +1,12 @@
-require 'puppet'
-require 'puppet/util/autoload'
-
-class Puppet::Faces
-  require 'puppet/faces/face_collection'
-
-  require 'puppet/faces/action_manager'
-  include Puppet::Faces::ActionManager
-  extend Puppet::Faces::ActionManager
-
-  require 'puppet/faces/option_manager'
-  include Puppet::Faces::OptionManager
-  extend Puppet::Faces::OptionManager
-
-  include Puppet::Util
-
-  class << self
-    # This is just so we can search for actions.  We only use its
-    # list of directories to search.
-    # Can't we utilize an external autoloader, or simply use the $LOAD_PATH? -pvb
-    def autoloader
-      @autoloader ||= Puppet::Util::Autoload.new(:application, "puppet/faces")
-    end
-
-    def faces
-      Puppet::Faces::FaceCollection.faces
-    end
-
-    def face?(name, version)
-      Puppet::Faces::FaceCollection.face?(name, version)
-    end
-
-    def register(instance)
-      Puppet::Faces::FaceCollection.register(instance)
-    end
-
-    def define(name, version, &block)
-      if face?(name, version)
-        face = Puppet::Faces::FaceCollection[name, version]
-      else
-        face = self.new(name, version)
-        Puppet::Faces::FaceCollection.register(face)
-        # REVISIT: Shouldn't this be delayed until *after* we evaluate the
-        # current block, not done before? --daniel 2011-04-07
-        face.load_actions
-      end
-
-      face.instance_eval(&block) if block_given?
-
-      return face
-    end
-
-    alias :[] :define
-  end
-
-  attr_accessor :default_format
-
-  def set_default_format(format)
-    self.default_format = format.to_sym
-  end
-
-  attr_accessor :type, :verb, :version, :arguments
-  attr_reader :name
-
-  def initialize(name, version, &block)
-    unless Puppet::Faces::FaceCollection.validate_version(version)
-      raise ArgumentError, "Cannot create face #{name.inspect} with invalid version number '#{version}'!"
-    end
-
-    @name = Puppet::Faces::FaceCollection.underscorize(name)
-    @version = version
-    @default_format = :pson
-
-    instance_eval(&block) if block_given?
-  end
-
-  # Try to find actions defined in other files.
-  def load_actions
-    path = "puppet/faces/#{name}"
-
-    loaded = []
-    [path, "#{name}@#{version}/#{path}"].each do |path|
-      Puppet::Faces.autoloader.search_directories.each do |dir|
-        fdir = ::File.join(dir, path)
-        next unless FileTest.directory?(fdir)
-
-        Dir.chdir(fdir) do
-          Dir.glob("*.rb").each do |file|
-            aname = file.sub(/\.rb/, '')
-            if loaded.include?(aname)
-              Puppet.debug "Not loading duplicate action '#{aname}' for '#{name}' from '#{fdir}/#{file}'"
-              next
-            end
-            loaded << aname
-            Puppet.debug "Loading action '#{aname}' for '#{name}' from '#{fdir}/#{file}'"
-            require "#{Dir.pwd}/#{aname}"
-          end
-        end
-      end
-    end
-  end
-
-  def to_s
-    "Puppet::Faces[#{name.inspect}, #{version.inspect}]"
-  end
-end
+# The public name of this feature is 'faces', but we have hidden all the
+# plumbing over in the 'interfaces' namespace to make clear the distinction
+# between the two.
+#
+# This file exists to ensure that the public name is usable without revealing
+# the details of the implementation; you really only need go look at anything
+# under Interfaces if you are looking to extend the implementation.
+#
+# It isn't hidden to gratuitously hide things, just to make it easier to
+# separate out the interests people will have.  --daniel 2011-04-07
+require 'puppet/interface'
+Puppet::Faces = Puppet::Interface
diff --git a/lib/puppet/interface.rb b/lib/puppet/interface.rb
new file mode 100644
index 000000000..70484adfc
--- /dev/null
+++ b/lib/puppet/interface.rb
@@ -0,0 +1,106 @@
+require 'puppet'
+require 'puppet/util/autoload'
+
+class Puppet::Interface
+  require 'puppet/interface/face_collection'
+
+  require 'puppet/interface/action_manager'
+  include Puppet::Interface::ActionManager
+  extend Puppet::Interface::ActionManager
+
+  require 'puppet/interface/option_manager'
+  include Puppet::Interface::OptionManager
+  extend Puppet::Interface::OptionManager
+
+  include Puppet::Util
+
+  class << self
+    # This is just so we can search for actions.  We only use its
+    # list of directories to search.
+    # Can't we utilize an external autoloader, or simply use the $LOAD_PATH? -pvb
+    def autoloader
+      @autoloader ||= Puppet::Util::Autoload.new(:application, "puppet/faces")
+    end
+
+    def faces
+      Puppet::Interface::FaceCollection.faces
+    end
+
+    def face?(name, version)
+      Puppet::Interface::FaceCollection.face?(name, version)
+    end
+
+    def register(instance)
+      Puppet::Interface::FaceCollection.register(instance)
+    end
+
+    def define(name, version, &block)
+      if face?(name, version)
+        face = Puppet::Interface::FaceCollection[name, version]
+      else
+        face = self.new(name, version)
+        Puppet::Interface::FaceCollection.register(face)
+        # REVISIT: Shouldn't this be delayed until *after* we evaluate the
+        # current block, not done before? --daniel 2011-04-07
+        face.load_actions
+      end
+
+      face.instance_eval(&block) if block_given?
+
+      return face
+    end
+
+    alias :[] :define
+  end
+
+  attr_accessor :default_format
+
+  def set_default_format(format)
+    self.default_format = format.to_sym
+  end
+
+  attr_accessor :type, :verb, :version, :arguments
+  attr_reader :name
+
+  def initialize(name, version, &block)
+    unless Puppet::Interface::FaceCollection.validate_version(version)
+      raise ArgumentError, "Cannot create face #{name.inspect} with invalid version number '#{version}'!"
+    end
+
+    @name = Puppet::Interface::FaceCollection.underscorize(name)
+    @version = version
+    @default_format = :pson
+
+    instance_eval(&block) if block_given?
+  end
+
+  # Try to find actions defined in other files.
+  def load_actions
+    path = "puppet/faces/#{name}"
+
+    loaded = []
+    [path, "#{name}@#{version}/#{path}"].each do |path|
+      Puppet::Interface.autoloader.search_directories.each do |dir|
+        fdir = ::File.join(dir, path)
+        next unless FileTest.directory?(fdir)
+
+        Dir.chdir(fdir) do
+          Dir.glob("*.rb").each do |file|
+            aname = file.sub(/\.rb/, '')
+            if loaded.include?(aname)
+              Puppet.debug "Not loading duplicate action '#{aname}' for '#{name}' from '#{fdir}/#{file}'"
+              next
+            end
+            loaded << aname
+            Puppet.debug "Loading action '#{aname}' for '#{name}' from '#{fdir}/#{file}'"
+            require "#{Dir.pwd}/#{aname}"
+          end
+        end
+      end
+    end
+  end
+
+  def to_s
+    "Puppet::Faces[#{name.inspect}, #{version.inspect}]"
+  end
+end
diff --git a/lib/puppet/faces/action.rb b/lib/puppet/interface/action.rb
index 58d2c6003..e4a37a1f7 100644
--- a/lib/puppet/faces/action.rb
+++ b/lib/puppet/interface/action.rb
@@ -1,8 +1,8 @@
 # -*- coding: utf-8 -*-
-require 'puppet/faces'
-require 'puppet/faces/option'
+require 'puppet/interface'
+require 'puppet/interface/option'
 
-class Puppet::Faces::Action
+class Puppet::Interface::Action
   def initialize(face, name, attrs = {})
     raise "#{name.inspect} is an invalid action name" unless name.to_s =~ /^[a-z]\w*$/
     @face    = face
diff --git a/lib/puppet/faces/action_builder.rb b/lib/puppet/interface/action_builder.rb
index a67068926..b08c3d023 100644
--- a/lib/puppet/faces/action_builder.rb
+++ b/lib/puppet/interface/action_builder.rb
@@ -1,7 +1,7 @@
-require 'puppet/faces'
-require 'puppet/faces/action'
+require 'puppet/interface'
+require 'puppet/interface/action'
 
-class Puppet::Faces::ActionBuilder
+class Puppet::Interface::ActionBuilder
   attr_reader :action
 
   def self.build(face, name, &block)
@@ -12,7 +12,7 @@ class Puppet::Faces::ActionBuilder
   private
   def initialize(face, name, &block)
     @face   = face
-    @action = Puppet::Faces::Action.new(face, name)
+    @action = Puppet::Interface::Action.new(face, name)
     instance_eval(&block)
   end
 
@@ -25,7 +25,7 @@ class Puppet::Faces::ActionBuilder
   end
 
   def option(*declaration, &block)
-    option = Puppet::Faces::OptionBuilder.build(@action, *declaration, &block)
+    option = Puppet::Interface::OptionBuilder.build(@action, *declaration, &block)
     @action.add_option(option)
   end
 end
diff --git a/lib/puppet/faces/action_manager.rb b/lib/puppet/interface/action_manager.rb
index 6c0036bd8..bb0e5bf57 100644
--- a/lib/puppet/faces/action_manager.rb
+++ b/lib/puppet/interface/action_manager.rb
@@ -1,12 +1,12 @@
-require 'puppet/faces/action_builder'
+require 'puppet/interface/action_builder'
 
-module Puppet::Faces::ActionManager
+module Puppet::Interface::ActionManager
   # Declare that this app can take a specific action, and provide
   # the code to do so.
   def action(name, &block)
     @actions ||= {}
     raise "Action #{name} already defined for #{self}" if action?(name)
-    action = Puppet::Faces::ActionBuilder.build(self, name, &block)
+    action = Puppet::Interface::ActionBuilder.build(self, name, &block)
     @actions[action.name] = action
   end
 
@@ -15,7 +15,7 @@ module Puppet::Faces::ActionManager
   def script(name, &block)
     @actions ||= {}
     raise "Action #{name} already defined for #{self}" if action?(name)
-    @actions[name] = Puppet::Faces::Action.new(self, name, :when_invoked => block)
+    @actions[name] = Puppet::Interface::Action.new(self, name, :when_invoked => block)
   end
 
   def actions
diff --git a/lib/puppet/faces/face_collection.rb b/lib/puppet/interface/face_collection.rb
index e6ee709d6..9f7a499c2 100644
--- a/lib/puppet/faces/face_collection.rb
+++ b/lib/puppet/interface/face_collection.rb
@@ -1,7 +1,7 @@
 # -*- coding: utf-8 -*-
-require 'puppet/faces'
+require 'puppet/interface'
 
-module Puppet::Faces::FaceCollection
+module Puppet::Interface::FaceCollection
   SEMVER_VERSION = /^(\d+)\.(\d+)\.(\d+)([A-Za-z][0-9A-Za-z-]*|)$/
 
   @faces = Hash.new { |hash, key| hash[key] = {} }
diff --git a/lib/puppet/faces/option.rb b/lib/puppet/interface/option.rb
index 7d3ed37ca..ccc2fbba7 100644
--- a/lib/puppet/faces/option.rb
+++ b/lib/puppet/interface/option.rb
@@ -1,6 +1,6 @@
-require 'puppet/faces'
+require 'puppet/interface'
 
-class Puppet::Faces::Option
+class Puppet::Interface::Option
   attr_reader   :parent
   attr_reader   :name
   attr_reader   :aliases
diff --git a/lib/puppet/faces/option_builder.rb b/lib/puppet/interface/option_builder.rb
index 0b6667546..83a1906b0 100644
--- a/lib/puppet/faces/option_builder.rb
+++ b/lib/puppet/interface/option_builder.rb
@@ -1,6 +1,6 @@
-require 'puppet/faces/option'
+require 'puppet/interface/option'
 
-class Puppet::Faces::OptionBuilder
+class Puppet::Interface::OptionBuilder
   attr_reader :option
 
   def self.build(face, *declaration, &block)
@@ -10,13 +10,13 @@ class Puppet::Faces::OptionBuilder
   private
   def initialize(face, *declaration, &block)
     @face   = face
-    @option = Puppet::Faces::Option.new(face, *declaration)
+    @option = Puppet::Interface::Option.new(face, *declaration)
     block and instance_eval(&block)
     @option
   end
 
   # Metaprogram the simple DSL from the option class.
-  Puppet::Faces::Option.instance_methods.grep(/=$/).each do |setter|
+  Puppet::Interface::Option.instance_methods.grep(/=$/).each do |setter|
     next if setter =~ /^=/      # special case, darn it...
 
     dsl = setter.sub(/=$/, '')
diff --git a/lib/puppet/faces/option_manager.rb b/lib/puppet/interface/option_manager.rb
index 02a73afc3..56df9760f 100644
--- a/lib/puppet/faces/option_manager.rb
+++ b/lib/puppet/interface/option_manager.rb
@@ -1,10 +1,10 @@
-require 'puppet/faces/option_builder'
+require 'puppet/interface/option_builder'
 
-module Puppet::Faces::OptionManager
+module Puppet::Interface::OptionManager
   # Declare that this app can take a specific option, and provide
   # the code to do so.
   def option(*declaration, &block)
-    add_option Puppet::Faces::OptionBuilder.build(self, *declaration, &block)
+    add_option Puppet::Interface::OptionBuilder.build(self, *declaration, &block)
   end
 
   def add_option(option)
diff --git a/spec/unit/faces/catalog_spec.rb b/spec/unit/faces/catalog_spec.rb
index 7621a864a..71972194a 100755
--- a/spec/unit/faces/catalog_spec.rb
+++ b/spec/unit/faces/catalog_spec.rb
@@ -1,6 +1,3 @@
-#!/usr/bin/env ruby
-
-require File.expand_path(File.dirname(__FILE__) + '/../../spec_helper.rb')
-
 describe Puppet::Faces[:catalog, '0.0.1'] do
+  it "should actually have some testing..."
 end
diff --git a/spec/unit/faces/certificate_request_spec.rb b/spec/unit/faces/certificate_request_spec.rb
index 637ea8c38..1a71a8379 100755
--- a/spec/unit/faces/certificate_request_spec.rb
+++ b/spec/unit/faces/certificate_request_spec.rb
@@ -1,6 +1,3 @@
-#!/usr/bin/env ruby
-
-require File.expand_path(File.dirname(__FILE__) + '/../../spec_helper.rb')
-
 describe Puppet::Faces[:certificate_request, '0.0.1'] do
+  it "should actually have some tests..."
 end
diff --git a/spec/unit/faces/certificate_revocation_list_spec.rb b/spec/unit/faces/certificate_revocation_list_spec.rb
index e319b18e2..4f41edef6 100755
--- a/spec/unit/faces/certificate_revocation_list_spec.rb
+++ b/spec/unit/faces/certificate_revocation_list_spec.rb
@@ -1,6 +1,3 @@
-#!/usr/bin/env ruby
-
-require File.expand_path(File.dirname(__FILE__) + '/../../spec_helper.rb')
-
 describe Puppet::Faces[:certificate_revocation_list, '0.0.1'] do
+  it "should actually have some tests..."
 end
diff --git a/spec/unit/faces/file_spec.rb b/spec/unit/faces/file_spec.rb
index aafa88ce0..fcb52c67e 100755
--- a/spec/unit/faces/file_spec.rb
+++ b/spec/unit/faces/file_spec.rb
@@ -1,6 +1,3 @@
-#!/usr/bin/env ruby
-
-require File.expand_path(File.dirname(__FILE__) + '/../../spec_helper.rb')
-
 describe Puppet::Faces[:file, '0.0.1'] do
+  it "should actually have some tests..."
 end
diff --git a/spec/unit/faces/key_spec.rb b/spec/unit/faces/key_spec.rb
index 70d4a52c1..9b7a58706 100755
--- a/spec/unit/faces/key_spec.rb
+++ b/spec/unit/faces/key_spec.rb
@@ -1,6 +1,3 @@
-#!/usr/bin/env ruby
-
-require File.expand_path(File.dirname(__FILE__) + '/../../spec_helper.rb')
-
 describe Puppet::Faces[:key, '0.0.1'] do
+  it "should actually have some tests..."
 end
diff --git a/spec/unit/faces/option_builder_spec.rb b/spec/unit/faces/option_builder_spec.rb
deleted file mode 100644
index 9296ba7b6..000000000
--- a/spec/unit/faces/option_builder_spec.rb
+++ /dev/null
@@ -1,29 +0,0 @@
-require 'puppet/faces/option_builder'
-
-describe Puppet::Faces::OptionBuilder do
-  let :face do Puppet::Faces.new(:option_builder_testing, '0.0.1') end
-
-  it "should be able to construct an option without a block" do
-    Puppet::Faces::OptionBuilder.build(face, "--foo").
-      should be_an_instance_of Puppet::Faces::Option
-  end
-
-  describe "when using the DSL block" do
-    it "should work with an empty block" do
-      option = Puppet::Faces::OptionBuilder.build(face, "--foo") do
-        # This block deliberately left blank.
-      end
-
-      option.should be_an_instance_of Puppet::Faces::Option
-    end
-
-    it "should support documentation declarations" do
-      text = "this is the description"
-      option = Puppet::Faces::OptionBuilder.build(face, "--foo") do
-        desc text
-      end
-      option.should be_an_instance_of Puppet::Faces::Option
-      option.desc.should == text
-    end
-  end
-end
diff --git a/spec/unit/faces/report_spec.rb b/spec/unit/faces/report_spec.rb
index f7a67349c..30897d5e7 100755
--- a/spec/unit/faces/report_spec.rb
+++ b/spec/unit/faces/report_spec.rb
@@ -1,6 +1,3 @@
-#!/usr/bin/env ruby
-
-require File.expand_path(File.dirname(__FILE__) + '/../../spec_helper.rb')
-
 describe Puppet::Faces[:report, '0.0.1'] do
+  it "should actually have some tests..."
 end
diff --git a/spec/unit/faces/resource_spec.rb b/spec/unit/faces/resource_spec.rb
index 0b4b24882..e3f2e1c62 100755
--- a/spec/unit/faces/resource_spec.rb
+++ b/spec/unit/faces/resource_spec.rb
@@ -1,6 +1,3 @@
-#!/usr/bin/env ruby
-
-require File.expand_path(File.dirname(__FILE__) + '/../../spec_helper.rb')
-
 describe Puppet::Faces[:resource, '0.0.1'] do
+  it "should actually have some tests..."
 end
diff --git a/spec/unit/faces/resource_type_spec.rb b/spec/unit/faces/resource_type_spec.rb
index 157066f2d..fcbf07520 100755
--- a/spec/unit/faces/resource_type_spec.rb
+++ b/spec/unit/faces/resource_type_spec.rb
@@ -1,6 +1,3 @@
-#!/usr/bin/env ruby
-
-require File.expand_path(File.dirname(__FILE__) + '/../../spec_helper.rb')
-
 describe Puppet::Faces[:resource_type, '0.0.1'] do
+  it "should actually have some tests..."
 end
diff --git a/spec/unit/faces/action_builder_spec.rb b/spec/unit/interface/action_builder_spec.rb
index 5c8b98849..ae9cc83d4 100755
--- a/spec/unit/faces/action_builder_spec.rb
+++ b/spec/unit/interface/action_builder_spec.rb
@@ -1,20 +1,20 @@
 #!/usr/bin/env ruby
 
 require File.expand_path(File.dirname(__FILE__) + '/../../spec_helper.rb')
-require 'puppet/faces/action_builder'
+require 'puppet/interface/action_builder'
 
-describe Puppet::Faces::ActionBuilder do
+describe Puppet::Interface::ActionBuilder do
   describe "::build" do
     it "should build an action" do
-      action = Puppet::Faces::ActionBuilder.build(nil, :foo) do
+      action = Puppet::Interface::ActionBuilder.build(nil, :foo) do
       end
-      action.should be_a(Puppet::Faces::Action)
+      action.should be_a(Puppet::Interface::Action)
       action.name.should == :foo
     end
 
     it "should define a method on the face which invokes the action" do
-      face = Puppet::Faces.new(:action_builder_test_faces, '0.0.1')
-      action = Puppet::Faces::ActionBuilder.build(face, :foo) do
+      face = Puppet::Interface.new(:action_builder_test_interface, '0.0.1')
+      action = Puppet::Interface::ActionBuilder.build(face, :foo) do
         when_invoked do
           "invoked the method"
         end
@@ -24,30 +24,30 @@ describe Puppet::Faces::ActionBuilder do
     end
 
     it "should require a block" do
-      expect { Puppet::Faces::ActionBuilder.build(nil, :foo) }.
+      expect { Puppet::Interface::ActionBuilder.build(nil, :foo) }.
         should raise_error("Action :foo must specify a block")
     end
 
     describe "when handling options" do
-      let :face do Puppet::Faces.new(:option_handling, '0.0.1') end
+      let :face do Puppet::Interface.new(:option_handling, '0.0.1') end
 
       it "should have a #option DSL function" do
         method = nil
-        Puppet::Faces::ActionBuilder.build(face, :foo) do
+        Puppet::Interface::ActionBuilder.build(face, :foo) do
           method = self.method(:option)
         end
         method.should be
       end
 
       it "should define an option without a block" do
-        action = Puppet::Faces::ActionBuilder.build(face, :foo) do
+        action = Puppet::Interface::ActionBuilder.build(face, :foo) do
           option "--bar"
         end
         action.should be_option :bar
       end
 
       it "should accept an empty block" do
-        action = Puppet::Faces::ActionBuilder.build(face, :foo) do
+        action = Puppet::Interface::ActionBuilder.build(face, :foo) do
           option "--bar" do
             # This space left deliberately blank.
           end
diff --git a/spec/unit/faces/action_manager_spec.rb b/spec/unit/interface/action_manager_spec.rb
index 61d1c1df5..50bea5f89 100755
--- a/spec/unit/faces/action_manager_spec.rb
+++ b/spec/unit/interface/action_manager_spec.rb
@@ -2,14 +2,14 @@
 
 require File.expand_path(File.dirname(__FILE__) + '/../../spec_helper.rb')
 
-# This is entirely an internal class for Faces, so we have to load it instead of our class.
-require 'puppet/faces'
+# This is entirely an internal class for Interface, so we have to load it instead of our class.
+require 'puppet/interface'
 
 class ActionManagerTester
-  include Puppet::Faces::ActionManager
+  include Puppet::Interface::ActionManager
 end
 
-describe Puppet::Faces::ActionManager do
+describe Puppet::Interface::ActionManager do
   subject { ActionManagerTester.new }
 
   describe "when included in a class" do
@@ -73,7 +73,7 @@ describe Puppet::Faces::ActionManager do
   end
 
   describe "when used to extend a class" do
-    subject { Class.new.extend(Puppet::Faces::ActionManager) }
+    subject { Class.new.extend(Puppet::Interface::ActionManager) }
 
     it "should be able to define an action" do
       subject.action(:foo) do
@@ -102,8 +102,8 @@ describe Puppet::Faces::ActionManager do
   describe "when used both at the class and instance level" do
     before do
       @klass = Class.new do
-        include Puppet::Faces::ActionManager
-        extend Puppet::Faces::ActionManager
+        include Puppet::Interface::ActionManager
+        extend Puppet::Interface::ActionManager
       end
       @instance = @klass.new
     end
@@ -216,7 +216,7 @@ describe Puppet::Faces::ActionManager do
 
   describe "#get_action" do
     let :parent_class do
-      parent_class = Class.new(Puppet::Faces)
+      parent_class = Class.new(Puppet::Interface)
       parent_class.action(:foo) {}
       parent_class
     end
diff --git a/spec/unit/faces/action_spec.rb b/spec/unit/interface/action_spec.rb
index c087744b1..4801a3cc8 100755
--- a/spec/unit/faces/action_spec.rb
+++ b/spec/unit/interface/action_spec.rb
@@ -1,13 +1,13 @@
 #!/usr/bin/env ruby
 
 require File.expand_path(File.dirname(__FILE__) + '/../../spec_helper.rb')
-require 'puppet/faces/action'
+require 'puppet/interface/action'
 
-describe Puppet::Faces::Action do
+describe Puppet::Interface::Action do
   describe "when validating the action name" do
     [nil, '', 'foo bar', '-foobar'].each do |input|
       it "should treat #{input.inspect} as an invalid name" do
-        expect { Puppet::Faces::Action.new(nil, input) }.
+        expect { Puppet::Interface::Action.new(nil, input) }.
           should raise_error(/is an invalid action name/)
       end
     end
@@ -15,7 +15,7 @@ describe Puppet::Faces::Action do
 
   describe "when invoking" do
     it "should be able to call other actions on the same object" do
-      face = Puppet::Faces.new(:my_face, '0.0.1') do
+      face = Puppet::Interface.new(:my_face, '0.0.1') do
         action(:foo) do
           when_invoked { 25 }
         end
@@ -33,7 +33,7 @@ describe Puppet::Faces::Action do
     # baz is an instance action calling a class action
     # qux is an instance action calling an instance action
     it "should be able to call other actions on the same object when defined on a class" do
-      class Puppet::Faces::MyFacesBaseClass < Puppet::Faces
+      class Puppet::Interface::MyInterfaceBaseClass < Puppet::Interface
         action(:foo) do
           when_invoked { 25 }
         end
@@ -47,7 +47,7 @@ describe Puppet::Faces::Action do
         end
       end
 
-      face = Puppet::Faces::MyFacesBaseClass.new(:my_inherited_face, '0.0.1') do
+      face = Puppet::Interface::MyInterfaceBaseClass.new(:my_inherited_face, '0.0.1') do
         action(:baz) do
           when_invoked { "the value of foo in baz is '#{foo}'" }
         end
@@ -65,7 +65,7 @@ describe Puppet::Faces::Action do
 
     context "when calling the Ruby API" do
       let :face do
-        Puppet::Faces.new(:ruby_api, '1.0.0') do
+        Puppet::Interface.new(:ruby_api, '1.0.0') do
           action :bar do
             when_invoked do |options|
               options
@@ -88,7 +88,7 @@ describe Puppet::Faces::Action do
 
   describe "with action-level options" do
     it "should support options with an empty block" do
-      face = Puppet::Faces.new(:action_level_options, '0.0.1') do
+      face = Puppet::Interface.new(:action_level_options, '0.0.1') do
         action :foo do
           option "--bar" do
             # this line left deliberately blank
@@ -101,7 +101,7 @@ describe Puppet::Faces::Action do
     end
 
     it "should return only action level options when there are no face options" do
-      face = Puppet::Faces.new(:action_level_options, '0.0.1') do
+      face = Puppet::Interface.new(:action_level_options, '0.0.1') do
         action :foo do option "--bar" end
       end
 
@@ -110,7 +110,7 @@ describe Puppet::Faces::Action do
 
     describe "with both face and action options" do
       let :face do
-        Puppet::Faces.new(:action_level_options, '0.0.1') do
+        Puppet::Interface.new(:action_level_options, '0.0.1') do
           action :foo do option "--bar" end
           action :baz do option "--bim" end
           option "--quux"
@@ -122,7 +122,7 @@ describe Puppet::Faces::Action do
       end
 
       it "should fetch options that the face inherited" do
-        parent = Class.new(Puppet::Faces)
+        parent = Class.new(Puppet::Interface)
         parent.option "--foo"
         child = parent.new(:inherited_options, '0.0.1') do
           option "--bar"
@@ -133,18 +133,18 @@ describe Puppet::Faces::Action do
         action.should be
 
         [:baz, :bar, :foo].each do |name|
-          action.get_option(name).should be_an_instance_of Puppet::Faces::Option
+          action.get_option(name).should be_an_instance_of Puppet::Interface::Option
         end
       end
 
       it "should get an action option when asked" do
         face.get_action(:foo).get_option(:bar).
-          should be_an_instance_of Puppet::Faces::Option
+          should be_an_instance_of Puppet::Interface::Option
       end
 
       it "should get a face option when asked" do
         face.get_action(:foo).get_option(:quux).
-          should be_an_instance_of Puppet::Faces::Option
+          should be_an_instance_of Puppet::Interface::Option
       end
 
       it "should return options only for this action" do
@@ -154,7 +154,7 @@ describe Puppet::Faces::Action do
 
     it_should_behave_like "things that declare options" do
       def add_options_to(&block)
-        face = Puppet::Faces.new(:with_options, '0.0.1') do
+        face = Puppet::Interface.new(:with_options, '0.0.1') do
           action(:foo, &block)
         end
         face.get_action(:foo)
@@ -163,7 +163,7 @@ describe Puppet::Faces::Action do
 
     it "should fail when a face option duplicates an action option" do
       expect {
-        Puppet::Faces.new(:action_level_options, '0.0.1') do
+        Puppet::Interface.new(:action_level_options, '0.0.1') do
           option "--foo"
           action :bar do option "--foo" end
         end
diff --git a/spec/unit/faces/face_collection_spec.rb b/spec/unit/interface/face_collection_spec.rb
index 30147a548..de6d29cee 100755
--- a/spec/unit/faces/face_collection_spec.rb
+++ b/spec/unit/interface/face_collection_spec.rb
@@ -3,12 +3,12 @@
 require File.expand_path(File.dirname(__FILE__) + '/../../spec_helper.rb')
 require 'tmpdir'
 
-describe Puppet::Faces::FaceCollection do
+describe Puppet::Interface::FaceCollection do
   # To avoid cross-pollution we have to save and restore both the hash
-  # containing all the faces data, and the array used by require.  Restoring
+  # containing all the interface data, and the array used by require.  Restoring
   # both means that we don't leak side-effects across the code. --daniel 2011-04-06
   before :each do
-    @original_faces  = subject.instance_variable_get("@faces").dup
+    @original_faces    = subject.instance_variable_get("@faces").dup
     @original_required = $".dup
     subject.instance_variable_get("@faces").clear
   end
diff --git a/spec/unit/interface/option_builder_spec.rb b/spec/unit/interface/option_builder_spec.rb
new file mode 100644
index 000000000..fae48324e
--- /dev/null
+++ b/spec/unit/interface/option_builder_spec.rb
@@ -0,0 +1,29 @@
+require 'puppet/interface/option_builder'
+
+describe Puppet::Interface::OptionBuilder do
+  let :face do Puppet::Interface.new(:option_builder_testing, '0.0.1') end
+
+  it "should be able to construct an option without a block" do
+    Puppet::Interface::OptionBuilder.build(face, "--foo").
+      should be_an_instance_of Puppet::Interface::Option
+  end
+
+  describe "when using the DSL block" do
+    it "should work with an empty block" do
+      option = Puppet::Interface::OptionBuilder.build(face, "--foo") do
+        # This block deliberately left blank.
+      end
+
+      option.should be_an_instance_of Puppet::Interface::Option
+    end
+
+    it "should support documentation declarations" do
+      text = "this is the description"
+      option = Puppet::Interface::OptionBuilder.build(face, "--foo") do
+        desc text
+      end
+      option.should be_an_instance_of Puppet::Interface::Option
+      option.desc.should == text
+    end
+  end
+end
diff --git a/spec/unit/faces/option_spec.rb b/spec/unit/interface/option_spec.rb
index a28fef087..3bcd121e2 100644
--- a/spec/unit/faces/option_spec.rb
+++ b/spec/unit/interface/option_spec.rb
@@ -1,14 +1,14 @@
-require 'puppet/faces/option'
+require 'puppet/interface/option'
 
-describe Puppet::Faces::Option do
-  let :face do Puppet::Faces.new(:option_testing, '0.0.1') end
+describe Puppet::Interface::Option do
+  let :face do Puppet::Interface.new(:option_testing, '0.0.1') end
 
   describe "#optparse_to_name" do
     ["", "=BAR", " BAR", "=bar", " bar"].each do |postfix|
       { "--foo" => :foo, "-f" => :f }.each do |base, expect|
         input = base + postfix
         it "should map #{input.inspect} to #{expect.inspect}" do
-          option = Puppet::Faces::Option.new(face, input)
+          option = Puppet::Interface::Option.new(face, input)
           option.name.should == expect
         end
       end
@@ -16,58 +16,58 @@ describe Puppet::Faces::Option do
 
     [:foo, 12, nil, {}, []].each do |input|
       it "should fail sensible when given #{input.inspect}" do
-        expect { Puppet::Faces::Option.new(face, input) }.
+        expect { Puppet::Interface::Option.new(face, input) }.
           should raise_error ArgumentError, /is not valid for an option argument/
       end
     end
 
     ["-foo", "-foo=BAR", "-foo BAR"].each do |input|
       it "should fail with a single dash for long option #{input.inspect}" do
-        expect { Puppet::Faces::Option.new(face, input) }.
+        expect { Puppet::Interface::Option.new(face, input) }.
           should raise_error ArgumentError, /long options need two dashes \(--\)/
       end
     end
   end
 
   it "requires a face when created" do
-    expect { Puppet::Faces::Option.new }.
+    expect { Puppet::Interface::Option.new }.
       should raise_error ArgumentError, /wrong number of arguments/
   end
 
   it "also requires some declaration arguments when created" do
-    expect { Puppet::Faces::Option.new(face) }.
+    expect { Puppet::Interface::Option.new(face) }.
       should raise_error ArgumentError, /No option declarations found/
   end
 
   it "should infer the name from an optparse string" do
-    option = Puppet::Faces::Option.new(face, "--foo")
+    option = Puppet::Interface::Option.new(face, "--foo")
     option.name.should == :foo
   end
 
   it "should infer the name when multiple optparse string are given" do
-    option = Puppet::Faces::Option.new(face, "--foo", "-f")
+    option = Puppet::Interface::Option.new(face, "--foo", "-f")
     option.name.should == :foo
   end
 
   it "should prefer the first long option name over a short option name" do
-    option = Puppet::Faces::Option.new(face, "-f", "--foo")
+    option = Puppet::Interface::Option.new(face, "-f", "--foo")
     option.name.should == :foo
   end
 
   it "should create an instance when given a face and name" do
-    Puppet::Faces::Option.new(face, "--foo").
-      should be_instance_of Puppet::Faces::Option
+    Puppet::Interface::Option.new(face, "--foo").
+      should be_instance_of Puppet::Interface::Option
   end
 
   describe "#to_s" do
     it "should transform a symbol into a string" do
-      option = Puppet::Faces::Option.new(face, "--foo")
+      option = Puppet::Interface::Option.new(face, "--foo")
       option.name.should == :foo
       option.to_s.should == "foo"
     end
 
     it "should use - rather than _ to separate words in strings but not symbols" do
-      option = Puppet::Faces::Option.new(face, "--foo-bar")
+      option = Puppet::Interface::Option.new(face, "--foo-bar")
       option.name.should == :foo_bar
       option.to_s.should == "foo-bar"
     end
diff --git a/spec/unit/faces_spec.rb b/spec/unit/interface_spec.rb
index 586abd6b5..afcf95dcf 100755
--- a/spec/unit/faces_spec.rb
+++ b/spec/unit/interface_spec.rb
@@ -1,48 +1,49 @@
-#!/usr/bin/env ruby
+require 'puppet/faces'
+require 'puppet/interface'
 
-require File.expand_path(File.dirname(__FILE__) + '/../spec_helper.rb')
+describe Puppet::Interface do
+  subject { Puppet::Interface }
 
-describe Puppet::Faces do
   before :all do
-    @faces = Puppet::Faces::FaceCollection.instance_variable_get("@faces").dup
+    @faces = Puppet::Interface::FaceCollection.instance_variable_get("@faces").dup
   end
 
   before :each do
-    Puppet::Faces::FaceCollection.instance_variable_get("@faces").clear
+    Puppet::Interface::FaceCollection.instance_variable_get("@faces").clear
   end
 
   after :all do
-    Puppet::Faces::FaceCollection.instance_variable_set("@faces", @faces)
+    Puppet::Interface::FaceCollection.instance_variable_set("@faces", @faces)
   end
 
   describe "#define" do
     it "should register the face" do
-      face = Puppet::Faces.define(:face_test_register, '0.0.1')
-      face.should == Puppet::Faces[:face_test_register, '0.0.1']
+      face = subject.define(:face_test_register, '0.0.1')
+      face.should == subject[:face_test_register, '0.0.1']
     end
 
     it "should load actions" do
-      Puppet::Faces.any_instance.expects(:load_actions)
-      Puppet::Faces.define(:face_test_load_actions, '0.0.1')
+      subject.any_instance.expects(:load_actions)
+      subject.define(:face_test_load_actions, '0.0.1')
     end
 
     it "should require a version number" do
-      expect { Puppet::Faces.define(:no_version) }.should raise_error ArgumentError
+      expect { subject.define(:no_version) }.should raise_error ArgumentError
     end
   end
 
   describe "#initialize" do
     it "should require a version number" do
-      expect { Puppet::Faces.new(:no_version) }.should raise_error ArgumentError
+      expect { subject.new(:no_version) }.should raise_error ArgumentError
     end
 
     it "should require a valid version number" do
-      expect { Puppet::Faces.new(:bad_version, 'Rasins') }.
+      expect { subject.new(:bad_version, 'Rasins') }.
         should raise_error ArgumentError
     end
 
     it "should instance-eval any provided block" do
-      face = Puppet::Faces.new(:face_test_block, '0.0.1') do
+      face = subject.new(:face_test_block, '0.0.1') do
         action(:something) do
           when_invoked { "foo" }
         end
@@ -53,31 +54,31 @@ describe Puppet::Faces do
   end
 
   it "should have a name" do
-    Puppet::Faces.new(:me, '0.0.1').name.should == :me
+    subject.new(:me, '0.0.1').name.should == :me
   end
 
   it "should stringify with its own name" do
-    Puppet::Faces.new(:me, '0.0.1').to_s.should =~ /\bme\b/
+    subject.new(:me, '0.0.1').to_s.should =~ /\bme\b/
   end
 
   it "should allow overriding of the default format" do
-    face = Puppet::Faces.new(:me, '0.0.1')
+    face = subject.new(:me, '0.0.1')
     face.set_default_format :foo
     face.default_format.should == :foo
   end
 
   it "should default to :pson for its format" do
-    Puppet::Faces.new(:me, '0.0.1').default_format.should == :pson
+    subject.new(:me, '0.0.1').default_format.should == :pson
   end
 
   # Why?
   it "should create a class-level autoloader" do
-    Puppet::Faces.autoloader.should be_instance_of(Puppet::Util::Autoload)
+    subject.autoloader.should be_instance_of(Puppet::Util::Autoload)
   end
 
   it "should try to require faces that are not known" do
-    Puppet::Faces::FaceCollection.expects(:require).with "puppet/faces/foo"
-    Puppet::Faces[:foo, '0.0.1']
+    subject::FaceCollection.expects(:require).with "puppet/faces/foo"
+    subject[:foo, '0.0.1']
   end
 
   it "should be able to load all actions in all search paths"
@@ -85,13 +86,13 @@ describe Puppet::Faces do
 
   it_should_behave_like "things that declare options" do
     def add_options_to(&block)
-      Puppet::Faces.new(:with_options, '0.0.1', &block)
+      subject.new(:with_options, '0.0.1', &block)
     end
   end
 
   describe "with face-level options" do
     it "should not return any action-level options" do
-      face = Puppet::Faces.new(:with_options, '0.0.1') do
+      face = subject.new(:with_options, '0.0.1') do
         option "--foo"
         option "--bar"
         action :baz do
@@ -103,7 +104,7 @@ describe Puppet::Faces do
 
     it "should fail when a face option duplicates an action option" do
       expect {
-        Puppet::Faces.new(:action_level_options, '0.0.1') do
+        subject.new(:action_level_options, '0.0.1') do
           action :bar do option "--foo" end
           option "--foo"
         end
@@ -111,7 +112,7 @@ describe Puppet::Faces do
     end
 
     it "should work when two actions have the same option" do
-      face = Puppet::Faces.new(:with_options, '0.0.1') do
+      face = subject.new(:with_options, '0.0.1') do
         action :foo do option "--quux" end
         action :bar do option "--quux" end
       end
@@ -123,7 +124,7 @@ describe Puppet::Faces do
 
   describe "with inherited options" do
     let :face do
-      parent = Class.new(Puppet::Faces)
+      parent = Class.new(subject)
       parent.option("--inherited")
       face = parent.new(:example, '0.2.1')
       face.option("--local")
@@ -138,7 +139,7 @@ describe Puppet::Faces do
 
     describe "#get_option" do
       it "should return an inherited option object" do
-        face.get_option(:inherited).should be_an_instance_of Puppet::Faces::Option
+        face.get_option(:inherited).should be_an_instance_of subject::Option
       end
     end
   end