mailmate 0.1.0

data/lib/mailmate/parser.rb

@@ -0,0 +1,218 @@
+# frozen_string_literal: true
+
+require_relative "ast"
+require "time"
+
+# Recursive-descent parser for MailMate filter expressions.
+#
+# Grammar (informal, top-down):
+#   filter      = expr eof
+#   expr        = or_expr
+#   or_expr     = and_expr ('or' and_expr)*
+#   and_expr    = not_expr (('and' | <implicit>) not_expr)*    # implicit AND
+#   not_expr    = ['not'] term
+#   term        = '(' expr ')'
+#               | clause
+#   clause      = path 'exists'
+#               | path op value
+#   path        = (ident | shorthand) ('.' ident)*
+#   op          = OP_TOKEN  (carries flags from lexer)
+#   value       = string | number | rel_date | abs_date | varref
+#   rel_date    = number unit 'ago'        # unit: day(s), week(s), month(s), year(s)
+#   abs_date    = string                   # parsed as Time.parse if value contains a date pattern
+#   varref      = '$' VAR ('.' (ident|shorthand))*
+
+module Mailmate
+  # @api private
+  #
+  # Filter-language parser. Use `Mailmate.compile_filter` as the public
+  # surface.
+  class Parser
+    class Error < StandardError; end
+
+    UNITS = {
+      "day" => :day, "days" => :day,
+      "week" => :week, "weeks" => :week,
+      "month" => :month, "months" => :month,
+      "year" => :year, "years" => :year,
+    }.freeze
+
+    DATE_LIKE = /\A\s*\d{4}[-\/.]\d{1,2}([-\/.]\d{1,2}|.*\d{2}:\d{2})/.freeze
+
+    def self.parse(tokens)
+      new(tokens).parse_filter
+    end
+
+    def initialize(tokens)
+      @tokens = tokens
+      @i = 0
+    end
+
+    def parse_filter
+      expr = parse_expr
+      expect(:eof)
+      expr
+    end
+
+    private
+
+    # ---------- token utilities ----------
+
+    def peek(off = 0); @tokens[@i + off]; end
+    def consume; t = @tokens[@i]; @i += 1; t; end
+
+    def at?(kind, value = nil)
+      t = peek
+      return false unless t && t[0] == kind
+      value.nil? || t[1] == value
+    end
+
+    def expect(kind, value = nil)
+      t = peek
+      ok = t && t[0] == kind && (value.nil? || t[1] == value)
+      raise Error, "expected #{kind}#{value ? " #{value.inspect}" : ""} at #{@i}, got #{t.inspect}" unless ok
+      consume
+    end
+
+    # ---------- grammar ----------
+
+    def parse_expr
+      parse_or
+    end
+
+    def parse_or
+      left = parse_and
+      while at?(:keyword, "or")
+        consume
+        right = parse_and
+        if left.is_a?(AST::OrNode)
+          left.children << right
+        else
+          left = AST::OrNode.new([left, right])
+        end
+      end
+      left
+    end
+
+    def parse_and
+      left = parse_not
+      loop do
+        if at?(:keyword, "and")
+          consume
+          right = parse_not
+        elsif implicit_and_continues?
+          right = parse_not
+        else
+          break
+        end
+        if left.is_a?(AST::AndNode)
+          left.children << right
+        else
+          left = AST::AndNode.new([left, right])
+        end
+      end
+      left
+    end
+
+    # Implicit AND only continues if the next token can start a clause/term and
+    # we're at the top level. This matches MailMate's "implicit and" between
+    # consecutive clauses without an explicit connector.
+    def implicit_and_continues?
+      t = peek
+      return false unless t
+      kind = t[0]
+      return true if kind == :lparen || kind == :ident || kind == :shorthand
+      return true if kind == :keyword && t[1] == "not"
+      false
+    end
+
+    def parse_not
+      if at?(:keyword, "not")
+        consume
+        AST::NotNode.new(parse_term)
+      else
+        parse_term
+      end
+    end
+
+    def parse_term
+      if at?(:lparen)
+        consume
+        e = parse_expr
+        expect(:rparen)
+        return e
+      end
+      parse_clause
+    end
+
+    def parse_clause
+      path = parse_path
+
+      if at?(:keyword, "exists")
+        consume
+        return AST::ExistsNode.new(path)
+      end
+
+      raise Error, "expected operator after path at #{@i}, got #{peek.inspect}" unless at?(:op)
+      _, op, flags = consume
+
+      value = parse_value
+      AST::CompareNode.new(path, op, flags, value)
+    end
+
+    def parse_path
+      parts = []
+      t = peek
+      raise Error, "expected ident or shorthand at #{@i}, got #{t.inspect}" unless t && (t[0] == :ident || t[0] == :shorthand)
+      parts << consume[1]
+      while at?(:dot)
+        consume
+        nt = peek
+        raise Error, "expected ident or shorthand after '.' at #{@i}, got #{nt.inspect}" unless nt && (nt[0] == :ident || nt[0] == :shorthand)
+        parts << consume[1]
+      end
+      parts
+    end
+
+    def parse_value
+      t = peek
+      case t[0]
+      when :var
+        var = consume[1]
+        path = []
+        while at?(:dot)
+          consume
+          nt = peek
+          raise Error, "expected ident or shorthand after '.' in $var path" unless nt && (nt[0] == :ident || nt[0] == :shorthand)
+          path << consume[1]
+        end
+        AST::VarRefNode.new(var, path)
+      when :number
+        n = consume[1]
+        # Possibly a relative date: NUMBER UNIT 'ago'
+        if at?(:ident) && UNITS.key?(peek[1])
+          unit_word = consume[1]
+          if at?(:ident, "ago")
+            consume
+            return AST::RelativeDateNode.new(n, UNITS[unit_word])
+          else
+            raise Error, "expected 'ago' after number unit, got #{peek.inspect}"
+          end
+        end
+        AST::NumberNode.new(n)
+      when :string
+        s = consume[1]
+        if s =~ DATE_LIKE
+          begin
+            return AST::AbsoluteDateNode.new(Time.parse(s))
+          rescue ArgumentError
+            # fall through to literal string
+          end
+        end
+        AST::LiteralStringNode.new(s)
+      else
+        raise Error, "expected value at #{@i}, got #{t.inspect}"
+      end
+    end
+  end
+end

