giblish 0.8.2 → 2.0.0.pre.alpha1

data/lib/giblish/gitrepos/checkoutmanager.rb

@@ -0,0 +1,124 @@
+require "git"
+require "date"
+require_relative "../utils"
+require_relative "../version"
+require_relative "gititf"
+require_relative "gitsummaryprovider"
+
+module Giblish
+  # acquires a handle to an existing git repo and provide the user
+  # with a iteration method 'each_checkout' where each matching branch and/or tag is
+  # checked out and presented to the user code.
+  class GitCheckoutManager
+    attr_reader :branches, :tags, :summary_provider, :git_repo, :repo_root
+
+    # cmd_opts::       a CmdLine::Options instance
+    #
+    # Required options:
+    # srcdir::         Pathname to the top dir of the local git repo to work with
+    # local_only::     if true, do not try to access any remote branches or merge with any
+    #                  upstream changes
+    # Optional options:
+    # abort_on_error:: bail out at an error or continue. Default 'true'
+    # branch_regex::   the regex for the branches to include during iteration (default: none)
+    # tag_regex::      the regex for the tags to include during iteration (default: none)
+    def initialize(cmd_opts)
+      @repo_root = GitItf.find_gitrepo_root(cmd_opts.srcdir)
+      raise ArgumentError, "The path: #{cmd_opts.srcdir} is not within a git repo!" if @repo_root.nil?
+
+      @local_only = cmd_opts.local_only
+      @abort_on_error = cmd_opts.abort_on_error.nil? ? true : cmd_opts.abort_on_error
+
+      @git_repo = init_git_repo(@repo_root, @local_only)
+      @branches = select_user_branches(cmd_opts.branch_regex, @local_only)
+      @tags = select_user_tags(cmd_opts.tag_regex)
+      @summary_provider = GitSummaryDataProvider.new(@repo_root.basename)
+    end
+
+    # present each git checkout matching the init criteria to the user's code.
+    #
+    # === Example
+    #
+    # gcm = GitCheckoutManager.new(opts)
+    # gcm.each_checkout do |name|
+    # ... do things with the currently checked out working tree ...
+    # end
+    def each_checkout
+      current_branch = @git_repo.current_branch
+      checkouts = (@branches + @tags)
+      if checkouts.empty?
+        Giblog.logger.info { "No matching branches or tags found." }
+        return
+      end
+
+      checkouts.each do |treeish|
+        sync_treeish(treeish)
+        # cache branch/tag info for downstream content generation
+        @summary_provider.cache_info(@git_repo, treeish)
+
+        yield(treeish.name)
+      rescue => e
+        Giblog.logger.error { e.message }
+        raise e if @abort_on_error
+      end
+
+      if @git_repo.current_branch != current_branch
+        Giblog.logger.info { "Checking out '#{current_branch}'" }
+        @git_repo.checkout current_branch
+      end
+    end
+
+    private
+
+    def sync_treeish(treeish)
+      Giblog.logger.info { "Checking out '#{treeish.name}'" }
+      @git_repo.checkout treeish.name
+
+      # merge branches with their upstream at origin unless
+      # 'only local'
+      unless (treeish.respond_to?(:tag?) && treeish.tag?) || @local_only
+        # this is a branch, make sure it is up-to-date
+        Giblog.logger.info { "Merging with origin/#{treeish.name}" }
+        @git_repo.merge "origin/#{treeish.name}"
+      end
+    end
+
+    def init_git_repo(git_repo_root, local_only)
+      # Sanity check git repo root
+      raise ArgumentError, "No git repo root dir given" unless git_repo_root
+
+      msg = "Could not find a git repo at #{git_repo_root} !"
+      begin
+        # Connect to the git repo
+        git_repo = Git.open(git_repo_root)
+        # fetch all remote refs if ok with user
+        msg = "Could not fetch from origin (do you need '--local-only'?)!"
+        git_repo.fetch unless local_only
+      rescue => e
+        raise "#{msg}\n\n#{e.message}"
+      end
+      git_repo
+    end
+
+    # Get the branches/tags the user wants to parse
+    def select_user_branches(regexp, local_only)
+      return [] unless regexp
+
+      user_checkouts = local_only ? @git_repo.branches.local : @git_repo.branches.remote
+      user_checkouts.select! do |b|
+        # match branches but remove eventual HEAD -> ... entry
+        regexp.match b.name unless /^HEAD/.match?(b.name)
+      end
+      Giblog.logger.debug { "selected git branches: #{user_checkouts.collect { |b| b.name }.join(", ")}" }
+      user_checkouts
+    end
+
+    def select_user_tags(regexp)
+      return [] unless regexp
+
+      @git_repo.tags.select do |t|
+        regexp.match t.name
+      end
+    end
+  end
+end

