Almirah 0.3.1 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: be9e792ca43617f09611a801b8e8c8efde741ec531a97295de8d65378232c0d2
-  data.tar.gz: 492000cb9aadaf0731e077b46ec3a32b573da9c8cd2acfaff6f282dec75c394d
+  metadata.gz: b3c6b1d68ee25c9b62690c4cdda45ec2d790960a6e75762576ddc60d6c3136e5
+  data.tar.gz: 334ef7251595119cd27bf980eeb53a8f02d913cde7d2fc5d0844a1d863b6c825
 SHA512:
-  metadata.gz: 51e65415ee9d0a8c0f77d19d21ab525a01cbc4c025bc5572f92f2df13bc56ceed8b04be5e18d3c0308c468c43986dd267046d9b1c125e281ad01476b08a93569
-  data.tar.gz: b64d9b5a0da5d254ecbc6dd861db05017b8cd81e13c0f58071413816d9b20d879187cbda5b2a703d5eae9f92ec044000010fc6b1b103fa30a9de04b265562cde
+  metadata.gz: 20383b85a3d59d35a3c6259095e7e8b6709055b6670e2b651fdecdd814eee54b71ebf7d2cc1958c85bc998a426361dfff470c1c10749044334ae7ec7f1a69616
+  data.tar.gz: d1d066ecfc0cfe644eaa28f42d793342e328f42d3eefc0e1fdeb2290c8ff281009bd59b99d23893604f89927ab698a922ef844af1e702c45a3a0a5d51926ff84

data/lib/almirah/doc_fabric.rb

@@ -5,6 +5,8 @@ require_relative 'doc_types/protocol'
 require_relative 'doc_types/coverage'
 require_relative 'doc_types/implementation'
 require_relative 'doc_types/traceability'
+require_relative 'doc_types/decision'
+require_relative 'doc_types/decisions_overview'
 require_relative 'doc_parser'
 require_relative 'source_file_parser'
 require_relative 'dom/document'
@@ -64,6 +66,19 @@ class DocFabric
     doc
   end
 
+  def self.create_decision(path)
+    doc = Decision.new path
+    DocFabric.parse_document doc
+    doc.extract_current_status
+    doc.extract_start_date
+    doc.extract_target_release_version
+    doc
+  end
+
+  def self.create_decisions_overview(project)
+    DecisionsOverview.new project
+  end
+
   def self.create_source_file(repository_path, path, repository_name)
     doc = SourceFile.new repository_path, path, repository_name
     DocFabric.parse_source_file doc
@@ -78,7 +93,7 @@ class DocFabric
     DocParser.parse(doc, file_lines)
 
     # Build dom
-    doc.dom = Document.new(doc.headings) if doc.is_a?(Specification) || doc.is_a?(Protocol)
+    doc.dom = Document.new(doc.headings) if doc.is_a?(Specification) || doc.is_a?(Protocol) || doc.is_a?(Decision)
   end
 
   def self.parse_source_file(doc)

data/lib/almirah/doc_items/controlled_paragraph.rb

@@ -2,7 +2,7 @@ require_relative 'paragraph'
 
 # <REQ> Implementa a controlled paragraph as a subclass of the DocItem >[SRS-001] </REQ>
 class ControlledParagraph < Paragraph
-  attr_accessor :id, :up_link_ids, :down_links, :coverage_links, :source_code_links
+  attr_accessor :id, :up_link_ids, :down_links, :coverage_links, :source_code_links, :decision_record_links
 
   def initialize(doc, text, id)
     super(doc, text)
@@ -12,6 +12,7 @@ class ControlledParagraph < Paragraph
     @down_links = nil
     @coverage_links = nil
     @source_code_links = nil
+    @decision_record_links = nil
   end
 
   def to_html
@@ -19,7 +20,7 @@ class ControlledParagraph < Paragraph
     unless @@html_table_render_in_progress
       s += "<table class=\"controlled\">\n"
       s += "\t<thead> <th>#</th> <th></th> <th title=\"Up-links\">UL</th> <th title=\"Down-links\">DL</th> \
-        <th title=\"Test Coverage\">COV</th> </thead>\n"
+        <th title=\"Test Coverage\">COV</th> <th title=\"Decision Record\">DR</th> </thead>\n"
       @@html_table_render_in_progress = true # rubocop:disable Style/ClassVars
     end
     f_text = format_string(@text)
@@ -108,6 +109,31 @@ class ControlledParagraph < Paragraph
     else
       s += "\t\t<td class=\"item_id\"></td>\n"
     end
+
+    if @decision_record_links
+      if @decision_record_links.length == 1
+        dr_doc = @decision_record_links[0].parent_doc
+        s += "\t\t<td class=\"item_id\">\
+            <a href=\"./../../decisions/#{dr_doc.html_rel_path}\" \
+            class=\"external\" title=\"Decision Record\">#{dr_doc.id.upcase}</a></td>\n"
+      else
+        s += "\t\t<td class=\"item_id\">"
+        s += "<div id=\"DR_#{@id}\" style=\"display: block;\">"
+        s += "<a  href=\"#\" onclick=\"decisionLink_OnClick(this.parentElement); return false;\" \
+            class=\"external\" title=\"Number of decision records\">#{@decision_record_links.length}</a>"
+        s += '</div>'
+        s += "<div id=\"DRS_#{@id}\" style=\"display: none;\">"
+        @decision_record_links.each do |lnk|
+          dr_doc = lnk.parent_doc
+          s += "\t\t\t<a href=\"./../../decisions/#{dr_doc.html_rel_path}\" \
+            class=\"external\" title=\"Referenced in\">#{dr_doc.id.upcase}</a>\n<br>"
+        end
+        s += '</div>'
+        s += "</td>\n"
+      end
+    else
+      s += "\t\t<td class=\"item_id\"></td>\n"
+    end
     s += "\t</tr>\n"
     s
   end

