docscribe 1.4.2 → 1.5.0

data/lib/docscribe/cli/formatters/json.rb

@@ -0,0 +1,294 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'docscribe/version'
+
+module Docscribe
+  module CLI
+    module Formatters
+      # Output formatter producing RuboCop-compatible JSON.
+      #
+      # stdout: complete JSON document with all findings.
+      # stderr: progress markers only (same as text mode).
+      class Json
+        SEVERITY_MAP = {
+          missing_param: 'convention',
+          missing_return: 'convention',
+          missing_raise: 'convention',
+          missing_visibility: 'convention',
+          missing_module_function_note: 'convention',
+          insert_full_doc_block: 'convention',
+          unsorted_tags: 'convention',
+          updated_param: 'warning',
+          updated_return: 'warning'
+        }.freeze
+
+        COP_NAME_MAP = {
+          missing_param: 'Docscribe/MissingParam',
+          missing_return: 'Docscribe/MissingReturn',
+          missing_raise: 'Docscribe/MissingRaise',
+          missing_visibility: 'Docscribe/MissingVisibility',
+          missing_module_function_note: 'Docscribe/MissingModuleFunctionNote',
+          insert_full_doc_block: 'Docscribe/MissingDocBlock',
+          unsorted_tags: 'Docscribe/UnsortedTags',
+          updated_param: 'Docscribe/UpdatedParam',
+          updated_return: 'Docscribe/UpdatedReturn'
+        }.freeze
+
+        # Output JSON check summary.
+        #
+        # @param [Docscribe::CLI::Formatters::state] state formatter state hash
+        # @param [Docscribe::CLI::Formatters::opts] options runtime options hash
+        # @return [void]
+        def format_check_summary(state:, options:)
+          puts JSON.generate(build_document(state, options))
+        end
+
+        # Output JSON write summary.
+        #
+        # @param [Docscribe::CLI::Formatters::state] state formatter state hash
+        # @param [Docscribe::CLI::Formatters::opts] options runtime options hash
+        # @return [void]
+        def format_write_summary(state:, options:)
+          puts JSON.generate(build_document(state, options))
+        end
+
+        private
+
+        # Build full JSON document.
+        #
+        # @private
+        # @param [Docscribe::CLI::Formatters::state] state formatter state hash
+        # @param [Docscribe::CLI::Formatters::opts] _options runtime options hash
+        # @return [Hash<Symbol, Object>]
+        def build_document(state, _options)
+          document_hash(build_files(state), state)
+        end
+
+        # Build document hash structure.
+        #
+        # @private
+        # @param [Array<Hash<Symbol, Object>>] files files offenses array
+        # @param [Docscribe::CLI::Formatters::state] state formatter state hash
+        # @return [Hash<Symbol, Object>]
+        def document_hash(files, state)
+          {
+            metadata: metadata_hash,
+            files: files,
+            summary: summary_hash(files, state)
+          }
+        end
+
+        # Build tool metadata hash.
+        #
+        # @private
+        # @return [Hash<Symbol, String>]
+        def metadata_hash
+          {
+            docscribe_version: Docscribe::VERSION,
+            ruby_version: RUBY_VERSION
+          }
+        end
+
+        # Build summary statistics hash.
+        #
+        # @private
+        # @param [Array<Hash<Symbol, Object>>] files files offenses array
+        # @param [Docscribe::CLI::Formatters::state] state formatter state hash
+        # @return [Hash<Symbol, Integer>]
+        def summary_hash(files, state)
+          {
+            offense_count: files.sum { |f| f[:offenses].size },
+            target_file_count: files.size,
+            inspected_file_count: inspected_count(state),
+            error_count: state[:error_paths].size
+          }
+        end
+
+        # Build files array from state.
+        #
+        # @private
+        # @param [Docscribe::CLI::Formatters::state] state formatter state hash
+        # @return [Array<Hash<Symbol, Object>>]
+        def build_files(state)
+          files = [] #: Array[Hash[untyped, untyped]]
+
+          append_check_files(state, files) if state[:fail_paths].any? || state[:type_mismatch_paths].any?
+          append_corrected_files(state, files) if state[:corrected_paths].any?
+          append_error_files(state, files) if state[:error_paths].any?
+
+          files
+        end
+
+        # Append check file entries.
+        #
+        # @private
+        # @param [Docscribe::CLI::Formatters::state] state formatter state hash
+        # @param [Array<Hash<Symbol, Object>>] files files offenses array
+        # @return [void]
+        def append_check_files(state, files)
+          state[:fail_paths].each do |path|
+            files << file_entry(path, state[:fail_changes][path] || [])
+          end
+
+          state[:type_mismatch_paths].each do |path|
+            files << file_entry(path, state[:type_mismatch_changes][path] || [], severity: 'warning')
+          end
+        end
+
+        # Append corrected file entries.
+        #
+        # @private
+        # @param [Docscribe::CLI::Formatters::state] state formatter state hash
+        # @param [Array<Hash<Symbol, Object>>] files files offenses array
+        # @return [void]
+        def append_corrected_files(state, files)
+          state[:corrected_paths].each do |path|
+            merge_or_append(files, path, state[:corrected_changes][path] || [])
+          end
+        end
+
+        # Append error file entries.
+        #
+        # @private
+        # @param [Docscribe::CLI::Formatters::state] state formatter state hash
+        # @param [Array<Hash<Symbol, Object>>] files files offenses array
+        # @return [void]
+        def append_error_files(state, files)
+          state[:error_paths].each do |path|
+            merge_or_append(files, path, [error_offense(state, path)])
+          end
+        end
+
+        # Merge or append file offenses.
+        #
+        # @private
+        # @param [Array<Hash<Symbol, Object>>] files files offenses array
+        # @param [String] path file path string
+        # @param [Array<Hash<Symbol, Object>>] offenses offense objects array
+        # @return [void]
+        def merge_or_append(files, path, offenses)
+          existing = files.find { |f| f[:path] == path }
+
+          if existing
+            existing[:offenses].concat(offenses)
+          else
+            files << { path: path, offenses: offenses }
+          end
+        end
+
+        # Build single file entry hash.
+        #
+        # @private
+        # @param [String] path file path string
+        # @param [Array<Docscribe::CLI::Formatters::change>] changes changes info array
+        # @param [String?] severity offense severity level
+        # @return [Hash<Symbol, Object>]
+        def file_entry(path, changes, severity: nil)
+          { path: path, offenses: build_offenses(changes, severity: severity) }
+        end
+
+        # Build error offense entry.
+        #
+        # @private
+        # @param [Docscribe::CLI::Formatters::state] state formatter state hash
+        # @param [String] path file path string
+        # @return [Hash<Symbol, Object>]
+        def error_offense(state, path)
+          error_offense_hash(state[:error_messages][path] || 'Unknown error')
+        end
+
+        # Format error offense hash.
+        #
+        # @private
+        # @param [String] message error message string
+        # @return [Hash<Symbol, Object>]
+        def error_offense_hash(message)
+          { severity: 'fatal', cop_name: 'Docscribe/ProcessingError', message: message,
+            corrected: false, correctable: false, location: default_location }
+        end
+
+        # Default location hash value.
+        #
+        # @private
+        # @return [Hash<Symbol, Integer>]
+        def default_location
+          { start_line: 1, start_column: 1, last_line: 1, last_column: 1 }
+        end
+
+        # Build offense array from changes.
+        #
+        # @private
+        # @param [Array<Docscribe::CLI::Formatters::change>] changes changes info array
+        # @param [String?] severity offense severity level
+        # @return [Array<Hash<Symbol, Object>>]
+        def build_offenses(changes, severity: nil)
+          changes.map { |change| build_offense(change, severity) }
+        end
+
+        # Build single offense hash.
+        #
+        # @private
+        # @param [Docscribe::CLI::Formatters::change] change change info hash
+        # @param [String?] severity offense severity level
+        # @return [Hash<Symbol, Object>]
+        def build_offense(change, severity)
+          {
+            severity: severity || SEVERITY_MAP[change[:type]] || 'convention',
+            cop_name: COP_NAME_MAP[change[:type]] || cop_name_fallback(change),
+            message: build_message(change),
+            corrected: false,
+            correctable: true,
+            location: location_for(change)
+          }
+        end
+
+        # Build location hash from change.
+        #
+        # @private
+        # @param [Docscribe::CLI::Formatters::change] change change info hash
+        # @return [Hash<Symbol, Integer>]
+        def location_for(change)
+          line = change[:line] || 1
+          { start_line: line, start_column: 1, last_line: line, last_column: 1 }
+        end
+
+        # Fallback cop name from type.
+        #
+        # @private
+        # @param [Docscribe::CLI::Formatters::change] change change info hash
+        # @return [String]
+        def cop_name_fallback(change)
+          name = change[:type].to_s.tr('_', '_').capitalize
+          "Docscribe/#{name}"
+        end
+
+        # Build human-readable message.
+        #
+        # @private
+        # @param [Docscribe::CLI::Formatters::change] change change info hash
+        # @return [String]
+        def build_message(change)
+          method = change[:method] ? " for #{change[:method]}" : ''
+          line = change[:line] ? " at line #{change[:line]}" : ''
+
+          return "unsorted tags#{line}" if change[:type] == :unsorted_tags
+
+          msg = change[:message] || change[:type].to_s.tr('_', ' ')
+          "#{msg}#{method}#{line}"
+        end
+
+        # Count inspected file total.
+        #
+        # @private
+        # @param [Docscribe::CLI::Formatters::state] state formatter state hash
+        # @return [Integer]
+        def inspected_count(state)
+          total = state[:checked_ok] + state[:checked_fail] + state[:type_mismatch_paths].size
+          total = state[:corrected] if total.zero? && state[:corrected].positive?
+          total + state[:error_paths].size
+        end
+      end
+    end
+  end
+end

