rubocop-osc7501 0.1.0

data/lib/rubocop/osc7501/lifecycle.rb

@@ -0,0 +1,302 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+require_relative 'writer'
+
+module RuboCop
+  # @rbs!
+  #   class CLI
+  #     attr_reader options: untyped
+  #     def execute_runners: (*untyped args) ?{ (*untyped) -> untyped } -> untyped
+  #   end
+  #   class Runner
+  #     def run: (*untyped args) ?{ (*untyped) -> untyped } -> untyped
+  #     def aborting?: () -> bool
+  #     private
+  #     def formatter_set: () -> untyped
+  #   end
+  #   module Formatter
+  #     class BaseFormatter
+  #       attr_reader output: untyped
+  #       attr_reader options: untyped
+  #       def initialize: (untyped output, ?untyped options) -> void
+  #       def started: (untyped target_files) -> void
+  #       def file_finished: (untyped file, untyped offenses) -> void
+  #       def finished: (untyped inspected_files) -> void
+  #     end
+  #   end
+
+  module OSC7501
+    # Private invocation hooks and observations for supported finite direct
+    # RuboCop inspections. Require-time installation stays inert.
+    module Lifecycle # :nodoc: all
+      # Options that select a non-inspection command. These come from the
+      # native parsed options at each supported boundary version.
+      NON_INSPECTION_OPTIONS = %i[
+        help version verbose_version show_cops list_enabled_cops_for
+        show_docs_url explain lsp mcp init list_target_files auto_gen_config
+      ].freeze
+
+      FORMATTER_NAMES = ['RuboCop::OSC7501::Formatter', '::RuboCop::OSC7501::Formatter'].freeze
+      THREAD_KEY = :rubocop_osc7501_invocation
+
+      # Owns one invocation's counters, elected reporter and final outcome.
+      class Invocation
+        # @rbs @mode: String
+        # @rbs @clock: Proc
+        # @rbs @formatters: Array[[untyped, Writer]]
+        # @rbs @reporter: untyped?
+        # @rbs @reporter_writer: Writer?
+        # @rbs @total: Integer?
+        # @rbs @results: Integer
+        # @rbs @offenses: Integer
+        # @rbs @started: bool
+        # @rbs @finished: bool
+        # @rbs @closed: bool
+        # @rbs @last_update: Float
+        # @rbs @runner_aborting: bool
+
+        attr_reader :mode, :reporter
+
+        #: (mode: String, ?clock: Proc?) -> void
+        def initialize(mode:, clock: nil)
+          unless %w[auto off force].include?(mode)
+            raise ArgumentError, 'RUBOCOP_OSC7501 must be auto, off, or force'
+          end
+
+          @mode = mode
+          @clock = clock || proc { Process.clock_gettime(Process::CLOCK_MONOTONIC) }
+          @formatters = []
+          @reporter = nil
+          @reporter_writer = nil
+          @total = nil
+          @results = 0
+          @offenses = 0
+          @started = false
+          @finished = false
+          @closed = false
+          @last_update = @clock.call
+          @runner_aborting = false
+        end
+
+        # Registers a selected OSC formatter in native construction order.
+        # The first formatter whose writer is enabled owns reporting.
+        #: (untyped formatter, Writer writer) -> void
+        def add_formatter(formatter, writer)
+          @formatters << [formatter, writer]
+          return unless @reporter.nil? && writer.enabled?
+
+          @reporter = formatter
+          @reporter_writer = writer
+        end
+
+        # Emits the initial working record after the native formatter set is
+        # available, before target discovery and old warm-cache work.
+        #: () -> nil
+        def attach
+          emit_working('Inspecting files')
+          nil
+        end
+
+        #: (untyped formatter, Integer total) -> nil
+        def started(formatter, total)
+          return nil unless reporter.equal?(formatter)
+
+          @started = true
+          @total = total
+          emit_working(count_message)
+          nil
+        end
+
+        #: (untyped formatter, untyped offenses) -> nil
+        def file_finished(formatter, offenses)
+          return nil unless reporter.equal?(formatter)
+
+          @results += 1
+          @offenses += offenses.length if offenses.respond_to?(:length)
+          now = @clock.call
+          return nil if now - @last_update < 0.1
+
+          @last_update = now
+          emit_working(count_message)
+          nil
+        end
+
+        #: (untyped runner) -> nil
+        def capture_runner(runner)
+          @runner_aborting = runner.respond_to?(:aborting?) && runner.aborting?
+          nil
+        end
+
+        #: (untyped status) -> nil
+        def finish_result(status)
+          if @runner_aborting
+            finish('idle', 'Stopped')
+          elsif status == 0
+            finish('done', 'Inspection complete')
+          else
+            finish('error', 'Inspection failed')
+          end
+        end
+
+        #: (Exception exception) -> nil
+        def finish_exception(exception)
+          stopped = exception.is_a?(Interrupt) || (exception.is_a?(SystemExit) && exception.success?)
+          finish(stopped ? 'idle' : 'error', stopped ? 'Stopped' : 'Inspection failed')
+        end
+
+        # Closes still-open File outputs from a native formatter set that was
+        # returned successfully before a later failure escaped the runner.
+        #: (untyped formatter_set) -> nil
+        def cleanup_native(formatter_set)
+          formatter_set.each do |formatter|
+            begin
+              output = formatter.output
+              output.close if output.is_a?(File) && !output.closed?
+            rescue IOError, SystemCallError
+              nil
+            end
+          end
+          nil
+        end
+
+        # Releases every adapter-owned duplicate exactly once.
+        #: () -> nil
+        def close
+          return nil if @closed
+
+          @closed = true
+          @formatters.each { |(_formatter, writer)| writer.close }
+          nil
+        end
+
+        private
+
+        #: (String) -> void
+        def emit_working(message)
+          return if @finished || reporter.nil?
+
+          writer = @reporter_writer
+          writer.emit(state: 'working', msg: message) if writer
+        end
+
+        #: (String, String) -> nil
+        def finish(state, message)
+          return nil if @finished
+
+          @finished = true
+          writer = @reporter_writer
+          writer.emit(state: state, msg: outcome_message(message)) if writer
+          nil
+        end
+
+        #: (String) -> String
+        def outcome_message(message)
+          return message unless @started
+
+          "#{message}: #{count_message}"
+        end
+
+        #: () -> String
+        def count_message
+          "#{@results}/#{@total} file results, #{@offenses} reported offenses"
+        end
+      end
+
+      # Prepended to RuboCop::CLI: owns context and finalization around the
+      # private command boundary reached after --require has loaded the gem.
+      # @rbs module-self RuboCop::CLI
+      module CLIHook
+        #: [T] (*untyped args) { (*untyped) -> T } -> T
+        def execute_runners(*args, &block)
+          invocation = Lifecycle.invocation_for(self)
+          return super unless invocation
+
+          previous = Lifecycle.current
+          Lifecycle.current = invocation
+          begin
+            result = super
+            invocation.finish_result(result)
+            result
+          rescue Exception => e # Record Interrupt and SystemExit before reraising.
+            invocation.finish_exception(e)
+            raise
+          ensure
+            invocation.close
+            Lifecycle.current = previous
+          end
+        end
+        private :execute_runners
+      end
+
+      # Prepended to RuboCop::Runner: participates only in an active selected
+      # invocation, constructs the configured native formatter set early and
+      # records the runner's existing abort state.
+      # @rbs module-self RuboCop::Runner
+      module RunnerHook
+        #: [T] (*untyped args) { (*untyped) -> T } -> T
+        def run(*args, &block)
+          invocation = Lifecycle.current
+          return super unless invocation
+
+          native_set = nil
+          begin
+            native_set = formatter_set
+            invocation.attach
+            super
+          ensure
+            invocation.cleanup_native(native_set) if native_set
+            invocation.capture_runner(self)
+          end
+        end
+      end
+
+      class << self
+        # @rbs @installed: bool
+
+        #: () -> void
+        def install!
+          return if @installed
+
+          @installed = true
+          RuboCop::CLI.prepend(CLIHook) if defined?(RuboCop::CLI)
+          RuboCop::Runner.prepend(RunnerHook) if defined?(RuboCop::Runner)
+          nil
+        end
+
+        #: () -> Invocation?
+        def current
+          Thread.current[THREAD_KEY]
+        end
+
+        #: (Invocation?) -> Invocation?
+        def current=(invocation)
+          Thread.current[THREAD_KEY] = invocation
+        end
+
+        #: (untyped cli) -> Invocation?
+        def invocation_for(cli)
+          options = cli.options
+          return nil unless options
+          return nil if NON_INSPECTION_OPTIONS.any? { |key| options.key?(key) }
+          return nil unless selected?(options[:formatters])
+
+          mode = ENV.fetch('RUBOCOP_OSC7501', 'auto')
+          return nil if mode == 'off'
+
+          Invocation.new(mode: mode)
+        end
+
+        #: (untyped formatters) -> bool
+        def selected?(formatters)
+          return false unless formatters.respond_to?(:any?)
+
+          formatters.any? do |pair|
+            type = pair.respond_to?(:first) ? pair.first : pair
+            type.equal?(Formatter) || (type.is_a?(String) && FORMATTER_NAMES.include?(type))
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/osc7501/version.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module RuboCop
+  module OSC7501
+    #: String
+    VERSION = '0.1.0'
+  end
+end