data/lib/almirah/doc_items/controlled_table.rb

@@ -101,13 +101,14 @@ class TestStepReferenceColumn < ControlledTableColumn # rubocop:disable Style/Do
 
   def to_html # rubocop:disable Metrics/AbcSize,Metrics/MethodLength
     s = ''
+    specifications_path = @parent_row.parent_doc.specifications_path
     if @up_link_ids
       if @up_link_ids.length == 1
         if tmp = /^([a-zA-Z]+)-\d+/.match(@up_link_ids[0])
           up_link_doc_name = tmp[1].downcase
         end
         s += "\t\t<td class=\"item_id\" style=\"text-align: center;\">\
-                    <a href=\"./../../../specifications/#{up_link_doc_name}/#{up_link_doc_name}.html##{@up_link_ids[0]}\" \
+                    <a href=\"#{specifications_path}#{up_link_doc_name}/#{up_link_doc_name}.html##{@up_link_ids[0]}\" \
                     class=\"external\" title=\"Linked to\">#{@up_link_ids[0]}</a></td>\n"
       else
         s += "\t\t<td class=\"item_id\" style=\"text-align: center;\">"
@@ -120,7 +121,7 @@ class TestStepReferenceColumn < ControlledTableColumn # rubocop:disable Style/Do
           if tmp = /^([a-zA-Z]+)-\d+/.match(lnk)
             up_link_doc_name = tmp[1].downcase
           end
-          s += "\t\t\t<a href=\"./../../../specifications/#{up_link_doc_name}/#{up_link_doc_name}.html##{lnk}\" \
+          s += "\t\t\t<a href=\"#{specifications_path}#{up_link_doc_name}/#{up_link_doc_name}.html##{lnk}\" \
                     class=\"external\" title=\"Verifies\">#{lnk}</a>\n<br>"
         end
         s += '</div>'
@@ -184,7 +185,7 @@ class ControlledTable < DocItem # rubocop:disable Style/Documentation
           end
         end
 
-      elsif index + 2 == columns.length # it is expected that test step result is placed to the pre-last column only
+      elsif (index + 2 == columns.length) && @parent_doc.instance_of?(Protocol) # test step result column applies only to Protocols
 
         col = TestStepResultColumn.new element
         new_row.columns.append col

data/lib/almirah/doc_items/markdown_list.rb

@@ -73,7 +73,7 @@ class MarkdownList < DocItem
     s.each_char do |c|
       case state
       when 'looking_for_list_item_marker'
-        if c == '*'
+        if c == '*' || c == '-'
           state = 'looking_for_space'
         elsif numeric?(c)
           state = 'looking_for_dot'
@@ -106,7 +106,7 @@ class MarkdownList < DocItem
   end
 
   def self.unordered_list_item?(raw_text)
-    res = /(\*\s?)(.*)/.match(raw_text)
+    res = /^\s*([*\-]\s+)(.*)/.match(raw_text)
     return true if res
 
     false

data/lib/almirah/doc_items/markdown_table.rb

@@ -3,9 +3,10 @@
 require_relative 'doc_item'
 
 class MarkdownTable < DocItem
-  attr_accessor :column_names, :rows, :heading_row, :is_separator_detected, :column_aligns
+  attr_accessor :column_names, :rows, :heading_row, :is_separator_detected, :column_aligns,
+                :is_decision_status_table
 
-  def initialize(doc, heading_row)
+  def initialize(doc, heading_row) # rubocop:disable Metrics/MethodLength
     super(doc)
     @heading_row = heading_row
 
@@ -18,6 +19,7 @@ class MarkdownTable < DocItem
     @rows = []
     @is_separator_detected = false
     @column_aligns = []
+    @is_decision_status_table = false
   end
 
   def add_separator(line)
@@ -69,10 +71,17 @@ class MarkdownTable < DocItem
     s += " </thead>\n"
 
     @rows.each do |row|
-      s += "\t<tr>\n"
+      tr_class = if @is_decision_status_table && row[0].to_s.strip == '*'
+                   ' class="current_status"'
+                 else
+                   ''
+                 end
+      s += "\t<tr#{tr_class}>\n"
       row.each_with_index do |col, index|
-        if col.to_i.positive? && col.to_i.to_s == col  # autoalign cells with numbers
-          s += "\t\t<td style=\"text-align: center;\">#{col}</td>\n"
+        cell = col
+        cell = '▶' if @is_decision_status_table && index.zero? && col.strip == '*'
+        if cell.to_i.positive? && cell.to_i.to_s == cell  # autoalign cells with numbers
+          s += "\t\t<td style=\"text-align: center;\">#{cell}</td>\n"
         else
           align = ''
           case @column_aligns[index]
@@ -83,7 +92,7 @@ class MarkdownTable < DocItem
           when 'center'
             align = 'style="text-align: center;"'
           end
-          f_text = format_string(col)
+          f_text = format_string(cell)
           s += "\t\t<td #{align}>#{f_text}</td>\n"
         end
       end

data/lib/almirah/doc_items/text_line.rb

@@ -1,3 +1,5 @@
+require 'cgi'
+
 class TextLineToken
   attr_accessor :value
 
@@ -54,14 +56,27 @@ class SquareBracketRightAndParentheseLeft < TextLineToken
   end
 end
 