data/lib/docscribe/cli/formatters/sarif.rb

@@ -0,0 +1,235 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'docscribe/version'
+
+module Docscribe
+  module CLI
+    module Formatters
+      # Output formatter producing SARIF 2.1 JSON.
+      #
+      # SARIF (Static Analysis Results Interchange Format) is a standard
+      # format for static analysis tools. This formatter produces output
+      # compatible with GitHub Code Scanning, VS Code SARIF viewer, etc.
+      #
+      # stdout: complete SARIF 2.1 document with all findings.
+      # stderr: progress markers only (same as text mode).
+      class Sarif
+        SEVERITY_MAP = {
+          missing_param: 'note',
+          missing_return: 'note',
+          missing_raise: 'note',
+          missing_visibility: 'note',
+          missing_module_function_note: 'note',
+          insert_full_doc_block: 'note',
+          unsorted_tags: 'note',
+          updated_param: 'warning',
+          updated_return: 'warning'
+        }.freeze
+
+        COP_NAME_MAP = {
+          missing_param: 'Docscribe/MissingParam',
+          missing_return: 'Docscribe/MissingReturn',
+          missing_raise: 'Docscribe/MissingRaise',
+          missing_visibility: 'Docscribe/MissingVisibility',
+          missing_module_function_note: 'Docscribe/MissingModuleFunctionNote',
+          insert_full_doc_block: 'Docscribe/MissingDocBlock',
+          unsorted_tags: 'Docscribe/UnsortedTags',
+          updated_param: 'Docscribe/UpdatedParam',
+          updated_return: 'Docscribe/UpdatedReturn'
+        }.freeze
+
+        SARIF_SCHEMA = 'https://raw.githubusercontent.com/oasis-tcs/sarif-spec/' \
+                       'master/Schemata/sarif-schema-2.1.0.json'
+
+        # @param [Docscribe::CLI::Formatters::state] state
+        # @param [Docscribe::CLI::Formatters::opts] options
+        # @return [void]
+        def format_check_summary(state:, options:)
+          puts JSON.generate(build_sarif_document(state, options[:format]))
+        end
+
+        # @param [Docscribe::CLI::Formatters::state] state
+        # @param [Docscribe::CLI::Formatters::opts] options
+        # @return [void]
+        def format_write_summary(state:, options:)
+          puts JSON.generate(build_sarif_document(state, options[:format]))
+        end
+
+        private
+
+        # @private
+        # @param [Docscribe::CLI::Formatters::state] state
+        # @param [Object] _format
+        # @return [Hash<String, Symbol, Object>]
+        def build_sarif_document(state, _format)
+          {
+            '$schema' => SARIF_SCHEMA,
+            version: '2.1.0',
+            runs: [build_run(state)]
+          }
+        end
+
+        # @private
+        # @param [Docscribe::CLI::Formatters::state] state
+        # @return [Hash<Symbol, Object>]
+        def build_run(state)
+          {
+            tool: build_tool,
+            results: build_results(state),
+            invocations: [build_invocation(state)]
+          }
+        end
+
+        # @private
+        # @return [Hash<Symbol, Object>]
+        def build_tool
+          {
+            driver: {
+              name: 'docscribe',
+              version: Docscribe::VERSION,
+              informationUri: 'https://github.com/unurgunite/docscribe'
+            }
+          }
+        end
+
+        # @private
+        # @param [Docscribe::CLI::Formatters::state] state
+        # @return [Array<Hash<Symbol, Object>>]
+        def build_results(state)
+          results = [] #: Array[Hash[Symbol, top]]
+
+          append_check_results(state, results)
+          append_corrected_results(state, results)
+          append_error_results(state, results)
+
+          results
+        end
+
+        # @private
+        # @param [Docscribe::CLI::Formatters::state] state
+        # @param [Array<Hash<Symbol, Object>>] results
+        # @return [void]
+        def append_check_results(state, results)
+          append_changes(state[:fail_paths], state[:fail_changes], results)
+          append_changes(state[:type_mismatch_paths], state[:type_mismatch_changes], results, level: 'warning')
+        end
+
+        # @private
+        # @param [Array<String>] paths
+        # @param [Hash<String, Array<Docscribe::CLI::Formatters::change>>] changes_map
+        # @param [Array<Hash<Symbol, Object>>] results
+        # @param [String?] level
+        # @return [void]
+        def append_changes(paths, changes_map, results, level: nil)
+          paths.each do |path|
+            (changes_map[path] || []).each do |change|
+              results << build_result(change, path, level: level)
+            end
+          end
+        end
+
+        # @private
+        # @param [Docscribe::CLI::Formatters::state] state
+        # @param [Array<Hash<Symbol, Object>>] results
+        # @return [void]
+        def append_corrected_results(state, results)
+          state[:corrected_paths].each do |path|
+            changes = state[:corrected_changes][path] || []
+            changes.each do |change|
+              results << build_result(change, path)
+            end
+          end
+        end
+
+        # @private
+        # @param [Docscribe::CLI::Formatters::state] state
+        # @param [Array<Hash<Symbol, Object>>] results
+        # @return [void]
+        def append_error_results(state, results)
+          state[:error_paths].each do |path|
+            msg = state[:error_messages][path] || 'Unknown error'
+            results << build_error_result(msg, path)
+          end
+        end
+
+        # @private
+        # @param [Docscribe::CLI::Formatters::change] change
+        # @param [String] path
+        # @param [String?] level
+        # @return [Hash<Symbol, Object>]
+        def build_result(change, path, level: nil)
+          {
+            ruleId: cop_name_for(change),
+            level: level || SEVERITY_MAP[change[:type]] || 'note',
+            message: { text: message_for(change) },
+            locations: [location(path, change[:line] || 1)]
+          }
+        end
+
+        # @private
+        # @param [String] message
+        # @param [String] path
+        # @return [Hash<Symbol, Object>]
+        def build_error_result(message, path)
+          {
+            ruleId: 'Docscribe/ProcessingError',
+            level: 'error',
+            message: { text: message },
+            locations: [location(path, 1)]
+          }
+        end
+
+        # @private
+        # @param [String] path
+        # @param [Integer] line
+        # @return [Hash<Symbol, Object>]
+        def location(path, line)
+          {
+            physicalLocation: {
+              artifactLocation: { uri: path },
+              region: { startLine: line }
+            }
+          }
+        end
+
+        # @private
+        # @param [Docscribe::CLI::Formatters::change] change
+        # @return [String]
+        def cop_name_for(change)
+          COP_NAME_MAP[change[:type]] || fallback_cop_name(change)
+        end
+
+        # @private
+        # @param [Docscribe::CLI::Formatters::change] change
+        # @return [String]
+        def fallback_cop_name(change)
+          name = change[:type].to_s.tr('_', ' ').split.map(&:capitalize).join
+          "Docscribe/#{name}"
+        end
+
+        # @private
+        # @param [Docscribe::CLI::Formatters::change] change
+        # @return [String]
+        def message_for(change)
+          method = change[:method] ? " for #{change[:method]}" : ''
+          line = change[:line] ? " at line #{change[:line]}" : ''
+
+          return "unsorted tags#{line}" if change[:type] == :unsorted_tags
+
+          msg = change[:message] || change[:type].to_s.tr('_', ' ')
+          "#{msg}#{method}#{line}"
+        end
+
+        # @private
+        # @param [Docscribe::CLI::Formatters::state] state
+        # @return [Hash<Symbol, Object>]
+        def build_invocation(state)
+          {
+            executionSuccessful: !state[:had_errors]
+          }
+        end
+      end
+    end
+  end
+end