Maint: Fix borked help/man output for node clean

This action's help was busted:

* You can't put bulleted lists in the description string of an action. It blows
  up the man page formatting.
* Description must begin with a description of the action, not a continuation of
  the summary; otherwise it makes the output of 'puppet help cmd action' useless.
* The description of how unexport works wasn't sufficiently clear.
(#15920) Make forward-sexp ignore comments in puppet-mode.el

Enables parse-sexp-ignore-comments.

Previously forward-sexp was broken by comments with unterminated
strings. E.g. with the following manifest:
  foo {
    # won'
  }
forward-sexp on the opening brace would get:
  forward-sexp: Scan error: “Unbalanced parentheses”

The problem got introduced in commit
1c02749e8b54616043f728ed18ddec1dc4353a2d (Committed patch from #1160).
(#15739) Bump report_version since #10064 change its format

With #10064, we changed the report format to include the
environment. However that patch did not bump the report_version
and it should have.  This retroactively bumps the version
without changing the format, which might be bad too, but it'd
be worse to change it again...
Merge branch 'backport-15739_report_format_version' into 2.7.x

* backport-15739_report_format_version:
  (#15739) Bump report_version since #10064 change its format
(Maint) Enable colorized rspec output on Windows

Commit `83cfe9d` added colorized rspec output by default. Unfortunately,
this doesn't work on Windows and causes ANSI escape characters to be
printed to stdout.

Although we load the `win32console` gem while requiring puppet, rspec
always writes to `$stdout` and `$stderr` that it was started with. So
later when the `win32console` gem overwrites those streams, the formatters
have already been created with the old ones.

This commit modifies the spec helper to reset the stdout and stderr
streams on the configuration object, as well as each of the formatters.
Unfortunately, the formatter does not expose an accessor for its output
variable. I tested with 2.9 and 2.11, and both work as expected, i.e.
color on Windows.

This commit doesn't change behavior on non-Windows platforms.
Merge pull request #1081 from joshcooper/maint/2.7.x/rspec-color

(Maint) Enable colorized rspec output on Windows
Merge pull request #1020 from gleb/ticket/2.7.x/15920_fix_sexp_ignore_comments_in_puppel_el

(#15920) Make forward-sexp ignore comments in puppet-mode.el
maint: remove .rspec entirely

There isn't much good reason to force a set of rspec options on everyone,
especially because these override any user configuration.

If you really want to configure the way rspec works, modify ~/.rspec instead.

Signed-off-by: Daniel Pittman <daniel@puppetlabs.com>
Merge pull request #1083 from daniel-pittman/maint/2.7.x/no-dot-rspec

maint: remove .rspec entirely
Merge pull request #944 from nfagerlund/maint/2.7.x/node_clean_help

Maint: Fix borked help/man output for node clean
Whitespace only cleanup
(Maint) Stop watchr from reading non-existent spec.opts

Without this patch the watchr auto-testing script attempts to read the
spec.opts file.  This is a problem because the file no longer exists in
the repository which causes watchr to fatally error out.

This patch fixes the problem by simply removing the code replacing it
with a comment to use a personal ~/.rspec file instead of the project
rspec options file.
(#15193) Document how to use the static compiler

Without this patch the magic nature of the `Filebucket[puppet]` resource
and the expected behavior of the puppet agent obtaining file content
from the server is not documented anywhere.  This is a problem because
it is not clear how to configure the agent in a manner that does not
produce errors when using the static compiler.

This patch fixes the problem by providing a more in-depth description of
the high-level approach the static compiler takes.  In addition, the
specific configuration of `fileserver { puppet: server => $server, path
=> false }` is documented in the README_DEVELOPER.
Document the different forms of catalogs to help test writers

Without this patch it was not clear to me that the static compiler
operates primarily on a resource catalog.

This was a problem because I spent considerable amounts of time trying
to figure out the difference between `resource[:source]` returning
`"puppet:///..."` inside of
`Puppet::Resource::Catalog::StaticCompiler#find` when running `puppet
apply` and `resource[:source]` returning `["puppet:///..."]` (an array)
when inside of `#find` from the spec test.

When testing catalog terminii the resource form of the catalog should be
created instead of the RAL form.

This patch addresses the problem by providing a description of the
difference between a resource catalog and a RAL catalog and when it is
appropriate to use each.
(#15193) Add spec test coverage for static compiler

Without this patch there is no test coverage for the static compiler
terminus.  This is a problem because internal changes to the indirector
break the expected behavior of the static compiler and we have no
automated way to discover the broken behavior.

This patch adds spec test coverage for the static compiler's find
method.  This covers the most common use case of the static compiler
where by file resources with source parameters are modified in the
resource catalog.

The patch does not include test coverage for recursive file resources.

The approach taken stubs the underlying compiler terminus and produces a
fake resource catalog for the static compiler to operate on.  The
fileserver metadata API is also mocked to break the dependency on a real
fileserver.
(#15193) Fix StaticCompiler#store_content

Without this patch the static compiler's store_content method improperly
calls the indirector in a way that produces fatal exceptions preventing
catalog compilation.

These errors take the form of:

    NoMethodError: undefined method `find' for
    Puppet::FileServing::Content:Class

This patch fixes the problem by sending the messages to the right
places for Puppet 2.7.x and Puppet 3.x
Merge branch 'bug/2.7.x/15193_fix_static_compiler' into 2.7.x

* bug/2.7.x/15193_fix_static_compiler:
  (#15193) Fix StaticCompiler#store_content
  (#15193) Add spec test coverage for static compiler
  Document the different forms of catalogs to help test writers
  (#15193) Document how to use the static compiler
  (Maint) Stop watchr from reading non-existent spec.opts
  Whitespace only cleanup
Merge branch '2.7.x' into 3.x

* 2.7.x:
  (#15193) Fix StaticCompiler#store_content
  (#15193) Add spec test coverage for static compiler
  Document the different forms of catalogs to help test writers
  (#15193) Document how to use the static compiler
  (Maint) Stop watchr from reading non-existent spec.opts
  Whitespace only cleanup
  maint: remove .rspec entirely
  (Maint) Enable colorized rspec output on Windows
  (#15739) Bump report_version since #10064 change its format
  (#15920) Make forward-sexp ignore comments in puppet-mode.el
  Maint: Fix borked help/man output for node clean

Conflicts:
	lib/puppet/indirector/catalog/static_compiler.rb

This merge-up modifies the nature of the stub on

    Puppet::FileServing::Metadata.
      indirection.stubs(:find).
      with() { |*args| args[0] == options[:source].sub('puppet:///','') }.
      returns(fake_fileserver_metadata)

To get the tests passing with 3.x the stub is relaxed by the patch to
ignore the options hash passed along with the URI.