+class BacktickToken < TextLineToken
+  def initialize # rubocop:disable Lint/MissingSuper
+    @value = '`'
+  end
+end
+
+class InlineCodeToken < TextLineToken
+  def initialize(raw) # rubocop:disable Lint/MissingSuper
+    @value = raw
+  end
+end
+
 class TextLineParser
   attr_accessor :supported_tokens
 
-  def initialize # rubocop:disable Metrics/AbcSize
+  def initialize # rubocop:disable Metrics/AbcSize,Metrics/MethodLength
     @supported_tokens = []
     @supported_tokens.append(BoldAndItalicToken.new)
     @supported_tokens.append(BoldToken.new)
     @supported_tokens.append(ItalicToken.new)
+    @supported_tokens.append(BacktickToken.new)
     @supported_tokens.append(SquareBracketRightAndParentheseLeft.new)
     @supported_tokens.append(ParentheseLeft.new)
     @supported_tokens.append(ParentheseRight.new)
@@ -70,7 +85,7 @@ class TextLineParser
     @supported_tokens.append(TextLineToken.new)
   end
 
-  def tokenize(str)
+  def tokenize(str) # rubocop:disable Metrics/MethodLength,Metrics/CyclomaticComplexity,Metrics/AbcSize,Metrics/PerceivedComplexity
     result = []
     sl = str.length
     si = 0
@@ -79,29 +94,110 @@ class TextLineParser
         tl = t.value.length
         if tl != 0 # literal is the last supported token in the list
           projected_end_position = si + tl - 1
-          next if projected_end_position > sl
+          next if projected_end_position >= sl
 
           buf = str[si..projected_end_position]
-          if buf == t.value
+          next unless buf == t.value
+
+          if emphasis_token?(t) && !can_flank?(str, si, projected_end_position)
+            append_literal(result, buf)
+          else
             result.append(t)
-            si = projected_end_position + 1
-            break
           end
+          si = projected_end_position + 1
+          break
         else
-          if result.length.positive? && (result[-1].instance_of? TextLineToken)
-            literal = result[-1]
-            literal.value += str[si]
-          else
-            literal = TextLineToken.new
-            literal.value = str[si]
-            result.append(literal)
-          end
+          append_literal(result, str[si])
           si += 1
         end
       end
     end
+    fuse_backticks(result)
+  end
+
+  private
+
+  def fuse_backticks(tokens) # rubocop:disable Metrics/MethodLength,Metrics/AbcSize
+    result = []
+    i = 0
+    while i < tokens.length
+      if tokens[i].instance_of?(BacktickToken)
+        closer = next_backtick_index(tokens, i + 1)
+        if closer
+          raw = tokens[(i + 1)..(closer - 1)].map(&:value).join
+          result.append(InlineCodeToken.new(raw))
+          i = closer + 1
+        else
+          append_literal(result, '`')
+          i += 1
+        end
+      else
+        result.append(tokens[i])
+        i += 1
+      end
+    end
     result
   end
+
+  def next_backtick_index(tokens, start_idx)
+    idx = start_idx
+    while idx < tokens.length
+      return idx if tokens[idx].instance_of?(BacktickToken)
+
+      idx += 1
+    end
+    nil
+  end
+
+  def emphasis_token?(token)
+    token.is_a?(ItalicToken) || token.is_a?(BoldToken) || token.is_a?(BoldAndItalicToken)
+  end
+
+  def append_literal(result, text)
+    if !result.empty? && result[-1].instance_of?(TextLineToken)
+      result[-1].value += text
+    else
+      literal = TextLineToken.new
+      literal.value = text.dup
+      result.append(literal)
+    end
+  end
+
+  def can_flank?(str, start_idx, end_idx)
+    left_flanking?(str, start_idx, end_idx) || right_flanking?(str, start_idx, end_idx)
+  end
+
+  def left_flanking?(str, start_idx, end_idx)
+    after = char_at(str, end_idx + 1)
+    return false if after.nil? || whitespace?(after)
+    return true unless punctuation?(after)
+
+    before = char_at(str, start_idx - 1)
+    before.nil? || whitespace?(before)
+  end
+
+  def right_flanking?(str, start_idx, end_idx)
+    before = char_at(str, start_idx - 1)
+    return false if before.nil? || whitespace?(before)
+    return true unless punctuation?(before)
+
+    after = char_at(str, end_idx + 1)
+    after.nil? || whitespace?(after)
+  end
+
+  def char_at(str, idx)
+    return nil if idx.negative? || idx >= str.length
+
+    str[idx]
+  end
+
+  def whitespace?(char)
+    char.match?(/\s/)
+  end
+
+  def punctuation?(char)
+    char.match?(/[[:punct:]]/)
+  end
 end
 
 class TextLineBuilderContext
@@ -117,6 +213,10 @@ class TextLineBuilderContext
     str
   end
 
+  def inline_code(str)
+    str
+  end
+
   def link(_link_text, link_url)
     link_url
   end
@@ -230,6 +330,9 @@ class TextLineBuilder
           ti = ti_starting_position + 1
         end
 
+      when 'InlineCodeToken'
+        result += @builder_context.inline_code(token_list[ti].value)
+        ti += 1
       when 'TextLineToken', 'ParentheseLeft', 'ParentheseRight', 'SquareBracketRight'
         result += token_list[ti].value
         ti += 1
@@ -267,6 +370,10 @@ class TextLine < TextLineBuilderContext
     "<b><i>#{str}</i></b>"
   end
 
+  def inline_code(str)
+    "<code class=\"inline\">#{CGI.escapeHTML(str)}</code>"
+  end
+
   def link(link_text, link_url)
     # define default result first
     result = "<a target=\"_blank\" rel=\"noopener\" href=\"#{link_url}\" class=\"external\">#{link_text}</a>"

data/lib/almirah/doc_parser.rb

