Almirah 0.4.3 → 0.4.5

data/lib/almirah/project.rb

@@ -2,7 +2,6 @@
 
 require 'fileutils'
 require_relative 'doc_fabric'
-require_relative 'doc_items/work_item'
 require_relative 'navigation_pane'
 require_relative 'doc_types/traceability'
 require_relative 'doc_types/index'
@@ -45,13 +44,14 @@ class Project
     parse_all_protocols
     parse_all_source_files
     parse_decisions
+    parse_risks
     link_all_specifications
     link_all_protocols
     link_all_source_files
     link_all_decisions
+    link_all_risks
     check_wrong_specification_referenced
     build_link_registry
-    link_work_items
     create_index
     render_all_specifications(@project_data.specifications)
     render_all_specifications(@project_data.traceability_matrices)
@@ -60,12 +60,13 @@ class Project
     render_all_source_files
     render_all_specifications(@project_data.implementation_matrices) # intentionally after source file rendering
     render_decisions_overview
-    render_critical_chain_page
     render_all_decisions
+    render_all_risk_records
+    render_risk_registry_pages
+    render_risks_overview
     render_index
     create_search_data
     report_broken_links
-    report_kit_violations
     report_rendered
   end
 
@@ -74,13 +75,14 @@ class Project
     parse_test_run test_run
     parse_all_source_files
     parse_decisions
+    parse_risks
     link_all_specifications
     link_all_protocols
     link_all_source_files
     link_all_decisions
+    link_all_risks
     check_wrong_specification_referenced
     build_link_registry
-    link_work_items
     create_index
     render_all_specifications(@project_data.specifications)
     render_all_specifications(@project_data.traceability_matrices)
@@ -89,12 +91,13 @@ class Project
     render_all_source_files
     render_all_specifications(@project_data.implementation_matrices) # intentionally after source file rendering
     render_decisions_overview
-    render_critical_chain_page
     render_all_decisions
+    render_all_risk_records
+    render_risk_registry_pages
+    render_risks_overview
     render_index
     create_search_data
     report_broken_links
-    report_kit_violations
     report_rendered
   end
 
@@ -114,111 +117,6 @@ class Project
     broken.each { |b| puts ConsoleReporter.warn_detail("  #{b[:document] || '?'}: #{b[:target]}") }
   end
 
