snitcher_reports 0.2.0

data/lib/snitcher/holiday_region_resolver.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+require 'tzinfo'
+require 'holidays'
+
+module Snitcher
+  # Maps IANA timezone identifiers to holidays gem region symbols.
+  # Uses TZInfo::Country to build a reverse lookup (timezone → country code),
+  # then validates the country code is available in the holidays gem.
+  #
+  # Some countries only have sub-regions in the holidays gem (e.g. Belgium → :be_fr).
+  # These are handled via a static fallback map.
+  module HolidayRegionResolver
+    # Countries where the base code isn't in holidays gem but a sub-region is.
+    SUB_REGION_FALLBACK = {
+      'be' => 'be_fr',
+      'bg' => 'bg_en',
+      'mt' => 'mt_en',
+      'rs' => 'rs_la'
+    }.freeze
+
+    # Timezones shared by multiple countries in TZInfo where the automatic
+    # "fewest zones" heuristic picks the wrong country. Keyed by IANA
+    # timezone identifier, valued with the correct ISO 3166-1 alpha-2 code.
+    TIMEZONE_COUNTRY_OVERRIDES = {
+      'Europe/Belgrade' => 'rs', # Belgrade is capital of Serbia
+      'Europe/Berlin' => 'de',   # Berlin is capital of Germany
+      'America/Phoenix' => 'us'  # Phoenix is in Arizona, USA
+    }.freeze
+
+    class << self
+      # Resolve IANA timezone to holidays gem region symbol.
+      # @param timezone_name [String] IANA timezone (e.g. "Europe/Warsaw")
+      # @return [Symbol, nil] holidays gem region (e.g. :pl), or nil if unmappable
+      def resolve(timezone_name)
+        country_code = timezone_to_country(timezone_name)
+        return nil unless country_code
+
+        region = SUB_REGION_FALLBACK.fetch(country_code, country_code)
+        region_sym = region.to_sym
+
+        valid_region?(region_sym) ? region_sym : nil
+      end
+
+      # Checks if a region string/symbol is supported by the holidays gem.
+      # @param region [String, Symbol] region to validate
+      # @return [Boolean]
+      def valid_region?(region)
+        available_regions_set.include?(region.to_sym)
+      end
+
+      # Returns public holidays for a given region and year.
+      # Uses :observed flag to include substitute days (consistent with WorkingHoursCalculator).
+      # @param region [Symbol] holidays gem region (e.g. :pl)
+      # @param year [Integer] calendar year
+      # @return [Array<Hash>] holiday entries with :date and :name keys
+      def holidays_for_year(region, year)
+        Holidays.between(Date.new(year, 1, 1), Date.new(year, 12, 31), region, :observed)
+      end
+
+      # Returns the country name for display during init prompts.
+      # @param timezone_name [String] IANA timezone
+      # @return [String, nil] country name (e.g. "Poland"), or nil
+      def country_name(timezone_name)
+        country_code = timezone_to_country(timezone_name)
+        return nil unless country_code
+
+        TZInfo::Country.get(country_code.upcase).name
+      rescue TZInfo::InvalidCountryCode
+        nil
+      end
+
+      # Resets cached timezone→country map and region set. Call in test setup to prevent leakage.
+      def reset_cache!
+        @tz_country_map = nil
+        @available_regions_set = nil
+      end
+
+      private
+
+      # @return [String, nil] lowercase ISO 3166-1 alpha-2 code
+      def timezone_to_country(timezone_name)
+        tz_country_map[timezone_name]
+      end
+
+      # Lazily builds and caches timezone → country code map.
+      # Thread-safe for reads after first build (CLI is single-threaded).
+      def tz_country_map
+        @tz_country_map ||= build_tz_country_map
+      end
+
+      # @return [Set<Symbol>] cached set of available holidays gem regions
+      def available_regions_set
+        @available_regions_set ||= Holidays.available_regions.to_set
+      end
+
+      # Builds a hash mapping every IANA timezone identifier to a single lowercase
+      # ISO 3166-1 alpha-2 country code, resolving multi-country timezones via
+      # TIMEZONE_COUNTRY_OVERRIDES or fewest-zones heuristic.
+      # @return [Hash{String => String}] timezone_name → country_code
+      def build_tz_country_map
+        # Collect all countries claiming each timezone
+        tz_candidates = Hash.new { |h, k| h[k] = [] }
+        TZInfo::Country.all.each do |country|
+          zones = country.zone_identifiers
+          code = country.code.downcase
+          zones.each { |tz| tz_candidates[tz] << [code, zones.size] }
+        end
+
+        tz_candidates.each_with_object({}) do |(tz, candidates), map|
+          map[tz] = if TIMEZONE_COUNTRY_OVERRIDES.key?(tz)
+                      TIMEZONE_COUNTRY_OVERRIDES[tz]
+                    elsif candidates.size == 1
+                      candidates.first[0]
+                    else
+                      # Prefer country with fewest zones (most specific mapping)
+                      candidates.min_by { |_code, zone_count| zone_count }[0]
+                    end
+        end
+      end
+    end
+  end
+end

