Almirah 0.4.0 → 0.4.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b3c6b1d68ee25c9b62690c4cdda45ec2d790960a6e75762576ddc60d6c3136e5
-  data.tar.gz: 334ef7251595119cd27bf980eeb53a8f02d913cde7d2fc5d0844a1d863b6c825
+  metadata.gz: 5221af43605bcaab2815ac5c940d53188394a92f8f8fadbbd2def016d1d52328
+  data.tar.gz: dd1d271774fe527d93512134b70cca3471048ff2a0859327c813eb75ebd35b54
 SHA512:
-  metadata.gz: 20383b85a3d59d35a3c6259095e7e8b6709055b6670e2b651fdecdd814eee54b71ebf7d2cc1958c85bc998a426361dfff470c1c10749044334ae7ec7f1a69616
-  data.tar.gz: d1d066ecfc0cfe644eaa28f42d793342e328f42d3eefc0e1fdeb2290c8ff281009bd59b99d23893604f89927ab698a922ef844af1e702c45a3a0a5d51926ff84
+  metadata.gz: 6cf6a8d5892855c7b8752a2a3d447fec79dcf89a6a796b931709b2207ceeaddaede5cf7ac262ce13ab8b47aa081ead25fd225f353fff3afb84bc01dfaf2dfbdd
+  data.tar.gz: 9c0c6cffe8a41a19fc6778bcb0a3210f5a0ca3402b058d6b5f011b0434805fd11035be76a9ec6a742485839fe7523480d043923e582a2f0367c4fadb93922473

data/lib/almirah/console_reporter.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+# Reporter prints concise, aligned progress lines for the processing pipeline:
+#
+#   parsing specifications ..... 4 ok
+#   parsing test protocols ..... 2 ok
+#   parsing decisions .......... 14 ok
+#   traceability matrices ...... 4 ok
+#   coverage matrices .......... 1 ok
+#   implementation matrices .... 1 ok
+#   decision links ............. 5 ok
+#   rendering HTML ............. ./build/index.html
+#
+# ANSI colour is applied only when writing to an interactive terminal, so piped
+# or captured output stays clean.
+module ConsoleReporter
+  COLUMN = 28 # label is dot-padded out to this column, then the value follows
+
+  module_function
+
+  def count(label, number)
+    emit(label, "#{number} ok", 92) # green highlight
+  end
+
+  def result(label, value)
+    emit(label, value, 96) # cyan highlight
+  end
+
+  def warn(label, value)
+    emit(label, value.to_s, 91) # red highlight
+  end
+
+  # Colourises a detail line with the same red as warn (TTY-gated).
+  def warn_detail(text)
+    colorize(text, 91)
+  end
+
+  def emit(label, value, color_code)
+    dotted = "#{label} ".ljust(COLUMN, '.')
+    puts "#{dotted} #{colorize(value, color_code)}"
+  end
+
+  def colorize(text, color_code)
+    $stdout.tty? ? "\e[#{color_code}m#{text}\e[0m" : text
+  end
+end

data/lib/almirah/doc_fabric.rb

@@ -17,12 +17,6 @@ class DocFabric
   @@spec_colors = %w[cff4d2 fbeee6 ffcad4 bce6ff e4dfd9 f9e07f cbe54e d3e7ee eab595 86e3c3
                      ffdca2 ffffff ffdd94 d0e6a5 ffb284 f3dbcf c9bbc8 c6c09c]
 
-  def self.add_lazy_doc_id(path)
-    if res = /(\w+)[.]md$/.match(path)
-      TextLine.add_lazy_doc_id(res[1])
-    end
-  end
-
   def self.create_specification(path)
     color = @@spec_colors[@@color_index]
     @@color_index += 1
@@ -71,6 +65,7 @@ class DocFabric
     DocFabric.parse_document doc
     doc.extract_current_status
     doc.extract_start_date
+    doc.extract_target_date
     doc.extract_target_release_version
     doc
   end

data/lib/almirah/doc_items/code_block.rb