data/lib/giblish/{gititf.rb → gitrepos/gititf.rb}

@@ -1,5 +1,5 @@
 require "open3"
-require_relative "utils"
+require "git"
 
 module Giblish
   # A home-grown interface class to git. Used for situations when the
@@ -8,14 +8,32 @@ module Giblish
     attr_reader :repo_root, :git_dir
 
     def initialize(path)
-      @repo_root = Giblish::PathManager.find_gitrepo_root(path)
+      @repo_root = GitItf.find_gitrepo_root(path)
       raise ArgumentError("The path: @{path} is not within a git repo!") if @repo_root.nil?
 
       @git_dir = @repo_root / ".git"
     end
 
+    # Find the root directory of the git repo in which the
+    # given dirpath resides.
+    #
+    # dirpath:: an absolute path to a directory that resides
+    #           within a git repo.
+    #
+    # returns:: the root direcotry of the git repo or nil if the input path
+    #          does not reside within a git repo.
+    def self.find_gitrepo_root(dirpath)
+      Pathname.new(dirpath).ascend do |p|
+        next unless p.exist?
+
+        git_dir = p.realpath.join(".git")
+        return p if git_dir.directory?
+      end
+    end
+
     # Get the log history of the supplied file as an array of
     # hashes, each entry has keys:
+    #
     # sha
     # date
     # author
@@ -29,6 +47,14 @@ module Giblish
       process_log_output(o)
     end
 
+    def current_branch
+      # git rev-parse --abbrev-ref HEAD
+      o, e, s = exec_cmd("rev-parse", %w[--abbrev-ref HEAD], "")
+      raise "Failed to get git log for #{filename}!!\n#{e}" if s.exitstatus != 0
+
+      o.strip
+    end
+
     private
 
     # Process the log output from git
@@ -47,7 +73,7 @@ module Giblish
         end
 
         if in_message
-          hsh["message"] << "#{line[4..-1]}\n"
+          hsh["message"] << "#{line[4..]}\n"
           next
         end
 
@@ -58,7 +84,7 @@ module Giblish
         case key
         when "commit"
           hsh_array << hsh if hsh
-          hsh = { "sha" => value, "message" => "", "parent" => [] }
+          hsh = {"sha" => value, "message" => +"", "parent" => []}
         when "parent"
           hsh["parent"] << value
         when "author"

data/lib/giblish/gitrepos/gitsummary.erb

