Almirah 0.4.3 → 0.4.5

data/lib/almirah/doc_types/risk_record.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require_relative 'decision'
+require_relative '../doc_items/controlled_table'
+
+# A risk record (ADR-215): one Markdown file per risk, collected from the
+# first-level subfolders of the project's risks/ folder, each subfolder being
+# a risk registry. The record format is the decision-record format — filename
+# letters-digits id, frontmatter title, Status table with a "*" current-state
+# marker — so the type reuses Decision wholesale.
+class RiskRecord < Decision
+  # The first-level risks/ subfolder the record was collected from.
+  attr_accessor :registry
+
+  def to_console
+    puts "\e[36mRisk Record: #{@id}\e[0m"
+  end
+
+  # The rendered HTML of the record section whose heading text equals
+  # `section_name` (ADR-216). Empty when there is no such section — the
+  # register renders it as an empty cell.
+  def section_html(section_name)
+    section_items(section_name).map(&:to_html).join
+  end
+
+  # The numeric value of the named section (ADR-217): its items' plain text
+  # parsed as a Float. nil when the section is missing, empty, or not numeric —
+  # the RPN cell renders blank rather than computing a broken record as safe.
+  def section_numeric(section_name)
+    texts = section_items(section_name).filter_map { |i| i.text if i.respond_to?(:text) }
+    Float(texts.join(' ').strip, exception: false)
+  end
+
+  # The record's value for an RPN group (ADR-217): the product of its numeric
+  # input sections. nil when any input is missing or not numeric — such a
+  # record renders a blank cell and is ignored by the summary aggregates.
+  def rpn_value(group)
+    factors = group[:inputs].map { |input| section_numeric(input) }
+    return nil if factors.any?(&:nil?)
+
+    factors.reduce(:*)
+  end
+
+  # The distinct controlled-paragraph IDs the record's Affected Documents
+  # Req-ID column links to (ADR-218), in the section's row order — the
+  # IDs-only content of the register cell. Empty when the record carries no
+  # Affected Documents section or its rows link nothing.
+  def affected_document_ids
+    table = section_items('Affected Documents').find { |i| i.is_a?(ControlledTable) }
+    return [] if table.nil?
+
+    table.rows.flat_map { |row| row.up_link_ids || [] }.uniq
+  end
+
+  private
+
+  # The items between the heading whose text equals `section_name` and the
+  # next heading of the same or a higher level; empty when no heading matches.
+  def section_items(section_name)
+    in_section = false
+    section_level = nil
+    collected = []
+    @items.each do |item|
+      if item.is_a?(Heading) && !in_section
+        next unless item.text.strip == section_name
+
+        in_section = true
+        section_level = item.level
+      elsif in_section
+        break if item.is_a?(Heading) && item.level <= section_level
+
+        collected.append item
+      end
+    end
+    collected
+  end
+end

