bidi2pdf 0.1.13 → 0.1.15

data/sig/bidi2pdf/test_helpers/pdf_text_sanitizer.rbs

@@ -0,0 +1,38 @@
+module Bidi2pdf
+  module TestHelpers
+    # rubocop: disable-next Metrics/ModuleLength
+    module PDFTextSanitizer
+      def self.clean: (untyped text) -> untyped
+
+      def self.clean_pages: (untyped pdf) -> untyped
+
+      def self.normalize: (untyped text) -> untyped
+
+      def self.contains?: (untyped actual_pdf_thingy, untyped expected, ?untyped? page_number) -> (false | untyped)
+
+      def self.match_expected?: (untyped text, untyped expected) -> (false | untyped)
+
+      def self.match?: (untyped actual_pdf_thingy, untyped expected_pdf_thingy) -> (true | false)
+
+      def self.report_content_mismatch: (untyped actual, untyped expected) -> untyped
+
+      def self.content_mismatch_message: (untyped actual, untyped expected) -> untyped
+
+      def self.page_difference_message: (untyped actual_page, untyped expected_page, untyped page_idx) -> (nil | untyped)
+
+      def self.format_diff_output: (untyped diffs, untyped expected, untyped actual) -> untyped
+
+      def self.reporter: () -> untyped
+
+      private
+
+      def self.group_changed_diffs: (untyped diffs) -> untyped
+
+      def self.format_change: (untyped expected, untyped actual, untyped change) -> untyped
+
+      def self.extract_snippets: (untyped expected, untyped actual, untyped change, untyped pos) -> { context_start: untyped, context: untyped, expected_snip: untyped, actual_snip: untyped }
+
+      def self.build_output: (untyped snip_data, untyped pos) -> ::Array[::String]
+    end
+  end
+end

data/sig/bidi2pdf/test_helpers/spec_paths_helper.rbs

@@ -0,0 +1,35 @@
+# This module provides helper methods for managing paths in test environments.
+# It includes methods to retrieve directories and generate temporary file paths.
+module Bidi2pdf
+  module TestHelpers
+    # This submodule contains path-related helper methods and configuration for tests.
+    module SpecPathsHelper
+      # Retrieves the directory path for Docker files.
+      # @return [String] the Docker directory path
+      def fixture_dir: () -> untyped
+
+      # Retrieves the directory path for fixtures.
+      # @return [String] the fixture directory path
+      def fixture_file: (*untyped) -> untyped
+
+      # Retrieves the directory path for specs.
+      # @return [String] the spec directory path
+      def spec_dir: () -> untyped
+
+      # Retrieves the directory path for temporary files.
+      # @return [String] the temporary directory path
+      def tmp_dir: () -> untyped
+
+      # Generates a path for a temporary file by joining the temporary directory with the given parts.
+      # @param [Array<String>] parts the parts of the file path to join
+      # @return [String] the full path to the temporary file
+      def tmp_file: (*untyped parts) -> untyped
+
+      # Generates a random temporary directory path.
+      # @param [Array<String>] dirs additional directory components to include in the path
+      # @param [String, nil] prefix an optional prefix for the directory name
+      # @return [String] the full path to the random temporary directory
+      def random_tmp_dir: (*untyped dirs, ?prefix: untyped?) -> untyped
+    end
+  end
+end

data/sig/bidi2pdf/test_helpers/testcontainers/chromedriver_container.rbs

@@ -0,0 +1,43 @@
+module Bidi2pdf
+  module TestHelpers
+    module Testcontainers
+      class ChromedriverContainer < ::Testcontainers::DockerContainer
+        @docker_file: untyped
+
+        @build_dir: untyped
+
+        @wait_for: untyped
+
+        @_container: untyped
+
+        @_id: untyped
+
+        @name: untyped
+
+        @_created_at: untyped
+
+        DEFAULT_CHROMEDRIVER_PORT: 3000
+
+        DEFAULT_IMAGE: "dieters877565/chromedriver"
+
+        attr_reader docker_file: untyped
+
+        attr_reader build_dir: untyped
+
+        def initialize: (?untyped image, **untyped options) -> void
+
+        def start: () -> untyped
+
+        def port: () -> untyped
+
+        # rubocop: disable Metrics/AbcSize
+        def build_local_image: () -> untyped
+
+        # rubocop: disable Metrics/AbcSize
+        def start_local_image: () -> untyped
+
+        def session_url: (?protocol: ::String) -> untyped
+      end
+    end
+  end
+end