-  # Builds the per-row WorkItem dependency network (ADR-194): registers every
-  # Scope-row work item, fills the intra-record step-order edges, then resolves
-  # each Depends On reference globally (LinkRegistry) to the activity-type-aligned
-  # work item of the target record, tagging each cross-record edge in-group or
-  # cross-group against the decision_groups boundary (ADR-197). Unresolved
-  # references are collected for report_kit_violations. Runs after
-  # build_link_registry (so every record resolves) and before rendering (so the
-  # overview Kit column is ready).
-  def link_work_items
-    @kit_unresolved = []
-    @project_data.decisions.each do |d|
-      d.scope_work_items.each { |wi| @project_data.work_items[wi.id] = wi }
-    end
-    link_intra_record_steps
-    link_cross_record_dependencies
-  end
-
-  # Each row's lower-numbered same-record steps are its predecessors; equal step
-  # numbers are concurrent (no edge). These edges are in-group by definition.
-  def link_intra_record_steps
-    @project_data.decisions.each do |d|
-      items = d.scope_work_items
-      items.each do |wi|
-        items.each do |other|
-          next if other.equal?(wi) || other.step >= wi.step
-
-          wi.add_predecessor(other, cross_group: false)
-          other.add_successor(wi)
-        end
-      end
-    end
-  end
-
-  def link_cross_record_dependencies
-    @project_data.decisions.each do |d|
-      d.scope_work_items.each do |wi|
-        wi.depends_on_refs.each { |ref| link_dependency(d, wi, ref) }
-      end
-    end
-  end
-
-  def link_dependency(record, work_item, ref)
-    target = @project_data.link_registry.find_by_id(ref)
-    unless target.is_a?(Decision)
-      @kit_unresolved << { record: record.id, target: ref }
-      return
-    end
-    prereq = aligned_work_item(target, work_item.activity)
-    return if prereq.nil? || prereq.equal?(work_item)
-
-    cross = decision_group_name(record) != decision_group_name(target)
-    work_item.add_predecessor(prereq, cross_group: cross)
-    prereq.add_successor(work_item)
-    anchor = target.scope_table&.step_column? ? prereq.row_anchor : nil
-    work_item.add_resolved_dependency(ref, target, anchor, prereq.id)
-  end
-
-  # The target record's work item whose activity (Item) matches `activity`,
-  # falling back to the nearest earlier activity by canonical phase order, then
-  # (when the target has only later activities) to its earliest row. nil only
-  # when the target has no Scope rows.
-  def aligned_work_item(target, activity)
-    items = target.scope_work_items
-    return nil if items.empty?
-
-    exact = items.select { |t| t.activity == activity }.min_by(&:step)
-    return exact if exact
-
-    rank = WorkItem::ACTIVITY_ORDER.index(activity) || WorkItem::ACTIVITY_ORDER.length
-    earlier = items.select { |t| t.activity_rank <= rank }
-    return items.min_by { |t| [t.activity_rank, t.step] } if earlier.empty?
-
-    earlier.min_by { |t| [-t.activity_rank, t.step] }
-  end
-
-  # The planning-group name (first-level decisions/ folder) a record belongs to,
-  # read from the decision_groups collection (ADR-197).
-  def decision_group_name(doc)
-    group = @project_data.decision_groups.find { |g| g.values.first.include?(doc) }
-    group&.keys&.first
-  end
-
-  # Reports the two kit gates and unresolved Depends On references (ADR-194), all
-  # as non-failing console warnings alongside report_broken_links.
-  def report_kit_violations
-    @kit_unresolved ||= []
-    phase = @project_data.work_items.each_value.select(&:phase_order_violation?)
-    cross = @project_data.work_items.each_value.select(&:cross_record_violation?)
-    total = phase.length + cross.length + @kit_unresolved.length
-    return if total.zero?
-
-    ConsoleReporter.warn('kit violations', total)
-    phase.each do |wi|
-      blocking = wi.intra_record_predecessors.reject(&:done?).map(&:id).join(', ')
-      puts ConsoleReporter.warn_detail("  phase order: #{wi.id} started before #{blocking}")
-    end
-    cross.each do |wi|
-      blocking = wi.cross_record_predecessors.reject(&:done?).map(&:id).join(', ')
-      puts ConsoleReporter.warn_detail("  not kitted: #{wi.id} needs #{blocking}")
-    end
-    @kit_unresolved.each do |u|
-      puts ConsoleReporter.warn_detail("  unresolved Depends On: #{u[:record]} -> #{u[:target]}")
-    end
-  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.
@@ -238,6 +136,10 @@ class Project
       d.output_rel_path = "decisions/#{d.html_rel_path}"
       reg.register(d)
     end
+    @project_data.risk_records.each do |d|
+      d.output_rel_path = "risks/#{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"
@@ -309,6 +211,77 @@ class Project
     end
   end
 
