giblish 2.2.2 → 3.0.0

data/lib/giblish/configurator.rb

@@ -1,204 +1,122 @@
 require_relative "config_utils"
-require_relative "resourcepaths"
 require_relative "docattr_providers"
-require_relative "adocsrc_providers"
-require_relative "subtreeinfobuilder"
-require_relative "docid/docid"
-require_relative "search/headingindexer"
-require_relative "indexbuilders/depgraphbuilder"
-require_relative "indexbuilders/subtree_indices"
-require_relative "gitrepos/history_pb"
+require_relative "resourcepaths"
+require_relative "layout_config/html_layout_config"
+require_relative "layout_config/pdf_layout_config"
+require_relative "config_builders/docid_config_builder"
+require_relative "config_builders/index_config_builder"
+require_relative "config_builders/git_index_config_builder"
 
 module Giblish
-  class HtmlLayoutConfig
-    attr_reader :pre_builders, :post_builders, :adoc_extensions, :adoc_api_opts, :docattr_providers
-
-    def initialize(resource_paths, config_opts)
-      @adoc_api_opts = {backend: "html"}
-      @pre_builders = []
-      @post_builders = []
-      @adoc_extensions = {}
-      @docattr_providers = []
-
-      if resource_paths.src_resource_dir_abs && resource_paths.dst_style_path_rel
-        # copy local resources to dst and link the generated html with
-        # the given css
-        @pre_builders << CopyResourcesPreBuild.new(resource_paths)
-
-        # make sure generated html has relative link to the copied css
-        @docattr_providers << RelativeCssDocAttr.new(resource_paths.dst_style_path_rel)
-      elsif config_opts.server_css
-        # do not copy any local resources, use the given web path to link to css
-        @docattr_providers << AbsoluteLinkedCss.new(config_opts.server_css)
-      end
-
-      if config_opts.make_searchable
-        # enabling text search
-        search_provider = HeadingIndexer.new(config_opts.srcdir)
-        @adoc_extensions[:tree_processor] = search_provider
-        @post_builders << search_provider
-
-        # add search form to all docs
-        @adoc_extensions[:docinfo_processor] = AddSearchForm.new(config_opts.search_action_path)
-      end
-    end
-  end
-
-  # A combined docattr_provider and post-processor that:
-  # - instructs asciidoctor-mathematical to use svg as format
-  # - removes svg cache files produced by asciidoctor-mathematical
-  class PdfMathPostbuilder
-    # called by the TreeConverter during the post_build phase
-    def on_postbuild(src_topdir, dst_tree, converter)
-      dst_top = src_topdir.pathname
-      dst_top.each_child do |c|
-        if c.basename.to_s.match?(/^stem-[0-9a-f]*\.svg$/)
-          Giblog.logger.debug("will remove #{c}")
-          c.delete
-        end
-      end
-    end
-
-    def document_attributes(src_node, dst_node, dst_top)
-      {
-        "mathematical-format" => "svg"
-      }
-    end
-  end
-
-  class PdfLayoutConfig
-    attr_reader :pre_builders, :post_builders, :adoc_extensions, :adoc_api_opts, :docattr_providers
-
-    def initialize(resource_paths)
-      @adoc_api_opts = {backend: "pdf"}
-      @pre_builders = []
-      @post_builders = []
-      @adoc_extensions = {}
-      @docattr_providers = []
-
-      begin
-        require "asciidoctor-mathematical"
-        cc = PdfMathPostbuilder.new
-        @post_builders << cc
-        @docattr_providers << cc
-      rescue LoadError
-        Giblog.logger.warn { "Did not find asciidoctor-mathematical. stem blocks will not be rendered correctly!" }
-      end
+  # AIDEV-NOTE: Assembles configuration from specialized builders following composition pattern
+  class Configurator
+    # @return [Hash] Build options for TreeConverter
+    attr_reader :build_options
 
-      if resource_paths.src_style_path_abs
-        # generate pdf using asciidoctor-pdf with custom styling
-        @docattr_providers << PdfCustomStyle.new(
-          resource_paths.src_style_path_abs,
-          *resource_paths.font_dirs_abs.to_a
-        )
-      end
-    end
-  end
+    # @return [DocAttrBuilder] Document attribute builder
+    attr_reader :doc_attr
 
