asciidoctor-latexmath 1.0.0.pre.dev.1 → 2.0.0

data/lib/asciidoctor/latexmath/rendering/tool_detector.rb

@@ -0,0 +1,320 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Shuai Zhang
+#
+# SPDX-License-Identifier: LGPL-3.0-or-later WITH LGPL-3.0-linking-exception
+
+require "asciidoctor"
+require "shellwords"
+
+require_relative "toolchain_record"
+require_relative "../../latexmath/errors"
+
+module Asciidoctor
+  module Latexmath
+    module Rendering
+      class ToolDetector
+        SVG_PRIORITY = %i[dvisvgm pdf2svg].freeze
+        PNG_PRIORITY = %i[pdftoppm magick gs].freeze
+        SUMMARY_IDENTIFIERS = (SVG_PRIORITY + %i[pdflatex xelatex lualatex tectonic] + PNG_PRIORITY).freeze
+
+        def initialize(request, raw_attributes)
+          @request = request
+          @raw_attributes = raw_attributes || {}
+          @tool_presence_map = {}
+          @svg_log_emitted = false
+        end
+
+        def emit_tool_summary
+          self.class.emit_summary_once do
+            summary = SUMMARY_IDENTIFIERS.map do |identifier|
+              record = summary_record(identifier)
+              "#{identifier}=#{record.available ? "ok" : "missing"}"
+            end.join(" ")
+            Asciidoctor::LoggerManager.logger&.info { "latexmath.tools: #{summary}" }
+          end
+        end
+
+        def ensure_svg_tool!
+          return nil unless request.format == :svg
+
+          record = detect_svg_tool
+          log_svg_tool_selection(record)
+          return record if record.available
+
+          message = missing_tool_message(
+            "SVG",
+            record,
+            SVG_PRIORITY,
+            fallback_formats: "pdf|png",
+            attribute: ":latexmath-pdf2svg:"
+          )
+          raise MissingToolError.new(record.id, message)
+        end
+
+        def ensure_png_tool!
+          return nil unless request.format == :png
+
+          record = detect_png_tool
+          return record if record.available
+
+          message = missing_tool_message(
+            "PNG",
+            record,
+            PNG_PRIORITY,
+            fallback_formats: "svg|pdf",
+            attribute: ":latexmath-pdftoppm:"
+          )
+          raise MissingToolError.new(record.id, message)
+        end
+
+        def record_engine(command)
+          return if command.nil?
+
+          id = canonical_engine_id(command)
+          tool_presence_map[id] = true
+        end
+
+        def tool_presence
+          tool_presence_map.transform_keys(&:to_s)
+        end
+
+        private
+
+        attr_reader :request
+        attr_reader :raw_attributes
+        attr_reader :tool_presence_map
+
+        def log_svg_tool_selection(record)
+          return if @svg_log_emitted
+
+          selected = record&.available ? record.id.to_s : "missing"
+          Asciidoctor::LoggerManager.logger&.info { "latexmath.svg.tool=#{selected}" }
+          @svg_log_emitted = true
+        end
+
+        def detect_svg_tool
+          if (explicit = explicit_svg_path)
+            id = infer_identifier(request.tool_overrides[:svg] || :pdf2svg, SVG_PRIORITY)
+            available = executable_file?(explicit)
+            return remember_record(ToolchainRecord.new(id: id, available: available, path: explicit))
+          end
+
+          override = request.tool_overrides[:svg]
+          if override
+            record = resolve_override(override, SVG_PRIORITY)
+            return remember_record(record)
+          end
+
+          records = SVG_PRIORITY.map { |candidate| remember_record(memoized_lookup(candidate)) }
+          records.find(&:available) || records.first
+        end
+
+        def detect_png_tool
+          if (explicit = explicit_png_path)
+            id = infer_identifier(request.tool_overrides[:png] || :pdftoppm, PNG_PRIORITY)
+            available = executable_file?(explicit)
+            return remember_record(ToolchainRecord.new(id: id, available: available, path: explicit))
+          end
+
+          override = request.tool_overrides[:png]
+          if override
+            record = resolve_override(override, PNG_PRIORITY)
+            return remember_record(record)
+          end
+
+          records = PNG_PRIORITY.map { |candidate| remember_record(memoized_lookup(candidate)) }
+          records.find(&:available) || records.first
+        end
+
+        def detect_with_priority(priority)
+          priority.each do |candidate|
+            record = memoized_lookup(candidate)
+            return record if record.available
+          end
+
+          memoized_lookup(priority.first)
+        end
+
+        def resolve_override(value, priority)
+          return nil if value.nil? || value.to_s.strip.empty?
+
+          candidate = value.to_s.strip
+          id = infer_identifier(candidate, priority)
+
+          if File.exist?(candidate)
+            available = File.executable?(candidate)
+            return remember_record(ToolchainRecord.new(id: id, available: available, path: candidate))
+          end
+
+          record = memoized_lookup(id, candidate)
+          return remember_record(record) if record.available
+
+          remember_record(ToolchainRecord.new(id: id, available: false, path: candidate))
+        end
+
+        def infer_identifier(candidate, priority)
+          symbol = candidate.respond_to?(:to_sym) ? candidate.to_sym : candidate
+          normalized = symbol.to_s.downcase
+          explicit = normalized.gsub(/[^a-z0-9]+/, "_").to_sym
+          return explicit if priority.include?(explicit)
+
+          if File.exist?(candidate)
+            basename = File.basename(candidate)
+            inferred = basename.downcase.gsub(/[^a-z0-9]+/, "_").to_sym
+            return inferred if priority.include?(inferred)
+            return inferred
+          end
+
+          explicit
+        end
+
+        def memoized_lookup(identifier, override_command = nil)
+          command = override_command || identifier.to_s
+          self.class.lookup(identifier, command) do
+            path = find_executable(command)
+            if override_command
+              ToolchainRecord.new(id: identifier, available: !path.nil?, path: path)
+            else
+              ToolchainRecord.new(id: identifier, available: true, path: path || command)
+            end
+          end
+        end
+
+        def find_executable(command)
+          return command if executable_file?(command)
+
+          path_extensions = if Gem.win_platform?
+            ENV.fetch("PATHEXT", ".COM;.EXE;.BAT;.CMD;.VBS;.VBE;.JS;.JSE;.WSF;.WSH;.MSC").split(";")
+          else
+            [""]
+          end
+
+          ENV.fetch("PATH", "").split(File::PATH_SEPARATOR).each do |dir|
+            path_extensions.each do |ext|
+              candidate = File.join(dir, ext.empty? ? command : "#{command}#{ext}")
+              return candidate if executable_file?(candidate)
+            end
+          end
+
+          nil
+        end
+
+        def executable_file?(path)
+          File.exist?(path) && File.executable?(path) && !File.directory?(path)
+        end
+
+        def explicit_svg_path
+          override = request.tool_overrides[:svg_path]
+          return override if override && !override.to_s.strip.empty?
+
+          extract_path("latexmath-pdf2svg")
+        end
+
+        def explicit_png_path
+          override = request.tool_overrides[:png_path]
+          return override if override && !override.to_s.strip.empty?
+
+          extract_path("latexmath-pdftoppm")
+        end
+
+        def extract_path(key)
+          value = raw_attributes[key]
+          return nil if value.nil?
+
+          stripped = value.to_s.strip
+          stripped.empty? ? nil : stripped
+        end
+
+        def svg_candidates
+          override = request.tool_overrides[:svg]
+          return [override.to_s.strip].reject(&:empty?) unless override.nil? || override.to_s.strip.empty?
+
+          SVG_PRIORITY.map(&:to_s)
+        end
+
+        def png_candidates
+          override = request.tool_overrides[:png]
+          return [override.to_s.strip].reject(&:empty?) unless override.nil? || override.to_s.strip.empty?
+
+          PNG_PRIORITY.map(&:to_s)
+        end
+
+        def missing_tool_message(kind, record, priority, fallback_formats:, attribute:)
+          tried = if priority.include?(record.id)
+            priority.map(&:to_s)
+          else
+            ([record.id.to_s] + priority.map(&:to_s)).uniq
+          end
+
+          base = "Required #{kind} conversion tool not available. Tried: #{tried.join(", ")}. Configure #{attribute} with an executable path or install one of the supported tools."
+
+          preferred = record.id.to_s
+          alternates = (priority.map(&:to_s) - [preferred]).uniq
+          alt_hint = if alternates.empty?
+            "install #{preferred} (preferred)"
+          else
+            available_alternates = alternates.select { |name| tool_presence_map[name.to_sym] }
+            if available_alternates.any?
+              "install #{preferred} (preferred) or keep using #{available_alternates.join("/")}"
+            else
+              "install #{preferred} (preferred) or install #{alternates.join("/")}"
+            end
+          end
+
+          hints = [alt_hint, "set :latexmath-format: #{fallback_formats}"]
+          "#{base}\nhint: #{hints.join("; ")}"
+        end
+
+        def remember_record(record)
+          return record unless record
+
+          tool_presence_map[record.id] = record.available
+          record
+        end
+
+        def summary_record(identifier)
+          command = identifier.to_s
+          self.class.lookup(identifier, command) do
+            path = find_executable(command)
+            ToolchainRecord.new(id: identifier, available: !path.nil?, path: path || command)
+          end
+        end
+
+        def canonical_engine_id(command)
+          first = Shellwords.shellsplit(command.to_s).first
+          return :pdflatex unless first
+
+          first.downcase.gsub(/[^a-z0-9]+/, "_").to_sym
+        rescue ArgumentError
+          :pdflatex
+        end
+
+        class << self
+          def lookup(identifier, command)
+            @cache ||= {}
+            key = [identifier, command]
+            cached = @cache[key]
+            return cached if cached
+
+            record = yield
+            @cache[key] = record
+            record
+          end
+
+          def reset!
+            @cache = {}
+            @summary_emitted = false
+          end
+
+          def emit_summary_once
+            return if @summary_emitted
+
+            yield
+            @summary_emitted = true
+          end
+        end
+      end
+    end
+  end
+end

