cocov_plugin_kit 0.1.1 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 58a993db2cae820ec262839636dcec32f746ba604fefe2c421fe6ee3f559ec2f
-  data.tar.gz: 84f5d7cc669b2207405588ff063cedfe76bd585f00af7708fe2268100b8049e9
+  metadata.gz: 40112f205669ad015d2fd5a49b1391820633eff66544fdd927d6e1cca210def1
+  data.tar.gz: 3a0a3faa3e564fe377d6595522aa7ae68e28bd312f54b7caa85c9d32cbb5fde1
 SHA512:
-  metadata.gz: f715fb0d82ee68aef358b981cd6e15ee1cd99feb216d05cf1f138eca85b550c5251c8bd248b14f009d919063379d4b25a0f899188a5156580e6bc1233fc17866
-  data.tar.gz: '0394e82212fb0fa3f5accb0302c02b0bb9682310f4e7bf162b3410a9fdc43bae18765e4d263dd19004119065c071217549e35a8a509571b5c45d64ff8a0a2d85'
+  metadata.gz: 034064d2eeb761d390912e9beb0f0f8acd09305663480e924e0a949f2bdf2aa9b437cc5a2c77323226fd15abd19f9753adc6301fc97f692718831bbff146c1ab
+  data.tar.gz: 328f90eaa0a1bc264d7270aaaf920c87c4b7b8cdc526694a1eb4bb5904aa5c47ed45d7f46d993cca82fa10daa0e4f12f9d2076dbebed6318354281431793f33d

data/.rubocop.yml

@@ -2,6 +2,15 @@ AllCops:
   TargetRubyVersion: 2.6
   NewCops: enable
 
+Metrics/AbcSize:
+  Enabled: false
+
+Metrics/MethodLength:
+  Enabled: false
+
+Metrics/ParameterLists:
+  Enabled: false
+
 Style/StringLiterals:
   Enabled: true
   EnforcedStyle: double_quotes
@@ -12,3 +21,13 @@ Style/StringLiteralsInInterpolation:
 
 Layout/LineLength:
   Max: 120
+  Exclude:
+    - plugin_kit.gemspec
+
+Metrics/BlockLength:
+  Exclude:
+    - spec/**/*.rb
+
+Lint/RescueException:
+  Exclude:
+    - lib/cocov/plugin_kit.rb

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    cocov_plugin_kit (0.1.1)
+    cocov_plugin_kit (0.1.2)
 
 GEM
   remote: https://rubygems.org/

data/lib/cocov/plugin_kit/exec.rb

@@ -2,10 +2,15 @@
 
 module Cocov
   module PluginKit
+    # Exec provides utilities for executing processes and obtaining its results.
     module Exec
+      # ExecutionError is thrown when an #exec or #exec2 procedure fails. It
+      # includes the captured stdout and stderr streams, along with the exit
+      # status, the original command and its environment.
       class ExecutionError < StandardError
         attr_reader :stdout, :stderr, :status, :cmd, :env
 
+        # Internal: Initializes a new ExecutionError instance
         def initialize(status, stdout, stderr, cmd, env)
           super("Process #{cmd.split.first} exited with status #{status}")
           @status = status
@@ -18,6 +23,19 @@ module Cocov
 
       module_function
 
+      # Public: Executes a given command (represented as an array of strings),
+      # returning both its stdout and stderr streams as Strings. Extra options
+      # are passed directly to Process.spawn, except :env, which when provided
+      # must be a Hash representing environment keys and values.
+      # This function will block until the process finishes, either returning
+      # both streams (stdout, stderr) as an Array, or raising an ExecutionError.
+      #
+      # Example:
+      #
+      #   stdout, stderr = Exec::exec2(["git", "version"], chdir: "/tmp")
+      #   # stdout == "git version 2.30.2\n"
+      #   # stderr == ""
+      #
       def exec2(cmd, **options)
         out_reader, out_writer = IO.pipe
         err_reader, err_writer = IO.pipe
@@ -62,6 +80,9 @@ module Cocov
         [stdout, stderr]
       end
 
+      # Public: exec works exactly like #exec2, but only returns the stdout
+      # stream, instead of both stdout and stderr.
+      # For more information, see the documentation for #exec.
       def exec(cmd, **options)
         exec2(cmd, **options).first
       end

data/lib/cocov/plugin_kit/run.rb

@@ -2,6 +2,16 @@
 
 module Cocov
   module PluginKit