-  # configure all parts needed to execute the options specified by
-  # the user
-  class Configurator
-    attr_reader :build_options, :doc_attr, :config_opts
+    # @return [CmdLine::Options] User configuration options
+    attr_reader :config_opts
 
-    # config_opts:: a Cmdline::Options instance with config info
+    # Creates configuration by assembling layout, DocId, and index configurations.
+    #
+    # @param config_opts [CmdLine::Options] User configuration options
     def initialize(config_opts)
       @config_opts = config_opts
       @resource_paths = ResourcePaths.new(config_opts)
 
-      @build_options = {
-        pre_builders: [],
-        post_builders: [],
-        adoc_api_opts: {},
-        # add a hash where all values are initiated as empty arrays
-        adoc_extensions: Hash.new { |h, k| h[k] = [] }
-      }
+      # Build layout configuration
+      layout_config = build_layout_config(config_opts)
 
-      # Initiate the doc attribute repo used during 'run-time'
+      # Initialize doc attribute builder
       @doc_attr = DocAttrBuilder.new(
-        GiblishDefaultDocAttribs.new
+        GiblishDefaultDocAttribs.new,
+        *layout_config.docattr_providers,
+        CmdLineDocAttribs.new(config_opts)
       )
 
-      layout_config = case config_opts
-      in format: "html" then HtmlLayoutConfig.new(@resource_paths, config_opts)
-      in format: "pdf" then PdfLayoutConfig.new(@resource_paths)
-      else
-        raise OptionParser::InvalidArgument, "The given cmd line flags are not supported: #{config_opts.inspect}"
-      end
+      # Build feature configurations
+      docid_config = DocIdConfigBuilder.build(config_opts)
+      index_config = build_index_config(config_opts)
 
-      # setup all options from the chosen layout configuration but
-      # override doc attributes with ones from the supplied configuration to
-      # ensure they have highest pref
-      @doc_attr.add_doc_attr_providers(
-        *layout_config.docattr_providers, CmdLineDocAttribs.new(config_opts)
-      )
+      # Assemble final build options
+      @build_options = assemble_build_options(layout_config, docid_config, index_config, config_opts)
+    end
 
-      setup_docid(config_opts, @build_options, @doc_attr)
-      setup_index_generation(config_opts, @resource_paths, @build_options, @doc_attr)
+    private
 
-      # setup all pre,post, and build options
-      @build_options[:adoc_api_opts] = layout_config.adoc_api_opts
-      @build_options[:pre_builders] += layout_config.pre_builders
-      @build_options[:post_builders] += layout_config.post_builders
-      layout_config.adoc_extensions.each do |type, instance|
-        @build_options[:adoc_extensions][type] << instance
+    # @param config_opts [CmdLine::Options]
+    # @return [LayoutConfigResult]
+    def build_layout_config(config_opts)
+      case config_opts
+      in format: "html" then HtmlLayoutConfig.build(@resource_paths, config_opts)
+      in format: "pdf" then PdfLayoutConfig.build(@resource_paths)
+      else
+        raise OptionParser::InvalidArgument, "The given cmd line flags are not supported: #{config_opts.inspect}"
       end
-
-      # add copy of asset dirs if options stipulates this
-      @build_options[:post_builders] << CopyAssetDirsPostBuild.new(@config_opts) unless @config_opts.copy_asset_folders.nil?
     end
 
-    protected
+    # @param config_opts [CmdLine::Options]
+    # @return [IndexConfig]
+    def build_index_config(config_opts)
+      IndexConfigBuilder.build(config_opts, @resource_paths, @doc_attr)
+    end
 
