Almirah 0.4.2 → 0.4.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5221af43605bcaab2815ac5c940d53188394a92f8f8fadbbd2def016d1d52328
-  data.tar.gz: dd1d271774fe527d93512134b70cca3471048ff2a0859327c813eb75ebd35b54
+  metadata.gz: 46e67646a16db801d9dbe0cd2c2873a38e6e35068c5cde855179b9f5beb00089
+  data.tar.gz: c4953874698c949e6711ebdfa0c84dc0b56d6291674a7127d6ccfbb31802cea4
 SHA512:
-  metadata.gz: 6cf6a8d5892855c7b8752a2a3d447fec79dcf89a6a796b931709b2207ceeaddaede5cf7ac262ce13ab8b47aa081ead25fd225f353fff3afb84bc01dfaf2dfbdd
-  data.tar.gz: 9c0c6cffe8a41a19fc6778bcb0a3210f5a0ca3402b058d6b5f011b0434805fd11035be76a9ec6a742485839fe7523480d043923e582a2f0367c4fadb93922473
+  metadata.gz: 1401a30fbde34dd6c21b77685e3e2506753e7b302d528189e5d3d129eff6f9a15dd169f756be53ea1467dc5805fe36d0ce0678d2a446a866b18e95c66e70de64
+  data.tar.gz: 1db3dd4230d6b77154758bdbad3802fb121ba23c41a3ee33aeb8ba70ac0be4a7ac0d8e14ea05667869d2625fcc638ca2d900a47270f22ff9bac1077c932173ba

data/bin/almirah

@@ -1,5 +1,5 @@
 #!/usr/bin/env ruby
 
-require "almirah"
+require 'almirah'
 
-CLI.start(ARGV)
+CLI.start(ARGV)

data/lib/almirah/doc_fabric.rb

@@ -7,6 +7,7 @@ require_relative 'doc_types/implementation'
 require_relative 'doc_types/traceability'
 require_relative 'doc_types/decision'
 require_relative 'doc_types/decisions_overview'
+require_relative 'doc_types/critical_chain_page'
 require_relative 'doc_parser'
 require_relative 'source_file_parser'
 require_relative 'dom/document'
@@ -67,6 +68,8 @@ class DocFabric
     doc.extract_start_date
     doc.extract_target_date
     doc.extract_target_release_version
+    doc.extract_owners
+    doc.extract_scope_table
     doc
   end
 
@@ -74,6 +77,10 @@ class DocFabric
     DecisionsOverview.new project
   end
 
+  def self.create_critical_chain_page(project)
+    CriticalChainPage.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

data/lib/almirah/doc_items/blockquote.rb

@@ -1,22 +1,21 @@
-require_relative "doc_item"
+require_relative 'doc_item'
 
 class Blockquote < DocItem
+  attr_accessor :text
 
-    attr_accessor :text
+  def initialize(text)
+    @text = text
+  end
 
-    def initialize(text)
-        @text = text
+  def to_html
+    s = ''
+    f_text = format_string(@text)
+    if @@html_table_render_in_progress
+      s += "</table>\n"
+      @@html_table_render_in_progress = false
     end
 
-    def to_html
-        s = ''
-        f_text = format_string(@text)
-        if @@html_table_render_in_progress
-            s += "</table>\n"
-            @@html_table_render_in_progress = false
-        end
-
-        s += "<div class=\"blockquote\"><p>#{f_text}</div>\n"
-        return s
-    end
-end
+    s += "<div class=\"blockquote\"><p>#{f_text}</div>\n"
+    s
+  end
+end

data/lib/almirah/doc_items/code_block.rb

@@ -1,27 +1,25 @@
-require_relative "doc_item"
+require_relative 'doc_item'
 
 class CodeBlock < DocItem
+  attr_accessor :suggested_format, :code_lines
 
-    attr_accessor :suggested_format
-    attr_accessor :code_lines
+  def initialize(suggested_format)
+    @suggested_format = suggested_format
+    @code_lines = []
+  end
 
-    def initialize(suggested_format)
-        @suggested_format = suggested_format
-        @code_lines = Array.new
-    end
-
-    def to_html
-        s = ''
+  def to_html
+    s = ''
 
