metanorma-plugin-plantuml 1.0.14 → 1.0.15

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 76a24adfb562fe1a39ccb67f4544884e11249e781d1c018cf4fba54d98c5459e
-  data.tar.gz: 165e9f1a919f0f7a51cbd929c259ef82ce5ae9e5d694a4bbd36d9cbe32a5cdda
+  metadata.gz: 2c4b579643b6072bf87b205256a322daee254f200b829539d5f972da33ac46c0
+  data.tar.gz: 3ba87fc795b42832ee26a4dce6450d83c53c5625d24e0ab17fa51cf056b60feb
 SHA512:
-  metadata.gz: b097cbd66938f606fb2d8375754aa5950d8c6e6d0fa53549d9136620c843adc4b9fc4723cb845e623d3c8a35e0d2d27f5b6303cc57fb1fea078926984ae13ce9
-  data.tar.gz: b78558a93c73146a893f77017c2d9959a9235068246b5a15911c419e3f340b4769ba16d3490c376c652242d3658cd01c4df5e1eb76ba8b062f0522807e43476c
+  metadata.gz: d602eddb79c725717821bdeaeb1bc9eba1a7c67f2e1096ce282b288d5f958cd8af9432fbeecddf55ae285eb0d4e608cca4f844a582f56d384f1b236ad109e153
+  data.tar.gz: 1eb514f53f64d1782efd2d5e9b375478e08501bea47394450f34001fadbb7494ccfda070022fb9b5ea7a56e994e0b80bb06be1ffc441ef9ce90b59b49a27b156

data/.rubocop_todo.yml

@@ -1,6 +1,6 @@
 # This configuration was generated by
 # `rubocop --auto-gen-config`
-# on 2026-05-11 22:41:11 UTC using RuboCop version 1.86.1.
+# on 2026-05-12 02:38:27 UTC using RuboCop version 1.86.1.
 # The point is for the user to remove these configuration records
 # one by one as the offenses are removed from the code base.
 # Note that changes in the inspected code, or installation of new
@@ -11,14 +11,13 @@ Gemspec/RequiredRubyVersion:
   Exclude:
     - 'metanorma-plugin-plantuml.gemspec'
 
-# Offense count: 8
+# Offense count: 6
 # This cop supports safe autocorrection (--autocorrect).
 # Configuration parameters: Max, AllowHeredoc, AllowURI, AllowQualifiedName, URISchemes, AllowRBSInlineAnnotation, AllowCopDirectives, AllowedPatterns, SplitStrings.
 # URISchemes: http, https
 Layout/LineLength:
   Exclude:
     - 'Rakefile'
-    - 'lib/metanorma/plugin/plantuml/backend.rb'
     - 'lib/metanorma/plugin/plantuml/config.rb'
     - 'lib/metanorma/plugin/plantuml/wrapper.rb'
     - 'spec/metanorma/plugin/plantuml/plantuml_integration_spec.rb'

data/lib/metanorma/plugin/plantuml/backend.rb

@@ -6,14 +6,12 @@ require "fileutils"
 module Metanorma
   module Plugin
     module Plantuml
-      # Backend class for PlantUML diagram generation
-      # Adapted from metanorma-standoc's PlantUMLBlockMacroBackend
       class Backend
         class << self
           def plantuml_installed?
             return true if plantuml_available?
 
-            raise "PlantUML not installed"
+            raise PlantumlError, "PlantUML not installed"
           end
 
           def plantuml_available?
@@ -21,53 +19,64 @@ module Metanorma
           end
 
           def generate_file( # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
-            parent, reader, format_override: nil, options: {}
+            parent, source, format_override: nil, options: {}
           )
             ldir, imagesdir, fmt = generate_file_prep(parent)
             fmt = format_override if format_override
-            plantuml_content = prep_source(parent, reader)
+            validate_source(source)
 
-            # Extract filename from PlantUML source if specified
             filename = generate_unique_filename(fmt)
