Almirah 0.4.2 → 0.4.3

data/lib/almirah/project.rb

@@ -2,6 +2,7 @@
 
 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'
@@ -12,7 +13,7 @@ require_relative 'project/project_data'
 require_relative 'console_reporter'
 require_relative 'relative_url'
 
-class Project # rubocop:disable Metrics/ClassLength,Style/Documentation
+class Project
   attr_accessor :index, :project, :configuration, :project_data
 
   def initialize(configuration)
@@ -39,7 +40,7 @@ class Project # rubocop:disable Metrics/ClassLength,Style/Documentation
     FileUtils.copy_entry(src_folder, dst_folder)
   end
 
-  def specifications_and_protocols # rubocop:disable Metrics/MethodLength,Metrics/AbcSize
+  def specifications_and_protocols
     parse_all_specifications
     parse_all_protocols
     parse_all_source_files
@@ -50,6 +51,7 @@ class Project # rubocop:disable Metrics/ClassLength,Style/Documentation
     link_all_decisions
     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)
@@ -58,14 +60,16 @@ class Project # rubocop:disable Metrics/ClassLength,Style/Documentation
     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_index
     create_search_data
     report_broken_links
+    report_kit_violations
     report_rendered
   end
 
-  def specifications_and_results(test_run) # rubocop:disable Metrics/MethodLength,Metrics/AbcSize
+  def specifications_and_results(test_run)
     parse_all_specifications
     parse_test_run test_run
     parse_all_source_files
@@ -76,6 +80,7 @@ class Project # rubocop:disable Metrics/ClassLength,Style/Documentation
     link_all_decisions
     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)
@@ -84,10 +89,12 @@ class Project # rubocop:disable Metrics/ClassLength,Style/Documentation
     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_index
     create_search_data
     report_broken_links
+    report_kit_violations
     report_rendered
   end
 
@@ -107,10 +114,115 @@ class Project # rubocop:disable Metrics/ClassLength,Style/Documentation
     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.
-  def build_link_registry # rubocop:disable Metrics/MethodLength,Metrics/AbcSize
+  def build_link_registry
     reg = @project_data.link_registry
     TextLine.link_registry = reg
     TextLine.reset_broken_links
@@ -177,11 +289,26 @@ class Project # rubocop:disable Metrics/ClassLength,Style/Documentation
       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)
+      add_to_decision_group(doc, rel_dir)
     end
     BaseDocument.show_decisions_link = @project_data.decisions.any?
     ConsoleReporter.count('parsing decisions', @project_data.decisions.length)
   end
 
+  # Add a decision record to its planning group, keyed on the first-level folder
+  # under decisions/ (a record directly under decisions/ has rel_dir '.', kept as
+  # its own '.' group rather than dropped). Groups are single-key hashes appended
+  # in folder-encounter order; the matching one is reused. See ADR-197.
+  def add_to_decision_group(doc, rel_dir)
+    group_name = rel_dir.split('/').first
+    group = @project_data.decision_groups.find { |g| g.key?(group_name) }
+    if group.nil?
+      @project_data.decision_groups.append({ group_name => [doc] })
+    else
+      group[group_name].append(doc)
+    end
+  end
+
   def parse_test_run(test_run)
     path = @configuration.project_root_directory
     Dir.glob("#{path}/tests/runs/#{test_run}/**/*.md").each do |f|
@@ -190,7 +317,7 @@ class Project # rubocop:disable Metrics/ClassLength,Style/Documentation
     end
   end
 
-  def link_all_specifications # rubocop:disable Metrics/MethodLength,Metrics/AbcSize
+  def link_all_specifications
     comb_list = @project_data.specifications.combination(2)
     comb_list.each do |c|
       link_two_specifications(c[0], c[1])
@@ -209,7 +336,7 @@ class Project # rubocop:disable Metrics/ClassLength,Style/Documentation
     ConsoleReporter.count('traceability matrices', @project_data.traceability_matrices.length)
   end
 
-  def link_all_protocols # rubocop:disable Metrics/MethodLength
+  def link_all_protocols
     @project_data.protocols.each do |p|
       @project_data.specifications.each do |s|
         if p.up_link_docs.key?(s.id.to_s)
