predictability-engine 0.6.6

data/lib/predictability_engine/report/text_renderer.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module PredictabilityEngine
+  class Report
+    module TextRenderer
+      def self.render(report, fmt, color: false, layout: :standard, **)
+        config = Constants::FORMAT_CONFIG[fmt]
+        header = config[:h1].call(report.title)
+        if layout.to_sym == :landscape
+          return [header, '',
+                  render_landscape(report, fmt, color: color, **)].join("\n")
+        end
+
+        [header, SummaryVisualizer.render(report.items, fmt, color: color, percentiles: report.percentiles),
+         *Constants::CHART_CONFIG.map do |id, cfg|
+           render_section(report, id, cfg, fmt, color: color, **)
+         end].join("\n")
+      end
+
+      def self.render_landscape(report, fmt, color: false, **opts)
+        sum = SummaryVisualizer.render(report.items, fmt, color: color, percentiles: report.percentiles)
+        section_opts = opts.merge(color: color, table: true)
+        ch = Constants::CHART_CONFIG.map { |id, c| render_section(report, id, c, fmt, section_opts) }
+        br = fmt == :confluence ? ' \\\\ ' : '<br>'
+        bold = fmt == :confluence ? '*' : '**'
+        h_regex = fmt == :confluence ? /^h\d\.\s*(.*)$/ : /^#+\s*(.*)$/
+        clean_sum = sum.gsub(h_regex, "#{bold}\\1#{bold}").gsub("\n\n", br).gsub("\n", br)
+        clean_ch = ch.map { |c| c.gsub("\n", br) }
+
+        build_table(fmt, clean_sum, clean_ch)
+      end
+
+      def self.build_table(fmt, sum, charts)
+        row1 = "| #{sum} | #{charts[0]} | #{charts[1]} | #{charts[2]} |"
+        span = fmt == :confluence ? '^' : nil
+        row2 = "| #{span} | #{charts[3]} | #{charts[4]} | #{charts[5]} |"
+        md_hdr = "| | | | |\n| :--- | :--- | :--- | :--- |"
+        [(fmt == :markdown ? md_hdr : nil), row1, row2].compact.join("\n")
+      end
+
+      def self.render_section(report, chart_id, cfg, fmt, options = {})
+        title = section_title(cfg[:title], fmt, options[:table])
+        if fmt != :terminal && image_available?(report, chart_id)
+          [title, report.render_image_link(chart_id, fmt)].join("\n")
+        elsif %i[markdown confluence].include?(fmt) && MermaidVisualizer.respond_to?(chart_id)
+          render_mermaid(report, chart_id, fmt, title)
+        else
+          render_ascii(report, chart_id, Constants::FORMAT_CONFIG[fmt], options[:color], title,
+                       **options.except(:color, :table))
+        end
+      end
+
+      def self.section_title(title, fmt, table)
+        bold = fmt == :confluence ? '*' : '**'
+        table ? "#{bold}#{title}#{bold}" : Constants::FORMAT_CONFIG[fmt][:h2].call(title)
+      end
+
+      def self.image_available?(report, chart_id)
+        report.images_path && File.exist?(File.join(report.images_path, "#{chart_id}.png"))
+      end
+
+      def self.render_mermaid(report, chart_id, fmt, title)
+        wrap = fmt == :confluence ? ['{mermaid}', '{mermaid}'] : ['```mermaid', '```']
+        [title, wrap[0], MermaidVisualizer.send(chart_id, report.items, percentiles: report.percentiles),
+         wrap[1], render_legend(chart_id, report.percentiles)].compact.join("\n")
+      end
+
+      def self.render_ascii(report, chart_id, config, color, title, **opts) # rubocop:disable Metrics/ParameterLists
+        call_opts = opts.merge(percentiles: report.percentiles, color: color || false)
+        [title, config[:code].call(title, TerminalVisualizer.send(chart_id, report.items, **call_opts))].join("\n")
+      end
+
+      def self.render_legend(chart_id, pcts)
+        return nil unless chart_id == :forecasted_cfd_plot
+
+        "\n**Legend:** Arrivals (blue), Departures (green), Projections (various colors). " \
+          "Vertical lines for: #{pcts.join('%, ')}% confidence."
+      end
+
+      private_class_method :render_landscape, :build_table, :render_section, :section_title,
+                           :image_available?, :render_mermaid, :render_ascii, :render_legend
+    end
+  end
+end