-            extracted_filename = extract_plantuml_filename(plantuml_content)
+            extracted_filename = FilenameResolver.extract(source)
 
-            filename = "#{extracted_filename}.#{fmt}" if extracted_filename
+            if extracted_filename
+              safe_filename = FilenameResolver.sanitize(extracted_filename)
+              filename = "#{safe_filename}.#{fmt}"
+            end
 
             absolute_path, relative_path = path_prep(ldir, imagesdir)
             output_file = File.join(absolute_path, filename)
 
             result = Wrapper.generate(
-              plantuml_content,
+              source,
               format: fmt,
               output_file: output_file,
               includedirs: options[:includedirs],
               layout: options[:layout],
             )
 
-            raise "No image output from PlantUML: #{result[:error].message}" unless result[:success]
+            unless result[:success]
+              raise GenerationError,
+                    "No image output from PlantUML: #{result[:error].message}"
+            end
 
             File.join(relative_path, filename)
           end
 
           def generate_multiple_files(
-            parent, reader, formats, attrs, options: {}
+            parent, source, formats, attrs, options: {}
           )
-            # Generate files for each format
             filenames = formats.map do |format|
-              generate_file(parent, reader, format, options: options)
+              generate_file(parent, source,
+                            format_override: format, options: options)
             end
 
-            # Return data for BlockProcessor to create image block
             through_attrs = generate_attrs attrs
             through_attrs["target"] = filenames.first
-
-            # Store additional formats for potential future use
             through_attrs["data-formats"] = formats.join(",")
             through_attrs["data-files"] = filenames.join(",")
 
             through_attrs
           end
 
+          def validate_source(source)
+            diagram_type = extract_diagram_type(source)
+            return if diagram_type && matching_end?(source, diagram_type)
+
+            raise GenerationError,
+                  "@start#{diagram_type} without matching " \
+                  "@end#{diagram_type} in PlantUML!"
+          end
+
           def generate_file_prep(parent) # rubocop:disable Metrics/AbcSize,Metrics/MethodLength
             imagesdir = if parent.document.attr("docfile") &&
                 parent.document.attr("imagesdir")
@@ -92,11 +101,11 @@ module Metanorma
             ret = Utils.localdir(parent.document)
             return ret if File.writable?(ret)
 
-            raise "Destination directory #{ret} not writable for PlantUML!"
+            raise GenerationError,
+                  "Destination directory #{ret} not writable for PlantUML!"
           end
 
           def path_prep(localdir, imagesdir) # rubocop:disable Metrics/AbcSize,Metrics/MethodLength
-            # Determine source path
             sourcepath = if imagesdir.nil?
                            localdir
                          elsif Pathname.new(imagesdir).absolute?
@@ -105,14 +114,14 @@ module Metanorma
                            File.join(localdir, imagesdir)
                          end
 
-            # Determine PlantUML images destination absolute path
             path = Pathname.new(
               File.expand_path(File.join(localdir, "_plantuml_images")),
             )
             path.mkpath
 
             unless File.writable?(path)
-              raise "Destination path #{path} not writable for PlantUML!"
+              raise GenerationError,
+                    "Destination path #{path} not writable for PlantUML!"
             end
 
             [
@@ -122,28 +131,6 @@ module Metanorma
             ]
           end
 
-          def prep_source(parent, reader) # rubocop:disable Metrics/MethodLength
-            src = if reader.respond_to?(:source)
-                    # get content from BlockProcessor
-                    reader.source
-                  else
-                    # get content from ImageBlockMacroProcessor
-                    docfile_directory = File.dirname(
-                      parent.document.attributes["docfile"] || ".",
-                    )
-
-                    resolved_path = parent.document
-                      .path_resolver
-                      .system_path(reader, docfile_directory)
-
-                    File.read(resolved_path, encoding: "UTF-8")
-                  end
-
-            # Validate that we have matching start/end pairs
-            validate_plantuml_delimiters(src)
-            src
-          end
-
           def generate_attrs(attrs)
             %w[id align float title role width height alt]
               .each_with_object({}) do |key, memo|
