cocov_plugin_kit 0.1.1 → 0.1.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 58a993db2cae820ec262839636dcec32f746ba604fefe2c421fe6ee3f559ec2f
4
- data.tar.gz: 84f5d7cc669b2207405588ff063cedfe76bd585f00af7708fe2268100b8049e9
3
+ metadata.gz: 40112f205669ad015d2fd5a49b1391820633eff66544fdd927d6e1cca210def1
4
+ data.tar.gz: 3a0a3faa3e564fe377d6595522aa7ae68e28bd312f54b7caa85c9d32cbb5fde1
5
5
  SHA512:
6
- metadata.gz: f715fb0d82ee68aef358b981cd6e15ee1cd99feb216d05cf1f138eca85b550c5251c8bd248b14f009d919063379d4b25a0f899188a5156580e6bc1233fc17866
7
- data.tar.gz: '0394e82212fb0fa3f5accb0302c02b0bb9682310f4e7bf162b3410a9fdc43bae18765e4d263dd19004119065c071217549e35a8a509571b5c45d64ff8a0a2d85'
6
+ metadata.gz: 034064d2eeb761d390912e9beb0f0f8acd09305663480e924e0a949f2bdf2aa9b437cc5a2c77323226fd15abd19f9753adc6301fc97f692718831bbff146c1ab
7
+ data.tar.gz: 328f90eaa0a1bc264d7270aaaf920c87c4b7b8cdc526694a1eb4bb5904aa5c47ed45d7f46d993cca82fa10daa0e4f12f9d2076dbebed6318354281431793f33d
data/.rubocop.yml CHANGED
@@ -2,6 +2,15 @@ AllCops:
2
2
  TargetRubyVersion: 2.6
3
3
  NewCops: enable
4
4
 
5
+ Metrics/AbcSize:
6
+ Enabled: false
7
+
8
+ Metrics/MethodLength:
9
+ Enabled: false
10
+
11
+ Metrics/ParameterLists:
12
+ Enabled: false
13
+
5
14
  Style/StringLiterals:
6
15
  Enabled: true
7
16
  EnforcedStyle: double_quotes
@@ -12,3 +21,13 @@ Style/StringLiteralsInInterpolation:
12
21
 
13
22
  Layout/LineLength:
14
23
  Max: 120
24
+ Exclude:
25
+ - plugin_kit.gemspec
26
+
27
+ Metrics/BlockLength:
28
+ Exclude:
29
+ - spec/**/*.rb
30
+
31
+ Lint/RescueException:
32
+ Exclude:
33
+ - lib/cocov/plugin_kit.rb
data/Gemfile.lock CHANGED
@@ -1,7 +1,7 @@
1
1
  PATH
2
2
  remote: .
3
3
  specs:
4
- cocov_plugin_kit (0.1.1)
4
+ cocov_plugin_kit (0.1.2)
5
5
 
6
6
  GEM
7
7
  remote: https://rubygems.org/
@@ -2,10 +2,15 @@
2
2
 
3
3
  module Cocov
4
4
  module PluginKit
5
+ # Exec provides utilities for executing processes and obtaining its results.
5
6
  module Exec
7
+ # ExecutionError is thrown when an #exec or #exec2 procedure fails. It
8
+ # includes the captured stdout and stderr streams, along with the exit
9
+ # status, the original command and its environment.
6
10
  class ExecutionError < StandardError
7
11
  attr_reader :stdout, :stderr, :status, :cmd, :env
8
12
 
13
+ # Internal: Initializes a new ExecutionError instance
9
14
  def initialize(status, stdout, stderr, cmd, env)
10
15
  super("Process #{cmd.split.first} exited with status #{status}")
11
16
  @status = status
@@ -18,6 +23,19 @@ module Cocov
18
23
 
19
24
  module_function
20
25
 
26
+ # Public: Executes a given command (represented as an array of strings),
27
+ # returning both its stdout and stderr streams as Strings. Extra options
28
+ # are passed directly to Process.spawn, except :env, which when provided
29
+ # must be a Hash representing environment keys and values.
30
+ # This function will block until the process finishes, either returning
31
+ # both streams (stdout, stderr) as an Array, or raising an ExecutionError.
32
+ #
33
+ # Example:
34
+ #
35
+ # stdout, stderr = Exec::exec2(["git", "version"], chdir: "/tmp")
36
+ # # stdout == "git version 2.30.2\n"
37
+ # # stderr == ""
38
+ #
21
39
  def exec2(cmd, **options)
22
40
  out_reader, out_writer = IO.pipe
23
41
  err_reader, err_writer = IO.pipe
@@ -62,6 +80,9 @@ module Cocov
62
80
  [stdout, stderr]
63
81
  end
64
82
 
83
+ # Public: exec works exactly like #exec2, but only returns the stdout
84
+ # stream, instead of both stdout and stderr.
85
+ # For more information, see the documentation for #exec.
65
86
  def exec(cmd, **options)
66
87
  exec2(cmd, **options).first
67
88
  end
@@ -2,6 +2,16 @@
2
2
 
3
3
  module Cocov
4
4
  module PluginKit