@@ -250,7 +377,7 @@ class Project # rubocop:disable Metrics/ClassLength,Style/Documentation
     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
+  def check_wrong_specification_referenced
     available_specification_ids = {}
 
     @project_data.specifications.each do |s|
@@ -280,7 +407,7 @@ class Project # rubocop:disable Metrics/ClassLength,Style/Documentation
     end
   end
 
-  def link_two_specifications(doc_a, doc_b) # rubocop:disable Metrics/AbcSize,Metrics/CyclomaticComplexity,Metrics/MethodLength,Metrics/PerceivedComplexity
+  def link_two_specifications(doc_a, doc_b)
     if doc_b.up_link_docs.key?(doc_a.id.to_s)
       top_document = doc_a
       bottom_document = doc_b
@@ -383,7 +510,17 @@ class Project # rubocop:disable Metrics/ClassLength,Style/Documentation
     doc.to_html("#{path}/build/decisions/")
   end
 
-  def render_all_decisions # rubocop:disable Metrics/MethodLength,Metrics/AbcSize
+  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?
 
     build_decisions_root = "#{@configuration.project_root_directory}/build/decisions"

data/lib/almirah/project_configuration.rb

@@ -1,42 +1,139 @@
 require 'yaml'
+require 'date'
 
 class ProjectConfiguration
-    attr_accessor :project_root_directory, :parameters
+  DEFAULT_WIP_LIMIT = 2
+  DEFAULT_BUFFER_RATIO = 0.5
+  DEFAULT_HOURS_PER_DAY = 8
 
-    def initialize(path)
-        @project_root_directory = File.expand_path(path)
-        @parameters = {}
-        load_project_file
-    end
+  attr_accessor :project_root_directory, :parameters
 
-    def load_project_file
-            @parameters = YAML.load_file(@project_root_directory + '/project.yml')
-    rescue Psych::SyntaxError => e
-            puts "YAML syntax error: #{e.message}"
-    rescue Errno::ENOENT
-            puts 'Project file not found: project.yml'
-    end
+  def initialize(path)
+    @project_root_directory = File.expand_path(path)
+    @parameters = {}
+    load_project_file
+  end
 
-    def get_design_inputs
-        if (@parameters.key? 'specifications') and (@parameters['specifications'].key? 'input')
-            return @parameters['specifications']['input']
-        end
+  def load_project_file
+    @parameters = YAML.load_file(@project_root_directory + '/project.yml')
+  rescue Psych::SyntaxError => e
+    puts "YAML syntax error: #{e.message}"
+  rescue Errno::ENOENT
+    puts 'Project file not found: project.yml'
+  end
 
-        []
-    end
+  def get_design_inputs
+    return @parameters['specifications']['input'] if (@parameters.key? 'specifications') and (@parameters['specifications'].key? 'input')
+
+    []
+  end
+
+  def get_repositories
+    return @parameters['repositories'] if @parameters.key? 'repositories'
+
+    []
+  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?
+
+    value
+  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)
+
+    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
 
-    def get_repositories
-        return @parameters['repositories'] if @parameters.key? 'repositories'
+    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?
 
-    def is_spec_db_shall_be_created
-        if @parameters.key? 'output'
-            @parameters['output'].each do |p|
-               return true if p == 'specifications_db'
-            end
-        end
-        false
+    value
+  end
+
+  def is_spec_db_shall_be_created
+    if @parameters.key? 'output'
+      @parameters['output'].each do |p|
+        return true if p == 'specifications_db'
+      end
     end
+    false
+  end
+
+  # A value under the planning: key, or nil when planning is absent.
+  def planning_value(key)
+    return nil unless @parameters.is_a?(Hash)
+
+    planning = @parameters['planning']
+    planning.is_a?(Hash) ? planning[key] : nil
+  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)
+
+    match = /\A(\d{2})-(\d{2})-(\d{4})\z/.match(value.strip)
+    return nil unless match
+
+    Date.new(match[3].to_i, match[2].to_i, match[1].to_i)
+  rescue ArgumentError
+    nil
+  end
 end

data/lib/almirah/project_template.rb

@@ -2,7 +2,7 @@
 
 require 'fileutils'
 
