dim-toolkit 2.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 2782516b43e4c6b75d4e810cb13dd1c110ab7f5f8f1eecbf29bfb530ec8d3a6b
+  data.tar.gz: 73c4f999afb166a82d584101f72aba0d6f170dc5981dff903deb77490c96abb8
+SHA512:
+  metadata.gz: 5674b913de138615cd8902896f24bea48d66df18a71c47af7ba282a39cd46907944447b7964537fc48d100364e972cca8aabede2754dd1e478f08f0698afc7f8
+  data.tar.gz: 1b693a54304ccbb093185444b32389e53788b87c3446812cd5fa49453898d3c53a60b4d327614671787f5bce5bc31ccf94d1dbbdb3ec1ebd0d27f7cf2f098637

data/bin/dim

@@ -0,0 +1,9 @@
+#!/usr/bin/env ruby
+
+$LOAD_PATH.unshift("#{File.dirname(__FILE__)}/../lib")
+
+require 'dim/encoding'
+require 'dim/ver'
+require 'dim'
+
+Dim.main

data/lib/dim/commands/check.rb

@@ -0,0 +1,13 @@
+require_relative '../globals'
+
+module Dim
+  class Check
+    SUBCOMMANDS['check'] = self
+
+    def initialize(_loader); end
+
+    def execute(silent: true)
+      # checks are always done after loading, so this is just a placeholder for command line option
+    end
+  end
+end

data/lib/dim/commands/export.rb

@@ -0,0 +1,145 @@
+require 'pathname'
+require 'digest'
+
+require_relative '../globals'
+require_relative '../exporter/exporterInterface'
+require_relative '../exporter/rst'
+require_relative '../exporter/csv'
+require_relative '../exporter/json'
+require_relative 'check'
+
+module Dim
+  class Export
+    SUBCOMMANDS['export'] = self
+
+    attr_accessor :file_list, :export_dir
+
+    def initialize(loader)
+      @loader = loader
+      @file_list = []
+      @export_dir = nil
+    end
+
+    def execute(silent: true)
+      @silent = silent
+      @loader.filter(OPTIONS[:filter]) unless OPTIONS[:filter].empty?
+
+      puts 'Exporting...' unless @silent
+      export
+      clean_destination
+      puts 'Done.' unless @silent
+    end
+
+    def copy_files(mod)
+      @loader.module_data[mod][:files].each do |f, list|
+        d = File.dirname(f)
+
+        list.uniq.each do |l|
+          src_pattern = File.join(d, l)
+          Dir.glob(src_pattern).each do |src|
+            src = Pathname.new(src).cleanpath.to_s
+            dst = File.join(OPTIONS[:folder], mod.sanitize, Pathname.new(src).relative_path_from(Pathname(d)))
+            @file_list << dst
+            FileUtils.mkdir_p(File.dirname(dst))
+
+            if File.exist?(dst)
+              md5_src = Digest::MD5.file(src)
+              md5_dst = Digest::MD5.file(dst)
+              next if md5_src == md5_dst
+            end
+
+            puts "Copying #{src} to #{dst}..." unless @silent
+            FileUtils.cp_r(src, dst)
+          end
+        end
+      end
+    end
+
+    def write_content(filename, content)
+      old_content = (File.exist?(filename) ? File.read(filename) : nil)
+      if content != old_content
+        File.write(filename, content)
+        puts ' done' unless @silent
+      else
+        puts ' skipped' unless @silent
+      end
+    end
+
+    def create_index(requirements_by_module)
+      return unless @exporter.hasIndex
+
+      files = {}
+      @loader.module_data.each do |mod, data|
+        next if requirements_by_module[mod].empty?
+
+        c = data[:category]
+        o = data[:origin]
+        files[c] ||= {}
+        files[c][o] ||= []
+        files[c][o] << mod
+      end
+      ind = 0
+      files.each do |category, data|
+        data.each do |origin, modules|
+          ind += 1
+          filename = "index_#{format('%03d', ind)}_#{category.downcase}_#{origin.downcase.sanitize}"
+          filepath = "#{OPTIONS[:folder]}/#{filename}.#{OPTIONS[:type]}"
+          file_list << filepath
+          new_content = StringIO.new
+          print "Creating #{filepath}..." unless @silent
+          @exporter.index(new_content, category, origin, modules)
+          write_content(filepath, new_content.string)
+        end
+      end
+    end
+
+    def export
+      requirements_by_module = {}
+      module_keys = @loader.module_data.keys
+      module_keys.each { |um| requirements_by_module[um] = [] }
+      @loader.requirements.each { |_id, r| requirements_by_module[r.document] << r }
+
+      @exporter = EXPORTER[OPTIONS[:type]].new(@loader)
+      requirements_by_module.each do |doc, reqs|
+        next if reqs.empty?
+
+        @export_dir = File.join(OPTIONS[:folder])
+        filename = File.join(export_dir, doc.sanitize, "Requirements.#{OPTIONS[:type]}")
+        file_list << filename
+        FileUtils.mkdir_p(File.dirname(filename))
+        copy_files(doc)
+
+        new_content = StringIO.new
+        print "Creating #{filename}..." unless @silent
+        @exporter.header(new_content)
+        @exporter.document(new_content, doc)
+        meta = @loader.metadata[doc]
+        @exporter.metadata(new_content, meta) if meta != ''
+        reqs.each do |r|
+          @exporter.requirement(new_content, r)
+        end
+        @exporter.footer(new_content)
+        write_content(filename, new_content.string)
+      end
+
+      create_index(requirements_by_module)
+    end
+
+    def clean_destination(dir_path = export_dir)
+      Dir.new(dir_path).children.each do |file|
+        dst = File.join(dir_path, file)
+        path = Pathname.new(dst)
+
+        clean_destination(dst) if path.directory?
+
+        next if file_list.include? dst
+
+        if path.directory?
+          path.rmdir if path.empty?
+        else
+          path.delete
+        end
+      end
+    end
+  end
+end

