puppet-lint-wmf_styleguide-check 1.0.0

data/README.md

@@ -0,0 +1,41 @@
+# puppet-lint-wmf_styleguide check
+Puppet-lint plugin to check for violations of the WMF puppet coding style guide.
+
+There are quite a few prescriptions for how to write puppet manifests in the
+puppet coding page at https://wikitech.wikimedia.org/wiki/Puppet_coding.
+
+While most of the coding style requirements are already covered by puppet-lint,
+quite a few of them are not, specifically our own flavour of the role/profile
+pattern.
+
+This plugin checks those specific violations, so we have specific checks for
+classes, roles, profiles and defined types. Let's see which in order.
+
+For classes in modules, we check that:
+* no hiera() call is made
+* no class inclusion or declaration happens across modules
+* no system::role call is made
+
+For roles, we check that:
+* no hiera() call is made
+* no class is included that is not a profile
+* no class is explicitly declared [TODO]
+* one and only one system::role call is made
+
+For profiles, our checks are:
+* Every parameter has an explicit hiera() call
+* No hiera() call is made outside of parameters
+* No classes are included that are not globals or profiles
+* No system::role declaration
+
+For defined types, we check that:
+* no hiera() call is made
+* no class from other modules is either included or declared (except for defined
+  types in the profile module, which can declare classes from other modules).
+
+While some of the rules are not enforced right now (so we don't check for
+defines from other modules), that can be refined in the future.
+
+This plugin will output a ton of errors when ran on the operations/puppet
+repository as it stands now, and that's good as it gives us a good measure of
+where we are in the transition, and will help enforce the style guide afterwards.

data/lib/puppet-lint/plugins/check_wmf_styleguide.rb