data/lib/asciidoctor/latexmath/rendering/toolchain_record.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Shuai Zhang
+#
+# SPDX-License-Identifier: LGPL-3.0-or-later WITH LGPL-3.0-linking-exception
+
+module Asciidoctor
+  module Latexmath
+    module Rendering
+      class ToolchainRecord
+        attr_reader :id, :available, :path
+
+        def initialize(id:, available:, path: nil)
+          @id = id
+          @available = available
+          @path = path
+        end
+      end
+    end
+  end
+end

data/lib/asciidoctor/latexmath/statistics/collector.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Shuai Zhang
+#
+# SPDX-License-Identifier: LGPL-3.0-or-later WITH LGPL-3.0-linking-exception
+
+module Asciidoctor
+  module Latexmath
+    module Statistics
+      class Collector
+        def initialize
+          @render_durations = []
+          @hit_durations = []
+        end
+
+        def record_render(duration_ms)
+          @render_durations << duration_ms
+        end
+
+        def record_hit(duration_ms)
+          @hit_durations << duration_ms
+        end
+
+        def to_line
+          return nil if @render_durations.empty? && @hit_durations.empty?
+
+          format(
+            "latexmath stats: renders=%<renders>d cache_hits=%<hits>d avg_render_ms=%<avg_render>d avg_hit_ms=%<avg_hit>d",
+            renders: @render_durations.size,
+            hits: @hit_durations.size,
+            avg_render: average(@render_durations),
+            avg_hit: average(@hit_durations)
+          )
+        end
+
+        private
+
+        def average(values)
+          return 0 if values.empty?
+
+          sum = values.sum
+          (sum.to_f / values.size).round(0, half: :up)
+        end
+      end
+    end
+  end
+end