data/sig/bidi2pdf/test_helpers/testcontainers/chromedriver_test_helper.rbs

@@ -0,0 +1,45 @@
+module Bidi2pdf
+  module TestHelpers
+    module Testcontainers
+      module ChromedriverTestHelper
+        def session_url: () -> untyped
+
+        def chromedriver_container: () -> untyped
+      end
+
+      module SessionTestHelper
+        def reporter: () -> untyped
+
+        def chrome_args: () -> untyped
+
+        def create_session: (untyped session_url) -> untyped
+
+        # Full session/tab lifecycle in one call - create_session above only builds the session
+        # object, it never starts or closes it, and there is no after(:each) teardown for a spec
+        # that uses it directly. Mirrors Bidi2pdf::DSL.with_tab's own ensure-based teardown, but
+        # against a session_url this module already knows about (a long-lived remote-chrome
+        # reached over `session:` metadata, not a freshly spawned local chromedriver per call).
+        def with_tab: (untyped session_url) { (untyped) -> untyped } -> untyped
+      end
+    end
+  end
+end
+
+# alias the long class name
+ChromedriverTestcontainer: untyped
+
+class Object
+  def stop_container: (untyped container) -> (nil | untyped)
+
+  def dump_container_logs: (untyped container) -> (nil | untyped)
+
+  def stop_running_container: (untyped container) -> (nil | untyped)
+
+  def reporter: () -> untyped
+
+  def chromedriver_tests_present?: () -> untyped
+
+  def test_of_kind_present?: (untyped type) -> untyped
+
+  def start_chromedriver_container: (build_dir: untyped, mounts: untyped, shared_network: untyped, ?chromedriver_log_level: ::String) -> untyped
+end

data/sig/bidi2pdf/test_helpers/testcontainers/container_endpoint.rbs

@@ -0,0 +1,25 @@
+module Bidi2pdf
+  module TestHelpers
+    module Testcontainers
+      # Builds a URL for reaching a container's published port from the test
+      # process, using the container's own host/port resolution.
+      class ContainerEndpoint
+        @container: untyped
+
+        @port: untyped
+
+        def initialize: (untyped container, untyped port) -> void
+
+        def url: (?scheme: ::String, ?path: ::String) -> ::String
+
+        # Address reachable from another container on the same Docker network (e.g. remote-chrome
+        # reaching nginx), by alias and internal port - as opposed to #url's host-accessible,
+        # externally-mapped port. Uses the same @port this instance was built with, not a
+        # container_ports.first guess: the two methods must agree on which port they're both
+        # describing for the same container, or a caller comparing #url and #alias_url for what's
+        # meant to be the same endpoint could silently get two different services.
+        def alias_url: (?scheme: ::String, ?path: ::String) -> ::String
+      end
+    end
+  end
+end

data/sig/bidi2pdf/test_helpers/testcontainers/shared_docker_network.rbs

@@ -0,0 +1,3 @@
+class Object
+  def reporter: () -> untyped
+end

data/sig/bidi2pdf/test_helpers/testcontainers/testcontainers_refinement.rbs

@@ -0,0 +1,47 @@
+module Bidi2pdf
+  module TestHelpers
+    module TestcontainersRefinement
+      @aliases: untyped
+
+      @_network: untyped
+
+      def id: () -> untyped
+
+      def aliases: () -> untyped
+
+      def aliases=: (untyped aliases) -> untyped
+
+      def network: () -> untyped
+
+      def with_network: (untyped network) -> self
+
+      def with_network_aliases: (*untyped aliases) -> self
+
+      def container_json: () -> untyped
+
+      # Address of the Docker host at which this container's *mapped* ports
+      # are reachable from the test process.
+      #
+      # Resolution belongs to testcontainers: it honours TC_HOST, a tcp:/ssh:
+      # DOCKER_HOST, a native local daemon, and a sibling container reaching
+      # the daemon over the bridge gateway — and it derives #mapped_port from
+      # the same decision, so the two must stay on one path. We only add a
+      # fallback for the cases 0.2.0 leaves unresolved.
+      #
+      # This is not the address containers use to reach each other; for that
+      # the helpers join a shared network and address containers by alias.
+      def accessible_host: () -> untyped
+
+      # testcontainers-core 0.2.0 cannot resolve a host when the test process
+      # runs inside a container and the container under test is on a custom
+      # network: #container_gateway_ip hardcodes the "bridge" network key
+      # (docker_container.rb:1074), so #host returns nil. On the default
+      # bridge it can instead reach docker_container.rb:703, which calls an
+      # undefined `bridge_ip`. Both are fixed on testcontainers-ruby main;
+      # treat either as "unresolved" and fall back.
+      def resolved_host: () -> untyped
+
+      def _container_create_options: () -> untyped
+    end
+  end
+end

