snitcher_reports 0.2.0

data/lib/snitcher/sources/git.rb

@@ -0,0 +1,347 @@
+# frozen_string_literal: true
+
+require 'time'
+
+module Snitcher
+  module Sources
+    # Reads work items from the commit history of a local checkout.
+    #
+    # Every git invocation goes through CommandRunner, which raises when git exits
+    # non-zero or has to be killed for hanging. That is deliberate: the only other thing
+    # this source could return on a broken git is an empty list, and an empty list is
+    # indistinguishable from a week in which nobody committed. Orchestrator#fetch catches
+    # the exception, records the source in #failed_sources and marks the report
+    # incomplete — the same route a Jira or ClickUp outage takes.
+    #
+    # Two commands are exempt, via CommandRunner#output_or_nil, because a non-zero exit
+    # from them is a legitimate answer rather than an outage: see #remote_base_url and
+    # #diff_stats. They warn and degrade, and only that one detail is lost. A third case
+    # is exempt for the same reason and reports nothing at all: a checkout with no commits
+    # on it yet, which git fails on but which is an empty week, not an outage — see
+    # #no_commits_yet?.
+    class Git < Source
+      # Matches JIRA-style ticket IDs: 2-10 uppercase letters, hyphen, digits
+      # Examples: "PROJ-123", "ENG-1", "AB-99999"
+      TICKET_REGEX = /([A-Z]{2,10}-\d+)/
+
+      # Matches GitHub/GitLab PR/MR numbers prefixed with #
+      # Examples: "#123", "#1", "#99999"
+      PR_NUMBER_REGEX = /#(\d+)/
+
+      def initialize(config = {})
+        super
+        # Whether the path was chosen or merely inherited is what #unavailable_reason reports:
+        # a configured path that is not a checkout is a typo to fix, an inherited working
+        # directory is just where the process happened to run. Mirrors the || below rather
+        # than Source.presence, so the two stay in step.
+        @repo_path_configured = !config[:repo_path].nil?
+        @repo_path = config[:repo_path] || Dir.pwd
+        @command_runner = CommandRunner.new(repo_path: @repo_path, timeout_seconds: config[:timeout])
+      end
+
+      def source_name
+        :git
+      end
+
+      def available?
+        Dir.exist?(File.join(@repo_path, '.git'))
+      end
+
+      def unavailable_reason
+        return "sources.git.repo_path (#{@repo_path}) is not a git checkout" if @repo_path_configured
+
+        "no sources.git.repo_path is set and the working directory (#{@repo_path}) " \
+          'is not a git checkout'
+      end
+
+      def fetch(user_email:, since:, until_time:)
+        return [] unless available?
+
+        emails = user_emails(user_email)
+        items = []
+        items += fetch_merge_items(emails: emails, since: since, until_time: until_time)
+        items += fetch_non_merge_items(emails: emails, since: since, until_time: until_time)
+        deduplicate_by_pr(items)
+      end
+
+      private
+
+      def fetch_merge_items(emails:, since:, until_time:)
+        find_merge_commits(since: since, until_time: until_time).filter_map do |merge|
+          authors = pr_authors(merge[:hash])
+          next unless authors.intersect?(emails)
+
+          stats = diff_stats(from: "#{merge[:hash]}^1", to: "#{merge[:hash]}^2")
+          ticket_ids = extract_ticket_ids(merge[:subject])
+          ticket_ids = extract_ticket_ids(merge[:body].to_s) if ticket_ids.empty? && merge[:body]
+
+          build_work_item(
+            external_id: ticket_ids.first || merge[:hash][0..7],
+            title: clean_title(merge[:subject], merge[:body]),
+            completed_at: merge[:date],
+            time_spent_seconds: nil,
+            time_source: nil,
+            url: commit_url(merge[:hash]),
+            metadata: {
+              commit: merge[:hash],
+              commit_type: :merge,
+              ticket_ids: ticket_ids,
+              pr_number: extract_pr_number(merge[:subject]),
+              lines_added: stats[:added],
+              lines_deleted: stats[:deleted],
+              files_changed: stats[:files],
+              authors: authors
+            }
+          )
+        end
+      end
+
+      def fetch_non_merge_items(emails:, since:, until_time:)
+        commits = find_non_merge_commits(since: since, until_time: until_time)
+        authors_by_hash = batch_commit_authors(commits.map { |c| c[:hash] })
+
+        commits.filter_map do |commit|
+          authors = authors_by_hash[commit[:hash]] || []
+          next unless authors.intersect?(emails)
+
+          stats = diff_stats(from: "#{commit[:hash]}~1", to: commit[:hash])
+          ticket_ids = extract_ticket_ids(commit[:subject])
+          pr_number = extract_pr_number(commit[:subject])
+
+          build_work_item(
+            external_id: ticket_ids.first || commit[:hash][0..7],
+            title: commit[:subject],
+            completed_at: commit[:date],
+            time_spent_seconds: nil,
+            time_source: nil,
+            url: commit_url(commit[:hash]),
+            metadata: {
+              commit: commit[:hash],
+              commit_type: pr_number ? :squash : :direct,
+              ticket_ids: ticket_ids,
+              pr_number: pr_number,
+              lines_added: stats[:added],
+              lines_deleted: stats[:deleted],
+              files_changed: stats[:files],
+              authors: authors
+            }
+          )
+        end
+      end
+
+      def find_merge_commits(since:, until_time:)
+        fetch_git_log_records(['--merges'], since: since, until_time: until_time)
+      end
+
+      def find_non_merge_commits(since:, until_time:)
+        fetch_git_log_records(['--no-merges', '--first-parent'], since: since, until_time: until_time)
+      end
+
+      # Parses structured git log output into work-item field hashes.
+      #
+      # Raises when git fails: this is what feeds #fetch, and an empty list here is the
+      # report's entire git section. The one exception is a checkout with no commits on
+      # it yet, which git also reports as a failure but which genuinely has nothing to
+      # report — see #no_commits_yet?.
+      #
+      # A checkout that has commits, none of them in the requested window, never reaches
+      # either branch: git exits zero with empty output, and that has always read as the
+      # empty week it is.
+      def fetch_git_log_records(flags, since:, until_time:)
+        output = @command_runner.output(
+          ['log', *flags, "--since=#{since.iso8601}", "--until=#{until_time.iso8601}",
+           # Use \x01/\x00 as record/field separators because %b (body) can contain newlines
+           '--format=%x01%H%x00%ae%x00%aI%x00%s%x00%b']
+        )
+
+        output.split("\x01").filter_map do |record|
+          next if record.strip.empty?
+
+          hash, author_email, date_str, subject, body = record.split("\x00", 5)
+          {
+            hash: hash.strip,
+            author_email: author_email,
+            date: Time.parse(date_str),
+            subject: subject,
+            body: body&.split("\n")&.find { |l| !l.strip.empty? }&.strip
+          }
+        end
+      rescue CommandRunner::CommandError
+        raise unless no_commits_yet?
+
+        []
+      end
+
+      # True when the checkout is a readable repository whose HEAD carries no commit yet:
+      # a fresh `git init`, or a branch nobody has committed to.
+      #
+      # This has to be told apart from a checkout git cannot read at all, because git
+      # fails the same way for both — exit 128 from `git log`. "Nobody has committed
+      # anything" is an answer, and the report states it as zero items; "this checkout is
+      # broken" is not, and the report has to say the source failed. The two are separated
+      # structurally rather than by matching git's wording, which is localised: for an
+      # unborn HEAD the repository itself still resolves and only HEAD does not.
+      #
+      # Memoized: the orchestrator walks a batch of people on one source instance, and the
+      # repository does not grow a first commit halfway through the run.
+      def no_commits_yet?
+        return @no_commits_yet if defined?(@no_commits_yet)
+
+        @no_commits_yet = @command_runner.success?(%w[rev-parse --git-dir]) &&
+                          !@command_runner.success?(%w[rev-parse --verify --quiet HEAD])
+      end
+
+      # Returns the HTTPS URL for a commit (e.g. "https://github.com/org/repo/commit/abc123"),
+      # or nil when the remote cannot be resolved.
+      def commit_url(hash)
+        remote_base_url&.then { |base| "#{base}/commit/#{hash}" }
+      end
+
+      # Resolves the origin remote URL into a browsable HTTPS base URL.
+      # Handles SCP-style SSH (git@host:org/repo), ssh:// protocol, and HTTPS URLs.
+      # Strips embedded credentials from HTTPS URLs to prevent token leakage.
+      # Memoized (including nil on failure) — resolved once per source instance.
+      #
+      # Warns rather than raising on a failing git: a checkout with no `origin` is a
+      # normal local repo, and `git remote get-url` exits non-zero for it. All that is
+      # lost is the link on each item, so failing the source here would throw away a
+      # correct commit list over a missing hyperlink. Memoization means one warning.
+      def remote_base_url
+        return @remote_base_url if defined?(@remote_base_url)
+
+        output = @command_runner.output_or_nil(%w[remote get-url origin],
+                                               consequence: 'Items carry no commit links.')
+        @remote_base_url = output && normalize_remote_url(output.strip)
+      end
+
+      # Converts a git remote URL to a browsable HTTPS base URL.
+      # @param url [String] raw remote URL from git
+      # @return [String] HTTPS URL without .git suffix or credentials
+      def normalize_remote_url(url)
+        return nil if url.empty?
+
+        normalized =
+          case url
+          when %r{^ssh://}
+            # ssh://git@github.com/org/repo.git → https://github.com/org/repo
+            url.sub(%r{^ssh://[^/]*@}, 'https://')
+          when /^git@/
+            # git@github.com:org/repo.git → https://github.com/org/repo
+            url.sub(/^git@([^:]+):/, 'https://\1/')
+          when %r{^https?://}
+            # Strip credentials from HTTPS URLs: https://token@github.com/... → https://github.com/...
+            url.sub(%r{://[^/]*@}, '://')
+          else
+            # Unrecognized schemes (git://, file://, etc.) — not browsable
+            return nil
+          end
+        normalized.sub(/\.git$/, '')
+      end
+
+      # Get all commit authors between the two parents of the merge.
+      #
+      # Raises when git fails, because the caller reads the result as "this merge is
+      # not yours" and drops the item. The known non-outage failure is a shallow clone,
+      # where a merge parent may be missing — but a shallow clone also truncates the
+      # log this source walks, so a report built on one is wrong in ways that are worth
+      # a failed source rather than a quietly short list.
+      def pr_authors(merge_hash)
+        output = @command_runner.output(
+          ['log', '--format=%ae', '--no-merges', "#{merge_hash}^1..#{merge_hash}^2"]
+        )
+
+        output.lines.map(&:strip).uniq
+      end
+
+      # Fetches authors for multiple commits in a single git subprocess call,
+      # returning a hash of { commit_hash => [author_emails] }.
+      # Parses Co-authored-by trailers to include co-authors.
+      #
+      # Raises when git fails: authorship is the filter every non-merge commit passes
+      # through, so an empty result drops the entire non-merge half of the report.
+      def batch_commit_authors(commit_hashes)
+        return {} if commit_hashes.empty?
+
+        # Use \x01 as record separator between commits
+        output = @command_runner.output(['log', '--no-walk', '--format=%x01%H%n%ae%n%B', *commit_hashes])
+
+        result = {}
+        output.split("\x01").each do |record|
+          next if record.strip.empty?
+
+          lines = record.lines.map(&:strip)
+          hash = lines.first
+          authors = [lines[1]].compact.reject(&:empty?)
+
+          lines.each do |line|
+            match = line.match(/^Co-authored-by:\s*[^<]+<([^>]+)>/i)
+            authors << match[1] if match
+          end
+
+          result[hash] = authors.uniq
+        end
+
+        result
+      end
+
+      # Line counts for one commit, zero when they cannot be read.
+      #
+      # Warns rather than raising: `git diff <commit>~1 <commit>` exits non-zero for a
+      # root commit, which has no parent, and that is an ordinary commit to report. The
+      # item still appears with everything that identifies it — only its line counts are
+      # missing — so this is the one place where degrading costs less than failing.
+      def diff_stats(from:, to:)
+        output = @command_runner.output_or_nil(['diff', '--numstat', from, to],
+                                               consequence: "Line counts for #{to} read as zero.")
+        return { added: 0, deleted: 0, files: 0 } unless output
+
+        added = deleted = files = 0
+
+        output.lines.each do |line|
+          parts = line.strip.split("\t")
+          next if parts[0] == '-' # binary file
+
+          added += parts[0].to_i
+          deleted += parts[1].to_i
+          files += 1
+        end
+
+        { added: added, deleted: deleted, files: files }
+      end
+
+      def extract_ticket_ids(subject)
+        subject.scan(TICKET_REGEX).flatten.uniq
+      end
+
+      def extract_pr_number(subject)
+        match = subject.match(PR_NUMBER_REGEX)
+        match ? match[1].to_i : nil
+      end
+
+      # Clean merge commit subject by removing common prefixes (GitHub/GitLab formats).
+      # For GitHub-style merges the subject is just the merge boilerplate; the actual
+      # PR title lives in the commit body, so fall back to body when subject strips empty.
+      # Falls back to the original subject if body is also absent, ensuring a non-nil title.
+      def clean_title(subject, body = nil)
+        cleaned = subject
+                  .sub(/^Merge pull request #\d+ from \S+\s*/, '')
+                  .sub(/^Merge branch '\S+'\s*(into \S+)?/, '')
+                  .strip
+
+        return cleaned unless cleaned.empty?
+        return body unless body.nil? || body.empty?
+
+        subject
+      end
+
+      # Merge items are added first, so merge commits take precedence over squash duplicates
+      def deduplicate_by_pr(items)
+        seen = {}
+        items.select do |item|
+          pr = item.metadata[:pr_number]
+          !pr || (seen[pr] ? false : seen[pr] = true)
+        end
+      end
+    end
+  end
+end

data/lib/snitcher/sources/google_calendar.rb

@@ -0,0 +1,328 @@
+# frozen_string_literal: true
+
+require 'base64'
+require 'google/apis/calendar_v3'
+require 'googleauth'
+require 'json'
+require 'stringio'
+require 'time'
+
+module Snitcher
+  module Sources
+    # Reports meeting time from a Google Calendar as WorkItems (one per meeting instance).
+    #
+    # Two authentication paths, see README "Google Calendar Setup":
+    # a service account with domain-wide delegation, which impersonates the requested user
+    # and is what makes multi-user reports possible, or a static OAuth2 refresh token, which
+    # reads one fixed account. The service account wins when both are configured.
+    #
+    # Recurring series are expanded into individual instances (single_events: true) and
+    # collapsed for display by MeetingsAggregator via the shared recurring_event_id.
+    #
+    # Filters applied during fetch: meetings that have not finished yet, declined RSVPs, all-day
+    # events, solo events (no other attendees), and — when working_hours is configured — time
+    # outside business hours.
+    class GoogleCalendar < Source
+      # The two credential paths ask for different scopes on purpose.
+      #
+      # Domain-wide delegation matches scopes literally: an admin who authorized
+      # `calendar.events` has not thereby authorized `calendar.events.readonly`, and asking for
+      # the narrower one fails with `unauthorized_client`. DELEGATED_SCOPE is therefore the
+      # read/write scope Workspace admins already grant to calendar-writing apps, so Snitcher
+      # works against an existing delegation entry. This source only lists events; narrow the
+      # constant to `calendar.events.readonly` where you control the delegation and can add it.
+      #
+      # OAuth carries the scope its refresh token was granted, so it stays read-only — widening
+      # it here would invalidate tokens already issued.
+      DELEGATED_SCOPE = 'https://www.googleapis.com/auth/calendar.events'
+      OAUTH_SCOPE = 'https://www.googleapis.com/auth/calendar.events.readonly'
+      TOKEN_URI = 'https://oauth2.googleapis.com/token'
+      DEFAULT_CALENDAR_ID = 'primary'
+      MAX_RESULTS = 250 # Google Calendar API per-page maximum
+      MAX_PAGES = 20 # safety cap, mirrors other sources
+      SERVICE_ACCOUNT_ENV = 'GOOGLE_SERVICE_ACCOUNT_JSON'
+
+      def initialize(config = {})
+        super
+        validate_calendar_id!(config[:calendar_id])
+        @client_id     = Source.presence(config[:client_id])     || Source.env('GOOGLE_CLIENT_ID')
+        @client_secret = Source.presence(config[:client_secret]) || Source.env('GOOGLE_CLIENT_SECRET')
+        @refresh_token = Source.presence(config[:refresh_token]) || Source.env('GOOGLE_REFRESH_TOKEN')
+        @service_account_json = Source.presence(config[:service_account_json]) ||
+                                Source.env(SERVICE_ACCOUNT_ENV)
+        @calendar_id   = Source.presence(config[:calendar_id]) || DEFAULT_CALENDAR_ID
+        @service       = config[:service] # test seam; nil in production
+        @now           = config[:now]     # test seam; nil in production
+        @services_by_email = {}
+
+        warn_both_credentials if service_account? && oauth?
+      end
+
+      def source_name
+        :google_calendar
+      end
+
+      def available?
+        service_account? || oauth?
+      end
+
+      def unavailable_reason
+        "neither #{SERVICE_ACCOUNT_ENV} nor the GOOGLE_CLIENT_ID + GOOGLE_CLIENT_SECRET + " \
+          'GOOGLE_REFRESH_TOKEN trio is set'
+      end
+
+      # Multi-user reporting needs a service account: the OAuth path reads one fixed account's
+      # calendar and cannot honour a requested user_email. Credentials are ENV-only by design
+      # (config[:service_account_json] exists for tests), so this reads ENV.
+      def self.multi_user_capable?
+        !!Source.env(SERVICE_ACCOUNT_ENV)
+      end
+
+      # Reads the requested user's calendar. With a service account the credentials impersonate
+      # them; with OAuth there is a single authenticated account, so user_email cannot select a
+      # calendar and every requested user sees that one account's meetings.
+      #
+      # One address per person. A person mapped to several addresses is a configuration error
+      # rather than a silent choice of the first one: there is one calendar identity per person,
+      # and picking one address at random would report the wrong calendar without saying so.
+      def fetch(user_email:, since:, until_time:)
+        return [] unless available?
+
+        emails = Array(user_email)
+        validate_one_address!(emails)
+
+        email = primary_email(emails)
+        return [] if email.nil? || email.to_s.strip.empty?
+
+        cutoff = cutoff_for(until_time)
+        # A window entirely in the future holds no finished meetings, and a reversed range is not
+        # something to ask Google about.
+        return [] if cutoff <= since
+
+        list_calendar_events(user_email: email, since: since, until_time: cutoff).filter_map do |event|
+          next if unfinished?(event, cutoff)
+          next if all_day?(event)
+          next if declined?(event)
+          next if solo?(event)
+
+          seconds = meeting_seconds(event)
+          next unless seconds.positive? # fully outside working hours
+
+          build_meeting_item(event, seconds)
+        end
+      end
+
+      private
+
+      # --- configuration ---
+
+      # Checked before Source.presence, which calls strip and would raise NoMethodError on an
+      # Array — in the constructor, outside the Orchestrator's per-source rescue, taking down
+      # the whole report instead of just this source.
+      def validate_calendar_id!(calendar_id)
+        return unless calendar_id.is_a?(Array)
+
+        raise Snitcher::ConfigurationError,
+              'sources.google_calendar.calendar_id takes one calendar, not a list.'
+      end
+
+      def validate_one_address!(emails)
+        return unless emails.size > 1
+
+        raise Snitcher::ConfigurationError,
+              'google_calendar accepts one address per person. ' \
+              "sources.google_calendar.emails maps #{emails.first} to #{emails.size} addresses."
+      end
+
+      # --- credentials ---
+
+      def service_account?
+        !!@service_account_json
+      end
+
+      def oauth?
+        !!(@client_id && @client_secret && @refresh_token)
+      end
+
+      # The service account takes precedence: unlike the OAuth token, it honours user_email.
+      # Warn so a configured refresh token is not mistaken for the credential in use.
+      def warn_both_credentials
+        warn "[google_calendar] both #{SERVICE_ACCOUNT_ENV} and GOOGLE_REFRESH_TOKEN are set; " \
+             'using the service account.'
+      end
+
+      # The authorized service for one user, cached per email. With a service account the
+      # credentials impersonate that user; with OAuth there is a single authenticated account
+      # and every user shares it.
+      def service_for_user(user_email)
+        return @service if @service # injected fake: shared across users by design
+
+        @services_by_email[user_email] ||= build_service(user_email)
+      end
+
+      def build_service(user_email)
+        svc = Google::Apis::CalendarV3::CalendarService.new
+        svc.authorization = service_account? ? impersonated_credentials(user_email) : oauth_credentials
+        svc
+      end
+
+      # The key is parsed once. #duplicate carries `sub` as a first-class option and drops the
+      # base credential's cached tokens, so no token leaks between impersonated users.
+      def impersonated_credentials(user_email)
+        base_service_account_credentials.duplicate(sub: user_email)
+      end
+
+      def base_service_account_credentials
+        @base_service_account_credentials ||=
+          Google::Auth::ServiceAccountCredentials.make_creds(
+            json_key_io: StringIO.new(decoded_service_account_key), scope: DELEGATED_SCOPE
+          )
+      end
+
+      # Decoded here rather than left to googleauth so a misconfigured variable reports what to
+      # fix, instead of surfacing an OpenSSL or JSON error from inside the gem.
+      #
+      # The hint avoids the base64 command on purpose: GNU base64 wraps its output at 76
+      # characters, and strict_decode64 rejects newlines. The Ruby one-liner is portable.
+      def decoded_service_account_key
+        decoded = Base64.strict_decode64(@service_account_json)
+        JSON.parse(decoded)
+        decoded
+      rescue ArgumentError
+        raise Snitcher::ConfigurationError,
+              "#{SERVICE_ACCOUNT_ENV} is not valid base64, or contains line breaks. Encode the " \
+              "key file: ruby -rbase64 -e 'print Base64.strict_encode64(File.binread(ARGV[0]))' key.json"
+      rescue JSON::ParserError
+        raise Snitcher::ConfigurationError,
+              "#{SERVICE_ACCOUNT_ENV} does not decode to JSON. Re-encode the service account key file."
+      end
+
+      def oauth_credentials
+        Google::Auth::UserRefreshCredentials.new(
+          client_id: @client_id, client_secret: @client_secret,
+          refresh_token: @refresh_token, scope: OAUTH_SCOPE, token_credential_uri: TOKEN_URI
+        )
+      end
+
+      # --- transport (test seam: override via config[:service] or stub this method) ---
+
+      # calendar_id applies in both credential modes. Left at the default, every reported
+      # person reads their own calendar, because `primary` resolves against the impersonated
+      # user. Set, every reported person reads that one calendar — each authenticated as
+      # themselves, so Google still checks access per person.
+      def list_calendar_events(user_email:, since:, until_time:)
+        service = service_for_user(user_email)
+        calendar_id = @calendar_id
+        events = []
+        page_token = nil
+        pages = 0
+        loop do
+          result = service.list_events(
+            calendar_id,
+            single_events: true, # expand recurring series into instances
+            order_by: 'startTime',
+            # getutc, not utc: Time#utc converts in place, and these two objects belong to the
+            # caller — the CLI hands the same instances to the presenter and to anomaly
+            # detection afterwards. Mutating them shifted the reported period a day back in
+            # any timezone ahead of UTC.
+            time_min: since.getutc.iso8601,
+            time_max: until_time.getutc.iso8601,
+            max_results: MAX_RESULTS,
+            page_token: page_token
+          )
+          events.concat(result.items || [])
+          page_token = result.next_page_token
+          pages += 1
+          break if page_token.nil? || pages >= MAX_PAGES
+        end
+        events
+      end
+
+      # --- the window ---
+
+      # The window never reaches past the current moment. A report whose --to is today asks for the
+      # whole day, and Google answers with the meetings still ahead of us; counting those reports
+      # time that has not been spent.
+      #
+      # No timezone handling here on purpose: Time comparison is by moment, not by wall-clock
+      # fields, so this is correct whatever zone the process, the calendar and the event use.
+      def cutoff_for(until_time)
+        [until_time, @now || Time.now].min
+      end
+
+      # --- filters ---
+
+      # Google returns events that overlap the window, so a meeting running right now comes back
+      # even with time_max at the cut-off. A meeting counts once it is over — reporting the elapsed
+      # part would change the same report every few minutes while the meeting runs.
+      #
+      # A missing end time falls through: #meeting_seconds returns 0 for it and the seconds check
+      # in #fetch drops it.
+      def unfinished?(event, cutoff)
+        finish = to_time(event.end&.date_time)
+        !finish.nil? && finish > cutoff
+      end
+
+      def all_day?(event)
+        event.start&.date && event.start.date_time.nil?
+      end
+
+      # The owning user's RSVP. Uses Google's `self` flag (no email matching needed).
+      def declined?(event)
+        me = self_attendee(event)
+        me && me.response_status == 'declined'
+      end
+
+      # Personal reminders/focus blocks: no attendees, or only the owner.
+      def solo?(event)
+        others = (event.attendees || []).reject(&:self)
+        others.empty?
+      end
+
+      def self_attendee(event)
+        (event.attendees || []).find(&:self)
+      end
+
+      # --- mapping ---
+
+      def meeting_seconds(event)
+        start = to_time(event.start&.date_time)
+        finish = to_time(event.end&.date_time)
+        return 0 unless start && finish
+
+        WorkingHoursCalculator.seconds_between(start, finish, @working_hours)
+      end
+
+      def build_meeting_item(event, seconds)
+        finish = to_time(event.end&.date_time)
+        build_work_item(
+          external_id: event.id,
+          title: event.summary || '(no title)',
+          completed_at: finish,
+          time_spent_seconds: seconds,
+          time_source: :calculated,
+          url: event.html_link,
+          metadata: {
+            start: to_time(event.start&.date_time)&.iso8601,
+            end: finish&.iso8601,
+            attendees_count: (event.attendees || []).size,
+            organizer: event.organizer&.email,
+            recurring: !event.recurring_event_id.nil?,
+            recurring_event_id: event.recurring_event_id
+          }
+        )
+      end
+
+      # Google SDK returns DateTime; normalize to Time (UTC) for WorkingHoursCalculator.
+      #
+      # Only date_time is read, not the separate time_zone field next to it. In an events.list
+      # response date_time carries the event's own offset, so the moment is unambiguous; time_zone
+      # is there to expand recurrence rules, which the server did for us (single_events: true).
+      def to_time(value)
+        return nil if value.nil?
+
+        value.respond_to?(:to_time) ? value.to_time.utc : value
+      end
+    end
+  end
+end