data/lib/rubocop/osc7501/writer.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module RuboCop
+  module OSC7501
+    # Encodes status records onto an output stream following the family
+    # writer contract. Private to the adapter.
+    class Writer # :nodoc: all
+      # Base64 of "RuboCop".
+      ENCODED_TITLE = ['RuboCop'].pack('m0').freeze
+
+      # @rbs @output: IO | StringIO
+      # @rbs @enabled: bool
+      # @rbs @owned: IO?
+
+      #: (IO | StringIO output, mode: String) -> void
+      def initialize(output, mode:)
+        @output = output
+        @owned = nil
+        @enabled = mode == 'force' || (mode == 'auto' && automatic_output?)
+        own_output if @enabled
+      rescue IOError, SystemCallError
+        @enabled = false
+      end
+
+      #: () -> bool
+      def enabled?
+        @enabled
+      end
+
+      #: (state: String, msg: String) -> nil
+      def emit(state:, msg:)
+        return nil unless @enabled
+
+        fields = ['app=rubocop', "title=#{ENCODED_TITLE}", "state=#{state}", "msg=#{encode(msg, 2048)}"]
+        @output.write("\e]7501;#{fields.join(':')}\e\\")
+        @output.flush if @output.respond_to?(:flush)
+        nil
+      rescue IOError, SystemCallError
+        # Reporting failures disable reporting without disturbing the command.
+        @enabled = false
+        close
+        nil
+      end
+
+      # Closes only a descriptor duplicated from an enabled File output.
+      #: () -> nil
+      def close
+        output = @owned
+        @owned = nil
+        output.close if output && !output.closed?
+        nil
+      rescue IOError, SystemCallError
+        nil
+      end
+
+      private
+
+      #: () -> void
+      def own_output
+        return unless @output.is_a?(File)
+
+        @owned = @output.dup #: IO
+        @output = @owned
+      rescue IOError, SystemCallError
+        @enabled = false
+        @owned = nil
+      end
+
+      #: () -> bool
+      def automatic_output?
+        ENV['TERM'] != 'dumb' && @output.respond_to?(:tty?) && @output.tty?
+      end
+
+      #: (String, Integer) -> String
+      def encode(text, byte_limit)
+        input = text.to_s.byteslice(0, sanitization_byte_limit(byte_limit)) #: String
+        plain = input.encode('UTF-8', invalid: :replace, undef: :replace)
+        plain = plain.gsub(/\e\[[0-9;?]*[ -\/]*[@-~]/, '')
+        plain = plain.gsub(/[\u0000-\u001F\u007F-\u009F]/, ' ')
+        clean = plain.gsub(/\s+/, ' ').strip
+        bytes = 0
+        bounded = clean.each_char.take_while do |char|
+          bytes += char.bytesize
+          bytes <= byte_limit
+        end.join
+        [bounded].pack('m0')
+      end
+
+      # Bound sanitization work with 50% headroom for removed formatting.
+      #: (Integer) -> Integer
+      def sanitization_byte_limit(output_byte_limit)
+        output_byte_limit + output_byte_limit / 2
+      end
+    end
+  end
+end

data/lib/rubocop/osc7501.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+require 'rubocop'
+require_relative 'osc7501/version'
+require_relative 'osc7501/writer'
+require_relative 'osc7501/lifecycle'
+require_relative 'osc7501/formatter'
+
+module RuboCop
+  module OSC7501
+    # Requiring this entrypoint registers the formatter and installs inert
+    # lifecycle hooks once. Only a selected supported inspection reports.
+    Lifecycle.install!
+  end
+end

data/sig/rubocop/osc7501/formatter.rbs

@@ -0,0 +1,22 @@
+# Generated from lib/rubocop/osc7501/formatter.rb with RBS::Inline
+
+module RuboCop
+  module OSC7501
+    # Native RuboCop formatter selected alongside ordinary output. It only
+    # observes callbacks; the private lifecycle owns election and outcomes.
+    class Formatter < RuboCop::Formatter::BaseFormatter
+      @invocation: Lifecycle::Invocation?
+
+      @writer: Writer?
+
+      # : (untyped output, ?untyped options) -> void
+      def initialize: (untyped output, ?untyped options) -> void
+
+      # : (untyped files) -> nil
+      def started: (untyped files) -> nil
+
+      # : (untyped file, untyped offenses) -> nil
+      def file_finished: (untyped file, untyped offenses) -> nil
+    end
+  end
+end

data/sig/rubocop/osc7501/lifecycle.rbs

@@ -0,0 +1,158 @@
+# Generated from lib/rubocop/osc7501/lifecycle.rb with RBS::Inline
+
+module RuboCop
+  class CLI
+    attr_reader options: untyped
+    def execute_runners: (*untyped args) ?{ (*untyped) -> untyped } -> untyped
+  end
+
+  class Runner
+    def run: (*untyped args) ?{ (*untyped) -> untyped } -> untyped
+    def aborting?: () -> bool
+    private
+    def formatter_set: () -> untyped
+  end
+
+  module Formatter
+    class BaseFormatter
+      attr_reader output: untyped
+      attr_reader options: untyped
+      def initialize: (untyped output, ?untyped options) -> void
+      def started: (untyped target_files) -> void
+      def file_finished: (untyped file, untyped offenses) -> void
+      def finished: (untyped inspected_files) -> void
+    end
+  end
+
+  module OSC7501
+    # Private invocation hooks and observations for supported finite direct
+    # RuboCop inspections. Require-time installation stays inert.
+    module Lifecycle
+      # Options that select a non-inspection command. These come from the
+      # native parsed options at each supported boundary version.
+      NON_INSPECTION_OPTIONS: untyped
+
+      FORMATTER_NAMES: untyped
+
+      THREAD_KEY: ::Symbol
+
+      # Owns one invocation's counters, elected reporter and final outcome.
+      class Invocation
+        @runner_aborting: bool
+
+        @last_update: Float
+
+        @closed: bool
+
+        @finished: bool
+
+        @started: bool
+
+        @offenses: Integer
+
+        @results: Integer
+
+        @total: Integer?
+
+        @reporter_writer: Writer?
+
+        @reporter: untyped?
+
+        @formatters: Array[[ untyped, Writer ]]
+
+        @clock: Proc
+
+        @mode: String
+
+        attr_reader mode: untyped
+
+        attr_reader reporter: untyped
+
+        # : (mode: String, ?clock: Proc?) -> void
+        def initialize: (mode: String, ?clock: Proc?) -> void
+
+        # Registers a selected OSC formatter in native construction order.
+        # The first formatter whose writer is enabled owns reporting.
+        # : (untyped formatter, Writer writer) -> void
+        def add_formatter: (untyped formatter, Writer writer) -> void
+
+        # Emits the initial working record after the native formatter set is
+        # available, before target discovery and old warm-cache work.
+        # : () -> nil
+        def attach: () -> nil
+
+        # : (untyped formatter, Integer total) -> nil
+        def started: (untyped formatter, Integer total) -> nil
+
+        # : (untyped formatter, untyped offenses) -> nil
+        def file_finished: (untyped formatter, untyped offenses) -> nil
+
+        # : (untyped runner) -> nil
+        def capture_runner: (untyped runner) -> nil
+
+        # : (untyped status) -> nil
+        def finish_result: (untyped status) -> nil
+
+        # : (Exception exception) -> nil
+        def finish_exception: (Exception exception) -> nil
+
+        # Closes still-open File outputs from a native formatter set that was
+        # returned successfully before a later failure escaped the runner.
+        # : (untyped formatter_set) -> nil
+        def cleanup_native: (untyped formatter_set) -> nil
+
+        # Releases every adapter-owned duplicate exactly once.
+        # : () -> nil
+        def close: () -> nil
+
+        private
+
+        # : (String) -> void
+        def emit_working: (String) -> void
+
+        # : (String, String) -> nil
+        def finish: (String, String) -> nil
+
+        # : (String) -> String
+        def outcome_message: (String) -> String
+
+        # : () -> String
+        def count_message: () -> String
+      end
+
+      # Prepended to RuboCop::CLI: owns context and finalization around the
+      # private command boundary reached after --require has loaded the gem.
+      # @rbs module-self RuboCop::CLI
+      module CLIHook : RuboCop::CLI
+        # : [T] (*untyped args) { (*untyped) -> T } -> T
+        def execute_runners: [T] (*untyped args) { (*untyped) -> T } -> T
+      end
+
+      # Prepended to RuboCop::Runner: participates only in an active selected
+      # invocation, constructs the configured native formatter set early and
+      # records the runner's existing abort state.
+      # @rbs module-self RuboCop::Runner
+      module RunnerHook : RuboCop::Runner
+        # : [T] (*untyped args) { (*untyped) -> T } -> T
+        def run: [T] (*untyped args) { (*untyped) -> T } -> T
+      end
+
+      @installed: bool
+
+      # : () -> void
+      def self.install!: () -> void
+
+      # : () -> Invocation?
+      def self.current: () -> Invocation?
+
+      # : (Invocation?) -> Invocation?
+      def self.current=: (Invocation?) -> Invocation?
+
+      # : (untyped cli) -> Invocation?
+      def self.invocation_for: (untyped cli) -> Invocation?
+
+      # : (untyped formatters) -> bool
+      def self.selected?: (untyped formatters) -> bool
+    end
+  end
+end

data/sig/rubocop/osc7501/version.rbs

@@ -0,0 +1,8 @@
+# Generated from lib/rubocop/osc7501/version.rb with RBS::Inline
+
+module RuboCop
+  module OSC7501
+    # : String
+    VERSION: ::String
+  end
+end

data/sig/rubocop/osc7501/writer.rbs

@@ -0,0 +1,46 @@
+# Generated from lib/rubocop/osc7501/writer.rb with RBS::Inline
+
+module RuboCop
+  module OSC7501
+    # Encodes status records onto an output stream following the family
+    # writer contract. Private to the adapter.
+    class Writer
+      # Base64 of "RuboCop".
+      ENCODED_TITLE: untyped
+
+      @output: IO | StringIO
+
+      @enabled: bool
+
+      @owned: IO?
+
+      # : (IO | StringIO output, mode: String) -> void
+      def initialize: (IO | StringIO output, mode: String) -> void
+
+      # : () -> bool
+      def enabled?: () -> bool
+
+      # : (state: String, msg: String) -> nil
+      def emit: (state: String, msg: String) -> nil
+
+      # Closes only a descriptor duplicated from an enabled File output.
+      # : () -> nil
+      def close: () -> nil
+
+      private
+
+      # : () -> void
+      def own_output: () -> void
+
+      # : () -> bool
+      def automatic_output?: () -> bool
+
+      # : (String, Integer) -> String
+      def encode: (String, Integer) -> String
+
+      # Bound sanitization work with 50% headroom for removed formatting.
+      # : (Integer) -> Integer
+      def sanitization_byte_limit: (Integer) -> Integer
+    end
+  end
+end

data/sig/rubocop/osc7501.rbs

@@ -0,0 +1,6 @@
+# Generated from lib/rubocop/osc7501.rb with RBS::Inline
+
+module RuboCop
+  module OSC7501
+  end
+end