-    def setup_index_generation(config_opts, resource_paths, build_options, doc_attr)
-      return if config_opts.no_index
+    # @param layout_config [LayoutConfigResult]
+    # @param docid_config [DocIdConfig]
+    # @param index_config [IndexConfig]
+    # @param config_opts [CmdLine::Options]
+    # @return [Hash]
+    def assemble_build_options(layout_config, docid_config, index_config, config_opts)
+      # Start with layout configuration
+      options = {
+        adoc_api_opts: layout_config.adoc_api_opts,
+        pre_builders: layout_config.pre_builders.dup,
+        post_builders: layout_config.post_builders.dup,
+        adoc_extensions: Hash.new { |h, k| h[k] = [] }
+      }
 
-      # setup index generation
-      adoc_src_provider = SubtreeIndexBase.new(
-        {erb_template_path: resource_paths.idx_erb_template_abs}
-      )
-      idx = SubtreeInfoBuilder.new(doc_attr, nil, adoc_src_provider, config_opts.index_basename)
-      build_options[:post_builders] << idx
-    end
+      # Merge layout extensions
+      layout_config.adoc_extensions.each do |type, instances|
+        options[:adoc_extensions][type] += instances
+      end
 
-    def setup_docid(config_opts, build_options, doc_attr)
-      return unless config_opts.resolve_docid
+      # Merge docid configuration
+      options[:pre_builders] += docid_config.pre_builders
+      options[:post_builders] += docid_config.post_builders
+      options[:adoc_extensions][:preprocessor] += docid_config.preprocessors
 
-      # setup docid resolution
-      d = DocIdExtension::DocidPreBuilder.new
-      build_options[:pre_builders] << d
-      docid_pp = DocIdExtension::DocidProcessor.new({id_2_node: d.id_2_node})
-      build_options[:adoc_extensions][:preprocessor] << docid_pp
+      # Merge index configuration
+      options[:post_builders] += index_config.post_builders
 
-      # early exit if user does not want indices
-      return if config_opts.no_index
+      # Add asset copying if configured
+      unless config_opts.copy_asset_folders.nil?
+        options[:post_builders] << CopyAssetDirsPostBuild.new(config_opts)
+      end
 
-      # generate dep graph if graphviz is available
-      dg = DependencyGraphPostBuilder.new(docid_pp.node_2_ids, doc_attr, nil, nil, config_opts.graph_basename)
-      build_options[:post_builders] << dg
+      options
     end
   end
 
-  # swap standard index generation from the base class to ones including
-  # git history.
+  # AIDEV-NOTE: Git-specific configurator using composition instead of inheritance
   class GitRepoConfigurator < Configurator
+    # Creates configuration for git repository conversion with history support.
+    #
+    # @param config_opts [CmdLine::Options] User configuration options
+    # @param git_repo_dir [Pathname] Path to git repository root
     def initialize(config_opts, git_repo_dir)
       @git_repo_dir = git_repo_dir
       config_opts.search_action_path ||= "/gibsearch.cgi"
       super(config_opts)
     end
 
-    protected
-
-    def setup_index_generation(config_opts, resource_paths, build_options, doc_attr)
-      return if config_opts.no_index
+    private
 
-      build_options[:post_builders] << AddHistoryPostBuilder.new(@git_repo_dir)
-
-      # setup index generation
-      adoc_src_provider = SubtreeIndexGit.new(
-        {erb_template_path: resource_paths.idx_erb_template_abs}
-      )
-      build_options[:post_builders] << SubtreeInfoBuilder.new(doc_attr, nil, adoc_src_provider, config_opts.index_basename)
+    # @param config_opts [CmdLine::Options]
+    # @return [IndexConfig]
+    def build_index_config(config_opts)
+      GitIndexConfigBuilder.build(config_opts, @resource_paths, @doc_attr, @git_repo_dir)
     end
   end
 end

data/lib/giblish/docid/docid.rb

@@ -1,5 +1,5 @@
 require "asciidoctor"
-require_relative "../pathtree"
+require "gran"
 
 module Giblish
   module DocIdExtension
@@ -62,7 +62,7 @@ module Giblish
         if @id_2_node.key? doc_id
           Giblog.logger.warn { "Found same doc id twice: (#{doc_id}). This id will be associated with '#{path}' and _not_ with '#{@id_2_node[id]}'." }
         end
