imapcli 2.0.0 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 251ac4bd70a607d8891eb4035bf69ba10017995436d2af15138e8647ac042530
-  data.tar.gz: 57072fa35d2eb0e53a85e27464638844fedb83807c8e4f98ad59c502cbd07be3
+  metadata.gz: 0736f0dbe2cb473770fb5f92f0f37546b9f26a6e892bbca3c69b072c1f06db9f
+  data.tar.gz: '0609a383ac74799eb2aade3d52fa0c5c811fc5cb4b253f1607e0b6f2dbe7cf01'
 SHA512:
-  metadata.gz: 5cfc0a536bb6ae0b71e4262cf9ae03d7213c093c10b6c47597a02ee2bac101357423ec0df5a66038d2e6673fcf03973cef1d564015dc56dd3c665bcb31521da4
-  data.tar.gz: b2f986bd44dfe6e3374b272bf50fd238ebff681665a32ddad07c2930e8842f5132c27df861dd31f13486b167179649b94ea2e788679721f952662a6620170102
+  metadata.gz: 69d818a1780fda1549bbd83581c2d0abbc4ecda7274cb411bedd450a8365e322153263c1f5b490b03a183e7c8cb02e5d382c82c8628ee43e1c1c1294f6e76afa
+  data.tar.gz: e664577a0949609bebd90a7bc08b94e4559001fcb7b26429958fe38801acd835089b030cad3d3b1fa09a95ccc51b400f6cb8f66befc4903ebe1cb9b4bb56746d

data/CHANGELOG.md

@@ -5,6 +5,19 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Version 2.1.0 (2025-03-16)][v2.1.0]
+
+### Added
+
+- New command-line flag `-l`/`--limit` to limit the statistics output to
+  a given number of mailboxes (folders).
+
+## [Version 2.0.1 (2025-03-11)][v2.0.1]
+
+### Fixed
+
+- Do not crash with empty IMAP mailboxes.
+
 ## [Version 2.0.0 (2025-03-10)][v2.0.0]
 
 ### Added
@@ -66,6 +79,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Fix: Docker image.
 - Fix: Options error message.
 
+[v2.1.0]: https://github.com/bovender/imapcli/releases/tag/v2.1.0
+[v2.0.1]: https://github.com/bovender/imapcli/releases/tag/v2.0.1
 [v2.0.0]: https://github.com/bovender/imapcli/releases/tag/v2.0.0
 [v1.0.7]: https://github.com/bovender/imapcli/releases/tag/v1.0.7
 [v1.0.5]: https://github.com/bovender/imapcli/releases/tag/v1.0.5

data/Dockerfile

@@ -1,4 +1,4 @@
-FROM ruby:alpine
+FROM ruby:3.4-alpine
 LABEL maintainer="bovender@bovender.de"
 LABEL description="Command-line tool to query IMAP servers, collect stats etc."
 
@@ -7,11 +7,12 @@ ADD . /imapcli
 RUN apk add --no-cache git build-base && \
   gem update --system && \
   cd imapcli && \