-        if @@html_table_render_in_progress
-            s += "</table>\n"
-            @@html_table_render_in_progress = false
-        end
-        s += "<code>"
-        @code_lines.each do |l|
-            s += escape_text(l) + " </br>" # ADR-188/SRS-096: code content is inert text
-        end
-        s += "</code>\n"
-        return s
+    if @@html_table_render_in_progress
+      s += "</table>\n"
+      @@html_table_render_in_progress = false
+    end
+    s += '<code>'
+    @code_lines.each do |l|
+      s += escape_text(l) + ' </br>' # ADR-188/SRS-096: code content is inert text
     end
-end
+    s += "</code>\n"
+    s
+  end
+end

data/lib/almirah/doc_items/controlled_paragraph.rb

@@ -21,7 +21,7 @@ class ControlledParagraph < Paragraph
       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> <th title=\"Decision Record\">DR</th> </thead>\n"
-      @@html_table_render_in_progress = true # rubocop:disable Style/ClassVars
+      @@html_table_render_in_progress = true
     end
     f_text = format_string(@text)
     s += "\t<tr>\n"
@@ -85,7 +85,7 @@ class ControlledParagraph < Paragraph
     end
 
     if @coverage_links
-      if tmp = /^(.+)[.]\d+/.match(@coverage_links[0].id)    # guessing that all the links refer to one document
+      if tmp = /^(.+)[.]\d+/.match(@coverage_links[0].id) # guessing that all the links refer to one document
         cov_link_doc_name = tmp[1].downcase
       end
       if @coverage_links.length == 1

data/lib/almirah/doc_items/controlled_table.rb

@@ -1,10 +1,10 @@
 require_relative 'controlled_table_row'
 require_relative 'text_line'
 
-class ControlledTableColumn < TextLine # rubocop:disable Style/Documentation
+class ControlledTableColumn < TextLine
   attr_accessor :text
 
-  def initialize(text) # rubocop:disable Lint/MissingSuper
+  def initialize(text)
     @text = text.strip
   end
 
@@ -17,7 +17,7 @@ end
 class RegualrColumn < ControlledTableColumn
 end
 
-class TestStepNumberColumn < ControlledTableColumn # rubocop:disable Style/Documentation
+class TestStepNumberColumn < ControlledTableColumn
   attr_accessor :step_number, :row_id
 
   def initialize(text)
@@ -32,7 +32,7 @@ class TestStepNumberColumn < ControlledTableColumn # rubocop:disable Style/Docum
   end
 end
 
-class TestStepResultColumn < ControlledTableColumn # rubocop:disable Style/Documentation
+class TestStepResultColumn < ControlledTableColumn
   def to_html
     f_text = format_string(@text)
     case @text.downcase
@@ -46,7 +46,7 @@ class TestStepResultColumn < ControlledTableColumn # rubocop:disable Style/Docum
   end
 end
 
-class TestStepReferenceColumn < ControlledTableColumn # rubocop:disable Style/Documentation
+class TestStepReferenceColumn < ControlledTableColumn
   attr_accessor :up_link_ids, :up_link_doc_ids, :parent_row
 
   def initialize(parent_row, text)
@@ -99,7 +99,7 @@ class TestStepReferenceColumn < ControlledTableColumn # rubocop:disable Style/Do
     end
   end
 
-  def to_html # rubocop:disable Metrics/AbcSize,Metrics/MethodLength
+  def to_html
     s = ''
     specifications_path = @parent_row.parent_doc.specifications_path
     if @up_link_ids
@@ -133,10 +133,10 @@ class TestStepReferenceColumn < ControlledTableColumn # rubocop:disable Style/Do
   end
 end
 
-class ControlledTable < DocItem # rubocop:disable Style/Documentation
+class ControlledTable < DocItem
   attr_accessor :column_names, :rows, :is_separator_detected
 
-  def initialize(doc, markdown_table) # rubocop:disable Lint/MissingSuper
+  def initialize(doc, markdown_table)
     @parent_doc = doc
     @parent_heading = doc.headings[-1]
 
@@ -158,7 +158,7 @@ class ControlledTable < DocItem # rubocop:disable Style/Documentation
     true
   end
 
-  def format_columns(columns) # rubocop:disable Metrics/AbcSize,Metrics/MethodLength
+  def format_columns(columns)
     new_row = ControlledTableRow.new
     new_row.parent_doc = @parent_doc
 
@@ -198,11 +198,11 @@ class ControlledTable < DocItem # rubocop:disable Style/Documentation
     new_row
   end
 