data/lib/predictability_engine/report.rb

@@ -0,0 +1,328 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+require_relative 'report/constants'
+require_relative 'report/image_generator'
+require_relative 'report/text_renderer'
+
+module PredictabilityEngine
+  class Report # rubocop:disable Metrics/ClassLength
+    include Constants
+
+    PRIORITY_SORT = lambda do |values|
+      values.sort_by { |v| [Constants::PRIORITY_ORDER.index(v) || Constants::PRIORITY_ORDER.size, v] }
+    end
+
+    FACETS = [
+      { key: :priority, label: 'Priority', accessor: :priority, dirname: 'priorities',
+        sort: PRIORITY_SORT },
+      { key: :type, label: 'Type', accessor: :type, dirname: 'types',
+        sort: lambda(&:sort) }
+    ].freeze
+
+    attr_reader :items, :title, :percentiles, :images_path, :type, :priority
+
+    def initialize(items, title: 'Predictability Report', percentiles: PredictabilityEngine::DEFAULT_PERCENTILES,
+                   type: nil, priority: nil)
+      @type = type
+      @priority = priority
+      @items = filter_by_facets(items)
+      @title = title
+      @percentiles = percentiles
+      @images_path = nil
+    end
+
+    def self.generate_all(items)
+      reports = { all: new(items, title: 'Full Predictability Dashboard') }
+      FACETS.each do |facet|
+        values = facet_values(items, facet)
+        next unless values.size > 1
+
+        reports[facet[:key]] = values.to_h do |val|
+          [val, new(items, title: "Dashboard: #{val}", facet[:key] => val)]
+        end
+      end
+      reports
+    end
+
+    def self.facet_values(items, facet)
+      raw = items.map { |i| i.public_send(facet[:accessor]) || 'Unspecified' }.uniq
+      facet[:sort].call(raw)
+    end
+
+    def render(format, layout: nil, color: false, **extra_opts)
+      config = find_format_config(format)&.last
+      method_name = "render_#{find_format_config(format)&.first || format.to_sym}"
+      raise ArgumentError, "Unsupported format: #{format}" unless respond_to?(method_name, true)
+
+      opts = { layout: effective_layout(layout, config), color: color }.merge(extra_opts)
+      opts[:format] = config[:format] if config&.key?(:format)
+      opts[:landscape] = config[:landscape] if config&.key?(:landscape)
+      send(method_name, **opts)
+    end
+
+    def generate_chart_images(base_dir, **)
+      @images_path = ImageGenerator.generate(self, base_dir, **)
+    end
+
+    def render_html(layout: :landscape, sub_reports: nil, **)
+      charts = CHART_CONFIG.map do |id, cfg|
+        chart = VegaVisualizer.send(cfg[:vega] || id, @items,
+                                    title: nil,
+                                    percentiles: @percentiles)
+        { title: cfg[:title], chart: chart }
+      end
+      Visualizer.to_full_html(charts, @items, title: @title, layout: layout, percentiles: @percentiles,
+                                              sub_reports: sub_reports)
+    end
+
+    def with_report_temp_html(layout: :landscape)
+      temp_html = "tmp/report_#{object_id}.html"
+      FileUtils.mkdir_p('tmp')
+      File.write(temp_html, render_html(layout: layout))
+      yield temp_html
+    ensure
+      FileUtils.rm_f(temp_html) if temp_html
+    end
+
+    def playwright_bin
+      root = File.expand_path('../..', __dir__)
+      unless ENV['PLAYWRIGHT_BROWSERS_PATH']
+        require 'etc'
+        real_home = begin
+          Etc.getpwuid.dir
+        rescue StandardError
+          Dir.home
+        end
+        ENV['PLAYWRIGHT_BROWSERS_PATH'] = File.expand_path('.cache/ms-playwright', real_home)
+      end
+      File.exist?("#{root}/node_modules/.bin/playwright") ? "#{root}/node_modules/.bin/playwright" : 'npx playwright'
+    end
+
+    def playwright_chromium_launch_opts
+      exe = ENV.fetch('PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH', nil)
+      return {} unless exe
+
+      # System Chromium (e.g. Alpine apk) needs --no-sandbox in Docker containers.
+      { executablePath: exe, chromiumSandbox: false }
+    end
+
+    def pdf_viewport_size(format, landscape)
+      res = RESOLUTION_CONFIG[format.to_s.downcase]
+      if res
+        return landscape ? res : [res[1], res[0]]
+      end
+
+      sizes = { 'A4' => [794, 1123], 'A3' => [1123, 1587] }
+      w, h = sizes[format.to_s.upcase] || sizes[DEFAULT_SIZE.to_s.upcase]
+      landscape ? [h, w] : [w, h]
+    end
+
+    def render_image_link(chart_id, fmt)
+      rel_path = "images/#{chart_id}.png"
+      fmt == :confluence ? "!#{rel_path}!" : "![](#{rel_path})"
+    end
+
+    private
+
+    def filter_by_facets(items)
+      FACETS.reduce(items) do |acc, facet|
+        filter_val = instance_variable_get("@#{facet[:key]}")
+        next acc unless filter_val
+
+        acc.select { |i| (i.public_send(facet[:accessor]) || 'Unspecified') == filter_val }
+      end
+    end
+
+    def render_ppt_multi_slide
+      require 'powerpoint'
+      base_dir = "tmp/ppt_#{object_id}"
+      FileUtils.mkdir_p(base_dir)
+      generate_chart_images_or_warn(base_dir)
+
+      deck = Powerpoint::Presentation.new
+      deck.add_intro(@title, "Generated on #{PredictabilityEngine.format_datetime(Time.now)}")
+
+      metrics = SummaryVisualizer.metrics_terminal(@items, color: false, percentiles: @percentiles)
+      deck.add_textual_slide('Flow Metrics Summary', metrics.split("\n").map(&:strip).reject(&:empty?))
+
+      CHART_CONFIG.each_key do |id|
+        img = File.join(@images_path, "#{id}.png") if @images_path
+        deck.add_pictorial_slide(CHART_CONFIG[id][:title], img) if img && File.exist?(img)
+      end
+
+      ppt_file = File.join(base_dir, 'dashboard.pptx')
+      deck.save(ppt_file)
+      File.binread(ppt_file)
+    ensure
+      FileUtils.rm_rf(base_dir) if base_dir
+    end
+
+    def generate_chart_images_or_warn(base_dir, **)
+      generate_chart_images(base_dir, **)
+    rescue StandardError => e
+      PredictabilityEngine.warn_chart_failure(e, context: 'Slides will be text-only.')
+      @images_path = nil
+    end
+
+    def find_format_config(format)
+      fmt = format.to_sym
+      FORMAT_CONFIG.find { |k, v| k == fmt || v[:aliases]&.include?(fmt) }
+    end
+
+    def effective_layout(layout, config) = (layout || config&.dig(:layout) || :landscape).to_sym
+
+    %i[terminal markdown confluence].each do |f|
+      define_method("render_#{f}") { |**o| TextRenderer.render(self, f, **o) }
+    end
+
+    def render_raw_csv(**)
+      require_relative 'raw_data_exporter'
+      RawDataExporter.generate_csv(@items)
+    end
+
+    def render_xlsx(**)
+      require_relative 'excel_exporter'
+      Dir.mktmpdir('pe_xlsx_') do |dir|
+        generate_chart_images(dir, width: ExcelExporter::CAPTURE_WIDTH,
+                                   height: ExcelExporter::CAPTURE_HEIGHT,
+                                   scale: ExcelExporter::CHART_SCALE)
+        ExcelExporter.generate(@items, images_path: @images_path)
+      end
+    end
+
+    def render_landscape(layout: :landscape, **) = render_html(layout: layout, **)
+    def render_a3_landscape(**) = render_pdf(**)
+
+    def render_png(layout: :landscape, size: DEFAULT_SIZE, **)
+      res = RESOLUTION_CONFIG[size.to_s.downcase] || RESOLUTION_CONFIG[DEFAULT_SIZE]
+      with_report_temp_html(layout: layout) do |temp_html|
+        png_data = nil
+        with_playwright_page(temp_html, width: res[0], height: res[1]) do |page|
+          png_data = page.screenshot
+        end
+        png_data
+      end
+    end
+
+    def render_ppt(size: DEFAULT_SIZE, **_opts)
+      require 'powerpoint'
+      res = RESOLUTION_CONFIG[size.to_s.downcase] || RESOLUTION_CONFIG[DEFAULT_SIZE]
+      temp_img = "tmp/dashboard_#{object_id}.png"
+      ppt_file = "tmp/dashboard_#{object_id}.pptx"
+
+      with_report_temp_html(layout: :landscape) do |temp_html|
+        capture_screenshot(temp_html, temp_img, width: res[0], height: res[1])
+
+        deck = Powerpoint::Presentation.new
+        deck.add_pictorial_slide(@title, temp_img)
+        deck.save(ppt_file)
+        File.binread(ppt_file)
+      end
+    rescue StandardError => e
+      PredictabilityEngine.logger.warn do
+        "High-fidelity PPT generation failed: #{e.message}. Falling back to multi-slide."
+      end
+      render_ppt_multi_slide
+    ensure
+      FileUtils.rm_f(temp_img) if temp_img
+      FileUtils.rm_f(ppt_file) if ppt_file
+    end
+
+    def capture_screenshot(html_path, img_path, width: 1280, height: 720)
+      with_playwright_page(html_path, width: width, height: height) do |page|
+        page.screenshot(path: img_path, fullPage: true)
+      end
+    end
+
+    def render_pdf(layout: :landscape, high_fidelity: true, format: nil, size: DEFAULT_SIZE, landscape: true, **_opts) # rubocop:disable Metrics/ParameterLists
+      fmt = format || size
+      high_fidelity ? render_pdf_playwright(layout: layout, format: fmt, landscape: landscape) : render_pdf_prawn
+    rescue StandardError => e
+      PredictabilityEngine.logger.warn { "High-fidelity PDF generation failed: #{e.message}. Falling back to Prawn." }
+      render_pdf_prawn
+    end
+
+    def render_pdf_playwright(layout: :landscape, format: DEFAULT_SIZE, landscape: true)
+      with_report_temp_html(layout: layout) do |temp_html|
+        capture_pdf(temp_html, format, landscape)
+      end
+    end
+
+    def capture_pdf(html_path, format, landscape)
+      w, h = pdf_viewport_size(format, landscape)
+      pdf_data = nil
+      with_playwright_page(html_path, width: w, height: h) do |page|
+        pdf_opts = { printBackground: true,
+                     margin: { top: '0', right: '0', bottom: '0', left: '0' },
+                     width: "#{w}px", height: "#{h}px" }
+        pdf_data = page.pdf(**pdf_opts)
+      end
+      pdf_data
+    end
+
+    def with_playwright_page(html_path, width: 1280, height: 720)
+      require 'playwright'
+      Playwright.create(playwright_cli_executable_path: playwright_bin) do |p|
+        p.chromium.launch(**playwright_chromium_launch_opts) do |browser|
+          page = browser.new_page(viewport: { width: width, height: height })
+          route_vega_cdn(page)
+          page.goto("file://#{File.expand_path(html_path)}")
+          sleep 2 # wait for Vega to render
+          yield page
+        end
+      end
+    end
+
+    def route_vega_cdn(page)
+      js_dir = File.join(Gem.loaded_specs['vega'].gem_dir, 'vendor', 'assets', 'javascripts')
+      { '**/npm/vega@5**' => 'vega.js', '**/npm/vega-lite@5**' => 'vega-lite.js',
+        '**/npm/vega-embed@6**' => 'vega-embed.js' }.each do |pattern, filename|
+        content = File.binread(File.join(js_dir, filename)).force_encoding('UTF-8')
+        page.route(pattern, ->(route, _req) { route.fulfill(body: content, contentType: 'application/javascript') })
+      end
+    end
+
+    def render_pdf_prawn(**)
+      require 'prawn'
+      Prawn::Document.new(page_layout: :landscape, margin: 30) do |pdf|
+        Report.send(:setup_pdf_font_on_doc, pdf)
+        pdf.text @title, size: 20, style: :bold
+        pdf.move_down 15
+
+        pdf.define_grid(columns: 3, rows: 2, gutter: 15)
+
+        pdf.grid([0, 0], [1, 0]).bounding_box do
+          pdf.text 'Flow Metrics Summary', size: 14, style: :bold
+          pdf.move_down 10
+          pdf.text SummaryVisualizer.metrics_terminal(@items, color: false, percentiles: @percentiles), size: 8
+        end
+
+        charts = CHART_CONFIG.keys
+        [[0, 1], [0, 2], [1, 1], [1, 2]].each_with_index do |grid_pos, i|
+          id = charts[i]
+          next unless id
+
+          pdf.grid(*grid_pos).bounding_box do
+            pdf.text CHART_CONFIG[id][:title], size: 10, style: :bold
+            pdf.move_down 5
+            PdfVisualizer.draw_chart(pdf, id, @items, percentiles: @percentiles)
+          end
+        end
+      end.render
+    end
+
+    def self.setup_pdf_font_on_doc(pdf)
+      mono = find_font(Constants::FONT_PATHS)
+      bold = find_font(Constants::FONT_BOLD_PATHS)
+      return unless mono && bold
+
+      pdf.font_families.update('CustomMono' => { normal: mono, bold: bold })
+      pdf.font 'CustomMono'
+    end
+
+    def self.find_font(paths) = paths.find { |p| File.exist?(p) }
+
+    private_class_method :setup_pdf_font_on_doc, :find_font
+  end
+end

