defmastership 1.0.18 → 1.1.0

data/features/rename_included_files.feature

@@ -23,7 +23,6 @@ Feature: The rename_included_files command
     And an empty file named "any_path/one_file.png"
     When I successfully run `defmastership modify --modifications rename_included_png thedoc.adoc`
     Then the stdout should not contain anything
-    And the stderr should not contain anything
     And the file "thedoc.adoc" should contain:
     """
     include::any_path/one_file.png[]
@@ -49,7 +48,6 @@ Feature: The rename_included_files command
     And an empty file named "any_path/one_file.png"
     When I successfully run `defmastership modify --modifications rename_included_png thedoc.adoc`
     Then the stdout should not contain anything
-    And the stderr should not contain anything
     And the file "thedoc.adoc" should contain:
     """
     [define, requirement, TOTO-WHATEVER-123]
@@ -77,7 +75,6 @@ Feature: The rename_included_files command
     And an empty file named "any_path/one_file.png"
     When I successfully run `defmastership modify --modifications rename_included_png thedoc.adoc`
     Then the stdout should not contain anything
-    And the stderr should not contain anything
     And the file "thedoc.adoc" should contain:
     """
     [define, requirement, TOTO-WHATEVER-123]
@@ -109,7 +106,6 @@ Feature: The rename_included_files command
     And an empty file named "one_two/one_file.png"
     When I successfully run `defmastership modify --modifications rename_included_png thedoc.adoc`
     Then the stdout should not contain anything
-    And the stderr should not contain anything
     And the file "thedoc.adoc" should contain:
     """
     :any: one
@@ -142,7 +138,6 @@ Feature: The rename_included_files command
     And an empty file named "any_path/TOTO-WHATEVER-123_one_file.png"
     When I successfully run `defmastership modify --modifications rename_included_png thedoc.adoc`
     Then the stdout should not contain anything