@@ -153,49 +140,19 @@ module Metanorma
 
           private
 
-          def validate_plantuml_delimiters(src)
-            # Find @start... pattern
-            # (case insensitive, support all PlantUML diagram types)
-            start_match = src.match(/^@start(\w+)/i)
-            raise "PlantUML content must start with @start... directive!" unless start_match
-
-            diagram_type = start_match[1].downcase
-            end_pattern = "@end#{diagram_type}"
-
-            # Look for matching @end... directive (case insensitive)
-            return if /#{Regexp.escape(end_pattern)}\s*$/mi.match?(src)
-
-            raise "@start#{diagram_type} without matching #{end_pattern} " \
-                  "in PlantUML!"
-          end
-
-          def extract_plantuml_filename(plantuml_content)
-            # Extract filename from any @start... line if specified
-            # Only match when filename is on the same line as @start...
-            # (no newlines)
-            lines = plantuml_content.lines
-            first_line = lines.first&.strip
-            return nil unless first_line
-
-            match = first_line.match(/^@start\w+\s+(.+)$/i)
-            return nil unless match
-
-            filename = match[1].strip
-            return nil if filename.nil? || filename.empty?
+          def extract_diagram_type(source)
+            match = source.match(/^@start(\w+)/i)
+            unless match
+              raise GenerationError,
+                    "PlantUML content must start with @start... directive!"
+            end
 
-            # Sanitize filename for filesystem use
-            sanitize_filename(filename)
+            match[1].downcase
           end
 
