Almirah 0.4.2 → 0.4.3

data/lib/almirah/doc_types/critical_chain_page.rb

@@ -0,0 +1,218 @@
+# frozen_string_literal: true
+
+require 'date'
+require 'json'
+require_relative 'base_document'
+require_relative 'decision_grouping'
+require_relative 'planning_dates'
+require_relative '../html_safe'
+require_relative '../project/critical_chain'
+require_relative '../project/fever_chart'
+require_relative '../project/working_calendar'
+
+# The dedicated Critical Chain & Project Buffer page (ENH-202): one block per
+# decision group, each showing the ordered critical chain rows, the project
+# buffer, and the projected duration; a group with no estimates is marked
+# unestimated. The chain and buffer are ADR-195's CriticalChain, reused
+# unchanged -- this page only relocates the rendering off the overview.
+class CriticalChainPage < BaseDocument
+  include HtmlSafe
+  include DecisionGrouping
+  include PlanningDates
+
+  # Recent Fridays sampled for the fever-chart trail (ADR-196), matching the
+  # velocity chart's window.
+  FEVER_TRAIL_WEEKS = 6
+
+  attr_accessor :project
+
+  def initialize(project)
+    super()
+    @project = project
+    @title = 'Critical Chain & Project Buffer'
+    @id = 'critical-chain'
+  end
+
+  def to_console
+    puts "\e[36mCritical Chain: #{@id}\e[0m"
+  end
+
+  def needs_chartjs?
+    true
+  end
+
+  def to_html(output_file_path)
+    html_rows = ['', "<h1>#{@title}</h1>\n", render_critical_chain]
+    save_html_to_file(html_rows, nil, output_file_path)
+  end
+
+  private
+
+  def render_critical_chain
+    ratio = @project.configuration.get_buffer_ratio
+    hours_per_day = @project.configuration.get_hours_per_day
+    lookup = record_lookup
+    blocks = grouped_work_items.each_with_index.map do |(name, items), index|
+      critical_chain_block(name, items, ratio, lookup, hours_per_day, index)
+    end
+    blocks << %(\t<p class="cc_unestimated">No decision records to plan.</p>\n) if blocks.empty?
+    %(<div class="critical_chain">\n#{blocks.join}</div>\n)
+  end
+
+  # The calendar a group's projected completion date is measured on (ADR-211):
+  # one anchored at the group's declared planning.groups start date, or the
+  # shared project-anchored calendar when the group declares none. Memoised per
+  # group name so each group reuses one calendar.
+  def group_calendar(name)
+    @group_calendars ||= {}
+    @group_calendars[name] ||= begin
+      start = @project.configuration.get_group_start_dates[name]
+      start ? WorkingCalendar.new(anchor: start, holidays: @project.configuration.get_holidays) : working_calendar
+    end
+  end
+
+  # An upcased-record-id => Decision map, so a chain row can reach its owning
+  # record's effort log (ADR-196).
+  def record_lookup
+    @project.project_data.decisions.to_h { |doc| [doc.id.to_s.upcase, doc] }
+  end
+
+  # The shared working calendar (ADR-205) projecting the working-day projected
+  # duration onto a real completion date.
+  def working_calendar
+    @working_calendar ||= WorkingCalendar.new(anchor: @project.configuration.get_start_date,
+                                              holidays: @project.configuration.get_holidays)
+  end
+
+  def critical_chain_block(name, items, ratio, lookup, hours_per_day, index) # rubocop:disable Metrics/ParameterLists
+    plan = CriticalChain.new(items, buffer_ratio: ratio)
+    header = %(\t<div class="cc_group">\n\t\t<h3>#{escape_text(name)}</h3>\n)
+    body = if plan.estimated?
+             cc_group_body(plan, lookup, hours_per_day, index, group_calendar(name))
+           else
+             %(\t\t<p class="cc_unestimated">No estimates — plan not sized.</p>\n)
+           end
+    "#{header}#{body}\t</div>\n"
+  end
+
+  # The estimated group's plan (chain table + buffer + projected duration) on the
+  # left and its buffer-consumption fever chart on the right, side by side
+  # (ADR-196). The chart is omitted when no chain row carries a positive estimate.
+  def cc_group_body(plan, lookup, hours_per_day, index, calendar)
+    fever = FeverChart.new(plan, lookup, hours_per_day: hours_per_day)
+    left = %(\t\t<div class="cc_plan">\n#{cc_chain_html(plan, fever, calendar)}\t\t</div>\n)
+    right = fever.plottable? ? %(\t\t<div class="cc_fever">\n#{fever_chart_html(fever, index)}\t\t</div>\n) : ''
+    %(\t\t<div class="cc_group_body">\n#{left}#{right}\t\t</div>\n)
+  end
+
+  def cc_chain_html(plan, fever, calendar)
+    lines = [%(\t\t<table class="cc_chain">\n),
+             "\t\t\t<thead><th>Record</th><th>Item</th><th>Owner</th><th>Duration</th></thead>\n"]
+    plan.chain.each { |wi| lines << cc_chain_row(wi) }
+    lines << "\t\t</table>\n"
+    projected = format_days(plan.projected_duration)
+    finish = calendar.date_for(plan.projected_duration)
+    lines << %(\t\t<p class="cc_buffer">Project buffer: #{plan.buffer} working days</p>\n)
+    lines << cc_consumed_html(plan, fever)
+    lines << %(\t\t<p class="cc_projected">Projected duration: #{projected} working days</p>\n)
+    lines << %(\t\t<p class="cc_finish">Projected completion: #{finish.strftime('%d-%m-%Y')}</p>\n)
+    lines.join
+  end
+
+  # The live buffer-health line shown under the buffer figure: how much of the
+  # project buffer the chain's overruns have eaten so far, as a percentage and as
+  # days of the baseline buffer. The percentage and day count both come from the
+  # fever chart, so the figure and the chart's live point always agree, and the
+  # "of N baseline days" makes explicit that the denominator is the baseline
+  # buffer -- not the (remaining-work) "Project buffer" figure above it. Empty
+  # when the plan carries no buffer to consume (no positive-estimate chain row, or
+  # zero baseline buffer).
+  def cc_consumed_html(plan, fever)
+    return '' unless fever.plottable? && plan.baseline_buffer.positive?
+
+    today = Date.today
+    consumed_pct = fever.live_point(today).last.round
+    consumed_days = format_days(fever.consumed_days(today).round(1))
+    baseline = plan.baseline_buffer
+    unit = baseline == 1 ? 'day' : 'days'
+    detail = "#{consumed_days} of #{baseline} baseline #{unit}"
+    %(\t\t<p class="cc_consumed">Buffer consumed: #{consumed_pct}% (#{detail})</p>\n)
+  end
+
+  def cc_chain_row(work_item)
+    cells = [work_item.record_id.upcase, work_item.activity, work_item.owner, format_days(work_item.focused_estimate)]
+    "\t\t\t<tr>#{cells.map { |c| "<td>#{escape_text(c.to_s)}</td>" }.join}</tr>\n"
+  end
+
+  # A working-day count without a trailing ".0" when it is whole.
+  def format_days(value)
+    value == value.to_i ? value.to_i.to_s : value.to_s
+  end
+
+  # The fever chart: the effort-only historical trail over recent Fridays plus the
+  # live point (which credits Done rows), drawn over the green/yellow/red zones.
+  def fever_chart_html(fever, index)
+    today = Date.today
+    fridays = recent_fridays(today, FEVER_TRAIL_WEEKS)
+    dates = fridays + [today]
+    points = fever.trail(fridays) + [fever.live_point(today)]
+    coords = points.zip(dates).map do |(completion, consumption), date|
+      { x: completion.round(2), y: consumption.round(2), d: date.strftime('%b %-d') }
+    end
+    radii = Array.new(coords.length - 1, 3) + [6]
+    colors = points.map { |completion, consumption| zone_color(completion, consumption) }
+    fever_canvas_script("fever_chart_#{index}", coords, radii, colors)
+  end
+
+  def fever_canvas_script(canvas_id, coords, radii, colors)
+    <<~HTML
+      \t\t\t<canvas id="#{canvas_id}" class="fever_canvas"></canvas>
+      \t\t\t<script>
+      \t\t\t#{fever_zone_plugin_js}
+      \t\t\tnew Chart(document.getElementById('#{canvas_id}'), {
+      \t\t\t\ttype: 'scatter',
+      \t\t\t\tdata: { datasets: [{ label: 'Buffer health', data: #{coords.to_json}, showLine: true,
+      \t\t\t\t\tborderColor: 'rgba(80,80,80,0.7)', pointRadius: #{radii.to_json},
+      \t\t\t\t\tpointBackgroundColor: #{colors.to_json}, pointBorderColor: '#333' }] },
+      \t\t\t\toptions: { responsive: true, maintainAspectRatio: false, plugins: { legend: { display: false },
+      \t\t\t\t\ttooltip: { callbacks: { label: (ctx) => ctx.raw.d + ': (' + ctx.parsed.x + ', ' + ctx.parsed.y + ')' } } },
+      \t\t\t\t\tscales: { x: { title: { display: true, text: 'Chain completion %' }, min: 0, max: 100 },
+      \t\t\t\t\t\ty: { title: { display: true, text: 'Buffer consumption %' }, min: 0, suggestedMax: 100 } } },
+      \t\t\t\tplugins: [window.feverZonesPlugin]
+      \t\t\t});
+      \t\t\t</script>
+    HTML
+  end
+
+  # The conventional CCPM zone for a point: green below the lower one-third
+  # diagonal, red above the upper, yellow between (ADR-196).
+  def zone_color(completion, consumption)
+    lower = (2.0 / 3.0) * completion
+    upper = (100.0 / 3.0) + (2.0 / 3.0) * completion
+    return '#2e9e2e' if consumption <= lower
+    return '#e0a200' if consumption <= upper
+
+    '#d33'
+  end
+
+  # A page-global Chart.js plugin (declared once, idempotently) that paints the
+  # three fever zones behind every fever chart on the page.
+  def fever_zone_plugin_js
+    <<~JS.strip
+      window.feverZonesPlugin = window.feverZonesPlugin || { id: 'feverZones', beforeDraw(chart) {
+        const a = chart.chartArea; if (!a) return; const x = chart.scales.x, y = chart.scales.y;
+        const px = v => x.getPixelForValue(v), py = v => y.getPixelForValue(v);
+        const lower = c => (2/3)*c, upper = c => 100/3 + (2/3)*c, ctx = chart.ctx;
+        ctx.save();
+        ctx.fillStyle = 'rgba(224,162,0,0.10)'; ctx.fillRect(a.left, a.top, a.width, a.height);
+        ctx.fillStyle = 'rgba(46,158,46,0.12)'; ctx.beginPath();
+        ctx.moveTo(px(0), py(0)); ctx.lineTo(px(100), py(lower(100)));
+        ctx.lineTo(px(100), py(y.min)); ctx.lineTo(px(0), py(y.min)); ctx.closePath(); ctx.fill();
+        ctx.fillStyle = 'rgba(221,51,51,0.12)'; ctx.beginPath();
+        ctx.moveTo(px(0), py(upper(0))); ctx.lineTo(px(100), py(100));
+        ctx.lineTo(px(100), py(y.max)); ctx.lineTo(px(0), py(y.max)); ctx.closePath(); ctx.fill();
+        ctx.restore();
+      } };
+    JS
+  end
+end

data/lib/almirah/doc_types/decision.rb

@@ -4,10 +4,12 @@ require 'date'
 require_relative 'persistent_document'
 require_relative '../doc_items/heading'
 require_relative '../doc_items/markdown_table'
+require_relative '../doc_items/scope_table'
 
-class Decision < PersistentDocument # rubocop:disable Style/Documentation,Metrics/ClassLength
+class Decision < PersistentDocument
   attr_accessor :path, :sequence_number, :record_type, :html_rel_path, :root_prefix, :current_status,
-                :start_date, :target_date, :target_release_version, :specifications_path, :wrong_links_hash
+                :start_date, :target_date, :target_release_version, :specifications_path, :wrong_links_hash,
+                :owners, :scope_table
 
   def initialize(file_path)
     super
@@ -19,6 +21,7 @@ class Decision < PersistentDocument # rubocop:disable Style/Documentation,Metric
     @target_date = nil
     @target_release_version = nil
     @wrong_links_hash = {}
+    @owners = []
   end
 
   def to_console
@@ -64,7 +67,73 @@ class Decision < PersistentDocument # rubocop:disable Style/Documentation,Metric
     )
   end
 
-  def effective_status_on(date) # rubocop:disable Metrics/MethodLength,Metrics/AbcSize,Metrics/CyclomaticComplexity,Metrics/PerceivedComplexity
+  # The distinct, first-seen-ordered list of non-empty Owner cells in the Scope
+  # table. Empty when there is no Scope table, no Owner column, or no owner values.
+  # The Owner column is located by header text, not position.
+  def extract_owners
+    @owners = []
+    table = find_section_table('Scope')
+    return if table.nil?
+
+    owner_idx = column_index(table, 'Owner')
+    return if owner_idx.nil?
+
+    table.cells.each do |row|
+      owner = row[owner_idx].to_s.strip
+      @owners << owner unless owner.empty? || @owners.include?(owner)
+    end
+  end
+
+  # The parsed Scope ScopeTable (ADR-194), or nil when the record has no Scope
+  # section. Memoised so the work-item network and the readers share one table.
+  def extract_scope_table
+    table = find_section_table('Scope')
+    @scope_table = table.is_a?(ScopeTable) ? table : nil
+  end
+
+  # The Scope rows as WorkItem nodes (ADR-194); empty when there is no ScopeTable.
+  def scope_work_items
+    @scope_table ? @scope_table.work_items : []
+  end
+
+  # A record declares prerequisites when any of its rows carries a Depends On
+  # reference; the overview Kit column is empty otherwise.
+  def declared_dependencies?
+    scope_work_items.any? { |wi| wi.depends_on_refs.any? }
+  end
+
+  # Kitted when every one of its work items is (a record with no rows is kitted).
+  def fully_kitted?
+    scope_work_items.all?(&:fully_kitted?)
+  end
+
+  # A started row blocked by an unsatisfied cross-record predecessor — the
+  # overview emphasises such a record, matching the console warning.
+  def kit_started_violation?
+    scope_work_items.any?(&:cross_record_violation?)
+  end
+
+  # One entry per Scope row whose row Status is In-Progress, yielding that row's
+  # owner. Rows without an owner, or not In-Progress, contribute nothing. The
+  # per-row Status is read directly and is independent of the record's lifecycle
+  # status. Owner and Status columns are located by header text, not position.
+  def in_progress_owner_tally
+    table = find_section_table('Scope')
+    return [] if table.nil?
+
+    owner_idx = column_index(table, 'Owner')
+    status_idx = column_index(table, 'Status')
+    return [] if owner_idx.nil? || status_idx.nil?
+
+    table.cells.filter_map do |row|
+      owner = row[owner_idx].to_s.strip
+      next if owner.empty?
+
+      owner if row[status_idx].to_s.strip == 'In-Progress'
+    end
+  end
+
+  def effective_status_on(date)
     table = find_section_table('Status')
     return nil if table.nil?
 
@@ -89,9 +158,46 @@ class Decision < PersistentDocument # rubocop:disable Style/Documentation,Metric
     status.empty? ? nil : status
   end
 
+  # Total logged effort in hours across the # Effort table (ADR-196); 0 when the
+  # record has no Effort section. Undated and unparseable entries still count
+  # toward the record total.
+  def actual_hours
+    effort_entries.sum { |e| e[:hours] }
+  end
+
+  # Logged hours dated on or before `date` (ADR-196). Undated entries are
+  # excluded since they cannot be placed on the timeline.
+  def actual_hours_on(date)
+    effort_entries.sum { |e| e[:date] && e[:date] <= date ? e[:hours] : 0.0 }
+  end
+
+  # Logged hours dated on or before `date` for the Scope row whose Item matches
+  # `item` (case-insensitive) — the per-chain-row actual the fever chart credits
+  # (ADR-196). Entries with no Item credit no row and are excluded here.
+  def row_actual_hours_on(item, date)
+    key = item.to_s.strip.downcase
+    return 0.0 if key.empty?
+
+    effort_entries.sum do |e|
+      e[:item] == key && e[:date] && e[:date] <= date ? e[:hours] : 0.0
+    end
+  end
+
+  # The [earliest, latest] dated # Effort entry crediting the Scope row whose Item
+  # matches `item` (case-insensitive) — the real logged span the Gantt's tracking
+  # lane draws (ADR-213). nil when the row has no dated effort. Undated entries are
+  # excluded since they cannot be placed on the timeline.
+  def effort_date_range(item)
+    key = item.to_s.strip.downcase
+    return nil if key.empty?
+
+    dates = effort_entries.filter_map { |e| e[:date] if e[:item] == key }
+    dates.empty? ? nil : dates.minmax
+  end
+
   private
 
-  def lookup_cell(section_name:, key_column:, value_column:, key:) # rubocop:disable Metrics/AbcSize
+  def lookup_cell(section_name:, key_column:, value_column:, key:)
     table = find_section_table(section_name)
     return nil if table.nil?
 
@@ -106,7 +212,7 @@ class Decision < PersistentDocument # rubocop:disable Style/Documentation,Metric
     cell.empty? ? nil : cell
   end
 
-  def find_section_table(section_name) # rubocop:disable Metrics/MethodLength,Metrics/CyclomaticComplexity,Metrics/PerceivedComplexity
+  def find_section_table(section_name)
     in_section = false
     section_level = nil
     @items.each do |item|
@@ -117,7 +223,7 @@ class Decision < PersistentDocument # rubocop:disable Style/Documentation,Metric
         elsif in_section && item.level <= section_level
           return nil
         end
-      elsif in_section && item.is_a?(MarkdownTable)
+      elsif in_section && (item.is_a?(MarkdownTable) || item.is_a?(ScopeTable))
         return item
       end
     end
@@ -131,7 +237,7 @@ class Decision < PersistentDocument # rubocop:disable Style/Documentation,Metric
     col_index = column_index(table, column_name)
     return [] if col_index.nil?
 
-    table.rows.filter_map { |row| parse_dd_mm_yyyy(row[col_index]) }
+    table.cells.filter_map { |row| parse_dd_mm_yyyy(row[col_index]) }
   end
 
   def column_index(table, column_name)
@@ -152,6 +258,45 @@ class Decision < PersistentDocument # rubocop:disable Style/Documentation,Metric
     nil
   end
 
+  # Parsed # Effort rows (ADR-196): [{ date:, item:, hours: }, ...]. The section
+  # is located by heading text and its columns addressed by header (Date / Item /
+  # Hours), like Status and Scope. Hours parse as non-negative floats (blank,
+  # negative, or unparseable -> 0); Item is downcased for case-insensitive row
+  # matching, or nil when absent. Memoised so the readers share one parse.
+  def effort_entries
+    return @effort_entries if defined?(@effort_entries)
+
+    @effort_entries = parse_effort_entries
+  end
+
+  def parse_effort_entries
+    table = find_section_table('Effort')
+    return [] if table.nil?
+
+    date_idx = column_index(table, 'Date')
+    hours_idx = column_index(table, 'Hours')
+    return [] if date_idx.nil? || hours_idx.nil?
+
+    item_idx = column_index(table, 'Item')
+    table.cells.map { |row| effort_entry(row, date_idx, item_idx, hours_idx) }
+  end
+
+  def effort_entry(row, date_idx, item_idx, hours_idx)
+    { date: parse_dd_mm_yyyy(row[date_idx]),
+      item: item_idx ? normalize_item(row[item_idx]) : nil,
+      hours: parse_hours(row[hours_idx]) }
+  end
+
+  def normalize_item(value)
+    text = value.to_s.strip.downcase
+    text.empty? ? nil : text
+  end
+
+  def parse_hours(value)
+    hours = Float(value.to_s.strip, exception: false)
+    hours.nil? || hours.negative? ? 0.0 : hours
+  end
+
   def assign_id_parts(stem)
     match = stem.match(/\A([A-Za-z]+)-(\d+)/)
     if match

data/lib/almirah/doc_types/decision_grouping.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+# Shared helper for the planning views: the non-empty decision groups (ADR-197)
+# paired with their Scope-row work items. Used by the overview's group-segmented
+# Gantt (ADR-201) and the dedicated Critical Chain page (ADR-195 / ENH-202).
+module DecisionGrouping
+  # [[group-name, [WorkItem, ...]], ...] in decision_groups (folder-encounter)
+  # order, only groups that have at least one work item.
+  def grouped_work_items
+    by_record = @project.project_data.work_items.values.group_by(&:record_id)
+    @project.project_data.decision_groups.filter_map do |group|
+      name = group.keys.first
+      items = group.values.first.flat_map { |doc| by_record[doc.id] || [] }
+      [name, items] unless items.empty?
+    end
+  end
+end