Almirah 0.3.1 → 0.4.1

data/lib/almirah/doc_types/decisions_overview.rb

@@ -0,0 +1,202 @@
+# 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
+
+  # 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
+    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
+    status_dist = status_distribution_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">
+      \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
+
+  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
+
+  # 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})"
+  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/doc_types/source_file.rb

@@ -25,7 +25,6 @@ class SourceFile < PersistentDocument
     depth = relative_path.count('/') + 1 # +1 for the repository folder
     depth += 1 # for the source_files folder
     @specifications_path = "./#{'../' * depth}specifications/"
-    puts @specifications_path
   end
 
   def to_console
@@ -78,13 +77,10 @@ class SourceFile < PersistentDocument
     @html_file_path = output_file_path
     FileUtils.mkdir_p(File.dirname(output_file_path))
 
-    # Calculate the relative path depth to determine correct number of parent directory symbols
-    relative_path = @path.sub("#{@root_path}/", '')
-    depth = relative_path.count('/') + 1 # +1 for the repository folder
-    depth += 1 # for the source_files folder
-    css_path = "#{'../' * depth}css/main.css"
-    js_path = "#{'../' * depth}scripts/main.js"
-    index_path = "#{'../' * depth}index.html"
+    @output_rel_path = output_file_path.split('/build/', 2).last
+    css_path = rel_to('css/main.css')
+    js_path = rel_to('scripts/main.js')
+    index_path = rel_to('index.html')
 
     file = File.open(output_file_path, 'w')
     file_data.each do |s|

data/lib/almirah/link_registry.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+# Project-wide registry of managed documents, used to resolve cross-document
+# links (ADR-186) to their generated output pages. Documents are indexed by
+# their id / filename stem (case-insensitive, folder-independent) and, when they
+# originate from a source file, by their absolute source path (for native
+# Markdown relative links).
+class LinkRegistry
+  attr_reader :collisions
+
+  def initialize
+    @by_id = {}
+    @by_source = {}
+    @collisions = []
+  end
+
+  # Each registered document is expected to already carry an output_rel_path
+  # (its generated page, relative to the build root).
+  def register(doc)
+    key = doc.id.to_s.downcase
+    if @by_id.key?(key) && !@by_id[key].equal?(doc)
+      @collisions << key
+    else
+      @by_id[key] = doc
+    end
+    return unless doc.respond_to?(:path) && doc.path
+
+    @by_source[File.expand_path(doc.path)] = doc
+  end
+
+  def find_by_id(id)
+    @by_id[id.to_s.downcase]
+  end
+
+  def find_by_source(source_path)
+    @by_source[File.expand_path(source_path)]
+  end
+end

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,18 +1,23 @@
+require_relative '../link_registry'
+
 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, :link_registry
 
-  def initialize
+  def initialize # rubocop:disable Metrics/MethodLength
     @specifications = []
     @protocols = []
     @traceability_matrices = []
     @coverage_matrices = []
     @source_files = []
     @implementation_matrices = []
+    @decisions = []
 
     @specifications_dictionary = {}
     @covered_specifications_dictionary = {}
     @implemented_specifications_dictionary = {}
+
+    @link_registry = LinkRegistry.new
   end
 end

data/lib/almirah/project.rb

@@ -9,6 +9,8 @@ require_relative 'search/specifications_db'
 require_relative 'project/doc_linker'
 require_relative 'project_configuration'
 require_relative 'project/project_data'
+require_relative 'console_reporter'
+require_relative 'relative_url'
 
 class Project # rubocop:disable Metrics/ClassLength,Style/Documentation
   attr_accessor :index, :project, :configuration, :project_data
@@ -37,14 +39,17 @@ 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
+    build_link_registry
     create_index
     render_all_specifications(@project_data.specifications)
     render_all_specifications(@project_data.traceability_matrices)
@@ -52,18 +57,25 @@ 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
+    report_broken_links
+    report_rendered
   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
+    build_link_registry
     create_index
     render_all_specifications(@project_data.specifications)
     render_all_specifications(@project_data.traceability_matrices)
@@ -71,22 +83,64 @@ 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
+    report_broken_links
+    report_rendered
+  end
+
+  def report_rendered
+    root = @configuration.project_root_directory
+    base = root == Dir.pwd ? '.' : root
+    ConsoleReporter.result('rendering HTML', File.join(base, 'build', 'index.html'))
+  end
+
+  # Reports cross-document links that could not be resolved (ADR-186, SRS-094),
+  # naming the linking document. The build still completes.
+  def report_broken_links
+    broken = TextLine.broken_links
+    return if broken.empty?
+
+    ConsoleReporter.warn('broken links', broken.length)
+    broken.each { |b| puts ConsoleReporter.warn_detail("  #{b[:document] || '?'}: #{b[:target]}") }
+  end
+
+  # Assigns each document its generated output path (relative to the build root)
+  # and registers it for cross-document link resolution (ADR-186). Runs after all
+  # documents are parsed and before any rendering, so link targets are known.
+  def build_link_registry # rubocop:disable Metrics/MethodLength,Metrics/AbcSize
+    reg = @project_data.link_registry
+    TextLine.link_registry = reg
+    TextLine.reset_broken_links
+    @project_data.specifications.each do |d|
+      d.output_rel_path = "specifications/#{d.id}/#{d.id}.html"
+      reg.register(d)
+    end
+    @project_data.protocols.each do |d|
+      d.output_rel_path = "tests/protocols/#{d.id}/#{d.id}.html"
+      reg.register(d)
+    end
+    @project_data.decisions.each do |d|
+      d.output_rel_path = "decisions/#{d.html_rel_path}"
+      reg.register(d)
+    end
+    @project_data.source_files.each do |d|
+      rel = d.path.sub("#{d.root_path}/", '')
+      d.output_rel_path = "source_files/#{d.repository}/#{rel}.html"
+      reg.register(d)
+    end
   end
 
   def parse_all_specifications
     path = @configuration.project_root_directory