-          def sanitize_filename(filename)
-            # Remove quotes and sanitize for filesystem
-            filename = filename.gsub(/^["']|["']$/, "")
-            # Replace any non-alphanumeric characters
-            # (except dash, underscore, dot) with underscore
-            filename.gsub(/[^\w\-.]/, "_")
-              .gsub(/\.{2,}/, "_")  # Replace multiple dots with underscore
-              .gsub(/_{2,}/, "_")   # Replace multiple underscores with single
-              .gsub(/^[_\-.]+|[_\-.]+$/, "") # Remove leading/trailing chars
+          def matching_end?(source, diagram_type)
+            end_directive = "@end#{diagram_type}"
+            source.downcase.include?(end_directive.downcase)
           end
 
           def generate_unique_filename(format)

data/lib/metanorma/plugin/plantuml/block_processor.rb

@@ -3,7 +3,6 @@
 module Metanorma
   module Plugin
     module Plantuml
-      # PlantUML block processor
       class BlockProcessor < ::Asciidoctor::Extensions::BlockProcessor
         include ::Metanorma::Plugin::Plantuml::BlockProcessorBase
 
@@ -13,25 +12,23 @@ module Metanorma
         parse_content_as :raw
 
         def process(parent, reader, attrs)
-          # Check for document-level disable flag
+          source = reader.source
+
           if parent.document.attr("plantuml-disabled")
-            return abort(parent, reader, attrs,
+            return abort(parent, source, attrs,
                          "PlantUML processing disabled")
           end
 
-          # Check PlantUML availability explicitly
           unless Backend.plantuml_available?
-            return abort(parent, reader, attrs,
-                         "PlantUML not installed")
+            return abort(parent, source, attrs, "PlantUML not installed")
           end
 
-          # Parse format specifications
           formats = parse_formats(attrs, parent.document)
           options = parse_options(parent, reader, attrs)
 
-          process_image_block(parent, reader, attrs, formats, options)
+          process_image_block(parent, source, attrs, formats, options)
         rescue StandardError => e
-          abort(parent, reader, attrs, e.message)
+          abort(parent, source, attrs, e.message)
         end
 
         private
@@ -39,7 +36,6 @@ module Metanorma
         def parse_options(parent, _reader, attrs)
           options = {}
 
-          # Parse include directory
           options[:includedirs] = add_attrs_to_includedirs(
             parent.document, attrs, parse_doc_includedirs(parent.document)
           )

data/lib/metanorma/plugin/plantuml/block_processor_base.rb

@@ -7,12 +7,12 @@ module Metanorma
   module Plugin
     module Plantuml
       module BlockProcessorBase
-        def abort(parent, reader, attrs, msg)
+        def abort(parent, text, attrs, msg)
           warn msg
           attrs["language"] = "plantuml"
           create_listing_block(
             parent,
-            reader.respond_to?(:source) ? reader.source : reader,
+            text,
             attrs.reject { |k, _v| k.to_s.match?(/^\d+$/) },
           )
         end
@@ -35,19 +35,16 @@ module Metanorma
         end
 
         def parse_formats(attrs, document) # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity, Metrics/AbcSize, Metrics/MethodLength
-          # Check for formats attribute (multiple formats)
           if attrs["formats"]
             formats = attrs["formats"].split(",").map(&:strip).map(&:downcase)
             return formats.select { |f| valid_format?(f) }
           end
 
-          # Check for format attribute (single format override)
           if attrs["format"]
             format = attrs["format"].strip.downcase
             return [format] if valid_format?(format)
           end
 
-          # Fall back to document attribute or default
           default_format = document
             .attr("plantuml-image-format")&.strip&.downcase ||
             Wrapper::DEFAULT_FORMAT
@@ -74,19 +71,17 @@ module Metanorma
           includedirs.compact.uniq
         end
 
-        def process_image_block(parent, reader, attrs, formats, options) # rubocop:disable Metrics/MethodLength
+        def process_image_block(parent, source, attrs, formats, options) # rubocop:disable Metrics/MethodLength
           if formats.length == 1
-            # Single format - original behavior
             filename = Backend.generate_file(
-              parent, reader, format_override: formats.first, options: options
+              parent, source, format_override: formats.first, options: options
             )
             through_attrs = Backend.generate_attrs(attrs)
             through_attrs["target"] = filename
           else
-            # Multiple formats - generate multiple files
             through_attrs = Backend
               .generate_multiple_files(
-                parent, reader, formats, attrs, options: options
+                parent, source, formats, attrs, options: options
               )
           end
 

data/lib/metanorma/plugin/plantuml/filename_resolver.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Metanorma
+  module Plugin
+    module Plantuml
+      class FilenameResolver
+        class << self
+          def extract(content)
+            first_line = content.lines.first&.strip
+            return nil unless first_line
+
+            match = first_line.match(/^@start\w+\s+([^\n]+)/i)
+            return nil unless match
+
+            filename = match[1].strip
+            return nil if filename.empty?
+
+            filename.gsub(/^["']|["']$/, "")
+          end
+
+          def sanitize(filename)
+            result = filename.gsub(/[^\w\-.]/, "_")
+            result = result.tr_s("._", "._")
+            result = result.gsub(/\.{2,}/, ".")
+            result = result.gsub(/_{2,}/, "_")
+            strip_special_edges(result)
+          end
+
+          private
+
+          def strip_special_edges(str)
+            result = str
+            trim = { "_" => true, "-" => true, "." => true }
+            result = result[1..] while result.length > 1 && trim[result[0]]
+            result = result[..-2] while result.length > 1 && trim[result[-1]]
+            result
+          end
+        end
+      end
+    end
+  end
+end

data/lib/metanorma/plugin/plantuml/image_block_macro_processor.rb

@@ -3,37 +3,47 @@
 module Metanorma
   module Plugin
     module Plantuml
-      # PlantUML block processor
       class ImageBlockMacroProcessor < ::Asciidoctor::Extensions::BlockMacroProcessor
         include ::Metanorma::Plugin::Plantuml::BlockProcessorBase
 
         use_dsl
         named :plantuml_image
 
-        def process(parent, reader, attrs)
-          # Check for document-level disable flag
+        def process(parent, target, attrs)
+          display_text = target
+
           if parent.document.attr("plantuml-disabled")
-            return abort(parent, reader, attrs,
+            return abort(parent, display_text, attrs,
                          "PlantUML processing disabled")
           end
 
-          # Check PlantUML availability explicitly
           unless Backend.plantuml_available?
-            return abort(parent, reader, attrs,
-                         "PlantUML not installed")
+            return abort(parent, display_text, attrs, "PlantUML not installed")
           end
 
-          # Parse format specifications
+          source = read_source_file(parent, target)
           formats = parse_formats(attrs, parent.document)
-          options = parse_options(parent, reader, attrs)
+          options = parse_options(parent, target, attrs)
 
-          process_image_block(parent, reader, attrs, formats, options)
+          process_image_block(parent, source, attrs, formats, options)
         rescue StandardError => e
-          abort(parent, reader, attrs, e.message)
+          abort(parent, display_text, attrs, e.message)
         end
 
         private
 
+        def read_source_file(parent, target)
+          docfile_directory = File.dirname(
+            parent.document.attributes["docfile"] || ".",
+          )
+
+          resolved_path = parent.document
+            .path_resolver
+            .system_path(target, docfile_directory)
+
+          File.read(resolved_path, encoding: "UTF-8")
+        end
+
         def add_image_path_to_includedirs(document, image_path, includedirs)
           docdir = document.attributes["docdir"]
           includedirs << File.dirname(
@@ -42,16 +52,15 @@ module Metanorma
           includedirs.compact.uniq
         end
 
-        def parse_options(parent, reader, attrs) # rubocop:disable Metrics/AbcSize
+        def parse_options(parent, target, attrs) # rubocop:disable Metrics/AbcSize
           options = {}
 
-          # Parse include directory
           options[:includedirs] = parse_doc_includedirs(parent.document)
           options[:includedirs] = add_attrs_to_includedirs(
             parent.document, attrs, options[:includedirs]
           )
           options[:includedirs] = add_image_path_to_includedirs(
-            parent.document, reader, options[:includedirs]
+            parent.document, target, options[:includedirs]
           )
 
           if attrs["layout"]

data/lib/metanorma/plugin/plantuml/version.rb

@@ -3,7 +3,7 @@
 module Metanorma
   module Plugin
     module Plantuml
-      VERSION = "1.0.14"
+      VERSION = "1.0.15"
       PLANTUML_JAR_VERSION = "1.2026.3"
     end
   end

data/lib/metanorma/plugin/plantuml/wrapper.rb

@@ -67,7 +67,6 @@ module Metanorma
             output, _, status = Open3.capture3(*cmd)
 
             if status.success?
-              # Extract version from output
               version_match = output.match(/PlantUML version ([\d.]+)/)
               version_match ? version_match[1] : PLANTUML_JAR_VERSION
             end
@@ -141,24 +140,16 @@ module Metanorma
           end
 
           def execute_plantuml(content, format, output_file, options) # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity, Metrics/AbcSize, Metrics/MethodLength
-            # PlantUML generates output files based on filename specified in
-            # @start... line
-            # We need to use a temp directory and then move the file
             Dir.mktmpdir do |temp_dir| # rubocop:disable Metrics/BlockLength
-              # create input file
               File.write("#{temp_dir}/plantuml_input.puml", content)
 
-              # Handle include files
               if options[:include_files] && !options[:include_files].empty?
                 if options[:includedirs].empty?
-                  # raise error when include files are found but includedirs
-                  # is nil
                   raise PlantumlError,
                         "includedirs is required when include files are specified"
                 end
 
                 options[:include_files].each do |include_file|
-                  # find local include file in includedirs
                   found_include_file = nil
                   options[:includedirs].each do |includedir|
                     include_file_path = Pathname.new(includedir)
@@ -172,7 +163,6 @@ module Metanorma
 
                   next unless found_include_file
 
-                  # create include file in temp directory
                   temp_include_file = Pathname.new(temp_dir)
                     .join(include_file).to_s
 
@@ -202,14 +192,12 @@ module Metanorma
                 raise GenerationError.new(error_message, error)
               end
 
-              # Find the generated file and move it to the desired location
               if output_file
                 generated_file = find_generated_file(temp_dir, content,
                                                      format)
                 if generated_file && File.exist?(generated_file)
                   FileUtils.mv(generated_file, output_file)
                 else
-                  # Debug: List what files were actually generated
                   generated_files = Dir.glob(File.join(temp_dir, "*"))
                   error_msg = "Generated file not found in temp directory. "
                   error_msg += "Expected: #{generated_file}. "
@@ -225,37 +213,19 @@ module Metanorma
           end
 
           def find_generated_file(temp_dir, content, format)
-            # PlantUML generates files based on the filename specified in
-            # @start... line
             extension = format.to_s.downcase
 
-            # First, try to extract filename from PlantUML content
-            plantuml_filename = extract_plantuml_filename_from_content(content)
+            plantuml_filename = FilenameResolver.extract(content)
 
             if plantuml_filename
-              # Look for file with PlantUML-specified name
               generated_file = File.join(temp_dir,
                                          "#{plantuml_filename}.#{extension}")
               return generated_file if File.exist?(generated_file)
             end
 
-            # Fallback: scan directory for any generated files with
-            # the correct extension
             Dir.glob(File.join(temp_dir, "*.#{extension}")).first
           end
 
-          def extract_plantuml_filename_from_content(content)
-            # Extract the raw filename from @start... line (don't sanitize)
-            match = content.match(/^@start\w+\s+(.{1,999})$/mi)
-            return nil unless match
-
-            filename = match[1].strip.split("\n").first&.strip
-            return nil if filename.nil? || filename.empty?
-
-            # Remove quotes but keep the original name as PlantUML will use it
-            filename.gsub(/^["']|["']$/, "")
-          end
-
           def build_command(input_file, format, output_dir, options) # rubocop:disable Metrics/MethodLength,Metrics/AbcSize
             cmd = [
               configuration.java_path,
@@ -263,21 +233,14 @@ module Metanorma
               "-jar", PLANTUML_JAR_PATH
             ]
 
-            # Add format-specific options
             format_str = format.to_s.downcase
             cmd << "-t#{format_str}" if SUPPORTED_FORMATS.include?(format_str)
 
-            # Use 'smetana' layout engine for pragma
             layout = options[:layout] || "smetana"
             cmd << "-Playout=#{layout}"
 
-            # Add output directory option
             cmd << "-o" << output_dir
-
-            # Add charset option for better compatibility
             cmd << "-charset" << "UTF-8"
-
-            # Add input file
             cmd << input_file
 
             cmd

data/lib/metanorma-plugin-plantuml.rb

@@ -27,6 +27,8 @@ module Metanorma
                "metanorma/plugin/plantuml/invalid_format_error"
       autoload :Config, "metanorma/plugin/plantuml/config"
       autoload :Utils, "metanorma/plugin/plantuml/utils"
+      autoload :FilenameResolver,
+               "metanorma/plugin/plantuml/filename_resolver"
       autoload :Wrapper, "metanorma/plugin/plantuml/wrapper"
       autoload :Backend, "metanorma/plugin/plantuml/backend"
       autoload :BlockProcessorBase,

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: metanorma-plugin-plantuml
 version: !ruby/object:Gem::Version
-  version: 1.0.14
+  version: 1.0.15
 platform: ruby
 authors:
 - Ribose Inc.
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-05-11 00:00:00.000000000 Z
+date: 2026-05-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: asciidoctor
@@ -49,6 +49,7 @@ files:
 - lib/metanorma/plugin/plantuml/block_processor.rb
 - lib/metanorma/plugin/plantuml/block_processor_base.rb
 - lib/metanorma/plugin/plantuml/config.rb
+- lib/metanorma/plugin/plantuml/filename_resolver.rb
 - lib/metanorma/plugin/plantuml/generation_error.rb
 - lib/metanorma/plugin/plantuml/image_block_macro_processor.rb
 - lib/metanorma/plugin/plantuml/invalid_format_error.rb