data/lib/snitcher/jql_validator.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Snitcher
+  # JQL (Jira Query Language) validation and escaping.
+  #
+  # SECURITY NOTE: The JIRA REST API does not support parameterized JQL queries.
+  # All JQL must be constructed as strings. This module provides:
+  # 1. Input validation to reject suspicious patterns
+  # 2. Explicit escaping of user-controlled values
+  # 3. Documentation of security assumptions
+  module JQLValidator
+    # Characters that are dangerous in JQL queries and should be blocked
+    # These are JQL operators and special syntax that could modify query semantics
+    JQL_DANGEROUS_CHARS = /[{}()\[\]"\\*:|&!]/
+
+    # Validate that email is safe for use in JQL queries
+    # IMPORTANT: This is a defense-in-depth check AFTER email format validation.
+    # The email has already been validated by Validators.validate_email!, which
+    # blocks these characters, but we validate again here as explicit defense.
+    def self.validate_email_for_jql!(email)
+      if email.match?(JQL_DANGEROUS_CHARS)
+        raise Validators::ValidationError, "Email contains unsafe JQL characters: #{email}"
+      end
+
+      email
+    end
+
+    # Escape user values for safe inclusion in JQL strings
+    # JQL uses double quotes for string literals, so we escape quotes inside values
+    def self.escape_jql_string(value)
+      value.gsub('"', '\\"')
+    end
+
+    # Validate date string format (YYYY-MM-DD)
+    # Dates are constructed by our code, not user input, but validate for safety
+    def self.validate_date_format!(date_string)
+      unless date_string.match?(/^\d{4}-\d{2}-\d{2}$/)
+        raise Validators::ValidationError, "Invalid date format: #{date_string}. Expected YYYY-MM-DD"
+      end
+
+      date_string
+    end
+  end
+end

data/lib/snitcher/meetings_aggregator.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Snitcher
+  # Collapses google_calendar WorkItems into per-series rows for the Meetings report section.
+  module MeetingsAggregator
+    MEETING_SOURCE = :google_calendar
+
+    module_function
+
+    def meeting_items(items)     = items.select { |i| i.source == MEETING_SOURCE }
+    def non_meeting_items(items) = items.reject { |i| i.source == MEETING_SOURCE }
+    def total_seconds(items)     = meeting_items(items).sum { |i| i.time_spent_seconds || 0 }
+    def any?(items)              = meeting_items(items).any?
+
+    # @return [Hash] { rows: [{title:, count:, total_seconds:}], event_count:, total_seconds: }
+    #   rows sorted by total_seconds desc; recurring instances collapsed by series id.
+    def aggregate(items)
+      meetings = meeting_items(items)
+      rows = meetings.group_by { |i| series_key(i) }.map do |_key, group|
+        { title: group.first.title,
+          count: group.size,
+          total_seconds: group.sum { |i| i.time_spent_seconds || 0 } }
+      end.sort_by { |r| -r[:total_seconds] }
+
+      { rows: rows, event_count: meetings.size,
+        total_seconds: meetings.sum { |i| i.time_spent_seconds || 0 } }
+    end
+
+    # Items round-tripped through NDJSON/JSON have string metadata keys (see work_item.rb#from_h),
+    # so tolerate both symbol and string keys for the series id.
+    def series_key(item)
+      md = item.metadata || {}
+      # Non-recurring events have no series id, so they fall back to title: two distinct one-off
+      # meetings with the same title intentionally collapse into one row (acceptable trade-off).
+      md[:recurring_event_id] || md['recurring_event_id'] || item.title
+    end
+  end
+end

data/lib/snitcher/orchestrator.rb

@@ -0,0 +1,227 @@
+# frozen_string_literal: true
+
+module Snitcher
+  class Orchestrator
+    SOURCE_MAP = {
+      jira: Sources::Jira,
+      git: Sources::Git,
+      linear: Sources::Linear,
+      clickup: Sources::ClickUp,
+      google_calendar: Sources::GoogleCalendar
+    }.freeze
+
+    # Sources that failed to run during the last #fetch, as [{ source:, error: }] — not a
+    # source that ran and simply had nothing to report, which is a legitimate answer and
+    # stays unlisted. Two kinds of failure land here: a source that raised while fetching,
+    # and one that never started because it was not available when this orchestrator was
+    # built.
+    attr_reader :failed_sources
+
+    def initialize(sources: SOURCE_MAP.keys, config: {}, configuration: Configuration.new,
+                   unavailable: [])
+      @configuration = configuration
+      # Decided once, here: availability is a property of the run, not of the person a report
+      # is for. #fetch seeds @failed_sources from this, so everyone in a batch is told about
+      # the same missing sources. `unavailable` carries the ones a caller already dropped
+      # before building this orchestrator — see Client#resolve_sources.
+      @unavailable_sources = unavailable.map { |e| { source: e[:source], error: e[:error] } }
+      @failed_sources = []
+      @user_email_for = {} # single-user override (Array<String>), keyed by source_name symbol
+      @email_map_for = {} # work-email => Array<source-email> map, keyed by source_name symbol
+      @configured_working_hours = {} # per-source fallback, keyed by source_name symbol
+      @sources = sources.filter_map do |source_name|
+        source_class = SOURCE_MAP[source_name]
+        unless source_class
+          record_unavailable(source_name, 'unknown source')
+          next
+        end
+
+        # Merge .snitcher.yml statuses into source config
+        source_config = source_config_for(source_name).merge(
+          config[source_name] || {}
+        )
+
+        # Per-source identity: the emails map (multi-user) translates a requested email
+        # into the source-specific email(s); the single `user` is the default identity
+        # used only when no email is requested (see #emails_for). Both accept a String
+        # or a list of strings (one person committing under several addresses). Both are
+        # stripped before the source is constructed.
+        email_map = source_config[:emails]
+        user_override = source_config[:user]
+        source_config = source_config.except(:user, :emails)
+
+        source = source_class.new(source_config)
+        unless source.available?
+          record_unavailable(source_name, source.unavailable_reason)
+          next
+        end
+
+        if email_map
+          @email_map_for[source_name] = normalize_email_map(email_map, context: "sources.#{source_name}.emails")
+        end
+        if user_override
+          @user_email_for[source_name] = normalize_emails(user_override, context: "sources.#{source_name}.user")
+        end
+        @configured_working_hours[source_name] = source_config[:working_hours]
+        source
+      end
+    end
+
+    def fetch(since:, until_time:, user_email: nil)
+      requested = normalize_requested(user_email)
+      # Seeded, not cleared. A source that raised is this person's outage and must not carry
+      # to the next person in the batch; a source that never started is the run's, and belongs
+      # on every report this orchestrator produces. #dup so per-fetch entries never accumulate
+      # into the per-run list.
+      @failed_sources = @unavailable_sources.dup
+
+      @sources.flat_map do |source|
+        emails = emails_for(source.source_name, requested)
+        if emails.empty?
+          record_dropped_identity(source.source_name) unless requested
+          next []
+        end
+
+        apply_working_hours(source, requested)
+        source.fetch(user_email: emails, since: since, until_time: until_time)
+      rescue Validators::ValidationError => e
+        # Validation errors should fail fast - re-raise
+        raise e
+      rescue StandardError => e
+        # Record the outage before continuing, so the report can mark itself incomplete
+        # instead of presenting a short list as the whole truth.
+        @failed_sources << { source: source.source_name, error: "#{e.class}: #{e.message}" }
+        # Log error with actionable hint and continue with other sources
+        warn "[#{source.source_name}] Error fetching data: #{e.class}: #{e.message}"
+        warn '  Check credentials in .env and network connectivity.'
+        warn "  Backtrace: #{e.backtrace.first(5).join("\n            ")}" if ENV['DEBUG']
+        []
+      end.sort_by { |item| -(item.completed_at&.to_f || 0) }
+    end
+
+    def available_sources
+      @sources.map(&:source_name)
+    end
+
+    private
+
+    # Resolves the list of emails a source should filter by, in priority order:
+    #   1. the emails map (sources.<name>.emails): a per-user translation from the
+    #      requested work email to the source-specific identity.
+    #   2. otherwise the requested email as-is; if it matches no data the source just
+    #      returns nothing — we never substitute a different identity. Nothing here
+    #      can tell whose address was requested, so substituting the configured
+    #      default would hand one person's data to a report labelled with another's.
+    # When NO email is requested the configured default identity (sources.<name>.user)
+    # applies — that is the "run it for myself" path, where no one else was named.
+    # Returns an Array<String>; empty when nothing is requested and no default is set.
+    def emails_for(source_name, requested)
+      return Array(@user_email_for[source_name]) unless requested
+
+      map = @email_map_for[source_name]
+      mapped = map && Array(map[requested])
+      return mapped if mapped && !mapped.empty?
+
+      warn_unmapped_identity(source_name, requested)
+      [requested]
+    end
+
+    # Points the source at this person's working hours. A person named under
+    # working_hours.people gets their own; everyone else is reset to whatever the source
+    # was constructed with — the shared block, or a value handed straight to
+    # Orchestrator.new(config:). Resetting rather than leaving the slot alone is what
+    # stops one person's override from carrying into the next person in the batch.
+    def apply_working_hours(source, requested)
+      source.working_hours = @configuration.working_hours_override(requested) ||
+                             @configured_working_hours[source.source_name]
+    end
+
+    # Records a source that never started. Mirrors the rescue in #fetch — same entry shape,
+    # same channel — because a consumer cannot act on the difference between "asked and it
+    # broke" and "never asked, it was not there": either way the items are missing. Called
+    # right before the `next` that drops the source in #initialize's filter_map; the nil
+    # this returns is discarded, since `next` has already exited the block by then.
+    def record_unavailable(source_name, error)
+      @unavailable_sources << { source: source_name, error: error }
+      warn "[#{source_name}] Skipped: #{error}."
+      warn '  Its items are missing from every report in this run.'
+      nil
+    end
+
+    # Records a source skipped on the no-email path because its `user` was configured but
+    # lost every address to validation (see #normalize_emails). Per fetch, not per run like
+    # #record_unavailable: a named email never reads `user`, so a batch is unaffected. No
+    # `user` at all stays unlisted — there is no one to report on, and nothing is broken.
+    def record_dropped_identity(source_name)
+      return unless @user_email_for.key?(source_name)
+
+      @failed_sources << { source: source_name, error: "no valid address in sources.#{source_name}.user" }
+    end
+
+    # Warns once per source when a named email has no mapping while a default identity
+    # is configured. That combination used to silently swap in the default; the report
+    # now filters by the requested address, so a setup relying on the old behaviour
+    # gets an empty section instead of a wrong one. The hint names the fix.
+    def warn_unmapped_identity(source_name, requested)
+      default = Array(@user_email_for[source_name])
+      return if default.empty?
+
+      @warned_unmapped ||= {}
+      return if @warned_unmapped[source_name]
+
+      @warned_unmapped[source_name] = true
+      warn "[#{source_name}] No sources.#{source_name}.emails entry for #{requested} — " \
+           "filtering by that address. Add \"#{requested}: #{default.join(', ')}\" " \
+           "under sources.#{source_name}.emails if it is the same person."
+    end
+
+    # Validates the requested email when present; nil/blank means "not requested",
+    # deferring to the per-source default in #emails_for.
+    def normalize_requested(user_email)
+      return nil if user_email.nil? || user_email.to_s.strip.empty?
+
+      Validators.validate_email!(user_email)
+    end
+
+    # Coerces the config map to { String => Array<String> }, tolerating symbol/string
+    # keys and String-or-Array values (one person committing under several addresses).
+    # A malformed entry is warned about and dropped rather than raised: this map holds
+    # every person's identity for this source, so one typo must not cost everyone else
+    # their report (see #normalize_emails). An entry left with no valid address is left out
+    # of the map altogether, so that person resolves exactly as if they had no entry.
+    def normalize_email_map(raw, context:)
+      return {} unless raw.is_a?(Hash)
+
+      raw.each_with_object({}) do |(work, git), map|
+        key = work.to_s
+        emails = normalize_emails(git, context: "#{context}[#{key}]")
+        map[key] = emails unless emails.empty?
+      end
+    end
+
+    # Coerces a String or Array of emails into a validated, deduped Array<String>.
+    # An invalid entry is warned about and skipped rather than raised, so it only
+    # empties out the mapping it belongs to instead of aborting Orchestrator.new
+    # before any report in the batch has run.
+    def normalize_emails(value, context:)
+      Array(value).filter_map do |email|
+        Validators.validate_email!(email.to_s)
+      rescue Validators::ValidationError => e
+        warn "[Snitcher] Warning: #{e.message} in #{context}. That address is dropped, " \
+             'so items under it are missing from reports.'
+        nil
+      end.uniq
+    end
+
+    # Returns all non-empty config keys for a source from .snitcher.yml.
+    # Passes through status keys, project/space filters, and any future keys.
+    # Injects global working_hours config — consumed by Jira, Linear, and ClickUp
+    # for filtering calculated time to business hours. Update when adding new sources.
+    def source_config_for(source_name)
+      return {} unless @configuration.exists?
+
+      @configuration.source_with_working_hours(source_name)
+                    .reject { |_k, v| v.respond_to?(:empty?) && v.empty? }
+    end
+  end
+end

data/lib/snitcher/presenters/html.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require 'base64'
+require 'erb'
+require 'uri'
+
+module Snitcher
+  module Presenters
+    class Html
+      include Presenter
+
+      ALLOWED_URL_SCHEMES = %w[http https mailto].freeze
+      TRACKER_SOURCES = %i[jira linear clickup].freeze
+
+      def render
+        render_time = Time.now
+        stats, grouped = compute_stats_and_groups
+        logo_data_uri = load_logo_data_uri
+        template_path = File.expand_path('../templates/report.html.erb', __dir__)
+        ERB.new(File.read(template_path)).result(binding)
+      end
+
+      SEVERITY_COLORS = { critical: '#c0392b', warning: '#d35400', info: '#2c7be5' }.freeze
+      def severity_color(severity) = SEVERITY_COLORS.fetch(severity, '#555')
+
+      private
+
+      def compute_stats_and_groups
+        total_seconds = 0
+        meeting_seconds = 0
+        tracker_items = 0
+        commits_count = 0
+        grouped = {}
+
+        items.each do |item|
+          # Meetings render in their own aggregated section, not a per-source table, and are
+          # excluded from tracked-time totals (reported separately as Meeting Hours).
+          if item.source == MeetingsAggregator::MEETING_SOURCE
+            meeting_seconds += item.time_spent_seconds || 0
+            next
+          end
+
+          total_seconds += item.time_spent_seconds || 0
+          tracker_items += 1 if TRACKER_SOURCES.include?(item.source)
+          commits_count += 1 if item.source == :git
+          (grouped[item.source] ||= []) << item
+        end
+
+        hours_logged = (total_seconds / TimeFormatter::SECONDS_PER_HOUR.to_f).round
+        meeting_hours = (meeting_seconds / TimeFormatter::SECONDS_PER_HOUR.to_f).round
+
+        [{ total_seconds: total_seconds, tracker_items: tracker_items,
+           commits_count: commits_count, hours_logged: hours_logged,
+           meeting_seconds: meeting_seconds, meeting_hours: meeting_hours,
+           meeting_aggregate: MeetingsAggregator.aggregate(items) }, grouped]
+      end
+
+      def load_logo_data_uri
+        path = File.expand_path('../templates/snitcher-logo.png', __dir__)
+        "data:image/png;base64,#{Base64.strict_encode64(File.binread(path))}"
+      end
+
+      def safe_url(url)
+        return nil unless url
+
+        uri = URI.parse(url)
+        ALLOWED_URL_SCHEMES.include?(uri.scheme&.downcase) ? ERB::Util.html_escape(url) : nil
+      rescue URI::InvalidURIError
+        nil
+      end
+
+      def item_label(source, count)
+        word = source == :git ? 'commit' : 'ticket'
+        count == 1 ? word : "#{word}s"
+      end
+
+      # Escapes the AI narrative, then re-applies a minimal safe markdown subset:
+      # newlines to <br>, **bold** to <strong>. Escaping happens first, so the
+      # re-applied tags can never be used to inject markup from the narrative text.
+      def render_narrative_html(narrative)
+        ERB::Util.html_escape(narrative)
+                 .gsub("\n", '<br>')
+                 .gsub(/\*\*(.+?)\*\*/, '<strong>\1</strong>')
+      end
+    end
+  end
+end

data/lib/snitcher/presenters/markdown.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+module Snitcher
+  module Presenters
+    class Markdown
+      include Presenter
+
+      def render
+        sections = []
+        sections << render_header if header_available?
+        sections << render_narrative if config[:narrative]
+        sections << render_summary
+        sections << render_by_source if non_meeting_items.any?
+        sections << render_meetings if MeetingsAggregator.any?(items)
+        sections << render_all_items if non_meeting_items.any?
+        sections << render_anomalies if anomalies.any?
+        sections.join("\n\n")
+      end
+
+      private
+
+      def render_anomalies
+        headers = %w[Severity Signal Details]
+        rows = anomalies.map { |a| [escape_md(a.severity.to_s), escape_md(a.title), escape_md(a.description)] }
+        "## Potential Problems\n\n#{format_table(headers, rows)}"
+      end
+
+      def non_meeting_items
+        @non_meeting_items ||= MeetingsAggregator.non_meeting_items(items)
+      end
+
+      def header_available?
+        config[:user_email] || config[:since] || config[:until_time]
+      end
+
+      def render_header
+        lines = ["# Snitcher Report\n"]
+        lines << "**User**: #{escape_md(config[:user_email].to_s)}" if config[:user_email]
+        if config[:since] && config[:until_time]
+          since_str = config[:since].strftime('%Y-%m-%d')
+          # until_time is exclusive (already offset by +1 day); subtract to get display date
+          until_str = (config[:until_time] - TimeFormatter::SECONDS_PER_DAY).strftime('%Y-%m-%d')
+          lines << "**Period**: #{since_str} \u2013 #{until_str}" # en-dash (U+2013) is intentional
+        end
+        lines << "**Generated**: #{Time.now.strftime('%Y-%m-%d %H:%M')}"
+        lines.join("\n")
+      end
+
+      def render_narrative
+        "## Overview\n\n#{config[:narrative]}"
+      end
+
+      def items_by_source
+        @items_by_source ||= non_meeting_items.group_by(&:source)
+      end
+
+      def render_summary
+        sources = items.map(&:source).uniq
+
+        headers = %w[Metric Value]
+        rows = [
+          ['Total items', items.count.to_s],
+          ['Sources', sources.map { |s| escape_md(s.to_s) }.join(', ')]
+        ]
+        rows << ['Total tracked time', format_duration(total_seconds)] if total_seconds.positive?
+        if MeetingsAggregator.any?(items)
+          m = MeetingsAggregator.aggregate(items)
+          rows << ['Meetings', "#{format_duration(m[:total_seconds])} across #{m[:event_count]} events"]
+        end
+
+        "## Summary\n\n#{format_table(headers, rows)}"
+      end
+
+      # Dedicated Meetings section: a total plus one row per recurring series (collapsed).
+      def render_meetings
+        m = MeetingsAggregator.aggregate(items)
+
+        headers = %w[Meeting Count Time]
+        rows = m[:rows].map do |row|
+          [escape_md(truncate(row[:title], TITLE_TRUNCATE_LENGTH_BY_SOURCE)),
+           row[:count].to_s,
+           format_duration(row[:total_seconds])]
+        end
+
+        total_line = "**Total**: #{format_duration(m[:total_seconds])} across #{m[:event_count]} events"
+        "## Meetings\n\n#{total_line}\n\n#{format_table(headers, rows)}"
+      end
+
+      def render_by_source
+        sections = ['## Work Items by Source']
+        items_by_source.each do |source, source_items|
+          sections << render_source_section(source, source_items)
+        end
+        sections.join("\n\n")
+      end
+
+      def render_source_section(source, source_items)
+        headers = ['Ticket', 'Summary', 'Time Spent', 'Completed']
+        rows = source_items.map do |item|
+          [
+            format_ticket(item),
+            escape_md(truncate(item.title, TITLE_TRUNCATE_LENGTH_BY_SOURCE)),
+            item.time_spent_human || '-',
+            item.completed_date || '-'
+          ]
+        end
+
+        "### #{escape_md(source.to_s.capitalize)}\n\n#{format_table(headers, rows)}"
+      end
+
+      def render_all_items
+        headers = ['Source', 'Ticket', 'Summary', 'Time Spent', 'Completed']
+        rows = non_meeting_items.map do |item|
+          [
+            escape_md(item.source),
+            format_ticket(item),
+            escape_md(truncate(item.title, TITLE_TRUNCATE_LENGTH)),
+            item.time_spent_human || '-',
+            item.completed_date || '-'
+          ]
+        end
+
+        "## All Items\n\n#{format_table(headers, rows)}"
+      end
+
+      # Formats a work item's ticket ID, linking it to the item URL when available.
+      # Escapes parentheses and pipes in URLs to prevent markdown syntax breakage.
+      # @param item [WorkItem]
+      # @return [String] plain escaped ID or markdown link
+      def format_ticket(item)
+        if item.url
+          escaped_url = item.url.gsub('(', '%28').gsub(')', '%29').gsub('|', '%7C').gsub(/[\r\n]/, '')
+          "[#{escape_md(item.external_id)}](#{escaped_url})"
+        else
+          escape_md(item.external_id)
+        end
+      end
+    end
+  end
+end