data/sig/bidi2pdf/test_helpers/testcontainers.rbs

@@ -0,0 +1,6 @@
+module Bidi2pdf
+  module TestHelpers
+    module Testcontainers
+    end
+  end
+end

data/sig/bidi2pdf/verbose_logger.rbs

@@ -0,0 +1,37 @@
+module Bidi2pdf
+  class VerboseLogger < SimpleDelegator
+    @logger: untyped
+
+    @verbosity: untyped
+
+    VERBOSITY_LEVELS: { none: 0, low: 1, medium: 2, high: 3 }
+
+    attr_reader logger: untyped
+
+    attr_reader verbosity: untyped
+
+    def initialize: (untyped logger, ?::Symbol verbosity) -> void
+
+    def verbosity=: (untyped verbosity) -> untyped
+
+    def verbosity_sym: () -> untyped
+
+    def debug1: (?untyped? progname) { (?) -> untyped } -> (nil | untyped)
+
+    def debug1?: () -> untyped
+
+    def debug1!: () -> untyped
+
+    def debug2: (?untyped? progname) { (?) -> untyped } -> (nil | untyped)
+
+    def debug2?: () -> untyped
+
+    def debug2!: () -> untyped
+
+    def debug3: (?untyped? progname) { (?) -> untyped } -> (nil | untyped)
+
+    def debug3?: () -> untyped
+
+    def debug3!: () -> untyped
+  end
+end

data/sig/bidi2pdf/version.rbs

@@ -0,0 +1,3 @@
+module Bidi2pdf
+  VERSION: "0.1.15"
+end

data/sig/bidi2pdf.rbs

@@ -1,4 +1,132 @@
 module Bidi2pdf
-  VERSION: String
-  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+  self.@logger: untyped
+
+  self.@network_events_logger: untyped
+
+  self.@browser_console_logger: untyped
+
+  self.@logging_subscriber: untyped
+
+  self.@notification_service: untyped
+
+  PAPER_FORMATS_CM: { letter: { width: ::Float, height: ::Float }, legal: { width: ::Float, height: ::Float }, tabloid: { width: ::Float, height: ::Float }, ledger: { width: ::Float, height: ::Float }, a0: { width: ::Float, height: ::Float }, a1: { width: ::Float, height: ::Float }, a2: { width: ::Float, height: ::Float }, a3: { width: ::Float, height: ::Float }, a4: { width: ::Float, height: ::Float }, a5: { width: ::Float, height: ::Float }, a6: { width: ::Float, height: ::Float } }
+
+  class Error < StandardError
+  end
+
+  class SessionNotStartedError < Error
+  end
+
+  class WebsocketError < Error
+  end
+
+  class ClientError < WebsocketError
+  end
+
+  class CmdError < ClientError
+    @cmd: untyped
+
+    @response: untyped
+
+    attr_reader cmd: untyped
+
+    attr_reader response: untyped
+
+    def initialize: (untyped cmd, untyped response) -> void
+  end
+
+  class CmdResponseNotStoredError < ClientError
+  end
+
+  class CmdTimeoutError < ClientError
+  end
+
+  class PrintError < Error
+  end
+
+  class ScreenshotError < Error
+  end
+
+  class ScriptInjectionError < Error
+  end
+
+  class StyleInjectionError < Error
+  end
+
+  class NotificationsError < Error
+    @causes: untyped
+
+    attr_reader causes: untyped
+
+    def initialize: (untyped causes) -> void
+  end
+
+  class NavigationError < Error
+  end
+
+  class NavigationAuthError < NavigationError
+    @url: untyped
+
+    attr_reader url: untyped
+
+    def initialize: (untyped url, ?untyped? message) -> void
+  end
+
+  class NavigationTimeoutError < NavigationError
+  end
+
+  class NavigationNotFoundError < NavigationError
+  end
+
+  class NavigationDNSError < NavigationError
+  end
+
+  attr_accessor self.default_timeout: untyped
+
+  attr_accessor self.enable_default_logging_subscriber: untyped
+
+  attr_accessor self.log_truncate_limit: untyped
+
+  attr_accessor self.chromedriver_log_level: untyped
+
+  attr_reader self.logging_subscriber: untyped
+
+  attr_reader self.logger: untyped
+
+  attr_reader self.network_events_logger: untyped
+
+  attr_reader self.browser_console_logger: untyped
+
+  attr_reader self.notification_service: untyped
+
+  # Allow configuration through a block
+  def self.configure: () ?{ (untyped) -> untyped } -> untyped
+
+  def self.init: () -> untyped
+
+  # Truncates a value for safe log output - a raw url/param can be a `data:` URL whose base64
+  # payload is proportional to document size, and logging it whole can be large enough to choke
+  # CI log ingestion (confirmed live: GitHub Actions' log UI stalls badly on very long single
+  # lines, reading as a hung job even though the process underneath is fine).
+  #
+  # @param [Object] value The value to truncate (converted via #to_s).
+  # @param [Integer] limit The maximum number of bytes to keep. Defaults to
+  #   +Bidi2pdf.log_truncate_limit+, itself configurable via +Bidi2pdf.configure+.
+  # @return [String] The value unchanged if short enough, otherwise a truncated prefix plus a
+  #   byte-count marker. Truncation is byte-based (not character-based), since the goal is
+  #   bounding actual log-entry size; a partial trailing multi-byte character is scrubbed rather
+  #   than left as invalid UTF-8.
+  def self.truncate_for_log: (untyped value, ?limit: untyped) -> (untyped | ::String)
+
+  def self.translate_paper_format: (untyped format) -> { width: untyped, height: untyped }
+
+  def self.logger=: (untyped new_logger) -> untyped
+
+  def self.network_events_logger=: (untyped new_network_events_logger) -> untyped
+
+  def self.browser_console_logger=: (untyped new_browser_console_logger) -> untyped
+
+  def self.logging_subscriber=: (untyped new_logging_subscriber) -> untyped
+
+  def self.notification_service=: (untyped new_notification_service) -> untyped
 end