@@ -0,0 +1,61 @@
+= Document repo '<%= @repo_name %>'
+Generated at <%= DateTime.now.strftime("%Y-%m-%d %H:%M:%S") %> by giblish - v<%= Giblish::VERSION %>
+
+// Display one table for each branch
+<% unless @branch_info.empty? %>
+Branches::
+
+<% @branch_info.each do |b|
+  c = b.latest_commit
+%>
+
+xref:<%= index_path(b.name) %>[*<%= b.name %>*]
+[cols="1a,5a"]
+|===
+
+2+^|_last committed to <%= c.datetime.strftime("%Y-%m-%d") %> by <%= c.committer %>._
+
+|*Sha* 
+|<%= c.sha[0..7] %> ...
+
+|*Message*
+|<%= c.message %>
+
+|===
+
+
+<% end %>
+<% end %>
+
+// Display one table for each tag
+<% unless @tag_infos.empty? %>
+Tags::
+
+<% @tag_infos.each do |t| 
+  c = t.commit
+%>
+
+xref:<%= index_path(t.name) %>[*<%= t.name %>*]
+[cols="1a,5a"]
+|===
+
+2+^| _was created <%= t.date.strftime("%Y-%m-%d") %> by <%= t.author %>._
+
+|*Message*
+|<%= t.message %>
+
+2+^|_The tag points to the commit made <%= c.datetime.strftime("%Y-%m-%d") %> by <%= c.committer %>._
+
+|*Sha*
+|<%= c.sha[0..8] %> ...
+
+|*Message*
+|<%= t.commit.message %>
+
+|===
+
+
+<% end %>
+<% end %>
+
+

data/lib/giblish/gitrepos/gitsummaryprovider.rb

@@ -0,0 +1,78 @@
+require "erb"
+
+module Giblish
+  class GitSummaryDataProvider
+    attr_reader :tags, :branches
+    attr_accessor :index_basename
+
+    CommitInfo = Struct.new(:sha, :datetime, :committer, :message)
+    TagInfo = Struct.new(:sha, :name, :date, :message, :author, :commit) do
+      def id
+        Giblish.to_valid_id(name)
+      end
+    end
+    BranchInfo = Struct.new(:name, :latest_commit)
+
+    DEFAULT_GIT_SUMMARY_TEMPLATE = "/gitsummary.erb"
+
+    def initialize(repo_name)
+      @index_basename = "index"
+
+      # all these are used by erb
+      @repo_name = repo_name
+      @branch_info = []
+      @tag_infos = []
+    end
+
+    # Cache info on one tag or branch
+    #
+    # repo:: a handle to a Git repo object
+    # treeish:: either a Git::Tag or a Git::Branch object
+    def cache_info(repo, treeish)
+      if treeish.respond_to?(:tag?) && treeish.tag?
+        @tag_infos.push(
+          cache_tag_info(repo, treeish)
+        ).sort_by!(&:date).reverse!
+      else
+        @branch_info.push(cache_branch_info(repo, treeish))
+      end
+    end
+
+    # returns:: a string with the relative path to the index file
+    #           in the given branch/tag subtree
+    def index_path(treeish_name)
+      Giblish.to_fs_str(treeish_name) + "/" + @index_basename + ".adoc"
+    end
+
+    def source
+      erb_template = File.read(__dir__ + DEFAULT_GIT_SUMMARY_TEMPLATE)
+      ERB.new(erb_template, trim_mode: "<>").result(binding)
+    end
+
+    private
+
+    def cache_tag_info(repo, tag)
+      unless tag.annotated?
+        c = repo.gcommit(tag)
+        commit = CommitInfo.new(c.sha, c.date, c.author.name, c.message)
+        return TagInfo.new(tag.sha, tag.name, c.date, "<No message - this is not an annotated tag>", c.committer.name, commit)
+      end
+
+      # Handle annotated tags
+      # get sha of the associated commit. (a bit convoluted...)
+      c = repo.gcommit(tag.contents_array[0].split(" ")[1])
+      commit = CommitInfo.new(c.sha, c.date, c.author.name, c.message)
+      TagInfo.new(tag.sha, tag.name, tag.tagger.date, tag.message, tag.tagger.name, commit)
+    end
+
+    def cache_branch_info(repo, branch)
+      # get sha of the associated commit. (a bit convoluted...)
+      c = repo.gcommit(branch)
+      commit = CommitInfo.new(c.sha, c.date, c.author.name, c.message)
+
+      # puts c.instance_variables
+
+      BranchInfo.new(branch.name, commit)
+    end
+  end
+end