-  # bundle config set --local without development test && \
+  bundle config set --local without development test && \
+  bundle config set --local deployment true && \
   bundle install && \
   apk del build-base && \
   rm -rf /var/cache/apk/*
 
 WORKDIR /imapcli
-ENTRYPOINT ["exe/imapcli"]
+ENTRYPOINT ["bundle", "exec", "exe/imapcli"]
 

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    imapcli (1.0.7)
+    imapcli (2.0.1)
       activesupport (~> 8.0)
       csv
       descriptive_statistics (~> 2.5)
@@ -16,7 +16,7 @@ PATH
 GEM
   remote: https://rubygems.org/
   specs:
-    activesupport (8.0.1)
+    activesupport (8.0.2)
       base64
       benchmark (>= 0.3)
       bigdecimal
@@ -83,7 +83,7 @@ GEM
       pp (>= 0.6.0)
       rdoc (>= 4.0.0)
       reline (>= 0.4.2)
-    json (2.10.1)
+    json (2.10.2)
     language_server-protocol (3.17.0.4)
     lint_roller (1.1.0)
     listen (3.9.0)
@@ -92,7 +92,7 @@ GEM
     logger (1.6.6)
     lumberjack (1.2.10)
     method_source (1.1.0)
-    minitest (5.25.4)
+    minitest (5.25.5)
     nenv (0.3.0)
     net-imap (0.5.6)
       date
@@ -142,7 +142,7 @@ GEM
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.13.0)
     rspec-support (3.13.2)
-    rubocop (1.73.2)
+    rubocop (1.74.0)
       json (~> 2.3)
       language_server-protocol (~> 3.17.0.2)
       lint_roller (~> 1.1.0)
@@ -153,7 +153,7 @@ GEM
       rubocop-ast (>= 1.38.0, < 2.0)
       ruby-progressbar (~> 1.7)
       unicode-display_width (>= 2.4.0, < 4.0)
-    rubocop-ast (1.38.1)
+    rubocop-ast (1.39.0)
       parser (>= 3.3.1.0)
     rubocop-performance (1.24.0)
       lint_roller (~> 1.1)
@@ -237,4 +237,4 @@ DEPENDENCIES
   simplecov
 
 BUNDLED WITH
-   2.5.22
+   2.6.5

data/README.md

@@ -15,7 +15,6 @@ IMAP mailbox sizes.
 - [Terminology](#terminology)
 - [Usage](#usage)
 - [Alternative resources](#alternative-resources)
-- [State of the project](#state-of-the-project)
 - [Credits](#credits)
 - [License](#license)
 
@@ -264,7 +263,18 @@ keyword, as shown below.
 
 Example:
 
-    bundle exec -it bin/imapcli -s yourserver.example.com -u myusername -P stats -r -o max_size Archive
+    docker run -it bin/imapcli -s yourserver.example.com -u myusername -P stats -r -o max_size Archive
+
+#### Limiting the number of mailboxes
+
+You can limit the number of mailboxes (folders) in the output table with the
+`-l`/`--limit` flag. This flag takes an argument that indicates the maximum
+number of mailboxes. THe default value for this argument is 10.
+
+Use case: Say you have a very large IMAP account, and you would like to know the
+5 folders that contain the largest messages. The command should be:
+
+    imapcli -s yourserver.example.com -u myusername -P stats -o max_size --limit 5 
 
 #### Obtaining comma-separated values (CSV)
 
@@ -292,20 +302,13 @@ following:
 
   Pull down e-mails from an IMAP server to your local disk
 
-## State of the project
-
-I have not been able to work on this project for quite some time. It still
-serves me well when I occasionally need it. Pull requests are of course welcome.
-
-This project is [semantically versioned](https://semver.org).
-
 ### To do
 
-[x] More human-friendly number formatting (e.g., MiB/GiB as appropriate)
-[ ] Output to file
-[ ] Deal with server-specific mailbox separator characters (e.g. '.' vs. '/')
-[ ] Man page
-[ ] More commands?
+- [x] More human-friendly number formatting (e.g., MiB/GiB as appropriate)
+- [ ] Output to file
+- [ ] Deal with server-specific mailbox separator characters (e.g. '.' vs. '/')
+- [ ] Man page
+- [ ] More commands?
 
 ## Credits
 

data/imapcli.gemspec

@@ -22,10 +22,10 @@ Gem::Specification.new do |s|
   s.bindir = 'exe'
   s.executables = ['imapcli']
 
+  s.add_dependency('activesupport', '~> 8.0')
   s.add_dependency('csv')
   s.add_dependency('descriptive_statistics', '~> 2.5')
   s.add_dependency('dotenv', '~> 3.1')
-  s.add_dependency('activesupport', '~> 8.0')
   s.add_dependency('gli', '~> 2.22')
   s.add_dependency('net-imap')
   s.add_dependency('tty-progressbar', '~> 0.18')

data/lib/imapcli/cli.rb

@@ -74,6 +74,10 @@ module Imapcli
         default: 'total_size'
       c.switch %i[reverse], desc: 'Reverse sort order (largest first)', negatable: false
       c.switch [:csv], desc: 'Output comma-separated values (CSV)'
+      c.flag %i[l limit],
+        desc: 'Limit the results to n folders (IMAP mailboxes)',
+        arg_name: 'max_lines',
+        default: 10
 
       c.action do |_global_options, options, args| # rubocop:disable Metrics/BlockLength
         raise unless @validator.stats_options_valid?(options, args)

data/lib/imapcli/command.rb

@@ -68,7 +68,12 @@ module Imapcli
             yield current_count if block_given?
           end
         end
-        output = sorted_list(list, options).map do |mailbox|
+
+        output = if options[:limit]
+          sorted_list(list, options).last(options[:limit].to_i)
+        else
+          sorted_list(list, options)
+        end.map do |mailbox|
           stats_to_table(mailbox.full_name, mailbox.stats)
         end
         output << stats_to_table('Total', total_stats) if list.length > 1
@@ -138,28 +143,30 @@ module Imapcli
       end
     end
 
-    def sorted_list(list, options = {}) # rubocop:disable Metrics/MethodLength,Metrics/AbcSize,Metrics/CyclomaticComplexity,Metrics/PerceivedComplexity
-      sorted = case options[:sort]&.to_sym
-               when :count
-                 list.sort_by { |mailbox| mailbox.stats.count }
-               when :total_size
-                 list.sort_by { |mailbox| mailbox.stats.total_size }
-               when :median_size
-                 list.sort_by { |mailbox| mailbox.stats.median_size }
-               when :min_size
-                 list.sort_by { |mailbox| mailbox.stats.min_size }
-               when :q1_size
-                 list.sort_by { |mailbox| mailbox.stats.q1 }
-               when :q3_size
-                 list.sort_by { |mailbox| mailbox.stats.q3 }
-               when :max_size
-                 list.sort_by { |mailbox| mailbox.stats.max_size }
-               when nil
-                 list
-               else
-                 raise "invalid sort option: #{options[:sort]}"
-               end
-      options[:reverse] ? sorted.reverse : sorted
+    def sorted_list(list, options)
+      return list if options.nil? || options[:sort].nil?
+      sort_property = options[:sort]&.to_sym
+      if %i[count total_size min_size q1 median_size q3 max_size].include? sort_property
+        sorted = sort_mailboxes(list, sort_property, options[:reverse])
+      else
+        raise "invalid sort option: #{options[:sort]}"
+      end
+    end
+
+    private
+    
+    # Sorts a list of mailboxes according to a given property
+    # such as total count of e-mails, total size of all e-mails etc.
+    # Some mailboxes may not have this property, e.g., an empty
+    # mailbox will have `nil` values for median_size etc.
+    # We always sort mailboxes with `nil` values to the bottom.
+    def sort_mailboxes(mailboxes, property, reverse)
+      # Devide ary into two parts, one part where the property has a value
+      # and the other where the property is nil.
+      partitions = mailboxes.partition { |mailbox| mailbox.stats.send(property) }
+      sorted = partitions[0].sort_by { |mailbox| mailbox.stats.send(property) }
+      sorted = sorted.reverse if reverse
+      sorted + partitions[1]
     end
 
   end

data/lib/imapcli/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Imapcli
-  VERSION = '2.0.0'
+  VERSION = '2.1.0'
 end

data/spec/lib/imapcli/command_spec.rb

@@ -22,9 +22,11 @@ RSpec.describe Imapcli::Command do
                              Net::IMAP::MailboxList.new(nil, '/', 'Inbox'),
                              Net::IMAP::MailboxList.new(nil, '/', 'Inbox/Foo'),
                              Net::IMAP::MailboxList.new(nil, '/', 'Inbox/Foo/Sub'),
+                             Net::IMAP::MailboxList.new(nil, '/', 'Inbox/Many/Messages'),
                              Net::IMAP::MailboxList.new(nil, '/', 'Inbox/Bar'),
-                             Net::IMAP::MailboxList.new(nil, '/', 'Inbox/Bar/Sub'),
-                             Net::IMAP::MailboxList.new(nil, '/', 'Inbox/Bar/Sub/Subsub'),
+                             Net::IMAP::MailboxList.new(nil, '/', 'Inbox/Largest/Messages'),
+                             Net::IMAP::MailboxList.new(nil, '/', 'Inbox/Smallest/Messages'),
+                             Net::IMAP::MailboxList.new(nil, '/', 'Inbox/Empty'),
                            ])
     end
 
@@ -57,17 +59,19 @@ RSpec.describe Imapcli::Command do
         allow(client).to receive(:message_sizes) do |mailbox|
           case mailbox
           when 'Inbox'
-            (1..4).map { |i| 1024 * i }
+            [200, 300, 400, 500]
           when 'Inbox/Foo'
-            (3..10).map { |i| 1024 * i }
-          when 'Inbox/Foo/Sub'
-            Array.new(10, 1024)
+            [355, 360, 380, 200]
+          when 'Inbox/Many/Messages'
+            Array.new(10, 100)
           when 'Inbox/Bar'
-            (1..2).map { |i| 1024 * i }
-          when 'Inbox/Bar/Sub'
-            [1, 1024 * 20]
-          when 'Inbox/Bar/Sub/Subsub' # rubocop:disable Lint/DuplicateBranch
-            (1..4).map { |i| 1024 * i }
+            [2_000, 3_000, 4_000]
+          when 'Inbox/Largest/Messages'
+            [2_500_000, 100_000, 200_000]
+          when 'Inbox/Smallest/Messages'
+            [10, 20, 30]
+          when 'Inbox/Empty'
+            []
           else
             [1024, 2048, 4096, 8192]
           end
@@ -77,8 +81,8 @@ RSpec.describe Imapcli::Command do
       it 'for all folders' do
         output = command.stats
         expect(output).to be_a Array
-        expect(output.length).to eq 7
-        expect(output[0][0]).to eq 'Inbox'
+        expect(output.length).to eq 9
+        expect(output[0][0]).to eq 'Inbox' # sorted before 'Inbox'
         expect(output[0][1]).to eq 4
       end
 
@@ -87,7 +91,15 @@ RSpec.describe Imapcli::Command do
         expect(output).to be_a Array
         expect(output.length).to eq 1
         expect(output[0][0]).to eq 'Inbox/Foo'
-        expect(output[0][1]).to eq 8 # depends on message_sizes stub (see above)
+        expect(output[0][1]).to eq 4 # depends on message_sizes stub (see above)
+      end
+
+      it 'for an empty folder' do
+        output = command.stats('Inbox/Empty')
+        expect(output).to be_a Array
+        expect(output.length).to eq 1
+        expect(output[0][0]).to eq 'Inbox/Empty'
+        expect(output[0][1]).to eq 0
       end
 
       it 'for a given folder and subfolders' do
@@ -100,26 +112,31 @@ RSpec.describe Imapcli::Command do
       it 'sorts by number of messages' do
         output = command.stats('Inbox', depth: -1, sort: :count, reverse: true)
         expect(output).to be_a Array
-        expect(output[0][0]).to eq 'Inbox/Foo/Sub'
+        expect(output[0][0]).to eq 'Inbox/Many/Messages'
       end
 
       it 'sorts by total message size' do
-        output = command.stats('Inbox', depth: -1, sort: :total_size, reverse: true)
+        output = command.stats('Inbox', depth: -1, sort: :total_size, reverse: false)
         expect(output).to be_a Array
-        expect(output[0][0]).to eq 'Inbox/Foo'
+        expect(output[-2][0]).to eq 'Inbox/Largest/Messages'
       end
 
-      it 'sorts by largest message' do
+      it 'reverse-sorts largest message first' do
         output = command.stats('Inbox', depth: -1, sort: :max_size, reverse: true)
         expect(output).to be_a Array
-        expect(output[0][0]).to eq 'Inbox/Bar/Sub'
+        expect(output[0][0]).to eq 'Inbox/Largest/Messages'
+        expect(output[-2][0]).to eq 'Inbox/Empty'
       end
 
-      it 'sorts by smallest message' do
-        output = command.stats('Inbox', depth: -1, sort: :min_size, reverse: true)
+      it 'sorts smallest message first' do
+        output = command.stats('Inbox', depth: -1, sort: :min_size, reverse: false)
         expect(output).to be_a Array
-        # binding.pry
-        expect(output[0][0]).to eq 'Inbox/Foo'
+        expect(output[0][0]).to eq 'Inbox/Smallest/Messages'
+      end
+
+      it 'returns only the first n mailboxes' do
+        output = command.stats('Inbox', depth: -1, limit: 2)
+        expect(output.length).to eq 3 # including summary line
       end
     end
 

metadata

@@ -1,15 +1,29 @@
 --- !ruby/object:Gem::Specification
 name: imapcli
 version: !ruby/object:Gem::Version
-  version: 2.0.0
+  version: 2.1.0
 platform: ruby
 authors:
 - Daniel Kraus (bovender)
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-03-10 00:00:00.000000000 Z
+date: 2025-03-16 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '8.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '8.0'
 - !ruby/object:Gem::Dependency
   name: csv
   requirement: !ruby/object:Gem::Requirement
@@ -52,20 +66,6 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.1'
-- !ruby/object:Gem::Dependency
-  name: activesupport
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '8.0'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '8.0'
 - !ruby/object:Gem::Dependency
   name: gli
   requirement: !ruby/object:Gem::Requirement