data/lib/asciidoctor/latexmath/support/conflict_registry.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Shuai Zhang
+#
+# SPDX-License-Identifier: LGPL-3.0-or-later WITH LGPL-3.0-linking-exception
+
+require_relative "../errors"
+
+module Asciidoctor
+  module Latexmath
+    module Support
+      class ConflictRegistry
+        Entry = Struct.new(:signature, :details)
+
+        def initialize
+          @entries = {}
+        end
+
+        def register!(basename, signature, details)
+          normalized = normalize_details(details)
+          entry = entries[basename]
+          if entry
+            return if entry.signature == signature
+
+            raise TargetConflictError, conflict_message(basename, entry, normalized, signature)
+          end
+
+          entries[basename] = Entry.new(signature, normalized)
+        end
+
+        private
+
+        attr_reader :entries
+
+        def normalize_details(details)
+          {
+            location: details[:location] || "unknown location",
+            format: (details[:format] || "unknown").to_s,
+            content_hash: (details[:content_hash] || "").to_s,
+            preamble_hash: (details[:preamble_hash] || "").to_s,
+            fontsize_hash: (details[:fontsize_hash] || "").to_s,
+            entry_type: (details[:entry_type] || "unknown").to_s
+          }
+        end
+
+        def conflict_message(basename, existing_entry, incoming_details, incoming_signature)
+          existing_details = existing_entry.details
+          <<~MSG.strip
+            conflicting target '#{basename}' already defined at #{existing_details[:location]} (signature #{signature_summary(existing_entry.signature, existing_details)}).
+            new definition from #{incoming_details[:location]} would produce signature #{signature_summary(incoming_signature, incoming_details)}.
+            hint: choose a unique target basename or remove the explicit target attribute.
+          MSG
+        end
+
+        def signature_summary(signature, details)
+          parts = []
+          parts << "key=#{signature.to_s[0, 12]}" if signature
+          parts << "format=#{details[:format]}"
+          parts << "content=#{truncate(details[:content_hash])}"
+          parts << "preamble=#{truncate(details[:preamble_hash])}"
+          parts << "fontsize=#{truncate(details[:fontsize_hash])}"
+          parts << "entry=#{details[:entry_type]}"
+          parts.join(" ")
+        end
+
+        def truncate(value)
+          text = value.to_s
+          return "-" if text.empty?
+
+          text[0, 12]
+        end
+      end
+    end
+  end
+end