-class ProjectTemplate # rubocop:disable Style/Documentation
+class ProjectTemplate
   attr_accessor :project_root
 
   def initialize(project_name)
@@ -324,11 +324,11 @@ class ProjectTemplate # rubocop:disable Style/Documentation
 
       # Scope
 
-      | Item | Status | Start Date | Target Date | Description |
-      |---|---|---|---|---|
-      | Requirements | To Do | | | |
-      | Code | To Do | | | |
-      | Tests | To Do | | | |
+      | # | Item | Owner | Depends On | Est (focused) | Est (safe) | Status | Start Date | Target Date | Description |
+      |---|---|---|---|---|---|---|---|---|---|
+      | 1 | Requirements | BA | | 2 | 3 | To Do | | | |
+      | 2 | Code | DEV | | 3 | 5 | To Do | | | |
+      | 3 | Tests | TEST | | 2 | 4 | To Do | | | |
 
       # Out of Scope
 

data/lib/almirah/project_utility.rb

@@ -2,7 +2,7 @@
 
 require 'fileutils'
 
-class ProjectUtility # rubocop:disable Style/Documentation
+class ProjectUtility
   attr_accessor :configuration
 
   def initialize(configuration)
@@ -19,7 +19,7 @@ class ProjectUtility # rubocop:disable Style/Documentation
 
   private
 
-  def combine(run_id) # rubocop:disable Metrics/AbcSize,Metrics/MethodLength
+  def combine(run_id)
     path = @configuration.project_root_directory
     dst_folder = "#{@configuration.project_root_directory}/build"
     FileUtils.mkdir_p(dst_folder)
@@ -29,9 +29,7 @@ class ProjectUtility # rubocop:disable Style/Documentation
     dst_f = File.open(dst_file, 'a')
 
     src_path = if run_id
-                 unless Dir.exist? "#{path}/tests/runs/#{run_id}"
-                   puts "\e[1m\e[31m Run #{run_id} folder does not exists"
-                 end
+                 puts "\e[1m\e[31m Run #{run_id} folder does not exists" unless Dir.exist? "#{path}/tests/runs/#{run_id}"
                  "#{path}/tests/runs/#{run_id}/**/*.md"
                else
                  "#{path}/tests/protocols/**/*.md"

data/lib/almirah/search/specifications_db.rb

@@ -12,7 +12,7 @@ class SpecificationsDb
     create_data
   end
 
-  def create_data # rubocop:disable Metrics/AbcSize,Metrics/MethodLength
+  def create_data
     @specifications.each do |sp|
       sp.items.each do |i|
         if (i.instance_of? Paragraph) or (i.instance_of? ControlledParagraph)
@@ -31,7 +31,7 @@ class SpecificationsDb
     end
   end
 
-  def add_markdown_list_item_to_db(data, item_for_reference, item_to_process) # rubocop:disable Metrics/AbcSize,Metrics/MethodLength
+  def add_markdown_list_item_to_db(data, item_for_reference, item_to_process)
     e = nil
     item_to_process.rows.each do |r|
       if r.is_a?(MarkdownList)

data/lib/almirah/source_file_parser.rb

@@ -2,7 +2,7 @@ require_relative 'doc_items/doc_item'
 require_relative 'doc_items/heading'
 require_relative 'doc_items/source_code_paragraph'
 
-class SourceFileParser # rubocop:disable Style/Documentation
+class SourceFileParser
   def self.parse(doc, file_lines)
     # restart section numbering for each new document
     Heading.reset_global_section_number
@@ -19,7 +19,7 @@ class SourceFileParser # rubocop:disable Style/Documentation
     doc.headings.append(item)
 
     # main loop
-    file_lines.each do |s| # rubocop:disable Metrics/BlockLength
+    file_lines.each do |s|
       res = %r{<REQ>(.*)</REQ>}.match(s) # Document Referece Item
       next unless res
 
@@ -36,7 +36,6 @@ class SourceFileParser # rubocop:disable Style/Documentation
         up_links = []
         tmp.each do |ul|
           lnk = ul[0]
-          #
           doc_id = /([a-zA-Z]+)-\d+/.match(lnk) # SRS
           up_links << lnk.upcase if doc_id
           # try to find the real end of text