@@ -174,7 +174,7 @@ class DocParser # rubocop:disable Metrics/ClassLength,Style/Documentation
 
           doc.items.append(item)
 
-        elsif res = /^(\*\s+)(.*)/.match(s) # check if unordered list start
+        elsif res = /^([*\-]\s+)(.*)/.match(s) # check if unordered list start
 
           if doc.title == ''
             # dummy section if root is not a Document Title (level 0)
@@ -248,8 +248,9 @@ class DocParser # rubocop:disable Metrics/ClassLength,Style/Documentation
 
             if temp_md_table
               if temp_md_table.is_separator_detected # if there is a separator
-                # check if parent doc is a Protocol
-                if doc.instance_of? Protocol
+                # check if parent doc is a Protocol, or a Decision Record inside an "Affected Documents" section
+                if doc.instance_of?(Protocol) ||
+                   (doc.instance_of?(Decision) && in_section?(doc, 'Affected Documents'))
                   # check if it is a controlled table
                   tmp = /(.*)\s+>\[(\S*)\]/.match(row)
                   if tmp && (temp_md_table.instance_of? MarkdownTable)
@@ -379,4 +380,20 @@ class DocParser # rubocop:disable Metrics/ClassLength,Style/Documentation
     end
     temp_md_table
   end
+
+  # Returns true when the most recently parsed heading is inside (or equal to) a section
+  # whose heading text matches `section_name`. Walks back through the heading list
+  # accumulating the ancestor chain (strictly decreasing levels).
+  def self.in_section?(doc, section_name)
+    return false if doc.headings.empty?
+
+    last_level = doc.headings[-1].level + 1
+    doc.headings.reverse_each do |h|
+      next if h.level >= last_level
+
+      last_level = h.level
+      return true if h.text.strip == section_name
+    end
+    false
+  end
 end

data/lib/almirah/doc_types/base_document.rb

@@ -3,6 +3,10 @@
 class BaseDocument # rubocop:disable Style/Documentation
   attr_accessor :title, :id, :dom, :headings
 
+  class << self
+    attr_accessor :show_decisions_link
+  end
+
   def initialize
     @items = []
     @headings = []
@@ -21,6 +25,10 @@ class BaseDocument # rubocop:disable Style/Documentation
 
     output_file_path += if @id == 'index'
                           "#{@id}.html"
+                        elsif instance_of? DecisionsOverview
+                          'overview.html'
+                        elsif instance_of? Decision
+                          "#{@id}.html"
                         else
                           "#{@id}/#{@id}.html"
                         end
@@ -55,14 +63,30 @@ class BaseDocument # rubocop:disable Style/Documentation
         elsif instance_of? Protocol
           file.puts '<link rel="stylesheet" href="../../../css/main.css">'
           file.puts '<script src="../../../scripts/main.js"></script>'
+        elsif instance_of? DecisionsOverview
+          file.puts '<link rel="stylesheet" href="../css/main.css">'
+          file.puts '<script src="../scripts/main.js"></script>'
+          file.puts '<script src="https://cdn.jsdelivr.net/npm/chart.js"></script>'
+        elsif instance_of? Decision
+          file.puts "<link rel=\"stylesheet\" href=\"#{root_prefix}css/main.css\">"
+          file.puts "<script src=\"#{root_prefix}scripts/main.js\"></script>"
         end
       elsif s.include?('{{HOME_BUTTON}}')
         if @id == 'index'
           file.puts '<a id="home_menu_item" href="./index.html"><span><i class="fa fa-home" aria-hidden="true"></i></span>&nbsp;Home</a>'
+          file.puts decisions_link('./decisions/overview.html') if BaseDocument.show_decisions_link
         elsif instance_of? Protocol
           file.puts '<a id="index_menu_item" href="./../../../index.html"><span><i class="fa fa-info" aria-hidden="true"></i></span>&nbsp;Index</a>'
+          file.puts decisions_link('./../../../decisions/overview.html') if BaseDocument.show_decisions_link
+        elsif instance_of? DecisionsOverview
+          file.puts index_link('./../index.html')
+          file.puts decisions_link('./overview.html')
+        elsif instance_of? Decision
+          file.puts index_link("#{root_prefix}index.html")
+          file.puts decisions_link("#{root_prefix}decisions/overview.html")
         else
-           file.puts '<a id="index_menu_item" href="./../../index.html"><span><i class="fa fa-info" aria-hidden="true"></i></span>&nbsp;Index</a>'
+          file.puts '<a id="index_menu_item" href="./../../index.html"><span><i class="fa fa-info" aria-hidden="true"></i></span>&nbsp;Index</a>'
+          file.puts decisions_link('./../../decisions/overview.html') if BaseDocument.show_decisions_link
         end
       elsif s.include?('{{GEM_VERSION}}')
         file.puts "(#{Gem.loaded_specs['Almirah'].version.version})"
@@ -72,4 +96,14 @@ class BaseDocument # rubocop:disable Style/Documentation
     end
     file.close
   end