-  def to_html # rubocop:disable Metrics/MethodLength
+  def to_html
     s = ''
     if @@html_table_render_in_progress
       s += "</table>\n"
-      @@html_table_render_in_progress = false # rubocop:disable Style/ClassVars
+      @@html_table_render_in_progress = false
     end
 
     s += "<table class=\"markdown_table\">\n"

data/lib/almirah/doc_items/controlled_table_row.rb

@@ -1,23 +1,20 @@
-require_relative "doc_item"
+require_relative 'doc_item'
 
 class ControlledTableRow < DocItem
+  attr_accessor :id, :up_link_ids, :columns
 
-    attr_accessor :id
-    attr_accessor :up_link_ids
-    attr_accessor :columns
-    
-    def initialize
-        @id = ""
-        @up_link_ids = nil
-        @columns = []
-    end
+  def initialize
+    @id = ''
+    @up_link_ids = nil
+    @columns = []
+  end
 
-    def to_html
-        s = ""
-        s += "\t<tr>\n"
-        @columns.each do |col|
-            s += col.to_html    # "\t\t<td>#{col}</td>\n\r"
-        end
-        s += "\t</tr>\n"
+  def to_html
+    s = ''
+    s += "\t<tr>\n"
+    @columns.each do |col|
+      s += col.to_html # "\t\t<td>#{col}</td>\n\r"
     end
-end
+    s += "\t</tr>\n"
+  end
+end

data/lib/almirah/doc_items/doc_footer.rb

@@ -1,17 +1,14 @@
-require_relative "doc_item"
+require_relative 'doc_item'
 
 class DocFooter < DocItem
+  def initialize; end
 
-    def initialize
+  def to_html
+    s = ''
+    if @@html_table_render_in_progress
+      s += "</table>\n"
+      @@html_table_render_in_progress = false
     end
-
-    def to_html
-        s = ''
-        if @@html_table_render_in_progress
-            s += "</table>\n"
-            @@html_table_render_in_progress = false
-        end
-        return s
-    end
-
-end
+    s
+  end
+end

data/lib/almirah/doc_items/doc_item.rb

@@ -2,13 +2,13 @@
 
 require_relative 'text_line'
 
-class DocItem < TextLine # rubocop:disable Style/Documentation
+class DocItem < TextLine
   attr_accessor :parent_doc, :parent_heading
 
   @parent_doc = nil
   @parent_heading = nil
 
-  @@html_table_render_in_progress = false # rubocop:disable Style/ClassVars
+  @@html_table_render_in_progress = false
 
   def initialize(doc)
     super()

data/lib/almirah/doc_items/heading.rb

@@ -92,7 +92,7 @@ class Heading < Paragraph
     heading_level = level.to_s
     heading_text = get_section_info_html
     if level.zero?
-      heading_level = 1.to_s        # Render Doc Title as a regular h1
+      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"

data/lib/almirah/doc_items/image.rb

@@ -1,35 +1,33 @@
-require_relative "doc_item"
+require_relative 'doc_item'
 
 class Image < DocItem
+  attr_accessor :text, :path
 
-    attr_accessor :text
-    attr_accessor :path
+  def initialize(text, path)
+    @text = text
+    @path = path
+  end
 
-    def initialize(text, path)
-        @text = text
-        @path = path
-    end
+  def getTextWithoutSpaces
+    @text.split.join('-')
+  end
 
-    def getTextWithoutSpaces
-        return @text.split.join('-')
+  def to_html
+    s = ''
+    if @@html_table_render_in_progress
+      s += "</table>\n"
+      @@html_table_render_in_progress = false
     end
 