data/lib/giblish/gitrepos/history_pb.rb

@@ -0,0 +1,41 @@
+require_relative "../subtreeinfobuilder"
+
+module Giblish
+  # Adds a 'FileHistory' instance to each file node's data delegator.
+  # Users down-the-line can then call node.data.history to receive
+  # an Array of HistoryEntry objects.
+  class AddHistoryPostBuilder
+    def initialize(repo_root)
+      @git_itf = GitItf.new(repo_root)
+    end
+
+    # Called from TreeConverter during post build phase
+    def on_postbuild(src_tree, dst_tree, converter)
+      current_branch = @git_itf.current_branch
+
+      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))
+          next
+        end
+        # next unless dst_node.leaf?
+
+        src_node = dst_node.data.src_node
+        next unless src_node.pathname.exist?
+
+        # Get the commit history of the doc as an Array of entries
+        file_log = FileHistory.new(current_branch)
+        @git_itf.file_log(src_node.pathname.to_s).each do |log_entry|
+          file_log.history << FileHistory::LogEntry.new(
+            log_entry["date"],
+            log_entry["author"],
+            log_entry["message"],
+            log_entry["sha"]
+          )
+        end
+        dst_node.data.add(file_log)
+      end
+    end
+  end
+end

data/lib/giblish/indexbuilders/d3treegraph.rb

@@ -0,0 +1,88 @@
+# Generate asciidoc that represents a given pathtree as a
+# verbatim block with indented, clickable entries.
+class D3TreeGraph
+  attr_reader :tree
+
+  # tree: PathTree
+  # === Required node data methods
+  # title
+  # docid
+  #
+  # options:
+  # dir_index_base_name: String - the basename of the index file
+  # residing in each directory
+  def initialize(tree:, options: {dir_index_base_name: "index"})
+    @tree = transform_data(tree)
+    @options = options
+  end
+
+  def source
+    erb_template = File.read("#{__dir__}/templates/tree.html.erb")
+    ERB.new(erb_template, trim_mode: "<>").result(binding)
+  end
+
+  private
+
+  #      1             1
+  #    / | \           |-2
+  #   2  5  6     ->   | |-3
+  #  /\    / \         | |-4
+  # 3 4   7   8        |-5
+  #                    |-6
+  #                      |-7
+  #                      |-8
+  def transform_data(tree)
+    data = {}
+    last_level = 0
+    path = []
+    # root -> left -> right
+    tree.traverse_preorder do |level, node|
+      d = node.leaf? ? leaf_info(node) : directory_info(node)
+
+      if level == 0
+        data = d
+        path << d
+      elsif level > last_level
+        path[-1][:children] << d
+        path << d
+      elsif level == last_level
+        path[-2][:children] << d
+        path[-1] = d
+      else
+        path[level - 1][:children] << d
+        path[level] = d
+        path = path[0..level]
+      end
+      last_level = level
+    end
+    data
+  end
+
+  def leaf_info(node)
+    conv_info = node.data
+    if conv_info.converted
+      name = (conv_info.docid.nil? ? "" : "#{conv_info.docid} - ") + conv_info.title
+      dst_ref = conv_info.src_rel_path.sub_ext(".html")
+      {
+        name: name,
+        dst_ref: dst_ref,
+        children: []
+      }
+    else
+      Giblog.logger.warn { "Could not get node data for #{conv_info.src_basename}" }
+      {
+        name: "ERR: Failed Conversion",
+        dst_ref: "",
+        children: []
+      }
+    end
+  end
+
+  def directory_info(node)
+    {
+      name: node.segment,
+      dst_ref: "",
+      children: []
+    }
+  end
+end

data/lib/giblish/indexbuilders/depgraphbuilder.rb