-        (doc_id.length.between?(ID_MIN_LENGTH, ID_MAX_LENGTH) && !doc_id.include?("#"))
+        doc_id.length.between?(ID_MIN_LENGTH, ID_MAX_LENGTH) && !doc_id.include?("#")
       end
     end
 
@@ -84,7 +84,7 @@ module Giblish
       def initialize(opts)
         raise ArgumentError, "Missing required option: :id_2_node!" unless opts.key?(:id_2_node)
 
-        super(opts)
+        super
         @id_2_node = opts[:id_2_node]
 
         # init new keys in the hash with an empty array

data/lib/giblish/gitrepos/history_pb.rb

@@ -1,9 +1,10 @@
 require_relative "../subtreeinfobuilder"
+require_relative "../node_data_provider"
 
 module Giblish
-  # Adds a 'FileHistory' instance to each file node's data delegator.
+  # Adds a 'FileHistory' instance to each node's data via dynamic composition.
   # Users down-the-line can then call node.data.history to receive
-  # an Array of HistoryEntry objects.
+  # a FileHistory object.
   class AddHistoryPostBuilder
     def initialize(repo_root)
       @git_itf = GitItf.new(repo_root)
@@ -15,8 +16,10 @@ module Giblish
 
       dst_tree.traverse_preorder do |level, dst_node|
         unless dst_node.leaf?
-          dst_node.data = DataDelegator.new if dst_node.data.nil?
-          dst_node.data.add(FileHistory.new(current_branch))
+          # Non-leaf nodes don't have conversion info yet, create NodeDataProvider with history
+          if dst_node.data.nil?
+            dst_node.data = NodeDataProvider.new(FileHistory.new(current_branch))
+          end
           next
         end
 
@@ -33,7 +36,9 @@ module Giblish
             log_entry["sha"]
           )
         end
-        dst_node.data.add(file_log)
+
+        # Add history provider to existing NodeDataProvider
+        dst_node.data.add_provider(file_log)
       end
     end
   end

data/lib/giblish/indexbuilders/depgraphbuilder.rb

@@ -90,7 +90,7 @@ module Giblish
       # add a virtual 'gibgraph.adoc' node as the only node in a source tree
       # with this object as provider of both adoc source and conversion options
       v_srcpath = Pathname.new("/virtual") / "#{@basename}.adoc"
-      src_node = PathTree.new(v_srcpath, self).node(v_srcpath, from_root: true)
+      src_node = Gran::PathTree.new(v_srcpath, self).node(v_srcpath, from_root: true)
 
       # add the destination node where the converted file will be stored
       i_node = dst_tree.add_descendants(@basename)

data/lib/giblish/indexbuilders/subtree_indices.rb

@@ -100,7 +100,7 @@ module Giblish
     HISTORY_TABLE_HEADING = <<~HISTORY_HEADER
       File history::
 