+  # Collect risk records (ADR-215): each first-level subfolder of risks/ is a
+  # risk registry; a registry's overview.md is its preface, not a record. Files
+  # directly under risks/ belong to no registry and are not collected.
+  def parse_risks
+    path = @configuration.project_root_directory
+    risks_root = "#{path}/risks"
+    Dir.glob("#{risks_root}/*/**/*.md").each do |f|
+      if File.basename(f).downcase == 'overview.md'
+        register_risk_preface(f, risks_root)
+        next
+      end
+
+      doc = DocFabric.create_risk_record(f)
+      rel_dir = File.dirname(f.sub("#{risks_root}/", ''))
+      doc.registry = rel_dir.split('/').first
+      doc.html_rel_path = "#{rel_dir}/#{doc.id}.html"
+      @project_data.risk_records.append(doc)
+      add_to_risk_registry(doc)
+    end
+    BaseDocument.show_risks_link = risk_registry_names.any?
+    ConsoleReporter.count('parsing risk records', @project_data.risk_records.length)
+    report_duplicate_risk_ids
+  end
+
+  # The registry names in file-system (parse) order: every first-level risks/
+  # folder holding records or a preface. The set that earns the top-menu Risks
+  # button (ADR-219) and a registry page (ADR-216).
+  def risk_registry_names
+    (@project_data.risk_registries.map { |g| g.keys.first } +
+     @project_data.risk_registry_prefaces.keys).uniq
+  end
+
+  # A registry's own overview.md is its preface (ADR-216), parsed like a record
+  # for rendering but never collected. An overview.md nested deeper inside a
+  # registry is neither a record nor a preface and is skipped entirely.
+  def register_risk_preface(file, risks_root)
+    rel_dir = File.dirname(file.sub("#{risks_root}/", ''))
+    return unless rel_dir.index('/').nil?
+
+    doc = DocFabric.create_risk_record(file)
+    doc.registry = rel_dir
+    doc.output_rel_path = "risks/#{rel_dir}/overview.html"
+    @project_data.risk_registry_prefaces[rel_dir] = doc
+  end
+
+  # Add a risk record to its registry, keyed on the first-level folder under
+  # risks/. Registries are single-key hashes appended in folder-encounter order,
+  # mirroring add_to_decision_group.
+  def add_to_risk_registry(doc)
+    registry = @project_data.risk_registries.find { |g| g.key?(doc.registry) }
+    if registry.nil?
+      @project_data.risk_registries.append({ doc.registry => [doc] })
+    else
+      registry[doc.registry].append(doc)
+    end
+  end
+
+  # Two risk records sharing one id would collide in the project-wide link
+  # space; each registry is expected to use its own letter prefix (ADR-215).
+  # Reported as a non-failing warning, like broken links.
+  def report_duplicate_risk_ids
+    duplicates = @project_data.risk_records.group_by(&:id).select { |_id, records| records.length > 1 }
+    return if duplicates.empty?
+
+    ConsoleReporter.warn('duplicated risk ids', duplicates.length)
+    duplicates.each do |id, records|
+      files = records.map { |r| r.path.sub("#{@configuration.project_root_directory}/", '') }.join(', ')
+      puts ConsoleReporter.warn_detail("  #{id}: #{files}")
+    end
+  end
+
   def parse_test_run(test_run)
     path = @configuration.project_root_directory
     Dir.glob("#{path}/tests/runs/#{test_run}/**/*.md").each do |f|
@@ -366,6 +339,22 @@ class Project
     ConsoleReporter.count('decision links', number_of_links)
   end
 
+  # A risk record's Affected Documents uplinks resolve exactly as a decision
+  # record's (ADR-218): the specification paragraph gains the record among its
+  # downlinks and a dangling Req-ID lands in the record's wrong_links_hash.
+  def link_all_risks
+    number_of_links = 0
+    @project_data.risk_records.each do |r|
+      @project_data.specifications.each do |s|
+        next unless r.up_link_docs.key?(s.id.to_s)
+
+        DocLinker.link_decision_to_spec(r, s)
+        number_of_links += 1
+      end
+    end
+    ConsoleReporter.count('risk links', number_of_links)
+  end
+
   def link_all_source_files
     return unless DocLinker.link_all_source_files(@project_data)
 
@@ -510,16 +499,6 @@ class Project
     doc.to_html("#{path}/build/decisions/")
   end
 
-  def render_critical_chain_page
-    return if @project_data.decisions.empty?
-
-    path = @configuration.project_root_directory
-    FileUtils.mkdir_p("#{path}/build/decisions")
-
-    doc = DocFabric.create_critical_chain_page(@project)
-    doc.to_html("#{path}/build/decisions/")
-  end
-
   def render_all_decisions
     return if @project_data.decisions.empty?
 
@@ -535,6 +514,66 @@ class Project
     end
   end
 