data/tasks/generate_rbs.rake

@@ -6,7 +6,7 @@ require "rbs"
 SOURCE_DIR = "lib"
 OUTPUT_DIR = "sig"
 
-# rubocop:disable  Metrics/BlockLength
+# rubocop:disable-next  Metrics/BlockLength
 namespace :rbs do
   file_list = FileList["#{SOURCE_DIR}/**/*.rb"]
 
@@ -32,15 +32,11 @@ namespace :rbs do
         parser = RBS::Prototype::RB.new
         parser.parse input.read
 
-        if output.file?
-          puts "⚠️  RBS file already exists: #{rbs_path}"
-        else
-          puts "📝 Writing RBS file: #{rbs_path}"
+        puts "📝 Writing RBS file: #{rbs_path}"
 
-          output.open("w") do |io|
-            writer = RBS::Writer.new(out: io)
-            writer.write(parser.decls)
-          end
+        output.open("w") do |io|
+          writer = RBS::Writer.new(out: io)
+          writer.write(parser.decls)
         end
       rescue StandardError => e
         puts "❌ Error generating RBS for #{rb_path}: #{e.message}"
@@ -55,10 +51,14 @@ namespace :rbs do
 
   desc "Clean all generated RBS files"
   task :clean_rbs do
-    FileList["#{OUTPUT_DIR}/**/*.rbs"].each do |file|
+    # sig/vendor/** holds hand-written signatures for third-party gems (e.g. Thor) with no
+    # corresponding lib/ source to regenerate from - excluded so a clean+regenerate cycle can't
+    # delete them with no way to get them back.
+    generated = FileList["#{OUTPUT_DIR}/**/*.rbs"].exclude("#{OUTPUT_DIR}/vendor/**")
+
+    generated.each do |file|
       FileUtils.rm_f(file)
     end
     puts "🧹 Cleaned up all RBS files"
   end
 end
-# rubocop:enable Metrics/BlockLength

