Add cops for resource / property descriptions

These are off by default, but allow us to enforce descriptions in our repos.

Signed-off-by: Tim Smith <tsmith@chef.io>

config/cookstyle.yml

@@ -386,6 +386,21 @@ ChefSharing/EmptyMetadataField:
   Include:
     - '**/metadata.rb'
 
+ChefSharing/IncludePropertyDescriptions:
+  Description: Properties should include description fields to allow automated documention. Requires Chef Infra Client 13.9 or later.
+  Enabled: false
+  VersionAdded: '6.1.0'
+  Include:
+    - '**/libraries/*.rb'
+    - '**/resources/*.rb'
+
+ChefSharing/IncludeResourceDescriptions:
+  Description: Resources should include description fields to allow automated documention. Requires Chef Infra Client 13.9 or later.
+  Enabled: false
+  VersionAdded: '6.1.0'
+  Include:
+    - '**/resources/*.rb'
+
 ###############################
 # ChefDeprecations: Resolving Deprecations that block upgrading Chef Infra Client
 ###############################

lib/rubocop/cop/chef/sharing/include_property_descriptions.rb

@@ -0,0 +1,47 @@
+#
+# Copyright:: Copyright 2019, Chef Software Inc.
+# Author:: Tim Smith (<tsmith@chef.io>)
+#
+# 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.
+#
+module RuboCop
+  module Cop
+    module Chef
+      module ChefSharing
+        # Resources properties should include description fields to allow automated documention. Requires Chef Infra Client 13.9 or later.
+        #
+        # @example
+        #
+        #   # bad
+        #   property :foo, String
+        #
+        #   # good
+        #   property :foo, String, description: "Set the important thing to..."
+        #
+        class IncludePropertyDescriptions < Cop
+          MSG = 'Resources should include description fields to allow automated documention. Requires Chef Infra Client 13.9 or later.'.freeze
+
+          def_node_matcher :property?, <<-PATTERN
+            (send nil? :property (sym _) ... $(hash ...))
+          PATTERN
+
+          def on_send(node)
+            property?(node) do |hash_items|
+              add_offense(node, location: :expression, message: MSG, severity: :refactor) unless hash_items.keys.include?(s(:sym, :description))
+            end
+          end
+        end
+      end
+    end
+  end
+end

lib/rubocop/cop/chef/sharing/include_resource_descriptions.rb

@@ -0,0 +1,48 @@
+#
+# Copyright:: Copyright 2019, Chef Software Inc.
+# Author:: Tim Smith (<tsmith@chef.io>)
+#
+# 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.
+#
+module RuboCop
+  module Cop
+    module Chef
+      module ChefSharing
+        # Resources should include description fields to allow automated documention. Requires Chef Infra Client 13.9 or later.
+        #
+        # @example
+        #
+        #   # good
+        #   resource_name :foo
+        #   description "The foo resource is used to do..."
+        #
+        class IncludeResourceDescriptions < Cop
+          include RangeHelp
+
+          MSG = 'Resources should include description fields to allow automated documention. Requires Chef Infra Client 13.9 or later.'.freeze
+
+          def investigate(processed_source)
+            return if processed_source.blank?
+
+            # Using range similar to RuboCop::Cop::Naming::Filename (file_name.rb)
+            range = source_range(processed_source.buffer, 1, 0)
+
+            add_offense(nil, location: range, message: MSG, severity: :refactor) unless resource_description(processed_source.ast).any?
+          end
+
+          def_node_search :resource_description, '(send nil? :description str ...)'
+        end
+      end
+    end
+  end
+end