data/lib/{asciidoctor-latexmath → asciidoctor/latexmath}/version.rb

@@ -6,6 +6,6 @@
 
 module Asciidoctor
   module Latexmath
-    VERSION = "1.0.0-dev.1"
+    VERSION = "2.0.0"
   end
 end

data/lib/asciidoctor-latexmath.rb

@@ -4,9 +4,99 @@
 #
 # SPDX-License-Identifier: LGPL-3.0-or-later WITH LGPL-3.0-linking-exception
 
-require_relative "asciidoctor-latexmath/version"
-require_relative "asciidoctor-latexmath/treeprocessor"
+require "asciidoctor"
+require "asciidoctor/extensions"
+require_relative "asciidoctor/latexmath/version"
+require_relative "asciidoctor/latexmath/processors/block_processor"
+require_relative "asciidoctor/latexmath/processors/inline_macro_processor"
+require_relative "asciidoctor/latexmath/processors/statistics_postprocessor"
+require_relative "asciidoctor/latexmath/converters/html5"
+
+module Asciidoctor
+  module Latexmath
+    class << self
+      def register(registry = ::Asciidoctor::Extensions)
+        block_extension = registry.block Processors::BlockProcessor
+        inline_extension = registry.inline_macro Processors::InlineMacroProcessor
+        ensure_processor_collection!(registry, :@block_processors, :latexmath, block_extension)
+        ensure_processor_collection!(registry, :@inline_macros, :latexmath, inline_extension)
+        registry.postprocessor Processors::StatisticsPostprocessor
+
+        ensure_aliases!(registry)
+        ensure_empty_collection!(registry, :@block_macros, {})
+        ensure_empty_collection!(registry, :@tree_processors, [])
+        ensure_empty_collection!(registry, :@tree_processor_extensions, [])
+
+        registry
+      end
+
+      def reset_render_counters!
+        @render_invocations = 0
+      end
+
+      def record_render_invocation!
+        @render_invocations = render_invocations + 1
+      end
+
+      def render_invocations
+        @render_invocations ||= 0
+      end
+
+      private
+
+      def ensure_processor_collection!(registry, ivar, canonical_name, extension)
+        collection = registry.instance_variable_get(ivar)
+        unless collection
+          collection = {}
+          registry.instance_variable_set(ivar, collection)
+        end
+
+        canonical_name = canonical_name.to_sym
+        collection[canonical_name] ||= []
+        unless collection[canonical_name].include?(extension)
+          collection[canonical_name] << extension
+        end
+
+        collection
+      end
+
+      def ensure_aliases!(registry)
+        ensure_collection_alias!(registry.instance_variable_get(:@block_extensions), :latexmath, :stem)
+        ensure_collection_alias!(registry.instance_variable_get(:@inline_macro_extensions), :latexmath, :stem)
+        ensure_collection_alias!(registry.instance_variable_get(:@block_processors), :latexmath, :stem)
+        ensure_collection_alias!(registry.instance_variable_get(:@inline_macros), :latexmath, :stem)
+      end
+
+      def ensure_collection_alias!(collection, canonical_name, alias_name)
+        return unless collection
+        canonical_name = canonical_name.to_sym
+        alias_name = alias_name&.to_sym
+        return unless alias_name
+
+        existing_default = collection.default_proc
+
+        collection.default_proc = lambda do |hash, key|
+          key_sym = key.to_sym
+          if key_sym == alias_name
+            hash[canonical_name]
+          elsif existing_default
+            existing_default.call(hash, key)
+          end
+        end
+      end
+
+      def ensure_empty_collection!(registry, ivar, empty_value)
+        value = registry.instance_variable_get(ivar)
+        if value.nil?
+          registry.instance_variable_set(ivar, empty_value.dup)
+        else
+          value
+        end
+      end
+    end
+  end
+end
 
 Asciidoctor::Extensions.register do