@@ -0,0 +1,436 @@
+# Class to manage puppet resources.
+class PuppetResource
+  attr_accessor :profile_module, :role_module
+
+  def initialize(resource_hash)
+    # Input should be a resource coming from
+    # the resource index
+    @resource = resource_hash
+    @params = parse_params
+  end
+
+  def type
+    if class?
+      'class'
+    else
+      'defined type'
+    end
+  end
+
+  # rubocop:disable Metrics/CyclomaticComplexity, Metrics/MethodLength
+  def parse_params
+    # Parse parameters and return a hash containing
+    # the parameter name as a key and a hash of tokens as value:
+    #  :param => the parameter token
+    #  :value => All the code tokens that represent the value of the parameter
+    res = {}
+    current_param = nil
+    in_value = false
+    return res unless @resource[:param_tokens]
+    @resource[:param_tokens].each do |token|
+      case token.type
+      when :VARIABLE
+        current_param = token.value
+        res[current_param] ||= { param: token, value: [] }
+      when :COMMA
+        current_param = nil
+        in_value = false
+      when :EQUALS
+        in_value = true
+      when *PuppetLint::Lexer::FORMATTING_TOKENS
+        # Skip non-code tokens
+        next
+      else
+        res[current_param][:value] << token if in_value && token
+      end
+    end
+    res
+  end
+  # rubocop:enable Metrics/CyclomaticComplexity, Metrics/MethodLength
+
+  def params
+    @params || parse_params
+  end
+
+  def profile_module
+    @profile_module || 'profile'
+  end
+
+  def role_module
+    @role_module || 'role'
+  end
+
+  def class?
+    @resource[:type] == :CLASS
+  end
+
+  def name
+    @resource[:name_token].value.gsub(/^::/, '')
+  end
+
+  def path
+    @resource[:path]
+  end
+
+  def filename
+    puts @resource
+    @resource[:filename]
+  end
+
+  def module_name
+    name.split('::')[0]
+  end
+
+  def profile?
+    class? && (module_name == profile_module)
+  end
+
+  def role?
+    class? && (module_name == role_module)
+  end
+
+  def hiera_calls
+    @resource[:tokens].select(&:hiera?)
+  end
+
+  def included_classes
+    @resource[:tokens].map(&:included_class).compact
+  end
+
+  def declared_classes
+    @resource[:tokens].map(&:declared_class).compact
+  end
+
+  def declared_resources
+    @resource[:tokens].select(&:declared_type?)
+  end
+
+  def resource?(name)
+    @resource[:tokens].select { |t| t.declared_type? && t.value.gsub(/^::/, '') == name }
+  end
+end
+
+class PuppetLint
+  class Lexer
+    # Add some utility functions to the PuppetLint::Lexer::Token class
+    class Token
+      # Extend the basic token with utility functions
+      def function?
+        @type == :NAME && @next_code_token.type == :LPAREN
+      end
+
+      def hiera?
+        function? && @value == 'hiera'
+      end
+
+      def class_include?
+        @type == :NAME && ['include', 'require'].include?(@value) && @next_code_token.type != :FARROW
+      end
+
+      def included_class
+        return unless class_include?
+        return @next_code_token.next_code_token if @next_code_token.type == :LPAREN
+        @next_code_token
+      end
+
+      def declared_class
+        return unless @type == :CLASS
+        # In a class declaration, the first token is the class declaration itself.
+        return if @next_code_token.type != :LBRACE
+        @next_code_token.next_code_token
+      end
+
+      def declared_type?
+        @type == :NAME && @next_code_token.type == :LBRACE && @prev_code_token.type != :CLASS
+      end
+
+      def node_def?
+        [:SSTRING, :STRING, :NAME, :REGEX].include?(@type)
+      end
+
+      def role_keyword?
+        @type == :NAME && @value = 'role' && @next_code_token.type == :LPAREN
+      end
+    end
+  end
+end
+
+# Checks and functions
+def check_profile(klass)
+  # All parameters of profiles should have a default value that is a hiera lookup
+  params_without_hiera_defaults klass
+  # All hiera lookups should be in parameters
+  hiera_not_in_params klass
+  # Only a few selected classes should be included in a profile
+  profile_illegal_include klass
+  # System::role only goes in roles
+  check_no_system_role klass
+end
+
+def check_role(klass)
+  # Hiera lookups within a role are forbidden
+  hiera klass
+  # A role should only include profiles
+  include_not_profile klass
+  # A call, and only one, to system::role will be done
+  check_system_role klass
+  # No defines should be present in a role
+  check_no_defines klass
+end
+
+def check_class(klass)
+  # No hiera lookups allowed in a class.
+  hiera klass
+  # Cannot include or declare classes from other modules
+  class_illegal_include klass
+  illegal_class_declaration klass
+  # System::role only goes in roles
+  check_no_system_role klass
+end
+
+def check_define(define)
+  # No hiera calls are admitted in defines. ever.
+  hiera define
+  # No class can be included in defines, like in classes
+  class_illegal_include define
+  # Non-profile defines should respect the rules for classes
+  illegal_class_declaration define unless define.module_name == 'profile'
+end
+
+def hiera(klass)
+  hiera_errors(klass.hiera_calls, klass)
+end
+
+def params_without_hiera_defaults(klass)
+  # Finds parameters that have no hiera-defined default value.
+  klass.params.each do |name, data|
+    next unless data[:value].select(&:hiera?).empty?
+    token = data[:param]
+    msg = {
+      message: "wmf-style: Parameter '#{name}' of class '#{klass.name}' has no call to hiera",
+      line: token.line,
+      column: token.column
+    }
+    notify :error, msg
+  end
+end
+
+def hiera_not_in_params(klass)
+  tokens = klass.hiera_calls.reject do |token|
+    maybe_param = token.prev_code_token.prev_code_token
+    klass.params.keys.include?(maybe_param.value)
+  end
+  hiera_errors(tokens, klass)
+end
+
+def hiera_errors(tokens, klass)
+  tokens.each do |token|
+    value = token.next_code_token.next_code_token.value
+    msg = {
+      message: "wmf-style: Found hiera call in #{klass.type} '#{klass.name}' for '#{value}'",
+      line: token.line,
+      column: token.column
+    }
+    notify :error, msg
+  end
+end
+
+def profile_illegal_include(klass)
+  modules_include_ok = ['profile', 'passwords']
+  classes_include_ok = ['lvs::configuration', 'network::constants']
+  klass.included_classes.each do |token|
+    class_name = token.value.gsub(/^::/, '')
+    next if classes_include_ok.include? class_name
+    module_name = class_name.split('::')[0]
+    next if modules_include_ok.include? module_name
+    msg = {
+      message: "wmf-style: profile '#{klass.name}' includes non-profile class #{class_name}",
+      line: token.line,
+      column: token.column
+    }
+    notify :error, msg
+  end
+end
+
+def class_illegal_include(klass)
+  modules_include_ok = [klass.module_name]
+  klass.included_classes.each do |token|
+    class_name = token.value.gsub(/^::/, '')
+    module_name = class_name.split('::')[0]
+    next if modules_include_ok.include? module_name
+    msg = {
+      message: "wmf-style: #{klass.type} '#{klass.name}' includes #{class_name} from another module",
+      line: token.line,
+      column: token.column
+    }
+    notify :error, msg
+  end
+end
+
+def include_not_profile(klass)
+  modules_include_ok = ['role', 'profile', 'standard']
+  klass.included_classes.each do |token|
+    class_name = token.value.gsub(/^::/, '')
+    module_name = class_name.split('::')[0]
+    next if modules_include_ok.include? module_name
+    msg = {
+      message: "wmf-style: role '#{klass.name}' includes #{class_name} which is neither a role nor a profile",
+      line: token.line,
+      column: token.column
+    }
+    notify :error, msg
+  end
+end
+
+def illegal_class_declaration(klass)
+  # Classes and defines should NEVER declare
+  # classes from other modules.
+  # If a class has multiple such occurrences, it should be a profile
+  klass.declared_classes.each do |token|
+    class_name = token.value.gsub(/^::/, '')
+    module_name = class_name.split('::')[0]
+    next if klass.module_name == module_name
+    msg = {
+      message: "wmf-style: #{klass.type} '#{klass.name}' declares class #{class_name} from another module",
+      line: token.line,
+      column: token.column
+    }
+    notify :error, msg
+  end
+end
+
+def check_no_system_role(klass)
+  # The system::role define should only be used in roles
+  klass.resource?('system::role').each do |token|
+    msg = {
+      message: "wmf-style: #{klass.type} '#{klass.name}' declares system::role, which should only be used in roles",
+      line: token.line,
+      column: token.column
+    }
+    notify :error, msg
+  end
+end
+
+def check_system_role(klass)
+  return if klass.resource?('system::role').length == 1
+  msg = {
+    message: "wmf-style: role '#{klass.name}' should declare system::role once",
+    line: 1,
+    column: 1
+  }
+  notify :error, msg
+end
+
+def check_no_defines(klass)
+  return if klass.declared_resources == klass.resource?('system::role')
+  msg = {
+    message: "wmf-style: role '#{klass.name}' should not include defines",
+    line: 1,
+    column: 1
+  }
+  notify :error, msg
+end
+
+# rubocop:disable Metrics/MethodLength, Metrics/PerceivedComplexity, Metrics/AbcSize, Metrics/CyclomaticComplexity
+def check_node(node)
+  title = node[:title_tokens].map(&:value).join(', ')
+  node[:tokens].each do |token|
+    msg = nil
+    if token.hiera?
+      msg = {
+        message: "wmf-style: Found hiera call in node '#{title}'",
+        line: token.line,
+        column: token.column
+      }
+
+    elsif token.class_include?
+      msg = {
+        message: "wmf-style: node '#{title}' includes class #{token.included_class.value}",
+        line: token.line,
+        column: token.column
+      }
+    elsif token.declared_class
+      msg = {
+        message: "wmf-style: node '#{title}' declares class #{token.declared_class.value}",
+        line: token.line,
+        column: token.column
+      }
+    elsif token.declared_type?
+      msg = {
+        message: "wmf-style: node '#{title}' declares #{token.value}",
+        line: token.line,
+        column: token.column
+      }
+    elsif token.role_keyword? && token.next_code_token.next_code_token.next_code_token.type != :RPAREN
+      msg = {
+        message: "wmf-style: node '#{title}' includes multiple roles",
+        line: token.line,
+        column: token.column
+      }
+    end
+    notify :error, msg if msg
+  end
+end
+
+PuppetLint.new_check(:wmf_styleguide) do
+  def node_indexes
+    # Override the faulty "node_indexes" method from puppet-lint
+    result = []
+    in_node_def = false
+    braces_level = nil
+    start = 0
+    title_tokens = []
+    tokens.each_with_index do |token, i|
+      if token.type == :NODE
+        braces_level = 0
+        start = i
+        in_node_def = true
+        next
+      end
+      # If we're not within a node definition, skip this token
+      next unless in_node_def
+      case token.type
+      when :LBRACE
+        title_tokens = tokens[start + 1..(i - 1)].select(&:node_def?) if braces_level.zero?
+        braces_level += 1
+      when :RBRACE
+        braces_level -= 1
+        if braces_level.zero?
+          result << {
+            start: start,
+            end: i,
+            tokens: tokens[start..i],
+            title_tokens: title_tokens
+          }
+          in_node_def = false
+        end
+      end
+    end
+    result
+  end
+  # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PercievedComplexity
+
+  def check_classes
+    class_indexes.each do |cl|
+      klass = PuppetResource.new(cl)
+      if klass.profile?
+        check_profile klass
+      elsif klass.role?
+        check_role klass
+      else
+        check_class klass
+      end
+    end
+  end
+
+  def check
+    check_classes
+    defined_type_indexes.each do |df|
+      define = PuppetResource.new(df)
+      check_define define
+    end
+    node_indexes.each do |node|
+      check_node node
+    end
+  end
+end