-      [cols=\"2,3,8,3\",options=\"header\"]
+      [cols="2,3,8,3",options="header"]
       |===
       |Date |Author |Message |Sha1
     HISTORY_HEADER
@@ -110,20 +110,16 @@ module Giblish
       |===\n\n
     HIST_FOOTER
 
-    def initialize(erb_template_path)
-      super(erb_template_path)
-    end
-
     def subtitle(dst_node)
       "from #{dst_node.data.branch}"
     end
 
     def document_detail_fail(node_data)
-      super(node_data) + generate_history_info(node_data)
+      super + generate_history_info(node_data)
     end
 
     def document_detail(node_data)
-      super(node_data) + generate_history_info(node_data)
+      super + generate_history_info(node_data)
     end
 
     def generate_history_info(node_data)

data/lib/giblish/indexbuilders/verbatimtree.rb

@@ -16,7 +16,7 @@ module Giblish
     def source
       # output tree intro
       tree_string = +<<~DOC_HEADER
-        [subs=\"normal\"]
+        [subs="normal"]
         ----
       DOC_HEADER
 

data/lib/giblish/layout_config/html_layout_config.rb

@@ -0,0 +1,77 @@
+require_relative "layout_config_result"
+require_relative "../docattr_providers"
+require_relative "../resourcepaths"
+require_relative "../search/headingindexer"
+
+module Giblish
+  # AIDEV-NOTE: Builder for HTML layout configuration following established provider pattern
+  class HtmlLayoutConfig
+    # Builds complete HTML layout configuration.
+    #
+    # @param resource_paths [ResourcePaths] Resolved paths for resources, styles, and templates
+    # @param config_opts [CmdLine::Options] User configuration options
+    # @return [LayoutConfigResult] Complete layout configuration with all components
+    def self.build(resource_paths, config_opts)
+      # AIDEV-NOTE: Create search provider once and reuse in both extensions and post_builders
+      search_provider = config_opts.make_searchable ? HeadingIndexer.new(config_opts.srcdir) : nil
+
+      pre_builders = build_pre_builders(resource_paths)
+      post_builders = build_post_builders(search_provider)
+      adoc_extensions = build_adoc_extensions(search_provider, config_opts)
+      docattr_providers = build_docattr_providers(resource_paths, config_opts)
+
+      LayoutConfigResult.new(
+        pre_builders: pre_builders,
+        post_builders: post_builders,
+        adoc_extensions: adoc_extensions,
+        adoc_api_opts: {backend: "html"},
+        docattr_providers: docattr_providers
+      )
+    end
+
+    # @param resource_paths [ResourcePaths]
+    # @return [Array<CopyResourcesPreBuild>]
+    def self.build_pre_builders(resource_paths)
+      builders = []
+      if resource_paths.src_resource_dir_abs && resource_paths.dst_style_path_rel
+        builders << CopyResourcesPreBuild.new(resource_paths)
+      end
+      builders
+    end
+
+    # @param search_provider [HeadingIndexer, nil]
+    # @return [Array<HeadingIndexer>]
+    def self.build_post_builders(search_provider)
+      builders = []
+      builders << search_provider if search_provider
+      builders
+    end
+
+    # @param search_provider [HeadingIndexer, nil]
+    # @param config_opts [CmdLine::Options]
+    # @return [Hash{Symbol => Array<Object>}]
+    def self.build_adoc_extensions(search_provider, config_opts)
+      extensions = {}
+      if search_provider
+        extensions[:tree_processor] = [search_provider]
+        extensions[:docinfo_processor] = [AddSearchForm.new(config_opts.search_action_path)]
+      end
+      extensions
+    end
+
+    # @param resource_paths [ResourcePaths]
+    # @param config_opts [CmdLine::Options]
+    # @return [Array<Object>]
+    def self.build_docattr_providers(resource_paths, config_opts)
+      providers = []
+      if resource_paths.src_resource_dir_abs && resource_paths.dst_style_path_rel
+        providers << RelativeCssDocAttr.new(resource_paths.dst_style_path_rel)
+      elsif config_opts.server_css
+        providers << AbsoluteLinkedCss.new(config_opts.server_css)
+      end
+      providers
+    end
+
+    private_class_method :build_pre_builders, :build_post_builders, :build_adoc_extensions, :build_docattr_providers
+  end
+end

data/lib/giblish/layout_config/layout_config_result.rb

@@ -0,0 +1,35 @@
+module Giblish
+  # AIDEV-NOTE: Immutable value object holding complete layout configuration
+  class LayoutConfigResult
+    # @return [Array<Object>] Pre-build phase processors
+    attr_reader :pre_builders
+
+    # @return [Array<Object>] Post-build phase processors
+    attr_reader :post_builders
+
+    # @return [Hash{Symbol => Array<Object>}] Asciidoctor extensions by type
+    attr_reader :adoc_extensions
+
+    # @return [Hash{Symbol => Object}] Options passed to Asciidoctor API
+    attr_reader :adoc_api_opts
+
+    # @return [Array<Object>] Document attribute providers
+    attr_reader :docattr_providers
+
+    # Creates immutable layout configuration.
+    #
+    # @param pre_builders [Array<Object>] Objects implementing on_prebuild(src_tree, dst_tree, converter)
+    # @param post_builders [Array<Object>] Objects implementing on_postbuild(src_tree, dst_tree, converter)
+    # @param adoc_extensions [Hash{Symbol => Array<Object>}] Extension type to array of extension instances
+    # @param adoc_api_opts [Hash{Symbol => Object}] Options passed to Asciidoctor API
+    # @param docattr_providers [Array<Object>] Objects implementing document_attributes(src_node, dst_node, dst_top)
+    def initialize(pre_builders:, post_builders:, adoc_extensions:, adoc_api_opts:, docattr_providers:)
+      @pre_builders = pre_builders.freeze
+      @post_builders = post_builders.freeze
+      @adoc_extensions = adoc_extensions.freeze
+      @adoc_api_opts = adoc_api_opts.freeze
+      @docattr_providers = docattr_providers.freeze
+      freeze
+    end
+  end
+end

data/lib/giblish/layout_config/pdf_layout_config.rb

@@ -0,0 +1,89 @@
+require_relative "layout_config_result"
+require_relative "../docattr_providers"
+require_relative "../utils"
+
+module Giblish
+  # AIDEV-NOTE: Combined docattr provider and post-processor for asciidoctor-mathematical
+  class PdfMathPostbuilder
+    # Cleans up temporary SVG files created by asciidoctor-mathematical.
+    #
+    # @param src_topdir [Gran::PathTree] Source tree root
+    # @param dst_tree [Gran::PathTree] Destination tree
+    # @param converter [TreeConverter] Converter instance
+    # @return [void]
+    def on_postbuild(src_topdir, dst_tree, converter)
+      dst_top = src_topdir.pathname
+      dst_top.each_child do |c|
+        if c.basename.to_s.match?(/^stem-[0-9a-f]*\.svg$/)
+          Giblog.logger.debug("will remove #{c}")
+          c.delete
+        end
+      end
+    end
+
+    # Provides document attributes for mathematical formula rendering.
+    #
+    # @param src_node [Gran::PathTree::Node] Source node
+    # @param dst_node [Gran::PathTree::Node] Destination node
+    # @param dst_top [Pathname] Destination top directory
+    # @return [Hash{String => String}] Document attributes
+    def document_attributes(src_node, dst_node, dst_top)
+      {"mathematical-format" => "svg"}
+    end
+  end
+
+  # AIDEV-NOTE: Builder for PDF layout configuration following established provider pattern
+  class PdfLayoutConfig
+    # Builds complete PDF layout configuration.
+    #
+    # @param resource_paths [ResourcePaths] Resolved paths for resources, styles, and fonts
+    # @return [LayoutConfigResult] Complete layout configuration with all components
+    def self.build(resource_paths)
+      post_builders = build_post_builders
+      docattr_providers = build_docattr_providers(resource_paths, post_builders)
+
+      LayoutConfigResult.new(
+        pre_builders: [],
+        post_builders: post_builders,
+        adoc_extensions: {},
+        adoc_api_opts: {backend: "pdf"},
+        docattr_providers: docattr_providers
+      )
+    end
+
+    # @return [Array<PdfMathPostbuilder>]
+    def self.build_post_builders
+      builders = []
+      begin
+        require "asciidoctor-mathematical"
+        builders << PdfMathPostbuilder.new
+      rescue LoadError
+        Giblog.logger.warn { "Did not find asciidoctor-mathematical. stem blocks will not be rendered correctly!" }
+      end
+      builders
+    end
+
+    # @param resource_paths [ResourcePaths]
+    # @param post_builders [Array<PdfMathPostbuilder>]
+    # @return [Array<Object>]
+    def self.build_docattr_providers(resource_paths, post_builders)
+      providers = []
+
+      # Add math postbuilder as provider if it exists
+      math_builder = post_builders.find { |b| b.is_a?(PdfMathPostbuilder) }
+      providers << math_builder if math_builder
+
+      # Add custom style if configured
+      if resource_paths.src_style_path_abs
+        providers << PdfCustomStyle.new(
+          resource_paths.src_style_path_abs,
+          *resource_paths.font_dirs_abs.to_a
+        )
+      end
+
+      providers
+    end
+
+    private_class_method :build_post_builders, :build_docattr_providers
+  end
+end