+
+  def decisions_link(href)
+    icon = '<span><i class="fa fa-gavel" aria-hidden="true"></i></span>'
+    %(<a id="decisions_menu_item" href="#{href}">#{icon}&nbsp;Decision Records</a>)
+  end
+
+  def index_link(href)
+    icon = '<span><i class="fa fa-info" aria-hidden="true"></i></span>'
+    %(<a id="index_menu_item" href="#{href}">#{icon}&nbsp;Index</a>)
+  end
 end

data/lib/almirah/doc_types/decision.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+require 'date'
+require_relative 'persistent_document'
+require_relative '../doc_items/heading'
+require_relative '../doc_items/markdown_table'
+
+class Decision < PersistentDocument # rubocop:disable Style/Documentation,Metrics/ClassLength
+  attr_accessor :path, :sequence_number, :record_type, :html_rel_path, :root_prefix, :current_status,
+                :start_date, :target_release_version, :specifications_path, :wrong_links_hash
+
+  def initialize(file_path)
+    super
+    @path = file_path
+    stem = File.basename(file_path, File.extname(file_path))
+    assign_id_parts(stem)
+    @current_status = nil
+    @start_date = nil
+    @target_release_version = nil
+    @wrong_links_hash = {}
+  end
+
+  def to_console
+    puts "\e[36mDecision: #{@id}\e[0m"
+  end
+
+  def to_html(nav_pane, output_file_path)
+    html_rows = []
+    html_rows.append('')
+
+    @items.each do |item|
+      html_rows.append item.to_html
+    end
+
+    save_html_to_file(html_rows, nav_pane, output_file_path)
+  end
+
+  def extract_current_status
+    status_table = find_section_table('Status')
+    return if status_table.nil?
+
+    status_table.is_decision_status_table = true
+    marker_rows = status_table.rows.select { |row| row[0].to_s.strip == '*' }
+    @current_status = marker_rows.length == 1 ? marker_rows[0][-1].to_s.strip : nil
+  end
+
+  def extract_start_date
+    dates = collect_dates('Status', 'Date') + collect_dates('Scope', 'Start Date')
+    @start_date = dates.min
+  end
+
+  def extract_target_release_version
+    @target_release_version = lookup_cell(
+      section_name: 'Software Versions',
+      key_column: 'Software Version Category',
+      value_column: 'Software Version ID',
+      key: 'Target Release Version'
+    )
+  end
+
+  def effective_status_on(date) # rubocop:disable Metrics/MethodLength,Metrics/AbcSize,Metrics/CyclomaticComplexity,Metrics/PerceivedComplexity
+    table = find_section_table('Status')
+    return nil if table.nil?
+
+    date_idx = column_index(table, 'Date')
+    status_idx = column_index(table, 'Status')
+    return nil if date_idx.nil? || status_idx.nil?
+
+    best_idx = nil
+    best_date = nil
+    table.rows.each_with_index do |row, i|
+      parsed = parse_dd_mm_yyyy(row[date_idx])
+      next if parsed.nil? || parsed > date
+
+      if best_date.nil? || parsed > best_date || (parsed == best_date && i > best_idx)
+        best_date = parsed
+        best_idx = i
+      end
+    end
+    return nil if best_idx.nil?
+
+    status = table.rows[best_idx][status_idx].to_s.strip
+    status.empty? ? nil : status
+  end
+
+  private
+
+  def lookup_cell(section_name:, key_column:, value_column:, key:) # rubocop:disable Metrics/AbcSize
+    table = find_section_table(section_name)
+    return nil if table.nil?
+
+    key_idx = column_index(table, key_column)
+    value_idx = column_index(table, value_column)
+    return nil if key_idx.nil? || value_idx.nil?
+
+    row = table.rows.find { |r| r[key_idx].to_s.strip == key }
+    return nil if row.nil?
+
+    cell = row[value_idx].to_s.strip
+    cell.empty? ? nil : cell
+  end
+
+  def find_section_table(section_name) # rubocop:disable Metrics/MethodLength,Metrics/CyclomaticComplexity,Metrics/PerceivedComplexity
+    in_section = false
+    section_level = nil
+    @items.each do |item|
+      if item.is_a?(Heading)
+        if !in_section && item.text.strip == section_name
+          in_section = true
+          section_level = item.level
+        elsif in_section && item.level <= section_level
+          return nil
+        end
+      elsif in_section && item.is_a?(MarkdownTable)
+        return item
+      end
+    end
+    nil
+  end
+
+  def collect_dates(section_name, column_name)
+    table = find_section_table(section_name)
+    return [] if table.nil?
+
+    col_index = column_index(table, column_name)
+    return [] if col_index.nil?
+
+    table.rows.filter_map { |row| parse_dd_mm_yyyy(row[col_index]) }
+  end
+
+  def column_index(table, column_name)
+    table.column_names.each_with_index do |name, idx|
+      return idx if name.to_s.strip == column_name
+    end
+    nil
+  end
+
+  def parse_dd_mm_yyyy(value)
+    return nil if value.nil?
+
+    match = /\A(\d{2})-(\d{2})-(\d{4})\z/.match(value.to_s.strip)
+    return nil unless match
+
+    Date.new(match[3].to_i, match[2].to_i, match[1].to_i)
+  rescue ArgumentError
+    nil
+  end
+
+  def assign_id_parts(stem)
+    match = stem.match(/\A([A-Za-z]+)-(\d+)/)
+    if match
+      @id = "#{match[1]}-#{match[2]}".downcase
+      @record_type = match[1].upcase
+      @sequence_number = match[2]
+    else
+      @id = stem.downcase
+      @record_type = nil
+      @sequence_number = nil
+    end
+  end
+end

data/lib/almirah/doc_types/decisions_overview.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+require 'date'
+require 'json'
+require_relative 'base_document'
+
+class DecisionsOverview < BaseDocument # rubocop:disable Style/Documentation,Metrics/ClassLength
+  attr_accessor :project
+
+  def initialize(project)
+    super()
+    @project = project
+    @title = 'Decision Records Overview'
+    @id = 'overview'
+  end
+
+  def to_console
+    puts "\e[36mDecisions Overview: #{@id}\e[0m"
+  end
+
+  def to_html(output_file_path) # rubocop:disable Metrics/MethodLength,Metrics/AbcSize,Metrics/CyclomaticComplexity
+    html_rows = []
+    html_rows.append('')
+    html_rows.append "<h1>#{@title}</h1>\n"
+
+    html_rows.append render_charts_grid
+
+    html_rows.append "<table class=\"controlled decisions_overview\">\n"
+    html_rows.append "\t<thead>\n"
+    html_rows.append "\t\t<th>#</th>\n"
+    html_rows.append "\t\t<th>Type</th>\n"
+    html_rows.append "\t\t<th>Status</th>\n"
+    html_rows.append "\t\t<th>Title</th>\n"
+    html_rows.append "\t\t<th>Start Date</th>\n"
+    html_rows.append "\t\t<th>Target Date</th>\n"
+    html_rows.append "\t\t<th title=\"Target Release Version\">Release</th>\n"
+    html_rows.append "\t\t<th>Owner</th>\n"
+    html_rows.append "</thead>\n"
+
+    sorted_items = @project.project_data.decisions.sort_by do |d|
+      [d.sequence_number ? 0 : 1, d.sequence_number.to_i, d.id]
+    end
+    sorted_items.each do |doc|
+      s = "\t<tr>\n"
+      s += "\t\t<td class=\"item_id\">\n"
+      label = doc.sequence_number || doc.id
+      href = doc.html_rel_path ? "./#{doc.html_rel_path}" : "##{doc.id}"
+      anchor_attrs = %(name="#{doc.id}" id="#{doc.id}" href="#{href}" title="Decision Record ID")
+      s += "\t\t\t<a #{anchor_attrs}>#{label}</a>"
+      s += "\t\t</td>\n"
+      s += "\t\t<td class=\"item_type\">#{doc.record_type}</td>\n"
+      s += "\t\t<td class=\"item_status\">#{doc.current_status}</td>\n"
+      title_html = doc.html_rel_path ? %(<a href="./#{doc.html_rel_path}" class="external">#{doc.title}</a>) : doc.title
+      s += "\t\t<td class=\"item_text\" style='padding: 5px;'>#{title_html}</td>\n"
+      start_date_html = doc.start_date ? doc.start_date.strftime('%d-%m-%Y') : ''
+      s += "\t\t<td class=\"item_meta\">#{start_date_html}</td>\n"
+      s += "\t\t<td class=\"item_meta\"></td>\n"
+      s += "\t\t<td class=\"item_meta\">#{doc.target_release_version}</td>\n"
+      s += "\t\t<td class=\"item_meta\"></td>\n"
+      s += "</tr>\n"
+      html_rows.append s
+    end
+    html_rows.append "</table>\n"
+
+    save_html_to_file(html_rows, nil, output_file_path)
+  end
+
+  private
+
+  CHART_PALETTE = [
+    [54, 162, 235], [255, 99, 132], [255, 159, 64], [255, 205, 86],
+    [75, 192, 192], [153, 102, 255], [201, 203, 207]
+  ].freeze
+
+  def render_charts_grid # rubocop:disable Metrics/MethodLength,Metrics/AbcSize
+    counts = @project.project_data.decisions.each_with_object(Hash.new(0)) do |item, cntr|
+      cntr[item.record_type] += 1 if item.record_type
+    end
+    labels = counts.keys.sort
+    data = labels.map { |k| counts[k] }
+    pie_colors = labels.each_with_index.map { |_, i| palette_rgba(i, 0.5) }
+
+    velocity = velocity_chart_data
+
+    <<~HTML
+      <div class="decisions_overview_charts">
+      \t<div class="chart_cell">
+      \t\t<canvas id="decisions_type_pie"></canvas>
+      \t\t<script>
+      \t\t\tnew Chart(document.getElementById('decisions_type_pie'), {
+      \t\t\t\ttype: 'pie',
+      \t\t\t\tdata: {
+      \t\t\t\t\tlabels: #{labels.to_json},
+      \t\t\t\t\tdatasets: [{
+      \t\t\t\t\t\tlabel: 'Decision records',
+      \t\t\t\t\t\tdata: #{data.to_json},
+      \t\t\t\t\t\tbackgroundColor: #{pie_colors.to_json},
+      \t\t\t\t\t\tborderWidth: 0
+      \t\t\t\t\t}]
+      \t\t\t\t},
+      \t\t\t\toptions: { plugins: { title: { display: true, text: 'Decision Records by Type' } } }
+      \t\t\t});
+      \t\t</script>
+      \t</div>
+      \t<div class="chart_cell">
+      \t\t<canvas id="decisions_velocity_bar"></canvas>
+      \t\t<script>
+      \t\t\tnew Chart(document.getElementById('decisions_velocity_bar'), {
+      \t\t\t\ttype: 'bar',
+      \t\t\t\tdata: #{velocity.to_json},
+      \t\t\t\toptions: {
+      \t\t\t\t\tplugins: { title: { display: true, text: 'Decision Records by Status Over Time' } },
+      \t\t\t\t\tscales: { x: { stacked: true }, y: { stacked: true, ticks: { precision: 0 } } }
+      \t\t\t\t}
+      \t\t\t});
+      \t\t</script>
+      \t</div>
+      \t<div class="chart_cell"></div>
+      </div>
+    HTML
+  end
+
+  def velocity_chart_data(reference_date: Date.today, weeks: 6) # rubocop:disable Metrics/MethodLength,Metrics/AbcSize
+    fridays = recent_fridays(reference_date, weeks)
+    segments = []
+    counts = {}
+
+    fridays.each_with_index do |friday, i|
+      @project.project_data.decisions.each do |doc|
+        status = doc.effective_status_on(friday)
+        next if status.nil?
+
+        unless counts.key?(status)
+          counts[status] = Array.new(fridays.length, 0)
+          segments << status
+        end
+        counts[status][i] += 1
+      end
+    end
+
+    {
+      labels: fridays.map { |f| f.strftime('%d-%m-%Y') },
+      datasets: segments.map { |s| { label: s, data: counts[s] } }
+    }
+  end
+
+  def palette_rgba(index, alpha)
+    r, g, b = CHART_PALETTE[index % CHART_PALETTE.length]
+    "rgba(#{r}, #{g}, #{b}, #{alpha})"
+  end
+
+  def recent_fridays(reference_date, count)
+    friday_wday = 5
+    days_back = (reference_date.wday - friday_wday) % 7
+    most_recent = reference_date - days_back
+    (0...count).to_a.reverse.map { |i| most_recent - (7 * i) }
+  end
+end

data/lib/almirah/doc_types/protocol.rb

@@ -2,9 +2,12 @@ require_relative "persistent_document"
 
 class Protocol < PersistentDocument
 
+    attr_accessor :specifications_path
+
     def initialize(fele_path)
         super
         @id = File.basename(fele_path, File.extname(fele_path)).downcase
+        @specifications_path = './../../../specifications/'
     end
 
     def to_html(nav_pane, output_file_path)

data/lib/almirah/project/doc_linker.rb

@@ -44,6 +44,30 @@ class DocLinker
     end
   end
 
+  def self.link_decision_to_spec(decision, specification) # rubocop:disable Metrics/AbcSize,Metrics/CyclomaticComplexity,Metrics/MethodLength,Metrics/PerceivedComplexity
+    top_document = specification
+    bottom_document = decision
+
+    bottom_document.controlled_items.each do |item|
+      next unless item.up_link_ids
+
+      item.up_link_ids.each do |up_lnk|
+        if top_document.dictionary.key?(up_lnk.to_s)
+
+          top_item = top_document.dictionary[up_lnk.to_s]
+
+          top_item.decision_record_links = [] unless top_item.decision_record_links
+          top_item.decision_record_links.append(item)
+        elsif tmp = /^([a-zA-Z]+)-\d+/.match(up_lnk)
+          # check if there is a non existing link with the right doc_id
+          if tmp[1].downcase == top_document.id.downcase
+            bottom_document.wrong_links_hash[up_lnk] = item
+          end # SRS
+        end
+      end
+    end
+  end
+
   def self.link_source_file_to_spec(source_file, specification) # rubocop:disable Metrics/AbcSize,Metrics/CyclomaticComplexity,Metrics/MethodLength,Metrics/PerceivedComplexity
     top_document = specification
     bottom_document = source_file

data/lib/almirah/project/project_data.rb

@@ -1,7 +1,7 @@
 class ProjectData
   attr_reader :specifications, :protocols, :traceability_matrices, :coverage_matrices, :source_files,
               :specifications_dictionary, :covered_specifications_dictionary, :implemented_specifications_dictionary,
-              :implementation_matrices
+              :implementation_matrices, :decisions
 
   def initialize
     @specifications = []
@@ -10,6 +10,7 @@ class ProjectData
     @coverage_matrices = []
     @source_files = []
     @implementation_matrices = []
+    @decisions = []
 
     @specifications_dictionary = {}
     @covered_specifications_dictionary = {}

data/lib/almirah/project.rb

@@ -37,13 +37,15 @@ class Project # rubocop:disable Metrics/ClassLength,Style/Documentation
     FileUtils.copy_entry(src_folder, dst_folder)
   end
 
-  def specifications_and_protocols # rubocop:disable Metrics/MethodLength
+  def specifications_and_protocols # rubocop:disable Metrics/MethodLength,Metrics/AbcSize
     parse_all_specifications
     parse_all_protocols
     parse_all_source_files
+    parse_decisions
     link_all_specifications
     link_all_protocols
     link_all_source_files
+    link_all_decisions
     check_wrong_specification_referenced
     create_index
     render_all_specifications(@project_data.specifications)
@@ -52,17 +54,21 @@ class Project # rubocop:disable Metrics/ClassLength,Style/Documentation
     render_all_protocols
     render_all_source_files
     render_all_specifications(@project_data.implementation_matrices) # intentionally after source file rendering
+    render_decisions_overview
+    render_all_decisions
     render_index
     create_search_data
   end
 
-  def specifications_and_results(test_run) # rubocop:disable Metrics/MethodLength
+  def specifications_and_results(test_run) # rubocop:disable Metrics/MethodLength,Metrics/AbcSize
     parse_all_specifications
     parse_test_run test_run
     parse_all_source_files
+    parse_decisions
     link_all_specifications
     link_all_protocols
     link_all_source_files
+    link_all_decisions
     check_wrong_specification_referenced
     create_index
     render_all_specifications(@project_data.specifications)
@@ -71,6 +77,8 @@ class Project # rubocop:disable Metrics/ClassLength,Style/Documentation
     render_all_protocols
     render_all_source_files
     render_all_specifications(@project_data.implementation_matrices) # intentionally after source file rendering
+    render_decisions_overview
+    render_all_decisions
     render_index
     create_search_data
   end
@@ -114,6 +122,18 @@ class Project # rubocop:disable Metrics/ClassLength,Style/Documentation
     end
   end
 
+  def parse_decisions
+    path = @configuration.project_root_directory
+    decisions_root = "#{path}/decisions"
+    Dir.glob("#{decisions_root}/**/*.md").each do |f|
+      doc = DocFabric.create_decision(f)
+      rel_dir = File.dirname(f.sub("#{decisions_root}/", ''))
+      doc.html_rel_path = rel_dir == '.' ? "#{doc.id}.html" : "#{rel_dir}/#{doc.id}.html"
+      @project_data.decisions.append(doc)
+    end
+    BaseDocument.show_decisions_link = @project_data.decisions.any?
+  end
+
   def parse_test_run(test_run)
     path = @configuration.project_root_directory
     Dir.glob("#{path}/tests/runs/#{test_run}/**/*.md").each do |f|
@@ -156,6 +176,16 @@ class Project # rubocop:disable Metrics/ClassLength,Style/Documentation
     end
   end
 
+  def link_all_decisions
+    @project_data.decisions.each do |d|
+      @project_data.specifications.each do |s|
+        next unless d.up_link_docs.key?(s.id.to_s)
+
+        DocLinker.link_decision_to_spec(d, s)
+      end
+    end
+  end
+
   def link_all_source_files
     return unless DocLinker.link_all_source_files(@project_data)
 
@@ -295,6 +325,33 @@ class Project # rubocop:disable Metrics/ClassLength,Style/Documentation
     doc.to_html("#{path}/build/")
   end
 
+  def render_decisions_overview
+    return if @project_data.decisions.empty?
+
+    path = @configuration.project_root_directory
+    FileUtils.mkdir_p("#{path}/build/decisions")
+
+    doc = DocFabric.create_decisions_overview(@project)
+    doc.to_console
+    doc.to_html("#{path}/build/decisions/")
+  end
+
+  def render_all_decisions # rubocop:disable Metrics/MethodLength,Metrics/AbcSize
+    return if @project_data.decisions.empty?
+
+    build_decisions_root = "#{@configuration.project_root_directory}/build/decisions"
+    @project_data.decisions.each do |doc|
+      out_dir_rel = File.dirname(doc.html_rel_path)
+      out_dir = out_dir_rel == '.' ? build_decisions_root : "#{build_decisions_root}/#{out_dir_rel}"
+      FileUtils.mkdir_p(out_dir)
+      depth = 1 + (out_dir_rel == '.' ? 0 : out_dir_rel.split('/').size)
+      doc.root_prefix = '../' * depth
+      doc.specifications_path = "./#{doc.root_prefix}specifications/"
+      doc.to_console
+      doc.to_html(NavigationPane.new(doc), "#{out_dir}/")
+    end
+  end
+
   def create_search_data
     db = SpecificationsDb.new @project_data.specifications
     data_path = "#{@configuration.project_root_directory}/build/data"

data/lib/almirah/templates/css/main.css

@@ -64,11 +64,14 @@ table.markdown_table th{
     background-color:#EEEEEE;
 }
 table.markdown_table td{
-    border: 1px solid #bbb; 
+    border: 1px solid #bbb;
     padding: 4px;
     display: table-cell;
     vertical-align: inherit;
 }
+table.markdown_table tr.current_status td {
+    background-color: #ffffee;
+}
 table.controlled{
     border: 1px solid #e4e4e4;
     border-collapse: collapse;
@@ -110,9 +113,32 @@ table.controlled td.item_id {
     width: 3%;
     text-align: center;
 }
+table.controlled td.item_type {
+    width: 5%;
+    text-align: center;
+    font-weight: normal;
+}
+table.controlled td.item_status {
+    width: 5%;
+    text-align: center;
+    white-space: nowrap;
+}
 table.controlled td.item_text{
     text-align: left;
 }
+.decisions_overview_charts {
+    display: grid;
+    grid-template-columns: repeat(3, 1fr);
+    gap: 16px;
+    margin-bottom: 16px;
+}
+.decisions_overview_charts .chart_cell {
+    min-height: 240px;
+}
+.decisions_overview_charts .chart_cell canvas {
+    max-width: 100%;
+    max-height: 300px;
+}
 table.controlled:not(.odd-even) tbody tr:nth-child(odd) { background-color:#f6f7f8; }
 table.controlled:not(.odd-even) tbody tr:nth-child(even) { background-color: #fff; }
 table.controlled:not(.odd-even) tbody tr:nth-child(odd):hover,
@@ -146,6 +172,15 @@ code {
     margin-top: 4px;
     margin-bottom: 4px;
 }
+code.inline {
+    display: inline;
+    background:#f4f4f4;
+    border: 1px solid #ddd;
+    border-left: 1px solid #ddd;
+    border-radius: 3px;
+    padding: 0 4px;
+    margin: 0;
+}
 div.todoblock {
     display: block;
     background:#fcc;

data/lib/almirah/templates/scripts/main.js

@@ -50,7 +50,13 @@ function openNav() {
     clicked.style.display = 'none';
     id_parts = clicked.id.split("_");
     required_id = "COVS_" + id_parts[1];
-    document.getElementById(required_id).style.display = 'block';  
+    document.getElementById(required_id).style.display = 'block';
+  }
+  function decisionLink_OnClick(clicked){
+    clicked.style.display = 'none';
+    id_parts = clicked.id.split("_");
+    required_id = "DRS_" + id_parts[1];
+    document.getElementById(required_id).style.display = 'block';
   }
   function upLink_OnClick(clicked){
     clicked.style.display = 'none';

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: Almirah
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.4.0
 platform: ruby
 authors:
 - Oleksandr Ivanov
@@ -78,6 +78,8 @@ files:
 - lib/almirah/doc_parser.rb
 - lib/almirah/doc_types/base_document.rb
 - lib/almirah/doc_types/coverage.rb
+- lib/almirah/doc_types/decision.rb
+- lib/almirah/doc_types/decisions_overview.rb
 - lib/almirah/doc_types/implementation.rb
 - lib/almirah/doc_types/index.rb
 - lib/almirah/doc_types/persistent_document.rb