Add cops for resource / property descriptions

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,53 @@
+#
+# Copyright:: Copyright 2020, 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
+        # Resource 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
+          extend TargetChefVersion
+
+          minimum_target_chef_version '13.9'
+
+          MSG = 'Resource properties should include description fields to allow automated documention. Requires Chef Infra Client 13.9 or later.'.freeze
+
+          # any method named property being called with a symbol argument and anything else
+          def_node_matcher :property?, '(send nil? :property (sym _) ...)'
+
+          # hash that contains description in any order (that's the <> bit)
+          def_node_search :description_hash, '(hash <(pair (sym :description) ...) ...>)'
+
+          def on_send(node)
+            property?(node) do
+              add_offense(node, location: :expression, message: MSG, severity: :refactor) unless description_hash(processed_source.ast).any?
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,51 @@
+#
+# Copyright:: Copyright 2020, 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
+          extend TargetChefVersion
+
+          minimum_target_chef_version '13.9'
+
+          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

spec/rubocop/cop/chef/sharing/include_property_descriptions_spec.rb

@@ -0,0 +1,49 @@
+#
+# Copyright:: 2020, 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.
+#
+
+require 'spec_helper'
+
+describe RuboCop::Cop::Chef::ChefSharing::IncludePropertyDescriptions, :config do
+  subject(:cop) { described_class.new(config) }
+
+  it 'registers an offense when a property does not include a description' do
+    expect_offense(<<~RUBY)
+    property :foo, String, name_property: true
+    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Resource properties should include description fields to allow automated documention. Requires Chef Infra Client 13.9 or later.
+    RUBY
+  end
+
+  it 'registers an offense when a property does not include a description or any other hash items' do
+    expect_offense(<<~RUBY)
+    property :foo, String
+    ^^^^^^^^^^^^^^^^^^^^^ Resource properties should include description fields to allow automated documention. Requires Chef Infra Client 13.9 or later.
+    RUBY
+  end
+
+  it "doesn't register an offense when a property contains a description" do
+    expect_no_offenses(<<~RUBY)
+      resource_name 'foo'
+      description 'foo does a thing'
+    RUBY
+  end
+
+  it "doesn't register an offense when an attribute doesn't contain a description" do
+    expect_no_offenses(<<~RUBY)
+      attribute :foo, String
+    RUBY
+  end
+end

spec/rubocop/cop/chef/sharing/include_resource_descriptions_spec.rb

@@ -0,0 +1,36 @@
+#
+# Copyright:: 2020, 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.
+#
+
+require 'spec_helper'
+
+describe RuboCop::Cop::Chef::ChefSharing::IncludeResourceDescriptions, :config do
+  subject(:cop) { described_class.new(config) }
+
+  it 'registers an offense when a resource does not include a description' do
+    expect_offense(<<~RUBY)
+    resource_name 'foo'
+    ^ Resources should include description fields to allow automated documention. Requires Chef Infra Client 13.9 or later.
+    RUBY
+  end
+
+  it "doesn't register an offense when a resource contains a description" do
+    expect_no_offenses(<<~RUBY)
+      resource_name 'foo'
+      description 'foo does a thing'
+    RUBY
+  end
+end