@@ -19,7 +19,7 @@ class CodeBlock < DocItem
         end
         s += "<code>"
         @code_lines.each do |l|
-            s += l + " </br>"
+            s += escape_text(l) + " </br>" # ADR-188/SRS-096: code content is inert text
         end
         s += "</code>\n"
         return s

data/lib/almirah/doc_items/controlled_table.rb

@@ -151,7 +151,7 @@ class ControlledTable < DocItem # rubocop:disable Style/Documentation
   end
 
   def add_row(row)
-    columns = row.split('|')
+    columns = split_table_cells(row)
 
     @rows.append(format_columns(columns))
 

data/lib/almirah/doc_items/doc_item.rb

@@ -19,4 +19,16 @@ class DocItem < TextLine # rubocop:disable Style/Documentation
   def get_url
     ''
   end
+
+  # Splits a Markdown table row into its cell strings, treating a backslash-escaped
+  # pipe (\|) as a literal character within a cell rather than a column separator
+  # (e.g. a "|" inside an inline code span such as `[[target\|alias]]`). The escaping
+  # backslash is dropped so the cell renders the intended literal pipe.
+  def split_table_cells(row)
+    row.split(/(?<!\\)\|/).map { |cell| cell.gsub('\\|', '|') }
+  end
+
+  def owner_document
+    @parent_doc
+  end
 end

data/lib/almirah/doc_items/heading.rb

@@ -57,8 +57,26 @@ class Heading < Paragraph
     end
   end
 
+  # As get_section_info but with the author-supplied text HTML-escaped for safe
+  # interpolation into rendered HTML (headings, TOC, traceability). ADR-188/SRS-096.
+  def get_section_info_html
+    if level.zero? # Doc Title
+      escape_text(@text)
+    else
+      "#{@section_number} #{escape_text(@text)}"
+    end
+  end
+
   def get_anchor_text