data/lib/almirah/doc_types/risk_registry_page.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+require_relative 'base_document'
+require_relative 'rpn_rendering'
+require_relative '../doc_items/heading'
+
+# The registry page (ADR-216): build/risks/<registry>/overview.html holding
+# the rendered registry preface (overview.md), when present, followed by the
+# register table — one row per risk record with the implicit linked-ID and
+# Title columns first, then the configured columns filled from each record's
+# section matched by heading text. The Status column is reserved: it is filled
+# from the record's current lifecycle status, never from a section.
+class RiskRegistryPage < BaseDocument
+  include RpnRendering
+
+  STATUS_COLUMN = 'Status'
+  # The column rendered as bare linked IDs from the record's Affected
+  # Documents section (ADR-218), never as the section's prose.
+  AFFECTED_DOCUMENTS_COLUMN = 'Affected Documents'
+
+  attr_accessor :registry, :records, :preface, :columns, :rpn_groups
+
+  # `columns` is the configured per-registry list (ADR-216); nil means the
+  # registry is not configured and gets the implicit columns plus Status only.
+  # `rpn_groups` (ADR-217) appends one computed "<Name> RPN" column per group
+  # after the configured columns; empty appends nothing.
+  def initialize(registry, records, preface, columns, rpn_groups = [])
+    super()
+    @registry = registry
+    @records = records
+    @preface = preface
+    @columns = columns.nil? ? [STATUS_COLUMN] : columns
+    @rpn_groups = rpn_groups
+    @id = 'overview'
+    @title = preface_title || "Risk Registry: #{registry}"
+  end
+
+  def to_console
+    puts "\e[36mRisk Registry: #{@registry}\e[0m"
+  end
+
+  def to_html(output_file_path)
+    html_rows = ['']
+    html_rows.concat preface_html
+    html_rows.append render_register_table
+    save_html_to_file(html_rows, nil, output_file_path)
+  end
+
+  private
+
+  # The preface frontmatter title names the page; without it the registry does.
+  def preface_title
+    params = @preface&.frontmatter&.parameters
+    params && params['title']
+  end
+
+  # The rendered overview.md items. The parser-injected level-0 title heading
+  # is not authored preface content and is skipped.
+  def preface_html
+    return [] if @preface.nil?
+
+    @preface.items.reject { |i| i.is_a?(Heading) && i.level.zero? }.map(&:to_html)
+  end
+
+  def render_register_table
+    s = "<table class=\"controlled risk_register\">\n"
+    s += "\t<thead>\n"
+    s += "\t\t<th>#</th>\n"
+    s += "\t\t<th>Title</th>\n"
+    @columns.each { |c| s += "\t\t<th>#{c}</th>\n" }
+    @rpn_groups.each { |g| s += "\t\t<th>#{g[:name]} RPN</th>\n" }
+    s += "</thead>\n"
+    @records.each { |doc| s += render_record_row(doc) }
+    s + "</table>\n"
+  end
+
+  def render_record_row(doc)
+    href = "./#{record_href(doc)}"
+    s = "\t<tr>\n"
+    s += "\t\t<td class=\"item_id\">\n"
+    s += "\t\t\t<a name=\"#{doc.id}\" id=\"#{doc.id}\" href=\"#{href}\" title=\"Risk Record ID\">#{doc.id.upcase}</a>"
+    s += "\t\t</td>\n"
+    s += "\t\t<td class=\"item_text\" style='padding: 5px;'>\
+<a href=\"#{href}\" class=\"external\">#{record_title(doc)}</a></td>\n"
+    @columns.each { |c| s += render_column_cell(doc, c) }
+    @rpn_groups.each { |g| s += render_rpn_cell(doc, g) }
+    s + "\t</tr>\n"
+  end
+
+  # The Title cell (ENH-221): the frontmatter title with the record's own
+  # leading "ID:" prefix removed, case-insensitively — the ID column already
+  # carries it. A title not starting with the record's ID stays unchanged, and
+  # the record page keeps the full title. Display-only, like the uppercased ID:
+  # anchors and hrefs keep the canonical lowercase id.
+  def record_title(doc)
+    doc.title.to_s.sub(/\A#{Regexp.escape(doc.id)}\s*:\s*/i, '')
+  end
+
+  # The record page path relative to the registry page, which sits at the
+  # registry root: the record's html_rel_path minus its registry segment.
+  def record_href(doc)
+    doc.html_rel_path.split('/', 2).last
+  end
+
+  def render_column_cell(doc, column)
+    return "\t\t<td class=\"item_status\">#{doc.current_status}</td>\n" if column == STATUS_COLUMN
+    return render_affected_documents_cell(doc) if column == AFFECTED_DOCUMENTS_COLUMN
+
+    "\t\t<td class=\"item_text\">#{doc.section_html(column)}</td>\n"
+  end
+
+  # IDs only (ADR-218): each distinct linked controlled-paragraph ID as a
+  # clickable link in row order; a dangling ID renders in the existing
+  # broken-link style rather than being dropped. The Proposed Text stays on
+  # the record page.
+  def render_affected_documents_cell(doc)
+    links = doc.affected_document_ids.map { |id| affected_document_link(doc, id) }
+    "\t\t<td class=\"item_id\">#{links.join(', ')}</td>\n"
+  end
+
+  def affected_document_link(doc, item_id)
+    if doc.wrong_links_hash.key?(item_id)
+      %(<span class="broken_link" title="Unresolved reference">#{item_id}</span>)
+    else
+      spec = /^([a-zA-Z]+)-\d+/.match(item_id)&.[](1)&.downcase
+      href = "./../../specifications/#{spec}/#{spec}.html##{item_id}"
+      %(<a href="#{href}" class="external" title="Affected document">#{item_id}</a>)
+    end
+  end
+
+  # The computed group cell (ADR-217): the record's group value, blank when
+  # any input is missing or not numeric, coloured by the group's thresholds
+  # when configured.
+  def render_rpn_cell(doc, group)
+    value = doc.rpn_value(group)
+    return "\t\t<td class=\"item_rpn\"></td>\n" if value.nil?
+
+    classes = ['item_rpn', rpn_threshold_class(value, group)].compact.join(' ')
+    "\t\t<td class=\"#{classes}\">#{format_rpn(value)}</td>\n"
+  end
+end

data/lib/almirah/doc_types/risks_overview.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require_relative 'base_document'
+require_relative 'rpn_rendering'
+
+# The all-registries summary page (ADR-219): build/risks/overview.html, the
+# target of the top-menu Risks button. One table row per registry, in
+# file-system order, with the columns Risk Registry (linked to the registry
+# page), Total Risks, Open Risks, Highest RPN and Average RPN — the RPN
+# aggregates computed over the registry's leading RPN group, ignoring records
+# whose group value is blank. The Risk Registry cell shows the registry
+# preface's frontmatter title, falling back to the folder name (ENH-221).
+class RisksOverview < BaseDocument
+  include RpnRendering
+
+  OPEN_EXCLUDED_STATUS = 'Closed'
+
+  attr_accessor :registries, :configuration, :prefaces
+
+  # `registries` is the ordered list of [name, records] pairs; `prefaces`
+  # maps a registry name to its parsed overview.md, when it has one.
+  def initialize(registries, configuration, prefaces = {})
+    super()
+    @registries = registries
+    @configuration = configuration
+    @prefaces = prefaces
+    @id = 'overview'
+    @title = 'Risk Registries'
+  end
+
+  def to_console
+    puts "\e[36mRisks Overview: #{@id}\e[0m"
+  end
+
+  def to_html(output_file_path)
+    html_rows = ['']
+    html_rows.append "<h1>#{@title}</h1>\n"
+    html_rows.append render_registries_table
+    save_html_to_file(html_rows, nil, output_file_path)
+  end
+
+  private
+
+  def render_registries_table
+    s = "<table class=\"controlled risks_overview\">\n"
+    s += "\t<thead>\n"
+    s += "\t\t<th>Risk Registry</th>\n"
+    s += "\t\t<th>Total Risks</th>\n"
+    s += "\t\t<th>Open Risks</th>\n"
+    s += "\t\t<th>Highest RPN</th>\n"
+    s += "\t\t<th>Average RPN</th>\n"
+    s += "</thead>\n"
+    @registries.each { |name, records| s += render_registry_row(name, records) }
+    s + "</table>\n"
+  end
+
+  def render_registry_row(name, records)
+    group = @configuration.get_risk_rpn_groups(name).first
+    values = group ? records.filter_map { |r| r.rpn_value(group) } : []
+    s = "\t<tr>\n"
+    s += "\t\t<td class=\"item_text\" style='padding: 5px;'>\
+<a name=\"#{name}\" id=\"#{name}\" href=\"./#{name}/overview.html\" class=\"external\" \
+title=\"Risk Registry\">#{registry_title(name)}</a></td>\n"
+    s += "\t\t<td class=\"item_rpn\">#{records.length}</td>\n"
+    s += "\t\t<td class=\"item_rpn\">#{open_count(records)}</td>\n"
+    s += render_highest_cell(values, group)
+    s += render_average_cell(values)
+    s + "\t</tr>\n"
+  end
+
+  # The registry preface's frontmatter title (ENH-221) — the same source the
+  # registry page heading uses — or the folder name when the registry has no
+  # preface or the preface carries no title.
+  def registry_title(name)
+    params = @prefaces[name]&.frontmatter&.parameters
+    (params && params['title']) || name
+  end
+
+  # Every record whose marked status is not Closed counts as open — including
+  # records with no current-status marker (ADR-219 keeps the count honest to
+  # the marker; another terminal status is the registry preface's to document).
+  def open_count(records)
+    records.count { |r| r.current_status.to_s.strip != OPEN_EXCLUDED_STATUS }
+  end
+
+  # The worst risk's verdict carries up: the cell keeps the leading group's
+  # threshold colouring. Blank without a group or computable values.
+  def render_highest_cell(values, group)
+    return "\t\t<td class=\"item_rpn\"></td>\n" if values.empty?
+
+    highest = values.max
+    classes = ['item_rpn', rpn_threshold_class(highest, group)].compact.join(' ')
+    "\t\t<td class=\"#{classes}\">#{format_rpn(highest)}</td>\n"
+  end
+
+  def render_average_cell(values)
+    return "\t\t<td class=\"item_rpn\"></td>\n" if values.empty?
+
+    average = (values.sum.to_f / values.length).round(1)
+    "\t\t<td class=\"item_rpn\">#{format_rpn(average)}</td>\n"
+  end
+end

data/lib/almirah/doc_types/rpn_rendering.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+# Shared RPN cell presentation (ADR-217, reused by the registries summary of
+# ADR-219): the threshold band class and the integer-when-whole formatting.
+module RpnRendering
+  # Acceptable at or below the acceptable bound, unacceptable at or above the
+  # unacceptable bound, caution between them (the ALARP band); a lone bound
+  # leaves the rest of the range as caution. nil when no thresholds configured.
+  def rpn_threshold_class(value, group)
+    if group[:acceptable] && value <= group[:acceptable]
+      'rpn_acceptable'
+    elsif group[:unacceptable] && value >= group[:unacceptable]
+      'rpn_unacceptable'
+    elsif group[:acceptable] || group[:unacceptable]
+      'rpn_caution'
+    end
+  end
+
+  # Whole values print as integers (8 * 3 -> 24, not 24.0).
+  def format_rpn(value)
+    value == value.to_i ? value.to_i.to_s : value.to_s
+  end
+end

data/lib/almirah/project/project_data.rb

@@ -3,7 +3,8 @@ 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, :decisions, :decision_groups, :work_items, :link_registry
+              :implementation_matrices, :decisions, :decision_groups, :risk_records, :risk_registries,
+              :risk_registry_prefaces, :link_registry
 
   def initialize
     @specifications = []
@@ -16,9 +17,14 @@ class ProjectData
     # Insertion-ordered list of single-key hashes { "<first-level folder>" => [Decision, ...] },
     # grouping decision records by the planning folder they live in (see ADR-197).
     @decision_groups = []
-    # Every Scope-row WorkItem across all decision records, keyed by its canonical
-    # "<record>.<step>.<activity>" id (see ADR-194), populated by link_work_items.
-    @work_items = {}
+    @risk_records = []
+    # Insertion-ordered list of single-key hashes { "<first-level risks/ folder>" => [RiskRecord, ...] },
+    # grouping risk records by the registry they live in (see ADR-215).
+    @risk_registries = []
+    # Registry prefaces (ADR-216): each registry's parsed overview.md, keyed by
+    # the registry (first-level risks/ folder) name. A registry without an
+    # overview.md has no entry; its page simply starts at the register table.
+    @risk_registry_prefaces = {}
 
     @specifications_dictionary = {}
     @covered_specifications_dictionary = {}