data/tasks/release_credentials_check.rake

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+# Works out which rubygems.org credential `rake release` would really push with, and refuses to go on
+# when that is not what the repo's configuration says it should be.
+module ReleaseCredentialsCheck
+  BUNDLE_CONFIG_PATH = ".bundle/config"
+  CREDENTIALS_PATH = File.expand_path("~/.gem/credentials")
+
+  module_function
+
+  # Ask Bundler, exactly as its own release task does (gem_helper.rb: Bundler.settings["gem.push_key"])
+  # - never parse .bundle/config for this. Bundler may not be reading that file at all: the official
+  # ruby Docker images set BUNDLE_APP_CONFIG=/usr/local/bundle, which silently replaces the repo's
+  # .bundle/ as the app config dir. Reading the file directly made this check report a key that
+  # `rake release` then did not use.
+  def effective_key
+    Bundler.settings["gem.push_key"]&.to_s&.downcase
+  end
+
+  # What the repo's own .bundle/config asks for - only ever compared against #effective_key.
+  def key_on_disk
+    return unless File.exist?(BUNDLE_CONFIG_PATH)
+
+    (YAML.load_file(BUNDLE_CONFIG_PATH) || {})["BUNDLE_GEM__PUSH_KEY"]&.to_s&.downcase
+  end
+
+  def available_keys
+    File.exist?(CREDENTIALS_PATH) ? (YAML.load_file(CREDENTIALS_PATH) || {}).keys.map(&:to_s) : []
+  end
+
+  # Always printed first, in one stream (puts only - mixing in `warn`'s stderr made lines print out
+  # of order once a terminal merges the two streams), so the context stays visible above whichever
+  # message stops the release.
+  def print_banner(key, keys)
+    puts "=== rubygems.org push credentials ==="
+    puts "  gem.push_key Bundler will use: #{key || "(not set)"}"
+    puts "  Bundler app config dir:        #{Bundler.app_config_path}#{" (from BUNDLE_APP_CONFIG)" if ENV["BUNDLE_APP_CONFIG"]}"
+    puts "  ~/.gem/credentials keys:       #{keys.empty? ? "(none found)" : keys.join(", ")}"
+    puts "======================================"
+  end
+
+  # @return [String, nil] why the release must not go on, or nil when it may
+  def problem(key, keys)
+    ignored_config_problem(key) || credentials_problem(key, keys)
+  end
+
+  def ignored_config_problem(key)
+    wanted = key_on_disk
+    return if wanted.nil? || wanted == key
+
+    "#{BUNDLE_CONFIG_PATH} sets gem.push_key '#{wanted}', but Bundler is not reading that file " \
+      "(app config dir: #{Bundler.app_config_path}) and would push with '#{key || "the default rubygems_api_key"}'. " \
+      "Set BUNDLE_GEM__PUSH_KEY=#{wanted} in the environment, or unset BUNDLE_APP_CONFIG."
+  end
+
+  def credentials_problem(key, keys)
+    return "~/.gem/credentials has no keys at all (missing, empty, or not mounted)." if keys.empty?
+    return "configured key '#{key}' is not among ~/.gem/credentials' keys #{keys.inspect}." if key && !keys.include?(key)
+    return if key || keys.include?("rubygems_api_key")
+
+    "no gem.push_key configured and ~/.gem/credentials has no default 'rubygems_api_key' key (found: #{keys.inspect})."
+  end
+end
+
+desc "Show which rubygems.org credential key `rake release`/`gem push` will use"
+task :release_credentials_check do
+  # Without this, stdout is buffered (not a TTY once piped/captured) while stderr isn't - so
+  # `abort`'s message below can reach the terminal before the `puts` lines that logically ran
+  # first, once the two streams get merged. Confirmed live: without sync, "release aborted: ..."
+  # printed above the diagnostic banner, not after it.
+  $stdout.sync = true
+
+  key = ReleaseCredentialsCheck.effective_key
+  keys = ReleaseCredentialsCheck.available_keys
+  ReleaseCredentialsCheck.print_banner(key, keys)
+
+  problem = ReleaseCredentialsCheck.problem(key, keys)
+  abort "release aborted: #{problem}" if problem
+
+  puts "NOTE: no gem.push_key configured - this will push using the default :rubygems_api_key." if key.nil?
+end
+
+# A prerequisite of "release:rubygem_push" specifically, not the outer "release" task. Bundler's
+# own gem_helper.rb defines release as depending on
+# ["build", "release:guard_clean", "release:source_control_push", "release:rubygem_push"], run in
+# that listed order, with release:rubygem_push's own action being the actual `rubygem_push(...)`
+# call that consumes this credential - attaching to the outer "release" task instead would append
+# here via Task#enhance's simple union, running this *after* every one of those, including the
+# push itself, which would make it a report on a mistake already made, not a guard against one.
+# Attaching to "release:rubygem_push" guarantees Rake resolves this before *that* task's own
+# action runs, regardless of how bundler orders its other prerequisites in some other version -
+# automatically, regardless of how `rake release` gets invoked (this Makefile's release-shell, a
+# bare host checkout, CI), not something you have to remember to check with a separate command.
+desc "Push the built gem to rubygems.org (checks credentials first)"
+task "release:rubygem_push" => :release_credentials_check