-    "#{@section_number}-#{getTextWithoutSpaces}"
+    "#{@section_number}-#{anchor_slug}"
+  end
+
+  # The anchor is a generated identifier emitted into name/href attributes, so it
+  # must not carry the HTML-significant characters that author heading text may
+  # contain (ADR-188). Stripping them keeps the anchor inert and self-consistent
+  # across the heading, its self-link, and the table of contents.
+  def anchor_slug
+    getTextWithoutSpaces.gsub(/[<>"'&]/, '')
   end
 
   def get_markdown_anchor_text
@@ -72,10 +90,10 @@ class Heading < Paragraph
       @@html_table_render_in_progress = false
     end
     heading_level = level.to_s
-    heading_text = get_section_info
+    heading_text = get_section_info_html
     if level.zero?
-      heading_level = 1.to_s # Render Doc Title as a regular h1
-      heading_text = @text    # Doc Title does not have a section number
+      heading_level = 1.to_s        # Render Doc Title as a regular h1
+      heading_text = escape_text(@text) # Doc Title does not have a section number
     end
     s += "<a name=\"#{@anchor_id}\"></a>\n"
     s += "<h#{heading_level}> #{heading_text} <a href=\"\##{@anchor_id}\" class=\"heading_anchor\">"

data/lib/almirah/doc_items/image.rb

@@ -21,7 +21,14 @@ class Image < DocItem
             @@html_table_render_in_progress = false
         end
 
-        s += "<p style=\"margin-top: 15px;\"><img src=\"#{@path}\" alt=\"#{@text}\" "
+        alt = escape_attr(@text)
+        src = safe_url(@path)
+        if src.nil? # disallowed scheme: render inert rather than emitting it (ADR-188, SRS-098)
+            s += "<p style=\"margin-top: 15px;\">[image: #{alt}]"
+            return s
+        end
+
+        s += "<p style=\"margin-top: 15px;\"><img src=\"#{escape_attr(src)}\" alt=\"#{alt}\" "
         s += "href=\"javascript:void(0)\" onclick=\"image_OnClick(this)\">"
         return s
     end

data/lib/almirah/doc_items/markdown_table.rb

@@ -12,7 +12,7 @@ class MarkdownTable < DocItem
 
     res = /^[|](.*[|])/.match(heading_row)
     @column_names = if res
-                      res[1].split('|')
+                      split_table_cells(res[1])
                     else
                       ['# ERROR# ']
                     end
@@ -49,7 +49,7 @@ class MarkdownTable < DocItem
   end
 
   def add_row(row)
-    columns = row.split('|')
+    columns = split_table_cells(row)
     @rows.append(columns.map!(&:strip))
     true
   end
@@ -65,7 +65,7 @@ class MarkdownTable < DocItem
     s += "\t<thead>"
 
     @column_names.each do |h|
-      s += " <th>#{h}</th>"
+      s += " <th>#{format_string(h.strip)}</th>"
     end
 
     s += " </thead>\n"

data/lib/almirah/doc_items/text_line.rb

@@ -1,4 +1,7 @@
 require 'cgi'
+require 'uri'
+require_relative '../relative_url'
+require_relative '../html_safe'
 
 class TextLineToken
   attr_accessor :value
@@ -50,6 +53,18 @@ class SquareBracketRight < TextLineToken
   end
 end
 
+class DoubleSquareBracketLeft < TextLineToken
+  def initialize # rubocop:disable Lint/MissingSuper
+    @value = '[['
+  end
+end
+
+class DoubleSquareBracketRight < TextLineToken
+  def initialize # rubocop:disable Lint/MissingSuper
+    @value = ']]'
+  end
+end
+
 class SquareBracketRightAndParentheseLeft < TextLineToken
   def initialize
     @value = ']('
@@ -77,6 +92,8 @@ class TextLineParser
     @supported_tokens.append(BoldToken.new)
     @supported_tokens.append(ItalicToken.new)
     @supported_tokens.append(BacktickToken.new)
+    @supported_tokens.append(DoubleSquareBracketLeft.new)
+    @supported_tokens.append(DoubleSquareBracketRight.new)
     @supported_tokens.append(SquareBracketRightAndParentheseLeft.new)
     @supported_tokens.append(ParentheseLeft.new)
     @supported_tokens.append(ParentheseRight.new)
@@ -201,6 +218,12 @@ class TextLineParser
 end
 
 class TextLineBuilderContext
+  # Literal (non-markup) text run. Subclasses encode it for the HTML context;
+  # the base context leaves it untouched for plain reconstruction/unit tests.
+  def literal_text(str)
+    str
+  end
+
   def italic(str)
     str
   end
@@ -220,6 +243,10 @@ class TextLineBuilderContext
   def link(_link_text, link_url)
     link_url
   end
+
+  def wiki_link(inner)
+    "[[#{inner}]]"
+  end
 end
 
 class TextLineBuilder
@@ -229,7 +256,7 @@ class TextLineBuilder
     @builder_context = builder_context
   end
 
-  def restore(token_list)
+  def restore(token_list) # rubocop:disable Metrics/AbcSize,Metrics/CyclomaticComplexity,Metrics/MethodLength,Metrics/PerceivedComplexity
     result = ''
     return '' if token_list.nil?
 
@@ -296,6 +323,25 @@ class TextLineBuilder
           result += '***'
           ti = ti_starting_position + 1
         end
+      when 'DoubleSquareBracketLeft'
+        # wiki/Obsidian link: collect raw text up to the closing "]]"
+        is_found = false
+        ti_starting_position = ti
+        tii = ti + 1
+        while tii < tl
+          if token_list[tii].instance_of?(DoubleSquareBracketRight)
+            inner = token_list[(ti + 1)..(tii - 1)].map(&:value).join
+            result += @builder_context.wiki_link(inner)
+            ti = tii + 1
+            is_found = true
+            break
+          end
+          tii += 1
+        end
+        unless is_found
+          result += '[['
+          ti = ti_starting_position + 1
+        end
       when 'SquareBracketLeft'
         # try to find closing part
         is_found = false
@@ -324,7 +370,11 @@ class TextLineBuilder
           tii += 1
         end
         if is_found
-          result += @builder_context.link(restore(sub_list_url_text), restore(sub_list_url_address))
+          # URL is reconstructed raw (not via restore) so scheme classification
+          # and file-path resolution see the original characters; link() applies
+          # attribute escaping and the scheme allow-list (ADR-188).
+          raw_url = (sub_list_url_address || []).map(&:value).join
+          result += @builder_context.link(restore(sub_list_url_text), raw_url)
         else
           result += '['
           ti = ti_starting_position + 1
@@ -333,8 +383,8 @@ class TextLineBuilder
       when 'InlineCodeToken'
         result += @builder_context.inline_code(token_list[ti].value)
         ti += 1
-      when 'TextLineToken', 'ParentheseLeft', 'ParentheseRight', 'SquareBracketRight'
-        result += token_list[ti].value
+      when 'TextLineToken', 'ParentheseLeft', 'ParentheseRight', 'SquareBracketRight', 'DoubleSquareBracketRight'
+        result += @builder_context.literal_text(token_list[ti].value)
         ti += 1
       else
         ti += 1
@@ -345,11 +395,39 @@ class TextLineBuilder
 end
 
 class TextLine < TextLineBuilderContext
-  @@lazy_doc_id_dict = {}
+  include HtmlSafe
+
+  @@link_registry = nil # rubocop:disable Style/ClassVars
+  @@broken_links = [] # rubocop:disable Style/ClassVars
+
+  class << self
+    def link_registry=(registry)
+      @@link_registry = registry # rubocop:disable Style/ClassVars
+    end
+
+    def link_registry
+      @@link_registry
+    end
+
+    # Cross-document links that could not be resolved to a managed document,
+    # collected during rendering for reporting (ADR-186, SRS-094).
+    def broken_links
+      @@broken_links
+    end
+
+    def reset_broken_links
+      @@broken_links = [] # rubocop:disable Style/ClassVars
+    end
 
-  def self.add_lazy_doc_id(id)
-    doc_id = id.to_s.downcase
-    @@lazy_doc_id_dict[doc_id] = doc_id
+    def record_broken_link(document, target)
+      @@broken_links << { document: document&.id, target: target }
+    end
+  end
+
+  # The document that owns this text line. Used to resolve cross-document links
+  # relative to the current page. nil for stand-alone text (e.g. unit tests).
+  def owner_document
+    nil
   end
 
   def format_string(str)
@@ -358,6 +436,11 @@ class TextLine < TextLineBuilderContext
     tlb.restore(tlp.tokenize(str))
   end
 
+  # Literal text run, HTML-escaped for element content (ADR-188, SRS-096).
+  def literal_text(str)
+    escape_text(str)
+  end
+
   def italic(str)
     "<i>#{str}</i>"
   end
@@ -374,30 +457,63 @@ class TextLine < TextLineBuilderContext
     "<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>"
-
-    lazy_doc_id = nil
-    anchor = nil
-
-    if res = /(\w+)[.]md$/.match(link_url)          # link
-      lazy_doc_id = res[1].to_s.downcase
+  def link(link_text, link_url) # rubocop:disable Metrics/MethodLength
+    raw = link_url.to_s
+    kind, target, fragment = classify_markdown_link(raw)
+    case kind
+    when :internal
+      href = RelativeUrl.between(owner_document.output_rel_path, target.output_rel_path, fragment: fragment)
+      "<a href=\"#{escape_attr(href)}\" class=\"external\">#{link_text}</a>"
+    when :broken
+      TextLine.record_broken_link(owner_document, raw)
+      "<a href=\"#{escape_attr(raw)}\" class=\"broken_link\" title=\"Unresolved cross-document link\">#{link_text}</a>"
+    else
+      url = safe_url(raw)
+      return link_text if url.nil? # disallowed scheme: render inert (ADR-188, SRS-098)
 
-    elsif res = /(\w*)[.]md(#.*)$/.match(link_url)  # link with anchor
-      if res && res.length > 2
-        lazy_doc_id = res[1]
-        anchor = res[2]
-      end
+      "<a target=\"_blank\" rel=\"noopener\" href=\"#{escape_attr(url)}\" class=\"external\">#{link_text}</a>"
     end
+  end
 
-    if lazy_doc_id && @@lazy_doc_id_dict.key?(lazy_doc_id)
-      result = if anchor
-                 "<a href=\".\\..\\#{lazy_doc_id}\\#{lazy_doc_id}.html#{anchor}\" class=\"external\">#{link_text}</a>"
-               else
-                 "<a href=\".\\..\\#{lazy_doc_id}\\#{lazy_doc_id}.html\" class=\"external\">#{link_text}</a>"
-               end
+  # Resolves an Obsidian/wiki link "[[target#fragment|alias]]" to a managed
+  # document by its unique id/filename, independent of folder (ADR-186).
+  def wiki_link(inner) # rubocop:disable Metrics/CyclomaticComplexity,Metrics/PerceivedComplexity,Metrics/AbcSize,Metrics/MethodLength
+    link_part, sep, alias_text = inner.partition('|')
+    target, _hash, fragment = link_part.partition('#')
+    display = (sep.empty? ? link_part : alias_text).strip
+    display = link_part.strip if display.empty?
+
+    doc = TextLine.link_registry&.find_by_id(target.strip)
+    if doc && owner_document&.output_rel_path
+      href = RelativeUrl.between(owner_document.output_rel_path, doc.output_rel_path,
+                                 fragment: fragment.strip.empty? ? nil : fragment.strip)
+      "<a href=\"#{href}\" class=\"external\">#{CGI.escapeHTML(display)}</a>"
+    elsif owner_document&.output_rel_path
+      TextLine.record_broken_link(owner_document, "[[#{inner}]]")
+      "<span class=\"broken_link\" title=\"Unresolved wiki link\">#{CGI.escapeHTML(display)}</span>"
+    else
+      "[[#{inner}]]"
     end
-    result
+  end
+
+  private
+
+  # Classifies a Markdown link target as :internal (a managed document, resolved
+  # against the owning document's source directory), :broken (a local .md path
+  # that does not resolve), or :external (everything else). ADR-186.
+  def classify_markdown_link(raw) # rubocop:disable Metrics/CyclomaticComplexity,Metrics/PerceivedComplexity
+    path_part, _sep, fragment = raw.partition('#')
+    path_part = URI::DEFAULT_PARSER.unescape(path_part) # decode %20 etc. to match the real file path
+    return [:external] unless local_markdown_path?(path_part)
+
+    doc = owner_document
+    return [:external] unless doc&.output_rel_path && doc.respond_to?(:path) && doc.path && TextLine.link_registry
+
+    target = TextLine.link_registry.find_by_source(File.expand_path(path_part, File.dirname(doc.path)))
+    target ? [:internal, target, fragment.empty? ? nil : fragment] : [:broken]
+  end
+
+  def local_markdown_path?(path_part)
+    path_part.match?(/\.(md|markdown)\z/i) && !path_part.match?(%r{\A[a-z][a-z0-9+.\-]*://}i)
   end
 end

data/lib/almirah/doc_types/base_document.rb

@@ -1,7 +1,9 @@
 # frozen_string_literal: true
 
+require_relative '../relative_url'
+
 class BaseDocument # rubocop:disable Style/Documentation
-  attr_accessor :title, :id, :dom, :headings
+  attr_accessor :title, :id, :dom, :headings, :output_rel_path
 
   class << self
     attr_accessor :show_decisions_link
@@ -32,6 +34,7 @@ class BaseDocument # rubocop:disable Style/Documentation
                         else
                           "#{@id}/#{@id}.html"
                         end
+    @output_rel_path = output_file_path.split('/build/', 2).last
     file = File.open(output_file_path, 'w')
     file_data.each do |s| # rubocop:disable Metrics/BlockLength
       if s.include?('{{CONTENT}}')
@@ -43,51 +46,21 @@ class BaseDocument # rubocop:disable Style/Documentation
       elsif s.include?('{{DOCUMENT_TITLE}}')
         file.puts s.gsub! '{{DOCUMENT_TITLE}}', @title
       elsif s.include?('{{STYLES_AND_SCRIPTS}}')
+        file.puts "<link rel=\"stylesheet\" href=\"#{rel_to('css/main.css')}\">"
+        file.puts "<script src=\"#{rel_to('scripts/main.js')}\"></script>"
         if @id == 'index'
-          file.puts '<script type="module" src="./scripts/orama_search.js"></script>'
-          file.puts '<link rel="stylesheet" href="./css/search.css">'
-          file.puts '<link rel="stylesheet" href="./css/main.css">'
-          file.puts '<script src="./scripts/main.js"></script>'
-        elsif instance_of? Specification
-          file.puts '<link rel="stylesheet" href="../../css/main.css">'
-          file.puts '<script src="../../scripts/main.js"></script>'
-        elsif instance_of? Traceability
-          file.puts '<link rel="stylesheet" href="../../css/main.css">'
-          file.puts '<script src="../../scripts/main.js"></script>'
-        elsif instance_of? Coverage
-          file.puts '<link rel="stylesheet" href="../../css/main.css">'
-          file.puts '<script src="../../scripts/main.js"></script>'
-        elsif instance_of? Implementation
-          file.puts '<link rel="stylesheet" href="../../css/main.css">'
-          file.puts '<script src="../../scripts/main.js"></script>'
-        elsif instance_of? Protocol
-          file.puts '<link rel="stylesheet" href="../../../css/main.css">'
-          file.puts '<script src="../../../scripts/main.js"></script>'
+          file.puts "<script type=\"module\" src=\"#{rel_to('scripts/orama_search.js')}\"></script>"
+          file.puts "<link rel=\"stylesheet\" href=\"#{rel_to('css/search.css')}\">"
         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")
+          file.puts home_link(rel_to('index.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 decisions_link('./../../decisions/overview.html') if BaseDocument.show_decisions_link
+          file.puts index_link(rel_to('index.html'))
         end
+        file.puts decisions_link(rel_to('decisions/overview.html')) if BaseDocument.show_decisions_link
       elsif s.include?('{{GEM_VERSION}}')
         file.puts "(#{Gem.loaded_specs['Almirah'].version.version})"
       else
@@ -106,4 +79,14 @@ class BaseDocument # rubocop:disable Style/Documentation
     icon = '<span><i class="fa fa-info" aria-hidden="true"></i></span>'
     %(<a id="index_menu_item" href="#{href}">#{icon}&nbsp;Index</a>)
   end
+
+  def home_link(href)
+    icon = '<span><i class="fa fa-home" aria-hidden="true"></i></span>'
+    %(<a id="home_menu_item" href="#{href}">#{icon}&nbsp;Home</a>)
+  end
+
+  # Relative URL from this page to a target path under the build root.
+  def rel_to(target)
+    RelativeUrl.between(@output_rel_path, target)
+  end
 end

data/lib/almirah/doc_types/decision.rb

@@ -7,7 +7,7 @@ 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
+                :start_date, :target_date, :target_release_version, :specifications_path, :wrong_links_hash
 
   def initialize(file_path)
     super
@@ -16,6 +16,7 @@ class Decision < PersistentDocument # rubocop:disable Style/Documentation,Metric
     assign_id_parts(stem)
     @current_status = nil
     @start_date = nil
+    @target_date = nil
     @target_release_version = nil
     @wrong_links_hash = {}
   end
@@ -49,6 +50,11 @@ class Decision < PersistentDocument # rubocop:disable Style/Documentation,Metric
     @start_date = dates.min
   end
 
+  def extract_target_date
+    dates = collect_dates('Status', 'Date') + collect_dates('Scope', 'Target Date')
+    @target_date = dates.max
+  end
+
   def extract_target_release_version
     @target_release_version = lookup_cell(
       section_name: 'Software Versions',

data/lib/almirah/doc_types/decisions_overview.rb

@@ -54,7 +54,8 @@ class DecisionsOverview < BaseDocument # rubocop:disable Style/Documentation,Met
       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"
+      target_date_html = doc.target_date ? doc.target_date.strftime('%d-%m-%Y') : ''
+      s += "\t\t<td class=\"item_meta\">#{target_date_html}</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"
@@ -72,6 +73,10 @@ class DecisionsOverview < BaseDocument # rubocop:disable Style/Documentation,Met
     [75, 192, 192], [153, 102, 255], [201, 203, 207]
   ].freeze
 
+  # Records with a missing or ambiguous current-status marker are surfaced under
+  # this category as a data-quality indicator rather than being silently dropped.
+  UNDEFINED_STATUS_LABEL = 'Undefined'
+
   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
@@ -81,6 +86,7 @@ class DecisionsOverview < BaseDocument # rubocop:disable Style/Documentation,Met
     pie_colors = labels.each_with_index.map { |_, i| palette_rgba(i, 0.5) }
 
     velocity = velocity_chart_data
+    status_dist = status_distribution_chart_data
 
     <<~HTML
       <div class="decisions_overview_charts">
@@ -115,7 +121,20 @@ class DecisionsOverview < BaseDocument # rubocop:disable Style/Documentation,Met
       \t\t\t});
       \t\t</script>
       \t</div>
-      \t<div class="chart_cell"></div>
+      \t<div class="chart_cell">
+      \t\t<canvas id="decisions_status_bar"></canvas>
+      \t\t<script>
+      \t\t\tnew Chart(document.getElementById('decisions_status_bar'), {
+      \t\t\t\ttype: 'bar',
+      \t\t\t\tdata: #{status_dist.to_json},
+      \t\t\t\toptions: {
+      \t\t\t\t\tindexAxis: 'y',
+      \t\t\t\t\tplugins: { title: { display: true, text: 'Decision Records by Current Status' }, legend: { display: false } },
+      \t\t\t\t\tscales: { x: { beginAtZero: true, ticks: { precision: 0 } } }
+      \t\t\t\t}
+      \t\t\t});
+      \t\t</script>
+      \t</div>
       </div>
     HTML
   end
@@ -144,6 +163,32 @@ class DecisionsOverview < BaseDocument # rubocop:disable Style/Documentation,Met
     }
   end
 
+  # Tally each decision record under its current status (the "*"-marked Status
+  # row). Records whose current status is undefined fall under "Undefined", which
+  # is ordered last; real statuses keep first-seen order. The count is baked into
+  # each label so small categories stay legible on a linear axis next to a
+  # dominant one.
+  def status_distribution_chart_data # rubocop:disable Metrics/MethodLength,Metrics/AbcSize,Metrics/CyclomaticComplexity,Metrics/PerceivedComplexity
+    counts = Hash.new(0)
+    keys = []
+    @project.project_data.decisions.each do |doc|
+      status = doc.current_status
+      key = status.nil? || status.strip.empty? ? UNDEFINED_STATUS_LABEL : status
+      keys << key unless counts.key?(key)
+      counts[key] += 1
+    end
+    keys << UNDEFINED_STATUS_LABEL if keys.delete(UNDEFINED_STATUS_LABEL)
+
+    colors = keys.each_with_index.map do |k, i|
+      k == UNDEFINED_STATUS_LABEL ? palette_rgba(CHART_PALETTE.length - 1, 0.5) : palette_rgba(i, 0.5)
+    end
+    {
+      labels: keys.map { |k| "#{k} (#{counts[k]})" },
+      datasets: [{ label: 'Decision records', data: keys.map { |k| counts[k] },
+                   backgroundColor: colors, borderWidth: 0 }]
+    }
+  end
+
   def palette_rgba(index, alpha)
     r, g, b = CHART_PALETTE[index % CHART_PALETTE.length]
     "rgba(#{r}, #{g}, #{b}, #{alpha})"