5
+ # Public: Run implements helpers and prepares the environment for a Plugin
6
+ # runtime. All Cocov Ruby plugins must either inherit this class or directly
7
+ # use it by using the block alternative of Cocov::PluginKit#run.
8
+ #
9
+ # The class provides the following accessors:
10
+ # - workdir: The path to the root of the repository being checked. The
11
+ # plugin is always executed with its pwd set to this path.
12
+ # - repo_name: The name of the repository being cheked.
13
+ # - commit_sha: The SHA of the commit being checked.
14
+ #
5
15
  class Run
6
16
  attr_reader :workdir, :repo_name, :commit_sha
7
17
 
@@ -13,23 +23,34 @@ module Cocov
13
23
  @output_file = output_file
14
24
  end
15
25
 
26
+ # Public: When inheriting this class, the plugin entrypoint must be
27
+ # implemented on this method's override.
16
28
  def run; end
17
29
 
30
+ # Public: Alias to Exec.exec2. For more information, see the documentation
31
+ # for that method.
18
32
  def exec2(cmd, **options)
19
33
  Exec.exec2(cmd, **options)
20
34
  end
21
35
 
36
+ # Public: Alias to Exec.exec. For more information, see the documentation
37
+ # for that method.
22
38
  def exec(cmd, **options)
23
39
  Exec.exec(cmd, **options)
24
40
  end
25
41
 
42
+ # Public: Returns the SHA1 digest of the provided data
26
43
  def sha1(data)
27
44
  Digest::SHA1.hexdigest(data)
28
45
  end
29
46
 
30
- ALLOWED_KINDS = %i[style performance security bug complexity duplication].freeze
47
+ # :nodoc:
48
+ ALLOWED_KINDS = %i[style performance security bug complexity duplication convention].freeze
31
49
 
32
- def emit_issue(kind:, file:, line_start:, line_end:, message:, uid: nil)
50
+ # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
51
+
52
+ # :nodoc:
53
+ def validate_issue_args!(kind:, file:, line_start:, line_end:, message:, uid:)
33
54
  unless ALLOWED_KINDS.include? kind
34
55
  raise ArgumentError, "Invalid kind `#{kind}'. Valid options are #{ALLOWED_KINDS.join(", ")}"
35
56
  end
@@ -44,10 +65,35 @@ module Cocov
44
65
 
45
66
  raise ArgumentError, "message must be a non-empty string" if !message.is_a?(String) || message.strip == ""
46
67
 
47
- if !uid.nil? && (!uid.is_a?(String) || uid.strip == "")
48
- raise ArgumentError, "uid must be a non-empty string when provided"
49
- end
68
+ return unless !uid.nil? && (!uid.is_a?(String) || uid.strip == "")
50
69
 
70
+ raise ArgumentError, "uid must be a non-empty string when provided"
71
+ end
72
+ # rubocop:enable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
73
+
74
+ # Public: Emits a new issue with the provided arguments.
75
+ #
76
+ # kind: - A symbol identifying kind of the issue being emitted.
77
+ # file: - The path, relative to the repository root, of the file
78
+ # where the issue was found.
79
+ # line_start: - The first line where the issue was found. Must be greater
80
+ # than zero.
81
+ # line_end: - The last line where the issue was found. Must be equal or
82
+ # greater than the value of line_start.
83
+ # message: - A message describing the issue. Must not be empty.
84
+ # uid: - An uniquely identifier representing this issue among any
85
+ # other possible issue in any other file in this repository.
86
+ # This identifier must be the result of a pure function;
87
+ # i.e. the same issue in the same file, spanning the same
88
+ # lines must have the same uid no matter how many times it
89
+ # is reported. If omitted, an UID is automatically
90
+ # calculated. If provided, must be a non-empty string.
91
+ #
92
+ # Returns nothing. Raises ArgumentError in case invalid data is provided
93
+ # (see documentation above.)
94
+ def emit_issue(kind:, file:, line_start:, line_end:, message:, uid: nil)
95
+ validate_issue_args! kind: kind, file: file, line_start: line_start,
96
+ line_end: line_end, message: message, uid: uid
51
97
  data = {
52
98
  kind: kind,
53
99
  file: file,
@@ -2,6 +2,6 @@
2
2
 
3
3
  module Cocov
4
4
  module PluginKit
5
- VERSION = "0.1.1"
5
+ VERSION = "0.1.2"
6
6
  end
7
7
  end
@@ -12,11 +12,17 @@ require_relative "plugin_kit/run"
12
12
  require_relative "plugin_kit/exec"
13
13
 
14
14
  module Cocov
15
+ # PluginKit implements helpers for implementing Cocov Plugins in Ruby. The
16
+ # main module provides a single run function that must be used to wrap the
17
+ # plugin runtime, and is responsible for preparing the environment and running
18
+ # the provided block
15
19
  module PluginKit
16
- class Error < StandardError; end
17
-
18
20
  module_function
19
21
 
22
+ # Public: Prepares the environment and executes a given `klass` (Class) or
23
+ # a single block. When `klass` is not provided, PluginKit::Run is used.
24
+ # When providing a custom class, make sure to inherit PluginKit::Run.
25
+ # For examples, see the library's README file.
20
26
  def run(klass = nil, &block)
21
27
  output_file = File.open(ENV.fetch("COCOV_OUTPUT_FILE"), "w")
22
28
  exit_code = 0
metadata CHANGED
@@ -1,7 +1,7 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: cocov_plugin_kit
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.1.1
4
+ version: 0.1.2
5
5
  platform: ruby
6
6
  authors:
7
7
  - Victor Gama