@@ -0,0 +1,109 @@
+require_relative "dotdigraphadoc"
+
+module Giblish
+  # Provide the source for a graphviz-based index page.
+  #
+  # Note: The asciidoctor-diagram API seems a bit strange when it comes to storing
+  # temporary files:
+  # * it uses a document attribute {imagesoutdir} and stores the
+  #   generated svg image under that regardless of svg-type.
+  # * it uses an option in the diagram macro "cachedir" under which a cached image
+  #   is stored.
+  class GraphPageBase
+    attr_reader :adoc_source
+
+    def initialize(info_2_ids, dst_node, basename, opts = {})
+      # use a tmp dir since asciidoctor-diagram generates cache files
+      # that it doesn't remove afterwards
+      Dir.mktmpdir do |dir|
+        # build the graph source
+        graph = DotDigraphAdoc.new(
+          info_2_ids: info_2_ids,
+          opts: {"svg-type" => "inline", "cachedir" => dir}
+        )
+
+        @adoc_source = <<~DEPGRAPH_PAGE
+          = Dependency graph
+          :imagesoutdir: #{dir}
+
+          #{graph.source}
+
+        DEPGRAPH_PAGE
+      end
+    end
+  end
+
+  # Generates a summary page with a docid-based dependency graph for an entire destination
+  # tree.
+  class DependencyGraphPostBuilder
+    # the dependency graph relies on graphwiz (dot), check if we can access that
+    def self.dot_supported
+      !Giblish.which("dot").nil?
+    end
+
+    DEFAULT_BASENAME = "gibgraph"
+
+    # node_2_ids:: a { src_node => [doc id refs]} hash. It will be queried during
+    #              the post-build phase => it must be populated before the end of the
+    #              build phase
+    def initialize(node_2_ids, docattr_provider = nil, api_opt_provider = nil, adoc_src_provider = nil, basename = DEFAULT_BASENAME)
+      # this class relies on graphwiz (dot), make sure we can access it
+      raise "Could not find the 'dot' tool needed to generate a dependency graph!" unless DependencyGraphPostBuilder.dot_supported
+
+      # require asciidoctor module needed for generating diagrams
+      require "asciidoctor-diagram/graphviz"
+
+      @node_2_ids = node_2_ids
+      @docattr_provider = docattr_provider
+      @api_opt_provider = api_opt_provider
+      @adoc_src_provider = adoc_src_provider || GraphPageBase
+      @basename = basename
+
+      @adoc_source = nil
+    end
+
+    def document_attributes(src_node, dst_node, dst_top)
+      @docattr_provider.nil? ? {} : @docattr_provider.document_attributes(src_node, dst_node, dst_top)
+    end
+
+    def api_options(src_node, dst_node, dst_top)
+      @api_opt_provider.nil? ? {} : @api_opt_provider.api_options(dst_top)
+    end
+
+    def adoc_source(src_node, dst_node, dst_top)
+      @adoc_source
+    end
+
+    # Called from TreeConverter during post build phase
+    def on_postbuild(src_tree, dst_tree, converter)
+      return unless DependencyGraphPostBuilder.dot_supported
+
+      # convert {src_node => [doc ids]} to {conv_info => [doc ids]}
+      info_2_ids = {}
+      dst_tree.traverse_preorder do |_level, dst_node|
+        next unless dst_node.leaf?
+
+        sn = dst_node.data.src_node
+        info_2_ids[dst_node] = @node_2_ids[sn] if @node_2_ids.key?(sn)
+      end
+
+      # 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)
+
+      # add the destination node where the converted file will be stored
+      i_node = dst_tree.add_descendants(@basename)
+
+      # get the adoc source from the provider (Class or instance)
+      @adoc_source = if @adoc_src_provider.is_a?(Class)
+        @adoc_src_provider.new(info_2_ids, dst_tree, @basename).adoc_source
+      else
+        @adoc_src_provider.adoc_source
+      end
+
+      # do the conversion
+      converter.convert(src_node, i_node, dst_tree)
+    end
+  end
+end