puppetlabs-onceover-codequality 1.2.1

data/README.md

@@ -0,0 +1,150 @@
+# PuppetlabsOnceover::CodeQuality
+
+This is the Code Quality plugin for [puppetlabs-onceover](https://github.com/puppetlabs/puppetlabs-onceover), _The gateway drug to automated infrastructure testing with Puppet_
+
+## What does it do?
+
+The plugin checks your control repository for:
+
+* Linting
+* Syntax
+
+And then generates documentation using [Puppet Strings](https://github.com/puppetlabs/puppet-strings/)
+
+For sure you can hack around with rake/make and hack something up each time but aint nobody got time for that!
+
+## Installation
+
+Install the `puppetlabs-onceover-codequality` gem by adding it to your `Gemfile` or by running the following command:
+
+```shell
+gem install puppetlabs-onceover-codequality
+```
+
+## Usage
+
+Installing the codequality gem creates a new item within puppetlabs-onceover's `run` command: `codequality`.  See `puppetlabs-onceover run codequality --help` for all available options.
+
+The command will return `1` to the system if any tests fail, otherwise `0`, which makes it perfect to include in build pipelines.
+
+### Check all code in the control repository for Lint and Syntax errors
+
+```shell
+puppetlabs-onceover run codequality
+```
+
+### Skip Lint check
+
+```shell
+puppetlabs-onceover run codequality --no_lint
+```
+
+### Skip Puppet syntax check
+
+```shell
+puppetlabs-onceover run codequality --no_syntax
+```
+
+### Skip Puppetfile syntax check
+
+```shell
+puppetlabs-onceover run codequality --no_puppetfile
+```
+
+### Skip documentation generation
+
+```shell
+puppetlabs-onceover run codequality --no_docs
+```
+
+### Use custom lint setting
+
+Create a file `puppet-lint.rc` in the directory you run `puppetlabs-onceover codequality`
+from and it will be automatically used by Puppet Lint. If missing, the built-in
+defaults from `lib/puppetlabs-onceover/codequality/lint.rb` will be used.
+
+
+## Sample output
+
+### All clear
+
+```shell
+$ puppetlabs-onceover run codequality
+INFO   -> Checking for lint...
+INFO   -> checking manifests
+INFO   -> checking site/role
+INFO   -> Checking syntax...
+---> syntax:manifests
+---> syntax:templates
+---> syntax:hiera:yaml
+INFO   -> Code Quality tests passed, have a nice day
+```
+
+### Lint and syntax errors
+
+```shell
+$ puppetlabs-onceover run codequality
+INFO   -> Checking for lint...
+INFO   -> checking manifests
+INFO   -> checking site/role
+./manifests/example.pp - WARNING: class not documented on line 1
+./manifests/webserver.pp - WARNING: class not documented on line 1
+./manifests/database_server.pp - WARNING: class not documented on line 1
+ERROR  -> Lint test failed, see previous errors
+INFO   -> Checking syntax...
+---> syntax:manifests
+Could not parse for environment *root*: Syntax error at 'ensure' at /home/geoff/crud/control-repo/manifests/bogus.pp:2:3
+ERROR  -> Syntax test failed, see previous errors
+ERROR  -> Code Quality tests failed, see previous error
+$ echo $?
+1
+```
+
+## FAQ
+
+**`WARN: Unresolved specs during Gem::Specification.reset`?**
+
+I get these errors when I run `puppetlabs-onceover run codequality` but everything seems to work, what gives?:
+
+```shell
+WARN: Unresolved specs during Gem::Specification.reset:
+      rake (>= 0)
+      hiera (< 4, >= 2.0)
+      gettext (>= 3.0.2)
+WARN: Clearing out unresolved specs.
+Please report a bug if this causes problems.
+```
+
+Beats me - something to do with rubygems.  The best way to beat this message is to use [bundler](https://github.com/bundler/bundler) which basically you should already be doing anyway (for your own sanity):
+
+```shell
+bundle exec puppetlabs-onceover run codequality
+```
+
+**What are you using under-the-hood?**
+
+* [puppet-lint](https://github.com/rodjek/puppet-lint)
+* [puppet-syntax](https://github.com/voxpupuli/puppet-syntax)
+* [puppet-strings](https://github.com/puppetlabs/puppet-strings/)
+* [r10k](https://github.com/puppetlabs/r10k/)
+
+## Development
+
+### Writing your own onceover plugins
+
+Have a look at [helloworld plugin](https://github.com/declarativesystems/onceover-helloworld) if you want to have a go at writing a plugin of your own.
+
+### How to run tests
+
+```shell
+bundle exec rake spec
+```
+
+## Contributing
+
+* Bug reports and pull requests welcome
+
+## Transfer Notice
+
+This project was originally authored by dylanratcliffe. The maintainer preferred that Vox Pupuli take ownership of the project for future improvement and maintenance.
+Existing pull requests and issues were transferred over, please fork and continue to contribute here instead of voxpupuli/onceover-codequality.

data/Rakefile

@@ -0,0 +1,21 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec
+
+begin
+  require 'rubygems'
+  require 'github_changelog_generator/task'
+rescue LoadError
+  # Do nothing if no required gem installed
+else
+  GitHubChangelogGenerator::RakeTask.new :changelog do |config|
+    config.exclude_labels = %w[duplicate question invalid wontfix wont-fix skip-changelog github_actions]
+    config.user = 'puppetlabs'
+    config.project = 'puppetlabs-onceover-codequality'
+    gem_version = Gem::Specification.load("#{config.project}.gemspec").version
+    config.future_release = "v#{gem_version}"
+  end
+end

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "puppetlabs-onceover/codequality"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/lib/puppetlabs-onceover/codequality/cli.rb

@@ -0,0 +1,65 @@
+require "puppetlabs-onceover/codequality/lint"
+require "puppetlabs-onceover/codequality/syntax"
+require "puppetlabs-onceover/codequality/docs"
+require "puppetlabs-onceover/codequality/puppetfile"
+require "puppetlabs-onceover/codequality/environment"
+require "puppetlabs-onceover/codequality/executor"
+require "puppetlabs-onceover/codequality/formatter"
+class PuppetlabsOnceover
+  module CodeQuality
+    class CLI
+      def self.command
+        @cmd ||= Cri::Command.define do
+          name 'codequality'
+          usage 'codequality [--no-syntax] [--no-lint] [--no-docs] [--html-docs] [--no-puppetfile]'
+          summary "Code Quality checking for onceover"
+          description <<-DESCRIPTION
+              Check files in your Control Repository for Lint and Syntax errors
+          DESCRIPTION
+
+          flag nil, :no_lint, 'Do not check for lint errors', :argument => :optional
+          flag nil, :no_puppetfile, 'Do not check Puppetfile for syntax errors', :argument => :optional
+          flag nil, :no_syntax, 'Do not check for syntax errors', :argument => :optional
+          flag nil, :no_docs, 'Do not generate documentation (puppet-strings) for local modules', :argument => :optional
+          flag nil, :html_docs, 'Generate docs in HTML format instead of markdown', :argument => :optional
+
+          run do |opts, args, cmd|
+            no_lint = opts[:no_lint] || false
+            no_syntax = opts[:no_syntax] || false
+            no_docs = opts[:no_docs] || false
+            no_puppetfile = opts[:no_puppetfile] || false
+            html_docs = opts[:html_docs] || false
+            status = true
+
+            logger.info "Running Code Quality tests"
+
+            if !no_puppetfile
+              status &= PuppetlabsOnceover::CodeQuality::Puppetfile.puppetfile
+            end
+
+            if !no_syntax
+              status &= PuppetlabsOnceover::CodeQuality::Syntax.puppet
+            end
+
+            if !no_lint
+              status &= PuppetlabsOnceover::CodeQuality::Lint.puppet
+            end
+
+            if !no_docs
+              status &= PuppetlabsOnceover::CodeQuality::Docs.puppet_strings(html_docs)
+            end
+
+            if status
+              logger.info "Code Quality tests PASSED, have a nice day"
+            else
+              logger.error "Code Quality tests FAILED, see previous error(s)"
+              exit 1
+            end
+          end
+        end
+      end
+    end
+  end
+end
+
+PuppetlabsOnceover::CLI::Run.command.add_command(PuppetlabsOnceover::CodeQuality::CLI.command)

data/lib/puppetlabs-onceover/codequality/docs.rb

@@ -0,0 +1,28 @@
+# Support for generating documentation using Puppet Strings for each module
+# listed in the environment.conf modulepath
+class PuppetlabsOnceover
+  module CodeQuality
+    module Docs
+      def self.puppet_strings(html_docs)
+        status = true
+        format = html_docs ? "--markup html" : "--format markdown"
+
+        CodeQuality::Environment.get_site_dirs.each { |local_mod_dir|
+          if Dir.exist?(local_mod_dir)
+            Dir.glob("#{local_mod_dir}/*/") { |dir|
+              Dir.chdir(dir) {
+                CodeQuality::Formatter.start_test("Generate documentation in #{dir}")
+                # puppet strings prints useful metrics so don't swallow its output
+                output, ok = CodeQuality::Executor.run("puppet strings generate #{format}")
+                status &= ok
+                CodeQuality::Formatter.end_test(output, ok, true)
+              }
+            }
+          end
+        }
+
+        status
+      end
+    end
+  end
+end

data/lib/puppetlabs-onceover/codequality/environment.rb

@@ -0,0 +1,33 @@
+class PuppetlabsOnceover
+  module CodeQuality
+    module Environment
+      ENVIRONMENT_CONF = "environment.conf"
+
+      # Latest best practice is to change the name of `site` to be
+      # `site-modules`. This means we need to start processing `environment.conf`
+      # to extract this...
+      def self.get_site_dirs()
+        if File.exist?(ENVIRONMENT_CONF)
+          # modulepath = site-modules:modules:$basemodulepath
+          modulepath = open(ENVIRONMENT_CONF) { |f| f.each_line.find { |line| line.include?("modulepath") } }
+
+          begin
+            environments = modulepath.split("=")[1].split(":").reject { |e|
+              # reject any elements containing interpolation or referencing modules
+              # loaded by r10k
+              e =~ /\$/ || e == "modules" || e =~ /[\\.\/]/
+            }.map { |e|
+              e.strip
+            }
+          rescue NoMethodError => e
+            raise "Malformed environment configuration: #{ENVIRONMENT_CONF}"
+          end
+        else
+          raise "Missing environment configuration: #{ENVIRONMENT_CONF}"
+        end
+
+        environments
+      end
+    end
+  end
+end

data/lib/puppetlabs-onceover/codequality/executor.rb

@@ -0,0 +1,13 @@
+class PuppetlabsOnceover
+  module CodeQuality
+    module Executor
+      # Capture all program output and check the exit status was zero
+      def self.run(*command)
+        output, s = Open3.capture2e(*command)
+        ok = s.exitstatus.zero?
+
+        return output, ok
+      end
+    end
+  end
+end

data/lib/puppetlabs-onceover/codequality/formatter.rb

@@ -0,0 +1,30 @@
+class PuppetlabsOnceover
+  module CodeQuality
+    module Formatter
+      START_TEST = "Checking".freeze
+      MSG_TEST_OK = "...OK".freeze
+
+      def self.start_test(test_name)
+        logger.info "Checking #{test_name}..."
+      end
+
+      def self.end_test(output, ok, show_output = false)
+        if !ok || show_output
+          output.each_line do |line|
+            if line.start_with?('::') # This is special syntax for GitHub annotations
+              puts(line)
+            else
+              logger.info("\t#{line.chomp}")
+            end
+          end
+        end
+
+        if ok
+          logger.info "...OK"
+        else
+          logger.error "...FAILED"
+        end
+      end
+    end
+  end
+end

data/lib/puppetlabs-onceover/codequality/lint.rb

@@ -0,0 +1,45 @@
+class PuppetlabsOnceover
+  module CodeQuality
+    module Lint
+      # Apply linting to the manifests directory and each module under `site`
+      LINT_PATHS = [
+        "manifests",
+      ]
+
+      # use our default options unless user has created own settings
+      if !File.exist? ".puppet-lint.rc"
+        LINT_OPTIONS = [
+          "--relative",
+          "--fail-on-warnings",
+          "--no-double_quoted_strings-check",
+          "--no-80chars-check",
+          "--no-variable_scope-check",
+          "--no-quoted_booleans-check",
+        ].freeze
+      else
+        LINT_OPTIONS = [].freeze
+      end
+
+      def self.puppet
+        status = true
+
+        # wait until runtime to scan directories for unit tests
+        lint_paths = LINT_PATHS.concat(
+          CodeQuality::Environment.get_site_dirs.each { |site_dir|
+            Dir.glob("#{site_dir}/*").select { |f| File.directory? f }
+          }
+        )
+        lint_paths.each { |p|
+          if Dir.exist?(p)
+            CodeQuality::Formatter.start_test("lint in #{p}")
+            output, ok = CodeQuality::Executor.run("puppet-lint #{LINT_OPTIONS.join ' '} #{p}")
+            status &= ok
+            CodeQuality::Formatter.end_test(output, ok)
+          end
+        }
+
+        status
+      end
+    end
+  end
+end

data/lib/puppetlabs-onceover/codequality/puppetfile.rb

@@ -0,0 +1,22 @@
+# Support for checking syntax of Puppetfile
+class PuppetlabsOnceover
+  module CodeQuality
+    module Puppetfile
+      def self.puppetfile
+        status = true
+        if File.exist?("Puppetfile")
+          CodeQuality::Formatter.start_test("Puppetfile")
+          output, ok = CodeQuality::Executor.run("r10k puppetfile check")
+
+          status &= ok
+
+          CodeQuality::Formatter.end_test(output, ok)
+        else
+          logger.warn("No Puppetfile found... continuing")
+        end
+
+        status
+      end
+    end
+  end
+end

data/lib/puppetlabs-onceover/codequality/syntax.rb

@@ -0,0 +1,54 @@
+class PuppetlabsOnceover
+  module CodeQuality
+    module Syntax
+      def self.puppet
+        status = true
+
+        #
+        # puppet-syntax
+        #
+
+        CodeQuality::Formatter.start_test("puppetlabs-syntax rake task")
+        # puppetlabs-syntax seems to assign $stdout/$stderr internally in ways that
+        # prevent capturing output. As a nasty hack, run it as inline ruby and
+        # capture the output from the process...
+        inline_ruby = <<-RUBY_CODE
+          require 'puppetlabs-syntax/tasks/puppetlabs-syntax'
+          PuppetlabsSyntax.exclude_paths = ['vendor/**/*','spec/templates/*.erb']
+          Rake::Task['syntax'].invoke
+        RUBY_CODE
+        # output, s = Open3.capture2e("ruby", "-e", inline_ruby)
+        output, ok = CodeQuality::Executor.run("ruby", "-e", inline_ruby)
+        status &= ok
+        CodeQuality::Formatter.end_test(output, ok)
+
+        #
+        # python yaml
+        #
+
+        # Python gives us "better" validation of YAML data then ruby, eg:
+        # ```yaml
+        #  foo: bar
+        # baz: clive
+        # ```
+        #
+        # would parse only the foo key in ruby, throwing away the baz key due to
+        # a perceived negative indent, whereas python would tell you to fix the
+        # file and make it consistent. This is yaml implementation dependent but
+        # users would be advised to fix the file, so lets _also_ validate yaml
+        # files with python if available on our path...
+        if system("python --version && python -c 'import yaml'", :err => File::NULL)
+          CodeQuality::Formatter.start_test("Additional python YAML validation")
+          script = File.join(File.dirname(File.expand_path(__FILE__)), "../../../res/validate_yaml.py")
+          output, ok = CodeQuality::Executor.run("python #{script}")
+          status &= ok
+          CodeQuality::Formatter.end_test(output, ok)
+        else
+          logger.warn("Please install python and pyyaml for enhanced YAML validation (pip install pyyaml)")
+        end
+
+        status
+      end
+    end
+  end
+end

data/lib/puppetlabs-onceover/codequality/version.rb

@@ -0,0 +1,5 @@
+class PuppetlabsOnceover
+  module CodeQuality
+    VERSION = "1.2.1".freeze
+  end
+end

data/lib/puppetlabs-onceover/codequality.rb

@@ -0,0 +1,7 @@
+require "puppetlabs-onceover/codequality/version"
+require "puppetlabs-onceover/codequality/cli"
+
+class PuppetlabsOnceover
+  module CodeQuality
+  end
+end

data/puppetlabs-onceover-codequality.gemspec

@@ -0,0 +1,30 @@
+# coding: utf-8
+
+lib = File.expand_path("../lib", __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require "puppetlabs-onceover/codequality/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "puppetlabs-onceover-codequality"
+  spec.version       = PuppetlabsOnceover::CodeQuality::VERSION
+  spec.authors       = ["Puppet, Inc."]
+  spec.email         = ["modules-team@puppet.com"]
+  spec.license       = "Apache-2.0"
+
+  spec.summary       = %q{Lint and syntax validation for puppetlabs-onceover}
+  spec.homepage      = "https://github.com/puppetlabs/puppetlabs-onceover-codequality"
+
+  spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.required_ruby_version = Gem::Requirement.new('>= 3.2')
+
+  spec.add_dependency 'puppetlabs-onceover', '~> 5.0'
+  spec.add_dependency 'puppetlabs-syntax', '~> 7.0'
+  spec.add_dependency 'puppet-lint', '~> 5.1'
+  spec.add_dependency 'puppet-strings', '>= 5.0', '< 8.0'
+  spec.add_dependency 'rake', '~> 13.3'
+  spec.add_dependency 'rspec', '~> 3.13'
+end

data/res/validate_yaml.py

@@ -0,0 +1,25 @@
+import sys
+import os
+import re
+
+status = 0
+try:
+  import yaml
+  for root, dirs, files in os.walk("."):
+    for f in files:
+      # we want yaml files that are not in hidden (.) dirs or vendor directory. account for / vs \ on windows/linux
+      target = os.path.join(root, f)
+      if target.endswith(".yaml") and not re.match("^\.(/|\\\)(\.|vendor)", target):
+        try:
+          yaml.safe_load(open(target,"r"))
+        except Exception as e:
+          status = 1
+          print("YAML syntax error in %s: %s" % (target, str(e)))
+
+except ImportError as e:
+  status = 1
+  print("Please install the python-yaml library: pip install pyyaml")
+
+
+sys.exit(status)
+