data/lib/dim/commands/format.rb

@@ -0,0 +1,198 @@
+require 'fileutils'
+
+require_relative '../globals'
+
+module Dim
+  class Format
+    SUBCOMMANDS['format'] = self
+    TARGET_WIDTH = 120
+    TARGET_WIDTH_ONE_LINER = 150
+    WIDTH_MIN = 50 # used when ID in one-liner or language-attr is very long
+
+    def initialize(loader)
+      @loader = loader
+    end
+
+    def short_type(type)
+      return "h#{type[8..]}" if /\Aheading_(\d+)\z/ === type
+
+      'info' # type == "information"
+    end
+
+    def create_string_array(val, line_width, line_width_first)
+      input = val.strip
+      return ['|'] + input.split("\n") if input.include?("\n")
+
+      if "#,[]{}&*!|>\)\"%@`'?:-".include?(input[0]) || input =~ /(:(\s|\Z)|\s#)/ || (input.length > line_width_first && input =~ /\s\s/)
+        return ['|', input] if input.length <= line_width_first
+
+        res = ['>']
+      else
+        res = []
+      end
+      until input.empty?
+        width = (res.empty? ? line_width_first : line_width)
+        if input.length <= width
+          res << input
+          break
+        end
+        pos = input[0, width + 2].rindex(/ \w/)
+        if pos
+          res << input[0, pos]
+          input = input[pos + 1..]
+        else
+          pos = input.index(/ \w/)
+          if pos
+            res << input[0, pos]
+            input = input[pos + 1..]
+          else
+            res << input
+            break
+          end
+        end
+      end
+      res
+    end
+
+    def dump(attr, val, shift, target_width = TARGET_WIDTH)
+      shift_first = [shift - attr.length, 0].max
+
+      line_width = [target_width - shift, WIDTH_MIN].max
+      line_width_first = [target_width - [shift, attr.length].max, WIDTH_MIN].max
+
+      array = create_string_array(val, line_width, line_width_first)
+      array[0] = attr + ' ' * shift_first + array[0]
+      (1..array.length - 1).each do |i|
+        array[i] = ' ' * shift + array[i]
+      end
+      array
+    end
+
+    def format_file(data)
+      io = StringIO.new
+
+      io.puts "document: #{data['document']}\n\n"
+
+      if data.key?('metadata') && !data['metadata'].empty?
+        io.puts dump('metadata: ', data['metadata'], 10)
+        io.puts "\n"
+      end
+
+      data.each do |id, req|
+        next if %w[module enclosed document].include? id
+
+        # do not write default values
+        next unless req.is_a?(Hash)
+
+        req.delete_if { |_key, value| value.nil? }
+
+        req.delete('test_setups')
+
+        %w[tags verification_methods refs].each do |e|
+          req[e] = req[e].cleanUniqString if req.key?(e) && req[e].is_a?(String)
+        end
+
+        # use oneliner style for headings and information if reasonable
+        if req.keys.length == 2 &&
+           %w[type text].all? { |e| req.key?(e) } &&
+           (req['type'] =~ /\Aheading_\d+\Z/ ||
+            req['type'] =~ /\Ainformation\Z/)
+          stripped = req['text'].strip
+          unless stripped.include?("\n")
+            one_liner = "#{short_type(req['type'])} #{req['text']}"
+            str = dump("#{id}: ", one_liner, Requirement::SYNTAX['text'][:format_shift], TARGET_WIDTH_ONE_LINER)
+            if str.length == 1
+              io.puts str
+              io.puts "\n"
+              next
+            end
+          end
+        end
+
+        io.puts "#{id}:"
+        @loader.all_attributes.each_key do |k|
+          next unless req.key?(k)
+
+          if req[k] && req[k].empty? || req[k].nil?
+            io.puts "  #{k}:"
+            next
+          end
+          shift = [@loader.all_attributes[k][:format_shift], k.length + 4].max
+          case @loader.all_attributes[k][:format_style]
+          when :single
+            shift_str = ' ' * [shift - (k.length + 4), 0].max
+            io.puts "  #{k}: #{shift_str}#{req[k].strip}"
+          when :multi
+            shift_str = ' ' * [shift - (k.length + 4), 0].max
+            io.puts "  #{k}: #{shift_str}#{req[k].cleanUniqString}"
+          when :list
+            io.puts dump("  #{k}: ", req[k].cleanUniqString, shift)
+          when :text
+            io.puts dump("  #{k}: ", req[k], shift)
+          when :split
+            arr = req[k].cleanUniqArray
+
+            if arr.length == 1
+              io.puts "  #{k}: #{shift_str}#{arr[0]}"
+            else
+              io.puts "  #{k}: #{shift_str}>"
+              shift_str = ' ' * shift
+              arr.each_with_index do |a, i|
+                io.puts "#{shift_str}#{a}#{i < arr.length - 1 ? ',' : ''}"
+              end
+            end
+          else
+            Dim::ExitHelper.exit(code: 1, msg: 'Invalid format style')
+          end
+        end
+
+        io.puts "\n"
+      end
+
+      if data.key?('enclosed')
+        a = Array(data['enclosed'])
+        if a.length == 1
+          io.puts "enclosed: #{a[0]}\n\n"
+        else
+          io.puts "enclosed:\n"
+          Array(data['enclosed']).each do |e|
+            io.puts "  - #{e}"
+          end
+          io.puts "\n"
+        end
+      end
+
+      io.truncate(io.length - 1) # do not print two line breaks at the end
+
+      io
+    end
+
+    def execute(silent: true)
+      puts OPTIONS[:output_format] == 'check-only' ? 'Checking format...' : 'Formatting...' unless silent
+
+      incorrect_files = []
+      @loader.original_data.each do |filename, data|
+        formatted_data = format_file(data).string
+        if OPTIONS[:output_format] == 'check-only'
+          original_data = File.read(filename).universal_newline
+          incorrect_files << filename if original_data != formatted_data
+        elsif OPTIONS[:output_format] == 'stdout'
+          puts formatted_data
+          next
+        else
+          output_filename = OPTIONS[:output_format] == 'extra' ? "#{filename}.formatted" : filename
+          File.write(output_filename, formatted_data)
+        end
+      end
+
+      unless incorrect_files.empty?
+        io = StringIO.new
+        io.puts 'The following files are not formatted correctly:'
+        io.puts(incorrect_files.map { |f| "- #{f}" })
+        Dim::ExitHelper.exit(code: 1, msg: io.string)
+      end
+
+      puts 'Done.' unless silent
+    end
+  end
+end

data/lib/dim/commands/stats.rb

@@ -0,0 +1,64 @@
+module Dim
+  class Stats
+    SUBCOMMANDS['stats'] = self
+
+    def initialize(loader)
+      @loader = loader
+    end
+
+    def execute(silent: true)
+      print_stats
+    end
+
+    def print_owner(type, module_name = nil)
+      if type == :all
+        top = 'ALL'
+        is_owner = proc { |_x| true }
+      else # :module
+        is_owner = proc { |x| x.document == module_name }
+        top = "DOCUMENT: #{module_name}"
+      end
+
+      puts "\n#{top}\n#{'-' * top.length}"
+      all_reqs = @loader.requirements.values
+      reqs_owner = all_reqs.select { |r| is_owner.call(r) }
+
+      num_files = if type == :module
+                    @loader.module_data[module_name][:files].length
+                  else
+                    @loader.module_data.values.map { |e| e[:files].keys }.flatten.length
+                  end
+      puts "Number of files: #{num_files}"
+
+      if type != :module
+        mods = reqs_owner.map(&:document).uniq
+        puts "Number of modules: #{mods.count}"
+      end
+
+      puts "Number of entries: #{reqs_owner.length}"
+      real_reqs_owner = reqs_owner.select { |r| r.data['type'] == 'requirement' }
+      puts "Requirements: #{real_reqs_owner.length}"
+      valid_reqs = real_reqs_owner.select { |r| r.data['status'] == 'valid' }
+      puts "Valid requirements: #{valid_reqs.length}"
+      accepted = valid_reqs.select { |r| r.data['review_status'] == 'accepted' }
+      puts "  Accepted: #{accepted.length}"
+      covered = accepted.select { |r| r.data['tags'].include?('covered') }
+      puts "    Covered: #{covered.length}"
+      not_covered_num = accepted.length - covered.length
+      puts "    Not covered: #{not_covered_num}"
+      rejected = valid_reqs.select { |r| r.data['review_status'] == 'rejected' }
+      puts "  Rejected: #{rejected.length}"
+      unclear = valid_reqs.select { |r| r.data['review_status'] == 'unclear' }
+      puts "  Unclear: #{unclear.length}"
+      not_reviewed = valid_reqs.select { |r| r.data['review_status'] == 'not_reviewed' }
+      puts "  Not reviewed: #{not_reviewed.length}"
+    end
+
+    def print_stats
+      @loader.requirements.values.map(&:document).uniq.each do |mod|
+        print_owner(:module, mod)
+      end
+      print_owner(:all)
+    end
+  end
+end

data/lib/dim/consistency.rb

@@ -0,0 +1,187 @@
+require_relative 'globals'
+require_relative 'exit_helper'
+
+module Dim
+  class Consistency
+    def initialize(loader)
+      @loader = loader
+    end
+
+    def cyclic_check(ref, previous_ref, checked_ids = {}, list = [])
+      return if checked_ids[ref.id]
+
+      # Circular dependency can occur only on same category level
+      return if previous_ref && (ref.category_level != previous_ref.category_level)
+
+      if list.include?(ref.id)
+        Dim::ExitHelper.exit(
+          code: 1,
+          filename: ref.filename,
+          msg: "\"#{ref.id}\" is cyclically referenced: #{list.join(' -> ')} -> #{ref.id}"
+        )
+      end
+
+      list << ref.id
+
+      ref.existingRefs.each do |ref_id|
+        cyclic_check(@loader.requirements[ref_id], ref, checked_ids, list)
+      end
+
+      list.pop
+
+      # Any value other than nil and false will work, as this is being used to check
+      # boolean condition on line#11
+      checked_ids[ref.id] = 1 if list.empty?
+    end
+    private :cyclic_check
+
+    def insert_default_values(req)
+      req.all_attributes.each do |key, config|
+        next if req.data.key?(key)
+
+        req.data[key] = config[:default]
+      end
+    end
+
+    def insert_property_file_definitions(ref)
+      @loader.property_table.fetch(ref.document, {}).each do |attr, value|
+        ref.data[attr] = value if ref.data[attr].nil?
+
+        if attr == 'test_setups' && (ref.data['verification_methods'].nil? || ref.data['verification_methods'] == '')
+          ref.data['verification_methods'] = value
+        end
+      end
+    end
+
+    def merge_test_setups_and_verification_methods(ref)
+      return if ref.data.key?('verification_methods') && !ref.data['verification_methods'].nil?
+
+      ref.data['verification_methods'] = ref.data['test_setups'].clone
+    end
+
+    def calculate_test_setups(ref)
+      return unless ref.data['test_setups'].nil?
+
+      tags = ref.data['tags'].cleanArray
+
+      ref.data['test_setups'] = if ref.data['type'] != 'requirement' || tags.include?('process')
+                                  'none'
+                                elsif ref.category == 'input' || ref.category == 'unspecified'
+                                  'none'
+                                elsif ref.category == 'module'
+                                  'off_target'
+                                elsif tags.include?('tool')
+                                  'off_target'
+                                else
+                                  'on_target'
+                                end
+    end
+
+    def calculate_verification_methods(ref)
+      return unless ref.data['verification_methods'].nil?
+
+      tags = ref.data['tags'].cleanArray
+
+      ref.data['verification_methods'] = if ref.data['type'] != 'requirement' || tags.include?('process')
+                                           'none'
+                                         elsif ref.category == 'input' || ref.category == 'unspecified'
+                                           'none'
+                                         elsif ref.category == 'module'
+                                           'off_target'
+                                         elsif tags.include?('tool')
+                                           'off_target'
+                                         else
+                                           'on_target'
+                                         end
+    end
+
+    def calculate_review_status(ref)
+      return unless ref.data['review_status'].nil?
+
+      ref.data['review_status'] = if ref.category == 'input' || ref.category == 'unspecified'
+                                    'not_reviewed'
+                                  else
+                                    'accepted'
+                                  end
+    end
+
+    def clean_comma_separated(ref)
+      %w[tags developer tester refs test_setups verification_methods].each do |var|
+        ref.data[var] = ref.data[var].cleanString
+      end
+    end
+
+    def calculate_developer_tester(ref)
+      %w[developer tester].each do |t|
+        next unless ref.data[t].nil?
+
+        ref.data[t] = if ref.data['type'] != 'requirement'
+                        ''
+                      elsif ref.data['tags'].cleanArray.include?('process') && t == 'tester'
+                        ''
+                      elsif ref.category == 'input' || ref.category == 'unspecified'
+                        ''
+                      else
+                        ref.origin
+                      end
+      end
+    end
+
+    def calculate_status(ref)
+      return unless ref.data['status'].nil?
+
+      ref.data['status'] = %w[requirement information].include?(ref.data['type']) ? 'draft' : 'valid'
+    end
+
+    def check(allow_missing:)
+      requirements_by_module = {}
+      @loader.module_data.keys.each { |um| requirements_by_module[um] = [] }
+      @loader.requirements.each { |_id, r| requirements_by_module[r.document] << r }
+
+      @loader.requirements.each do |_id, r|
+        insert_property_file_definitions(r)
+        insert_default_values(r)
+        merge_test_setups_and_verification_methods(r)
+        calculate_test_setups(r)
+        calculate_verification_methods(r)
+        calculate_review_status(r)
+        calculate_developer_tester(r)
+        calculate_status(r)
+      end
+
+      @loader.requirements.each do |_id, r|
+        clean_comma_separated(r)
+      end
+
+      @loader.requirements.each do |id, r|
+        r.data['refs'].cleanArray.each do |ref|
+          if !@loader.requirements.has_key?(ref)
+            unless allow_missing
+              Dim::ExitHelper.exit(
+                code: 1,
+                filename: r.filename,
+                msg: "\"#{id}\" refers to non-existing \"#{ref}\""
+              )
+            end
+          else
+            # Generate upstream and downstream refs based on category level
+            if @loader.requirements[id].category_level <= @loader.requirements[ref].category_level
+              @loader.requirements[id].downstreamRefs |= [ref]
+              @loader.requirements[ref].upstreamRefs |= [id]
+            else
+              @loader.requirements[id].upstreamRefs |= [ref]
+              @loader.requirements[ref].downstreamRefs |= [id]
+            end
+            @loader.requirements[ref].backwardRefs << id
+            r.existingRefs << ref
+          end
+        end
+      end
+
+      @checked_ids = {}
+      @loader.requirements.each do |_id, r|
+        cyclic_check(r, nil, @checked_ids)
+      end
+    end
+  end
+end

data/lib/dim/dimmain.rb

@@ -0,0 +1,28 @@
+$stdout.sync = true
+
+require 'yaml'
+
+require_relative 'globals'
+require_relative 'exit_helper'
+require_relative 'ext/string'
+require_relative 'loader'
+require_relative 'ver'
+require_relative 'requirement'
+require_relative 'commands/stats'
+require_relative 'commands/check'
+require_relative 'commands/export'
+require_relative 'commands/format'
+require_relative 'options'
+
+module Dim
+  def self.main(args = ARGV)
+    Dim::Options.parse(args)
+    loader = Dim::Loader.new
+    loader.load(file: OPTIONS[:input],
+                attributes_file: OPTIONS[:attributes],
+                allow_missing: OPTIONS[:allow_missing],
+                no_check_enclosed: OPTIONS[:no_check_enclosed] || false,
+                silent: OPTIONS[:silent] || false)
+    SUBCOMMANDS[OPTIONS[:subcommand]].new(loader).execute(silent: OPTIONS[:silent] || false)
+  end
+end

data/lib/dim/encoding.rb

@@ -0,0 +1,4 @@
+# This overwrites the configuration of local machines,
+# Dim shall read, process and write only UTF_8.
+Encoding.default_external = Encoding::UTF_8
+Encoding.default_internal = Encoding::UTF_8

data/lib/dim/exit_helper.rb

@@ -0,0 +1,23 @@
+module Dim
+  class ExitHelper
+    @exit_code = 0
+
+    class << self
+      def exit_code
+        @exit_code
+      end
+
+      def reset_exit_code
+        @exit_code = 0
+      end
+
+      def exit(msg:, code: 0, filename: nil)
+        @exit_code = code
+        inf = filename ? "in #{filename}: " : ''
+        pre = code.positive? ? 'Error: ' : ''
+        warn("#{pre}#{inf}#{msg}")
+        Kernel.exit(code)
+      end
+    end
+  end
+end