data/lib/mailmate/platform_error.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Mailmate
+  # @api public
+  #
+  # Raised when a subsystem that needs macOS-specific bits (AppleScript,
+  # MailMate's on-disk layout, the `open` and `osascript` commands) is invoked
+  # on a non-macOS host. Library-only code paths (parser, evaluator over
+  # synthetic fixtures) keep working anywhere; this error only surfaces at
+  # actual integration points.
+  class PlatformError < StandardError
+    def self.check_darwin!(component:)
+      return if RUBY_PLATFORM.include?("darwin")
+      raise new(
+        "#{component} requires macOS (RUBY_PLATFORM=#{RUBY_PLATFORM}). " \
+        "The mailmate gem's library code (filter parser, evaluator) works " \
+        "on any platform, but integration with MailMate itself is macOS-only.",
+      )
+    end
+  end
+end

data/lib/mailmate/source_resolver.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+# Resolves a mailbox UUID (or smart-mailbox `set`) to a list of `Messages/`
+# directories on disk. Walks the `set` chain to handle nested smart mailboxes:
+# the chain ends at a special UUID (ALL_MESSAGES, INBOX, SENT, etc.) which
+# maps to actual on-disk paths.
+#
+# Also returns an accumulated list of filters from any smart mailboxes
+# encountered along the way — these AND with the leaf mailbox's filter.
+
+module Mailmate
+  # @api public
+  class SourceResolver
+    # Standard-mailbox name patterns. Each special UUID maps to one or more
+    # `*.mailbox` directories per account. Gmail nests system folders under
+    # `[Gmail]/...`; iCloud is flat with different names.
+    SPECIAL_DIRS = {
+      "INBOX"   => ["INBOX.mailbox"],
+      "DRAFTS"  => ["[Gmail].mailbox/Drafts.mailbox", "Drafts.mailbox"],
+      "SENT"    => ["[Gmail].mailbox/Sent Mail.mailbox", "Sent Messages.mailbox"],
+      "ARCHIVE" => ["[Gmail].mailbox/Archive.mailbox", "Archive.mailbox"],
+      "JUNK"    => ["[Gmail].mailbox/Spam.mailbox", "Junk.mailbox"],
+      "TRASH"   => ["[Gmail].mailbox/Trash.mailbox", "Deleted Messages.mailbox"],
+    }.freeze
+
+    # ALL_MESSAGES: union of INBOX/SENT/DRAFTS/ARCHIVE plus any custom labels.
+    # Excludes Trash/Junk (per MailMate help: "All Messages" is everything except
+    # deleted/junk).
+    ALL_MESSAGES_EXCLUDES = %r{/(?:Trash|Junk|Spam|Deleted Messages)\.mailbox/Messages/?\z}.freeze
+
+    def initialize(graph)
+      @graph = graph
+    end
+
+    # Resolve a mailbox spec to {dirs:, filters:}.
+    # `spec` may be a UUID, a name, or a special UUID literal.
+    # Returns:
+    #   :dirs    => Array<String> of absolute paths to `Messages/` directories
+    #   :filters => Array<String> of filter expressions to AND together
+    def resolve(spec)
+      filters = []
+      uuid = spec
+      visited = []
+      loop do
+        raise ArgumentError, "Cycle in mailbox resolution: #{visited.inspect}" if visited.include?(uuid)
+        visited << uuid
+
+        m = @graph.by_uuid[uuid] || @graph.by_uuid[@graph.by_name[uuid]]
+
+        # Collect this node's filter (if it has one). The special UUIDs
+        # FLAGGED / SENT / etc. can themselves be smart mailboxes (e.g.
+        # Brian's "Flagged" with filter `#flags.flag = '\Flagged'`); the
+        # filter has to be picked up before we resolve the special to dirs.
+        filters << m[:filter] if m && m[:filter]
+
+        next_uuid = m && m[:set]
+
+        # If `set` points elsewhere, walk to it (handles nested smart mailboxes).
+        if next_uuid && next_uuid != uuid
+          uuid = next_uuid
+          next
+        end
+
+        # Terminal — resolve to on-disk dirs.
+        if MailboxGraph::SPECIAL_UUIDS.include?(uuid)
+          return { dirs: special_dirs(uuid), filters: filters }
+        end
+
+        raise ArgumentError, "Mailbox #{spec.inspect} can't be resolved to disk paths " \
+                             "(uuid=#{uuid}, name=#{m && m[:name].inspect})"
+      end
+    end
+
+    def special_dirs(uuid)
+      case uuid
+      when "ALL_MESSAGES"
+        all_message_dirs
+      when "INBOX", "DRAFTS", "SENT", "ARCHIVE", "JUNK", "TRASH"
+        per_account_dirs(SPECIAL_DIRS[uuid])
+      else
+        # Unknown special — return empty list and let the caller fail loudly.
+        []
+      end
+    end
+
+    def all_message_dirs
+      Dir.glob("#{Mailmate.config.imap_root}/*/**/Messages")
+         .select { |p| File.directory?(p) }
+         .reject { |p| p =~ ALL_MESSAGES_EXCLUDES }
+    end
+
+    def per_account_dirs(suffixes)
+      result = []
+      Dir.glob("#{Mailmate.config.imap_root}/*").each do |account|
+        next unless File.directory?(account)
+        suffixes.each do |suffix|
+          d = "#{account}/#{suffix}/Messages"
+          result << d if File.directory?(d)
+        end
+      end
+      result
+    end
+  end
+end

