defmastership 1.0.19 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6075e9ff9eb3bb1d4080344f8288946ed3ae008c0ef7c943e558417ac1922084
-  data.tar.gz: 2707d0ef2c7ac04eb6fb5ff07362584243c3f8d7661a9e7f617d8239b79d162d
+  metadata.gz: 57c8ecae1a1c2e304a23c513b3a65b6c112da30ccaf75fb7f137f9247e9db36c
+  data.tar.gz: 2730ff7b5ef8838d4a131f182099479935ab347f0505b3a5518e6561bc30eb8c
 SHA512:
-  metadata.gz: 6670fef12836200db63e7bff8eec4afd5dad49e53a1d873b84816572933ca7fee2364076691f4e55d7858e3a49398b34d601f1c1ba6a7f05b9a8628b393acc03
-  data.tar.gz: e0169b605d73381d402c932cdd6387cb06cca5287364735c4a95c5fe5087845a24b4bc62018a87676510520db5ea6d656b4e1a9cb2e8586b772f6c0deae7f87f
+  metadata.gz: d4832d0e97edd679f51fe2223bf8eabe28c8e8e2dc14b9b994c055d24c31e14547b3db9fdb962abd843c86d9c370af1c3d3e662a52833260fc0b40b61f70ba7d
+  data.tar.gz: fdbfa9b7b031f10129cb5a7e12c9d3aee542ee86d1f56f406a3e05bd17297a20e99a8ec1ddf537bd61e2f128a0d6d764bdd47659d48e2c9e8166b603bc1ca6df

data/.gitignore

@@ -6,3 +6,6 @@ defmastership-0.0.1.gem
 /Gemfile.lock
 /pkg/
 /.ruby-version
+/doc/
+/.yardoc/
+/whatever

data/.gitlab-ci.yml

@@ -12,15 +12,29 @@ default:
 bdd:
   script:
     - bundle exec rake test:features
+  artifacts:
+    paths:
+      - features_results.html
 
 unit tests:
   script:
     - bundle exec rake test:spec