-    def to_html
-        s = ''
-        if @@html_table_render_in_progress
-            s += "</table>\n"
-            @@html_table_render_in_progress = false
-        end
-
-        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
+    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
-end
+
+    s += "<p style=\"margin-top: 15px;\"><img src=\"#{escape_attr(src)}\" alt=\"#{alt}\" "
+    s += 'href="javascript:void(0)" onclick="image_OnClick(this)">'
+    s
+  end
+end

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 == '*' || c == '-'
+        if ['*', '-'].include?(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*([*\-]\s+)(.*)/.match(raw_text)
+    res = /^\s*([*-]\s+)(.*)/.match(raw_text)
     return true if res
 
     false

data/lib/almirah/doc_items/markdown_table.rb

@@ -6,7 +6,7 @@ class MarkdownTable < DocItem
   attr_accessor :column_names, :rows, :heading_row, :is_separator_detected, :column_aligns,
                 :is_decision_status_table
 
-  def initialize(doc, heading_row) # rubocop:disable Metrics/MethodLength
+  def initialize(doc, heading_row)
     super(doc)
     @heading_row = heading_row
 
@@ -54,6 +54,13 @@ class MarkdownTable < DocItem
     true
   end
 
+  # Header-addressed cell grid (each row an array of stripped cell strings).
+  # Named alongside ScopeTable#cells so Decision's Scope/Status/version readers
+  # can treat either table type uniformly (ADR-194).
+  def cells
+    @rows
+  end
+
   def to_html
     s = ''
     if @@html_table_render_in_progress
@@ -80,7 +87,7 @@ class MarkdownTable < DocItem
       row.each_with_index do |col, index|
         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
+        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 = ''

data/lib/almirah/doc_items/scope_table.rb

@@ -0,0 +1,188 @@
+# frozen_string_literal: true
+
+require 'date'
+require_relative 'controlled_table'
+require_relative 'work_item'
+
+# Purpose-built controlled table for a Decision Record's `# Scope` section
+# (ADR-194). It is modelled on ControlledTable but addresses its columns by
+# header text (not position) and has no fixed link column: it locates `#`,
+# `Item`, `Owner`, `Depends On`, and `Status` wherever the author placed them.
+#
+# Each data row becomes a WorkItem (the dependency-network node). The table also
+# keeps a plain header-addressed cell grid (`cells`) so the ADR-193 Scope
+# readers (owners / WIP / dates) keep working unchanged after the Scope section
+# stopped being a plain MarkdownTable.
+class ScopeTable < ControlledTable
+  attr_reader :cells, :work_items
+
+  def initialize(doc, markdown_table)
+    @parent_doc = doc
+    @parent_heading = doc.headings[-1]
+    @column_names = markdown_table.column_names
+    @is_separator_detected = markdown_table.is_separator_detected
+    @cells = []
+    @work_items = []
+    @col = locate_columns(@column_names)
+    # The switch to ScopeTable happens on the first data row, so the source
+    # MarkdownTable carries none yet; any it did are re-read for safety.
+    markdown_table.rows.each { |cells| append_cells(cells) }
+  end
+
+  def add_row(row)
+    append_cells(split_table_cells(row).map(&:strip))
+    true
+  end
+
+  # True when the table has a leading `#` step column, hence a per-row anchor a
+  # dependent record can deep-link to (ADR-194).
+  def step_column?
+    !@col[:step].nil?
+  end
+
+  # Render as a controlled table: an anchored, centered step number in the `#`
+  # column (so rows are linkable, like the protocol table) and formatted text
+  # for every other cell.
+  def to_html
+    s = +''
+    if @@html_table_render_in_progress
+      s << "</table>\n"
+      @@html_table_render_in_progress = false
+    end
+    s << "<table class=\"markdown_table\">\n\t<thead>"
+    @column_names.each { |h| s << " <th>#{format_string(h.strip)}</th>" }
+    s << " </thead>\n"
+    @cells.each_with_index { |cells, i| s << row_html(cells, @work_items[i]) }
+    s << "</table>\n"
+    s
+  end
+
+  private
+
+  def locate_columns(column_names)
+    index_of = lambda do |name|
+      column_names.each_with_index { |h, i| return i if h.to_s.strip == name }
+      nil
+    end
+    { step: index_of.call('#'), item: index_of.call('Item'), owner: index_of.call('Owner'),
+      depends_on: index_of.call('Depends On'), status: index_of.call('Status'),
+      est_focused: index_of.call('Est (focused)'), est_safe: index_of.call('Est (safe)'),
+      start_date: index_of.call('Start Date'), target_date: index_of.call('Target Date') }
+  end
+
+  def append_cells(cells)
+    @cells << cells
+    @work_items << build_work_item(cells)
+  end
+
+  def build_work_item(cells)
+    WorkItem.new(
+      record_id: @parent_doc.id,
+      step: step_number(cells, @cells.length), # 1-based row order fallback
+      activity: cell(cells, @col[:item]),
+      owner: cell(cells, @col[:owner]),
+      status: cell(cells, @col[:status]),
+      depends_on_refs: parse_depends_on(cell(cells, @col[:depends_on])),
+      start_date: parse_date(cell(cells, @col[:start_date])),
+      target_date: parse_date(cell(cells, @col[:target_date])),
+      **estimate_attrs(cells)
+    )
+  end
+
+  # A Scope Start/Target Date cell as a Date (ADR-213), or nil when blank or not
+  # in the DD-MM-YYYY form the rest of the planning views read (ADR-205).
+  def parse_date(text)
+    match = /\A(\d{2})-(\d{2})-(\d{4})\z/.match(text.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
+
+  # The ADR-195 estimate-derived attributes: focused and safe working-day
+  # estimates (blank/unparseable -> 0) and the owning record's sequence number
+  # (the critical-chain priority tiebreak).
+  def estimate_attrs(cells)
+    {
+      focused_estimate: parse_estimate(cell(cells, @col[:est_focused])),
+      safe_estimate: parse_estimate(cell(cells, @col[:est_safe])),
+      record_sequence: @parent_doc.sequence_number.to_i
+    }
+  end
+
+  # A Scope estimate cell as a non-negative number of working days (decimals
+  # allowed); blank, unparseable, or negative values count as 0 (ADR-195).
+  def parse_estimate(text)
+    value = Float(text.to_s.strip, exception: false)
+    value&.positive? ? value : 0.0
+  end
+
+  # The `#` column's integer when present; otherwise the row's 1-based position,
+  # so a record without the column keeps each row as its own sequential step.
+  def step_number(cells, row_position)
+    return row_position if @col[:step].nil?
+
+    value = cell(cells, @col[:step]).to_s.strip
+    value.match?(/\A\d+\z/) ? value.to_i : row_position
+  end
+
+  def parse_depends_on(text)
+    text.to_s.scan(/>\[([^\]]+)\]/).flatten.map(&:strip)
+  end
+
+  def cell(cells, index)
+    return '' if index.nil?
+
+    cells[index].to_s.strip
+  end
+
+  def row_html(cells, work_item)
+    s = +"\t<tr>\n"
+    cells.each_with_index { |value, index| s << cell_html(value, index, work_item) }
+    s << "\t</tr>\n"
+    s
+  end
+
+  def cell_html(value, index, work_item)
+    return depends_on_html(work_item) if index == @col[:depends_on]
+    return step_cell_html(value, work_item) if index == @col[:step]
+    return date_cell_html(value) if [@col[:start_date], @col[:target_date]].include?(index)
+
+    "\t\t<td>#{format_string(value.strip)}</td>\n"
+  end
+
+  # The Start/Target Date cells are kept on one line so a DD-MM-YYYY date never
+  # wraps at its hyphens in a narrow column (ADR-213).
+  def date_cell_html(value)
+    "\t\t<td class=\"scope_date\">#{format_string(value.strip)}</td>\n"
+  end
+
+  # The `#` cell is a named anchor (id + name), mirroring the test-step number
+  # column, so a dependent record's Depends On link can target this row.
+  def step_cell_html(value, work_item)
+    anchor = work_item.row_anchor
+    "\t\t<td style=\"text-align: center;\">" \
+      "<a name=\"#{anchor}\" id=\"#{anchor}\" href=\"##{anchor}\">#{format_string(value.strip)}</a></td>\n"
+  end
+
+  # Render each authored Depends On reference as a link to the resolved target
+  # record. When the target record has a `#` step column, the link deep-jumps to
+  # the aligned activity row (its step anchor); otherwise it opens the record
+  # page (no such anchor exists). Unresolved references render as broken-link
+  # spans (ADR-194 also reports them on the console).
+  def depends_on_html(work_item)
+    return "\t\t<td></td>\n" if work_item.depends_on_refs.empty?
+
+    links = work_item.depends_on_refs.map { |ref| dependency_ref_html(ref, work_item) }
+    "\t\t<td>#{links.join(', ')}</td>\n"
+  end
+
+  def dependency_ref_html(ref, work_item)
+    dep = work_item.resolved_dependencies[ref]
+    return "<span class=\"broken_link\" title=\"Unresolved Depends On\">#{ref}</span>" if dep.nil?
+
+    href = RelativeUrl.between(@parent_doc.output_rel_path, dep[:doc].output_rel_path, fragment: dep[:anchor])
+    "<a href=\"#{href}\" class=\"external\" title=\"Depends on #{dep[:label]}\">#{ref}</a>"
+  end
+end