data/lib/mailmate/var_resolver.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+require "set"
+require_relative "attributes"
+require_relative "source_resolver"
+require_relative "message"
+
+# @api private
+#
+# VarResolver — resolves `$VAR.attr` references in smart-mailbox filters.
+#
+# Semantics: `LHS = $VAR.attr` means "LHS equals SOME value of `attr` taken
+# over all messages in mailbox VAR". The set is built once per (var, attr)
+# pair and cached for the lifetime of the resolver.
+#
+# Variable lookup: `$VAR` → mailbox UUID, with fallback to name lookup.
+# `$SENT` → SENT (special UUID); `$PERSONAL_INBOX` → PERSONAL_INBOX (UUID
+# of a smart mailbox in MailMate's defaults).
+#
+# Cycle detection: if `$A` resolves through the graph to a filter that
+# references `$A`, raise. (None of Brian's current filters cycle.)
+
+module Mailmate
+  class VarResolver
+    class CycleError < StandardError; end
+    class UnsupportedVar < StandardError; end
+
+    def initialize(graph)
+      @graph = graph
+      @source_resolver = SourceResolver.new(graph)
+      @cache    = {}
+      @visiting = []
+    end
+
+    # Returns an Array<String|AddressValue|...> of values seen for `attr_path`
+    # in the mailbox named `var_name`. Empty array if no matches.
+    def resolve(var_name, attr_path)
+      key = [var_name, attr_path]
+      return @cache[key] if @cache.key?(key)
+
+      raise CycleError, "var-resolution cycle: #{(@visiting + [var_name]).join(" → ")}" \
+        if @visiting.include?(var_name)
+      @visiting << var_name
+
+      begin
+        # 1. Resolve the variable's mailbox to dirs + smart-filter chain.
+        uuid = MailboxGraph::SPECIAL_UUIDS.include?(var_name) ? var_name : @graph.by_name[var_name]
+        raise UnsupportedVar, "Unknown mailbox referenced: $#{var_name}" unless uuid
+
+        res = @source_resolver.resolve(uuid)
+        dirs = res[:dirs]
+        filter_str = compose_filter(res[:filters])
+
+        # 2. Build a child evaluator if there's an inner filter, with the
+        # *same* var resolver so nested $vars resolve.
+        inner_eval = filter_str ? Evaluator.new(Mailmate.compile_filter(filter_str), var_resolver: self) : nil
+
+        # 3. Walk dirs, collect attr_path values from matching messages.
+        values = []
+        dirs.each do |dir|
+          Dir.each_child(dir) do |fname|
+            next unless fname.end_with?(".eml")
+            path = "#{dir}/#{fname}"
+            eml_id = fname.sub(".eml", "").to_i
+            begin
+              # Header-only parse: most $var attrs are headers, and a full
+              # Mail.read on each Sent message would be slow.
+              mail = Mail.new(read_header_block(path))
+            rescue StandardError
+              next
+            end
+            msg = Message.new(mail, eml_id, path)
+            next if inner_eval && !inner_eval.matches?(msg)
+
+            v = Attributes.resolve(msg, attr_path)
+            Array(v).each { |x| values << x.to_s if x }
+          end
+        end
+
+        @cache[key] = values
+      ensure
+        @visiting.pop
+      end
+    end
+
+    private
+
+    def compose_filter(filters)
+      return nil if filters.empty?
+      filters.size == 1 ? filters.first : "(#{filters.map { |f| "(#{f})" }.join(" and ")})"
+    end
+
+    # Header-only read: stop at the first blank line (capped at 64KB).
+    # Same primitive used by the raw-bytes pre-filter in mailmate-search.
+    def read_header_block(path)
+      bytes = +""
+      File.open(path, "rb") do |f|
+        while (chunk = f.read(4096))
+          bytes << chunk
+          idx = bytes.index("\r\n\r\n") || bytes.index("\n\n")
+          return bytes[0..idx] if idx
+          break if bytes.bytesize > 65_536
+        end
+      end
+      bytes
+    end
+  end
+end

data/lib/mailmate/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Mailmate
+  VERSION = "0.1.0"
+end

data/lib/mailmate.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+# @api public
+#
+# mailmate — Ruby toolkit for MailMate on macOS.
+#
+# Public surface:
+#   Mailmate.config                            → singleton Config (data only; use the accessor)
+#   Mailmate.compile_filter(string)            → filter AST root
+#   Mailmate::Identity.mine?(addr)             → is this address one of mine?
+#   Mailmate::IndexReader.for(name)            → decoded Database.noindex/Headers/<name>
+#   Mailmate::EmlLookup.path_for(eml_id)       → eml-id → absolute path
+#   Mailmate::HeaderReader.header(path, name)  → read one header from an .eml
+#   Mailmate::MidUrl.for(message_id)           → build a mid:%3C...%3E URL
+#   Mailmate::DuplicateScanner.duplicates      → Hash{Message-ID => Array<eml_id>}
+#   Mailmate::AppleScriptDriver.new(...)       → drive MailMate via AppleScript
+#   Mailmate::Evaluator.new(ast).matches?(msg) → smart-mailbox filter evaluation
+#   Mailmate::MailboxGraph.load                → graph of all configured mailboxes
+#   Mailmate::SourceResolver.new(graph)        → resolves mailbox → on-disk dirs
+#   Mailmate::Message                          → thin wrapper over Mail + eml_id
+#   Mailmate::PlatformError                    → raised when macOS bits are needed elsewhere
+#
+# Internal (subject to change without notice; do not depend on these):
+#   Mailmate::Config (use Mailmate.config), Lexer, Parser, AST, Operators,
+#   Attributes, FilterClassifier, VarResolver, Mailmate::CLI::*.
+
+module Mailmate
+end
+
+require_relative "mailmate/version"
+require_relative "mailmate/platform_error"
+require_relative "mailmate/config"
+require_relative "mailmate/identity"
+require_relative "mailmate/header_reader"
+require_relative "mailmate/mid_url"
+require_relative "mailmate/eml_lookup"
+require_relative "mailmate/duplicate_scanner"
+require_relative "mailmate/applescript_driver"
+require_relative "mailmate/ast"
+require_relative "mailmate/lexer"
+require_relative "mailmate/parser"
+require_relative "mailmate/message"
+require_relative "mailmate/index_reader"
+require_relative "mailmate/attributes"
+require_relative "mailmate/operators"
+require_relative "mailmate/evaluator"
+require_relative "mailmate/mailbox_graph"
+require_relative "mailmate/source_resolver"
+require_relative "mailmate/var_resolver"
+require_relative "mailmate/filter_classifier"
+
+module Mailmate
+  def self.compile_filter(str)
+    Parser.parse(Lexer.lex(str))
+  end
+
+  # Convert a Time to the configured display zone.
+  # If `display_timezone` is set in config, use it as the offset (e.g.
+  # "-07:00"). Otherwise fall back to the system local zone (which honors
+  # macOS's DST rules, so Mountain users get MDT in summer and MST in winter).
+  def self.localize(time)
+    return nil unless time
+    t = time.respond_to?(:to_time) ? time.to_time : time
+    zone = config.display_timezone
+    if zone && !zone.empty?
+      t.getlocal(zone)
+    else
+      t.getlocal
+    end
+  rescue StandardError
+    time
+  end
+end

metadata

@@ -0,0 +1,146 @@
+--- !ruby/object:Gem::Specification
+name: mailmate
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Brian Murphy-Dye
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: mail
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.8'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.8'
+- !ruby/object:Gem::Dependency
+  name: csv
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+description: |
+  mailmate is a Ruby library and CLI for working with MailMate's on-disk
+  storage and AppleScript surface. It includes a smart-mailbox filter
+  engine (lexer/parser/evaluator over MailMate's filter language), readers
+  for the binary header indexes, and CLI tools for searching, reading,
+  modifying, and sending mail via MailMate.
+
+  Requires macOS with MailMate installed. Some library pieces (parser,
+  evaluator, fixture-driven tests) work on any platform; the integration
+  pieces (AppleScript driver, filesystem readers) raise Mailmate::PlatformError
+  on non-macOS hosts.
+email:
+- brian@murphydye.com
+executables:
+- mm-modify
+- mm-send
+- mmdiscover
+- mmmessage
+- mmsearch
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- config.yml.example
+- exe/mm-modify
+- exe/mm-send
+- exe/mmdiscover
+- exe/mmmessage
+- exe/mmsearch
+- lib/mailmate.rb
+- lib/mailmate/applescript_driver.rb
+- lib/mailmate/ast.rb
+- lib/mailmate/attributes.rb
+- lib/mailmate/cli/discover.rb
+- lib/mailmate/cli/message.rb
+- lib/mailmate/cli/modify.rb
+- lib/mailmate/cli/search.rb
+- lib/mailmate/cli/send.rb
+- lib/mailmate/config.rb
+- lib/mailmate/duplicate_scanner.rb
+- lib/mailmate/eml_lookup.rb
+- lib/mailmate/evaluator.rb
+- lib/mailmate/filter_classifier.rb
+- lib/mailmate/header_reader.rb
+- lib/mailmate/identity.rb
+- lib/mailmate/index_reader.rb
+- lib/mailmate/lexer.rb
+- lib/mailmate/mailbox_graph.rb
+- lib/mailmate/message.rb
+- lib/mailmate/mid_url.rb
+- lib/mailmate/operators.rb
+- lib/mailmate/parser.rb
+- lib/mailmate/platform_error.rb
+- lib/mailmate/source_resolver.rb
+- lib/mailmate/var_resolver.rb
+- lib/mailmate/version.rb
+licenses:
+- MIT
+metadata: {}
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.10
+specification_version: 4
+summary: Ruby toolkit for MailMate on macOS — search, read, modify, send, and smart-mailbox
+  evaluation
+test_files: []