data/lib/predictability_engine/report_generator.rb

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+
+module PredictabilityEngine
+  # Logic for generating and writing reports.
+  module ReportGenerator # rubocop:disable Metrics/ModuleLength
+    def self.run_report(file, format, items: nil, reports: nil, **)
+      items   ||= PredictabilityEngine.load_items(file, **)
+      reports ||= Report.generate_all(items)
+
+      if facet_total(reports).zero? || format.to_sym == :terminal
+        generate_single_report(file, format, reports[:all], **)
+      else
+        generate_multi_reports(file, format, reports, **)
+      end
+    end
+
+    def self.facet_total(reports)
+      Report::FACETS.sum { |f| (reports[f[:key]] || {}).size }
+    end
+
+    def self.each_facet_entry(reports)
+      yield :all, reports[:all]
+      Report::FACETS.each do |facet|
+        (reports[facet[:key]] || {}).each { |value, report| yield [facet[:key], value], report }
+      end
+    end
+
+    def self.generate_single_report(file, format, report, **opts)
+      fmt = format.to_sym
+      generate_images_if_needed(file, fmt, report, **opts)
+      opts = opts.merge(sub_reports: export_links_for(:all)) if html_format?(fmt) && !opts[:sub_reports]
+
+      content = report.render(fmt, **opts)
+      if opts[:output] || fmt != :terminal
+        write_report(file, format, content, opts[:output], **opts)
+      else
+        content
+      end
+    end
+
+    def self.generate_multi_reports(file, format, reports, **opts)
+      fmt  = format.to_sym
+      msgs = []
+      each_facet_entry(reports) do |slot, report|
+        generate_images_if_needed(file, fmt, report, **opts)
+        links   = build_nav_links(fmt, reports, slot)
+        content = report.render(fmt, sub_reports: links, **opts)
+        msg     = write_report(file, format, content, opts[:output], slot: slot, **opts)
+        PredictabilityEngine.logger.info { msg }
+        msgs << msg
+      end
+      "#{msgs.size} reports generated"
+    end
+
+    def self.generate_images_if_needed(file, format, report, **)
+      return unless %i[markdown md confluence conf].include?(format)
+
+      dir = report_dir(file, **)
+      report.generate_chart_images(dir)
+    rescue StandardError => e
+      PredictabilityEngine.warn_chart_failure(e, context: 'Inline images will be omitted.')
+    end
+
+    def self.build_nav_links(format, reports, current_slot)
+      return unless html_format?(format)
+
+      links = [nav_entry(:all, current_slot, label: 'All')]
+      Report::FACETS.each do |facet|
+        values = (reports[facet[:key]] || {}).keys
+        next if values.empty?
+
+        links << { separator: true }
+        values.each { |value| links << nav_entry([facet[:key], value], current_slot, label: value) }
+      end
+      links + export_links_for(current_slot)
+    end
+
+    def self.html_format?(format)
+      %i[html landscape].include?(format)
+    end
+
+    def self.export_links_for(slot)
+      prefix = slot.is_a?(Array) ? '../' : ''
+      [{ label: 'CSV', url: "#{prefix}dashboard.csv", download: true },
+       { label: 'XLSX', url: "#{prefix}dashboard.xlsx", download: true }]
+    end
+
+    def self.nav_entry(slot, current_slot, label:)
+      { label: label, url: nav_url(slot, current_slot), active: slot == current_slot }
+    end
+
+    def self.nav_url(slot, current_slot)
+      return main_dashboard_url(current_slot) if slot == :all
+
+      target_facet_key, value = slot
+      target_dir = facet_dirname(target_facet_key)
+      return "#{value}.html" if current_slot.is_a?(Array) && current_slot[0] == target_facet_key
+      return "../#{target_dir}/#{value}.html" if current_slot.is_a?(Array)
+
+      "#{target_dir}/#{value}.html"
+    end
+
+    def self.main_dashboard_url(current_slot)
+      current_slot.is_a?(Array) ? '../dashboard.html' : 'dashboard.html'
+    end
+
+    def self.facet_dirname(facet_key)
+      Report::FACETS.find { |f| f[:key] == facet_key }[:dirname]
+    end
+
+    def self.write_report(file, format, content, output, slot: :all, **) # rubocop:disable Metrics/ParameterLists
+      ext = format_to_ext(format.to_sym)
+      dir = report_dir(file, **)
+
+      if slot == :all
+        FileUtils.mkdir_p(dir) unless output || File.exist?(dir)
+        output ||= File.join(dir, dashboard_filename(format.to_sym, ext))
+      else
+        facet_key, value = slot
+        dir = File.join(dir, facet_dirname(facet_key))
+        FileUtils.mkdir_p(dir)
+        output = File.join(dir, "#{value}.#{ext}")
+      end
+
+      File.binwrite(output, content)
+      "Report generated at #{output}"
+    end
+
+    def self.report_dir(file, **opts)
+      base_dir = if opts[:output_dir]
+                   opts[:output_dir]
+                 else
+                   input_dir = File.dirname(file)
+                   input_dir == '.' ? 'reports' : File.join(input_dir, 'reports')
+                 end
+      Pathname.new(File.join(base_dir, File.basename(file, '.*'))).cleanpath.to_s
+    end
+
+    def self.clean_report_dir(file, **)
+      dir = report_dir(file, **)
+      FileUtils.rm_rf(dir)
+    end
+
+    def self.dashboard_filename(format, ext)
+      case format
+      when :html, :landscape, :dashboard then 'dashboard.html'
+      when :a3_landscape then 'dashboard_a3.pdf'
+      when :png then 'dashboard.png'
+      else "dashboard.#{ext}"
+      end
+    end
+
+    FORMAT_TO_EXT = {
+      markdown: 'md', md: 'md',
+      confluence: 'conf', conf: 'conf',
+      landscape: 'html', dashboard: 'html',
+      a3_landscape: 'pdf',
+      ppt: 'pptx',
+      png: 'png',
+      raw_csv: 'csv',
+      xlsx: 'xlsx'
+    }.freeze
+
+    def self.format_to_ext(format)
+      FORMAT_TO_EXT[format] || format.to_s
+    end
+  end
+end