-    And the stderr should not contain anything
     And the file "thedoc.adoc" should contain:
     """
     [define, requirement, TOTO-WHATEVER-123]

data/features/step_definitions/git_steps.rb

@@ -0,0 +1,19 @@
+# Copyright (c) 2024 Jerome Arbez-Gindre
+# frozen_string_literal: true
+
+require 'git'
+
+Given('I initialize a git repo') do
+  Git.init(Aruba.config.home_directory)
+end
+
+Given('I add and commit the {string} file') do |filename|
+  git = Git.open(Aruba.config.home_directory)
+  git.add(filename)
+  git.commit('whatever')
+end
+
+Given('I set the {string} tag') do |tag_name|
+  git = Git.open(Aruba.config.home_directory)
+  git.add_tag(tag_name)
+end

data/lib/defmastership/batch_modifier.rb

@@ -1,17 +1,35 @@
 # Copyright (c) 2020 Jerome Arbez-Gindre
 # frozen_string_literal: true
 
-module DefMastership
-  # Change references from temporary to definitive with multiple RefChangers
+module Defmastership
+  # Apply modications on a list of related asciidoc sources
   class BatchModifier
-    attr_reader :config, :adoc_sources, :changes
-
+    # Stores the overall invocation configuration
+    # @return [YAML] configuration as eventualy modified by modifiers
+    attr_reader :config
+    # Stores the list of asciidoc files to modify and to save
+    # @return [Hash{String => String}] asciidoc sources as modified by modifiers
+    #  * :key filename
+    #  * :value file content
+    attr_reader :adoc_sources
+    # Provides the list of performed modifications
+    # @return [Array<Array<String>>] List of performed modifications
+    # (each line: [Modifier, Was, Becomes])
+    attr_reader :changes
+
+    # @param config [YAML] the overall modifications configurations
+    # @param adoc_sources [Hash{String => String}] asciidoctor files to be modified
+    #  * Key: filename
+    #  * Value: file content
     def initialize(config, adoc_sources)
       @config = config
       @adoc_sources = adoc_sources
       @changes = []
     end
 
+    # Apply modications on asciidoc sources of @adoc_sources
+    #
+    # @param modifs [Array<String>] The modifications to apply
     def apply(modifs)
       modifs.each do |modif|
         modifier = modifier_from(modif)
@@ -28,7 +46,7 @@ module DefMastership
       config_modif_sym = config[modif]
       raise(ArgumentError, "#{modif} is not a known modification") unless config_modif_sym
 
-      ModifierFactory.from_config(config_modif_sym)
+      Modifier::Factory.from_config(config_modif_sym)
     end
 
     def collect_changes(modifier, modif)

data/lib/defmastership/comment_filter.rb

@@ -4,7 +4,8 @@
 # adding a method to string to figure out if a string is commented or
 # not.
 class String
+  # @return [Boolean] true if the line is commented
   def commented?
-    !!match(DefMastership::DMRegexp::SINGLE_LINE_COMMENT)
+    !!match(Defmastership::Core::DMRegexp::SINGLE_LINE_COMMENT)
   end
 end

data/lib/defmastership/definition.rb

@@ -3,8 +3,8 @@
 
 require 'digest'
 
-# Contains the content of a DefMastership definition
-module DefMastership
+# Contains the content of a Defmastership definition
+module Defmastership
   BUILD_FROM_MATCH = {
     type: ->(match) { match[:type] },
     reference: ->(match) { match[:reference] },
@@ -38,7 +38,7 @@ module DefMastership
 
   private_constant :DefinitionData
 
-  # DefMastership definition: contains all data of a definition
+  # Defmastership definition: contains all data of a definition
   class Definition
     extend Forwardable
     def_delegators :@data,
@@ -52,6 +52,7 @@ module DefMastership
                    :explicit_checksum,
                    :explicit_version
 
+    # @param match [MatchData] the definition data from regepx match
     def initialize(match)
       @data = DefinitionData.new(
         *BUILD_FROM_MATCH.transform_values { |lamb| lamb.call(match) }
@@ -59,34 +60,53 @@ module DefMastership
       )
     end
 
+    # Add a line to the definition's value
+    #
+    # @param new_line [String] the new line
+    # @return [Definition] the definition itself
     def <<(new_line)
       lines << new_line
       self
     end
 
+    # Add a line to the definition's value
+    #
+    # @return [String] the complete value of the definition
     def value
       lines.join("\n")
     end
 
+    # @return [String] short representation (8 last characters) of the sha256 of the definition's value
     def sha256_short
       "~#{Digest::SHA2.hexdigest(value).chars.last(8).join}"
     end
 
+    # @return [String] the explicit checsum if wrong or nil
     def wrong_explicit_checksum
       explicit_checksum unless explicit_checksum.eql?(sha256_short)
     end
 
-    def add_eref(refname, extrefs)
-      eref[refname] = extrefs.strip.split(/\s*,\s*/)
+    # Set an external ref list for a given reference type
+    #
+    # @param ref [String] the type of cross reference
+    # @param extrefs [String] the comma separated external references
+    def add_eref(ref, extrefs)
+      eref[ref] = extrefs.strip.split(/\s*,\s*/)
     end
 
+    # Set an internal ref
+    #
+    # @param ref [String] the internal reference
     def add_iref(ref)
       iref << ref
     end
 
+    # Set an attribute for a given key
+    #
+    # @param key [String] the attribute's key
+    # @param value [String] the attribute's value
     def set_attribute(key, value)
       attributes[key] = value
     end
   end
-  public_constant :Definition
 end

data/lib/defmastership/definition_parser.rb

@@ -3,8 +3,8 @@
 
 require('aasm')
 
-module DefMastership
-  # DefMastership definition: contains all data of a definition
+module Defmastership
+  # Defmastership definition: contains all data of a definition
   class DefinitionParser
     include AASM
 

data/lib/defmastership/document.rb

@@ -2,10 +2,12 @@
 # frozen_string_literal: true
 
 require('asciidoctor')
+require('defmastership/core/constants')
+require('defmastership/core/parsing_state')
 require('defmastership/matching_line')
 
-# Contains the content of a DefMastership document: mainly definitions
-module DefMastership
+# Contains the content of a Defmastership document: mainly definitions
+module Defmastership
   # Class to host data of Document class
   DocumentData = Struct.new(
     :definitions,
@@ -23,46 +25,38 @@ module DefMastership
       definition = Definition.new(matching_line.match)
       labels.merge(definition.labels)
       definitions << definition
-      matching_line.line
     },
     add_line: lambda { |matching_line|
       line = matching_line.line
       definitions.last << line
-      line
     },
     new_eref_setup: lambda { |matching_line|
-      refname = matching_line[:refname].to_sym
-      eref[refname] ||= {}
-      eref[refname][matching_line[:symb].to_sym] = matching_line[:value]
-      matching_line.line
+      reference = matching_line[:reference].to_sym
+      eref[reference] ||= {}
+      eref[reference][matching_line[:symb].to_sym] = matching_line[:value]
     },
     new_eref_def: lambda { |matching_line|
-      definitions.last.add_eref(matching_line[:refname].to_sym, matching_line[:extrefs])
-      matching_line.line
+      definitions.last.add_eref(matching_line[:reference].to_sym, matching_line[:extrefs])
     },
     new_iref_def: lambda { |matching_line|
-      self.iref = true
+      self.has_iref = true
       line = matching_line.line
-      line.scan(DMRegexp::IREF_DEF) do |_|
+      line.scan(Core::DMRegexp::IREF_DEF) do |_|
         definitions.last.add_iref(Regexp.last_match[:intref])
       end
-      line
     },
     new_attribute_conf: lambda { |matching_line|
       attributes[matching_line[:attr].to_sym] = matching_line[:prefix]
-      matching_line.line
     },
     new_attribute_value: lambda { |matching_line|
       definitions.last.set_attribute(matching_line[:attr].to_sym, matching_line[:value])
-      matching_line.line
     },
     new_variable_def: lambda { |matching_line|
       variables[matching_line[:varname].to_sym] = matching_line[:value]
-      matching_line.line
     },
     new_variable_use: lambda { |matching_line|
       line = matching_line.line
-      line.scan(DMRegexp::VARIABLE_USE) do |_|
+      line.scan(Core::DMRegexp::VARIABLE_USE) do |_|
         varname = Regexp.last_match[:varname]
         value = variables[varname.to_sym]
 
@@ -83,36 +77,35 @@ module DefMastership
 
     def initialize
       @data = DocumentData.new([], Set.new, {}, false, {}, {})
-      @parsing_state = ParsingState.new
+      @parsing_state = Core::ParsingState.new
       @definition_parser = DefinitionParser.new(self)
     end
 
-    def parse(lines)
-      lines.each do |line|
-        if @parsing_state.enabled?(line)
-          apply_filters(line)
-        else
-          generate_event(:new_line, MatchingLine.new(nil, line))
-        end
-      end
-    end
-
+    # Parse asciidoc file after [Asciidoctor] preprocessing
+    #
+    # @param adoc_file [String] the file to parse
     def parse_file_with_preprocessor(adoc_file)
-      parse(Asciidoctor.load_file(adoc_file, safe: :unsafe, parse: false).reader.read_lines)
+      do_parse(Asciidoctor.load_file(adoc_file, safe: :unsafe, parse: false).reader.read_lines)
     end
 
+    # @return [Boolean] true if the document has definitions with wrong explicit checksum
     def wrong_explicit_checksum?
       definitions.reduce(false) do |res, definition|
         res || !!definition.wrong_explicit_checksum
       end
     end
 
+    # @return [Boolean] true if the document has definitions with explicit versions
     def explicit_version?
       definitions.reduce(false) do |res, definition|
         res || !!definition.explicit_version
       end
     end
 
+    # Allow to add methods from parser actions
+    #
+    # @param method_name [Symbol] the name of the method
+    # @param args[Array<Object>] the arguments of the method
     def method_missing(method_name, *args)
       action = PARSER_ACTIONS[method_name]
       return instance_exec(*args, &action) if action
@@ -120,20 +113,36 @@ module DefMastership
       super
     end
 
+    # Allow to check if a parser action is available
+    #
+    # @param method_name [Symbol] the name of the method
+    # @param _args[Array<Object>] the arguments of the method
     # This method smells of :reek:UtilityFunction
     def respond_to_missing?(method_name, *_args)
       PARSER_ACTIONS.key?(method_name)
     end
 
-    def ref_to_def(ref)
-      definitions.find { |definition| definition.reference == ref }
+    # @param reference [String] the  defintion from the reference
+    # @return [Definition] the defintion from the reference
+    def ref_to_def(reference)
+      definitions.find { |definition| definition.reference == reference }
     end
 
-    def iref=(value)
+    private
+
+    def has_iref=(value)
       @data.iref = value
     end
 
-    private
+    def do_parse(lines)
+      lines.each do |line|
+        if @parsing_state.enabled?(line)
+          apply_filters(line)
+        else
+          generate_event(:new_line, MatchingLine.new(nil, line))
+        end
+      end
+    end
 
     def apply_filters(line)
       Helper.reduce_filters_until_consumed(line) do |event, match, updated_line|
@@ -151,6 +160,9 @@ module DefMastership
 
     # Helper functions
     module Helper
+      # Helper function: apply all filters
+      #
+      # @param line [String] the line
       def self.reduce_filters_until_consumed(line)
         FILTERS.reduce(line) do |res, filter|
           next res unless line.match(filter.regexp)

data/lib/defmastership/export/body_formatter.rb

@@ -0,0 +1,55 @@
+# Copyright (c) 2020 Jerome Arbez-Gindre
+# frozen_string_literal: true
+
+require('defmastership/set_join_hack')
+
+module Defmastership
+  module Export
+    # format CSV lines per definition
+    class BodyFormatter
+      # @param doc [Document] the document to export
+      # @param definition [String] the definition to export
+      def initialize(doc, definition)
+        @doc = doc
+        @definition = definition
+      end
+
+      # @return [Array<String>] list of always available columns values
+      def fixed
+        [@definition.type, @definition.reference, @definition.value, @definition.sha256_short]
+      end
+
+      # @return [Array<String>] Optional wrong_explicit_checksum column value
+      def wrong_explicit_checksum
+        wrong_explicit_checksum = @definition.wrong_explicit_checksum
+        wrong_explicit_checksum ? [wrong_explicit_checksum] : ['']
+      end
+
+      # @return [Array<String>] Optional version column value
+      def explicit_version
+        explicit_version = @definition.explicit_version
+        explicit_version ? [explicit_version] : ['']
+      end
+
+      # @return [Array<String>] Optional labels columns values
+      def labels
+        [@definition.labels.join("\n")]
+      end
+
+      # @return [Array<String>] Optional external refs columns values
+      def eref
+        @doc.eref.map { |key,| @definition.eref.fetch(key, []).join("\n") }
+      end
+
+      # @return [Array<String>] Optional internal refs column value
+      def iref
+        [@definition.iref.join("\n")]
+      end
+
+      # @return [Array<String>] Optional attributes columns values
+      def attributes
+        @doc.attributes.map { |key,| @definition.attributes.fetch(key, '') }
+      end
+    end
+  end
+end

data/lib/defmastership/export/csv/formatter.rb

@@ -0,0 +1,64 @@
+# Copyright (c) 2020 Jerome Arbez-Gindre
+# frozen_string_literal: true
+
+require('csv')
+require('defmastership/export/body_formatter')
+require('defmastership/export/header_formatter')
+
+module Defmastership
+  # Module to host export classes
+  module Export
+    # Module to host CSV export classes
+    module CSV
+      # to export a CSV file
+      class Formatter
+        # @param doc [Document] the document to export
+        # @param sep [String] the CSV separator
+        def initialize(doc, sep)
+          @doc = doc
+          @sep = sep
+        end
+
+        # Export the document to a CSV file
+        #
+        # @param output_file [Strinf] filename for the export
+        def export_to(output_file)
+          column_list = build_column_list
+          ::CSV.open(output_file, 'w:ISO-8859-1', col_sep: @sep) do |csv|
+            csv << header(column_list)
+            export_definitions_in(csv, column_list)
+          end
+        end
+
+        private
+
+        def export_definitions_in(csv, column_list)
+          @doc.definitions.each { |definition| csv << body(definition, column_list) }
+        end
+
+        def header(column_list)
+          header_formatter = HeaderFormatter.new(@doc)
+          header_line = column_list.map { |part| header_formatter.public_send(part) }
+          header_line.flatten
+        end
+
+        def body(definition, column_list)
+          body_formatter = BodyFormatter.new(@doc, definition)
+          body_line = column_list.map { |part| body_formatter.public_send(part) }
+          body_line.flatten
+        end
+
+        def build_column_list
+          [
+            [:wrong_explicit_checksum, @doc.wrong_explicit_checksum?],
+            [:explicit_version, @doc.explicit_version?],
+            [:labels, !@doc.labels.empty?],
+            [:eref, !@doc.eref.empty?],
+            [:iref, @doc.iref],
+            [:attributes, !@doc.attributes.empty?]
+          ].reduce([:fixed]) { |acc, elem| acc + (elem.fetch(1) ? [elem.first] : []) }
+        end
+      end
+    end
+  end
+end

data/lib/defmastership/export/header_formatter.rb

@@ -0,0 +1,51 @@
+# Copyright (c) 2020 Jerome Arbez-Gindre
+# frozen_string_literal: true
+
+require('csv')
+
+module Defmastership
+  module Export
+    # format CSV header (first line) for one document
+    class HeaderFormatter
+      # @param doc [Document] the document to export
+      def initialize(doc)
+        @doc = doc
+      end
+
+      # @return [Array<String>] list of always available columns
+      def fixed
+        %w[Type Reference Value Checksum]
+      end
+
+      # @return [Array<String>] Optional wrong_explicit_checksum column caption
+      def wrong_explicit_checksum
+        @doc.wrong_explicit_checksum? ? ['Wrong explicit checksum'] : []
+      end
+
+      # @return [Array<String>] Optional version column captions
+      def explicit_version
+        @doc.explicit_version? ? ['Version'] : []
+      end
+
+      # @return [Array<String>] Optional labels columns captions
+      def labels
+        @doc.labels.empty? ? [] : %w[Labels]
+      end
+
+      # @return [Array<String>] Optional external refs columns captions
+      def eref
+        @doc.eref.map { |_, ref| ref.fetch(:prefix) }
+      end
+
+      # @return [Array<String>] Optional internal refs column caption
+      def iref
+        @doc.iref ? ['Internal links'] : []
+      end
+
+      # @return [Array<String>] Optional attributes columns captions
+      def attributes
+        @doc.attributes.map { |_, value| value }
+      end
+    end
+  end
+end

data/lib/defmastership/filters.rb

@@ -1,23 +1,26 @@
 # Copyright (c) 2020 Jerome Arbez-Gindre
 # frozen_string_literal: true
 
-module DefMastership
+require('defmastership/core/constants')
+
+# Main module of the application
+module Defmastership
   # Contains regexp / action couples
   Filter = Struct.new(:regexp, :event, :consumed_line)
   private_constant :Filter
 
   FILTERS = [
-    Filter.new(DMRegexp::VARIABLE_DEF,  :new_variable_def,     false),
-    Filter.new(DMRegexp::VARIABLE_USE,  :new_variable_use,     false),
-    Filter.new(DMRegexp::DEFINITION,    :new_definition,       true),
-    Filter.new(DMRegexp::EREF_CONFIG,   :new_eref_setup,       true),
-    Filter.new(DMRegexp::EREF_DEF,      :new_eref_def,         false),
-    Filter.new(DMRegexp::IREF_DEF,      :new_iref_def,         false),
-    Filter.new(DMRegexp::ATTR_CONFIG,   :new_attribute_conf,   true),
-    Filter.new(DMRegexp::ATTR_SET,      :new_attribute_value,  false),
-    Filter.new(DMRegexp::BLOCK,         :block_delimiter,      true),
-    Filter.new(DMRegexp::EMPTY_LINE,    :empty_line,           false),
-    Filter.new(DMRegexp::WHATEVER,      :new_line,             true)
+    Filter.new(Core::DMRegexp::VARIABLE_DEF,  :new_variable_def,     false),
+    Filter.new(Core::DMRegexp::VARIABLE_USE,  :new_variable_use,     false),
+    Filter.new(Core::DMRegexp::DEFINITION,    :new_definition,       true),
+    Filter.new(Core::DMRegexp::EREF_CONFIG,   :new_eref_setup,       true),
+    Filter.new(Core::DMRegexp::EREF_DEF,      :new_eref_def,         false),
+    Filter.new(Core::DMRegexp::IREF_DEF,      :new_iref_def,         false),
+    Filter.new(Core::DMRegexp::ATTR_CONFIG,   :new_attribute_conf,   true),
+    Filter.new(Core::DMRegexp::ATTR_SET,      :new_attribute_value,  false),
+    Filter.new(Core::DMRegexp::BLOCK,         :block_delimiter,      true),
+    Filter.new(Core::DMRegexp::EMPTY_LINE,    :empty_line,           false),
+    Filter.new(Core::DMRegexp::WHATEVER,      :new_line,             true)
   ].freeze
   private_constant :FILTERS
 end

data/lib/defmastership/matching_line.rb

@@ -1,10 +1,11 @@
 # Copyright (c) 2020 Jerome Arbez-Gindre
 # frozen_string_literal: true
 
-module DefMastership
-  # a composite class
+module Defmastership
+  # a composite class storing a line and the corresponding match
   MatchingLine =
     Struct.new(:match, :line) do
+      # Act as a Hasg and delegate to the Match
       def [](key)
         value = match[key]
         return value if value