+  # Each registry renders to build/risks/<registry>/overview.html (ADR-216):
+  # the rendered preface first, then the register table of the registry's
+  # records, with the columns configured under the risks: root of project.yml
+  # (implicit columns plus Status when unconfigured). A registry holding only
+  # an overview.md still renders, with an empty table. Runs after
+  # render_all_risk_records so every record carries its rendering paths.
+  def render_risk_registry_pages
+    registry_names = risk_registry_names
+    return if registry_names.empty?
+
+    path = @configuration.project_root_directory
+    registry_names.each do |name|
+      records = @project_data.risk_registries.find { |g| g.key?(name) }&.fetch(name) || []
+      preface = @project_data.risk_registry_prefaces[name]
+      if preface
+        preface.root_prefix = '../../'
+        preface.specifications_path = "./#{preface.root_prefix}specifications/"
+      end
+      doc = DocFabric.create_risk_registry_page(name, records, preface, @configuration.get_risk_columns(name),
+                                                @configuration.get_risk_rpn_groups(name))
+      out_dir = "#{path}/build/risks/#{name}"
+      FileUtils.mkdir_p(out_dir)
+      doc.to_html("#{out_dir}/")
+    end
+  end
+
+  # The all-registries summary page (ADR-219): build/risks/overview.html, one
+  # row per registry with the total, open, and leading-group RPN aggregates.
+  # Rendered whenever the project has at least one registry — the same
+  # condition that emits the top-menu Risks button.
+  def render_risks_overview
+    registry_names = risk_registry_names
+    return if registry_names.empty?
+
+    registries = registry_names.map do |name|
+      [name, @project_data.risk_registries.find { |g| g.key?(name) }&.fetch(name) || []]
+    end
+    path = @configuration.project_root_directory
+    FileUtils.mkdir_p("#{path}/build/risks")
+    doc = DocFabric.create_risks_overview(registries, @configuration, @project_data.risk_registry_prefaces)
+    doc.to_html("#{path}/build/risks/")
+  end
+
+  # Each risk record renders to its own page under build/risks/<registry>/,
+  # with the navigation pane, exactly as decision records do (ADR-215).
+  def render_all_risk_records
+    return if @project_data.risk_records.empty?
+
+    build_risks_root = "#{@configuration.project_root_directory}/build/risks"
+    @project_data.risk_records.each do |doc|
+      out_dir_rel = File.dirname(doc.html_rel_path)
+      out_dir = "#{build_risks_root}/#{out_dir_rel}"
+      FileUtils.mkdir_p(out_dir)
+      depth = 1 + 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

@@ -1,11 +1,6 @@
 require 'yaml'
-require 'date'
 
 class ProjectConfiguration
-  DEFAULT_WIP_LIMIT = 2
-  DEFAULT_BUFFER_RATIO = 0.5
-  DEFAULT_HOURS_PER_DAY = 8
-
   attr_accessor :project_root_directory, :parameters
 
   def initialize(path)
@@ -34,76 +29,27 @@ class ProjectConfiguration
     []
   end
 
-  def get_wip_limit
-    return DEFAULT_WIP_LIMIT unless @parameters.is_a?(Hash)
-
-    planning = @parameters['planning']
-    return DEFAULT_WIP_LIMIT unless planning.is_a?(Hash)
-
-    value = planning['wip_limit']
-    return DEFAULT_WIP_LIMIT unless value.is_a?(Integer) && value.positive?
+  # The ordered register-column list for a risk registry folder (ADR-216),
+  # read from the risks: root — a list of { folder:, columns: } entries.
+  # nil when the registry carries no configuration; such a registry renders
+  # the implicit columns plus Status only.
+  def get_risk_columns(folder)
+    entry = risk_entry(folder)
+    return nil unless entry.is_a?(Hash) && entry['columns'].is_a?(Array)
 
-    value
+    entry['columns'].map(&:to_s)
   end
 
-  # The CCPM project-buffer ratio (ADR-195): a fraction in (0, 1] cutting the
-  # aggregated chain safety. Absent or out-of-range falls back to the 0.5 default.
-  def get_buffer_ratio
-    return DEFAULT_BUFFER_RATIO unless @parameters.is_a?(Hash)
+  # The named RPN groups of a risk registry folder (ADR-217), from the rpn:
+  # list of its risks: entry, in configured order:
+  # [{ name:, inputs: [..], acceptable:, unacceptable: }, ...]. Groups without
+  # a name or a non-empty inputs list are dropped; a threshold bound that is
+  # absent or not numeric is nil. Empty when the registry declares no groups.
+  def get_risk_rpn_groups(folder)
+    entry = risk_entry(folder)
+    return [] unless entry.is_a?(Hash) && entry['rpn'].is_a?(Array)
 