+    # Public: Run implements helpers and prepares the environment for a Plugin
+    # runtime. All Cocov Ruby plugins must either inherit this class or directly
+    # use it by using the block alternative of Cocov::PluginKit#run.
+    #
+    # The class provides the following accessors:
+    # - workdir:    The path to the root of the repository being checked. The
+    #               plugin is always executed with its pwd set to this path.
+    # - repo_name:  The name of the repository being cheked.
+    # - commit_sha: The SHA of the commit being checked.
+    #
     class Run
       attr_reader :workdir, :repo_name, :commit_sha
 
@@ -13,23 +23,34 @@ module Cocov
         @output_file = output_file
       end
 
+      # Public: When inheriting this class, the plugin entrypoint must be
+      # implemented on this method's override.
       def run; end
 
+      # Public: Alias to Exec.exec2. For more information, see the documentation
+      # for that method.
       def exec2(cmd, **options)
         Exec.exec2(cmd, **options)
       end
 
+      # Public: Alias to Exec.exec. For more information, see the documentation
+      # for that method.
       def exec(cmd, **options)
         Exec.exec(cmd, **options)
       end
 
+      # Public: Returns the SHA1 digest of the provided data
       def sha1(data)
         Digest::SHA1.hexdigest(data)
       end
 
-      ALLOWED_KINDS = %i[style performance security bug complexity duplication].freeze
+      # :nodoc:
+      ALLOWED_KINDS = %i[style performance security bug complexity duplication convention].freeze
 
-      def emit_issue(kind:, file:, line_start:, line_end:, message:, uid: nil)
+      # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+
+      # :nodoc:
+      def validate_issue_args!(kind:, file:, line_start:, line_end:, message:, uid:)
         unless ALLOWED_KINDS.include? kind
           raise ArgumentError, "Invalid kind `#{kind}'. Valid options are #{ALLOWED_KINDS.join(", ")}"
         end
@@ -44,10 +65,35 @@ module Cocov
 
         raise ArgumentError, "message must be a non-empty string" if !message.is_a?(String) || message.strip == ""
 
-        if !uid.nil? && (!uid.is_a?(String) || uid.strip == "")
-          raise ArgumentError, "uid must be a non-empty string when provided"
-        end
+        return unless !uid.nil? && (!uid.is_a?(String) || uid.strip == "")
 
+        raise ArgumentError, "uid must be a non-empty string when provided"
+      end
+      # rubocop:enable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+
+      # Public: Emits a new issue with the provided arguments.
+      #
+      # kind:       - A symbol identifying kind of the issue being emitted.
+      # file:       - The path, relative to the repository root, of the file
+      #               where the issue was found.
+      # line_start: - The first line where the issue was found. Must be greater
+      #               than zero.
+      # line_end:   - The last line where the issue was found. Must be equal or
+      #               greater than the value of line_start.
+      # message:    - A message describing the issue. Must not be empty.
+      # uid:        - An uniquely identifier representing this issue among any
+      #               other possible issue in any other file in this repository.
+      #               This identifier must be the result of a pure function;
+      #               i.e. the same issue in the same file, spanning the same
+      #               lines must have the same uid no matter how many times it
+      #               is reported. If omitted, an UID is automatically
+      #               calculated. If provided, must be a non-empty string.
+      #
+      # Returns nothing. Raises ArgumentError in case invalid data is provided
+      # (see documentation above.)
+      def emit_issue(kind:, file:, line_start:, line_end:, message:, uid: nil)
+        validate_issue_args! kind: kind, file: file, line_start: line_start,
+                             line_end: line_end, message: message, uid: uid
         data = {
           kind: kind,
           file: file,

data/lib/cocov/plugin_kit/version.rb

@@ -2,6 +2,6 @@
 
 module Cocov
   module PluginKit
-    VERSION = "0.1.1"
+    VERSION = "0.1.2"
   end
 end

data/lib/cocov/plugin_kit.rb

@@ -12,11 +12,17 @@ require_relative "plugin_kit/run"
 require_relative "plugin_kit/exec"
 
 module Cocov
+  # PluginKit implements helpers for implementing Cocov Plugins in Ruby. The
+  # main module provides a single run function that must be used to wrap the
+  # plugin runtime, and is responsible for preparing the environment and running
+  # the provided block
   module PluginKit
-    class Error < StandardError; end
-
     module_function
 
+    # Public: Prepares the environment and executes a given `klass` (Class) or
+    # a single block. When `klass` is not provided, PluginKit::Run is used.
+    # When providing a custom class, make sure to inherit PluginKit::Run.
+    # For examples, see the library's README file.
     def run(klass = nil, &block)
       output_file = File.open(ENV.fetch("COCOV_OUTPUT_FILE"), "w")
       exit_code = 0

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cocov_plugin_kit
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.2
 platform: ruby
 authors:
 - Victor Gama