+  artifacts:
+    paths:
+      - rspec_results.html
+      - coverage/*
 
 code_quality:
   script:
     - bundle exec rake quality:all
 
+yard documentation:
+  script:
+    - bundle exec rake yard
+  artifacts:
+    paths:
+      - doc
+
 bdd ruby2.7:
   image: ruby:2.7
   before_script:
@@ -75,3 +89,16 @@ unit tests ruby3.2:
   script:
     - bundle exec rake test:spec
 
+pages:
+  stage: deploy
+  script:
+    - mkdir public
+    - cp -r doc/* public
+    - cp "features_results.html" public
+    - cp "rspec_results.html" public
+    - cp -r "coverage" public
+  artifacts:
+    paths:
+      - public
+  only:
+    - master

data/Gemfile

@@ -10,9 +10,9 @@ ruby RUBY_VERSION
 # rubocop:disable Metrics/BlockLength
 group :development do
   # cucumber steps for command line tests
-  gem 'aruba',                 '~> 2.2'
+  gem 'aruba',                 '~> 2'
   # bdd
-  gem 'cucumber',              '~> 9.2'
+  gem 'cucumber',              '~> 9'
 
   # code duplication
   gem 'flay',                  '~> 2'
@@ -36,40 +36,51 @@ group :development do
     key = '7oac4dMz95cTUuFPtGDfTDSQep6ZhdGW'
     source "https://#{plan}:#{key}@gem.mutant.dev" do
       # license needed
-      gem 'mutant-license', '~> 0.1.1'
+      gem 'mutant-license', '~> 0'
     end
     # mutation testing
-    gem 'mutant-rspec', '~> 0.11'
+    gem 'mutant-rspec', '~> 0'
   end
   # to parse and execute Rakefile
-  gem 'rake',                  '~> 13.1'
+  gem 'rake', '~> 13'
+
+  if RUBY_VERSION >= '3.0'
+    # needed by yard to render documentation
+    gem 'rdoc', '~> 6'
+  end
   # tdd
-  gem 'rspec',                 '~> 3.13'
+  gem 'rspec',                 '~> 3'
   # # to test performances
-  # gem 'rspec-benchmark',       '~> 0.6.0'
+  # gem 'rspec-benchmark',       '~> 0'
   # code needs to be clean
-  gem 'rubocop',               '~> 1.65'
+  gem 'rubocop',               '1.68'
   # code needs to be clean
-  gem 'rubocop-performance',   '~> 1.21'
+  gem 'rubocop-performance',   '~> 1'
   # test code needs to be clean
-  gem 'rubocop-rspec',         '~> 3.0'
+  gem 'rubocop-rspec',         '~> 3'
   # Rakefiles need to be clean
-  gem 'rubocop-rake',          '~> 0.6'
+  gem 'rubocop-rake',          '~> 0'
+
   if RUBY_VERSION >= '3.0'
     # detect selling code
-    gem 'reek', '~> 6.3'
+    gem 'reek', '~> 6'
     # my code needs to be critiqued
     gem 'rubycritic', '~> 4'
+    # Doc need to be clean
+    gem 'rubocop-yard', '~> 0'
   end
 
   # What is tdd without code coverage ?
-  gem 'simplecov', '~> 0.22', '< 0.23'
-  # # to document code
-  # gem 'yard',                  '~> 0.9.5'
+  gem 'simplecov', '~> 0'
+
+  if RUBY_VERSION >= '3.0'
+    # to document code
+    gem 'yard', '~> 0'
+  end
 end
 # rubocop:enable Metrics/BlockLength
 
 group :debugging do
   # Sometimes, we need to debug
-  gem 'pry', '~> 0.14'
+  gem 'pry', '~> 0'
 end

data/LICENSE

@@ -1,7 +1,7 @@
 MIT License
 
 Copyright (c) 2020 Jérôme Arbez-Gindre, and the individual contributors
-to DefMastership.
+to Defmastership.
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.adoc

@@ -0,0 +1,24 @@
+= defmastership
+
+== Features
+
+* CSV export of https://gitlab.com/defmastership/asciidoctor-defmastership[asciidoctor-defmastership] statements.
+* Automatic modifications of asciidoc files for : (See https://defmastership.gitlab.io/defmastership-example/defmastership-example.pdf/#_automatic_modifications[list of modifications].)
+** Computation of definitions reference ids
+** Explicit checksums updates
+** Explicit version updates (note: defmastership-examples not updated with last feature modification)
+
+NOTE: depend on https://gitlab.com/defmastership/defmastership-core[defmastership-core]
+
+== Development method
+
+* BDD:
+** https://gitlab.com/defmastership/defmastership/-/tree/master/features[features].
+** https://defmastership.gitlab.io/defmastership/features_results.html[features_results.html]
+
+* TDD:
+** https://gitlab.com/defmastership/defmastership/-/tree/master/spec/unit/defmastership?ref_type=heads[unit tests (rspec)]
+** https://defmastership.gitlab.io/defmastership/rspec_results.html[rspec_results.html]
+** https://defmastership.gitlab.io/defmastership/coverage[Unit tests coverage]
+
+

data/Rakefile

@@ -1,7 +1,6 @@
 # Copyright (c) 2023 Jerome Arbez-Gindre
 # frozen_string_literal: true
 
-require('bundler/gem_tasks')
 require('rake/clean')
 
 Dir['tasks/**/*.rake'].each { |t| load t }

data/bin/defmastership

@@ -6,14 +6,14 @@ require('csv')
 require('defmastership')
 require('gli')
 
-module DefMastership
+module Defmastership
   # The start of everything !
   class App
     extend GLI::App
 
     program_desc 'Tool to handle Asciidoctor definition extension'
 
-    version DefMastership::VERSION
+    version Defmastership::VERSION
 
     subcommand_option_handling :normal
     arguments :strict
@@ -54,12 +54,12 @@ module DefMastership
       c.switch(%i[no-fail], desc: 'Exit succes even in case of wrong explicit checksum')
 
       c.action do |_global_options, options, args|
-        my_doc = DefMastership::Document.new
+        my_doc = Defmastership::Document.new
         my_doc.parse_file_with_preprocessor(args.first)
 
         output_file = args.first.sub(/\.adoc$/, '.csv')
 
-        DefMastership::CSVFormatter.new(my_doc, options['separator']).export_to(output_file)
+        Defmastership::Export::CSV::Formatter.new(my_doc, options['separator']).export_to(output_file)
 
         if my_doc.wrong_explicit_checksum?
           my_doc.definitions.each do |definition|
@@ -112,4 +112,4 @@ module DefMastership
   end
 end
 
-exit(DefMastership::App.run(ARGV))
+exit(Defmastership::App.run(ARGV))

data/config/mutant.yml

@@ -11,20 +11,22 @@ requires:
   - defmastership
 matcher:
   subjects:
-    - 'DefMastership*'
-  # ignore:
-  #   - 'DefMastership::BatchModifier*'
-  #   - 'DefMastership::CSVFormatter*'
-  #   - 'DefMastership::CSVFormatterBody*'
-  #   - 'DefMastership::CSVFormatterHeader*'
-  #   - 'DefMastership::ChangeRefModifier*'
-  #   - 'DefMastership::Definition*'
-  #   - 'DefMastership::Document*'
-  #   - 'DefMastership::Modifier*'
-  #   - 'DefMastership::ModifierFactory*'
-  #   - 'DefMastership::ParsingState*'
-  #   - 'DefMastership::RenameIncludedFilesModifier*'
-  #   - 'DefMastership::UpdateDefChecksumModifier*'
-  #   - 'DefMastership::UpdateDefModifier*'
-  #   - 'DefMastership::UpdateDefVersionModifier*'
+    - Defmastership*
+  ignore:
+    - Defmastership::Core*
+  #   - Defmastership::BatchModifier*
+  #   - Defmastership::Export::CSV::Formatter*
+  #   - Defmastership::Export::CSV::BodyFormatter*
+  #   - Defmastership::Export::CSV::HeaderFormatter*
+  #   - Defmastership::Modifier::ChangeRef*
+  #   - Defmastership::Definition*
+  #   - Defmastership::DefinitionParser*
+  #   - Defmastership::Document*
+  #   - Defmastership::Factory*
+  #   - Defmastership::Modifier::ModifierCommon*
+  #   - Defmastership::Modifier::Factory*
+  #   - Defmastership::Modifier::RenameIncludedFiles*
+  #   - Defmastership::Modifier::UpdateDefChecksum*
+  #   - Defmastership::Modifier::UpdateDef*
+  #   - Defmastership::Modifier::UpdateDefVersion*
 # fail_fast: true

data/config/rubocop.yml

@@ -13,6 +13,7 @@ require:
   - rubocop-performance
   - rubocop-rspec
   - rubocop-rake
+  - rubocop-yard
 
 AllCops:
   TargetRubyVersion: 2.7
@@ -34,10 +35,10 @@ Style/StringHashKeys :
   Enabled: true
   Exclude:
     - '*.gemspec'
-    - 'spec/unit/def_mastership/batch_modifier_spec.rb'
-    - 'spec/unit/def_mastership/update_def_checksum_modifier_spec.rb'
-    - 'spec/unit/def_mastership/update_def_modifier_spec.rb'
-    - 'spec/unit/def_mastership/update_def_version_modifier_spec.rb'
+    - 'spec/unit/defmastership/batch_modifier_spec.rb'
+    - 'spec/unit/defmastership/modifier/update_def_checksum_spec.rb'
+    - 'spec/unit/defmastership/modifier/update_def_spec.rb'
+    - 'spec/unit/defmastership/modifier/update_def_version_spec.rb'
 
 Style/MissingElse:
   EnforcedStyle: case
@@ -55,12 +56,6 @@ Security/Eval :
   Exclude:
     - 'Rakefile'
 
-Style/ConstantVisibility :
-  Exclude:
-     # there is one unique explicit constant visibility for all
-     # constants
-    - 'lib/defmastership/constants.rb'
-
 # rubocop-rspec options
 RSpec/MessageExpectation :
   Enabled: true

data/defmastership.gemspec

@@ -20,7 +20,7 @@ Gem::Specification.new do |spec|
   }
   spec.required_ruby_version = '>= 2.7'
   spec.name = 'defmastership'
-  spec.version = DefMastership::VERSION
+  spec.version = Defmastership::VERSION
   spec.author = 'Jérôme Arbez-Gindre'
   spec.email = 'jeromearbezgindre@gmail.com'
   spec.licenses = ['MIT']
@@ -29,13 +29,13 @@ Gem::Specification.new do |spec|
   spec.summary = 'Handling of references and definitions with asciidoctor'
   spec.files = `git ls-files`.split("\n")
   spec.require_paths << 'lib'
-  spec.extra_rdoc_files = ['README.rdoc', 'defmastership.rdoc']
-  spec.rdoc_options << '--title defmastership' << '--main README.rdoc' << '-ri'
   spec.bindir = 'bin'
   spec.executables << 'defmastership'
   spec.add_dependency('aasm', '~> 5')
   spec.add_dependency('asciidoctor', '~> 2')
   spec.add_dependency('csv', '~> 3')
+  spec.add_dependency('defmastership-core', '>= 1.1.0')
   spec.add_dependency('git', '~> 1')
   spec.add_dependency('gli', '~> 2')
+  spec.add_dependency('ostruct', '~> 0')
 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
 
+    # 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,
@@ -37,9 +39,9 @@ module DefMastership
       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
     },
@@ -54,7 +56,7 @@ module DefMastership
     },
     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]
 
@@ -75,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
@@ -112,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
 
+    # @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|
@@ -143,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