-    planning = @parameters['planning']
-    return DEFAULT_BUFFER_RATIO unless planning.is_a?(Hash)
-
-    value = planning['buffer_ratio']
-    return DEFAULT_BUFFER_RATIO unless value.is_a?(Numeric) && value.positive? && value <= 1
-
-    value
-  end
-
-  # The calendar anchor for working day 1 (ADR-205), a Date parsed from a
-  # DD-MM-YYYY planning.start_date. Absent or unparseable falls back to today,
-  # so an unconfigured project still renders (a moving anchor).
-  def get_start_date
-    date = parse_planning_date(planning_value('start_date'))
-    date || Date.today
-  end
-
-  # Per-group planning start dates (ADR-211): a map from a decision group's
-  # first-level folder name (under decisions/) to its start Date, read from
-  # planning.groups as DD-MM-YYYY entries. Non-string or unparseable values are
-  # dropped; empty when unset. A group absent from the map sequences after the
-  # previous group rather than carrying a declared start.
-  def get_group_start_dates
-    value = planning_value('groups')
-    return {} unless value.is_a?(Hash)
-
-    value.each_with_object({}) do |(name, raw), acc|
-      date = parse_planning_date(raw)
-      acc[name.to_s] = date if date
-    end
-  end
-
-  # The non-working holiday dates (ADR-205) from planning.holidays, each a
-  # DD-MM-YYYY entry; unparseable entries are dropped. Empty when unset.
-  def get_holidays
-    value = planning_value('holidays')
-    return [] unless value.is_a?(Array)
-
-    value.filter_map { |entry| parse_planning_date(entry) }
-  end
-
-  # Working hours per day (ADR-196): converts logged effort hours into the
-  # working-day unit the estimates use. Absent or non-positive falls back to 8.
-  def get_hours_per_day
-    return DEFAULT_HOURS_PER_DAY unless @parameters.is_a?(Hash)
-
-    planning = @parameters['planning']
-    return DEFAULT_HOURS_PER_DAY unless planning.is_a?(Hash)
-
-    value = planning['hours_per_day']
-    return DEFAULT_HOURS_PER_DAY unless value.is_a?(Numeric) && value.positive?
-
-    value
+    entry['rpn'].filter_map { |raw| risk_rpn_group(raw) }
   end
 
   def is_spec_db_shall_be_created
@@ -115,25 +61,30 @@ class ProjectConfiguration
     false
   end
 
-  # A value under the planning: key, or nil when planning is absent.
-  def planning_value(key)
+  # The risks: entry configuring a registry folder, or nil when absent.
+  def risk_entry(folder)
     return nil unless @parameters.is_a?(Hash)
 
-    planning = @parameters['planning']
-    planning.is_a?(Hash) ? planning[key] : nil
+    entries = @parameters['risks']
+    return nil unless entries.is_a?(Array)
+
+    entries.find { |e| e.is_a?(Hash) && e['folder'].to_s == folder }
   end
 
-  # Parse a planning date that may already be a Date (YAML ISO form) or a
-  # DD-MM-YYYY string; nil when neither.
-  def parse_planning_date(value)
-    return value if value.is_a?(Date)
-    return nil unless value.is_a?(String)
+  def risk_rpn_group(raw)
+    return nil unless raw.is_a?(Hash)
 
-    match = /\A(\d{2})-(\d{2})-(\d{4})\z/.match(value.strip)
-    return nil unless match
+    name = raw['name'].to_s
+    inputs = raw['inputs']
+    return nil if name.empty? || !inputs.is_a?(Array) || inputs.empty?
+
+    thresholds = raw['thresholds'].is_a?(Hash) ? raw['thresholds'] : {}
+    { name: name, inputs: inputs.map(&:to_s),
+      acceptable: numeric_threshold(thresholds['acceptable']),
+      unacceptable: numeric_threshold(thresholds['unacceptable']) }
+  end
 
-    Date.new(match[3].to_i, match[2].to_i, match[1].to_i)
-  rescue ArgumentError
-    nil
+  def numeric_threshold(value)
+    value.is_a?(Numeric) ? value : nil
   end
 end