-    # do a lasy pass first to get the list of documents id
     Dir.glob("#{path}/specifications/**/*.md").each do |f|
-      DocFabric.add_lazy_doc_id(f)
-    end
-    # parse documents in the second pass
-    Dir.glob("#{path}/specifications/**/*.md").each do |f| # rubocop:disable Style/CombinableLoops
       doc = DocFabric.create_specification(f)
       @project_data.specifications.append(doc)
       @project_data.specifications_dictionary[doc.id.to_s.downcase] = doc
     end
+    ConsoleReporter.count('parsing specifications', @project_data.specifications.length)
   end
 
   def parse_all_protocols
@@ -95,6 +149,7 @@ class Project # rubocop:disable Metrics/ClassLength,Style/Documentation
       doc = DocFabric.create_protocol(f)
       @project_data.protocols.append(doc)
     end
+    ConsoleReporter.count('parsing test protocols', @project_data.protocols.length)
   end
 
   def parse_all_source_files
@@ -114,6 +169,19 @@ 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?
+    ConsoleReporter.count('parsing decisions', @project_data.decisions.length)
+  end
+
   def parse_test_run(test_run)
     path = @configuration.project_root_directory
     Dir.glob("#{path}/tests/runs/#{test_run}/**/*.md").each do |f|
@@ -138,6 +206,7 @@ class Project # rubocop:disable Metrics/ClassLength,Style/Documentation
         @project_data.traceability_matrices.append doc
       end
     end
+    ConsoleReporter.count('traceability matrices', @project_data.traceability_matrices.length)
   end
 
   def link_all_protocols # rubocop:disable Metrics/MethodLength
@@ -154,6 +223,20 @@ class Project # rubocop:disable Metrics/ClassLength,Style/Documentation
       doc = DocFabric.create_coverage_matrix(value)
       @project_data.coverage_matrices.append doc
     end
+    ConsoleReporter.count('coverage matrices', @project_data.coverage_matrices.length)
+  end
+
+  def link_all_decisions
+    number_of_links = 0
+    @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)
+        number_of_links += 1
+      end
+    end
+    ConsoleReporter.count('decision links', number_of_links)
   end
 
   def link_all_source_files
@@ -164,6 +247,7 @@ class Project # rubocop:disable Metrics/ClassLength,Style/Documentation
       doc = DocFabric.create_implementation_document(value)
       @project_data.implementation_matrices.append doc
     end
+    ConsoleReporter.count('implementation matrices', @project_data.implementation_matrices.length)
   end
 
   def check_wrong_specification_referenced # rubocop:disable Metrics/AbcSize,Metrics/CyclomaticComplexity,Metrics/MethodLength,Metrics/PerceivedComplexity
@@ -237,14 +321,12 @@ class Project # rubocop:disable Metrics/ClassLength,Style/Documentation
     @index = Index.new(@project)
   end
 
-  def render_all_specifications(spec_list) # rubocop:disable Metrics/MethodLength
+  def render_all_specifications(spec_list)
     path = @configuration.project_root_directory
 
     FileUtils.mkdir_p("#{path}/build/specifications")
 
     spec_list.each do |doc|
-      doc.to_console
-
       img_src_dir = "#{path}/specifications/#{doc.id}/img"
       img_dst_dir = "#{path}/build/specifications/#{doc.id}/img"
 
@@ -280,8 +362,6 @@ class Project # rubocop:disable Metrics/ClassLength,Style/Documentation
     FileUtils.mkdir_p("#{path}/build/source_files")
 
     @project_data.source_files.each do |doc|
-      doc.to_console
-
       doc.to_html("#{path}/build/source_files/")
     end
   end
@@ -290,11 +370,34 @@ class Project # rubocop:disable Metrics/ClassLength,Style/Documentation
     path = @configuration.project_root_directory
 
     doc = @index
-    doc.to_console
-
     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_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_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/project_configuration.rb

@@ -4,7 +4,7 @@ class ProjectConfiguration
     attr_accessor :project_root_directory, :parameters
 
     def initialize(path)
-        @project_root_directory = path
+        @project_root_directory = File.expand_path(path)
         @parameters = {}
         load_project_file
     end