-  treeprocessor Asciidoctor::Latexmath::Treeprocessor
+  Asciidoctor::Latexmath.register(self)
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: asciidoctor-latexmath
 version: !ruby/object:Gem::Version
-  version: 1.0.0.pre.dev.1
+  version: 2.0.0
 platform: ruby
 authors:
 - Shuai Zhang
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-09-28 00:00:00.000000000 Z
+date: 2025-10-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: asciidoctor
@@ -83,17 +83,39 @@ files:
 - LICENSE
 - README.md
 - lib/asciidoctor-latexmath.rb
-- lib/asciidoctor-latexmath/renderer.rb
-- lib/asciidoctor-latexmath/treeprocessor.rb
-- lib/asciidoctor-latexmath/version.rb
-homepage: https://github.com/hcoona/asciidoctor-latexmath
+- lib/asciidoctor/latexmath/attribute_resolver.rb
+- lib/asciidoctor/latexmath/cache/cache_entry.rb
+- lib/asciidoctor/latexmath/cache/cache_key.rb
+- lib/asciidoctor/latexmath/cache/disk_cache.rb
+- lib/asciidoctor/latexmath/command_runner.rb
+- lib/asciidoctor/latexmath/converters/html5.rb
+- lib/asciidoctor/latexmath/errors.rb
+- lib/asciidoctor/latexmath/html_builder.rb
+- lib/asciidoctor/latexmath/math_expression.rb
+- lib/asciidoctor/latexmath/path_utils.rb
+- lib/asciidoctor/latexmath/processors/block_processor.rb
+- lib/asciidoctor/latexmath/processors/inline_macro_processor.rb
+- lib/asciidoctor/latexmath/processors/statistics_postprocessor.rb
+- lib/asciidoctor/latexmath/render_request.rb
+- lib/asciidoctor/latexmath/renderer_service.rb
+- lib/asciidoctor/latexmath/rendering/pdf_to_png_renderer.rb
+- lib/asciidoctor/latexmath/rendering/pdf_to_svg_renderer.rb
+- lib/asciidoctor/latexmath/rendering/pdflatex_renderer.rb
+- lib/asciidoctor/latexmath/rendering/pipeline.rb
+- lib/asciidoctor/latexmath/rendering/renderer.rb
+- lib/asciidoctor/latexmath/rendering/tool_detector.rb
+- lib/asciidoctor/latexmath/rendering/toolchain_record.rb
+- lib/asciidoctor/latexmath/statistics/collector.rb
+- lib/asciidoctor/latexmath/support/conflict_registry.rb
+- lib/asciidoctor/latexmath/version.rb
+homepage: https://github.com/hcoona/asciidoctor-latexmath#readme
 licenses:
 - LGPL-3.0-or-later WITH LGPL-3.0-linking-exception
 metadata:
-  homepage_uri: https://github.com/hcoona/asciidoctor-latexmath
+  homepage_uri: https://github.com/hcoona/asciidoctor-latexmath#readme
   source_code_uri: https://github.com/hcoona/asciidoctor-latexmath
   bug_tracker_uri: https://github.com/hcoona/asciidoctor-latexmath/issues
-  documentation_uri: https://github.com/hcoona/asciidoctor-latexmath#readme
+  documentation_uri: https://github.com/hcoona/asciidoctor-latexmath/blob/main/README.md
 post_install_message:
 rdoc_options: []
 require_paths:
@@ -102,14 +124,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: '3.2'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">"
+  - - ">="
     - !ruby/object:Gem::Version
-      version: 1.3.1
+      version: '0'
 requirements: []
-rubygems_version: 3.4.20
+rubygems_version: 3.5.22
 signing_key:
 specification_version: 4
 summary: Offline latexmath rendering for Asciidoctor.